Page MenuHome

Adaptive time step for fluid particles
Closed, ArchivedPublicPATCH


This patch adds a feature to allow the number of subframes to be altered automatically while a particle simulation is running. Currently, only SPH fluid particles implement this feature.

The code works by calculating the maximum Courant number[1] for the simulation. The user inputs a preferred Courant number to aim for. If the calculated Courant number is greater than the preferred one, the time step will be reduced; if it is greater, the time step will be increased. The Courant number is calculated by comparing the speed of each particle to the distance to its neighbours. But first, the speed of its neighbours are subtracted from its speed: this allows free-falling particles to simulate with zero subframes. Turbulent flows will simulate with more subframes.

This patch modifies the simulation loop in system_step to allow the time step to vary mid-frame. However, the last time step in the frame is adjusted so that it syncs with the end of the frame. Then, the effective number of subframes is stored as the initial time step size for the next frame. This causes the time step size to oscillate a little, but the results are still good.

Attached are some sample files for testing. Note that, although the adaptive subframe feature is stored in the .blend, it currently isn't read because it is waiting for a version bump for do_versions. Therefore to run these tests, you will need to enable adaptive subframes: find the Subframes control in the particle properties, and tick the new checkbox that is next to it; the Subframes control will then be replaced with one title Threshold, which controles the preferred Courant number. Values of 0.2 - 0.4 are sensible.


Event Timeline

Assigned to self for review.

The code currently prints out some debugging information to show the current time step. This is for your interest while testing, but it should be easy to remove. I can remove it if you like; just let me know.

Ooops! I forgot to reset the max Courant number to zero after each time step, so the time step would often shrink to 1/100th of a frame. I have added a new version of the patch that fixes this. The new version also prints out the Courant number on the console as CSV for graphing. The fields are: frame, partial frame, dt (in frames), Courant number, subframes. For example, this is the trace for frame 21 of a simulation:


Also, both patches apply against revision 36757. Let me know if you want an updated patch against HEAD.

Added a new version of the patch: dyn_subframe_vector3.patch. This one still applies against r36757. Changes:
- Default Courant number of 0.2, instead of 0.4.
- Tooltip now suggests a range of 0.1-0.3.
- Invalidating particle cache when enabling adaptive time step.
- Removed debugging print messages. To see them (if you're curious about how the code works, or to make some charts), use version 2 of the patch.

Attaching two files that show how the simulation progresses for the Drop.blend test, with a Courant target of 0.2.
- ATSChart_Drop.png is a graph of the time, timestep size and Courant number versus simulation step.
- Drop.png shows screenshots for two frames of the test.
In both images, (a) shows the state immediately before the particles in the tube are released, and (b) shows the state immediately before the falling particles land in the bowl. The graph shows that the time step is small while the bowl fills. As the fluid slows, the time step increases. When the particles in the tube are released the time step decreases again, and becomes very small when they strike the stationary particles. This is because at that time, their relative velocities are very different.

Attaching a new version of the patch (version 4) that deals with determinism. The previous version was deterministic between runs, but if two objects shared the same ParticleSettings they would evaluate differently. Now, the time step size is stored in ParticleSystem instead, so the state is not shared between objects.

Also attached is a .blend that demonstrates this. It contains two emitter objects that are identical, and share a ParticleSettings object. If you play or bake the animation, you should see that the particles in both systems are in the same locations. Try selecting just one of the emitters to visualise this: if the particles were in different locations, half of them would not be outlined as selected.

Subsequent runs should also produce the same results.

This new version of the patch follows up the discussion around attribution. A notice that will appear on the credits page on the web has been added (in intern/tools/ The attribution notices in two of the C files have been modified to show what the change was, so that it is clear copyright is not being claimed for the whole file. This roughly follows the convention in some of the Linux kernel files, such as

By making a contribution to this project, I certify that the contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file.

Signed-off-by: Alex Fraser <> on behalf of VPAC Ltd.

Committed, revision 40537.

Alex Fraser (z0r) changed the task status from Unknown Status to Unknown Status.Sep 26 2011, 2:50 PM