stochmod 0.1.0

Constrained tau-leap-like stochastic simulator for SBML models

stochmod

Constrained tau-leap-like stochastic simulator for SBML models, adapted from SPARCED-style simulation.

stochmod ingests SBML in Python, generates per-model C propensity code, compiles it into a cached shared library, and runs simulation through a pybind11 core with sparse CSC stoichiometry.

Install

pip install stochmod

For development from a clone:

pip install -e ".[dev]"

Requirements

• Python 3.10+
• A C compiler (gcc, clang, or MSVC cl) for first-time model builds (per-model codegen at runtime)
• CMake 3.18+ only when building the Python extension from source (binary wheels from PyPI already include it)

Quickstart

from stochmod import StochasticModule

mod = StochasticModule("model.xml")
traj = mod.run(start=0.0, stop=10.0, step=0.1)  # shape: (n_steps, n_species)

print(mod.species_names)
print(mod.parameter_ids)
print(mod.initial_state)
print(mod.parameter_values)

mod.update("k1", 0.5)
mod.set_state([100.0, 0.0])
mod.set_parameters([0.1, 1.0])

Trajectory columns follow mod.species_names index order. Row 0 is the initial state.

Cache

Compiled model libraries are stored under:

• $HOME/.cache/stochmod/<hash>/ (default)
• or a custom cache root via StochasticModule(sbml_path, cache_dir="/path/to/cache/root")

Each cache entry contains sparse stoichiometry arrays, generated C sources, and libmodel.so / libmodel.dll / libmodel.dylib.

SBML support (v1)

• SBML Level 3 Version 2 kinetic models
• Species, parameters, compartments, reactions with MathML kinetic laws
• Species amounts used as-is from SBML (initialAmount or initialConcentration * compartment size)

Not supported in v1: events, assignment/rate rules, algebraic constraints.

API

Method / property	Description
StochasticModule(sbml_path, cache_dir=None, verbose=None)	Parse SBML, build/load cached model
run(start, stop, step)	Simulate; returns [n_steps, n_species] NumPy array
update(key, val)	Update species, parameter, or compartment by SBML id
set_state(vector)	Replace all species amounts
set_parameters(vector)	Replace all parameter values
species_names	Species ids in column order
parameter_ids	Global parameter ids
initial_state	Current species amount vector
parameter_values	Current parameter vector

Tests

pytest

Publishing

See PUBLISHING.md for PyPI release steps (wheels CI + Trusted Publishing).

License

MIT — see LICENSE.txt.