simweave 0.4.0__py3-none-any.whl

simweave/__init__.py

@@ -0,0 +1,198 @@
+"""simweave: atomic-clock hybrid simulation engine.
+
+Public surface re-exports the primitives most users will need. For anything
+else, import the submodule directly (``simweave.continuous``, ``simweave.agents``,
+etc).
+"""
+
+from simweave.core import (
+    Clock,
+    EventQueue,
+    ScheduledEvent,
+    Entity,
+    SimEnvironment,
+    configure as configure_logging,
+    get_logger,
+)
+from simweave.discrete import (
+    EntityProperties,
+    exponential,
+    uniform,
+    normal,
+    deterministic,
+    set_default_seed,
+    Queue,
+    PriorityQueue,
+    Resource,
+    ResourcePool,
+    Service,
+    ArrivalGenerator,
+)
+from simweave.continuous import (
+    DynamicSystem,
+    SupportsDynamics,
+    SimulationResult,
+    simulate,
+    ContinuousProcess,
+    MassSpringDamper,
+    SimplePendulum,
+    QuarterCarModel,
+    SeriesRLC,
+    ThermalRC,
+    TwoMassThermal,
+)
+from simweave.spatial import Graph, grid_graph
+from simweave.agents import (
+    Compass,
+    Agent,
+    a_star,
+    dijkstra,
+    NoPathError,
+    manhattan,
+    euclidean,
+    chebyshev,
+)
+from simweave.supplychain import InventoryItems, Warehouse
+from simweave.mc import MCResult, run_monte_carlo, run_batched_mc
+from simweave.units import (
+    SIUnit,
+    Distance,
+    Velocity,
+    Acceleration,
+    Mass,
+    Force,
+    Area,
+    Volume,
+    TimeUnit,
+)
+from simweave.currency import (
+    Money,
+    CurrencyMismatchError,
+    FXConverter,
+    StaticFXConverter,
+    CallableFXConverter,
+    format_money,
+    register_custom,
+    unregister_custom,
+    is_valid_currency,
+    get_decimals,
+    list_codes,
+)
+# simweave.viz is import-cheap: plotly is only required when a plot helper
+# is actually called. The names below are always importable; calling one
+# without the `simweave[viz]` extra raises a clear ImportError.
+from simweave.viz import (
+    QueueLengthRecorder,
+    ServiceUtilisationRecorder,
+    WarehouseStockRecorder,
+    apply_theme,
+    available_themes,
+    get_default_theme,
+    have_plotly,
+    plot_agent_path,
+    plot_mc_fan,
+    plot_phase_portrait,
+    plot_queue_length,
+    plot_service_utilisation,
+    plot_state_trajectories,
+    plot_warehouse_stock,
+    register_theme,
+    set_default_theme,
+)
+
+__version__ = "0.4.0"
+
+__all__ = [
+    # Core
+    "Clock",
+    "EventQueue",
+    "ScheduledEvent",
+    "Entity",
+    "SimEnvironment",
+    "configure_logging",
+    "get_logger",
+    # Discrete
+    "EntityProperties",
+    "exponential",
+    "uniform",
+    "normal",
+    "deterministic",
+    "set_default_seed",
+    "Queue",
+    "PriorityQueue",
+    "Resource",
+    "ResourcePool",
+    "Service",
+    "ArrivalGenerator",
+    # Continuous
+    "DynamicSystem",
+    "SupportsDynamics",
+    "SimulationResult",
+    "simulate",
+    "ContinuousProcess",
+    "MassSpringDamper",
+    "SimplePendulum",
+    "QuarterCarModel",
+    "SeriesRLC",
+    "ThermalRC",
+    "TwoMassThermal",
+    # Spatial / Agents
+    "Graph",
+    "grid_graph",
+    "Compass",
+    "Agent",
+    "a_star",
+    "dijkstra",
+    "NoPathError",
+    "manhattan",
+    "euclidean",
+    "chebyshev",
+    # Supply chain
+    "InventoryItems",
+    "Warehouse",
+    # Monte Carlo
+    "MCResult",
+    "run_monte_carlo",
+    "run_batched_mc",
+    # Units
+    "SIUnit",
+    "Distance",
+    "Velocity",
+    "Acceleration",
+    "Mass",
+    "Force",
+    "Area",
+    "Volume",
+    "TimeUnit",
+    # Currency
+    "Money",
+    "CurrencyMismatchError",
+    "FXConverter",
+    "StaticFXConverter",
+    "CallableFXConverter",
+    "format_money",
+    "register_custom",
+    "unregister_custom",
+    "is_valid_currency",
+    "get_decimals",
+    "list_codes",
+    # Viz
+    "QueueLengthRecorder",
+    "ServiceUtilisationRecorder",
+    "WarehouseStockRecorder",
+    "apply_theme",
+    "available_themes",
+    "get_default_theme",
+    "have_plotly",
+    "plot_agent_path",
+    "plot_mc_fan",
+    "plot_phase_portrait",
+    "plot_queue_length",
+    "plot_service_utilisation",
+    "plot_state_trajectories",
+    "plot_warehouse_stock",
+    "register_theme",
+    "set_default_theme",
+    # Meta
+    "__version__",
+]

