MicroSimulator simulates microbial populations in microfluidic devices. It brings device geometry, steady fluid flow, solute transport, and individual-cell biology into one Python modeling workflow, connecting the conditions in a channel or trap to colony growth, signaling, and washout.
Models run on a C++23 engine with native CPU, Apple Metal, and NVIDIA CUDA backends. Simulations can run headlessly or with an interactive browser viewer. Device geometry and flow are optional for standalone colony models.
- Device geometry: describe traps, channels, and pillars with mechanical walls and solid masks that constrain cells and route solutes through the fluid space.
- Flow and transport: solve depth-averaged Hele-Shaw/Darcy flow in shallow devices or resolved Stokes-Brinkman flow on a staggered grid, then use the velocity field for conservative advection, diffusion, and reactions.
- Growth and signaling: combine nutrient uptake with conserved biochemical biomass, rod growth and division, contact mechanics, lineage, intracellular circuits, and diffusible signals.
- Cells in flow: model free-cell drift and rotation, explicitly attached populations, stationary biomass resistance, and model-defined outlet removal.
- Reproducible experiments: inspect live simulations, resume versioned checkpoints, run parameter sweeps, and export Parquet/Zarr datasets for quantitative analysis.
The microfluidics modeling guide explains how these pieces fit together. Cell motion uses a kinematic approximation followed by contact relaxation; stationary resistance is an empirical closure. The flow benchmarks and nutrient study document numerical checks and refinement studies. Experimental calibration remains specific to each model.
MicroSimulator requires Python 3.12, CMake 3.25 or newer, Ninja, a C++23 compiler, and uv.
git clone git@github.com:DRAGGON-Lab/MicroSimulator.git
cd MicroSimulator
uv sync --group dev
uv run microsimulator devices
uv run microsimulator run \
--model examples/microfluidic_trap.py \
--backend cpu \
--seed 42 \
--steps 100 \
--dt 0.02 \
--output results/trap.jsonThis runs a cell trap supplied with nutrient through a flowing channel and saves a restartable checkpoint. Follow getting started to set up the viewer, or continue with microfluidic devices to explore walls, transport, growth, and washout.
| Explore | Start with |
|---|---|
| Nutrient delivery, colony growth, and washout in a trap | Microfluidic trap |
| Flow around pillars, attached founders, and released daughters | Pillar channel |
| A quorum-sensing clock in a flowing device | Danino clock |
| A single biopixel trap with documented dimensions and CAD provenance | Biopixel tutorial |
| Nutrient penetration, biomass gain, and conservation | Controlled nutrient study |
The tutorial suite also covers growth, gene circuits, signaling, plasmids, contacts, and analysis. Device examples state their geometry, units, and modeling assumptions alongside the runnable code.
| Backend | Status | Role |
|---|---|---|
| CPU | Feature complete | Portable execution and numerical reference |
| Apple Metal | Feature complete | Native Apple GPU execution |
| NVIDIA CUDA | Under active development | Native NVIDIA GPU execution |
Both flow solvers have native CPU, Metal, and CUDA implementations. CPU and Metal support the complete current modeling workflow. CUDA compilation is checked, while NVIDIA runtime and application validation remain required for supported status. The validation policy defines the hardware and application acceptance criteria.
| Topic | Entry point |
|---|---|
| Microfluidics | Devices, flow, transport, and biology |
| Tutorials | Modeling tutorials |
| Architecture and numerics | Design documents |
| HPC environments | CPU, Metal, and CUDA setup |
| Analysis and visualization | Research output workflows |
| CellModeller compatibility | Scope and evidence |
| Development | Testing and validation |
The complete documentation index is available at docs/README.md.
MicroSimulator began as a rewrite of CellModeller and has developed into an independent microfluidics simulation system. It builds on that lineage of individual-based cell modeling with its own device, flow, transport, and experiment workflows. The compatibility guide documents supported CellModeller models and intentional numerical differences. Users of the former CellModeller2 package can follow the rename guide.
MicroSimulator is available under the MIT License.