simweave 0.4.0__py3-none-any.whl

simweave/discrete/queues.py

@@ -0,0 +1,317 @@
+"""FIFO queue and priority queue primitives.
+
+Queues are :class:`~simweave.core.entity.Entity` subclasses so they register
+with the environment and receive ``tick(dt, env)``. During a tick a queue
+ages the items it contains. Balking and reneging (via
+:class:`EntityProperties <simweave.discrete.properties.EntityProperties>`) are
+handled on :meth:`enqueue` and :meth:`tick` respectively.
+"""
+
+from __future__ import annotations
+
+import heapq
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+from simweave.core.entity import Entity
+from simweave.core.logging import get_logger
+
+log = get_logger("discrete.queue")
+
+
+class Queue(Entity):
+    """Bounded FIFO queue.
+
+    Parameters
+    ----------
+    maxlen:
+        Maximum number of items held. Extra arrivals are dropped (and the
+        drop counter is incremented).
+    name:
+        Human-readable name.
+    next_q:
+        Where forwarded items go -- another Queue/Service or the sentinel
+        string ``"terminus"`` meaning "remove from the system".
+    """
+
+    def __init__(
+        self,
+        maxlen: int = 10,
+        name: str | None = None,
+        next_q: "Queue | str" = "terminus",
+    ) -> None:
+        super().__init__(name=name)
+        if maxlen <= 0:
+            raise ValueError("Queue maxlen must be positive.")
+        self._deque: deque[Entity] = deque(maxlen=maxlen)
+        self.maxlen = maxlen
+        self._next_q: "Queue | str" = "terminus"
+        self.next_q = next_q  # validate via setter
+        self.dropped_count: int = 0
+        self.reneged_count: int = 0
+        self.balked_count: int = 0
+        # Metrics accumulated over the lifetime of the queue.
+        self.cumulative_length_time: float = 0.0  # integral of len(q) * dt
+        self.cumulative_wait_time: float = 0.0  # sum of total_wait_time on departure
+        self.arrivals: int = 0
+        self.departures: int = 0
+
+    # ------------------------------------------------------------------
+    # next_q management
+    # ------------------------------------------------------------------
+    @property
+    def next_q(self) -> "Queue | str":
+        return self._next_q
+
+    @next_q.setter
+    def next_q(self, value: "Queue | str") -> None:
+        if value == "terminus" or isinstance(value, Queue):
+            self._next_q = value
+        else:
+            raise TypeError(
+                f"next_q must be a Queue or 'terminus'; got {type(value).__name__}"
+            )
+
+    # ------------------------------------------------------------------
+    # Basic container protocol
+    # ------------------------------------------------------------------
+    def __len__(self) -> int:
+        return len(self._deque)
+
+    def __iter__(self):
+        return iter(self._deque)
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        nq = self._next_q if isinstance(self._next_q, str) else self._next_q.name
+        return f"{type(self).__name__}(name={self.name!r}, len={len(self)}/{self.maxlen}, next={nq})"
+
+    @property
+    def is_full(self) -> bool:
+        return len(self._deque) >= self.maxlen
+
+    @property
+    def is_empty(self) -> bool:
+        return len(self._deque) == 0
+
+    def peek(self) -> Entity | None:
+        return self._deque[0] if self._deque else None
+
+    # ------------------------------------------------------------------
+    # Core operations
+    # ------------------------------------------------------------------
+    def enqueue(self, item: Entity) -> bool:
+        """Attempt to append an item. Returns ``True`` on success.
+
+        Honours ``item.sim_properties.balk_on_length`` if present.
+        """
+        sim_props = getattr(item, "sim_properties", None)
+        balk = (
+            getattr(sim_props, "balk_on_length", None)
+            if sim_props is not None
+            else None
+        )
+        if balk is not None and len(self._deque) >= balk:
+            self.balked_count += 1
+            log.debug(
+                "%s: %s balked (len %d >= %d).",
+                self.name,
+                item.name,
+                len(self._deque),
+                balk,
+            )
+            return False
+
+        if self.is_full:
+            self.dropped_count += 1
+            log.debug("%s: dropped %s (full).", self.name, item.name)
+            return False
+
+        item.current_wait_time = 0.0
+        self._deque.append(item)
+        self.arrivals += 1
+        return True
+
+    def dequeue(self) -> Entity:
+        if not self._deque:
+            raise IndexError(f"{self.name}: dequeue from empty queue")
+        item = self._deque.popleft()
+        self.departures += 1
+        self.cumulative_wait_time += item.total_wait_time
+        return item
+
+    def renege_tail(self) -> Entity:
+        if not self._deque:
+            raise IndexError(f"{self.name}: renege from empty queue")
+        item = self._deque.pop()
+        self.reneged_count += 1
+        return item
+
+    def forward(self, override_target: "Queue | str | None" = None) -> bool:
+        """Dequeue head and enqueue into ``override_target`` (or ``self.next_q``).
+
+        Returns ``True`` if forwarded, ``False`` if downstream is blocked (in
+        which case the head item is *not* removed).
+        """
+        target = override_target if override_target is not None else self._next_q
+        if not self._deque:
+            return False
+        if target == "terminus":
+            self.dequeue()
+            return True
+        assert isinstance(target, Queue)
+        if target.is_full:
+            return False
+        item = self._deque.popleft()
+        self.departures += 1
+        self.cumulative_wait_time += item.total_wait_time
+        accepted = target.enqueue(item)
+        if not accepted:
+            # Shouldn't normally happen because we checked is_full, but handle
+            # balking on the downstream queue: silently drop.
+            self.dropped_count += 1
+        return True
+
+    # ------------------------------------------------------------------
+    # Tick-loop integration
+    # ------------------------------------------------------------------
+    def tick(self, dt: float, env) -> None:
+        super().tick(dt, env)
+        # Time-integrate length for Little's law calculations.
+        self.cumulative_length_time += len(self._deque) * dt
+        # Age waiting items and handle reneging.
+        to_renege: list[Entity] = []
+        for item in list(self._deque):
+            item.age += dt
+            item.current_wait_time += dt
+            item.total_wait_time += dt
+            renege_after = None
+            sim_props = getattr(item, "sim_properties", None)
+            if sim_props is not None:
+                renege_after = getattr(sim_props, "renege_after", None)
+            if renege_after is not None and item.current_wait_time >= renege_after:
+                to_renege.append(item)
+        for item in to_renege:
+            try:
+                self._deque.remove(item)
+                self.reneged_count += 1
+                log.debug(
+                    "%s: %s reneged after %.2f.",
+                    self.name,
+                    item.name,
+                    item.current_wait_time,
+                )
+            except ValueError:
+                pass
+
+    def has_work(self, env) -> bool:
+        # A plain queue does not perform work; items just wait.
+        return False
+
+    # ------------------------------------------------------------------
+    # Metrics
+    # ------------------------------------------------------------------
+    def average_length(self, elapsed: float) -> float:
+        """Mean queue length over the elapsed simulation time (L in Little's law)."""
+        if elapsed <= 0:
+            return 0.0
+        return self.cumulative_length_time / elapsed
+
+    def average_wait(self) -> float:
+        """Mean residence time of completed items (W in Little's law)."""
+        if self.departures == 0:
+            return 0.0
+        return self.cumulative_wait_time / self.departures
+
+
+# ---------------------------------------------------------------------------
+# Priority queue
+# ---------------------------------------------------------------------------
+
+
+@dataclass(order=True)
+class _PItem:
+    priority: float
+    seq: int
+    item: Any = field(compare=False)
+
+
+class PriorityQueue(Queue):
+    """Min-heap priority queue. Lower priority values dequeue first.
+
+    Items are wrapped in ``(priority, seq, item)`` tuples internally so the
+    payload doesn't need to be comparable.
+    """
+
+    def __init__(
+        self,
+        maxlen: int = 10,
+        name: str | None = None,
+        next_q: "Queue | str" = "terminus",
+    ) -> None:
+        super().__init__(maxlen=maxlen, name=name, next_q=next_q)
+        self._heap: list[_PItem] = []
+        self._seq_counter = 0
+        # Drop the inherited deque; we store in _heap. We keep len() consistent
+        # by overriding __len__.
+
+    def __len__(self) -> int:
+        return len(self._heap)
+
+    def __iter__(self):
+        return (p.item for p in self._heap)
+
+    def peek(self) -> Entity | None:
+        return self._heap[0].item if self._heap else None
+
+    @property
+    def is_full(self) -> bool:
+        return len(self._heap) >= self.maxlen
+
+    @property
+    def is_empty(self) -> bool:
+        return not self._heap
+
+    def enqueue(self, item: Entity, priority: float = 0.0) -> bool:  # type: ignore[override]
+        if self.is_full:
+            self.dropped_count += 1
+            return False
+        item.current_wait_time = 0.0
+        heapq.heappush(
+            self._heap, _PItem(priority=priority, seq=self._seq_counter, item=item)
+        )
+        self._seq_counter += 1
+        self.arrivals += 1
+        return True
+
+    def dequeue(self) -> Entity:  # type: ignore[override]
+        if not self._heap:
+            raise IndexError(f"{self.name}: dequeue from empty priority queue")
+        wrapped = heapq.heappop(self._heap)
+        self.departures += 1
+        self.cumulative_wait_time += wrapped.item.total_wait_time
+        return wrapped.item
+
+    def forward(self, override_target=None) -> bool:  # type: ignore[override]
+        target = override_target if override_target is not None else self._next_q
+        if not self._heap:
+            return False
+        if target == "terminus":
+            self.dequeue()
+            return True
+        assert isinstance(target, Queue)
+        if target.is_full:
+            return False
+        item = self.dequeue()
+        target.enqueue(item)
+        return True
+
+    def tick(self, dt: float, env) -> None:  # type: ignore[override]
+        # Skip Queue.tick deque iteration; operate on our heap.
+        Entity.tick(self, dt, env)
+        self.cumulative_length_time += len(self._heap) * dt
+        for wrapper in self._heap:
+            item = wrapper.item
+            item.age += dt
+            item.current_wait_time += dt
+            item.total_wait_time += dt

