Executable

Vivarium-chemotaxis

Eran Agmon + 1 other

v0.0.1MITOct 2026

Citation: A Multi-Scale Approach to Modeling E. coli Chemotaxis

A Vivarium model integrating receptor activity, flagellar motility, gene expression, transport, metabolism, membrane potential, growth, and division for Escherichia coli chemotaxis.

molecular cellular population

How this model is classified mathematically and dynamically.

Model class: multi-scale model ordinary differential equation model constraint-based model stochastic model agent-based model
Formalism: ODE stochastic agent-based
Determinism: Stochastic
Time dynamics: Discrete
Spatial: Compartmental
Multiscale: Yes

Organisms, entities and processes this model represents.

Organisms: Escherichia coli
Infectious agents: Not recorded
Health conditions: Not recorded
Biological processes: chemotaxis gene expression
Molecular entities: Not recorded
Proteins / genes: Not recorded

The data this model consumes and produces when executed.

Parameters

Name	Default	Unit	Meaning
ligand_id	MeAsp	Not recorded	External ligand sensed by the receptor cluster.
initial_ligand	5	millimolar	concentration
n_Tar	6	Not recorded	Number of Tar receptors in a cluster.
n_Tsr	12	Not recorded	Number of Tsr receptors in a cluster.
k_meth	0.0625	per second	Catalytic rate of receptor methylation.
k_demeth	0.0714	per second	Catalytic rate of receptor demethylation.
n_flagella	4	Not recorded	Number of flagella in the flagella motor model.
time_step	0.01	second	Process integration timestep.
p_K	1	Not recorded	Relative membrane permeability of potassium.
p_Na	0.05	Not recorded	Relative membrane permeability of sodium.

Initial conditions

Name	Value	Unit
initial_internal_ions	`{"K":300,"Cl":10,"Na":10,"PROTON":0}`	millimole
initial_external_ions	`{"K":5,"T":310.15,"Cl":110,"Na":145,"PROTON":0}`	millimole

Data inputs

Name	Format	Required	Purpose
flagella_chromosome_fasta	FASTA	Required	Chromosome sequence data used by flagella gene-expression configuration.
reference_data	CSV	Optional	Reference CSV data for expression and transport/metabolism experiments.

Outputs

Name	Quantity	Unit	Format
emitted_timeseries	concentration	Not recorded	CSV

Experiment protocol

Vivarium experiments run fixed-timestep process, composite, and agent-environment simulations; individual scripts commonly use 0.01–10 second timesteps and durations from seconds to thousands of seconds.

Timestep: 0.01 {'value': 'second', 'iri': 'http://purl.obolibrary.org/obo/UO_0000010', 'ontology_label': 'second', 'ontology': 'uo', 'mapping_confidence': 'high'}
Duration: 500 {'value': 'second', 'iri': 'http://purl.obolibrary.org/obo/UO_0000010', 'ontology_label': 'second', 'ontology': 'uo', 'mapping_confidence': 'high'}
Observables: chemoreceptor_activityCheY_Pmotile_statePMFvolumemass

Runtime environment, dependencies, and compute requirements.

Language: Python
Environment: pip

Vivarium advances simulations with fixed timesteps. Some larger experiments require MongoDB when configured with a database emitter.

Compute requirements

GPU: Not required
Parallelism: single

Dependencies

runtime: vivarium-cell ==0.0.23
vivarium-core ==0.0.34
pymunk ==5.6.0
numpy
scipy
system: MongoDB

Containers

docker · docker.io/mismplatform/envbuild@sha256:1010099a1eaf6d68e76ea5f143b4b1bdc437ac5248531445feff3cfa91ba72c6 · docker.io

Image approved · envbuild-agent · Oct 2026

Entry points

python chemotaxis/processes/chemoreceptor_cluster.py
Run the chemoreceptor cluster process analyses and plots.
python chemotaxis/processes/coarse_motor.py
Run the coarse motor variable-receptor analysis and plot.
python chemotaxis/processes/flagella_motor.py
Run the flagella motor variable-flagella simulation and plots.
python chemotaxis/processes/membrane_potential.py
Run the membrane-potential simulation and plot.
python chemotaxis/composites/chemotaxis_flagella.py
Run variable-flagella or gene-expression chemotaxis composite modes.
--variable
Run variable-flagella mode; mutually exclusive with --expression.
--expression
Run expression mode; mutually exclusive with --variable.
--flagella
Number of flagella.
python chemotaxis/composites/chemotaxis_master.py
Run the most complete chemotaxis master composite, or save its topology.
--topology
Save the composite topology instead of running the simulation.
python chemotaxis/composites/chemotaxis_minimal.py
Run the receptor-and-motor minimal chemotaxis composite.
python chemotaxis/composites/flagella_expression.py
Run flagella expression, optionally coupled to metabolism.
--metabolism
Run expression coupled to metabolism.
--expression
Run expression-only mode.
python chemotaxis/composites/transport_metabolism.py
Run transport, metabolism, and gene-expression simulation.
--shift
Run the glucose/lactose shift condition.
python chemotaxis/experiments/paper_experiments.py
Run paper experiments through the experiment control workflow.

Tests

pytestpytest

Artifacts stored with this model.

Download all (zip)

1.1 KB
170 B
3.0 KB
1.1 KB
5 B
855 B

Identifiers and integrity.

Metadata review: Approved · 1da614bf-946a-4400-a0be-4fd0f1d00f74 · Oct 2026

Contacts: Eran Agmon · eagmon@stanford.edu
Ryan Spangler · ryan.spangler@gmail.com
External IDs: url:https://github.com/vivarium-collective/vivarium-chemotaxis

Model characterization

Biology

Inputs & outputs