ΦFlow

Documentation central

The Youtube tutorials are useful. The “main” docs site is guide-like. API reference docs are stored separately: phi API documentation.

NB: Now (v2.5) a substantial part of the functionality has been broken out into a generic numerical library, PhiML, and so part of the documentation is filed there.

Arrays in Phiflow

A.k.a. Tensors, which are wrappers around the tensor objects in whatever math backend phiflow is using.

Arrays have mandatory names which are used in broadcasting rules. This is best explained in the video tutorial, Working with Tensors. broadcasting between objects with “spatial”, “batch”, “instance” and “channel” dimensions is largely automatic. I guess “temporal” is implied somehow? Maybe via Scene objects? I do not use those.

This system is neat, and flexible, but unfortunately I spend a lot of time working around it because ultimately I need to drop into the specialised mathematical tools of specific NN toolkits so I can get things done. Ultimately I still need to choose an interpretation for my tensors, and so PhiFlow’s attempt is valiant, but ultimately burdensome.

Documentation was previously at phi.math API documentation. Now that mathematical functionality has been broken out into PhiML, so now you should refer to phiml.math API documentation.

Fields in Phiflow

A sampling grid plus some sample data at grid locations gives us a SampledField. We could imagine fields that are defined in terms of some general mathematical function. Indeed the documentation references an AnalyticField, but this appears not to be implemented, so we can consider everything to be SampledField for now. CenteredGrid objects are reasonably obvious.

• This is the relevant video tutorial.
• Fields docs

Slightly fancy feature — Grids are not necessarily centred, i.e. summarising the values of a cell by its centre, but may be offset to convey values at the boundaries. This is called the Staggered Grid and is useful for velocity fields in particular.

• Staggered Grid API documentation

inf_field = field.at(
    CenteredGrid(0, x=16, y=16, bounds = field.bounds),
    keep_extrapolation=True)

inf_field = field.CenteredGrid(
    field, x=16, y=16, bounds=field.bounds,
    extrapolation=field.extrapolation)

Actual physics

The actual physics part is what phiflow makes easy.

• phi.physics API documentation:
• Fluids Tutorial: Introduction to core classes and fluid-related functions.
• Overview: Domains, built-in physics functions.
• Functions for Fluid Simulations: Advection, projection, diffusion

Optimisation

There are two types of optimisation supported in ΦFlow, with two different APIs. One is the ΦFlow native optimisation, which optimises Fields and ΦFlow Tensor objects. This copies the scipy.minimize interface.

Another is the NN-style SGD training, which optimises NN parameters. This looks like a normal SGD training loop, as per <insert favourite NN framework here>.

• Optimization and Training docs

As usual with the scipy.minimize style system, there is not much scope to see what is happening during the optimisation. There is an example showing how to do that better in the Physics-based Deep Learning textbook Burgers Optimization with a Differentiable Physics Gradient, although it uses an outdated record_gradients API. A shorter but more modern example is in the cookbook.

ML

The API is idiosyncratic, and, I think, rapidly evolving. Best explained through examples.

• PhiFlow/train_remove_divergence.py
• PhiFlow/differentiate_advection.py
• Differentiable Fluid Simulations with ΦFlow 2.ipynb

Visualization

Messy. They created a lovely UI for controlling simulations interactively, but that is messy and unsatisfactory because python GUIs suck and also jupyter GUIs suck, but and trying to serve two sucky masters is tedious.

As per the advice of lead developer Phillip Holl, I ignore the entire Vis system which only works from command-line scripts. I plot inside jupyter notebooks for now. If I wanted something more sophisticated I might use the ΦFlow Web Interface which integrates with dash. I am not sure why they do not just use one of the fairly standard tools for ML experiment tracking and visualisation such as tensorboard or whatever. the developers of those tools have already experienced the many irritations of trying to do this stuff interactively and found workarounds.

• Visualization
• phi.vis API documentation
• Animations.ipynb

Efficiency/GPUs

• PhiFlow/GPU_Execution.md

I find it congenial to use the EXCESSIVE KILL IT WITH FIRE method to moderate ΦFlow’s ambition with regard to GPUs. In some versions it is too reluctant to use CUDA and in other too averse. e.g. in 2.2.7 EVEN if I am not using cuda math.seed will still try use the GPU which is rude behaviour on shared machines.

Keep it simple by avoiding ambiguity:

from phi.torch.flow import *
from phi.torch import TORCH

GPU mode:

os.environ.pop("CUDA_VISIBLE_DEVICES", None)  #Dangerous on shared machines!
TORCH.set_default_device('GPU')
PHI_DEVICE = 'GPU'  # pass this to Phiflow functions
DEVICE = torch.device('cuda') # pass this to pytorch functions

CPU mode:

os.environ["CUDA_VISIBLE_DEVICES"]=""
TORCH.set_default_device('CPU')
PHI_DEVICE = 'CPU'  # pass this to Phiflow functions
DEVICE = torch.device('cpu') # pass this to pytorch functions

Useful examples

• PhiFlow/demos at master
• Cookbook

Data storage

I do not use the native phiflow system, since I store everything in hdf5. But it is nice that it the API documented:

• Reading and Writing Simulation Data
• Data format specification

References