# adicksonlab/openrxn architecture

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

- Interactive diagram: https://gitdiagram.com/adicksonlab/openrxn
- Repository: https://github.com/adicksonlab/openrxn

## Overview

1. **What this repository is**
OpenRXN is a Python library for building and simulating chemical reaction networks with compartment structure. The core architecture separates **domain modeling** (species, reactions, compartments, connectivity) from **simulation engines** (stochastic Gillespie and deterministic ODE), with examples showing how to assemble diffusion, reaction-diffusion, and birth/death systems.

2. **Primary abstraction layer: compartments and arrays**
The `src/openrxn/compartments` package is the spatial/discrete topology layer. It appears to define:
- a base compartment abstraction,
- identifier utilities (`ID.py`),
- array-based compartment layouts (`arrays.py`) for 1D/2D/3D grids.
This is the main boundary for representing “where” chemistry happens, independent of how it is simulated.

3. **Connectivity between compartments**
`connections.py` is the coupling layer that links compartments. This is where diffusion-like transport or adjacency relationships likely live. Architecturally, it sits between the spatial compartment model and the reaction/simulation layers, enabling a graph of connected reaction domains.

4. **Reaction and model definition**
`reactions.py` and `model.py` define the chemistry itself: species, reaction rules, and the assembled network/model object. `model_templates.py` likely provides convenience constructors for common patterns such as reaction-diffusion setups or standard kinetic motifs. This layer is the “source of truth” for system structure before simulation begins.

5. **Numerical system engines**
The `src/openrxn/systems` package is the execution layer. It contains two major simulation modes:
- `GillespieSystem.py` for stochastic discrete-event simulation,
- `ODESystem.py` for deterministic rate-equation integration.
`system.py` likely provides shared orchestration and interfaces, while `state.py` holds the evolving concentrations/counts and `deriv.py` likely computes ODE right-hand sides.

6. **How model data flows into simulation**
The normal flow is: define compartments/species/reactions in the model layer, connect compartments, then instantiate a system backend that transforms the model into a runtime state representation. The Gillespie path uses event-driven state updates, while the ODE path converts the same structural model into derivative calculations suitable for SciPy-style integration.

7. **Diffusion and transport handling**
`propagators.py` is likely the place where motion or transfer between compartments is translated into update rules or probability/flux operators. In practice, this is the bridge between a compartment graph and the two simulation backends, especially for reaction-diffusion examples.

8. **Reporting and observability**
`systems/reporters.py` suggests a results/output layer that records trajectories, time series, and possibly derived quantities. This is the boundary where internal simulation state becomes analyzable output, likely feeding pandas/numpy arrays and plotting workflows in the examples.

9. **Runtime and library dependencies that matter**
The architecture depends on:
- **Pint** for unit-aware quantities throughout the model,
- **NumPy/SciPy** for numerical state storage and ODE integration,
- **NetworkX** for graph visualization of compartment connectivity,
- **pandas/matplotlib** for analysis and plotting.
These are not incidental; they shape how state is represented, solved, and inspected.

10. **Examples as integration points**
The `examples/` directory demonstrates the intended composition patterns:
- pure diffusion,
- reaction-diffusion,
- Gillespie stochastic systems,
- birth/death kinetics,
- degradation ODEs,
- membrane slab modeling.
These examples show that the package is designed as a modeling toolkit rather than a single-purpose solver.

11. **Likely architectural boundaries**
A useful diagram should show four clear zones:
- **Domain model**: compartments, reactions, model assembly,
- **Topology/connectivity**: arrays and connection graph,
- **Simulation engines**: stochastic vs deterministic backends,
- **Outputs/analysis**: reporters, plotting, and saved trajectories.
The key design idea is that the same chemical network can be executed by different solvers without changing the model definition.

12. **Packaging and layout**
The project uses a standard `src/` layout with a single `openrxn` package and a top-level `setup.py`, indicating a distributable library rather than an application. That means the architecture is centered on reusable modules and example scripts, not a long-running service or UI.

