viva-munk
A composable framework for simulating populations of growing, dividing cells with realistic 2D physics and shared chemical environments. Cells are capsule-shaped rigid bodies or multi-segment compound bodies that grow, divide, secrete particles, attach to surfaces, and interact physically through collisions and confinement; concentration fields use finite-difference diffusion and are coupled to cells through exchange steps.
How this model is classified mathematically and dynamically.
- Model class
- Formalism
- Determinism
- Stochastic
- Time dynamics
- Discrete
- Spatial
- 2D
- Multiscale
- Yes
Organisms, entities and processes this model represents.
- Organisms
- Infectious agents
- Not recorded
- Health conditions
- Not recorded
- Biological processes
- Molecular entities
- Proteins / genes
- Not recorded
The data this model consumes and produces when executed.
Parameters
| Name | Default | Unit | Meaning |
|---|---|---|---|
| env_size | 500 | micrometer | Width and, unless env_height is set, height of the simulation chamber. |
| n_cells | 1 | Not recorded | Number of seeded cells in experiment configurations. |
| interval | 30 | second | Process tick interval; experiment-specific configurations use values such as 0.1, 1.0, or 30.0 seconds. |
| rate | 0.000289 | per second | Baseline exponential mass-growth rate; default corresponds to approximately a 40-minute doubling time. |
| threshold | 100 | Not recorded | Mass threshold at which a cell divides. |
| glucose_init | 5 | millimolar | glucose |
| glucose_km | 0.5 | millimolar | glucose |
| glucose_diffusion | 0.05 | square micrometer per second | glucose |
| run_speed | 20 | micrometer per second | Swimming speed during a chemotactic run. |
Outputs
| Name | Quantity | Unit | Format |
|---|---|---|---|
| emitted_state_timeseries | spatial position | micrometer | JSON |
| experiment_gif | Animated visualization of the simulated cells and optional fields. | Not recorded | GIF |
| html_report | HTML report containing timing, cell counts, descriptions, and embedded media. | Not recorded | Not recorded |
Experiment protocol
The suite runs registered multi-cell experiments with fixed-step process updates, emits state history, renders GIFs, and assembles an HTML report. Durations range from 900 to 36000 seconds across the registry.
- Timestep
- 1 second
- Duration
- 14400 second
- Observables
- cell positionscell masscell countvelocitypressurechemical concentration fields
Runtime environment, dependencies, and compute requirements.
- Language
- Python >=3.11
- Environment
- pip
The repository exposes nine registered experiment configurations. The test_suite shim delegates to cli.main; the replay command consumes history.db produced by the suite.
Compute requirements
- GPU
- Not required
- Parallelism
- multi-process
Dependencies
- runtime
- process-bigraph >=1.8.5
- bigraph-schema >=0.0.60
- bigraph-viz
- pymunk
- numpy
- matplotlib
- Pillow
- plum-dispatch
- pbg-superpowers
- viva-emitters >=0.4.2
- optional
- pytest
- build
- twine >=4.0.2
Entry points
python -m viva_munk.experiments.test_suiteRun the full experiment suite and generate the HTML report.
- --tests
- Experiments to run
- --output
- Output directory
- --open
- Open report in browser
- --no-open
- Do not open report in browser
- --serial
- Run sequentially instead of parallel
- --workers
- Number of parallel workers; 0 selects automatically
- --from-cache
- Rebuild report from cached runs
python -m viva_munk.experiments.replay <simulation_id>Replay a recorded simulation and regenerate its GIF.
- simulation_id
- Recorded simulation ID; omit when using --list
- --output
- Directory containing history.db
- --out
- Directory for the replay GIF
- --filename
- Replay GIF filename without extension
- --list
- List recorded simulations and exit
python -m viva_munk.experiments.cliCLI implementation for the multi-cell experiment test suite.
Tests
pytestpytest tests/
Artifacts stored with this model.
Identifiers and integrity.
- Metadata review
- Approved · 07ab255c-9ada-4d33-9f49-66cc6277d9f2 · Oct 2026
- Contacts
- Eran Agmon · agmon.eran@gmail.com
- External IDs
- url:https://github.com/vivarium-collective/Viva-munk