@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/simpy/references/events.md

@@ -1,225 +0,0 @@
-# Events, environments, and scheduling
-
-Verified 2026-07-23 against SimPy 4.1.2 documentation and tagged source.
-
-## Scheduler model
-
-`Environment` owns a single event queue and processes one event at a time. Tagged
-4.1.2 stores queue entries as `(time, priority, event_id, event)`:
-
-1. smallest simulation time first;
-2. smallest numeric priority first (`URGENT=0`, `NORMAL=1` in public event APIs);
-3. smallest strictly increasing event ID first.
-
-Thus same-time, same-priority events are FIFO by scheduling order. This is
-deterministic sequential execution, even when model processes represent concurrent
-activities. Floating-point discretization can collapse physically distinct times
-onto the same value, so test tie behavior explicitly.
-
-## Event lifecycle
-
-An `Event` moves once through:
-
-1. **not triggered** — not scheduled and no value;
-2. **triggered** — outcome/value fixed and scheduled; `event.triggered` is true;
-3. **processed** — removed for callback execution; `event.processed` is true when
-   `event.callbacks is None`.
-
-```python
-import simpy
-
-env = simpy.Environment()
-event = env.event()
-assert not event.triggered and not event.processed
-
-event.succeed("ready")
-assert event.triggered and not event.processed
-
-env.step()
-assert event.processed and event.value == "ready"
-```
-
-`event.succeed(value)` and `event.fail(exception)` return that event and may be
-called only once. In 4.1.2 `fail()` requires an `Exception`. `event.trigger(other)`
-copies the other event's success/failure and value, and returns `None`.
-
-A failed event throws its exception into a waiting process. If no process or
-callback defuses it, `Environment.step()` raises it. Treat private `_ok`, `_value`,
-and `_defused` as implementation details.
-
-## Callbacks
-
-Before processing, `event.callbacks` is a mutable list of one-argument callables.
-Yielding an event adds the waiting process's resume method. Processing executes
-callbacks in list order. Once fully processed, callbacks becomes `None`; appending
-then is invalid.
-
-```python
-log = []
-timeout = env.timeout(2, value=7)
-timeout.callbacks.append(lambda completed: log.append(completed.value))
-env.run()
-assert log == [7]
-```
-
-Keep callbacks short and non-blocking. A callback runs synchronously inside
-`Environment.step()` and can affect scheduler latency.
-
-## Timeout
-
-`env.timeout(delay, value=None)` creates a `Timeout`, immediately triggers it, and
-schedules it at `env.now + delay`. Because it is already triggered at construction,
-do not call `succeed()` or `fail()` on it.
-
-```python
-def timer(env):
-    result = yield env.timeout(3, value="elapsed")
-    assert result == "elapsed"
-```
-
-Reject negative delay. Use a consistent numeric time unit; SimPy does not attach
-units or protect against incompatible scales.
-
-## Process
-
-`env.process(generator)` requires a **generator object**, not an ordinary function
-result. It schedules an urgent `Initialize` event. Each yielded event suspends the
-generator; after the event's outcome, SimPy sends its value back or throws its
-failure into the generator.
-
-```python
-def child(env):
-    yield env.timeout(1)
-    return 42
-
-def parent(env):
-    child_process = env.process(child(env))
-    result = yield child_process
-    assert result == 42
-
-env = simpy.Environment()
-env.process(parent(env))
-env.run()
-```
-
-A `Process` is itself an event. It succeeds with the generator's return value or
-fails with an uncaught exception. `process.is_alive`, `process.target`, and
-`process.name` expose its current status.
-
-Common mistakes:
-
-- `env.process(worker)` instead of `env.process(worker(env))`;
-- a function without any reachable `yield`, which is not a generator;
-- performing blocking I/O or `time.sleep()` inside a normal Environment process;
-- yielding a number rather than an Event.
-
-## Condition events
-
-`AnyOf(env, events)` / `a | b` and `AllOf(env, events)` / `a & b` return a
-`Condition`. Yielding one produces a `ConditionValue`, an ordered dict-like mapping
-whose keys are the original Event objects and whose values are their values.
-
-```python
-def coordinate(env):
-    fast = env.timeout(1, value="fast")
-    slow = env.timeout(2, value="slow")
-
-    first = yield fast | slow
-    assert fast in first
-    assert first[fast] == "fast"
-
-    both = yield fast & slow
-    assert list(both.items()) == [(fast, "fast"), (slow, "slow")]
-```
-
-For `AllOf`, all input events appear. For `AnyOf`, all target events that occurred
-before the condition itself is processed can appear; do not assume exactly one
-winner when events tie. Input order determines result order.
-
-If any input event fails before the condition succeeds, `AnyOf` and `AllOf` fail.
-Conditions can be nested. `AnyOf` does **not** cancel losing events:
-
-```python
-with resource.request() as request:
-    patience = env.timeout(5)
-    result = yield request | patience
-    if request not in result:
-        # Context-manager exit cancels the still-pending request.
-        return
-    yield env.timeout(2)
-```
-
-An ordinary losing timeout remains scheduled. This is usually harmless but matters
-for event counts and traces.
-
-## `Environment.run()` boundaries
-
-### No criterion
-
-`env.run()` stops only when the event queue is empty. An endless generator such as
-`while True: yield env.timeout(1)` makes it nonterminating.
-
-### Numeric criterion
-
-`env.run(until=10)` creates an internal urgent stop event at time 10. It advances
-`env.now` to 10 but does **not** process ordinary events scheduled exactly at 10:
-
-```python
-env = simpy.Environment()
-boundary = env.timeout(10)
-env.run(until=10)
-assert env.now == 10
-assert not boundary.processed
-```
-
-The numeric target must be strictly greater than `env.now`.
-
-### Event criterion
-
-`env.run(until=event)` attaches a stop callback and returns the event value when
-that callback fires. It raises `RuntimeError` if the schedule empties before the
-criterion is triggered.
-
-Important 4.1.2 implementation detail: `Environment.step()` catches
-`StopSimulation`, preserves callbacks after the stopping callback, and reschedules
-the event at priority `-1`. Since `processed` means callbacks is `None`, the target
-can still report `processed == False` immediately after `run()` returns:
-
-```python
-env = simpy.Environment()
-target = env.timeout(5, value="done")
-assert env.run(until=target) == "done"
-assert target.triggered
-assert not target.processed
-env.step()
-assert target.processed
-```
-
-This behavior follows tagged 4.1.2 `simpy/core.py`; the topical guide's informal
-"processed" wording is not a safe postcondition. Depend on the returned value and
-your model state, not solely on `processed`.
-
-A timeout event and a numeric time can reach the same clock value but differ in
-same-time ordering. Numeric stopping is the clearer half-open horizon.
-
-## Manual stepping
-
-```python
-until = 10
-steps = 0
-max_steps = 100_000
-while env.peek() < until and steps < max_steps:
-    env.step()
-    steps += 1
-if steps == max_steps:
-    raise RuntimeError("event budget reached")
-```
-
-`peek()` returns infinity when empty; `step()` raises `simpy.core.EmptySchedule`
-when no event remains. Explicit step/event caps prevent a zero-delay loop from
-hanging diagnostics.
-
-## Sources
-
-See `sources.md` for versioned environment/event guides, API references, tagged
-`core.py`, and the scheduling guide.

