adicksonlab/openrxn

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.