simweave/discrete/resources.py

@@ -0,0 +1,89 @@
+"""Reusable resources and resource pools.
+
+A :class:`Resource` is an :class:`Entity` that a :class:`Service` may acquire
+before serving an item and release afterwards. Resources are held in a
+:class:`ResourcePool`, which is itself a :class:`Queue` so it enjoys the
+same tick semantics and bookkeeping.
+"""
+
+from __future__ import annotations
+
+from simweave.core.entity import Entity
+from simweave.discrete.queues import Queue
+
+
+class Resource(Entity):
+    """A reusable resource that can be checked out of a pool."""
+
+    def __init__(
+        self, name: str | None = None, home_pool: "ResourcePool | str" = "terminus"
+    ) -> None:
+        super().__init__(name=name)
+        self.home_pool: "ResourcePool | str" = home_pool
+        self.times_acquired: int = 0
+        self.busy_time: float = 0.0
+        self._is_busy: bool = False
+
+    @property
+    def is_busy(self) -> bool:
+        return self._is_busy
+
+    def release(self, to: "ResourcePool | None" = None) -> None:
+        """Return the resource to ``to`` or its home pool."""
+        target = to if to is not None else self.home_pool
+        self._is_busy = False
+        if isinstance(target, ResourcePool):
+            target.deposit(self)
+        elif target == "terminus":
+            return
+        else:
+            raise TypeError(
+                "Resource.release target must be a ResourcePool or 'terminus'."
+            )
+
+    def tick(self, dt: float, env) -> None:
+        super().tick(dt, env)
+        if self._is_busy:
+            self.busy_time += dt
+
+
+class ResourcePool(Queue):
+    """Pool of interchangeable resources that a Service can check out."""
+
+    def __init__(self, maxlen: int = 10, name: str | None = None) -> None:
+        super().__init__(maxlen=maxlen, name=name, next_q="terminus")
+
+    def deposit(self, resource: Resource) -> None:
+        """Return a resource to the pool. Raises if the pool is at capacity."""
+        if not isinstance(resource, Resource):
+            raise TypeError("ResourcePool only accepts Resource instances.")
+        resource.home_pool = self
+        if self.is_full:
+            raise RuntimeError(f"{self.name}: pool full when returning {resource.name}")
+        self._deque.append(resource)
+        self.arrivals += 1
+
+    # Alias for legacy naming.
+    add_resource = deposit
+
+    def try_acquire(self) -> Resource | None:
+        """Non-blocking acquire. Returns a Resource or ``None`` if empty."""
+        if not self._deque:
+            return None
+        resource = self._deque.popleft()
+        assert isinstance(resource, Resource)
+        resource.home_pool = self
+        resource._is_busy = True
+        resource.times_acquired += 1
+        self.departures += 1
+        return resource
+
+    def release(self, resource: Resource) -> None:
+        """Release a previously acquired resource back to this pool."""
+        resource.release(to=self)
+
+    def tick(self, dt: float, env) -> None:
+        super().tick(dt, env)
+        # Propagate tick to each idle resource so busy_time stays accurate
+        # when they are NOT in the pool (those will be ticked by the Service).
+        # Idle resources sitting here don't accrue busy_time.

