# viva-tumor-tcell — port plan

Porting [tumor-tcell](https://github.com/vivarium-collective/tumor-tcell) (a
vivarium-1.0 / vivarium-core ABM of the tumor microenvironment, from Hickey,
Agmon et al., *Cell Systems*) to a process-bigraph "viva-" workspace, using
**viva-munk** for the collision physics and porting everything else faithfully.

## Decisions (locked with the user)

- **Scope: tractable-faithful.** Port every experiment *type* (the 3 PD1+
  conditions, the 4-condition in-vitro killing/cytotoxicity assay, the lymph
  node) plus all plots, and run the committed studies at reduced scale
  (fewer cells / shorter time) that reproduces the qualitative results. Each
  study documents the exact params to scale to the paper figure; full-scale
  runs are a follow-up (mini/overnight).
- **Fields: port tumor-tcell's own `Fields`/`LocalField` faithfully** — its
  exact diffusion rates (IFNg 1.25e-3 cm²/day, debris 0.0864 cm²/day) and
  decay (IFNg 4.5 h e-fold). viva-munk is used ONLY for multibody collisions.

## Architecture

tumor-tcell's `Neighbors` process did **two** jobs: pymunk circle collisions,
**and** the biological neighbor-exchange (`present`/`accept`/`transfer`/
`receive`, "T-cell picks nearest tumor, tumor collects all T-cells"). viva-munk's
`PymunkProcess` covers only the collisions. So:

- **`TumorTcellPhysics`** (this repo) wraps a `viva_munk` `PymunkProcess`
  instance as its collision engine — builds flat pymunk bodies from the cells,
  steps viva-munk's real pymunk space (walls, jitter, substeps, collisions),
  and **also** performs the ported neighbor-exchange bookkeeping.
- Migration model is preserved: each tick a cell's velocity is set to
  `speed × random_direction` (tumor-tcell's persistent-random-walk migration),
  then integrated by the physics engine.

### Store layout (deliberate translation)

tumor-tcell nested each cell into `internal` / `boundary` / `neighbors` /
`globals` sub-stores. Here each cell is a **flat `tumor_tcell_agent`** with those
ports flattened into namespaced keys (`cell_state`, `internal_IFNg`, `speed`,
`present_TCR`, `accept_MHCI`, `receive_cytotoxic`, `exchange`, `local`, …). The
biology (equations, parameters, transitions, rates) is preserved exactly; only
the store shape changes, matching viva-munk's flat-agent + per-cell-process idiom.

Per-cell behavior processes (`TumorCellProcess`, `TCellProcess`) are embedded in
each agent (key `behavior`) and read the whole `cells` map via `agent_id`, like
viva-munk's `GrowDivide`. Division is done by the process writing `_add`/`_remove`
into the `cells` map (replaces vivarium's `MetaDivision` + `Remove` + `_divider`).

### Field consolidation

tumor-tcell split field handling across `Fields` (diffuse/decay + sample local
into cells) and `LocalField` (deposit each cell's `exchange` counts into the
field bin, reset exchange). Ported as **one** `DiffusionField` process per tick:
(1) deposit exchange → field bins (count→concentration via Avogadro/MW/bin-vol),
reset exchange; (2) diffuse + decay; (3) sample each cell's local concentration.
Same math, fewer moving parts.

## Faithfulness notes / known quirks

- Original `t_cell.py` decrements the stockpile on transfer by writing key
  `internal.cytotoxic_packets` (line ~513) which does not match its schema key
  `total_cytotoxic_packets` — so in the original the stockpile is never actually
  drawn down on transfer. We port the **intended** semantics (decrement
  `total_cytotoxic_packets`) and note the difference.

## Milestones

- **M1 — core seam (DONE, `ec104be`):** `tumor_tcell_agent` schema;
  `TumorCellProcess`, `TCellProcess`, `DiffusionField`, `TumorTcellPhysics`;
  `build_core()`; `tumor_tcell_basic` generator; tests for the physics swap,
  neighbor exchange, IFNg switch, killing.
- **M2 — full environment + processes (DONE, `778db13`):** `DendriticCellProcess`
  + tumor_debris field; generators `tumor_microenvironment` (CODEX layout),
  `killing_assay`, `lymph_node`. Directional trends validated.
- **M3 — investigation + studies + viz + publish (DONE):** the
  `tumor-tcell-showcase` investigation, three studies each with a canonical
  `sims/run.py`, interactive Plotly figures, runs recorded to `.pbg/runs.jsonl`,
  and a published read-only workbench bundle.
- **M4 — rigor pass / replicate seeds (DONE):** re-ran every study across 6
  seeds. The single-seed M3 verdicts were partly luck: tumor-count efficacy
  (25%<75% ordering) and the PDL1p conversion *fraction* do NOT separate from
  growth noise at tractable scale. Restructured to lead with the **robust**
  mechanisms — T-cell exhaustion (6/6), IFNg secretion (6/6), positive
  cytotoxicity (5/6) — reported as mean ± std with band charts; the efficacy
  study was renamed `tcell-efficacy-pd1` → `tcell-exhaustion`; scale-limited
  claims are documented, not gated.

## Remaining / future

- Replicate seeds + paper-scale runs (1200 cells, 3 days) on the mini for
  quantitative claims; turn directional readouts into hard gates.
- Cross-compartment lymph-node recirculation (the WIP arm; here all cells share
  one compartment — DC activation is modeled, T-cell LN↔tumor `_move` is not).
- Per-cell death/division timeseries + phylogeny-colored snapshots.