{"slug":"alterlab-simpy","title":"alterlab-simpy","summary":"Process-based discrete-event simulation in Python with SimPy — processes, queues, shared resources, and time-based events. Use when simulating systems where entities contend for shared resources over time, such as manufacturing systems, service operations, network traffic, or log","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-23T18:57:05.448763Z","repo":{"url":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","stars":68,"forks":13,"license":"MIT","updatedAt":"2026-09-23T13:42:59Z"},"bodyHtml":"
\n

name: alterlab-simpy\ndescription: Process-based discrete-event simulation in Python with SimPy — processes, queues, shared resources, and time-based events. Use when simulating systems where entities contend for shared resources over time, such as manufacturing systems, service operations, network traffic, or logistics. Part of the AlterLab Academic Skills suite.\nlicense: MIT\nallowed-tools: Read Write Edit Bash(python:) Bash(uv:)\ncompatibility: No API key required. Runs locally via uv run python; requires simpy 4.x (current 4.1.2 as of 2026-09; pure Python, no other dependencies).\nmetadata:\nskill-author: AlterLab\nversion: \"1.0.1\"\nlast_updated: \"2026-09-23\"

\n

SimPy - Discrete-Event Simulation

\n

Overview

\n

SimPy is a process-based discrete-event simulation framework based on standard Python. Use SimPy to model systems where entities (customers, vehicles, packets, etc.) interact with each other and compete for shared resources (servers, machines, bandwidth, etc.) over time.

\n

Core capabilities:

\n\n

When to Use This Skill

\n

Use the SimPy skill when:

\n
    \n
  1. Modeling discrete-event systems - Systems where events occur at irregular intervals
    2. \n
  2. Resource contention - Entities compete for limited resources (servers, machines, staff)
    3. \n
  3. Queue analysis - Studying waiting lines, service times, and throughput
    4. \n
  4. Process optimization - Analyzing manufacturing, logistics, or service processes
    5. \n
  5. Network simulation - Packet routing, bandwidth allocation, latency analysis
    6. \n
  6. Capacity planning - Determining optimal resource levels for desired performance
    7. \n
  7. System validation - Testing system behavior before implementation
    8. \n
\n

Not suitable for:

\n\n

Does NOT Trigger

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ScenarioUse Instead
Agent-based models of social systems with heterogeneous agents on grids or networks (segregation, opinion dynamics, diffusion)alterlab-abm-mesa
Searching for Pareto-optimal designs or parameters (e.g. cost vs. waiting time) with evolutionary algorithmsalterlab-pymoo
Fitting time-series or regression models to observed queue or throughput dataalterlab-statsmodels
Training a reinforcement-learning agent to control a systemalterlab-stable-baselines3
\n

Quick Start

\n

Basic Simulation Structure

\n
import simpy\n\ndef process(env, name):\n    \"\"\"A simple process that waits and prints.\"\"\"\n    print(f'{name} starting at {env.now}')\n    yield env.timeout(5)\n    print(f'{name} finishing at {env.now}')\n\n# Create environment\nenv = simpy.Environment()\n\n# Start processes\nenv.process(process(env, 'Process 1'))\nenv.process(process(env, 'Process 2'))\n\n# Run simulation\nenv.run(until=10)\n
\n

Resource Usage Pattern

\n
import simpy\n\ndef customer(env, name, resource):\n    \"\"\"Customer requests resource, uses it, then releases.\"\"\"\n    with resource.request() as req:\n        yield req  # Wait for resource\n        print(f'{name} got resource at {env.now}')\n        yield env.timeout(3)  # Use resource\n        print(f'{name} released resource at {env.now}')\n\nenv = simpy.Environment()\nserver = simpy.Resource(env, capacity=1)\n\nenv.process(customer(env, 'Customer 1', server))\nenv.process(customer(env, 'Customer 2', server))\nenv.run()\n
\n

Core Concepts

\n

1. Environment

\n

The simulation environment manages time and schedules events.

\n
import simpy\n\n# Standard environment (runs as fast as possible)\nenv = simpy.Environment(initial_time=0)\n\n# Real-time environment (synchronized with wall-clock)\nimport simpy.rt\nenv_rt = simpy.rt.RealtimeEnvironment(factor=1.0)\n\n# Run simulation\nenv.run(until=100)  # Run until time 100\nenv.run()  # Run until no events remain\n
\n

2. Processes

\n

Processes are defined using Python generator functions (functions with yield statements).

\n
def my_process(env, param1, param2):\n    \"\"\"Process that yields events to pause execution.\"\"\"\n    print(f'Starting at {env.now}')\n\n    # Wait for time to pass\n    yield env.timeout(5)\n\n    print(f'Resumed at {env.now}')\n\n    # Wait for another event\n    yield env.timeout(3)\n\n    print(f'Done at {env.now}')\n    return 'result'\n\n# Start the process\nenv.process(my_process(env, 'value1', 'value2'))\n
\n

3. Events

\n

Events are the fundamental mechanism for process synchronization. Processes yield events and resume when those events are triggered.

\n

Common event types:

\n\n

Resources

\n

SimPy provides several resource types for different scenarios. For comprehensive details, see references/resources.md.

\n

Resource Types Summary

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Resource TypeUse Case
ResourceLimited capacity (servers, machines)
PriorityResourcePriority-based queuing
PreemptiveResourceHigh-priority can interrupt low-priority
ContainerBulk materials (fuel, water)
StorePython object storage (FIFO)
FilterStoreSelective item retrieval
PriorityStorePriority-ordered items
\n

Quick Reference

\n
import simpy\n\nenv = simpy.Environment()\n\n# Basic resource (e.g., servers)\nresource = simpy.Resource(env, capacity=2)\n\n# Priority resource\npriority_resource = simpy.PriorityResource(env, capacity=1)\n\n# Container (e.g., fuel tank)\nfuel_tank = simpy.Container(env, capacity=100, init=50)\n\n# Store (e.g., warehouse)\nwarehouse = simpy.Store(env, capacity=10)\n
\n

Common Simulation Patterns

\n

Pattern 1: Customer-Server Queue

\n
import simpy\nimport random\n\ndef customer(env, name, server):\n    arrival = env.now\n    with server.request() as req:\n        yield req\n        wait = env.now - arrival\n        print(f'{name} waited {wait:.2f}, served at {env.now}')\n        yield env.timeout(random.uniform(2, 4))\n\ndef customer_generator(env, server):\n    i = 0\n    while True:\n        yield env.timeout(random.uniform(1, 3))\n        i += 1\n        env.process(customer(env, f'Customer {i}', server))\n\nenv = simpy.Environment()\nserver = simpy.Resource(env, capacity=2)\nenv.process(customer_generator(env, server))\nenv.run(until=20)\n
\n

Pattern 2: Producer-Consumer

\n
import simpy\n\ndef producer(env, store):\n    item_id = 0\n    while True:\n        yield env.timeout(2)\n        item = f'Item {item_id}'\n        yield store.put(item)\n        print(f'Produced {item} at {env.now}')\n        item_id += 1\n\ndef consumer(env, store):\n    while True:\n        item = yield store.get()\n        print(f'Consumed {item} at {env.now}')\n        yield env.timeout(3)\n\nenv = simpy.Environment()\nstore = simpy.Store(env, capacity=10)\nenv.process(producer(env, store))\nenv.process(consumer(env, store))\nenv.run(until=20)\n
\n

Pattern 3: Parallel Task Execution

\n
import simpy\n\ndef task(env, name, duration):\n    print(f'{name} starting at {env.now}')\n    yield env.timeout(duration)\n    print(f'{name} done at {env.now}')\n    return f'{name} result'\n\ndef coordinator(env):\n    # Start tasks in parallel\n    task1 = env.process(task(env, 'Task 1', 5))\n    task2 = env.process(task(env, 'Task 2', 3))\n    task3 = env.process(task(env, 'Task 3', 4))\n\n    # Wait for all to complete\n    results = yield task1 & task2 & task3\n    print(f'All done at {env.now}')\n\nenv = simpy.Environment()\nenv.process(coordinator(env))\nenv.run()\n
\n

Workflow Guide

\n

Step 1: Define the System

\n

Identify:

\n\n

Step 2: Implement Process Functions

\n

Create generator functions for each process type:

\n
def entity_process(env, name, resources, parameters):\n    # Arrival logic\n    arrival_time = env.now\n\n    # Request resources\n    with resource.request() as req:\n        yield req\n\n        # Service logic\n        service_time = calculate_service_time(parameters)\n        yield env.timeout(service_time)\n\n    # Departure logic\n    collect_statistics(env.now - arrival_time)\n
\n

Step 3: Set Up Monitoring

\n

Use monitoring utilities to collect data. See references/monitoring.md for comprehensive techniques.

\n
from scripts.resource_monitor import ResourceMonitor\n\n# Create and monitor resource\nresource = simpy.Resource(env, capacity=2)\nmonitor = ResourceMonitor(env, resource, \"Server\")\n\n# After simulation\nmonitor.report()\n
\n

Step 4: Run and Analyze

\n
# Run simulation\nenv.run(until=simulation_time)\n\n# Generate reports\nmonitor.report()\nstats.report()\n\n# Export data for further analysis\nmonitor.export_csv('results.csv')\n
\n

Advanced Features

\n

Process Interaction

\n

Processes can interact through events, process yields, and interrupts. See references/process-interaction.md for detailed patterns.

\n

Key mechanisms:

\n\n

Real-Time Simulations

\n

Synchronize simulation with wall-clock time for hardware-in-the-loop or interactive applications. See references/real-time.md.

\n
import simpy.rt\n\nenv = simpy.rt.RealtimeEnvironment(factor=1.0)  # 1:1 time mapping\n# factor=0.5 means 1 sim unit = 0.5 seconds (2x faster)\n
\n

Comprehensive Monitoring

\n

Monitor processes, resources, and events. See references/monitoring.md for techniques including:

\n\n

Scripts and Templates

\n

basic_simulation_template.py

\n

Complete template for building queue simulations with:

\n\n

Usage:

\n
from scripts.basic_simulation_template import SimulationConfig, run_simulation\n\nconfig = SimulationConfig()\nconfig.num_resources = 2\nconfig.sim_time = 100\nstats = run_simulation(config)\nstats.report()\n
\n

resource_monitor.py

\n

Reusable monitoring utilities:

\n\n

Usage:

\n
from scripts.resource_monitor import ResourceMonitor\n\nmonitor = ResourceMonitor(env, resource, \"My Resource\")\n# ... run simulation ...\nmonitor.report()\nmonitor.export_csv('data.csv')\n
\n

Import note: these from scripts.... paths are relative to the skill directory. Copy the script next to your simulation, or add the skill directory to PYTHONPATH before importing.

\n

Reference Documentation

\n

Detailed guides, loaded on demand:

\n\n

Best Practices

\n
    \n
  1. Generator functions: Always use yield in process functions
    2. \n
  2. Resource context managers: Use with resource.request() as req: for automatic cleanup
    3. \n
  3. Reproducibility: Set random.seed() for consistent results
    4. \n
  4. Monitoring: Collect data throughout simulation, not just at the end
    5. \n
  5. Validation: Compare simple cases with analytical solutions
    6. \n
  6. Documentation: Comment process logic and parameter choices
    7. \n
  7. Modular design: Separate process logic, statistics, and configuration
    8. \n
\n

Common Pitfalls

\n
    \n
  1. Forgetting yield: Processes must yield events to pause
    2. \n
  2. Event reuse: Events can only be triggered once
    3. \n
  3. Resource leaks: Use context managers or ensure release
    4. \n
  4. Blocking operations: Avoid Python blocking calls in processes
    5. \n
  5. Time units: Stay consistent with time unit interpretation
    6. \n
  6. Deadlocks: Ensure at least one process can make progress
    7. \n
\n

Example Use Cases

\n\n

Part of the AlterLab Academic Skills suite.

\n","files":[{"path":"evals/evals.json","sizeBytes":5179,"isText":true},{"path":"references/events.md","sizeBytes":8579,"isText":true},{"path":"references/monitoring.md","sizeBytes":12923,"isText":true},{"path":"references/process-interaction.md","sizeBytes":11525,"isText":true},{"path":"references/real-time.md","sizeBytes":10728,"isText":true},{"path":"references/resources.md","sizeBytes":7327,"isText":true},{"path":"scripts/basic_simulation_template.py","sizeBytes":5773,"isText":true},{"path":"scripts/resource_monitor.py","sizeBytes":11644,"isText":true},{"path":"SKILL.md","sizeBytes":13266,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-23T18:59:00.840474Z","sha256":"5B4E9FA8264AC99DABC78D7D6864C0763B1D71BA0BD90B6E09746FFA18A4C83C","sizeBytes":26122},"review":null,"source":{"repositoryUrl":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","path":"skills/data-science/alterlab-simpy","license":"MIT","commit":"e4836c08a20da195a11f30f203a8cf23ec30aa95","subtreeSha":"CDF1DF50C0E1CD52E3DA7F2959DCB3471225505FDC5E096C0AABE9131797FF9E","lastSyncedAt":"2026-09-23T18:56:52.297238Z"},"reviewedAt":"2026-09-23T19:02:50.109581Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/data-science/alterlab-simpy"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart"},{"target":"git","command":"git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git"}]}