simulsi 0.2.0__tar.gz → 0.3.0__tar.gz

{simulsi-0.2.0 → simulsi-0.3.0}/.gitignore

@@ -28,3 +28,4 @@ src/simulsi/web/static/
 .DS_Store
 .idea/
 .vscode/
+site/

{simulsi-0.2.0 → simulsi-0.3.0}/CHANGELOG.md

@@ -6,6 +6,40 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-06
+
+### Added
+
+- Per-run warm-up override (`Model.simulate(warmup=)`, `simulsi run --warmup`);
+  the model warm-up is scaled proportionally for shorter runs, with a note.
+- Dashboard runs experiments as background jobs with a progress bar
+  (`POST /api/run` returns 202, `GET /api/jobs/{id}`).
+- Multiple-comparison adjustment in `compare(adjust="bonferroni"|"holm"|"bh")`,
+  the CLI (`--adjust`), configs and the dashboard.
+- Warm-up detection with MSER-5 (`simulsi.analysis.mser`, `suggest_warmup`,
+  `simulsi warmup`).
+- Sequential experiments: `Experiment.run_until(relative_precision, ...)` and
+  `simulsi experiment --until-precision`.
+- Antithetic variates (`Experiment(antithetic=True)`, inverse-transform
+  sampling modes on `RandomStream`) and control variates
+  (`ExperimentResult.control_variate`, `statistics.control_variate`).
+- Documentation site with API reference (mkdocs-material, GitHub Pages).
+- Modelling primitives: `Container` (`sim.container`) for levels and stock;
+  filtered gets on queues (`queue.get(filter=...)`); `sim.wait_until(predicate)`;
+  shift schedules (`capacity_schedule`); non-stationary arrivals
+  (`arrivals` with `PiecewiseRate` or a rate function); `batch`, `split`/`join`,
+  `Router` and `shortest_queue`.
+- Input modelling: `fit_distribution` (MLE fits ranked by AIC/BIC/KS, with
+  `FitReport.format()` and `plot()`), `load_values` and `simulsi fit`;
+  trace-driven input with `load_trace`, `trace_arrivals` and `TraceReplay`.
+
+### Changed
+
+- Faster process engine (about 14% more events per second on process models);
+  `benchmarks/compare_simpy.py` compares against SimPy.
+- Worker process pools are reused across experiments in the same process
+  (`shutdown_workers()` to release them).
+
 ## [0.2.0] - 2026-10-02
 
 ### Added