simweave/agents/__init__.py

@@ -0,0 +1,23 @@
+"""Agents, routing, and orientation primitives."""
+
+from simweave.agents.compass import Compass
+from simweave.agents.routing import (
+    a_star,
+    dijkstra,
+    NoPathError,
+    manhattan,
+    euclidean,
+    chebyshev,
+)
+from simweave.agents.agent import Agent
+
+__all__ = [
+    "Compass",
+    "a_star",
+    "dijkstra",
+    "NoPathError",
+    "manhattan",
+    "euclidean",
+    "chebyshev",
+    "Agent",
+]

simweave/agents/agent.py

@@ -0,0 +1,161 @@
+"""Routable agent that inherits from :class:`~simweave.core.entity.Entity`.
+
+An Agent traverses a graph under its own steam. On each tick:
+
+* If it has no plan and has tasks queued, it replans to the next task via A*.
+* If it is mid-edge, it consumes distance according to ``speed * dt``.
+* On arrival at a node, it pops it from the path, records history, and may
+  fire ``on_arrive(node)``.
+
+The Agent holds only a reference to the graph; it does not own it. Several
+agents may share a graph.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Hashable, Sequence
+
+from simweave.core.entity import Entity
+from simweave.core.logging import get_logger
+from simweave.agents.compass import Compass
+from simweave.agents.routing import a_star, NoPathError
+from simweave.spatial.graph import adj_view, edge_weight
+
+log = get_logger("agents.agent")
+
+Node = Hashable
+
+
+class Agent(Entity):
+    """Graph-routing agent.
+
+    Parameters
+    ----------
+    graph:
+        A simweave Graph, networkx graph, or dict-of-dict adjacency.
+    start_node:
+        Node at which the agent spawns.
+    tasks:
+        Ordered list of target nodes to visit.
+    speed:
+        Distance per unit time.
+    heuristic:
+        Optional heuristic for A*. If None, A* degenerates to Dijkstra.
+    on_arrive:
+        Optional callback ``on_arrive(agent, node, env)`` fired when the
+        agent arrives at any node (including intermediate path nodes).
+    name:
+        Optional agent name.
+    """
+
+    def __init__(
+        self,
+        graph: Any,
+        start_node: Node,
+        tasks: Sequence[Node] | None = None,
+        speed: float = 1.0,
+        heuristic: Callable[[Node, Node], float] | None = None,
+        on_arrive: Callable[["Agent", Node, Any], None] | None = None,
+        weight_attr: str = "weight",
+        name: str | None = None,
+    ) -> None:
+        super().__init__(name=name)
+        self.graph = graph
+        self.position: Node = start_node
+        self.tasks: list[Node] = list(tasks or [])
+        self.path: list[Node] = []
+        self.speed = float(speed)
+        self.heuristic = heuristic
+        self.compass = Compass(points=8)
+        self.weight_attr = weight_attr
+        self.on_arrive = on_arrive
+
+        self._edge_remaining: float = 0.0
+        self._edge_weight: float = 0.0
+        self.history: list[tuple[float, Node]] = []
+        self.completed_tasks: int = 0
+
+    # ------------------------------------------------------------------
+    # Routing
+    # ------------------------------------------------------------------
+    def plan_to(self, target: Node) -> None:
+        """Replan to ``target`` from the current position using A*."""
+        try:
+            path = a_star(
+                self.graph,
+                self.position,
+                target,
+                heuristic=self.heuristic,
+                weight_attr=self.weight_attr,
+            )
+        except NoPathError:
+            log.warning("%s: no path from %s to %s", self.name, self.position, target)
+            self.path = []
+            return
+        # path[0] is the current position; drop it.
+        self.path = path[1:] if path and path[0] == self.position else path
+
+    def _take_next_task(self) -> None:
+        while self.tasks and not self.path:
+            target = self.tasks.pop(0)
+            if target == self.position:
+                # Already here; count as arrival.
+                self.completed_tasks += 1
+                if self.on_arrive is not None:
+                    self.on_arrive(self, target, None)
+                continue
+            self.plan_to(target)
+
+    # ------------------------------------------------------------------
+    # Tick loop
+    # ------------------------------------------------------------------
+    def tick(self, dt: float, env) -> None:
+        super().tick(dt, env)
+        if not self.path:
+            self._take_next_task()
+        if not self.path:
+            return
+
+        remaining_step = self.speed * dt
+        while remaining_step > 0 and self.path:
+            if self._edge_remaining <= 0:
+                # Begin traversing next edge.
+                next_node = self.path[0]
+                nbrs = adj_view(self.graph, self.position)
+                if next_node not in nbrs:
+                    log.warning(
+                        "%s: edge %s->%s missing; replanning.",
+                        self.name,
+                        self.position,
+                        next_node,
+                    )
+                    if self.path:
+                        target = self.path[-1]
+                        self.path = []
+                        self.plan_to(target)
+                    return
+                self._edge_weight = edge_weight(nbrs[next_node], self.weight_attr)
+                self._edge_remaining = self._edge_weight
+
+            step = min(remaining_step, self._edge_remaining)
+            self._edge_remaining -= step
+            remaining_step -= step
+
+            if self._edge_remaining <= 1e-12:
+                self.position = self.path.pop(0)
+                self.history.append((env.clock.t + dt, self.position))
+                if self.on_arrive is not None:
+                    self.on_arrive(self, self.position, env)
+                # If we've exhausted the current task plan, count the
+                # arrival as a completed task regardless of whether more
+                # tasks are queued behind it.
+                if not self.path:
+                    self.completed_tasks += 1
+
+        # If the path finished and more tasks queued, plan immediately so the
+        # next tick doesn't waste a step standing still.
+        if not self.path and self.tasks:
+            self._take_next_task()
+
+    def has_work(self, env) -> bool:
+        return bool(self.path) or bool(self.tasks)

simweave/agents/compass.py

@@ -0,0 +1,48 @@
+"""Discrete compass (4, 6, 8 or 16 point).
+
+Used by :class:`~simweave.agents.agent.Agent` for cheap orientation tracking
+independent of any graph topology.
+"""
+
+from __future__ import annotations
+
+
+class Compass:
+    """Discrete compass quantised to a fixed number of points."""
+
+    _LABELS_8 = ("N", "NE", "E", "SE", "S", "SW", "W", "NW")
+    _LABELS_4 = ("N", "E", "S", "W")
+    _ALLOWED = (4, 6, 8, 16)
+
+    def __init__(self, points: int = 8, angle: float = 0.0) -> None:
+        if points not in self._ALLOWED:
+            raise ValueError(f"Compass points must be one of {self._ALLOWED}")
+        self.points = points
+        self.atomic_angle = 360.0 / points
+        self.angle = self._quantize(float(angle))
+
+    def _quantize(self, angle: float) -> float:
+        angle %= 360.0
+        return (round(angle / self.atomic_angle) % self.points) * self.atomic_angle
+
+    @property
+    def direction(self) -> str:
+        if self.points == 8:
+            idx = int(round(self.angle / 45.0)) % 8
+            return self._LABELS_8[idx]
+        if self.points == 4:
+            idx = int(round(self.angle / 90.0)) % 4
+            return self._LABELS_4[idx]
+        return f"CW_{self.angle:g}"
+
+    def set_absolute(self, angle: float) -> str:
+        self.angle = self._quantize(angle)
+        return self.direction
+
+    def clockwise(self, delta: float) -> str:
+        self.angle = self._quantize(self.angle + delta)
+        return self.direction
+
+    def anti_clockwise(self, delta: float) -> str:
+        self.angle = self._quantize(self.angle - delta)
+        return self.direction

simweave/agents/routing.py

@@ -0,0 +1,113 @@
+"""A* (and Dijkstra) shortest path over a simweave / networkx / dict graph.
+
+Pure stdlib; networkx is not required. If ``heuristic`` is ``None`` the
+algorithm degrades to Dijkstra (heuristic = 0 is admissible).
+"""
+
+from __future__ import annotations
+
+import heapq
+from math import inf, sqrt
+from typing import Any, Callable, Hashable
+
+from simweave.spatial.graph import adj_view, edge_weight
+
+
+Node = Hashable
+Heuristic = Callable[[Node, Node], float]
+
+
+class NoPathError(ValueError):
+    """Raised when A* cannot reach the goal from the start node."""
+
+
+def a_star(
+    graph: Any,
+    start: Node,
+    goal: Node,
+    heuristic: Heuristic | None = None,
+    weight_attr: str = "weight",
+) -> list[Node]:
+    """Compute shortest path from ``start`` to ``goal``.
+
+    Parameters
+    ----------
+    graph:
+        Any object understood by :func:`simweave.spatial.graph.adj_view`.
+    heuristic:
+        Admissible heuristic ``h(node, goal)``. Defaults to zero (Dijkstra).
+    weight_attr:
+        Edge attribute to treat as weight. Defaults to ``"weight"``.
+
+    Returns
+    -------
+    list[Node]
+        Path from start to goal inclusive.
+    """
+    if heuristic is None:
+
+        def heuristic(a: Node, b: Node) -> float:
+            return 0.0
+
+    open_heap: list[tuple[float, int, Node]] = [(0.0, 0, start)]
+    came_from: dict[Node, Node] = {}
+    g_score: dict[Node, float] = {start: 0.0}
+    counter = 1
+    closed: set[Node] = set()
+
+    while open_heap:
+        _, _, current = heapq.heappop(open_heap)
+        if current in closed:
+            continue
+        if current == goal:
+            return _reconstruct(came_from, current)
+        closed.add(current)
+
+        for neighbor, edge_data in adj_view(graph, current).items():
+            if neighbor in closed:
+                continue
+            w = edge_weight(edge_data, weight_attr)
+            tentative = g_score[current] + w
+            if tentative < g_score.get(neighbor, inf):
+                g_score[neighbor] = tentative
+                came_from[neighbor] = current
+                f = tentative + heuristic(neighbor, goal)
+                heapq.heappush(open_heap, (f, counter, neighbor))
+                counter += 1
+
+    raise NoPathError(f"No path from {start!r} to {goal!r}.")
+
+
+def dijkstra(
+    graph: Any, start: Node, goal: Node, weight_attr: str = "weight"
+) -> list[Node]:
+    """Convenience wrapper -- A* with zero heuristic."""
+    return a_star(graph, start, goal, heuristic=None, weight_attr=weight_attr)
+
+
+def _reconstruct(came_from: dict[Node, Node], current: Node) -> list[Node]:
+    path = [current]
+    while current in came_from:
+        current = came_from[current]
+        path.append(current)
+    path.reverse()
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Heuristics for 2D grid-like nodes (tuples of (row, col) or (x, y)).
+# ---------------------------------------------------------------------------
+
+
+def manhattan(a: Node, b: Node) -> float:
+    return abs(a[0] - b[0]) + abs(a[1] - b[1])  # type: ignore[index]
+
+
+def euclidean(a: Node, b: Node) -> float:
+    dx = a[0] - b[0]  # type: ignore[index]
+    dy = a[1] - b[1]  # type: ignore[index]
+    return sqrt(dx * dx + dy * dy)
+
+
+def chebyshev(a: Node, b: Node) -> float:
+    return max(abs(a[0] - b[0]), abs(a[1] - b[1]))  # type: ignore[index]

simweave/continuous/__init__.py

@@ -0,0 +1,31 @@
+"""Continuous-time dynamics: state-space solver, plug-in systems, hybrid wrapper."""
+
+from simweave.continuous.solver import (
+    DynamicSystem,
+    SupportsDynamics,
+    SimulationResult,
+    simulate,
+    ContinuousProcess,
+)
+from simweave.continuous.systems import (
+    MassSpringDamper,
+    SimplePendulum,
+    QuarterCarModel,
+    SeriesRLC,
+    ThermalRC,
+    TwoMassThermal,
+)
+
+__all__ = [
+    "DynamicSystem",
+    "SupportsDynamics",
+    "SimulationResult",
+    "simulate",
+    "ContinuousProcess",
+    "MassSpringDamper",
+    "SimplePendulum",
+    "QuarterCarModel",
+    "SeriesRLC",
+    "ThermalRC",
+    "TwoMassThermal",
+]