PhiFlow's default branch is master and its coverage badge watches develop

The default branch is master and the badges point at develop

The repository's default branch is master, and three of the four badges and links at the top of the page target the other branch instead. The coverage badge is scoped to a branch named develop, and the tutorial notebook link points at a file on develop as well. So a reader arriving from those links lands on source that may not be the code they installed, and the coverage number they see may describe commits that were never tagged. Two long-lived branches are a normal way to run a project with in-progress documentation, but the badge pointing at the non-default branch is the kind of detail that costs an afternoon when the numbers and the version disagree.

Four autodiff backends, and not one of them is a dependency

The toolkit is written mostly in Python and is described as usable with four machine learning frameworks, each linkable so that the framework's own automatic differentiation flows through the solver and an end-to-end differentiable function can span a learning model and a physical simulation. What the install requires is much shorter: one helper library at a minimum version, a plotting library at a minimum version, and a version-parsing library. So the frameworks are optional by construction, and the code is arranged to match. The package list contains a subpackage for the Jax path, a second one nested under it for the autodiff-based interface, and separate subpackages for the TensorFlow and PyTorch paths. Choosing a backend is a matter of what you have installed.

The package list is written out by hand, thirteen paths deep

Most modern builds let a tool discover subpackages. This one does not. The build script names thirteen package paths explicitly, starting with the top-level package and then naming the field, geometry, maths, physics and autodiff subpackages, and finishing with four entries under the visualisation package: a console renderer, a dashboard renderer and a matplotlib renderer, plus the package itself. A thirteenth entry is nested one level deeper. The consequence is quiet rather than loud. Nothing fails if someone adds a new subpackage; it simply does not ship, and the failure appears at install time on someone else's machine as a missing module. Three visualisation backends in a hand-written list is also a signal about how often that list has to be touched.

A missing documentation file empties the package description

The long description is read from a single file in the documentation directory, and the read is wrapped in a try block that catches a missing file and falls back to an empty string. That is a reasonable pattern for a source install where documentation may not be present, and it is also a silent one: build from a checkout without that file and the package installs perfectly with no description at all on the index. The version is handled differently and better, read from a plain version file inside the package rather than imported from it, which means the number exists in exactly one place. The download link is then built by interpolating that version into an archive address.

Three spellings of the machine-learning helper live in this tree

The root contains a directory named with a capitalised, multi-segment name that matches the helper library the package depends on, and the build script requires that helper library by its lowercase published name at a minimum version. The package's own import namespace is a third, single-word lowercase form. So one tree contains a helper source directory, a requirement on the published distribution of that helper, and the simulator package under its own short name, and the only place the relationship is written down is the requirement line. Anyone vendoring the helper from the directory in the tree rather than from an index will find the build script quietly installing a different copy of it.

The gallery is organised by discretisation, not by physics

The examples are grouped into four categories and the grouping is about how space is represented rather than what is being simulated. The grid category is the largest, with sixteen entries running from a rendered fluid logo through wake flow, a lid-driven cavity, a rotating bar, higher-order turbulence, heat flow and reaction-diffusion, and it includes one example explicitly about running simulations in parallel. The mesh category has four and is the finite-volume set, including one that builds a mesh from a geometry file and one that solves flow around a cylinder. The particle category has seven, covering smoothed-particle and fluid-implicit methods, streamlines, terrain, gravity, billiards and ropes. The last category mixes optimisation with neural networks, from plain gradient descent to learning a throwing motion.

One gallery entry is filed under a caption that renames it

Each tile in the gallery links to a generated page whose filename comes from the example script. One of them is filed under a filename about a batched smoke simulation and captioned parallel simulations instead, which is a reasonable description of what it does and a small mismatch for anyone looking for the file by name. The same category also leads with a fluid logo rendered through the solver, which is the clearest statement on the page that the gallery is a demonstration of the machinery rather than a catalogue of physics problems. The rest are named after the situation they reproduce, which is what makes the list scannable in a way a physics index would not be.

Editorial conclusion

This suits someone who has a physics simulation inside a learning loop and wants gradients through it rather than a solver that returns numbers. Two things to know before you build on it. The package list in the build script is written out by hand, so a new subpackage is silently excluded from the distribution until somebody edits it, which is the failure mode to check for if an import works from a checkout and not from an install. And the project runs two long-lived branches, with the default on one and the coverage badge and tutorial link on the other, so read the documentation for the branch your installed version came from.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tum-pbs/PhiFlow on GitHub