viva-tumor-tcell
A multiscale agent-based tumor microenvironment model with tumor, T-cell, and dendritic-cell processes, diffusing IFNg and tumor-debris fields, cell-cell neighbor exchange, and phenotype conversion/exhaustion dynamics.
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
- Proteins / genes
- Not recorded
The data this model consumes and produces when executed.
Parameters
| Name | Default | Unit | Meaning |
|---|---|---|---|
| n_tumors | 60 | dimensionless | tumor cell count |
| n_tcells | 6 | dimensionless | T-cell count |
| pd1_positive_frac | 0.25 | dimensionless | initial fraction |
| tumor_pdl1n_frac | 0.9 | dimensionless | initial fraction |
| seed | 1 | dimensionless | Random-number-generator seed. |
Initial conditions
| Name | Value | Unit |
|---|---|---|
| IFNg | zero 40 x 40 field | nanogram per milliliter |
| initial_cell_population | 60 tumor cells and 6 T cells by default | dimensionless |
Outputs
| Name | Quantity | Unit | Format |
|---|---|---|---|
| snapshot_time_series | cell and field state | second | JSON |
| study_figures | Plot | Not recorded | HTML |
| scale_efficacy_results | time series | Not recorded | JSON |
Experiment protocol
Vivarium/process-bigraph composites advance in fixed 60-second ticks; canonical headline runs use 300 steps and study-specific runs use replicate seeds.
- Timestep
- 60 second
- Duration
- 18000 second
- Observables
- tumor_countpdl1p_fractionpd1p_fractionifng_maxpopulation_countsdeathsdivisions
Runtime environment, dependencies, and compute requirements.
- Language
- Python >=3.11
- Environment
- pip
Vivarium/process-bigraph composites are exposed as Python APIs; the six self-launching modules above were enumerated structurally. The canonical composite API is documented in README.md:47-55.
Compute requirements
- GPU
- Not required
- Parallelism
- single
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:5a02cc764b89a5692db49b85a8618b1d5e618fc12962d0ed195da17eb65d2e3c · docker.io
Image approved · envbuild-agent · Oct 2026
Entry points
python scripts/scale_efficacy.pyRun the larger-scale efficacy probe and write scalar time series.
- n_tumors
- n_tcells
- steps
- bounds
- nbins
- nseeds
python scripts/regen_spatial_gifs.pyRegenerate study spatial visualizations.
- which
python scripts/persist_study_runs.pyPersist representative study runs into study databases.
python studies/tumor-microenvironment/sims/run.pyRun the headline tumor microenvironment experiment and figure suite.
python studies/efficacy-at-scale/sims/run.pyRun the efficacy-at-scale study.
python studies/killing-assay-cytotoxicity/sims/run.pyRun the killing-assay cytotoxicity study.
python studies/phenotype-conversion/sims/run.pyRun the IFNg-driven phenotype-conversion study.
python studies/tcell-exhaustion/sims/run.pyRun the T-cell exhaustion study.
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.commaintainer · Vivarium Collective
- Eran Agmon · agmon.eran@gmail.com
- External IDs
- url:https://github.com/vivarium-collective/viva-tumor-tcell