package/skills/simpy/references/monitoring.md

@@ -1,260 +0,0 @@
-# Monitoring, tracing, and stepping
-
-Verified 2026-07-23 against SimPy 4.1.2.
-
-Monitoring is model instrumentation, not an automatic statistical analysis. Define:
-
-1. the estimand/state (queue waiting only, users in service, total in system);
-2. the observation instant (before request, after request, grant, release, final);
-3. the aggregation rule (time average, entity average, count, quantile);
-4. the analysis window and warm-up;
-5. memory/trace caps.
-
-## Prefer explicit domain observations
-
-Record domain events where their meaning is unambiguous:
-
-```python
-def customer(env, resource, log):
-    arrival = env.now
-    log.append({"event": "arrival", "time": env.now})
-    with resource.request() as request:
-        yield request
-        log.append(
-            {
-                "event": "service_start",
-                "queue_wait": env.now - arrival,
-                "time": env.now,
-            }
-        )
-        yield env.timeout(2)
-    log.append({"event": "departure", "time": env.now})
-```
-
-Entity-average wait and time-average queue length are different estimands.
-
-## Why queue samples are timing-sensitive
-
-For `Resource.request()`:
-
-- before the method: the new request is absent;
-- immediately after: an available slot may already be allocated, or the request is
-  in `queue`;
-- when the request Event is processed: waiting Process callbacks run;
-- during release: a queued request may be granted synchronously before the release
-  Event's callbacks finish.
-
-Several states may therefore exist at the same simulation timestamp. Label sample
-phase. Equal-time samples contribute zero duration to a time integral but affect an
-unweighted sample average.
-
-`len(resource.queue)` counts pending requests, not users in service. Total number in
-the congestion point is normally `resource.count + len(resource.queue)`.
-
-For Container/Store, distinguish `level`/`len(items)` from pending
-`put_queue`/`get_queue`.
-
-## Time-weighted state
-
-For a left-continuous piecewise-constant state `q(t)`, compute:
-
-`average = sum(q_i * (t_{i+1} - t_i)) / (end - start)`.
-
-Requirements:
-
-- initial sample at monitoring start;
-- every relevant state transition;
-- final sample exactly at the reporting horizon;
-- warm-up window clipping;
-- nondecreasing timestamps.
-
-Do not use `sum(queue_samples) / len(queue_samples)` as time-average queue length;
-busy periods typically generate more events and become overrepresented.
-
-## Bundled ResourceMonitor
-
-`scripts/resource_monitor.py` wraps one Resource-like instance, records request,
-grant, cancellation, release, and final states, and calculates time-weighted
-utilization/queue length.
-
-```python
-import simpy
-from resource_monitor import ResourceMonitor
-
-env = simpy.Environment()
-resource = simpy.Resource(env, capacity=2)
-monitor = ResourceMonitor(env, resource, "server")
-
-# Register bounded processes, then run.
-env.run(until=100)
-monitor.finalize(at=100)
-summary = monitor.summary(start=20, end=100)
-```
-
-The warm-up sample state is reconstructed from the last transition at or before
-`start`; the final sample closes the interval. `export_csv()` writes local private
-CSV atomically and refuses overwrite unless requested.
-
-Monkey-patching changes method identity and can interact with other wrappers. Attach
-one monitor per instance, patch before processes obtain method references, and call
-`detach()` before another instrumentation layer.
-
-## Generic resource wrappers
-
-The official guide demonstrates pre/post method wrappers:
-
-```python
-from functools import wraps
-
-def patch_resource(resource, pre=None, post=None):
-    def wrap(operation):
-        @wraps(operation)
-        def wrapper(*args, **kwargs):
-            if pre is not None:
-                pre(resource)
-            event = operation(*args, **kwargs)
-            if post is not None:
-                post(resource)
-            return event
-        return wrapper
-
-    for name in ("put", "get", "request", "release"):
-        if hasattr(resource, name):
-            setattr(resource, name, wrap(getattr(resource, name)))
-```
-
-Here "post" means after the method call, not necessarily after the returned Event
-is processed. To observe completion, append a callback while `event.callbacks` is
-still a list. Handle immediately triggered events before the environment steps.
-
-Subclassing can be clearer for one stable use case, but it still depends on
-protected `_env` in common examples. Prefer an explicit `env` reference.
-
-## Event tracing
-
-The official guide identifies:
-
-- `Environment.schedule()` — event enters the queue;
-- `Environment.step()` — next queued event is processed.
-
-The bundled `EventTraceRecorder` wraps `step()`, reads the next queue tuple, and
-records only:
-
-- simulation time;
-- priority;
-- event ID;
-- event class name;
-- queue size before the step.
-
-It avoids `repr(event)`, which can contain nondeterministic memory addresses. It
-caps records and writes JSON Lines.
-
-```python
-from resource_monitor import EventTraceRecorder
-
-trace = EventTraceRecorder(env, max_records=10_000)
-env.run(until=100)
-trace.detach()
-trace.export_jsonl("trace.jsonl")
-```
-
-This intentionally accesses `env._queue`, a private implementation detail. Pin
-SimPy and regression-test the tuple shape after upgrades. Full tracing increases
-runtime and memory; use a small deterministic diagnostic scenario.
-
-Summarize without executing model code:
-
-```bash
-python skills/simpy/scripts/event_trace_summary.py trace.jsonl
-python skills/simpy/scripts/event_trace_summary.py resource_samples.csv
-```
-
-The summarizer validates fixed schemas, file size, record count, numeric finiteness,
-and ordering.
-
-## Manual stepping
-
-Stepping is useful for debuggers, GUI integration, invariants, and hard event caps:
-
-```python
-from simpy.core import EmptySchedule
-
-max_events = 100_000
-processed = 0
-while env.peek() < 100 and processed < max_events:
-    env.step()
-    processed += 1
-
-if processed == max_events:
-    raise RuntimeError("event budget exhausted")
-if env.peek() == float("inf"):
-    # Empty schedule; verify intended completion instead of assuming success.
-    pass
-```
-
-`env.peek() < horizon` gives the same half-open boundary policy as numeric
-`run(until=horizon)`. `<=` processes events at the boundary and is a different
-estimand/termination convention.
-
-If a stop callback fires during `step()` in 4.1.2, SimPy may reschedule the Event to
-preserve remaining callbacks. See `events.md`.
-
-## Periodic polling
-
-Polling is simple but approximates the state path and adds events:
-
-```python
-def poll(env, resource, interval, end, samples):
-    while env.now < end:
-        samples.append((env.now, resource.count, len(resource.queue)))
-        delay = min(interval, end - env.now)
-        if delay <= 0:
-            return
-        yield env.timeout(delay)
-```
-
-Never use a zero/negative interval. Polling can miss short peaks. It is suitable
-for visualization at a declared resolution, not exact time integrals.
-
-## Measurement windows and censoring
-
-At a finite horizon:
-
-- an entity may arrive but remain queued;
-- service may start but not finish;
-- a future timeout may remain scheduled;
-- numeric `run(until=horizon)` excludes ordinary events exactly at the horizon.
-
-Report arrived, admitted, rejected, completed, and unfinished counts. A
-completed-only customer mean can be biased when long waits/services are more likely
-to be unfinished. Consider a terminating design that drains the system, a
-right-censoring-aware estimand, or sensitivity to a longer horizon.
-
-For steady-state replication/deletion, define whether an observation enters the
-analysis by arrival time, service-start time, departure time, or time-integral
-window. Do not choose after seeing favorable results.
-
-## Monitor non-interference tests
-
-For a deterministic miniature model, compare monitored and unmonitored runs:
-
-- same completion order and timestamps;
-- same resource counts and outputs;
-- same random draws/seed manifest;
-- no pending monitor bookkeeping after completion;
-- identical exception/interrupt behavior.
-
-Also test:
-
-- simultaneous request/release;
-- cancellation while queued;
-- preemption;
-- zero queue capacity;
-- final interval closure;
-- warm-up starting between transitions;
-- trace-cap behavior.
-
-## Sources
-
-See `sources.md` for the official monitoring, environment, time/scheduling, and
-tagged core source links.