Installation Guide

Below are instructions for installing and building the developer version of mantaflow from the souce code repository. For Linux, this process is rather straightforward, while a bit more work is involved for Windows and Mac. The packaged Windows release also contains pre-built binaries which you can use to test mantaflow before setting up the sources.

Jump to:

Linux

Windows

Mac OSX

 

Linux

This installation guide focusses on Ubuntu 14.04 as a distribution. The process will however look very similar with other distributions, the main differences being the package manager and library package names.

First, install a few pre-requisites:

If you want to enable CUDA support, additionally get the latest toolkit from nVidia, and install the appropriate developer driver (be careful though, these driver tend to wreck X11 - get some installation instructions from the web if this is the first time you install CUDA on Linux)

Then, change to the directory to install the source code in, and obtain the current sources from the repository (or alternatively download and extract a source code package)

To build the project using CMake, set up a build directory and choose the build options (explanation)

That's it! You can now test mantaflow using an example scene

Common Linux problems:

- In conjunction with tensorflow, it can easily happen these days that you have multiple version of python installed. If cmake for mantaflow finds a different one than you're using for tensorflow, you will get errors such as ''ImportError: no module named XXX''. To fix this problem, manually select a python version in cmake with -DPYTHON_VERSION=X.Y

 

Windows

There are several ways to build mantaflow on Windows. This guide focusses on using CMake and Visual Studio to build, since that is what most people seem to be interested in. You can however also use the free mingw or cygwin toolchains to build using gcc on the command line.

First, download and install the required tools and libraries. If you use the installer packages on the download pages linked below, cmake will automatically find the directories for most cases. TBB doesn't come with an installer, but is automatically detected if extracted into the standard directory C:\Program Files\Intel\TBB. In case cmake fails to find a package, you will need to add the install path by setting CMAKE_PREFIX_PATH in the cmake GUI.

Tool	Version	Comments
CMake	2.8+	required.
Python	2.7+ or 3.2+	required. Make sure you get the appropriate 32/64bit version you want to build for.
Visual Studio	2010+	recommended (older versions not supported anymore).
QT	5.x	recommended, used in the GUI version. For a lightweight install, choose the 5.x qt-libraries (if they exist for your version of MSVC). Click "Show-all-downloads", then select "Qt 5.x, VS 201x Opengl".
Intel TBB	4.0+	optional, can be used for multicore computations instead of OpenMP.
CUDA	4.0+	experimental, for advanced use

Next, obtain the source code from either repository or the source code package.

The Git URL is https://github.com/tum-pbs/mantaflow.git .

Once you obtained the code, start cmake. Select the base path, i.e. the directory that has CMakeLists.txt as the source directory, and create an empty directory named build in the base path to use as the binary directory.

Then, click Configure and chose your version of Visual Studio as a generator. If everything is installed correctly, the list of build options will appear. If you get an error, you might need to specify the install directory of the respective library using an additional string entry.

Finally, select your build options (for your first experiments, enable OPENMP and GUI and leave the rest off) and click on Generate and a Visual Studio solution file is generated in the build directory. Build and run, and select scenes/simpleplume.py for a first test scene. You are ready to go!

Common Windows problems:

- You can ignore warnings that doxygen is not found, or about "inconsistent linkage for round()". These won't cause problems.

- CMake for visual studio shows "Visual Studio 11", which means "Visual Studio 2012"! Be careful choosing the right version...

- Often DLLs are not found, e.g. for qt. The easiest way to get around this is to copy the necessary DLLs into the build/Release and build/Debug directories (the minimal set is Qt5Core.dll, Qt5Gui.dll, Qt5Opengl.dll, Qt5Widgets.dll and the three icuXXX.dll-s).

- When using Qt Creator, enable the FS compiler option (search for "qt creator" in CMakeLists.txt).

- OpenVDB is not easy to install for windows. You can try using our pre-compiled version, which you can download here. Unzip into the main source code directory.

 

