simweave 0.4.0__py3-none-any.whl

simweave/core/entity.py

@@ -0,0 +1,74 @@
+"""Entity base class.
+
+Everything that persists across ticks in simweave -- items, resources, agents,
+queues, services -- inherits from :class:`Entity`. The contract is small:
+
+* ``tick(dt, env)`` is called once per simulation tick for registered entities
+  (processes). The default implementation just ages the entity.
+* ``has_work(env)`` reports whether this entity has pending work *right now*;
+  used by the environment's skip-idle-gaps fast path.
+
+Items flowing through queues do not need to be registered themselves; they
+ride along with whatever process owns them. Queues and services age their
+contained items in their own ``tick``.
+"""
+
+from __future__ import annotations
+
+from itertools import count
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from simweave.core.environment import SimEnvironment
+
+
+class Entity:
+    """Base class for simulation entities."""
+
+    _id_counter = count(0)
+
+    def __init__(self, name: str | None = None) -> None:
+        self.id: int = next(Entity._id_counter)
+        self.name: str = (
+            name if name is not None else f"{type(self).__name__}_{self.id}"
+        )
+        self.created_at: float | None = None
+        self.age: float = 0.0
+        # Queue residency bookkeeping.
+        self.current_wait_time: float = 0.0
+        self.total_wait_time: float = 0.0
+        # Populated by a Service when pulling this entity for processing.
+        self.remaining_service_time: float = 0.0
+
+    def on_register(self, env: "SimEnvironment") -> None:
+        """Hook called when this entity is registered with an environment."""
+        if self.created_at is None:
+            self.created_at = env.clock.t
+
+    def tick(self, dt: float, env: "SimEnvironment") -> None:
+        """Advance this entity by ``dt`` simulation seconds.
+
+        Subclasses should call ``super().tick(dt, env)`` first (to keep the
+        age counter correct) before doing their own logic.
+        """
+        self.age += dt
+
+    def has_work(self, env: "SimEnvironment") -> bool:
+        """Report whether this entity has pending work.
+
+        The default is ``False`` -- plain items waiting in a queue are not
+        themselves "doing work" in the skip-idle-gaps sense; the queue/service
+        holding them is.
+        """
+        return False
+
+    # ------------------------------------------------------------------
+    # Dunder conveniences
+    # ------------------------------------------------------------------
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{type(self).__name__}(name={self.name!r}, id={self.id})"
+
+    @classmethod
+    def reset_id_counter(cls) -> None:
+        """Reset the shared ID counter. Useful between replicates in tests."""
+        cls._id_counter = count(0)

simweave/core/environment.py

