SimpyLens: Simpy Visualization and Debugging Toolkit

SimpyLens is a low-intrusion toolkit for SimPy model visualization, debugging, and runtime inspection. It helps developers understand queueing behavior, resource contention, and process flow in real time without rewriting simulation business logic.

SimPy Visual Demos

Full Simulation Debugging Workflow

assets/pottery_factory.gif shows the full SimpyLens interface for discrete-event simulation debugging: runtime controls, process flow, resource movement, and live inspection. It is useful for users searching for a SimPy visual debugger, queueing simulation viewer, or simulation runtime inspection tool.

Manual Resource Layout for Process Storytelling

assets/manual_layout.gif demonstrates manual resource positioning so teams can present and analyze process flow with a clearer mental model. This is especially relevant for simulation demos, teaching, and operations reviews where layout readability matters.

Key Features

• Real-time visualization for SimPy resources and process interactions.
• Runtime controls for play, step, pause, reset, and speed.
• Breakpoints with expression/callable conditions and edge modes.
• Structured logs for simulation, step lifecycle, resources, and breakpoints.
• Headless mode for tests and CI.
• Optional metrics collection with read-only resource metrics.

Installation

pip install simpylens

Quickstart

import simpy
import simpylens


def model(env):
    server = simpy.Resource(env, capacity=1)

    def customer():
        with server.request() as req:
            yield req
            yield env.timeout(3)

    env.process(customer())


lens = simpylens.Lens(model=model, gui=True, seed=42)
lens.show()

SimPy Examples Included

Examples are in examples/ and grouped by origin.

Adapted from official simpy examples/tutorial lineage:

• examples/bank_renege.py
• examples/gas_station_refueling.py

Original SimpyLens examples:

• examples/pottery_factory.py
• examples/wafer_fabrication.py

FAQ

Is SimpyLens a SimPy debugger?

Yes. SimpyLens provides breakpoint-based debugging, structured event logs, and step-by-step runtime inspection for SimPy simulations.

Can I visualize SimPy resources in real time?

Yes. SimpyLens visualizes Resource, Container, and Store families, including queue/load behavior and process flow.

Can SimpyLens run in headless mode for automated testing?

Yes. Use Lens(gui=False) to run simulations and assertions in tests or CI pipelines.

Does SimpyLens require rewriting my simulation model?

No. SimpyLens is designed for low-intrusion integration with your existing SimPy setup function.

Contributing

Contributions are welcome.

Suggested workflow:

1. Fork the repository.
2. Create a feature branch.
3. Add or update tests and examples.
4. Submit a pull request with a clear change description.

Documentation

• Architecture
• API Reference
• Logging Schema