viva-tumor-tcell
A multiscale agent-based model of the tumor microenvironment with tumor cells, T cells, dendritic cells, diffusing IFNg and tumor-debris fields, and cell-cell neighbor exchange.
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
- Not recorded
- Infectious agents
- Not recorded
- Health conditions
- Not recorded
- Biological processes
- Molecular entities
- Not recorded
- Proteins / genes
- Not recorded
The data this model consumes and produces when executed.
Parameters
| Name | Default | Unit | Meaning |
|---|---|---|---|
| n_tumors | 60 | dimensionless | cell count |
| n_tcells | 6 | dimensionless | cell count |
| pd1_positive_frac | 0.25 | dimensionless | Fraction of T cells starting PD1+; headline conditions use 0.25 and 0.75 |
| tumor_pdl1n_frac | 0.9 | dimensionless | Fraction of tumors starting PDL1n |
| bounds | [400,400] | micrometer | Two-dimensional chamber bounds |
| n_bins | [40,40] | dimensionless | Number of bins in the 2D field grid |
| depth | 15 | micrometer | Field depth |
| seed | 1 | dimensionless | Random-number-generator seed |
| timestep | 60 | second | Composite tick interval |
| IFNg_threshold | 15000 | dimensionless | concentration |
Initial conditions
| Name | Value | Unit |
|---|---|---|
| cells | initialized tumor, T-cell, and optional dendritic-cell agents | Not recorded |
| fields.IFNg | zero-valued 2D grid | nanogram per milliliter |
Outputs
| Name | Quantity | Unit | Format |
|---|---|---|---|
| population_timeseries | cell count | dimensionless | JSON |
| spatial_field_and_cell_snapshots | spatial specification | micrometer | HTML |
| scale_efficacy_results | cell count | dimensionless | JSON |
Experiment protocol
Canonical study runs fixed 60-second ticks for 600 ticks (approximately 10 hours); the larger-scale study uses 1500 ticks and 3 seeds according to its committed configuration.
- Timestep
- 60 {'value': 'second', 'iri': 'http://purl.obolibrary.org/obo/UO_0000010', 'ontology_label': 'second', 'ontology': 'uo', 'mapping_confidence': 'high'}
- Duration
- 10 {'value': 'hour', 'iri': None, 'ontology': 'uo', 'mapping_confidence': 'none'}
- Observables
- tumor population by stateT-cell population by statedeaths by typedivisionspeak IFNgspatial snapshots
Runtime environment, dependencies, and compute requirements.
- Language
- Python >=3.11
- Environment
- native
Vivarium-style process-bigraph composite with fixed 60-second ticks; the repository also exposes Python APIs through viva_tumor_tcell.run and composite generators.
Compute requirements
- GPU
- Not required
- Parallelism
- single
- Typical runtime
- 30 minutes
Dependencies
- runtime
- bigraph-schema >=0.0.60
- process-bigraph >=1.8.5
- viva-munk
- numpy
- scipy
- plotly
- optional
- pytest
- matplotlib
Containers
- docker · docker.io/mismplatform/envbuild@sha256:e9f84fa002b916ec0f7d7306d79739315dbe586ff22351a2c79349c86a7c0664 · docker.io
Image approved · envbuild-agent · Oct 2026
Entry points
python studies/tumor-microenvironment/sims/run.pyRun the canonical headline tumor-microenvironment experiment and render its figure suite
python studies/efficacy-at-scale/sims/run.pyRender the larger-scale efficacy analysis from committed data
python studies/killing-assay-cytotoxicity/sims/run.pyRun the T-cell killing-assay cytotoxicity study
python studies/phenotype-conversion/sims/run.pyRun the IFNg-driven tumor phenotype-conversion study
python studies/tcell-exhaustion/sims/run.pyRun the T-cell exhaustion study
python scripts/persist_study_runs.pyPersist representative study runs
python scripts/regen_spatial_gifs.py <which>Regenerate spatial GIF visualizations
- which
- Study selector
python scripts/scale_efficacy.pyRun the heavy larger-scale efficacy simulation and write committed results
Tests
pytestpytest -q
Artifacts stored with this model.
Identifiers and integrity.
- Metadata review
- Approved · 1da614bf-946a-4400-a0be-4fd0f1d00f74 · Oct 2026
- Contacts
- Eran Agmon · agmon.eran@gmail.com
- External IDs
- url:https://github.com/vivarium-collective/viva-tumor-tcell