Mac OS X

To build mantaflow on OS X, you will need some tools and libraries. If you haven't done so already, first install XCode (you can get it for free in the Mac App Store). Then, get the following tools:

Tool	Version	Comments
CMake	2.8+	required.
Python	2.7+ or 3.2+	required.
QT5	5.x	recommended, used in the GUI version. Get the "QT5 libraries" package.
Intel TBB	4.0+	optional, can be use for multicore computations instead of OpenMP (e.g. if you want to use clang).
CUDA	4.0+	experimental, for advanced use

Next, obtain the source code from either repository or the source code package.

The Git URL is https://github.com/tum-pbs/mantaflow.git .

Once you obtained the code, start the cmake GUI. Select the base path, i.e. the directory that has CMakeLists.txt as the source directory, and create an empty directory named build in the base path to use as the binary directory.

Then, click Configure. You now have two choices for the generator:

1. XCode: This will generate a XCode project file in your build directory, which you can directly open and build, debug or run mantaflow. The automatically created folder structure is a bit confusing, though, and the project will be re-created when running cmake with different options.

2. gcc make: This will create UNIX makefiles. You can either just build them using the terminal as in the linux instructions, or create an XCode project (external build system, use /usr/bin/make) and then add the source files manually. This will get you a cleaner project, which isn't overwritten when cmake is re-run, but does take some manual tweaking in order to get full debug support etc. Note - by default the Mac compiler does not support openmp anymore, thus configure and build with: mkdir manta/build cd manta/build cmake .. -DGUI=OFF make -j4 Once this works correctly, try it with DGUI=ON. If you have a custom installation of qt5, the easiest way is to modify the CMakeLists.txt file, and change the line SET(CMAKE_PREFIX_PATH "...") to the correct path (e.g. "~/Qt/5.5/clang_64").

If everything is installed correctly, the list of build options will appear. If you get an error, you might need to specify the install directory of the respective library using an additional string entry.

Finally, select your build options (for your first experiments, enable OPENMP and GUI and leave the rest off) and click on Generate. Build and run, and select scenes/simpleplume.py for a first test scene. If running the project does not work out of the box, you might need to select manta as an executable in Product/Edit Scheme, and set the working directory to your build directory. Now you're ready to go!

 

 

CMake Build Options

The options can be set/reset via -Dxxx=ON or -Dxxx=OFF at the command line or via the cmake GUI. CMake will memorize the last used options.

DEBUG	Compile in debug mode. This enables a series of additional asserts and sanity checks. It is a lot slower, but also, e.g., makes sure you don't run past grid boundaries. Highly recommended for testing in regular intervals.
TBB	Use multicore acceleration using Intel TBB (*)
OPENMP	Use multicore acceleration using OpenMP (*)
GUI	Build the QT GUI version
PYTHON_VERSION	Select a specific python version (string, e.g., "3.6"). This is especially important if you have multiple versions installed, and need a specific one, e.g., for including numpy and tensorflow.
PREPDEBUG	Debug generated files (**)
DOUBLEPRECISION	Use double-precision floating point numbers, instead of single (this is still experimental).
NUMPY	This option enables support for numpy arrays as native data types in manta kernels and plugins. It's optional, but crucial for incorporating neural networks with tensorflow and numpy.
OPENVDB	Experimental: this enables export for openvdb volumes. When active, save('data.vdb') will write an OpenVDB Volume that could be read, e.g., in Blender or Houdini.

(*): OpenMP or Intel TBB? From a usage perspective, it doesn't matter, as the multicore operations are all abstracted using Kernels. so you do not need to deal with either one directly. My tests showed that TBB is slightly faster, but that might just be my machine. So in the end, use whatever is easiest to set up on your machine.

(**): PREPDEBUG will beautify files generated by the pre-processor, and link to them for compiler errors instead of the original sources. Use only for debugging the pre-processor, otherwise you will end up editing the wrong sources.