simweave/discrete/services.py

@@ -0,0 +1,228 @@
+"""Multi-channel Service and arrival generator.
+
+A :class:`Service` is a :class:`Queue` (the pre-service buffer) plus a set of
+independent :class:`_WorkChannel` instances. Each channel processes one item
+at a time; if a completed item cannot be forwarded downstream (because the
+next queue is full) it sits in a "blocked-completion" slot until it clears.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+import numpy as np
+
+from simweave.core.entity import Entity
+from simweave.core.logging import get_logger
+from simweave.discrete.queues import Queue
+from simweave.discrete.resources import ResourcePool
+
+if TYPE_CHECKING:
+    from simweave.core.environment import SimEnvironment
+
+log = get_logger("discrete.service")
+
+
+class _WorkChannel:
+    """Internal single-item processing slot within a Service."""
+
+    __slots__ = ("parent", "idx", "current", "blocked", "held_resource", "busy_time")
+
+    def __init__(self, parent: "Service", idx: int) -> None:
+        self.parent = parent
+        self.idx = idx
+        self.current: Entity | None = None
+        self.blocked: Entity | None = None  # completed but next_q was full
+        self.held_resource = None
+        self.busy_time: float = 0.0
+
+    def is_busy(self) -> bool:
+        return self.current is not None or self.blocked is not None
+
+    def tick(self, dt: float, env) -> None:
+        # 1. Try to clear any blocked completed item first.
+        if self.blocked is not None:
+            if self._try_forward(self.blocked):
+                self._release_resource()
+                self.blocked = None
+
+        # 2. If idle, pull new work from the buffer.
+        if self.current is None and self.blocked is None:
+            self._try_start(env)
+
+        # 3. Process the current item, if any.
+        if self.current is not None:
+            step = min(self.current.remaining_service_time, dt)
+            self.current.remaining_service_time -= step
+            self.current.age += step
+            self.busy_time += step
+            if self.current.remaining_service_time <= 1e-12:
+                item = self.current
+                self.current = None
+                if self._try_forward(item):
+                    self._release_resource()
+                else:
+                    self.blocked = item
+
+    def _try_start(self, env) -> None:
+        if not self.parent._deque:
+            return
+        if self.parent.resources is not None:
+            r = self.parent.resources.try_acquire()
+            if r is None:
+                return
+            self.held_resource = r
+        item = self.parent.dequeue()
+        rng = getattr(self.parent, "rng", None)
+        sim_props = getattr(item, "sim_properties", None)
+        if sim_props is not None and hasattr(sim_props, "draw_service_time"):
+            item.remaining_service_time = sim_props.draw_service_time(rng)
+        elif item.remaining_service_time <= 0:
+            item.remaining_service_time = self.parent.default_service_time
+        self.current = item
+
+    def _try_forward(self, item: Entity) -> bool:
+        target = self.parent.next_q
+        if target == "terminus":
+            self.parent._record_completion(item)
+            return True
+        assert isinstance(target, Queue)
+        if target.is_full:
+            return False
+        accepted = target.enqueue(item)
+        if accepted:
+            self.parent._record_completion(item)
+        return accepted
+
+    def _release_resource(self) -> None:
+        if self.held_resource is not None:
+            self.parent.resources.release(self.held_resource)
+            self.held_resource = None
+
+
+class Service(Queue):
+    """Multi-channel server with optional resource pool.
+
+    Parameters
+    ----------
+    capacity:
+        Number of parallel work channels (servers).
+    buffer_size:
+        Max queue length *before* service. Further arrivals are dropped.
+    next_q:
+        Where to forward completed items.
+    resources:
+        Optional :class:`ResourcePool` from which to acquire one resource per
+        item served. If ``None``, the service is unconstrained.
+    default_service_time:
+        Fallback when an arriving entity has no ``sim_properties``.
+    rng:
+        Optional numpy Generator used when drawing service times.
+    """
+
+    def __init__(
+        self,
+        capacity: int = 1,
+        buffer_size: int = 10,
+        next_q: "Queue | str" = "terminus",
+        resources: ResourcePool | None = None,
+        default_service_time: float = 1.0,
+        rng: np.random.Generator | None = None,
+        name: str | None = None,
+    ) -> None:
+        super().__init__(maxlen=buffer_size, name=name, next_q=next_q)
+        if capacity < 1:
+            raise ValueError("Service capacity must be >= 1.")
+        self.capacity = capacity
+        self.resources = resources
+        self.default_service_time = float(default_service_time)
+        self.rng = rng if rng is not None else np.random.default_rng()
+        self.channels = [_WorkChannel(self, i) for i in range(capacity)]
+        self.completed_count: int = 0
+        self.completed_total_time: float = (
+            0.0  # sum of (wait + service) across completed
+        )
+
+    # ------------------------------------------------------------------
+    # next_q propagation to channels is implicit: they read parent.next_q.
+    # ------------------------------------------------------------------
+
+    def tick(self, dt: float, env) -> None:
+        # First tick the work channels (they pull from the buffer).
+        for ch in self.channels:
+            ch.tick(dt, env)
+        # Then tick the buffer's own age/renege bookkeeping (parent Queue).
+        super().tick(dt, env)
+
+    def has_work(self, env) -> bool:
+        return any(ch.is_busy() for ch in self.channels) or bool(self._deque)
+
+    # ------------------------------------------------------------------
+    # Metrics
+    # ------------------------------------------------------------------
+    def utilisation(self, elapsed: float) -> float:
+        """Average utilisation across all channels over ``elapsed`` time."""
+        if elapsed <= 0 or self.capacity == 0:
+            return 0.0
+        busy = sum(ch.busy_time for ch in self.channels)
+        return busy / (self.capacity * elapsed)
+
+    def average_residence(self) -> float:
+        """Mean total time (waiting + service) for completed items."""
+        if self.completed_count == 0:
+            return 0.0
+        return self.completed_total_time / self.completed_count
+
+    def _record_completion(self, item: Entity) -> None:
+        self.completed_count += 1
+        self.completed_total_time += item.total_wait_time + item.age  # rough summary
+
+
+# ---------------------------------------------------------------------------
+# Arrival generator
+# ---------------------------------------------------------------------------
+
+
+class ArrivalGenerator(Entity):
+    """Generates new entities according to an inter-arrival distribution.
+
+    On each tick it adds to an internal clock and, whenever the clock passes
+    the next scheduled arrival, invokes ``factory(env)`` to mint a new
+    entity and pushes it into ``target``. Multiple arrivals within a single
+    tick are handled correctly.
+    """
+
+    def __init__(
+        self,
+        interarrival: Callable[[np.random.Generator], float],
+        factory: Callable[[SimEnvironment], Entity],
+        target: Queue,
+        rng: np.random.Generator | None = None,
+        name: str | None = None,
+    ) -> None:
+        super().__init__(name=name)
+        self.interarrival = interarrival
+        self.factory = factory
+        self.target = target
+        self.rng = rng if rng is not None else np.random.default_rng()
+        self._countdown: float = float(self.interarrival(self.rng))
+        self.generated: int = 0
+        self.rejected: int = 0
+
+    def tick(self, dt: float, env) -> None:
+        super().tick(dt, env)
+        remaining = dt
+        while remaining >= self._countdown:
+            remaining -= self._countdown
+            entity = self.factory(env)
+            if self.target.enqueue(entity):
+                self.generated += 1
+            else:
+                self.rejected += 1
+            self._countdown = float(self.interarrival(self.rng))
+        self._countdown -= remaining
+
+    def has_work(self, env) -> bool:
+        # The generator always has "work" in the sense that another arrival
+        # is pending.
+        return True

simweave/mc/__init__.py

@@ -0,0 +1,5 @@
+"""Monte Carlo harness."""
+
+from simweave.mc.runner import MCResult, run_monte_carlo, run_batched_mc
+
+__all__ = ["MCResult", "run_monte_carlo", "run_batched_mc"]