@@ -0,0 +1,121 @@
+"""Simulation environment: clock + event queue + process registry.
+
+A :class:`SimEnvironment` owns the authoritative clock and an optional event
+queue. Processes (anything with a ``tick(dt, env)`` method) are registered so
+they step together each tick. An optional ``graph`` attribute exists as a
+convenience for spatial/agent simulations that need a shared topology.
+
+Run styles
+----------
+* ``env.run(until)`` -- step the clock by ``dt`` until ``t >= until``.
+* ``env.run(until, skip_idle_gaps=True)`` -- if nothing has work in the
+  current tick and the next pending event is strictly in the future, jump the
+  clock straight to that event. This degenerates to pure fixed-step when
+  events are dense, and approaches DEVS efficiency when they are sparse.
+* ``env.step()`` -- advance exactly one tick (useful in tests).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable, Protocol, runtime_checkable
+
+from simweave.core.clock import Clock
+from simweave.core.scheduler import EventQueue, ScheduledEvent
+from simweave.core.logging import get_logger
+
+log = get_logger("env")
+
+
+@runtime_checkable
+class Process(Protocol):
+    """A process that participates in the tick loop."""
+
+    def tick(self, dt: float, env: "SimEnvironment") -> None: ...
+
+
+class SimEnvironment:
+    """Container for a clock, an event queue, and registered processes."""
+
+    def __init__(
+        self,
+        start: float = 0.0,
+        dt: float = 1.0,
+        end: float | None = None,
+        graph: Any = None,
+    ) -> None:
+        self.clock = Clock(start=start, dt=dt, end=end)
+        self.events = EventQueue()
+        self.graph = graph
+        self._processes: list[Process] = []
+
+    # ------------------------------------------------------------------
+    # Process registry
+    # ------------------------------------------------------------------
+    def register(self, process: Process) -> Process:
+        """Register a process so it is ticked each simulation step."""
+        if not hasattr(process, "tick"):
+            raise TypeError("Registered process must implement tick(dt, env).")
+        self._processes.append(process)
+        on_register = getattr(process, "on_register", None)
+        if callable(on_register):
+            on_register(self)
+        return process
+
+    def register_all(self, processes: Iterable[Process]) -> None:
+        for p in processes:
+            self.register(p)
+
+    @property
+    def processes(self) -> tuple[Process, ...]:
+        return tuple(self._processes)
+
+    # ------------------------------------------------------------------
+    # Event scheduling helpers
+    # ------------------------------------------------------------------
+    def schedule_at(
+        self, time: float, callback: Callable[..., Any], *args: Any, **kwargs: Any
+    ) -> ScheduledEvent:
+        return self.events.schedule(time, callback, *args, **kwargs)
+
+    def schedule_after(
+        self, delay: float, callback: Callable[..., Any], *args: Any, **kwargs: Any
+    ) -> ScheduledEvent:
+        return self.events.schedule(self.clock.t + delay, callback, *args, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Running
+    # ------------------------------------------------------------------
+    def step(self) -> None:
+        """Process events due at ``t``, tick every process, then advance."""
+        for evt in self.events.pop_due(self.clock.t):
+            evt.callback(*evt.args, **evt.kwargs)
+        for p in self._processes:
+            p.tick(self.clock.dt, self)
+        self.clock.advance()
+
+    def run(self, until: float | None = None, skip_idle_gaps: bool = False) -> None:
+        """Run the simulation until ``until`` or ``clock.end``."""
+        if until is None:
+            until = self.clock.end
+        if until is None:
+            raise ValueError("Pass `until` or set clock.end before calling run().")
+        if until <= self.clock.t:
+            return
+
+        while self.clock.t < until:
+            if skip_idle_gaps and not self._any_has_work():
+                next_evt = self.events.peek_time()
+                if next_evt is not None and next_evt > self.clock.t:
+                    self.clock.jump_to(min(next_evt, until))
+                    continue
+                # Nothing has work and no future events -> nothing will change.
+                if next_evt is None:
+                    log.debug(
+                        "No work and no pending events; halting early at t=%s.",
+                        self.clock.t,
+                    )
+                    break
+            self.step()
+
+    def _any_has_work(self) -> bool:
+        return any(p.has_work(self) for p in self._processes if hasattr(p, "has_work"))

simweave/core/logging.py

@@ -0,0 +1,41 @@
+"""Lightweight logging helpers.
+
+The previous ``print_display`` class has been retired in favour of stdlib
+``logging``. Import ``get_logger(name)`` from here for a consistent simweave
+logger hierarchy.
+"""
+
+from __future__ import annotations
+
+import logging
+
+_ROOT = "simweave"
+_configured = False
+
+
+def configure(
+    level: int | str = logging.INFO,
+    fmt: str = "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    force: bool = False,
+) -> None:
+    """Configure the simweave logger hierarchy. Safe to call many times."""
+    global _configured
+    if _configured and not force:
+        return
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter(fmt))
+    root = logging.getLogger(_ROOT)
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(level)
+    root.propagate = False
+    _configured = True
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a logger under the ``simweave`` namespace."""
+    if name is None or name == _ROOT:
+        return logging.getLogger(_ROOT)
+    if name.startswith(_ROOT + "."):
+        return logging.getLogger(name)
+    return logging.getLogger(f"{_ROOT}.{name}")

simweave/core/scheduler.py