{simulsi-0.2.0 → simulsi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simulsi
-Version: 0.2.0
+Version: 0.3.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
@@ -42,6 +42,9 @@ 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: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
 Provides-Extra: pandas
 Requires-Dist: pandas>=2.1; extra == 'pandas'
 Provides-Extra: parquet
@@ -55,6 +58,12 @@ Description-Content-Type: text/markdown
 
 # SimulSI
 
+[![CI](https://github.com/Yashjindal11/simulsi/actions/workflows/ci.yml/badge.svg)](https://github.com/Yashjindal11/simulsi/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/simulsi)](https://pypi.org/project/simulsi/)
+[![Python](https://img.shields.io/pypi/pyversions/simulsi)](https://pypi.org/project/simulsi/)
+[![Docs](https://github.com/Yashjindal11/simulsi/actions/workflows/docs.yml/badge.svg)](https://yashjindal11.github.io/simulsi/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
 **Simulation Intelligence** - *Model the system. Simulate the future.*
 
 SimulSI is a general-purpose, reproducible simulation and scenario
@@ -120,14 +129,19 @@ for commercial packages; see
 
 ## Installation
 
-SimulSI is not on PyPI yet; install from source (Python 3.11+):
+Python 3.11+, from [PyPI](https://pypi.org/project/simulsi/):
+
+```bash
+pip install simulsi             # core (includes the CLI and the web dashboard)
+pip install "simulsi[viz]"      # + matplotlib plots
+pip install "simulsi[all]"      # + pandas, Parquet, matplotlib, Plotly
+```
+
+From source (for development):
 
 ```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
 ```
 
@@ -176,6 +190,10 @@ python scripts/run_examples.py      # all of them, quick mode
 
 ## Documentation
 
+The full documentation, including an API reference for every public class
+and function, is at **https://yashjindal11.github.io/simulsi/**. The same
+pages are in [`docs/`](docs):
+
 - [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

{simulsi-0.2.0 → simulsi-0.3.0}/README.md

@@ -1,5 +1,11 @@
 # SimulSI
 
+[![CI](https://github.com/Yashjindal11/simulsi/actions/workflows/ci.yml/badge.svg)](https://github.com/Yashjindal11/simulsi/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/simulsi)](https://pypi.org/project/simulsi/)
+[![Python](https://img.shields.io/pypi/pyversions/simulsi)](https://pypi.org/project/simulsi/)
+[![Docs](https://github.com/Yashjindal11/simulsi/actions/workflows/docs.yml/badge.svg)](https://yashjindal11.github.io/simulsi/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
 **Simulation Intelligence** - *Model the system. Simulate the future.*
 
 SimulSI is a general-purpose, reproducible simulation and scenario
@@ -65,14 +71,19 @@ for commercial packages; see
 
 ## Installation
 
-SimulSI is not on PyPI yet; install from source (Python 3.11+):
+Python 3.11+, from [PyPI](https://pypi.org/project/simulsi/):
+
+```bash
+pip install simulsi             # core (includes the CLI and the web dashboard)
+pip install "simulsi[viz]"      # + matplotlib plots
+pip install "simulsi[all]"      # + pandas, Parquet, matplotlib, Plotly
+```
+
+From source (for development):
 
 ```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
 ```
 
@@ -121,6 +132,10 @@ python scripts/run_examples.py      # all of them, quick mode
 
 ## Documentation
 
+The full documentation, including an API reference for every public class
+and function, is at **https://yashjindal11.github.io/simulsi/**. The same
+pages are in [`docs/`](docs):
+
 - [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

{simulsi-0.2.0 → simulsi-0.3.0}/benchmarks/README.md

@@ -57,3 +57,36 @@ variation. Re-run the script on your hardware rather than relying on them.
   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.
+
+## Comparison with SimPy
+
+[`compare_simpy.py`](compare_simpy.py) runs the same M/M/2 queue (arrival
+rate 1.8, service rate 1.0, a generator process per customer, NumPy draws)
+in SimulSI and in [SimPy](https://simpy.readthedocs.io/), and checks that
+both produce the same mean wait.
+
+```bash
+pip install simpy
+python benchmarks/compare_simpy.py --customers 100000 --repeat 3
+```
+
+Measured on 2026-10-06 (Python 3.12.15, SimulSI 0.3.0.dev, SimPy 4.1.2,
+Apple silicon, best of 3):
+
+| library | seconds | customers/s | mean wait |
+|---|---:|---:|---:|
+| SimulSI | 1.35 | 73,800 | 4.6536 |
+| SimPy | 0.84 | 118,700 | 4.6536 |
+
+The two give identical results, and SimulSI takes about 1.6x as long. Part of
+the gap is extra work SimulSI does on every request and release: it records
+time-weighted utilization and queue length, a wait-time tally and counters,
+and tracks which process holds each unit so unreleased resources can be
+reported. SimPy leaves that bookkeeping to the model. The rest is per-event
+overhead (lazy cancellation, the event status machine). Profiling for this
+comparison led to hot-path changes that cut the gap from 1.85x and made the
+`processes` benchmark about 14% faster.
+
+If raw speed on very large models matters most, SimPy (or a compiled
+engine) is the better choice. SimulSI is aimed at the experiment layer:
+replications, statistics, scenarios and analysis.

simulsi-0.3.0/docs/api/analysis.md

@@ -0,0 +1,6 @@
+# Comparison and sensitivity
+
+::: simulsi.analysis.comparison
+
+::: simulsi.analysis.sensitivity
+::: simulsi.analysis.warmup

simulsi-0.3.0/docs/api/decisions.md

@@ -0,0 +1,5 @@
+# Cost and optimisation
+
+::: simulsi.cost.model
+
+::: simulsi.optimization.objective

simulsi-0.3.0/docs/api/entities.md

@@ -0,0 +1,3 @@
+# Entities
+
+::: simulsi.entities.entity

simulsi-0.3.0/docs/api/events.md

@@ -0,0 +1,3 @@
+# Events
+
+::: simulsi.events.event

simulsi-0.3.0/docs/api/experiments.md

@@ -0,0 +1,7 @@
+# Experiments and Monte Carlo
+
+::: simulsi.experiments.experiment
+
+::: simulsi.experiments.montecarlo
+
+::: simulsi.experiments.provenance

simulsi-0.3.0/docs/api/io.md

@@ -0,0 +1,5 @@
+# Configuration and I/O
+
+::: simulsi.config.schema
+
+::: simulsi.serialization.io

simulsi-0.3.0/docs/api/metrics.md

@@ -0,0 +1,3 @@
+# Metrics
+
+::: simulsi.metrics.collectors

simulsi-0.3.0/docs/api/models.md

@@ -0,0 +1,7 @@
+# Models and scenarios
+
+::: simulsi.core.model
+
+::: simulsi.scenarios.scenario
+
+::: simulsi.models.queueing

simulsi-0.3.0/docs/api/processes.md

@@ -0,0 +1,11 @@
+# Processes, schedules and flow
+
+::: simulsi.processes.process
+
+::: simulsi.processes.schedules
+
+::: simulsi.processes.flow
+
+::: simulsi.processes.trace
+
+::: simulsi.processes.disruption

simulsi-0.3.0/docs/api/randomness.md

@@ -0,0 +1,7 @@
+# Randomness
+
+::: simulsi.randomness.stream
+
+::: simulsi.randomness.distributions
+
+::: simulsi.randomness.fitting

simulsi-0.3.0/docs/api/resources.md

@@ -0,0 +1,9 @@
+# Resources, containers and queues
+
+::: simulsi.resources.resource
+
+::: simulsi.resources.container
+
+::: simulsi.queues.queue
+
+::: simulsi.queues.discipline

simulsi-0.3.0/docs/api/simulation.md

@@ -0,0 +1,9 @@
+# Simulation and clock
+
+::: simulsi.core.simulation
+
+::: simulsi.core.clock
+
+::: simulsi.core.trace
+
+::: simulsi.core.checkpoint

simulsi-0.3.0/docs/api/statistics.md

@@ -0,0 +1,3 @@
+# Statistics
+
+::: simulsi.statistics.core

simulsi-0.3.0/docs/api/validation.md

@@ -0,0 +1,5 @@
+# Validation and introspection
+
+::: simulsi.validation.validate
+
+::: simulsi.introspection.graph

simulsi-0.3.0/docs/api/visualization.md

@@ -0,0 +1,3 @@
+# Visualization
+
+::: simulsi.visualization.plots

{simulsi-0.2.0 → simulsi-0.3.0}/docs/architecture.md

@@ -106,7 +106,7 @@ model is pickled by reference (module + qualified name); models loaded from
 files by the CLI are re-imported in each worker by an initializer. Results
 come back in task order. Start-up cost (about a second with the `spawn`
 start method used on macOS and Windows) makes parallelism worthwhile only when
-replications take longer than that. See [benchmarks](../benchmarks/README.md).
+replications take longer than that. See [benchmarks](https://github.com/Yashjindal11/simulsi/blob/main/benchmarks/README.md).
 
 ## Checkpointing
 
@@ -143,7 +143,7 @@ files are found automatically; otherwise pass `model=`.
 ## Performance
 
 The engine is pure Python. Measured numbers are in
-[benchmarks/README.md](../benchmarks/README.md). Practical guidance:
+[benchmarks/README.md](https://github.com/Yashjindal11/simulsi/blob/main/benchmarks/README.md). Practical guidance:
 
 * Prefer `yield number` / `sim.use(...)` in processes; avoid creating
   entities you never inspect.

{simulsi-0.2.0 → simulsi-0.3.0}/docs/cli.md

@@ -3,9 +3,11 @@
 ```text
 simulsi init [DIR] [--force]
 simulsi validate TARGET [-p KEY=VALUE ...] [--smoke T]
-simulsi run TARGET [-p KEY=VALUE ...] [--seed N] [--duration T] [-m METRIC ...] [--trace FILE] [--json]
-simulsi experiment CONFIG [-r N] [-w N] [--seed N] [-o DIR] [--checkpoint FILE] [-q]
-simulsi analyze RESULTS [-m METRIC ...] [--baseline NAME] [--confidence C] [--precision P] [--json]
+simulsi run TARGET [-p KEY=VALUE ...] [--seed N] [--duration T] [--warmup T] [-m METRIC ...] [--trace FILE] [--json]
+simulsi experiment CONFIG [-r N] [-w N] [--seed N] [-o DIR] [--checkpoint FILE] [--adjust METHOD] [--until-precision P] [-q]
+simulsi analyze RESULTS [-m METRIC ...] [--baseline NAME] [--confidence C] [--precision P] [--adjust METHOD] [--json]
+simulsi warmup TARGET [-p KEY=VALUE ...] [--series KEY] [-r N] [--duration T] [--bins N] [--json]
+simulsi fit FILE [--column NAME] [--candidates NAME ...] [--criterion aic|bic|ks] [--json]
 simulsi benchmark [--sizes N ...] [--workers N ...] [--replications N] [--no-memory] [--json]
 simulsi visualize TARGET [-o DIR] [-m METRIC ...] [--backend matplotlib|plotly] [--format png|svg|pdf]
 simulsi ui [RESULTS ...] [--model REF ...] [--host H] [--port P] [--no-browser]
@@ -41,6 +43,12 @@ Parameters given with `-p key=value` are parsed as YAML scalars, so
   `experiment.json`, `replications.csv`, `summary.csv` (and Parquet if asked).
 * **analyze** reloads saved results: summary, comparison, provenance, and
   with `--precision 0.05` how many replications each metric needs.
+* **warmup** suggests a warm-up period: it averages a recorded time series
+  (default: the first resource's queue length) over replications and applies
+  MSER-5.
+* **fit** fits input distributions to a CSV column or a text file of
+  numbers, ranks them (AIC, BIC or KS) and prints the best one as a config
+  spec you can paste into `experiment.yaml`.
 * **benchmark** measures engine throughput (10k / 100k / 1M events),
   process-based model throughput and parallel experiment speed on your
   machine, with tracemalloc peak memory.
@@ -67,6 +75,10 @@ experiment:
   common_random_numbers: true    # same seeds for every scenario (paired comparisons)
   confidence: 0.95
   on_error: raise                # or "record" to keep going and store errors
+  multiple_comparisons: holm     # none (default), bonferroni, holm or bh
+  target_precision: 0.05         # optional: add replications until +-5% (relative) ...
+  precision_metrics: [resource.server.wait.mean]   # ... for these metrics (default: metrics)
+  max_replications: 500          # upper limit for precision-based stopping
 
 parameters:                      # base values for every scenario
   arrival_rate: 0.9

{simulsi-0.2.0 → simulsi-0.3.0}/docs/concepts.md

@@ -232,6 +232,132 @@ Metrics (prefix `queue.<name>.`): `mean_length`, `max_length`, `wait.mean/max`,
 `puts`, `gets`, `removed`, `throughput`, `length_final`. Items never vanish:
 `puts == gets + removed + length`.
 
+`orders.get(filter=lambda o: o.startswith("rush"))` takes the first matching
+item in discipline order (waiting until one arrives); a filtered get that is
+waiting does not hold up gets for other items. `try_get(filter)` is the
+non-blocking form.
+
+## Containers
+
+A `Container` holds a *level* (fuel, stock, cash, parts in a bin) rather than
+distinct items. `get(amount)` waits until enough is there; `put(amount)` waits
+until there is room. Waiters are served strictly in arrival order.
+
+```python
+from simulsi import Simulation
+
+sim = Simulation(seed=2)
+stock = sim.container("stock", capacity=200, init=120)
+
+
+def demand(sim):
+    rng = sim.stream("demand")
+    while True:
+        yield 1.0
+        yield stock.get(rng.integers(5, 15))
+
+
+def replenish(sim):
+    while True:
+        yield sim.wait_until(lambda: stock.level < 40)   # reorder point
+        yield 3.0                                         # lead time
+        yield stock.put(150)
+
+
+sim.process(demand(sim))
+sim.process(replenish(sim))
+m = sim.run(until=500).metrics
+print(m["container.stock.level.mean"], m["container.stock.stockouts"])
+```
+
+Metrics (prefix `container.<name>.`): `level.mean/min/max`, `level_final`,
+`put_amount`, `get_amount`, `stockouts` (gets that had to wait),
+`get_wait.mean`, `put_wait.mean`.
+
+`sim.wait_until(predicate)` works with any model state: the predicate is
+checked after every event until it is true, and the yield returns the time
+it became true. Keep predicates cheap.
+
+## Schedules and time-varying arrivals
+
+```python
+from simulsi import Simulation
+from simulsi.processes import PiecewiseRate, arrivals, capacity_schedule
+
+sim = Simulation(seed=4)
+agents = sim.resource("agents", 2)
+# shifts in minutes: 2 agents at night, 6 from 08:00, 4 from 17:00, every day
+capacity_schedule(sim, agents, [(0, 2), (480, 6), (1020, 4)], period=1440)
+# calls per minute by time of day
+calls = PiecewiseRate([(0, 0.05), (480, 0.6), (720, 0.9), (1020, 0.3)], period=1440)
+
+
+def call(sim, i):
+    yield from sim.use(agents, sim.stream("talk").exponential(6.0))
+
+
+arrivals(sim, calls, call, stream="calls")
+m = sim.run(until=7 * 1440).metrics
+print(m["resource.agents.utilization"], m["resource.agents.wait.mean"])
+```
+
+* `capacity_schedule(sim, resource, [(time, capacity), ...], period=None)`
+  changes capacity at the given offsets. Lowering capacity does not
+  interrupt work in progress; the new limit applies to later grants.
+* `arrivals(sim, rate, spawn, stream=..., limit=None, until=None)` calls
+  `spawn(sim, i)` at every arrival and starts it as a process if it returns a
+  generator. `rate` can be a number (Poisson process), a `PiecewiseRate`
+  (exact, one random draw per arrival) or any function `rate(t)` together with
+  `max_rate=` (generated by thinning).
+
+## Batching, split/join and routing
+
+```python
+from simulsi import Simulation
+from simulsi.processes import Router, batch, join, shortest_queue, split
+
+sim = Simulation(seed=5)
+parts = sim.queue("parts")
+lines = [sim.resource("line-a", 1), sim.resource("line-b", 1)]
+inspection = Router(sim, "inspection", {"pass": 0.9, "rework": 0.1})
+
+
+def supplier(sim):
+    for i in range(12):
+        yield 0.5
+        yield parts.put(i)
+
+
+def finish(sim, line):
+    yield from sim.use(line, 2.0)
+    return inspection.choose()
+
+
+def assembler(sim):
+    while True:
+        kit = yield from batch(parts, 4, timeout=5.0)     # up to 4 parts
+        if not kit:
+            return
+        results = yield from join(split(sim, [finish(sim, shortest_queue(lines))
+                                              for _ in range(2)]))
+        print(sim.now, kit, results)
+
+
+sim.process(supplier(sim))
+sim.process(assembler(sim))
+m = sim.run().metrics
+print(m["route.inspection.pass"], m["route.inspection.rework"])
+```
+
+* `batch(queue, size, timeout=None)` collects items (`yield from`); with a
+  timeout it returns whatever has arrived by then.
+* `split(sim, generators)` starts parallel processes and `join(processes)`
+  waits for all of them and returns their return values in order (a failure
+  in any of them is raised in the joiner).
+* `Router(sim, name, {route: probability})` draws from its own stream
+  (`route:<name>`) and counts `route.<name>.<route>`.
+* `shortest_queue(resources)` picks the resource with the fewest waiting.
+
 ## Randomness
 
 ```python
@@ -258,6 +384,50 @@ In a simulation use `sim.stream("name")`: streams are keyed by name, so the
 arrival stream is the same whatever else the model draws. This is what makes
 common-random-number comparisons effective.
 
+## Input data: fitting and traces
+
+Input distributions should come from data. `fit_distribution` fits the
+exponential, gamma, lognormal, normal, uniform, triangular and Poisson
+families by maximum likelihood and ranks them:
+
+```python
+import numpy as np
+
+from simulsi.randomness import fit_distribution
+
+observed = np.random.default_rng(7).gamma(2.5, 1.6, size=400)   # e.g. service times
+report = fit_distribution(observed)
+print(report.format())                    # AIC, BIC, KS statistic and p-value per family
+service = report.best.distribution        # a simulsi Gamma, ready to sample
+print(service, report.best.distribution.to_spec())
+```
+
+* Families whose support does not fit the data (gamma or lognormal with
+  zeros, Poisson with fractions) are listed in `report.skipped`.
+* KS p-values use parameters estimated from the same data, so they are
+  optimistic. With fewer than about 30 observations, or when the best family
+  is still rejected, use `Empirical(data)` instead.
+* `report.plot()` overlays the top fits on a histogram.
+* `simulsi fit data.csv --column service` does the same from the command
+  line and prints a spec for `experiment.yaml`.
+
+**Trace-driven runs** replay history instead of sampling. With recorded
+arrivals and service times, a valid model should reproduce the recorded
+waits, which makes this a strong validation check:
+
+```py
+from simulsi.processes import TraceReplay, load_trace, trace_arrivals
+
+history = load_trace("arrivals.csv")          # rows like {"time": 3.5, "service": 4.1}
+
+def job(sim, record):
+    yield from sim.use(server, record["service"])
+
+trace_arrivals(sim, history, job)               # one arrival per row, at row["time"]
+repair_times = TraceReplay([12.0, 30.5, 8.2], cycle=True)
+repair_times.sample()                           # next recorded value
+```
+
 ## Metrics
 
 ```python

{simulsi-0.2.0 → simulsi-0.3.0}/docs/examples.md

@@ -1,6 +1,6 @@
 # Examples
 
-Every example is a single file in [`examples/`](../examples) with a
+Every example is a single file in [`examples/`](https://github.com/Yashjindal11/simulsi/blob/main/examples) with a
 module-level `model` and a `main(replications=...)` function. All data is
 synthetic. Run one with `python examples/<name>.py`, or all of them quickly
 with `python scripts/run_examples.py`. They also work with the CLI:
@@ -11,7 +11,7 @@ simulsi validate examples/manufacturing.py
 simulsi visualize examples/bank_queue.py --out plots
 ```
 
-## 1. Bank queue - [`bank_queue.py`](../examples/bank_queue.py)
+## 1. Bank queue - [`bank_queue.py`](https://github.com/Yashjindal11/simulsi/blob/main/examples/bank_queue.py)
 
 Poisson arrivals, log-normal service times (specified by mean and coefficient
 of variation via `LogNormal.from_moments`), a pool of tellers, and customers
@@ -22,7 +22,7 @@ the reneging fraction, for baseline / four tellers / lunch rush / both,
 compared with paired CIs. It ends with replication advice: how many
 replications are needed for a +-5% estimate of the mean wait.
 
-## 2. Emergency department - [`hospital.py`](../examples/hospital.py)
+## 2. Emergency department - [`hospital.py`](https://github.com/Yashjindal11/simulsi/blob/main/examples/hospital.py)
 
 Patients get an acuity level (`Categorical`), see a triage nurse, wait for a
 treatment room and then a doctor. Rooms and doctors use the `"priority"`
@@ -35,7 +35,7 @@ their acuity's target (a service level), doctor and room utilization. It
 compares an extra doctor with extra rooms - which one helps depends on which
 resource binds.
 
-## 3. Warehouse - [`warehouse.py`](../examples/warehouse.py)
+## 3. Warehouse - [`warehouse.py`](https://github.com/Yashjindal11/simulsi/blob/main/examples/warehouse.py)
 
 Orders arrive with a time-varying rate (a non-homogeneous Poisson process
 generated by thinning), each with a Poisson number of lines. Pickers walk
@@ -45,7 +45,7 @@ and pick, then hand orders to packers through a `Queue` buffer.
 time and picker/packer utilization, comparing a seventh picker against
 faster picking from better slotting.
 
-## 4. Manufacturing - [`manufacturing.py`](../examples/manufacturing.py)
+## 4. Manufacturing - [`manufacturing.py`](https://github.com/Yashjindal11/simulsi/blob/main/examples/manufacturing.py)
 
 Two machines in series with a finite buffer. A full buffer blocks machine 1
 while it still holds the finished job. Each machine fails at random
@@ -58,7 +58,7 @@ afterwards.
 costs). Scenarios: preventive maintenance (longer MTBF), a bigger buffer, a
 second technician.
 
-## 5. Transportation - [`transportation.py`](../examples/transportation.py)
+## 5. Transportation - [`transportation.py`](https://github.com/Yashjindal11/simulsi/blob/main/examples/transportation.py)
 
 Buses circulate around a loop of stops. Passengers queue at each stop with a
 random destination; a bus alights passengers, boards as many as fit, dwells
@@ -69,7 +69,7 @@ buses (congestion) and load factor (capacity utilization). It compares a
 fourth bus with bigger buses that have the same total number of seats -
 frequency against capacity.
 
-## 6. Aviation - [`aviation.py`](../examples/aviation.py)
+## 6. Aviation - [`aviation.py`](https://github.com/Yashjindal11/simulsi/blob/main/examples/aviation.py)
 
 A synthetic day of arrivals in two banks plus background traffic. Flights
 land with log-normal delays, wait on the taxiway if no gate is free (a gate
@@ -84,7 +84,7 @@ an airline planning tool, and it uses no real airline data.
 
 ## Smaller examples
 
-* [`queue.py`](../examples/queue.py) - M/M/c in 30 lines, compared with the
+* [`queue.py`](https://github.com/Yashjindal11/simulsi/blob/main/examples/queue.py) - M/M/c in 30 lines, compared with the
   Erlang-C formula.
 * `simulsi init` - the starter "service desk" project with a YAML experiment
   and cost model.