@synsci/cli-darwin-x64-baseline 1.1.77 → 1.1.78

package/bin/skills/simpy/references/real-time.md

@@ -0,0 +1,395 @@
+# SimPy Real-Time Simulations
+
+This guide covers real-time simulation capabilities in SimPy, where simulation time is synchronized with wall-clock time.
+
+## Overview
+
+Real-time simulations synchronize simulation time with actual wall-clock time. This is useful for:
+
+- **Hardware-in-the-loop (HIL)** testing
+- **Human interaction** with simulations
+- **Algorithm behavior analysis** under real-time constraints
+- **System integration** testing
+- **Demonstration** purposes
+
+## RealtimeEnvironment
+
+Replace the standard `Environment` with `simpy.rt.RealtimeEnvironment` to enable real-time synchronization.
+
+### Basic Usage
+
+```python
+import simpy.rt
+
+def process(env):
+    while True:
+        print(f'Tick at {env.now}')
+        yield env.timeout(1)
+
+# Real-time environment with 1:1 time mapping
+env = simpy.rt.RealtimeEnvironment(factor=1.0)
+env.process(process(env))
+env.run(until=5)
+```
+
+### Constructor Parameters
+
+```python
+simpy.rt.RealtimeEnvironment(
+    initial_time=0,      # Starting simulation time
+    factor=1.0,          # Real time per simulation time unit
+    strict=True          # Raise errors on timing violations
+)
+```
+
+## Time Scaling with Factor
+
+The `factor` parameter controls how simulation time maps to real time.
+
+### Factor Examples
+
+```python
+import simpy.rt
+import time
+
+def timed_process(env, label):
+    start = time.time()
+    print(f'{label}: Starting at {env.now}')
+    yield env.timeout(2)
+    elapsed = time.time() - start
+    print(f'{label}: Completed at {env.now} (real time: {elapsed:.2f}s)')
+
+# Factor = 1.0: 1 simulation time unit = 1 second
+print('Factor = 1.0 (2 sim units = 2 seconds)')
+env = simpy.rt.RealtimeEnvironment(factor=1.0)
+env.process(timed_process(env, 'Normal speed'))
+env.run()
+
+# Factor = 0.5: 1 simulation time unit = 0.5 seconds
+print('\nFactor = 0.5 (2 sim units = 1 second)')
+env = simpy.rt.RealtimeEnvironment(factor=0.5)
+env.process(timed_process(env, 'Double speed'))
+env.run()
+
+# Factor = 2.0: 1 simulation time unit = 2 seconds
+print('\nFactor = 2.0 (2 sim units = 4 seconds)')
+env = simpy.rt.RealtimeEnvironment(factor=2.0)
+env.process(timed_process(env, 'Half speed'))
+env.run()
+```
+
+**Factor interpretation:**
+- `factor=1.0` → 1 simulation time unit takes 1 real second
+- `factor=0.1` → 1 simulation time unit takes 0.1 real seconds (10x faster)
+- `factor=60` → 1 simulation time unit takes 60 real seconds (1 minute)
+
+## Strict Mode
+
+### strict=True (Default)
+
+Raises `RuntimeError` if computation exceeds allocated real-time budget.
+
+```python
+import simpy.rt
+import time
+
+def heavy_computation(env):
+    print(f'Starting computation at {env.now}')
+    yield env.timeout(1)
+
+    # Simulate heavy computation (exceeds 1 second budget)
+    time.sleep(1.5)
+
+    print(f'Computation done at {env.now}')
+
+env = simpy.rt.RealtimeEnvironment(factor=1.0, strict=True)
+env.process(heavy_computation(env))
+
+try:
+    env.run()
+except RuntimeError as e:
+    print(f'Error: {e}')
+```
+
+### strict=False
+
+Allows simulation to run slower than intended without crashing.
+
+```python
+import simpy.rt
+import time
+
+def heavy_computation(env):
+    print(f'Starting at {env.now}')
+    yield env.timeout(1)
+
+    # Heavy computation
+    time.sleep(1.5)
+
+    print(f'Done at {env.now}')
+
+env = simpy.rt.RealtimeEnvironment(factor=1.0, strict=False)
+env.process(heavy_computation(env))
+env.run()
+
+print('Simulation completed (slower than real-time)')
+```
+
+**Use strict=False when:**
+- Development and debugging
+- Computation time is unpredictable
+- Acceptable to run slower than target rate
+- Analyzing worst-case behavior
+
+## Hardware-in-the-Loop Example
+
+```python
+import simpy.rt
+
+class HardwareInterface:
+    """Simulated hardware interface."""
+
+    def __init__(self):
+        self.sensor_value = 0
+
+    def read_sensor(self):
+        """Simulate reading from hardware sensor."""
+        import random
+        self.sensor_value = random.uniform(20.0, 30.0)
+        return self.sensor_value
+
+    def write_actuator(self, value):
+        """Simulate writing to hardware actuator."""
+        print(f'Actuator set to {value:.2f}')
+
+def control_loop(env, hardware, setpoint):
+    """Simple control loop running in real-time."""
+    while True:
+        # Read sensor
+        sensor_value = hardware.read_sensor()
+        print(f'[{env.now}] Sensor: {sensor_value:.2f}°C')
+
+        # Simple proportional control
+        error = setpoint - sensor_value
+        control_output = error * 0.1
+
+        # Write actuator
+        hardware.write_actuator(control_output)
+
+        # Control loop runs every 0.5 seconds
+        yield env.timeout(0.5)
+
+# Real-time environment: 1 sim unit = 1 second
+env = simpy.rt.RealtimeEnvironment(factor=1.0, strict=False)
+hardware = HardwareInterface()
+setpoint = 25.0
+
+env.process(control_loop(env, hardware, setpoint))
+env.run(until=5)
+```
+
+## Human Interaction Example
+
+```python
+import simpy.rt
+
+def interactive_process(env):
+    """Process that waits for simulated user input."""
+    print('Simulation started. Events will occur in real-time.')
+
+    yield env.timeout(2)
+    print(f'[{env.now}] Event 1: System startup')
+
+    yield env.timeout(3)
+    print(f'[{env.now}] Event 2: Initialization complete')
+
+    yield env.timeout(2)
+    print(f'[{env.now}] Event 3: Ready for operation')
+
+# Real-time environment for human-paced demonstration
+env = simpy.rt.RealtimeEnvironment(factor=1.0)
+env.process(interactive_process(env))
+env.run()
+```
+
+## Monitoring Real-Time Performance
+
+```python
+import simpy.rt
+import time
+
+class RealTimeMonitor:
+    def __init__(self):
+        self.step_times = []
+        self.drift_values = []
+
+    def record_step(self, sim_time, real_time, expected_real_time):
+        self.step_times.append(sim_time)
+        drift = real_time - expected_real_time
+        self.drift_values.append(drift)
+
+    def report(self):
+        if self.drift_values:
+            avg_drift = sum(self.drift_values) / len(self.drift_values)
+            max_drift = max(abs(d) for d in self.drift_values)
+            print(f'\nReal-time performance:')
+            print(f'Average drift: {avg_drift*1000:.2f} ms')
+            print(f'Maximum drift: {max_drift*1000:.2f} ms')
+
+def monitored_process(env, monitor, start_time, factor):
+    for i in range(5):
+        step_start = time.time()
+        yield env.timeout(1)
+
+        real_elapsed = time.time() - start_time
+        expected_elapsed = env.now * factor
+        monitor.record_step(env.now, real_elapsed, expected_elapsed)
+
+        print(f'Sim time: {env.now}, Real time: {real_elapsed:.2f}s, ' +
+              f'Expected: {expected_elapsed:.2f}s')
+
+start = time.time()
+factor = 1.0
+env = simpy.rt.RealtimeEnvironment(factor=factor, strict=False)
+monitor = RealTimeMonitor()
+
+env.process(monitored_process(env, monitor, start, factor))
+env.run()
+monitor.report()
+```
+
+## Mixed Real-Time and Fast Simulation
+
+```python
+import simpy.rt
+
+def background_simulation(env):
+    """Fast background simulation."""
+    for i in range(100):
+        yield env.timeout(0.01)
+    print(f'Background simulation completed at {env.now}')
+
+def real_time_display(env):
+    """Real-time display updates."""
+    for i in range(5):
+        print(f'Display update at {env.now}')
+        yield env.timeout(1)
+
+# Note: This is conceptual - SimPy doesn't directly support mixed modes
+# Consider running separate simulations or using strict=False
+env = simpy.rt.RealtimeEnvironment(factor=1.0, strict=False)
+env.process(background_simulation(env))
+env.process(real_time_display(env))
+env.run()
+```
+
+## Converting Standard to Real-Time
+
+Converting a standard simulation to real-time is straightforward:
+
+```python
+import simpy
+import simpy.rt
+
+def process(env):
+    print(f'Event at {env.now}')
+    yield env.timeout(1)
+    print(f'Event at {env.now}')
+    yield env.timeout(1)
+    print(f'Event at {env.now}')
+
+# Standard simulation (runs instantly)
+print('Standard simulation:')
+env = simpy.Environment()
+env.process(process(env))
+env.run()
+
+# Real-time simulation (2 real seconds)
+print('\nReal-time simulation:')
+env_rt = simpy.rt.RealtimeEnvironment(factor=1.0)
+env_rt.process(process(env_rt))
+env_rt.run()
+```
+
+## Best Practices
+
+1. **Factor selection**: Choose factor based on hardware/human constraints
+   - Human interaction: `factor=1.0` (1:1 time mapping)
+   - Fast hardware: `factor=0.01` (100x faster)
+   - Slow processes: `factor=60` (1 sim unit = 1 minute)
+
+2. **Strict mode usage**:
+   - Use `strict=True` for timing validation
+   - Use `strict=False` for development and variable workloads
+
+3. **Computation budget**: Ensure process logic executes faster than timeout duration
+
+4. **Error handling**: Wrap real-time runs in try-except for timing violations
+
+5. **Testing strategy**:
+   - Develop with standard Environment (fast iteration)
+   - Test with RealtimeEnvironment (validation)
+   - Deploy with appropriate factor and strict settings
+
+6. **Performance monitoring**: Track drift between simulation and real time
+
+7. **Graceful degradation**: Use `strict=False` when timing guarantees aren't critical
+
+## Common Patterns
+
+### Periodic Real-Time Tasks
+
+```python
+import simpy.rt
+
+def periodic_task(env, name, period, duration):
+    """Task that runs periodically in real-time."""
+    while True:
+        start = env.now
+        print(f'{name}: Starting at {start}')
+
+        # Simulate work
+        yield env.timeout(duration)
+
+        print(f'{name}: Completed at {env.now}')
+
+        # Wait for next period
+        elapsed = env.now - start
+        wait_time = period - elapsed
+        if wait_time > 0:
+            yield env.timeout(wait_time)
+
+env = simpy.rt.RealtimeEnvironment(factor=1.0)
+env.process(periodic_task(env, 'Task', period=2.0, duration=0.5))
+env.run(until=6)
+```
+
+### Synchronized Multi-Device Control
+
+```python
+import simpy.rt
+
+def device_controller(env, device_id, update_rate):
+    """Control loop for individual device."""
+    while True:
+        print(f'Device {device_id}: Update at {env.now}')
+        yield env.timeout(update_rate)
+
+# All devices synchronized to real-time
+env = simpy.rt.RealtimeEnvironment(factor=1.0)
+
+# Different update rates for different devices
+env.process(device_controller(env, 'A', 1.0))
+env.process(device_controller(env, 'B', 0.5))
+env.process(device_controller(env, 'C', 2.0))
+
+env.run(until=5)
+```
+
+## Limitations
+
+1. **Performance**: Real-time simulation adds overhead; not suitable for high-frequency events
+2. **Synchronization**: Single-threaded; all processes share same time base
+3. **Precision**: Limited by Python's time resolution and system scheduling
+4. **Strict mode**: May raise errors frequently with computationally intensive processes
+5. **Platform-dependent**: Timing accuracy varies across operating systems

