simweave 0.4.0__py3-none-any.whl

simweave/supplychain/warehouse.py

@@ -0,0 +1,153 @@
+"""Warehouse entity that consumes inventory and replenishes from a parent.
+
+Simulation model (per tick):
+  1. Count down any outstanding reorder lead times; receive completed orders.
+  2. If a SKU's stock level is at or below its reorder point AND no order is
+     already in flight, raise a new order for ``batchsize``. If the parent
+     warehouse has stock, decrement them; otherwise record a backorder.
+
+Use :meth:`decrement_vector` (vectorised consumption) each tick to represent
+demand. Wire two Warehouses via ``parent_warehouse=`` to form multi-echelon
+supply chains; the outermost one uses the sentinel string ``"industry"``
+for infinite replenishment.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from simweave.core.entity import Entity
+from simweave.core.logging import get_logger
+from simweave.supplychain.inventory import InventoryItems
+
+log = get_logger("supplychain.warehouse")
+
+
+class Warehouse(Entity):
+    """Multi-SKU warehouse with (R, Q) reorder policy."""
+
+    def __init__(
+        self,
+        inventory: InventoryItems,
+        name: str | None = None,
+        parent_warehouse: "Warehouse | str" = "industry",
+    ) -> None:
+        super().__init__(name=name)
+        self.inv = inventory
+        self.parent: "Warehouse | str" = parent_warehouse
+
+        n = inventory.n_items
+        self._reorder_time_remaining = np.zeros(n, dtype=float)
+        self._orders_placed_bool = np.zeros(n, dtype=bool)
+        self._reorders_volume = np.zeros(n, dtype=float)
+        self._lifetime_total_orders = inventory.stock_level.copy()
+        self._lifetime_backorders = np.zeros(n, dtype=float)
+        self._demand_rate: np.ndarray | None = None
+
+    # ------------------------------------------------------------------
+    # Stock ops
+    # ------------------------------------------------------------------
+    def increment_by_idx(self, idx: int, amount: float = 1.0) -> None:
+        self.inv.stock_level[idx] += amount
+
+    def increment_vector(self, vec: np.ndarray) -> None:
+        self.inv.stock_level = self.inv.stock_level + np.asarray(vec, dtype=float)
+
+    def decrement_by_idx(self, idx: int, amount: float = 1.0) -> bool:
+        if self.inv.stock_level[idx] >= amount:
+            self.inv.stock_level[idx] -= amount
+            return True
+        log.debug(
+            "%s: item %s unavailable (have %.2f want %.2f).",
+            self.name,
+            self.inv.part_names[idx],
+            self.inv.stock_level[idx],
+            amount,
+        )
+        return False
+
+    def decrement_vector(self, vec: np.ndarray) -> np.ndarray:
+        """Vectorised consumption; returns a boolean mask of which SKUs succeeded."""
+        vec = np.asarray(vec, dtype=float)
+        avail = self.inv.stock_level >= vec
+        self.inv.stock_level = self.inv.stock_level - vec * avail.astype(float)
+        if not avail.all():
+            log.debug("%s: %d SKUs unavailable this tick.", self.name, (~avail).sum())
+        return avail
+
+    def check_items_available(self, requested: np.ndarray) -> np.ndarray:
+        return self.inv.stock_level >= np.asarray(requested, dtype=float)
+
+    # ------------------------------------------------------------------
+    # Reorder bookkeeping
+    # ------------------------------------------------------------------
+    def _receive_pending(self, elapsed: float = 1.0) -> None:
+        self._reorder_time_remaining = np.maximum(
+            0.0, self._reorder_time_remaining - elapsed
+        )
+        arrived = (self._reorder_time_remaining == 0) & (self._reorders_volume > 0)
+        if arrived.any():
+            deliveries = self._reorders_volume * arrived
+            self.increment_vector(deliveries)
+            self._reorders_volume = self._reorders_volume - deliveries
+            self._orders_placed_bool[arrived] = False
+
+    def _place_reorders(self) -> None:
+        need_reorder = (self.inv.stock_level <= self.inv.reorder_points) & (
+            ~self._orders_placed_bool
+        )
+        if not need_reorder.any():
+            return
+        reorders = self.inv.batchsize * need_reorder
+
+        if self.parent == "industry":
+            # Infinite replenishment.
+            pass
+        else:
+            assert isinstance(self.parent, Warehouse)
+            avail = self.parent.check_items_available(reorders)
+            # Decrement parent for the subset that is available.
+            self.parent.inv.stock_level = (
+                self.parent.inv.stock_level - reorders * avail.astype(float)
+            )
+            if not avail.all():
+                missing = ~avail & need_reorder
+                if missing.any():
+                    self._lifetime_backorders[missing] += reorders[missing]
+                need_reorder = need_reorder & avail
+                reorders = reorders * avail.astype(float)
+
+        self._orders_placed_bool = self._orders_placed_bool | need_reorder
+        self._reorders_volume = self._reorders_volume + reorders
+        self._reorder_time_remaining[need_reorder] = self.inv.newbuy_leadtimes[
+            need_reorder
+        ]
+        self._lifetime_total_orders = self._lifetime_total_orders + reorders
+
+    def process_orders(self, elapsed: float = 1.0) -> None:
+        """Tick the reorder logic by ``elapsed`` time units."""
+        self._receive_pending(elapsed)
+        self._place_reorders()
+
+    # ------------------------------------------------------------------
+    # Simulation tick integration
+    # ------------------------------------------------------------------
+    def tick(self, dt: float, env) -> None:
+        super().tick(dt, env)
+        # Default tick just counts down pending orders + places new.
+        # Consumption is driven by external demand -- users call
+        # decrement_vector() from a demand generator process.
+        self.process_orders(elapsed=dt)
+
+    def has_work(self, env) -> bool:
+        return bool((self._reorders_volume > 0).any() or self._orders_placed_bool.any())
+
+    # ------------------------------------------------------------------
+    # Post-hoc estimates
+    # ------------------------------------------------------------------
+    def estimate_demand_rate(self, total_sim_time: float) -> np.ndarray:
+        """Crude demand rate = lifetime orders / total_sim_time."""
+        if total_sim_time <= 0:
+            raise ValueError("total_sim_time must be positive.")
+        self._demand_rate = self._lifetime_total_orders / total_sim_time
+        return self._demand_rate

simweave/units/__init__.py

@@ -0,0 +1,25 @@
+"""Dimensional quantities with SI exponent tracking."""
+
+from simweave.units.si import (
+    SIUnit,
+    Distance,
+    Velocity,
+    Acceleration,
+    Mass,
+    Force,
+    Area,
+    Volume,
+    TimeUnit,
+)
+
+__all__ = [
+    "SIUnit",
+    "Distance",
+    "Velocity",
+    "Acceleration",
+    "Mass",
+    "Force",
+    "Area",
+    "Volume",
+    "TimeUnit",
+]

simweave/units/si.py

@@ -0,0 +1,213 @@
+"""SI unit classes with exponent-tracked dimensional analysis.
+
+Every unit carries a 7-tuple of SI exponents in the order
+(metre, kilogram, ampere, kelvin, mole, candela, second). Multiplication and
+division compose exponents; the result is re-typed to a known concrete class
+when the exponents match one of the registered shapes (e.g. m * m -> Area).
+Addition and subtraction are only permitted between operands of the same
+concrete type.
+
+This module is pure-Python and has no numpy dependency so it can be used in
+tight inner loops without allocating ndarrays.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+_SI_SYMBOLS = ("m", "kg", "A", "K", "mol", "cd", "s")
+
+
+def _unit_string(exponents: tuple[int, ...]) -> str:
+    parts: list[str] = []
+    for symbol, exp in zip(_SI_SYMBOLS, exponents):
+        if exp == 0:
+            continue
+        parts.append(symbol if exp == 1 else f"{symbol}^{exp}")
+    return "*".join(parts) if parts else "dimensionless"
+
+
+def _known_unit(exponents: tuple[int, ...]):
+    return _KNOWN_BY_EXP.get(exponents)
+
+
+@dataclass(slots=True)
+class SIUnit:
+    """Generic SI quantity with exponent-tracked dimensional analysis."""
+
+    value: float
+    unit: str = "dimensionless"
+    exponents: list[int] = field(default_factory=lambda: [0] * 7)
+
+    def __post_init__(self) -> None:
+        if isinstance(self.value, SIUnit):
+            self.value = self.value.value
+        self.value = float(self.value)
+        if len(self.exponents) != 7:
+            raise ValueError("SI exponents must have length 7.")
+
+    # -- representation ------------------------------------------------
+    def __str__(self) -> str:
+        return f"{self.value} [{self.unit}]"
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{type(self).__name__}({self.value}, unit={self.unit!r})"
+
+    # -- additive ------------------------------------------------------
+    def _check_same_dim(self, other: "SIUnit") -> None:
+        if tuple(self.exponents) != tuple(other.exponents):
+            raise TypeError(
+                f"Cannot add/subtract {self.unit} and {other.unit}: different dimensions."
+            )
+
+    def __add__(self, other: object) -> "SIUnit":
+        if not isinstance(other, SIUnit):
+            raise TypeError(
+                f"Cannot add {type(self).__name__} and {type(other).__name__}."
+            )
+        self._check_same_dim(other)
+        cls = type(self) if type(self) is type(other) else SIUnit
+        if cls is SIUnit:
+            return SIUnit(self.value + other.value, self.unit, list(self.exponents))
+        return cls(self.value + other.value)  # type: ignore[arg-type]
+
+    def __sub__(self, other: object) -> "SIUnit":
+        if not isinstance(other, SIUnit):
+            raise TypeError(
+                f"Cannot subtract {type(other).__name__} from {type(self).__name__}."
+            )
+        self._check_same_dim(other)
+        cls = type(self) if type(self) is type(other) else SIUnit
+        if cls is SIUnit:
+            return SIUnit(self.value - other.value, self.unit, list(self.exponents))
+        return cls(self.value - other.value)  # type: ignore[arg-type]
+
+    # -- multiplicative -----------------------------------------------
+    def __mul__(self, other: object) -> "SIUnit":
+        if isinstance(other, (int, float)):
+            return (
+                type(self)(self.value * float(other))
+                if type(self) is not SIUnit
+                else SIUnit(self.value * float(other), self.unit, list(self.exponents))
+            )
+        if isinstance(other, SIUnit):
+            new_exp = tuple(a + b for a, b in zip(self.exponents, other.exponents))
+            cls = _known_unit(new_exp)
+            if cls is None:
+                return SIUnit(
+                    self.value * other.value, _unit_string(new_exp), list(new_exp)
+                )
+            return cls(self.value * other.value)
+        raise TypeError(f"Unsupported multiplication with {type(other).__name__}.")
+
+    def __rmul__(self, other: object) -> "SIUnit":
+        return self.__mul__(other)
+
+    def __truediv__(self, other: object) -> "SIUnit":
+        if isinstance(other, (int, float)):
+            return (
+                type(self)(self.value / float(other))
+                if type(self) is not SIUnit
+                else SIUnit(self.value / float(other), self.unit, list(self.exponents))
+            )
+        if isinstance(other, SIUnit):
+            new_exp = tuple(a - b for a, b in zip(self.exponents, other.exponents))
+            cls = _known_unit(new_exp)
+            if cls is None:
+                return SIUnit(
+                    self.value / other.value, _unit_string(new_exp), list(new_exp)
+                )
+            return cls(self.value / other.value)
+        raise TypeError(f"Unsupported division with {type(other).__name__}.")
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, SIUnit):
+            return NotImplemented
+        return (
+            tuple(self.exponents) == tuple(other.exponents)
+            and self.value == other.value
+        )
+
+    def __hash__(self) -> int:
+        return hash((type(self), self.value, tuple(self.exponents)))
+
+
+# ---------------------------------------------------------------------------
+# Concrete dimensioned units. The existing public names are preserved so that
+# the quarter-car / pendulum / RLC examples remain compatible.
+# ---------------------------------------------------------------------------
+
+
+class Distance(SIUnit):
+    def __init__(self, value: float | SIUnit):
+        super().__init__(value=value, unit="m", exponents=[1, 0, 0, 0, 0, 0, 0])
+
+
+class Velocity(SIUnit):
+    def __init__(self, value: float | SIUnit):
+        super().__init__(value=value, unit="m/s", exponents=[1, 0, 0, 0, 0, 0, -1])
+
+
+class Acceleration(SIUnit):
+    def __init__(self, value: float | SIUnit):
+        super().__init__(value=value, unit="m/s^2", exponents=[1, 0, 0, 0, 0, 0, -2])
+
+
+class Mass(SIUnit):
+    def __init__(self, value: float | SIUnit):
+        super().__init__(value=value, unit="kg", exponents=[0, 1, 0, 0, 0, 0, 0])
+
+
+class Force(SIUnit):
+    def __init__(self, value: float | SIUnit):
+        super().__init__(value=value, unit="N", exponents=[1, 1, 0, 0, 0, 0, -2])
+
+
+class Area(SIUnit):
+    def __init__(self, value: float | SIUnit):
+        super().__init__(value=value, unit="m^2", exponents=[2, 0, 0, 0, 0, 0, 0])
+
+
+class Volume(SIUnit):
+    def __init__(self, value: float | SIUnit):
+        super().__init__(value=value, unit="m^3", exponents=[3, 0, 0, 0, 0, 0, 0])
+
+
+class TimeUnit(SIUnit):
+    """Time, stored canonically in seconds regardless of input unit."""
+
+    _SCALE_MAP: ClassVar[dict[str, float]] = {
+        "s": 1.0,
+        "sec": 1.0,
+        "ms": 1e-3,
+        "mins": 60.0,
+        "min": 60.0,
+        "hrs": 3600.0,
+        "h": 3600.0,
+        "days": 86400.0,
+        "day": 86400.0,
+    }
+
+    def __init__(self, value: float | SIUnit, unit: str = "s"):
+        if isinstance(value, SIUnit):
+            value = value.value
+        if unit not in self._SCALE_MAP:
+            raise ValueError(f"Unsupported time unit: {unit}")
+        super().__init__(
+            value=float(value) * self._SCALE_MAP[unit],
+            unit="s",
+            exponents=[0, 0, 0, 0, 0, 0, 1],
+        )
+
+
+_KNOWN_BY_EXP: dict[tuple[int, ...], type[SIUnit]] = {
+    (1, 0, 0, 0, 0, 0, 0): Distance,
+    (1, 0, 0, 0, 0, 0, -1): Velocity,
+    (1, 0, 0, 0, 0, 0, -2): Acceleration,
+    (0, 1, 0, 0, 0, 0, 0): Mass,
+    (2, 0, 0, 0, 0, 0, 0): Area,
+    (3, 0, 0, 0, 0, 0, 0): Volume,
+    (1, 1, 0, 0, 0, 0, -2): Force,
+    (0, 0, 0, 0, 0, 0, 1): TimeUnit,
+}

