From BlenderWiki

Jump to: navigation, search

Proposal (GSoC 2017 - Blender Mantaflow Integration)

Proposal for my GSoC 2017 Blender project "Fluid guiding and secondary particle systems". It is based on previous integration steps of Mantaflow into Blender and especially last years GSoC 2016 project "Single code fluid solver".


Sebastián Barschkis

Email / IRC



In this project I would like to improve the existing Mantaflow [1] integration by adding support for secondary particles and by implementing a novel technique on fluid flow guiding from a recent research paper [2]. Furthermore, I would like to incorporate more user feedback to get the integration ready for Blender 2.8.

Guided tornado Guided tornado Guided tornado


Secondary particle systems have become a standard in VFX software to enhance fluid simulations and to add detail to critical parts of the fluid (e.g. foam on breaking waves, drops from splashing liquid, floating dirt on liquid, sparks from fire). Not only through the amount of particles but also by being able to render them separately, secondary particle systems are an invaluable addition to any physically-based fluid simulation. Adding such particles to the Mantaflow integraton will reintroduce functionality from Blender Vanilla and bring back a very familiar tool.

The new fluid guiding algorithm in Mantaflow [2] solves a recurrent problem in which external forces make a fluid simulation look less physically correct. It takes an additional velocity field, enforces this onto the actual simulation and this way creates a guided fluid flow. By having this functionality in Blender user will be able to exert a motion onto the fluid which itself will preserve the characteristics that make it look physically-correct.


  • Option to add secondary particles to Mantaflow liquids
    • tracer, drop, floating particles - as we know them from current Blender v2.78 - should work with Mantaflow fluids
  • Visualize Mantaflow FLIP particles
    • besides just saving the mesh, there will be an option to cache FLIP particles.
  • Controls for guidable fluid flow
    • Animated objects in fluid domain should influence fluid velocity and Mantaflows fluid guiding algorithm should kick in
  • User and technical documentation in form of Blender-Wiki

Project Details

Particle systems

With Elbeem fluids the user is given the option to determine the amount of tracer particles and to control drop and floating particles through a generation factor. In general, this functionality is highly desirable for Mantaflow liquids as well. Similar options should therefore be implemented with the help of the current interface between Elbeem and Blender particles.

While getting back functionality is important, this "re-implementation" should also be used for improvements. Tracer particles that are seeded into the fluid for example could better take into account properties of its surrounding fluid, e.g. particles at a liquid inflow could be emitted with the help of liquid velocities and current curvature, tracer particles in a smoke / fire environment could make use of heat, fuel and react values. These calculations should run in the background, however, adding more UI controls to make particles less static is a good idea too.

Besides integrating Blender particles I also would like to open up Mantaflow FLIP particles to the user. These particles, that are used to generate the liquid mesh, can in theory be shown on their own. So instead of a mesh, the same liquid will be made up of particles. A second option in the cache for FLIP particles should suffice for this.

Guided fluid simulation

Starting from Mantaflow v0.10, there is basic functionality for fluid guiding. Access to this functionality is possible through the standard Mantaflow Python API and can be controlled by calling a more advanced pressure solve routine with a (predefined) velocity field and a set of strength parameters as additional arguments.

Integrating this feature into Blender would be a twofold process. On one hand, the current Python script backend needs to be adapted and new flow guiding functions need to be added. On the other hand, and this is the more challenging part of the feature, there needs to be flexible UI to let the user exactly define the flow velocity field. One potential solution to this would be to introduce fluid flow objects of type "guiding object". Their velocity determines part of the domain velocity and when animated these objects could control the fluid motion. Flow strength could be set in new UI fields as well.

For the development of this feature, one of my most recent additions to the Mantaflow integration - moving obstacles - will come in handy here too. While moving obstacle objects affect both velocity grid and flag grid (the grid that defines the content of any fluid cell, e.g. fluid, obstacle, empty), "guiding objects" would be invisible with respect to the simulation and only influence velocities. Thus, the mechanism of reading and writing velocities is quite similar and code parts will be reusable.

Transition to Blender 2.8

Getting rid of Elbeem and letting Mantaflow handle both smoke and liquids is probably one of the bigger updates in Blender. In order to meet all expectations I would like to dedicate some time every week to prepare the branch for the integration into master. This could include small UI changes, bug fixes for features that I have already implemented or working on versioning (e.g. ways to handle missing features).

Node based fluidsolver (optional)

I expect to be to busy with fluid guiding and particle systems during the entire GSoC. If there is some time left, I will first use it to work on the integration of the fluid-mantaflow branch into master. However, if it turns out that there is still time left, I plan on using it to draft a very basic version of a node based fluid solver (discuss concept and implement first iteration).

Project Schedule

In general I would like to get the smaller parts of my GSoC project done first. This includes visualizing Mantaflow FLIP particles and developing the fluid flow guiding mechanism. That way, users will be able to play with some of the cool functionality early on and I can focus on the slightly more challenging secondary particles in the time remaining.

The plan to achieve all this in 13 weeks looks like this:

Week Timeframe Plans
0 until 30/05 Get to know Mantaflow fluid guiding functions, read more about fluid guiding theory (papers, discuss with mentor)
1 30/05 - 05/06 Start working on Mantaflow FLIP particle cache integration
2 06/06 - 12/06 Start implementing fluid guiding setup (e.g. new object type, velocity transfer, Mantaflow script adaptions)
3 13/06 - 19/06 Work on both FLIP particles and fluid guiding
4 20/06 - 26/06 Mantaflow FLIP particle cache integration and fluid guiding should work now
5 27/06 - 03/07 Figure out how Blender particle system is hooked up to Elbeem, start with actual secondary particle systems
6 04/07 - 10/07 Continue work on secondary particles, if needed maybe collect some UI ideas for particles
7 11/07 - 17/07 Mid GSoC! Wrap-up what's been done so far. If I am not on track with my schedule, then use this week to catch up.
8 18/07 - 24/07 Time for first refactor/cleanup, try to produce some content with current state of secondary particle systems
9 25/07 - 31/07 Spend some extra time on Blender master integration this week
10 01/08 - 07/08 Secondary particle system should work
11 08/08 - 14/08 Extra week coding on things that got left behind, more master integration
12 15/08 - 21/08 Code review, refactor and cleanups, incorporate more user feedback, last-minute fixes now (and not in week 13 ...)
13 22/08 - 29/08 Create user documentation, sample scenes and videos


My name is Sebastián, I am 24 years old and currently studying computer science at the Technical University of Munich (TUM). In summer 2015 I picked up the previously finished GSoC 2014 Blender Mantaflow integration project and started working with Nils Thuerey on fire and smoke effects. The following summer 2016 I worked on my own GSoC project and added Mantaflow liquids to the integration branch. Since then I was able to add more and more features including support for multiple domains and moving obstacles.

By working with Mantaflow and at the CG chair at TUM I was able to learn a whole lot about fluids. I hope can make use of this, add more new useful features over the summer and eventually merge this branch into master.


  1. Thuerey N., Pfaff T.,, 2017
  2. Inglis F., Eckert M.-L., Gregson J. and Thuerey N., Primal-Dual Optimization for Fluids, Computer Graphics Forum, 2017