# paytonco/multicellular architecture

> Architecture diagram of the GitHub repository paytonco/multicellular, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paytonco/multicellular
- Repository: https://github.com/paytonco/multicellular
- Video tour (about a minute): https://gitdiagram.com/paytonco/multicellular/video

## Overview

multicellular is an agent-based bacterial-colony simulation framework. Users configure cells, reaction networks, and a shared environment, then run a Simulation that advances colony behavior and records cell and field histories; users can visualize colony or field state and run independent replicates. The main domain stages are intracellular chemistry and growth/division, colony mechanics and cell-field exchange, environmental diffusion/reaction, and time-stepped history/analysis. Source excerpts are partial, so links for documented but unsampled behavior are limited to supported module-level relationships.

Main entry points: [`src/multicellular/core/simulation.py`](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/simulation.py) (Simulation), [`src/multicellular/core/reactions.py`](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/reactions.py) (Reaction network), [`src/multicellular/utils/parallel.py`](https://github.com/paytonco/multicellular/blob/master/src/multicellular/utils/parallel.py) (Replicate runner), [`src/multicellular/core/colony.py`](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/colony.py) (Colony)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Biological model"]
  node_cell["Cell<br/>[cell.py]"]
  node_reaction["Reaction<br/>[reactions.py]"]
  node_network["Reaction network<br/>[reactions.py]"]
  node_environment["Environment and fields<br/>[environment.py]"]
end

subgraph group_dynamics["Colony dynamics"]
  node_colony["Colony<br/>[colony.py]"]
end

subgraph group_execution["Run management"]
  node_simulation["Simulation<br/>[simulation.py]"]
  node_replicates["Replicate runner<br/>[parallel.py]"]
end

subgraph group_analysis["Results and visualization"]
  node_history["Recorded history<br/>[simulation.py]"]
  node_visualization["Plots and animations<br/>[visualization.py]"]
end

node_user(("Researcher"))
node_results["Simulation results"]

node_user -->|"configures"| node_cell
node_user -->|"configures"| node_network
node_user -->|"configures"| node_environment
node_user -->|"starts"| node_simulation
node_user -->|"requests replicates"| node_replicates
node_cell -->|"simulates chemistry"| node_network
node_network -->|"evaluates rates"| node_reaction
node_environment -->|"steps field reactions"| node_network
node_colony -->|"steps, divides, moves"| node_cell
node_colony -->|"diffuses; exchanges chemicals"| node_environment
node_simulation -->|"advances"| node_colony
node_simulation -->|"records states"| node_history
node_simulation -->|"requests rendering"| node_visualization
node_visualization -->|"renders plots and animations"| node_results
node_simulation -->|"returns history"| node_results
node_replicates -->|"runs independent simulations"| node_simulation
node_replicates -->|"combines replicate histories"| node_results

click node_cell "https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/cell.py"
click node_reaction "https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/reactions.py"
click node_network "https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/reactions.py"
click node_environment "https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/environment.py"
click node_colony "https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/colony.py"
click node_simulation "https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/simulation.py"
click node_replicates "https://github.com/paytonco/multicellular/blob/master/src/multicellular/utils/parallel.py"
click node_history "https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/simulation.py"
click node_visualization "https://github.com/paytonco/multicellular/blob/master/src/multicellular/utils/visualization.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cell,node_reaction,node_network,node_environment toneBlue
class node_colony toneAmber
class node_simulation,node_replicates toneMint
class node_history,node_visualization toneRose
class node_user,node_results toneIndigo
```

## Components

### Biological model

- [Cell](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/cell.py): `src/multicellular/core/cell.py`
- [Reaction](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/reactions.py): `src/multicellular/core/reactions.py`
- [Reaction network](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/reactions.py): `src/multicellular/core/reactions.py`
- [Environment and fields](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/environment.py): `src/multicellular/core/environment.py`

### Colony dynamics

- [Colony](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/colony.py): `src/multicellular/core/colony.py`

### Run management

- [Simulation](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/simulation.py): `src/multicellular/core/simulation.py`
- [Replicate runner](https://github.com/paytonco/multicellular/blob/master/src/multicellular/utils/parallel.py): `src/multicellular/utils/parallel.py`

### Results and visualization

- [Recorded history](https://github.com/paytonco/multicellular/blob/master/src/multicellular/core/simulation.py): `src/multicellular/core/simulation.py`
- [Plots and animations](https://github.com/paytonco/multicellular/blob/master/src/multicellular/utils/visualization.py): `src/multicellular/utils/visualization.py`

### Other components

- **Researcher**
- **Simulation results**

## Connections

- Researcher → Cell: configures
- Researcher → Reaction network: configures
- Researcher → Environment and fields: configures
- Researcher → Simulation: starts
- Researcher → Replicate runner: requests replicates
- Cell → Reaction network: simulates chemistry
- Reaction network → Reaction: evaluates rates
- Environment and fields → Reaction network: steps field reactions
- Colony → Cell: steps, divides, moves
- Colony → Environment and fields: diffuses; exchanges chemicals
- Simulation → Colony: advances
- Simulation → Recorded history: records states
- Simulation → Plots and animations: requests rendering
- Plots and animations → Simulation results: renders plots and animations
- Simulation → Simulation results: returns history
- Replicate runner → Simulation: runs independent simulations
- Replicate runner → Simulation results: combines replicate histories