package/bin/skills/simpy/references/resources.md

@@ -0,0 +1,275 @@
+# SimPy Shared Resources
+
+This guide covers all resource types in SimPy for modeling congestion points and resource allocation.
+
+## Resource Types Overview
+
+SimPy provides three main categories of shared resources:
+
+1. **Resources** - Limited capacity resources (e.g., gas pumps, servers)
+2. **Containers** - Homogeneous bulk materials (e.g., fuel tanks, silos)
+3. **Stores** - Python object storage (e.g., item queues, warehouses)
+
+## 1. Resources
+
+Model resources that can be used by a limited number of processes at a time.
+
+### Resource (Basic)
+
+The basic resource is a semaphore with specified capacity.
+
+```python
+import simpy
+
+env = simpy.Environment()
+resource = simpy.Resource(env, capacity=2)
+
+def process(env, resource, name):
+    with resource.request() as req:
+        yield req
+        print(f'{name} has the resource at {env.now}')
+        yield env.timeout(5)
+        print(f'{name} releases the resource at {env.now}')
+
+env.process(process(env, resource, 'Process 1'))
+env.process(process(env, resource, 'Process 2'))
+env.process(process(env, resource, 'Process 3'))
+env.run()
+```
+
+**Key properties:**
+- `capacity` - Maximum number of concurrent users (default: 1)
+- `count` - Current number of users
+- `queue` - List of queued requests
+
+### PriorityResource
+
+Extends basic resource with priority levels (lower numbers = higher priority).
+
+```python
+import simpy
+
+env = simpy.Environment()
+resource = simpy.PriorityResource(env, capacity=1)
+
+def process(env, resource, name, priority):
+    with resource.request(priority=priority) as req:
+        yield req
+        print(f'{name} (priority {priority}) has the resource at {env.now}')
+        yield env.timeout(5)
+
+env.process(process(env, resource, 'Low priority', priority=10))
+env.process(process(env, resource, 'High priority', priority=1))
+env.run()
+```
+
+**Use cases:**
+- Emergency services (ambulances before regular vehicles)
+- VIP customer queues
+- Job scheduling with priorities
+
+### PreemptiveResource
+
+Allows high-priority requests to interrupt lower-priority users.
+
+```python
+import simpy
+
+env = simpy.Environment()
+resource = simpy.PreemptiveResource(env, capacity=1)
+
+def process(env, resource, name, priority):
+    with resource.request(priority=priority) as req:
+        try:
+            yield req
+            print(f'{name} acquired resource at {env.now}')
+            yield env.timeout(10)
+            print(f'{name} finished at {env.now}')
+        except simpy.Interrupt:
+            print(f'{name} was preempted at {env.now}')
+
+env.process(process(env, resource, 'Low priority', priority=10))
+env.process(process(env, resource, 'High priority', priority=1))
+env.run()
+```
+
+**Use cases:**
+- Operating system CPU scheduling
+- Emergency room triage
+- Network packet prioritization
+
+## 2. Containers
+
+Model production and consumption of homogeneous bulk materials (continuous or discrete).
+
+```python
+import simpy
+
+env = simpy.Environment()
+container = simpy.Container(env, capacity=100, init=50)
+
+def producer(env, container):
+    while True:
+        yield env.timeout(5)
+        yield container.put(20)
+        print(f'Produced 20. Level: {container.level}')
+
+def consumer(env, container):
+    while True:
+        yield env.timeout(7)
+        yield container.get(15)
+        print(f'Consumed 15. Level: {container.level}')
+
+env.process(producer(env, container))
+env.process(consumer(env, container))
+env.run(until=50)
+```
+
+**Key properties:**
+- `capacity` - Maximum amount (default: float('inf'))
+- `level` - Current amount
+- `init` - Initial amount (default: 0)
+
+**Operations:**
+- `put(amount)` - Add to container (blocks if full)
+- `get(amount)` - Remove from container (blocks if insufficient)
+
+**Use cases:**
+- Gas station fuel tanks
+- Buffer storage in manufacturing
+- Water reservoirs
+- Battery charge levels
+
+## 3. Stores
+
+Model production and consumption of Python objects.
+
+### Store (Basic)
+
+Generic FIFO object storage.
+
+```python
+import simpy
+
+env = simpy.Environment()
+store = simpy.Store(env, capacity=2)
+
+def producer(env, store):
+    for i in range(5):
+        yield env.timeout(2)
+        item = f'Item {i}'
+        yield store.put(item)
+        print(f'Produced {item} at {env.now}')
+
+def consumer(env, store):
+    while True:
+        yield env.timeout(3)
+        item = yield store.get()
+        print(f'Consumed {item} at {env.now}')
+
+env.process(producer(env, store))
+env.process(consumer(env, store))
+env.run()
+```
+
+**Key properties:**
+- `capacity` - Maximum number of items (default: float('inf'))
+- `items` - List of stored items
+
+**Operations:**
+- `put(item)` - Add item to store (blocks if full)
+- `get()` - Remove and return item (blocks if empty)
+
+### FilterStore
+
+Allows retrieval of specific objects based on filter functions.
+
+```python
+import simpy
+
+env = simpy.Environment()
+store = simpy.FilterStore(env, capacity=10)
+
+def producer(env, store):
+    for color in ['red', 'blue', 'green', 'red', 'blue']:
+        yield env.timeout(1)
+        yield store.put({'color': color, 'time': env.now})
+        print(f'Produced {color} item at {env.now}')
+
+def consumer(env, store, color):
+    while True:
+        yield env.timeout(2)
+        item = yield store.get(lambda x: x['color'] == color)
+        print(f'{color} consumer got item from {item["time"]} at {env.now}')
+
+env.process(producer(env, store))
+env.process(consumer(env, store, 'red'))
+env.process(consumer(env, store, 'blue'))
+env.run(until=15)
+```
+
+**Use cases:**
+- Warehouse item picking (specific SKUs)
+- Job queues with skill matching
+- Packet routing by destination
+
+### PriorityStore
+
+Items retrieved in priority order (lowest first).
+
+```python
+import simpy
+
+class PriorityItem:
+    def __init__(self, priority, data):
+        self.priority = priority
+        self.data = data
+
+    def __lt__(self, other):
+        return self.priority < other.priority
+
+env = simpy.Environment()
+store = simpy.PriorityStore(env, capacity=10)
+
+def producer(env, store):
+    items = [(10, 'Low'), (1, 'High'), (5, 'Medium')]
+    for priority, name in items:
+        yield env.timeout(1)
+        yield store.put(PriorityItem(priority, name))
+        print(f'Produced {name} priority item')
+
+def consumer(env, store):
+    while True:
+        yield env.timeout(5)
+        item = yield store.get()
+        print(f'Retrieved {item.data} priority item')
+
+env.process(producer(env, store))
+env.process(consumer(env, store))
+env.run()
+```
+
+**Use cases:**
+- Task scheduling
+- Print job queues
+- Message prioritization
+
+## Choosing the Right Resource Type
+
+| Scenario | Resource Type |
+|----------|---------------|
+| Limited servers/machines | Resource |
+| Priority-based queuing | PriorityResource |
+| Preemptive scheduling | PreemptiveResource |
+| Fuel, water, bulk materials | Container |
+| Generic item queue (FIFO) | Store |
+| Selective item retrieval | FilterStore |
+| Priority-ordered items | PriorityStore |
+
+## Best Practices
+
+1. **Capacity planning**: Set realistic capacities based on system constraints
+2. **Request patterns**: Use context managers (`with resource.request()`) for automatic cleanup
+3. **Error handling**: Wrap preemptive resources in try-except for Interrupt handling
+4. **Monitoring**: Track queue lengths and utilization (see monitoring.md)
+5. **Performance**: FilterStore and PriorityStore have O(n) retrieval time; use wisely for large stores