simulsi 0.2.0__tar.gz

simulsi-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+
+# SimulSI outputs are per-user
+simulsi-results/
+*.checkpoint.jsonl
+
+# Node / web
+node_modules/
+web/frontend/dist/
+src/simulsi/web/static/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/

simulsi-0.2.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-02
+
+### Added
+
+- Preemptive resources (`preemptive=True` with the priority discipline);
+  evicted processes receive `Interrupt(Preempted(...))`.
+- Sobol first-order and total-effect sensitivity indices
+  (`simulsi.analysis.sobol_indices`) with bootstrap CIs, validated against
+  the Ishigami function.
+- Checkpoints of running simulations (`sim.save_checkpoint`,
+  `Simulation.load_checkpoint`) restored by verified deterministic replay.
+- PyPI publishing workflow (trusted publishing).
+
+### Fixed
+
+- Hold times in event-log records were wrong for units granted at t = 0.
+
+## [0.1.0] - 2026-10-02
+
+First public release.
+
+### Added
+
+- Discrete-event engine: float clock with `timedelta`/`datetime` conversion,
+  heap-based event queue with deterministic `(time, priority, sequence)`
+  ordering, scheduling, rescheduling, cancellation, `run(until=...)`
+  that stops exactly at the horizon, snapshots and a structured event log
+  (JSON/CSV/Parquet export).
+- Generator-based processes with timeouts, signals, `all_of`/`any_of`,
+  waiting on other processes, interrupts and error propagation.
+- Resources with FIFO/LIFO/priority/custom disciplines, reneging,
+  capacity changes, downtime, automatic statistics; blocking queues.
+- Entities with attributes, state history and time-in-system metrics.
+- Seeded random streams (PCG64, named sub-streams via `SeedSequence`) and 12
+  distributions with validation and configuration specs.
+- Metrics: tallies, time-weighted gauges, counters, histograms, warm-up reset.
+- Models (`Model`, `@model`, `Parameter`), scenarios, full-factorial grids.
+- Experiments with common random numbers, provenance (git commit,
+  environment), parallel workers, checkpoint/resume and JSON/CSV/Parquet
+  export.
+- Monte Carlo (random and Latin hypercube sampling, vectorised models,
+  simulation models), statistics (t/bootstrap/Wilson intervals, replication
+  advice, convergence, batch means, paired and Welch differences), scenario
+  comparison, sensitivity analysis (OAT, finite differences, Pearson,
+  Spearman, SRC).
+- Failure/recovery processes, scheduled disruptions, cost models and an
+  optimisation `Objective` adapter.
+- Model validation (smoke run with deadlock / unreleased-resource / state
+  checks) and flow/state graph introspection (Mermaid, DOT).
+- Optional matplotlib/Plotly visualisation.
+- YAML experiment configuration (strict schema, safe loading, path checks)
+  and the `simulsi` CLI: `init`, `validate`, `run`, `experiment`, `analyze`,
+  `benchmark`, `visualize`, `ui`.
+- Optional React + TypeScript dashboard (`simulsi ui`): load experiments,
+  view parameters and provenance, run models, compare scenarios, inspect
+  distributions and convergence, trace single runs (timeline, queues,
+  utilization) and export JSON/CSV. Served locally on 127.0.0.1.
+- Six domain examples: bank, hospital, warehouse, manufacturing,
+  transportation, aviation - plus a minimal M/M/c example.
+- Benchmark suite (`benchmarks/run_benchmarks.py`, `simulsi benchmark`) with
+  measured results, and performance regression tests.
+- Documentation: user guide, architecture, research workflow, extension guide,
+  FAQ; documentation code blocks are executed by the test suite.
+
+### Known limitations
+
+- No preemptive resources, continuous-time dynamics or single-run
+  checkpoint/restore (experiments are checkpointed per replication).
+- Sensitivity analysis is local / correlation-based; no Sobol indices yet.
+- Not yet published on PyPI; install from source.

simulsi-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yash Jindal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simulsi-0.2.0/NOTICE

