PhiFlow Documentation

PhiFlow is an open-source simulation toolkit designed for optimization and machine learning. Key features include:

• ML Integration: Tight integration with PyTorch, Jax, and TensorFlow for differentiable simulations that can run on the GPU.
• PDE Operations: Built-in operations focused on fluid phenomena for concise simulation formulation.
• Web Interface: A flexible web UI with live visualizations and interactive controls.
• Backend Agnostic: Reusable simulation code that works across different backends (NumPy, PyTorch, Jax, TensorFlow) and dimensionalities (2D or 3D) without modification.
• Linear Equation Solver: High-level solver with automated sparse matrix generation.
• Design: Object-oriented and vectorized design for expressiveness and extensibility.

When comparing PhiFlow to MantaFlow, note these key architectural and data differences:

• Differentiability: PhiFlow supports differentiable operators, whereas MantaFlow focuses on fast CPU-based simulations.
• Grid Sizing: In PhiFlow, staggered velocity grids are larger by one layer on the positive domain sides compared to the scalar grids. In MantaFlow, all grids have the same size.
• Vector Dimensionality: MantaFlow uses a fixed 3-component Vec3 struct for all solvers. PhiFlow uses vectors that match the solver's dimensionality (e.g., 2-component arrays for 2D solvers).
• Gravity Direction: In PhiFlow, gravity acts along the last or first dimension (e.g., Z in 3D, Y in 2D). In MantaFlow, gravity always acts along the Y direction.

The web interface distinguishes between the execution speed of your code and the visual update speed in the browser:

1. Execution Framerate: Defined by the view() method; it controls how quickly your user code is executed.
2. Refresh Rate: Controlled via a setting above the field viewer in the web interface; it defines how often the diagrams in the browser are updated.

To handle data-parallel simulations efficiently, ΦFlow supports batch modes. This allows you to treat multiple scenes as a single batched object, which is ideal for stacking tensors of the same resolution.

1. Create a batch: Use Scene.create with the count argument set to the batch size and specify a batch_dim (e.g., 'batch').
2. Writing: When calling scenes.write(), the fields are automatically unstacked along the batch_dim and distributed to the individual scenes.
3. Reading: When calling scenes.read(), the loaded fields are automatically stacked along the batch_dim into a single batched tensor.

You can use the GUI to pause, run single iterations, or break a loop by iterating over Viewer.range().

To prevent the loop from running immediately upon launch, use play=False in the view() call. This stops execution as soon as the loop is encountered, allowing you to use GUI controls to manage the flow.

data = Domain(x=32, y=32).scalar_grid(Noise())
# play=False stops execution immediately when the loop is hit
for _ in view(data, play=False).range(10):
    data = physics(data)

Installing from source is required if you want to use PhiFlow CUDA operations with TensorFlow. The source version includes demo scripts and tests.

1. Clone the repository: git clone https://github.com/tum-pbs/PhiFlow.git <target directory>
2. Add the directory to your Python path (e.g., by running pip install <target directory>/ or configuring your IDE).

Note: If you use pip install <target directory>/, you must rerun this command after making changes to the source code.

$ git clone https://github.com/tum-pbs/PhiFlow.git <target directory>
$ pip install <target directory>/

The API documentation is generated using pdoc. To generate it manually, ensure that phi is in your Python path and that PyTorch, TensorFlow, and Jax are installed. Run the following command:

pdoc --html --output-dir docs --force phi

In PhiFlow, custom simulations should not rely on abstract State or Physics classes. Instead, define your simulation logic as standard Python functions and call them within a loop. The phi.physics module provides high-level operations that act on Field objects.

Commonly used functions like advect.semi_lagrangian and fluid.make_incompressible are available via the standard from phi.flow import * import.

from phi.flow import *

DOMAIN = Domain(x=64, y=80, boundaries=CLOSED, bounds=Box(x=100, y=100))
velocity = DOMAIN.staggered_grid(Noise())
pressure = DOMAIN.scalar_grid(0)
for _ in range(100):
    velocity = advect.semi_lagrangian(velocity, velocity, dt=1)
    velocity, pressure, iterations, _ = fluid.make_incompressible(velocity, DOMAIN, pressure_guess=pressure)