Developer Documentation

You'll find some basic information on mantaflows C++ core framework here. Plugins & Kernels provides an introduction on extending the framework with your own plugins. The developer documentation is a doxygen-generated class documentation - rather incomplete as of yet, but improving. It also contains a list of all exposed data types and plugins which can be accessed from Python scene files.

As the documentation is unfortunately still a bit sparse, the best way to get to know plugins and datatype extensions is to look at some simple examples in the code base, for example extforces.cpp.

Information how to use the test system can be found here.

General Concepts

The aim of this section is to provide some insights about general design choices of the mantaflow code.

• All simulations use normalized spatial coordinates. Thus a cell always has size one. This shifts complexity into the scene setups, but prevents numerical problems in the simulation, and improves readbility of the values you'll encounter in a simulation.
• The objects of a simulation should have as little internal state as possible. All this info should be represented in the Python scene.
• We've tried to keep the feature set as small as possible, to avoid feature creep, and to keep the code size down. Also, we've tried to minimize the use of external libraries. The most crucial dependence at the moment is Python.

Instead of strictly following an object oriented design, with a nice class hierarchy etc., mantaflow takes a data centric view. A fluid solver can be seen as a collection of operators working on different Eulerian or Lagrangian variables. As such, grids and particles are the central data types of all mantaflow scenes. The main goal of this design is to keep things as simple as possible.

Each of the grids and particle data fiels supports Scalar values (int or Real), and small vectors (three or four dimensional). Support for 4D data is intentionally different from 3D data. Usually, 3D data will be sufficient for most solvers. 2D is seen as a special case of 3D in mantaflow, thus code is shared, and all 3D code should work with 2D. The 4D handling is different:

• scenes are still usually mostly 3D, but can work with additional 4D data on the side.
• The interfaces are structured in the same way for 3D and 4D grids, so operators can still be made to work with both using templates.
• If 4D operators are needed in a scene, 4D support (and the size of the time dimension) can be manually enabled with the fourthDim.
• As before, grid dimensions are constant for all grids of a solver, thus within a single solver as parent, all 4D grids will have the same size of the t dimension.

Known Bugs / Pitfalls

• Don't dynamically create Solver objects after initializing the GUI. This can currently cause crashes.
• It's easy to forget that Grid<X> objects should never be passed by value (this could lead to lots of memory being unnecessarily copied). So always make sure to pass these objects by reference (for mandatory parameters) or pointer (for optional ones).
• The mantaflow preprocessor right now does not parse the C-preprocessor instructions (#...). So it won't recognize if parts of the code are not active due to an #ifdef, and incorrectly generate glue-code for it.
• In addition, it can't resolve overloaded functions. Usually the easiest way is to name them differently (e.g. fooReal, fooVec3 ...), or pass a pointer to the base type, and then manually distinguish (see advectSemiLagrange for an example).
• A peculiarity of the Python bindings is that passing parameters by reference won't work, unless the variable is a grid or particle system (which are handled in a non-standard way). For basic types, such as integer or Vec3 variables, parameters with references will transfer the value to the C++ code but not back. Thus, e.g., a function foo(Vec3& v) will get the value of v from the Python script, but modifying it in C++ will not have any effect on the Python value. As a work-around, values can be passed back to Python via the return value of a function.
• Showing cells in Qt by clicking on them currently has problems on Macs with some Qt versions (it should work on other platforms, and is hopefully fixed in Qt soon).
• Mantaflow uses anonymous variables to trigger kernel evaluations. Unfortunately, this can conflict with standard C/C++ syntax. E.g., int(a); is valid syntax for creating an integer with name "a". Thus, when starting a kernel with a single parameter, e.g., myKernel(grid); this will not trigger the kernel to be evaluated with parameter "grid", but instead it will lead to the creation of a new variable of type "myKernel" that is also called "grid", leading to a compiler error such as
  redefinition of 'grid' with a different type: 'Manta::myKernel' vs 'Grid'.
  While the preprocessor could theoretically check for this special case, we recommend the following work-around at the moment: instead of an anonymous variable, create a named one. E.g., myKernel tmp(grid);. This will get rid of the error.