@@ -0,0 +1,11 @@
+NOTICE
+======
+
+This project is licensed under the MIT License (see LICENSE).
+
+You are free to use, study, modify and build on this code, including
+commercially. The MIT License requires that you keep the copyright notice
+and license text with any substantial portion you reuse.
+
+Nothing in this NOTICE modifies, restricts or adds conditions to the MIT
+License. If the two ever appear to conflict, the LICENSE file governs.

simulsi-0.2.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: simulsi
+Version: 0.2.0
+Summary: A general-purpose, reproducible simulation and scenario experimentation framework for Python.
+Project-URL: Homepage, https://github.com/Yashjindal11/simulsi
+Project-URL: Documentation, https://github.com/Yashjindal11/simulsi/tree/main/docs
+Project-URL: Issues, https://github.com/Yashjindal11/simulsi/issues
+Author: Yash Jindal
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: discrete-event-simulation,experiments,monte-carlo,operations-research,queueing,sensitivity-analysis,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.11
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.8; extra == 'all'
+Requires-Dist: pandas>=2.1; extra == 'all'
+Requires-Dist: plotly>=5.18; extra == 'all'
+Requires-Dist: pyarrow>=14; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: matplotlib>=3.8; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pandas>=2.1; extra == 'dev'
+Requires-Dist: plotly>=5.18; extra == 'dev'
+Requires-Dist: pyarrow>=14; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.16.10; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.1; extra == 'pandas'
+Provides-Extra: parquet
+Requires-Dist: pandas>=2.1; extra == 'parquet'
+Requires-Dist: pyarrow>=14; extra == 'parquet'
+Provides-Extra: plotly
+Requires-Dist: plotly>=5.18; extra == 'plotly'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# SimulSI
+
+**Simulation Intelligence** - *Model the system. Simulate the future.*
+
+SimulSI is a general-purpose, reproducible simulation and scenario
+experimentation framework for Python. You describe a system - customers and
+tellers, patients and doctors, jobs and machines, aircraft and gates, requests
+and servers - as discrete-event processes; SimulSI runs it, measures it, and
+helps you answer *what if?* with replications, confidence intervals, scenario
+comparisons, Monte Carlo and sensitivity analysis.
+
+```python
+from simulsi import Experiment, Scenario, Simulation, model
+from simulsi.randomness import Exponential
+
+
+@model(duration=480, parameters={"arrival_rate": 1.0, "tellers": 3})
+def bank(sim: Simulation, p):
+    tellers = sim.resource("teller", capacity=p.tellers)
+    arrivals, service = sim.stream("arrivals"), sim.stream("service")
+
+    def customer(sim):
+        yield sim.request(tellers)                       # wait for a teller
+        yield Exponential(mean=2.6).sample(service)      # being served
+        sim.release(tellers)
+
+    def source(sim):
+        while True:
+            yield Exponential(rate=p.arrival_rate).sample(arrivals)
+            sim.process(customer(sim))
+
+    sim.process(source(sim))
+
+
+result = Experiment(
+    bank,
+    [Scenario("baseline"), Scenario("four_tellers", {"tellers": 4})],
+    replications=30,
+    seed=42,
+).run()
+print(result.format_summary(["resource.teller.wait.mean", "resource.teller.utilization"]))
+print(result.compare("baseline", metrics=["resource.teller.wait.mean"]).format())
+```
+
+## Why SimulSI?
+
+Discrete-event engines tell you what happened in *one* run. Decisions need
+more: how sure are we, which scenario is better, which input matters most, and
+can someone else reproduce this? SimulSI is built **experiment-first**:
+
+| | |
+|---|---|
+| **Reproducible by construction** | Every run is determined by its seed. Named random streams (`sim.stream("arrivals")`) are derived from the seed with NumPy's `SeedSequence`, so adding a resource never shifts another stream. Serial and parallel runs give identical numbers. |
+| **Scenario comparison** | Scenarios share replication seeds (*common random numbers*) and comparisons use paired confidence intervals, which are usually much tighter than comparing independent runs. |
+| **Statistics built in** | t and bootstrap CIs, Wilson intervals for probabilities, "have I run enough replications?" advice, convergence curves, batch means for long runs. |
+| **Monte Carlo & sensitivity** | Propagate input uncertainty (random or Latin hypercube sampling, vectorised or per simulation run). One-at-a-time, finite-difference, correlation and standardised-regression sensitivity. |
+| **Provenance** | Each experiment records id, model name/version, git commit, timestamp, seeds, parameters, runtime and environment. Results export to JSON, CSV and Parquet. |
+| **Model introspection** | `snapshot()` of live state, structured event logs, observed flow graphs (arrival -> queue -> service -> departure), entity state machines, and model validation with a smoke run (unreleased resources, possible deadlocks, zero capacities, unreached states). |
+| **Decision support** | Cost/revenue models on top of metrics; an `Objective` adapter that hands models to scipy.optimize, OR-Tools, evolutionary or Bayesian optimisers without depending on any of them. |
+| **Local-first** | No LLMs, API keys, telemetry or network access. Core dependencies: NumPy, SciPy, pydantic, PyYAML. Plotting, pandas, Parquet and the web dashboard are optional. |
+
+SimulSI is not a replacement for mature engines such as SimPy or Salabim, or
+for commercial packages; see
+[how SimulSI differs](docs/faq.md#how-does-simulsi-compare-with-other-tools).
+
+## Installation
+
+SimulSI is not on PyPI yet; install from source (Python 3.11+):
+
+```bash
+git clone https://github.com/Yashjindal11/simulsi.git && cd simulsi
+python -m venv .venv
+.venv/bin/pip install -e .            # core
+.venv/bin/pip install -e ".[viz]"     # + matplotlib plots
+.venv/bin/pip install -e ".[all]"     # + pandas, Parquet, matplotlib, Plotly
+.venv/bin/pip install -e ".[dev]"     # everything needed to run the tests
+```
+
+## Command line
+
+```bash
+simulsi init my-study                          # starter model.py + experiment.yaml
+simulsi validate my-study/experiment.yaml      # schema check + model smoke run
+simulsi run examples/queue.py -p servers=3     # one replication, metrics table
+simulsi experiment my-study/experiment.yaml    # scenarios x replications, comparison, saved results
+simulsi analyze my-study/results/service-desk --precision 0.05
+simulsi visualize my-study/results/service-desk --out plots
+simulsi benchmark                              # events/sec on this machine
+simulsi ui my-study/results/service-desk       # local dashboard on 127.0.0.1
+```
+
+Experiments are described in YAML - data only, validated against a strict
+schema:
+
+```yaml
+model: model.py:service_desk
+simulation: {seed: 42, duration: 480}
+experiment: {replications: 30, workers: 4}
+parameters: {arrival_rate: 0.9}
+scenarios:
+  - {name: high_demand, parameters: {arrival_rate: 1.3}}
+  - {name: extra_server, parameters: {servers: 3}}
+```
+
+## Examples
+
+| Example | Shows |
+|---|---|
+| [`queue.py`](examples/queue.py) | Minimal M/M/c model checked against Erlang C |
+| [`bank_queue.py`](examples/bank_queue.py) | Reneging customers, staffing scenarios, replication advice |
+| [`hospital.py`](examples/hospital.py) | Priority triage, several resources, service levels |
+| [`warehouse.py`](examples/warehouse.py) | Time-varying demand, picking/packing buffers, backlog |
+| [`manufacturing.py`](examples/manufacturing.py) | Breakdowns with a repair crew, blocking, cost model |
+| [`transportation.py`](examples/transportation.py) | Shuttle loop, boarding capacity, left-behind passengers |
+| [`aviation.py`](examples/aviation.py) | Synthetic airport gates, taxiway holds, tows, weather disruption |
+
+```bash
+python examples/hospital.py
+python scripts/run_examples.py      # all of them, quick mode
+```
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) - installation, quickstart, first experiment
+- [Core concepts](docs/concepts.md) - simulation, events, entities, resources, queues, processes, randomness, metrics, disruptions, validation, introspection
+- [Experiments and analysis](docs/experiments.md) - scenarios, experiments, Monte Carlo, statistics, comparison, sensitivity, cost, optimisation
+- [Visualization](docs/visualization.md) - plots and the web dashboard
+- [CLI and configuration](docs/cli.md)
+- [Architecture](docs/architecture.md) - design, module map, performance, limitations
+- [Extending SimulSI](docs/extending.md)
+- [Research workflow](docs/research.md) - reproducibility, provenance, statistical practice
+- [Examples](docs/examples.md) - walkthroughs of the domain examples
+- [FAQ](docs/faq.md) - including how SimulSI compares with other tools
+- [Benchmarks](benchmarks/README.md) - measured numbers and how to reproduce them
+
+## Status
+
+SimulSI is alpha software (0.x) and the API may still change. It is tested on
+Python 3.11-3.13 (Linux, macOS, Windows in CI) with unit, property-based
+(Hypothesis), statistical, integration, CLI and performance tests - including
+checks of simulated M/M/c queues against closed-form Erlang-C results.
+
+## Contributing
+
+Issues and pull requests are welcome - see [CONTRIBUTING.md](CONTRIBUTING.md)
+and the [Code of Conduct](CODE_OF_CONDUCT.md). For security reports see
+[SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Yash Jindal

simulsi-0.2.0/README.md

@@ -0,0 +1,151 @@
+# SimulSI
+
+**Simulation Intelligence** - *Model the system. Simulate the future.*
+
+SimulSI is a general-purpose, reproducible simulation and scenario
+experimentation framework for Python. You describe a system - customers and
+tellers, patients and doctors, jobs and machines, aircraft and gates, requests
+and servers - as discrete-event processes; SimulSI runs it, measures it, and
+helps you answer *what if?* with replications, confidence intervals, scenario
+comparisons, Monte Carlo and sensitivity analysis.
+
+```python
+from simulsi import Experiment, Scenario, Simulation, model
+from simulsi.randomness import Exponential
+
+
+@model(duration=480, parameters={"arrival_rate": 1.0, "tellers": 3})
+def bank(sim: Simulation, p):
+    tellers = sim.resource("teller", capacity=p.tellers)
+    arrivals, service = sim.stream("arrivals"), sim.stream("service")
+
+    def customer(sim):
+        yield sim.request(tellers)                       # wait for a teller
+        yield Exponential(mean=2.6).sample(service)      # being served
+        sim.release(tellers)
+
+    def source(sim):
+        while True:
+            yield Exponential(rate=p.arrival_rate).sample(arrivals)
+            sim.process(customer(sim))
+
+    sim.process(source(sim))
+
+
+result = Experiment(
+    bank,
+    [Scenario("baseline"), Scenario("four_tellers", {"tellers": 4})],
+    replications=30,
+    seed=42,
+).run()
+print(result.format_summary(["resource.teller.wait.mean", "resource.teller.utilization"]))
+print(result.compare("baseline", metrics=["resource.teller.wait.mean"]).format())
+```
+
+## Why SimulSI?
+
+Discrete-event engines tell you what happened in *one* run. Decisions need
+more: how sure are we, which scenario is better, which input matters most, and
+can someone else reproduce this? SimulSI is built **experiment-first**:
+
+| | |
+|---|---|
+| **Reproducible by construction** | Every run is determined by its seed. Named random streams (`sim.stream("arrivals")`) are derived from the seed with NumPy's `SeedSequence`, so adding a resource never shifts another stream. Serial and parallel runs give identical numbers. |
+| **Scenario comparison** | Scenarios share replication seeds (*common random numbers*) and comparisons use paired confidence intervals, which are usually much tighter than comparing independent runs. |
+| **Statistics built in** | t and bootstrap CIs, Wilson intervals for probabilities, "have I run enough replications?" advice, convergence curves, batch means for long runs. |
+| **Monte Carlo & sensitivity** | Propagate input uncertainty (random or Latin hypercube sampling, vectorised or per simulation run). One-at-a-time, finite-difference, correlation and standardised-regression sensitivity. |
+| **Provenance** | Each experiment records id, model name/version, git commit, timestamp, seeds, parameters, runtime and environment. Results export to JSON, CSV and Parquet. |
+| **Model introspection** | `snapshot()` of live state, structured event logs, observed flow graphs (arrival -> queue -> service -> departure), entity state machines, and model validation with a smoke run (unreleased resources, possible deadlocks, zero capacities, unreached states). |
+| **Decision support** | Cost/revenue models on top of metrics; an `Objective` adapter that hands models to scipy.optimize, OR-Tools, evolutionary or Bayesian optimisers without depending on any of them. |
+| **Local-first** | No LLMs, API keys, telemetry or network access. Core dependencies: NumPy, SciPy, pydantic, PyYAML. Plotting, pandas, Parquet and the web dashboard are optional. |
+
+SimulSI is not a replacement for mature engines such as SimPy or Salabim, or
+for commercial packages; see
+[how SimulSI differs](docs/faq.md#how-does-simulsi-compare-with-other-tools).
+
+## Installation
+
+SimulSI is not on PyPI yet; install from source (Python 3.11+):
+
+```bash
+git clone https://github.com/Yashjindal11/simulsi.git && cd simulsi
+python -m venv .venv
+.venv/bin/pip install -e .            # core
+.venv/bin/pip install -e ".[viz]"     # + matplotlib plots
+.venv/bin/pip install -e ".[all]"     # + pandas, Parquet, matplotlib, Plotly
+.venv/bin/pip install -e ".[dev]"     # everything needed to run the tests
+```
+
+## Command line
+
+```bash
+simulsi init my-study                          # starter model.py + experiment.yaml
+simulsi validate my-study/experiment.yaml      # schema check + model smoke run
+simulsi run examples/queue.py -p servers=3     # one replication, metrics table
+simulsi experiment my-study/experiment.yaml    # scenarios x replications, comparison, saved results
+simulsi analyze my-study/results/service-desk --precision 0.05
+simulsi visualize my-study/results/service-desk --out plots
+simulsi benchmark                              # events/sec on this machine
+simulsi ui my-study/results/service-desk       # local dashboard on 127.0.0.1
+```
+
+Experiments are described in YAML - data only, validated against a strict
+schema:
+
+```yaml
+model: model.py:service_desk
+simulation: {seed: 42, duration: 480}
+experiment: {replications: 30, workers: 4}
+parameters: {arrival_rate: 0.9}
+scenarios:
+  - {name: high_demand, parameters: {arrival_rate: 1.3}}
+  - {name: extra_server, parameters: {servers: 3}}
+```
+
+## Examples
+
+| Example | Shows |
+|---|---|
+| [`queue.py`](examples/queue.py) | Minimal M/M/c model checked against Erlang C |
+| [`bank_queue.py`](examples/bank_queue.py) | Reneging customers, staffing scenarios, replication advice |
+| [`hospital.py`](examples/hospital.py) | Priority triage, several resources, service levels |
+| [`warehouse.py`](examples/warehouse.py) | Time-varying demand, picking/packing buffers, backlog |
+| [`manufacturing.py`](examples/manufacturing.py) | Breakdowns with a repair crew, blocking, cost model |
+| [`transportation.py`](examples/transportation.py) | Shuttle loop, boarding capacity, left-behind passengers |
+| [`aviation.py`](examples/aviation.py) | Synthetic airport gates, taxiway holds, tows, weather disruption |
+
+```bash
+python examples/hospital.py
+python scripts/run_examples.py      # all of them, quick mode
+```
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) - installation, quickstart, first experiment
+- [Core concepts](docs/concepts.md) - simulation, events, entities, resources, queues, processes, randomness, metrics, disruptions, validation, introspection
+- [Experiments and analysis](docs/experiments.md) - scenarios, experiments, Monte Carlo, statistics, comparison, sensitivity, cost, optimisation
+- [Visualization](docs/visualization.md) - plots and the web dashboard
+- [CLI and configuration](docs/cli.md)
+- [Architecture](docs/architecture.md) - design, module map, performance, limitations
+- [Extending SimulSI](docs/extending.md)
+- [Research workflow](docs/research.md) - reproducibility, provenance, statistical practice
+- [Examples](docs/examples.md) - walkthroughs of the domain examples
+- [FAQ](docs/faq.md) - including how SimulSI compares with other tools
+- [Benchmarks](benchmarks/README.md) - measured numbers and how to reproduce them
+
+## Status
+
+SimulSI is alpha software (0.x) and the API may still change. It is tested on
+Python 3.11-3.13 (Linux, macOS, Windows in CI) with unit, property-based
+(Hypothesis), statistical, integration, CLI and performance tests - including
+checks of simulated M/M/c queues against closed-form Erlang-C results.
+
+## Contributing
+
+Issues and pull requests are welcome - see [CONTRIBUTING.md](CONTRIBUTING.md)
+and the [Code of Conduct](CODE_OF_CONDUCT.md). For security reports see
+[SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Yash Jindal

simulsi-0.2.0/benchmarks/README.md

@@ -0,0 +1,59 @@
+# Benchmarks
+
+```bash
+python benchmarks/run_benchmarks.py          # full suite, ~1 minute
+python benchmarks/run_benchmarks.py --quick  # 10k / 100k only
+simulsi benchmark                            # same measurements from the CLI
+```
+
+The script writes [`results/latest.json`](results/latest.json) (raw numbers
+plus the environment) and [`results/latest.md`](results/latest.md).
+
+## What is measured
+
+| Benchmark | Description | Size means |
+|---|---|---|
+| `events` | Pure engine overhead: callback events in 100 interleaved chains with exponential delays (heap push/pop, clock, dispatch). | events |
+| `processes` | An M/M/2 queue written with generator processes, a resource with contention, and metrics: about 3.85 events per customer. | customers |
+| `experiment(workers=N)` | 16 replications of the built-in M/M/1 model (20,000 time units each), serial and in worker processes. | replications |
+| `peak_memory_mb` | `tracemalloc` peak during a separate run (sizes up to 100k only, because tracing slows the run). | |
+
+## Results
+
+Measured on 2026-10-02 on the development machine. These are single
+measurements, not averages over repeated runs; expect some run-to-run
+variation. Re-run the script on your hardware rather than relying on them.
+
+- Python 3.12.15 (CPython), NumPy 2.5.3, SimulSI 0.1.0.dev0
+- macOS 26.6.2 on Apple silicon (arm64), 10 logical CPUs
+
+| name | size | events | seconds | events/s | peak MB |
+|---|---:|---:|---:|---:|---:|
+| events | 10,000 | 10,000 | 0.023 | 437,190 | 0.02 |
+| events | 100,000 | 100,000 | 0.228 | 438,656 | 0.02 |
+| events | 1,000,000 | 1,000,000 | 2.281 | 438,466 | - |
+| processes | 10,000 | 38,501 | 0.154 | 250,000 | 0.31 |
+| processes | 100,000 | 385,581 | 1.595 | 241,692 | 0.54 |
+| processes | 1,000,000 | 3,850,935 | 16.34 | 235,737 | - |
+| experiment (1 worker) | 16 | 1,119,489 | 4.59 | 244,072 | - |
+| experiment (2 workers) | 16 | 1,119,489 | 3.82 | 293,357 | - |
+| experiment (4 workers) | 16 | 1,119,489 | 3.40 | 329,285 | - |
+
+## Observations
+
+* Throughput is flat from 10k to 1M events: the heap is O(log n) and
+  finished processes and timeouts are freed by reference counting. An
+  earlier version kept a reference cycle per timeout, so the cyclic garbage
+  collector slowed long runs by about 30%. That was found with this suite and
+  fixed.
+* Memory stays small because statistics are incremental. Keeping raw
+  observations (`keep_values`), time series (`record_series`), entity
+  histories or an event log (`trace=True`) costs memory proportional to run
+  length.
+* Parallel speed-up is modest here (about 1.35x with 4 workers): each
+  replication takes about 0.3 s, while starting a worker process with the
+  `spawn` method (macOS, Windows) and importing NumPy/SciPy costs about a
+  second. Longer replications parallelise better. Results are identical to
+  serial runs either way (tested).
+* `tests/performance/test_performance.py` guards against regressions with
+  generous floors (about 10x below these numbers) and a linear-scaling check.