Spatio-Flux

A reference application for compositional multiscale biological modeling built on the Process-Bigraph framework. Spatio-Flux composes independently developed processes — metabolism, spatial transport, particle dynamics, structural rewrites — into a single executable simulation via typed interfaces and shared orchestration, not tightly coupled solvers.

It's the worked example in Process Bigraphs and the Architecture of Compositional Systems Biology (Agmon & Spangler, arXiv:2512.23754).

▶ Browse the live test suite report → 19 composite scenarios, each with structure diagrams, time series, and plots.

▶ Open the read-only workbench → The same 19 scenarios as a browsable investigation of studies — the composition DAG (standalone processes → pairs → triples → reference demos), each study's runs, reproduced visualizations, and the process/loom explorer — served with no backend.

What this repo is

Spatio-Flux is a testbed and reference implementation, not an optimized domain simulator. Its purpose is to make model composition explicit and inspectable.

It demonstrates how to:

• compose heterogeneous modeling paradigms (ODEs, dFBA, spatial fields, particles)
• couple mechanisms through shared typed state, not direct process calls
• coordinate multi-timescale execution with reusable orchestration patterns
• swap or recombine processes without modifying surrounding models

The test suite

The heart of the repo is spatio_flux/experiments/test_suite.py, which exercises 19 composition patterns and renders the report linked above.

Covered scenarios include:

• Monod and dynamic FBA metabolism (single-strain + multi-strain communities)
• COMETS-style spatial dFBA on a lattice
• Brownian and Newtonian (Pymunk) particle systems
• Particle–field exchange with embedded metabolism
• Event-driven division and boundary handling

Each scenario produces a process-bigraph diagram, serialized schemas and state, and domain-specific plots or animations.

Each composite is a @composite_generator-decorated function under spatio_flux/composites/, discoverable by the pbg-superpowers dashboard.

Reusing composites at different scales

Generators expose their lattice and transport parameters as keyword arguments — defaults match what the test-suite report uses, but callers (or the dashboard's parameter form) can override them to reuse the same composite at a different resolution or with different transport rates. Commonly available knobs:

• n_bins, bounds — lattice resolution and physical extent (default SQUARE_BINS / SQUARE_BOUNDS, or DEFAULT_BINS / DEFAULT_BOUNDS for diffusion-only generators)
• diffusion_rate, advection_rate — Brownian-particle or field transport coefficients (default DEFAULT_DIFFUSION, DEFAULT_ADVECTION; some generators use a scaled default such as DEFAULT_DIFFUSION / 2)
• n_particles, add_rate, division_mass_threshold — particle population controls
• initial_min_max — per-molecule (min, max) ranges used to seed field state
• field_advection_rate — field-level advection where it must be disambiguated from particle advection (e.g. comets_br_particles_dfba)

Each generator declares only the subset of parameters it actually uses; see the parameters={…} block on each @composite_generator for the authoritative list and types. Build a doc with overrides via:

from pbg_superpowers.composite_generator import build_generator
from spatio_flux.composites import REGISTRY

entry = next(e for e in REGISTRY.values() if e.name == "diffusion_process")
doc = build_generator(entry, overrides={"n_bins": [20, 40], "diffusion_rate": 0.1})

Run it locally

git clone https://github.com/vivarium-collective/spatio-flux.git
cd spatio-flux
uv sync
# Reproduce the whole test suite from the investigation (runs all 19 studies,
# then builds the report) and open it:
uv run python scripts/reproduce.py
open report/index.html

--only <slug> reproduces a single study. Each scenario is a study under studies/<slug>/; the investigation graph lives in investigations/spatio-flux-test-suite/investigation.yaml. To browse it interactively, serve the workbench dashboard:

vivarium-workbench serve --workspace .

The legacy spatio_flux/experiments/test_suite.py runner has been superseded by the investigation + scripts/reproduce.py.

Ecosystem

Spatio-Flux is part of Vivarium 2.0 — an open-source ecosystem for compositional modeling:

• bigraph-schema — typed hierarchical schemas
• process-bigraph — process and composite simulation interfaces
• bigraph-viz — visualization of bigraph structure and data flow
• pbg-superpowers — convention + dashboard for discoverable composites
• spatio-flux — reference multiscale application (this repo)

Citation

@article{agmon2025spatioflux,
  title   = {Process Bigraphs and the Architecture of Compositional Systems Biology},
  author  = {Agmon, Eran and Spangler, Daniel},
  journal = {PLoS Computational Biology},
  note    = {to appear},
  year    = {2025},
}