Simulatte

Discrete-event simulation framework for production planning and control and intralogistics, built on SimPy.

Simulatte in 60 seconds. Click to watch on simulatte.dev.

Note: Simulatte is under active development. All APIs — including those outside simulatte.experimental — should be considered unstable and may change between releases without prior deprecation. Pin your dependency to a specific version if you need stability.

What is Simulatte?

Simulatte is a Python library for simulating manufacturing job-shops with integrated intralogistics. It models production servers, warehouses, AGVs, and material flow in a unified framework. Use it to evaluate scheduling policies, analyze bottlenecks, and study system performance under stochastic conditions.

The library provides ready-to-use components for common manufacturing scenarios while remaining extensible for custom requirements. Whether you're researching release control policies, optimizing warehouse layouts, or teaching discrete-event simulation, Simulatte offers a clean API built on proven SimPy foundations.

Features

Job-Shop Scheduling

• Multi-server routing with configurable processing times
• Due dates and tardiness tracking
• Queue time and utilization metrics per server

Release Control

• Pre-Shop Pool (PSP) for workload-based job release
• Built-in policies: Immediate Release, LumsCor, SLAR, SLAR-Limit, DRACO, ConWIP, and Continuous Release
• Event callbacks (psp.on_arrival, shopfloor.on_processing_end) and composable triggers
• Starvation avoidance mechanisms

Extensibility

• Operation hooks: sync or generator-based, before/after processing (e.g., setup times, dispatching)
• Event callbacks: on_processing_end, on_job_finished, on_arrival for reactive logic
• Dispatcher protocol: one-call wiring of multi-event controllers via attach_dispatcher()
• WIP strategies: Standard and Corrected workload estimation
• Custom collectors: subclass Collector to compute your own metrics from events on the event bus

Time-Series Analysis

• Built-in collectors for WIP, throughput, job count, lateness
• Matplotlib integration: plot_wip(), plot_throughput(), plot_lateness()
• Window-aware KPIs (ShopFloorKPIs, FleetKPIs) with a configurable warm-up

Reinforcement Learning Integration (experimental)

• Gymnasium wrapper (SimulatteEnv): subclass a single ABC to turn any simulation into a Gymnasium environment (from simulatte.experimental.gymnasium import SimulatteEnv)
• Can be used with Stable-Baselines3, CleanRL, and other Gymnasium-compatible RL libraries
• Built-in lifecycle guards, seeding support, and resource cleanup

Intralogistics

• Warehouse with per-SKU inventory, finite pick/put slots, input/output bays
• AGV fleet with trapezoidal speed profiles, battery lifecycle, and charging stations
• FleetCoordinator orchestrating dispatch, travel, pick, transit, deliver, reposition, and charge
• Pluggable policies: dispatch (NearestIdleStrategy, RoundRobinStrategy), repositioning, replenishment (ReorderPointPolicy), load recovery
• Time-series metrics with plot_fleet_utilization(), plot_throughput(), plot_pending_orders(), plot_inventory()
• Three progressive examples: simple setup, manufacturing plant floor, multi-warehouse distribution hub

Events, Traces and Logging

• Typed events with state deltas for every component (Server, ShopFloor, Router, Warehouse, AGV, traffic, charging), delivered on a per-environment event bus
• Per-environment RNG streams derived from the seed, a semantic digest and a run manifest for reproducibility
• TraceRecorder writes a run to a seekable trace file; Trace replays, seeks and verifies it
• Log sinks: text or JSON output, SQLite, and a queryable in-memory history with filtering by component, level, time range

Multi-Run Experiments

• Runner class for stochastic experiments across multiple seeds
• Automatic seed management for reproducibility
• Parallel execution with multiprocessing support
• Progress bars via tqdm

Installation

pip install simulatte

or with uv:

uv add simulatte

The base install includes production and intralogistics simulation, collectors, traces, and Runner. Plotting and reinforcement learning are optional:

pip install "simulatte[plot]"  # Collector plot_* methods and plotting examples
pip install "simulatte[rl]"    # Experimental SimulatteEnv Gymnasium wrapper
pip install "simulatte[all]"   # Both integrations

With uv, use uv add "simulatte[plot]", uv add "simulatte[rl]", or uv add "simulatte[all]". Starting in 0.13, existing applications that plot or use SimulatteEnv must select the corresponding extra. Collecting time series and KPIs does not require plotting dependencies.

Quick Start

from simulatte.environment import Environment
from simulatte.server import Server
from simulatte.shopfloor import ShopFloor
from simulatte.job import ProductionJob

# Create simulation environment
env = Environment()
shopfloor = ShopFloor(env=env)
server = Server(env=env, capacity=1, shopfloor=shopfloor)

# Create a job with routing through the server
job = ProductionJob(
    env=env,
    sku="A",
    servers=[server],
    processing_times=[5.0],
    due_date=100,
)

# Run simulation
shopfloor.add(job)
env.run()

# Analyze results
print(f"Makespan: {job.makespan}")
print(f"Server utilization: {server.utilization_rate:.1%}")

AI Coding Agent Skill

Simulatte ships a skill for AI coding agents (Claude Code, Cursor, Windsurf, etc.) that helps them write correct Simulatte simulations — from choosing a release policy to running multi-seed experiments.

Install it with the Vercel Skills CLI:

npx skills add https://github.com/dmezzogori/simulatte/tree/main/skills/simulatte-dev

Once installed, invoke it with /simulatte-dev or let the agent auto-trigger it when working with Simulatte code.

Documentation

Full documentation is available at simulatte.dev.

Citation

If you use Simulatte in your research, please cite it via its Zenodo record. The concept DOI 10.5281/zenodo.21027366 always resolves to the latest version; cite the version DOI 10.5281/zenodo.21027367 to pin v0.12.0.

@software{Mezzogori2026Simulatte,
  author  = {Mezzogori, Davide and Mercogliano, Nicola},
  title   = {{Simulatte}: A discrete-event simulation framework for production planning and control and intralogistics},
  year    = {2026},
  version = {0.14.0},
  doi     = {10.5281/zenodo.21027366},
  url     = {https://doi.org/10.5281/zenodo.21027366}
}

Contributing

Contributions are welcome — please read CONTRIBUTING.md for the workflow (branching, PR requirements, merge process).

License

Simulatte is released under the MIT License.