simulatte 0.5.0

A discrete-event simulation framework for intralogistics and operations management

Simulatte

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

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
• 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 metrics collectors: plug in your own real-time or time-series collectors

Time-Series Analysis

• Built-in collectors for WIP, throughput, job count, lateness
• Matplotlib integration: plot_wip(), plot_throughput(), plot_lateness()
• Custom time-series collectors via simple protocol

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

Material Handling (experimental)

• Warehouse with inventory management
• AGV fleet coordination
• FIFO blocking semantics for realistic material flow

Logging

• Per-component event logging (Server, ShopFloor, Router, Warehouse, AGV)
• JSON or text format output
• 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

---

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:

@software{Mezzogori2025Simulatte,
  author = {Mezzogori, Davide and Mercogliano, Nicola},
  title = {{Simulatte}: A discrete-event simulation framework for production planning and control and intralogistics},
  year = {2025},
  url = {https://github.com/dmezzogori/simulatte},
  note = {Python package version 0.5.0}
}

---

Contributing

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

---

License

Simulatte is released under the MIT License.