Main entry points: [`src/openrxn/model.py`](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/model.py) (Model), [`src/openrxn/systems/GillespieSystem.py`](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/GillespieSystem.py) (Gillespie), [`src/openrxn/systems/ODESystem.py`](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/ODESystem.py) (ODE), [`src/openrxn/compartments/compartment.py`](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/compartments/compartment.py) (Compartment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_domain["Domain model"]
  node_reactions["Reactions<br/>reaction rules<br/>[reactions.py]"]
  node_model["Model<br/>network assembly<br/>[model.py]"]
  node_templates["Templates<br/>model builders<br/>[model_templates.py]"]
end

subgraph group_topology["Topology"]
  node_compartment["Compartment<br/>base abstraction<br/>[compartment.py]"]
  node_ids["IDs<br/>identifier utils<br/>[ID.py]"]
  node_arrays["Arrays<br/>grid layouts<br/>[arrays.py]"]
  node_connections["Connections<br/>coupling graph<br/>[connections.py]"]
end

subgraph group_runtime["Simulation runtime"]
  node_propagators["Propagators<br/>transport operators<br/>[propagators.py]"]
  node_system["System<br/>runtime base<br/>[system.py]"]
  node_state["State<br/>[state.py]"]
  node_deriv["Derivatives<br/>ode rhs<br/>[deriv.py]"]
  node_gillespie["Gillespie<br/>stochastic solver<br/>[GillespieSystem.py]"]
  node_ode["ODE<br/>deterministic solver<br/>[ODESystem.py]"]
end

subgraph group_outputs["Outputs"]
  node_reporters["Reporters<br/>results capture<br/>[reporters.py]"]
end

subgraph group_examples["Examples"]
  node_diffusion_ex["Diffusion<br/>example<br/>[1D_diffusion.py]"]
  node_rd_ex["Reac-diff<br/>example"]
  node_gillespie_ex["Stochastic<br/>example"]
  node_ode_ex["ODE demo<br/>example<br/>[degradation_ode.py]"]
end

node_arrays -->|"builds"| node_compartment
node_ids -->|"names"| node_compartment
node_compartment -->|"links"| node_connections
node_connections -->|"drives"| node_propagators
node_reactions -->|"defines"| node_model
node_compartment -->|"contains"| node_model
node_connections -->|"couples"| node_model
node_templates -->|"creates"| node_model
node_model -->|"loads"| node_system
node_system -->|"manages"| node_state
node_model -->|"executes via"| node_gillespie
node_model -->|"executes via"| node_ode
node_gillespie -->|"updates"| node_state
node_ode -->|"evaluates"| node_deriv
node_deriv -->|"reads"| node_state
node_propagators -->|"feeds"| node_gillespie
node_propagators -->|"feeds"| node_ode
node_gillespie -->|"emits"| node_reporters
node_ode -->|"emits"| node_reporters
node_diffusion_ex -->|"demonstrates"| node_arrays
node_diffusion_ex -->|"demonstrates"| node_connections
node_rd_ex -->|"demonstrates"| node_model
node_gillespie_ex -->|"demonstrates"| node_gillespie
node_ode_ex -->|"demonstrates"| node_ode

click node_compartment "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/compartments/compartment.py"
click node_ids "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/compartments/ID.py"
click node_arrays "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/compartments/arrays.py"
click node_connections "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/connections.py"
click node_reactions "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/reactions.py"
click node_model "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/model.py"
click node_templates "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/model_templates.py"
click node_propagators "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/propagators.py"
click node_system "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/system.py"
click node_state "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/state.py"
click node_deriv "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/deriv.py"
click node_gillespie "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/GillespieSystem.py"
click node_ode "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/ODESystem.py"
click node_reporters "https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/reporters.py"
click node_diffusion_ex "https://github.com/adicksonlab/openrxn/blob/master/examples/1D_diffusion.py"
click node_rd_ex "https://github.com/adicksonlab/openrxn/blob/master/examples/1D_reac_diffusion.py"
click node_gillespie_ex "https://github.com/adicksonlab/openrxn/blob/master/examples/Gillespie_AB_system.py"
click node_ode_ex "https://github.com/adicksonlab/openrxn/blob/master/examples/degradation_ode.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_reactions,node_model,node_templates toneBlue
class node_compartment,node_ids,node_arrays,node_connections toneAmber
class node_propagators,node_system,node_state,node_deriv,node_gillespie,node_ode toneMint
class node_reporters toneRose
class node_diffusion_ex,node_rd_ex,node_gillespie_ex,node_ode_ex toneIndigo
```

## Components

### Domain model

Chemical network definitions and assembly.

- [Reactions](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/reactions.py): reaction rules · Species and reaction definitions for the chemical network. · `src/openrxn/reactions.py`
- [Model](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/model.py): network assembly · Assembles the full reaction network and compartment structure. · `src/openrxn/model.py`
- [Templates](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/model_templates.py): model builders · Convenience constructors for common system patterns. · `src/openrxn/model_templates.py`

### Topology

Compartment structure and connectivity.

- [Compartment](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/compartments/compartment.py): base abstraction · Core compartment object representing a reaction domain. · `src/openrxn/compartments/compartment.py`
- [IDs](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/compartments/ID.py): identifier utils · Helpers for compartment and model identifiers. · `src/openrxn/compartments/ID.py`
- [Arrays](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/compartments/arrays.py): grid layouts · Array-based 1D/2D/3D compartment layouts. · `src/openrxn/compartments/arrays.py`
- [Connections](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/connections.py): coupling graph · Links compartments and encodes adjacency or transport. · `src/openrxn/connections.py`

### Simulation runtime

Shared state and solver backends.

- [Propagators](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/propagators.py): transport operators · Movement and transfer rules between compartments. · `src/openrxn/propagators.py`
- [System](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/system.py): runtime base · Shared simulation orchestration and interfaces. · `src/openrxn/systems/system.py`
- [State](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/state.py): runtime state · Evolving counts or concentrations during simulation. · `src/openrxn/systems/state.py`
- [Derivatives](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/deriv.py): ode rhs · Computes time derivatives for deterministic simulation. · `src/openrxn/systems/deriv.py`
- [Gillespie](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/GillespieSystem.py): stochastic solver · Discrete-event stochastic simulation backend. · `src/openrxn/systems/GillespieSystem.py`
- [ODE](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/ODESystem.py): deterministic solver · Deterministic rate-equation integration backend. · `src/openrxn/systems/ODESystem.py`

### Outputs

Trajectory capture and analysis boundaries.

- [Reporters](https://github.com/adicksonlab/openrxn/blob/master/src/openrxn/systems/reporters.py): results capture · Records trajectories and outputs analysis-ready data. · `src/openrxn/systems/reporters.py`

### Examples

Usage patterns demonstrating the library.

- [Diffusion](https://github.com/adicksonlab/openrxn/blob/master/examples/1D_diffusion.py): example · Pure diffusion and transport example. · `examples/1D_diffusion.py`
- [Reac-diff](https://github.com/adicksonlab/openrxn/blob/master/examples/1D_reac_diffusion.py): example · Reaction-diffusion example systems. · `examples/1D_reac_diffusion.py`
- [Stochastic](https://github.com/adicksonlab/openrxn/blob/master/examples/Gillespie_AB_system.py): example · Gillespie-driven chemical system example. · `examples/Gillespie_AB_system.py`
- [ODE demo](https://github.com/adicksonlab/openrxn/blob/master/examples/degradation_ode.py): example · Deterministic degradation and birth/death examples. · `examples/degradation_ode.py`

## Connections

- Arrays → Compartment: builds · Array layouts instantiate compartment instances.
- IDs → Compartment: names · Identifier utilities support compartment identity.
- Compartment → Connections: links · Compartments participate in connectivity graphs.
- Connections → Propagators: drives · Connectivity is converted into transport logic.
- Reactions → Model: defines · Reaction rules are assembled into the model.
- Compartment → Model: contains · The model includes compartment structure.
- Connections → Model: couples · The model stores inter-compartment coupling.
- Templates → Model: creates · Templates generate common model configurations.
- Model → System: loads · Systems consume the assembled model.
- System → State: manages · The runtime owns evolving simulation state.
- Model → Gillespie: executes via · Stochastic backend runs the same structural model.
- Model → ODE: executes via · Deterministic backend runs the same structural model.
- Gillespie → State: updates · Event-driven state transitions.
- ODE → Derivatives: evaluates · ODE solver uses derivative calculations.
- Derivatives → State: reads · Derivative computation uses current state.
- Propagators → Gillespie: feeds · Transport rules can inform stochastic updates.
- Propagators → ODE: feeds · Transport rules can inform deterministic flux terms.
- Gillespie → Reporters: emits · Stochastic trajectories are recorded for analysis.
- ODE → Reporters: emits · Deterministic trajectories are recorded for analysis.
- Diffusion → Arrays: demonstrates · Shows grid-based compartment layouts.
- Diffusion → Connections: demonstrates · Shows diffusion coupling between compartments.
- Reac-diff → Model: demonstrates · Shows reaction-diffusion model assembly.
- Stochastic → Gillespie: demonstrates · Shows stochastic execution path.
- ODE demo → ODE: demonstrates · Shows deterministic execution path.