MicroSimulator models microbial populations in microfluidic environments, connecting device geometry and flow to solute transport, cell growth, and signaling. These guides take you from a device description and biological rules to runnable experiments, visualization, and quantitative analysis. The modeling interface also supports colonies and multicellular systems without a device.
| If you want to… | Read… |
|---|---|
| Understand how devices, flow, and cells fit together | Microfluidics modeling guide |
| Run a first simulation | Getting started |
| Build a trap or channel with growth and washout | Microfluidic devices |
| Choose a flow solver and assess its numerical behavior | Flow models and flow benchmarks |
| Measure nutrient penetration and growth | Controlled nutrient study |
| Learn the modeling interface | Tutorials |
| Understand numerical conventions | Numerical contract |
| Analyze simulation output | Analysis recipes |
| Configure an accelerator | Execution environments |
| Migrate a CellModeller model or snapshot | Compatibility and migration |
| Test a contribution or backend | Testing and validation |
Start with getting started to install the tools, run a model, inspect it, and resume a checkpoint. Then follow the tutorial index by topic. Each runnable model is self-contained.
| Topic | Guides |
|---|---|
| Devices, flow, and transport | Walls, flow, and washout; pillar channels and flow solvers; nutrient penetration and growth |
| Cell biology | Growth and mechanics; gene circuits; signaling; plasmids and contacts |
| Circuits in populations | SimBOL examples; Danino clock in a device |
| Quantitative output | Checkpoints, contact graphs, and analysis |
Executable teaching models are under examples/tutorials. Smaller focused examples are available in examples.
The architecture guide introduces the engine design and groups the architecture decision records by subject. The numerical contract defines precision, tolerances, time integration, determinism, ordering, and failure behavior across backends.
Start with these documents when extending the engine:
- Shallow device flow and resolved Stokes-Brinkman flow
- Flow-driven cell motion
- Biomass, growth, and uptake
- Independent native backends
- Contact mechanics
- Grid signaling and cell coupling
- Data-only checkpoints
- Restartable model controllers
- Analysis recipes covers lazy Polars workflows for colony geometry, species, lineage, contact graphs, and signal fields.
- Viewer guide covers static scenes, interactive sessions, controls, development, and tests.
- Scene format v2 defines the data exchanged with visualization clients.
- Live viewer protocol v1 defines the authenticated loopback protocol for interactive sessions.
The CPU backend uses the base C++23/Python toolchain described in the top-level quick start. Accelerator-specific setup is documented separately:
The testing and validation guide distinguishes compile checks, native numerical tests, and full application tests. Accelerator support requires execution on corresponding hardware with fallback disabled.
- Run manifest v1 defines reproducible batch jobs and parameter sweeps.
- Scene format v2 defines data-only visualization frames.
- Live viewer protocol v1 defines interactive viewer messages and authority boundaries.
- Checkpoint design defines restart state and schema migration.
- Analysis dataset design defines Parquet/Zarr schemas and provenance.
MicroSimulator originated as a CellModeller rewrite and now has an independent device, flow, and transport modeling workflow. The compatibility and migration guide explains which CellModeller models and artifacts can be used directly, which require a typed translation, and where behavior intentionally differs. Source-pinned matrices and subsystem comparisons preserve the evidence behind those migration decisions.
The testing and validation guide describes the test layers, backend requirements, hardware runners, and release checks. The backend conformance reference lists the shared numerical scenarios and tolerances.
For a standard CPU development build:
uv sync --group dev
uv run pytest
cmake --preset cpu-debug
cmake --build --preset cpu-debug
ctest --preset cpu-debugFormatting, linting, and the Python type check run as commit hooks:
uv run --with pre-commit pre-commit install
uv run --with pre-commit pre-commit run --all-filesThe hooks cover the fast local gates only. Tests, native builds, and backend conformance need a configured build and hardware, and run through CTest and the conformance scripts.