@@ -0,0 +1,85 @@
+"""Optional heap-based event queue.
+
+The atomic-clock core ticks every process each timestep. Sometimes that's
+wasteful -- e.g. a warehouse that reorders once a week does not want to be
+polled 10080 times in between. The :class:`EventQueue` lets processes post
+callbacks to fire at (or after) a given simulation time. The environment
+drains any events whose scheduled time has been reached at the start of each
+tick.
+
+When combined with ``SimEnvironment.run(skip_idle_gaps=True)``, this also
+powers a DEVS-style fast path: if every registered process reports
+``has_work() is False`` and an event is pending at ``t_next``, the clock
+fast-forwards directly to ``t_next`` rather than grinding through empty
+ticks.
+"""
+
+from __future__ import annotations
+
+import heapq
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass(order=True)
+class ScheduledEvent:
+    """Heap-ordered event record.
+
+    ``seq`` is a tiebreaker so that two events at the same ``time`` fire in
+    insertion order, giving deterministic behaviour for simultaneous events.
+    """
+
+    time: float
+    seq: int
+    callback: Callable[..., Any] = field(compare=False)
+    args: tuple = field(compare=False, default=())
+    kwargs: dict = field(compare=False, default_factory=dict)
+    cancelled: bool = field(compare=False, default=False)
+
+
+class EventQueue:
+    """Min-heap priority queue of scheduled callbacks."""
+
+    def __init__(self) -> None:
+        self._heap: list[ScheduledEvent] = []
+        self._seq: int = 0
+
+    def __len__(self) -> int:
+        return sum(1 for e in self._heap if not e.cancelled)
+
+    def __bool__(self) -> bool:
+        return len(self) > 0
+
+    def schedule(
+        self, time: float, callback: Callable[..., Any], *args: Any, **kwargs: Any
+    ) -> ScheduledEvent:
+        """Schedule ``callback(*args, **kwargs)`` to fire at simulation ``time``."""
+        evt = ScheduledEvent(
+            time=float(time), seq=self._seq, callback=callback, args=args, kwargs=kwargs
+        )
+        heapq.heappush(self._heap, evt)
+        self._seq += 1
+        return evt
+
+    def peek_time(self) -> float | None:
+        """Return the time of the next non-cancelled event, or ``None``."""
+        self._drop_cancelled()
+        return self._heap[0].time if self._heap else None
+
+    def pop_due(self, now: float):
+        """Yield every non-cancelled event whose time is ``<= now``."""
+        self._drop_cancelled()
+        while self._heap and self._heap[0].time <= now:
+            evt = heapq.heappop(self._heap)
+            if evt.cancelled:
+                continue
+            yield evt
+            self._drop_cancelled()
+
+    def cancel(self, event: ScheduledEvent) -> None:
+        """Flag an event as cancelled without paying heap-removal cost."""
+        event.cancelled = True
+
+    def _drop_cancelled(self) -> None:
+        while self._heap and self._heap[0].cancelled:
+            heapq.heappop(self._heap)

simweave/currency/__init__.py

@@ -0,0 +1,64 @@
+"""simweave.currency: Decimal-backed Money, ISO 4217 codes, FX conversion.
+
+Public surface
+--------------
+* :class:`Money` — frozen, currency-tagged ``Decimal`` value with
+  strict same-currency arithmetic and explicit FX conversion.
+* :class:`CurrencyMismatchError` — raised on cross-currency ops.
+* :class:`FXConverter` — Protocol for rate lookup.
+* :class:`StaticFXConverter` — in-memory rate table with automatic
+  inverse lookup. Use for deterministic tests and fixed-rate models.
+* :class:`CallableFXConverter` — adapts an arbitrary callable to the
+  :class:`FXConverter` protocol.
+* :func:`format_money` — ASCII default formatter, optional locale-aware
+  path via ``simweave[intl]`` (babel).
+* :func:`register_custom`, :func:`unregister_custom` — escape hatch for
+  crypto, in-game, or test-fixture currency codes.
+* :func:`is_valid_currency`, :func:`get_decimals`, :func:`list_codes` —
+  registry introspection helpers.
+
+Design contract in short
+------------------------
+* Decimal everywhere; float inputs routed via ``str()`` to avoid
+  binary-float drift.
+* Banker's rounding (``ROUND_HALF_EVEN``) at display / quantisation
+  time; full precision preserved during computation.
+* Cross-currency arithmetic refuses — use ``money.to(target, fx)``.
+* Scalar * Money allowed; Money * Money refused.
+* Money / Money (same currency) returns ``float``; Money / scalar
+  returns Money.
+* Negatives are legal (debts, refunds, signed cashflows).
+"""
+
+from simweave.currency.codes import (
+    get_decimals,
+    is_valid_currency,
+    list_codes,
+    register_custom,
+    unregister_custom,
+)
+from simweave.currency.format import format_money
+from simweave.currency.fx import (
+    CallableFXConverter,
+    FXConverter,
+    StaticFXConverter,
+)
+from simweave.currency.money import CurrencyMismatchError, Money
+
+__all__ = [
+    # Core value type
+    "Money",
+    "CurrencyMismatchError",
+    # FX
+    "FXConverter",
+    "StaticFXConverter",
+    "CallableFXConverter",
+    # Formatting
+    "format_money",
+    # Registry
+    "register_custom",
+    "unregister_custom",
+    "is_valid_currency",
+    "get_decimals",
+    "list_codes",
+]