simweave/viz/__init__.py

@@ -0,0 +1,77 @@
+"""``simweave.viz`` -- plotly-based visualisation helpers.
+
+Every helper returns a ``plotly.graph_objects.Figure`` so JS frontends
+(such as EdgeWeave) can consume the figure via ``fig.to_json()`` without
+losing structure. Themes are applied via a small registry so users can
+switch between light, dark and custom palettes without rebuilding plots.
+
+Importing this module is cheap; plotly is only required when a plot
+helper is actually called. Install via the optional extra::
+
+    pip install simweave[viz]
+
+Quick start::
+
+    from simweave.viz import (
+        plot_state_trajectories,
+        set_default_theme,
+    )
+    from simweave.continuous import simulate, MassSpringDamper
+
+    res = simulate(MassSpringDamper(), t_span=(0, 10), dt=0.01)
+    set_default_theme("dark")
+    fig = plot_state_trajectories(res)
+    fig.show()              # or fig.write_html("msd.html"), or fig.to_json()
+"""
+
+from __future__ import annotations
+
+from simweave.viz.themes import (
+    Theme,
+    apply_theme,
+    available_themes,
+    get_default_theme,
+    get_theme,
+    register_theme,
+    set_default_theme,
+)
+from simweave.viz.recorders import (
+    QueueLengthRecorder,
+    ServiceUtilisationRecorder,
+    WarehouseStockRecorder,
+)
+from simweave.viz.plots import (
+    plot_agent_path,
+    plot_mc_fan,
+    plot_phase_portrait,
+    plot_queue_length,
+    plot_service_utilisation,
+    plot_state_trajectories,
+    plot_warehouse_stock,
+)
+from simweave.viz._plotly import have_plotly
+
+__all__ = [
+    # Themes
+    "Theme",
+    "apply_theme",
+    "available_themes",
+    "get_default_theme",
+    "get_theme",
+    "register_theme",
+    "set_default_theme",
+    # Recorders
+    "QueueLengthRecorder",
+    "ServiceUtilisationRecorder",
+    "WarehouseStockRecorder",
+    # Plot helpers
+    "plot_agent_path",
+    "plot_mc_fan",
+    "plot_phase_portrait",
+    "plot_queue_length",
+    "plot_service_utilisation",
+    "plot_state_trajectories",
+    "plot_warehouse_stock",
+    # Probe
+    "have_plotly",
+]

simweave/viz/_plotly.py

@@ -0,0 +1,35 @@
+"""Internal helper: lazy import plotly with a friendly error.
+
+simweave's core does not depend on plotly. Users who want viz install via
+the optional extra ``simweave[viz]``. Importing :mod:`simweave.viz` at the
+top level is cheap; the heavy import only happens when a plot helper is
+actually called.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+_INSTALL_HINT = (
+    "simweave.viz requires plotly. Install with `pip install simweave[viz]` "
+    "or `pip install plotly>=5.18`."
+)
+
+
+def require_go() -> Any:
+    """Return ``plotly.graph_objects`` or raise a clear ImportError."""
+    try:
+        import plotly.graph_objects as go  # type: ignore[import-not-found]
+    except ImportError as e:  # pragma: no cover - exercised when plotly absent
+        raise ImportError(_INSTALL_HINT) from e
+    return go
+
+
+def have_plotly() -> bool:
+    """Cheap probe: does the current environment have plotly available?"""
+    try:
+        import plotly  # noqa: F401
+    except ImportError:
+        return False
+    return True