Topological Simulation Platform for Active Matter.
TopoSPAM is a Python package that drives three C++ simulators and comes with an example
notebook for each of them in examples/:
| Notebook | Model | C++ backend |
|---|---|---|
ActiveFluid.ipynb |
2D active polar fluid (Ericksen-Leslie) | cpp/Active2d.cpp (OpenFPM, MPI) |
SpringLattice.ipynb |
Spring lattice with spontaneous strain | cpp/SpringLattice.cpp (OpenFPM) |
VertexModel.ipynb |
Active 3D vertex model of a monolayer | cpp/vertex_model3d_monolayer |
There are three ways to run TopoSPAM:
- Docker image (recommended to try the examples): everything is installed and compiled already. Works on Linux, macOS (Intel and Apple Silicon) and Windows.
- Native installation with pixi (recommended to work with the code): one command installs a locked environment with all dependencies, compiles the simulators and starts JupyterLab, on macOS and Linux. Nothing is installed system-wide.
- Native installation with Homebrew: a script installs the dependencies with Homebrew, compiles the simulators and creates a Python environment.
- Install Docker: Docker Desktop on macOS and Windows,
or Docker Engine on Linux. Check that
docker run --rm hello-worldworks. - Start TopoSPAM:
The first start downloads the image (about 3 GB).
docker run --rm -p 127.0.0.1:8888:8888 ghcr.io/abhinavsns/topospam:latest
- Open the link that is printed in the terminal, which looks like
http://127.0.0.1:8888/lab?token=.... - In JupyterLab, open the folder
examplesand one of the notebooks, then run all cells (Run menu, Run All Cells).
You do not need to activate an environment, start Jupyter yourself or compile anything: the
image contains the compiled simulators and starts JupyterLab. Stop it with Ctrl+C in the
terminal.
Good to know:
- Everything you do in the container is discarded when it stops. To keep your work, download
the files from JupyterLab, or mount a folder of your computer into the container: create it
(
mkdir work) and add-v "$PWD/work:/home/linuxbrew/topospam/work"to thedocker runcommand. It appears aswork/in JupyterLab. - If port 8888 is already in use, choose another one, e.g.
-p 127.0.0.1:8890:8888, and use that port in the printed link. - To use a shell in the container instead of JupyterLab, append
bashto thedocker runcommand (plus-itbefore the image name).python tests/smoke_test.pythen runs all simulators briefly. - The image exists for x86-64 (Intel/AMD) and ARM64 (e.g. Apple Silicon); Docker picks the
right one. On Apple Silicon, do not force
--platform linux/amd64: under the x86 emulation the Jupyter kernels do not start. - To build the image yourself:
docker build -t topospam .in this repository. On ARM64 this compiles OpenFPM from source, which takes a few minutes longer.
pixi installs the dependencies (compilers, MPI, OpenFPM, Python packages, ...)
as conda packages into the folder .pixi of the repository, in exactly the versions recorded
in pixi.lock. Homebrew is not needed.
- Install pixi:
curl -fsSL https://pixi.sh/install.sh | sh(orbrew install pixi), then open a new terminal. On macOS, the Xcode Command Line Tools are needed as well (xcode-select --install). - Get TopoSPAM and start JupyterLab:
The first run downloads the environment (a few GB) and compiles the simulators, which takes a few minutes. Open the notebooks in
git clone https://github.com/abhinavsns/topospam.git cd topospam pixi run labexamples/.
pixi run test runs all simulators briefly to check the installation, and pixi shell opens
a shell in the environment.
Prerequisites:
- macOS: the Xcode Command Line Tools (
xcode-select --install). - Linux: a C++ compiler and basic build tools, e.g.
sudo apt-get install build-essential procps curl file giton Debian/Ubuntu. On a machine without a display (e.g. a server reached via SSH), also installlibosmesa6for the 3D plots and see Troubleshooting. - Homebrew. Follow the instructions at the end of its installation to add it
to your
PATH.
Homebrew provides OpenFPM and its dependencies precompiled for Apple Silicon Macs (macOS 15 or newer) and for Linux. On Intel Macs it compiles all of them from source, which takes hours: use the Docker image or pixi there.
Then run:
git clone https://github.com/abhinavsns/topospam.git
cd topospam
./install.shinstall.sh takes a while (mostly Homebrew downloads) and performs these steps, which you can
also run yourself:
- Install OpenFPM and the other C++ dependencies with Homebrew:
brew tap abhinavsns/homebrew-openfpm brew trust abhinavsns/openfpm # needed by recent Homebrew versions for third-party taps brew install abhinavsns/homebrew-openfpm/openfpm eigen@3 gsl ffmpeg python@3.13 - Compile the C++ simulators in
cpp/:make backend
- Create a Python virtual environment and install the TopoSPAM package into it. Use Python
3.13 (or 3.10 to 3.14): VTK has no packages for Python 3.15, Homebrew's default
python3."$(brew --prefix python@3.13)/bin/python3.13" -m venv topospam_env source topospam_env/bin/activate pip install -e . python -m ipykernel install --user --name topospam --display-name "Python (TopoSPAM)"
- Run all simulators briefly to check the installation:
python tests/smoke_test.py --quick
Afterwards, start JupyterLab from the repository and open the notebooks in examples/:
source topospam_env/bin/activate
jupyter labTo update an existing Homebrew installation, e.g. one that stopped working after brew upgrade,
run brew update, brew upgrade abhinavsns/homebrew-openfpm/openfpm and then make clean backend
in the repository.
- With the Docker image: never.
- With pixi: never by hand.
pixi run labandpixi run testfirst recompile whatever C++ code changed. - With the Homebrew installation:
make backend(in the repository) compiles the C++ simulators.install.shdoes this once. Run it again after you change C++ code (e.g.cpp/Active2d.cpp) and afterbrew upgradeupdated OpenFPM's dependencies. Changes to the Python code need no recompilation (the package is installed in editable mode).
Each notebook starts with
import topospam
repo_path = topospam.set_repo_path('..')which tells TopoSPAM where the repository with the compiled simulators is, here relative to the
examples folder. If you copy a notebook somewhere else, pass the path of the repository
instead. set_repo_path also warns if the simulators have not been compiled yet.
The simulations write their output to cpp/Active2dOutput, cpp/SpringLatticeOutput and
cpp/VertexModelOutput; each run replaces the output of the previous one.
The installation relies on Homebrew, which changes over time. Some messages you may see:
Refusing to load formula abhinavsns/openfpm/openfpm from untrusted tap: recent Homebrew versions require trusting third-party taps. Runbrew trust abhinavsns/openfpm.boost@1.85 has been disabled: your OpenFPM formula is older than 5.0.1_1, which uses Homebrew's current Boost and is built against the current versions of its dependencies. Update it as described at the end of the installation steps above.'EIGEN_GNUC_AT' ...or other errors inEMatrix.hpp: OpenFPM 5.0.1 does not compile with Eigen 5, which Homebrew'seigenprovides since late 2025. Runbrew install eigen@3;make backenduses it automatically.fatal error: config.h: No such file or directory: the OpenFPM 5.0.1 package lacks this header. Update your copy of this repository, which provides it incpp/openfpm_config/.- Linux:
undefined reference to ...@GLIBC_2.38(or anotherGLIBC_version): Homebrew installed its own, newer glibc because the system one is too old for its packages. Programs linked against Homebrew's libraries then have to be compiled with Homebrew's GCC, whichmake backendselects automatically when Homebrew's glibc is installed. - Linux: 3D plots crash the kernel or fail with
Failed to load an X11 libraryorlibOSMesa not found: there is no display, and TopoSPAM renders with OSMesa instead. Install it (sudo apt-get install libosmesa6). If a display is set but does not work (e.g. SSH with X forwarding), also setexport VTK_DEFAULT_OPENGL_WINDOW=vtkOSOpenGLRenderWindowbefore starting Jupyter. No matching distribution found for vtkduringpip install: the Python version is newer than the ones VTK provides packages for (e.g. Python 3.15). Create the environment with Python 3.13, as shown in step 3 above.TopoSPAM backend executable not foundwhen running a simulation: the simulators have not been compiled. Runmake backendin the repository (or./install.sh; with pixi,pixi run build).mpirun was not found: Homebrew'sbindirectory is not on thePATHof the program that started Jupyter. Start Jupyter from a terminal in whichbrewworks.Error: Too many files openduring the Homebrew installation: run the installation again, or raise the limit first withulimit -n 4096.- Compilation errors on macOS can come from an old Xcode toolchain. Update the Xcode Command Line Tools.
If the native installation does not work on your system, please use the Docker image.
Please check the issues of this repository and the troubleshooting section above first. If you
run into a new problem, open an issue with the full error message and the output of
python tests/smoke_test.py. The system configuration differs for everyone, so the
installation may fail because of a dependency rather than TopoSPAM itself.
- pixi:
pixi.lockfixes every package, so the environment does not change by itself. To move to newer packages, runpixi update, check them withpixi run test, and commitpixi.lock. The workflowpixi.ymlinstalls the locked environment and runs the smoke test and all notebooks on macOS and Linux for every push and once a week. - OpenFPM comes as conda packages from the channel https://abhinavsns.github.io/homebrew-openfpm,
built from the recipes in the
conda/folder of abhinavsns/homebrew-openfpm by its CI. - Docker: the workflow
main.ymlbuilds and tests the image and publishes it frommainaslatest, and for a tagvX.Y.Zasghcr.io/abhinavsns/topospam:vX.Y.Z. A tagged image never changes, so cite a tag (e.g. in a paper) to point to a fixed version.