Gillespie

A compact NumPy framework for simulating stochastic discrete-event processes with Gillespie's Direct Method. The included SIR model demonstrates simulation, analysis, reproducible ensembles, and plotting without coupling the engine to the epidemiological model.

Quick start

Python and uv are required:

uv sync
uv run python examples/sir.py

Minimal usage:

from gillespie import simulate
from gillespie.sir import create_sir_model, make_sir_state

model = create_sir_model(population=1_000, beta=0.3, gamma=0.1)
initial_state = make_sir_state(
    population=1_000,
    infected=10,
    recovered=0,
)

result = simulate(
    model,
    initial_state,
    t_end=160.0,
    seed=42,
)

result.times contains the recorded times and result.states the corresponding states. The seed is explicit: repeating the same configuration produces the same trajectory in the supported numerical environment.

Documentation

• Using the library
• Gillespie's algorithm

Run the simulation-core benchmark with:

uv run python benchmarks/benchmark_core.py

The benchmark reports timings and throughput without enforcing machine-dependent thresholds.

Run the fast test suite with uv run pytest.