From BlenderWiki

Documentation (GSoC 2017 - Blender Mantaflow Integration)

This GSoC project is a continuation of last years project (Blender Mantaflow Integration: Single Code Fluid Solver) where the idea was to integrate the Mantaflow fluid simulation framework into Blender. This time the focus was on improving that integration. In particular, this was achieved by adding "Secondary particle effects" and "Fluid guiding" functionality.

Background information

This entire project is only possible because of Mantaflow. To learn more about the theory that's behind all the fluids, I highly recommend checking out Mantaflow itself and the according papers from the Thuerey Group at TU Munich:

• Mantaflow fluid-simulation framework: http://mantaflow.com/
• Thuerey Group (Games Engineering at TU Munich): http://ge.in.tum.de/

Getting started

The code for this project is in the branch fluid-mantaflow. The build process is very similar to the official Blender build. You can take a look at these building instructions to get started.

Secondary particles

Secondary particles are a useful addition to enrich any liquid simulation. They can either be used on top of a mesh simulation or just on their own.

In this implementation you can simulate with 'Drop', 'Bubble', 'Float' and/or 'Tracer' particles. Visualizing FLIP particles is also possible.

UI parameters

From the UI you can choose any combination of particles. Except for FLIP particles each particle type also has a customization parameter (you can also tweak the behaviour of FLIP particles - those parameters are just located in the Fluid tab and show up when choosing a liquid domain):

Drop threshold

The cutoff velocity which determines when to generate drop particles (generates drop particle once a cells velocity exceeds this value).

Bubble rise

A value between 0 and 1. Determines how much inverse gravity is applied on a bubble particle (e.g. a value of 0.5 lets a bubble particle rise with half the gravity)

Float amount

A value between 0 and 1. The probability with which a float particle is generated. A value of 0 generates no float particles. However, note that float particles may still show up after being converted from 'Bubble' particles (if these are enabled).

Tracer amount

Similar to float amount - the probability with which a tracer particle is generated.

Particle settings

Each particle type that you enable in the 'Fluid Particles' settings gets its own particle system. Once a particle type is enabled, you can find its particle system just as any other Blender particle system in the 'Particles' tab. From there you can tweak the look of the particles in greater detail.

An interesting thing to note about the new fluid particles is their structure in memory: While on the Blender side particle systems are clearly separated from each other, in Mantaflow there are only two systems. One handles FLIP particles for the actual liquid simulation, a second one handles all secondary particles (drop, bubble, float, tracer).

This structure makes it possible for particles to transition from one state to another (e.g. from drop to bubble, from bubble to float). It also leaves room for future improvements, e.g. particle collisions.

Particle life-cycle

In the current implementation drop, bubble and float particles undergo the "secondary particle lifecycle". This means that drop particles are converted to bubbles once they are inside the liquid. Bubble particles turn into float particles once they have risen up to the liquid surface.

Fluid Guiding

Fluid Guiding is a technique which allows you to enforce motion onto a fluid during its simulation. Mantaflows guiding functions ensure that fluid characteristics are maintained.

To set up a guided fluid simulation all you need to do is add a guiding object to your simulation. When animating this object (e.g. keyframes, object constraint to follow curve), its velocity will be taken into consideration when calculating fluid velocities.

	Fluid Guiding theory
	The magic, i.e. the algorithm, that achieves the guiding effect was previously implemented in Mantaflow. It is based on the paper on Primal-Dual Optimization for Fluids.

UI parameters

There are two parameters that will help control the outcome of a guided simulation:

Weight

This parameter controls the lag of the guiding. A larger value results in a greater lag.

Size

In Mantaflow this parameter is called the blur radius. It determines the size of the vortices that the guiding produces. A higher blur radius results in larger vortices.

Guided Smoke or Liquid?

The fluid guiding feature is currently intended to be used with smoke only. Guided liquid simulation are considered experimental.

The thing is that manipulating liquid velocities tends to be more complex: There are two "velocity representations" (domain grid and velocity from each FLIP particle) and as we've seen with liquid inflow (see Future Improvements) even slight inaccuracies can quickly result in unphysical fluid behaviour. It's currently not clear if a guided liquid simulation "explodes" as well.

But that doesn't mean that you cannot try out guided liquid simulations. The code that makes guided smoke simulations possible is also in use for liquids. My first tests in Blender yielded promising results and also when directly analyzing the grids in Mantaflow there were no "suspicious" velocities.

General integration improvements

The goal of this GSoC was also to make the branch more stable in general. Some improvements in this regard are:

Caching

While implementing secondary particles, it turned out that it makes sense to separate caching for surface (e.g. liquid mesh) and volumetric (e.g. secondary particles, smoke density) data. As such there are now two caching options: one for surfaces and one for volumetric data.

Initial velocity (smoke)

This setting was left untouched for a long time. The feature now works just as in the current Blender smoke solver.

Future Improvements

The Trello list has been around for some time now and is probably the most complete ToDo list. The new bugs and Blender 2.8 essential have the highest priority though:

Bugs

During this GSoC it turned out that liquid inflow objects are problematic. More specifically, there are two open bugs:

Bug 1 - "Problem with liquid inflow velocities" (View on Github)

This bug is the more problematic one. What happens is that liquid inflow velocities become very unstable when there is at least one open domain border. It is not quite clear why this happens. However, what we know is that the issue is reproducable in a standalone Mantaflow script as well.

Bug 2 - "Problem with thin obstacles" (View on Github)

The initial problem was that very thin obstacles (e.g. planes) were not registered by the obstacle levelset generating function. While this issue is now resolved, there remains a problem very fast FLIP particles which can slip through thin obstacles.

Roadmap Blender 2.8

Here are some ToDo's that I think are essential to get done before merging this branch into the main Blender version.

1. Fix open bugs (see bugs). Especially a reliable liquid inflow is important.
2. Add functionality to set initial velocities for liquids (needs different UI than smoke currently has)
3. Tweaking secondary particle life-cycle. Some trial and error to find out which cutoff values work best.
4. Testing, testing, testing.

It is also a good idea to set a bug reporting dealine for a first version. All bugs up until this date X will then be fixed and included in the first release.

Progress updates

The goal is to merge this branch into Blender 2.8. You can follow me on Twitter at @sebbas to hear about the latest progress updates!

Acknowledgements

I would like thank Nils Thuerey and Ton Roosendaal for mentoring this project! Special thanks also to Gottfried Hofmann for tracking down bugs and to Krzysztof Wiśniewski for creating cool test videos (Youtube playlist)!

And to everyone who tested (or is testing) this branch is: Thanks a lot! Main integration is in sight!