Metadata-Version: 2.2
Name: stochmod
Version: 0.1.0
Summary: Constrained tau-leap-like stochastic simulator for SBML models
Keywords: SBML,stochastic,tau-leap,systems-biology,simulation
Author-Email: "Jonah R. Huggins" <jonahrileyhuggins@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Project-URL: Homepage, https://github.com/JonahRileyHuggins/StochMod
Project-URL: Repository, https://github.com/JonahRileyHuggins/StochMod
Project-URL: Issues, https://github.com/JonahRileyHuggins/StochMod/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: sympy>=1.12
Requires-Dist: python-libsbml>=5.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Description-Content-Type: text/markdown

# 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

```bash
pip install stochmod
```

For development from a clone:

```bash
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

```python
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

```bash
pytest
```

## Publishing

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

## License

MIT — see [LICENSE.txt](LICENSE.txt).