simweave/currency/codes.py

@@ -0,0 +1,257 @@
+"""ISO 4217 currency registry.
+
+Maps an uppercase three-letter code (e.g. ``"GBP"``) to the number of
+minor-unit decimal places defined by ISO 4217 for that currency. A
+conservative subset of the ~180 active codes is baked in — enough to
+cover >99% of the world's tradable currencies without dragging in
+deprecated codes or fund/metal codes (XAU, XDR) that aren't "money"
+in any operational sense.
+
+For anything outside this registry (crypto, in-game currencies, test
+fixtures), use :func:`register_custom`.
+
+The registry is process-local: custom registrations do not persist
+across Python processes. This is deliberate — hard-coding crypto rates
+or custom codes across team members would be an anti-pattern.
+"""
+
+from __future__ import annotations
+
+# ISO 4217 minor-unit exponents. Listed by decimal places for readability.
+_ISO_4217: dict[str, int] = {
+    # 0 decimal places (no minor units)
+    "BIF": 0,
+    "CLP": 0,
+    "DJF": 0,
+    "GNF": 0,
+    "ISK": 0,
+    "JPY": 0,
+    "KMF": 0,
+    "KRW": 0,
+    "PYG": 0,
+    "RWF": 0,
+    "UGX": 0,
+    "UYI": 0,
+    "VND": 0,
+    "VUV": 0,
+    "XAF": 0,
+    "XOF": 0,
+    "XPF": 0,
+    # 2 decimal places (the vast majority)
+    "AED": 2,
+    "AFN": 2,
+    "ALL": 2,
+    "AMD": 2,
+    "ANG": 2,
+    "AOA": 2,
+    "ARS": 2,
+    "AUD": 2,
+    "AWG": 2,
+    "AZN": 2,
+    "BAM": 2,
+    "BBD": 2,
+    "BDT": 2,
+    "BGN": 2,
+    "BMD": 2,
+    "BND": 2,
+    "BOB": 2,
+    "BRL": 2,
+    "BSD": 2,
+    "BWP": 2,
+    "BYN": 2,
+    "BZD": 2,
+    "CAD": 2,
+    "CDF": 2,
+    "CHF": 2,
+    "CNY": 2,
+    "COP": 2,
+    "CRC": 2,
+    "CUP": 2,
+    "CVE": 2,
+    "CZK": 2,
+    "DKK": 2,
+    "DOP": 2,
+    "DZD": 2,
+    "EGP": 2,
+    "ERN": 2,
+    "ETB": 2,
+    "EUR": 2,
+    "FJD": 2,
+    "FKP": 2,
+    "GBP": 2,
+    "GEL": 2,
+    "GHS": 2,
+    "GIP": 2,
+    "GMD": 2,
+    "GTQ": 2,
+    "GYD": 2,
+    "HKD": 2,
+    "HNL": 2,
+    "HRK": 2,
+    "HTG": 2,
+    "HUF": 2,
+    "IDR": 2,
+    "ILS": 2,
+    "INR": 2,
+    "IRR": 2,
+    "JMD": 2,
+    "KES": 2,
+    "KGS": 2,
+    "KHR": 2,
+    "KPW": 2,
+    "KYD": 2,
+    "KZT": 2,
+    "LAK": 2,
+    "LBP": 2,
+    "LKR": 2,
+    "LRD": 2,
+    "LSL": 2,
+    "MAD": 2,
+    "MDL": 2,
+    "MGA": 2,
+    "MKD": 2,
+    "MMK": 2,
+    "MNT": 2,
+    "MOP": 2,
+    "MRU": 2,
+    "MUR": 2,
+    "MVR": 2,
+    "MWK": 2,
+    "MXN": 2,
+    "MYR": 2,
+    "MZN": 2,
+    "NAD": 2,
+    "NGN": 2,
+    "NIO": 2,
+    "NOK": 2,
+    "NPR": 2,
+    "NZD": 2,
+    "PAB": 2,
+    "PEN": 2,
+    "PGK": 2,
+    "PHP": 2,
+    "PKR": 2,
+    "PLN": 2,
+    "QAR": 2,
+    "RON": 2,
+    "RSD": 2,
+    "RUB": 2,
+    "SAR": 2,
+    "SBD": 2,
+    "SCR": 2,
+    "SDG": 2,
+    "SEK": 2,
+    "SGD": 2,
+    "SHP": 2,
+    "SLE": 2,
+    "SOS": 2,
+    "SRD": 2,
+    "SSP": 2,
+    "STN": 2,
+    "SVC": 2,
+    "SYP": 2,
+    "SZL": 2,
+    "THB": 2,
+    "TJS": 2,
+    "TMT": 2,
+    "TOP": 2,
+    "TRY": 2,
+    "TTD": 2,
+    "TWD": 2,
+    "TZS": 2,
+    "UAH": 2,
+    "USD": 2,
+    "UYU": 2,
+    "UZS": 2,
+    "VES": 2,
+    "WST": 2,
+    "XCD": 2,
+    "YER": 2,
+    "ZAR": 2,
+    "ZMW": 2,
+    "ZWL": 2,
+    # 3 decimal places (Middle East oil currencies)
+    "BHD": 3,
+    "IQD": 3,
+    "JOD": 3,
+    "KWD": 3,
+    "LYD": 3,
+    "OMR": 3,
+    "TND": 3,
+    # 4 decimal places (rare, mostly historic settlement)
+    "CLF": 4,
+    "UYW": 4,
+}
+
+# User-registered custom codes.
+_CUSTOM: dict[str, int] = {}
+
+
+def is_valid_currency(code: str) -> bool:
+    """Return True if ``code`` is a known ISO 4217 or custom-registered code."""
+    if not isinstance(code, str):
+        return False
+    up = code.upper()
+    return up in _ISO_4217 or up in _CUSTOM
+
+
+def get_decimals(code: str) -> int:
+    """Return the canonical decimal places for ``code``.
+
+    Raises
+    ------
+    KeyError
+        If the code is not a known ISO 4217 or custom-registered code.
+    """
+    up = code.upper()
+    if up in _CUSTOM:
+        return _CUSTOM[up]
+    if up in _ISO_4217:
+        return _ISO_4217[up]
+    raise KeyError(
+        f"Unknown currency code: {code!r}. "
+        f"Use simweave.currency.register_custom({code!r}, decimals=...) if intentional."
+    )
+
+
+def register_custom(code: str, decimals: int) -> None:
+    """Register a non-ISO currency code (crypto, in-game currency, test fixture).
+
+    Parameters
+    ----------
+    code:
+        Uppercase identifier. Overwrites a prior custom registration but
+        refuses to shadow a real ISO 4217 code.
+    decimals:
+        Non-negative number of minor-unit decimal places.
+
+    Examples
+    --------
+    >>> from simweave.currency import register_custom, Money
+    >>> register_custom("BTC", decimals=8)
+    >>> Money("0.12345678", "BTC").amount
+    Decimal('0.12345678')
+    """
+    if not isinstance(code, str) or not code.strip():
+        raise ValueError("Currency code must be a non-empty string.")
+    up = code.upper()
+    if up in _ISO_4217:
+        raise ValueError(
+            f"{up!r} is an ISO 4217 code; refuse to shadow with register_custom."
+        )
+    if not isinstance(decimals, int) or decimals < 0:
+        raise ValueError("decimals must be a non-negative integer.")
+    _CUSTOM[up] = decimals
+
+
+def unregister_custom(code: str) -> None:
+    """Remove a previously registered custom code. No-op if absent."""
+    _CUSTOM.pop(code.upper(), None)
+
+
+def list_codes(*, include_custom: bool = True) -> tuple[str, ...]:
+    """Return a sorted tuple of all currently known codes."""
+    codes = set(_ISO_4217)
+    if include_custom:
+        codes.update(_CUSTOM)
+    return tuple(sorted(codes))