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.

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:

SimulSI is not a replacement for mature engines such as SimPy or Salabim, or for commercial packages; see how SimulSI differs.

Installation

Python 3.11+, from PyPI:

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

With Docker (dashboard and CLI, no Python needed; the image is published for each release):

docker run --rm -p 127.0.0.1:8642:8642 ghcr.io/yashjindal11/simulsi        # dashboard on http://localhost:8642
docker run --rm -v "$PWD:/work" ghcr.io/yashjindal11/simulsi run model.py  # any CLI command

From source (for development):

git clone https://github.com/Yashjindal11/simulsi.git && cd simulsi
python -m venv .venv
.venv/bin/pip install -e ".[dev]"     # everything needed to run the tests

Command line

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:

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

python examples/hospital.py
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/:

• Getting started - installation, quickstart, first experiment
• Core concepts - simulation, events, entities, resources, queues, processes, randomness, metrics, disruptions, validation, introspection
• Experiments and analysis - scenarios, experiments, Monte Carlo, statistics, variance reduction, comparison, sensitivity, ranking and selection, cost, optimisation, surrogates
• Visualization - plots, HTML reports, notebooks and the web dashboard
• CLI and configuration
• Architecture - design, module map, performance, limitations
• Extending SimulSI
• Research workflow - reproducibility, provenance, statistical practice
• Examples and notebooks - walkthroughs of the domain examples and tutorial notebooks
• Coming from SimPy - concept map and a side-by-side port
• FAQ - including how SimulSI compares with other tools
• Benchmarks - 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 and the Code of Conduct. For security reports see SECURITY.md.

License

MIT © 2026 Yash Jindal