Architecture

┌───────────────────────────────────────┐
│  Python API (bngsim)                  │  pip install bngsim
│  Model, Simulator, Result             │  NumPy arrays, logging
├───────────────────────────────────────┤
│  pybind11 Binding Layer               │  GIL release during sim
│  _bngsim_core.cpp                     │  Exception translation
├───────────────────────────────────────┤
│  C++ Engine (libbngsim)               │  Re-entrant, instance-based
│  NetworkModel, CvodeSimulator         │  No globals, no file I/O
│  SsaSimulator                         │  No stdout, no exit()
├───────────────────────────────────────┤
│  SUNDIALS v7.x (vendored)             │  CVODE (adaptive BDF)
│  ExprTk (vendored, header-only)       │  Rate law expressions
└───────────────────────────────────────┘

Key design decisions

1. SUNDIALS v7.x with SUNContext for re-entrancy (not the ancient 2.4.0 bundled in BNG)

2. ExprTk replaces muParser — header-only, bytecode-compiled, 5 backward-compat aliases

3. Instance-based state — no globals. Multiple models/simulators coexist safely

4. Static linking — the wheel is self-contained (SUNDIALS linked statically into the extension)

5. Pluggable loaders — .net, Antimony (.ant), and SBML (.xml) via ModelBuilder