simweave 0.4.0__py3-none-any.whl

simweave/currency/format.py

@@ -0,0 +1,92 @@
+"""Formatting for :class:`Money`.
+
+Two paths:
+
+* **ASCII default** (always available): ``"GBP 1,234.50"``. No locale
+  assumptions — readable in logs, CSVs, and anywhere a BOM-sensitive
+  consumer might see it.
+* **Locale-aware via babel** (optional, ``simweave[intl]``):
+  ``"£1,234.50"`` with the currency symbol and digit grouping of the
+  user's locale.
+
+The format specifier protocol supported by ``f"{m:...}"``:
+
+* ``""``        -> default ASCII (``GBP 1,234.50``)
+* ``"r"``       -> round to currency precision first, then default ASCII
+* ``"raw"``     -> raw ``Decimal`` text, no grouping, no currency tag
+* Anything starting with a locale code containing ``_`` (e.g.
+  ``"en_GB"``) -> locale-aware via babel; raises ``ImportError`` if
+  ``simweave[intl]`` not installed.
+"""
+
+from __future__ import annotations
+
+from decimal import ROUND_HALF_EVEN, Decimal
+from typing import TYPE_CHECKING
+
+from simweave.currency.codes import get_decimals
+
+if TYPE_CHECKING:
+    from simweave.currency.money import Money
+
+
+def _ascii_format(money: "Money", round_first: bool) -> str:
+    decimals = get_decimals(money.currency)
+    amount = money.amount
+    if round_first:
+        quant = Decimal(10) ** -decimals
+        amount = amount.quantize(quant, rounding=ROUND_HALF_EVEN)
+    # Split sign and magnitude so grouping applies to the digits only.
+    sign = "-" if amount < 0 else ""
+    magnitude = abs(amount)
+    if decimals == 0:
+        body = f"{magnitude:,.0f}"
+    else:
+        body = f"{magnitude:,.{decimals}f}"
+    return f"{sign}{money.currency} {body}"
+
+
+def _babel_format(money: "Money", locale: str) -> str:
+    try:
+        from babel.numbers import format_currency
+    except ImportError as exc:  # pragma: no cover - optional extra
+        raise ImportError(
+            "Locale-aware money formatting requires babel. "
+            "Install with `pip install simweave[intl]`."
+        ) from exc
+    return format_currency(money.amount, money.currency, locale=locale)
+
+
+def format_money(money: "Money", spec: str = "", locale: str | None = None) -> str:
+    """Format a :class:`Money` for display.
+
+    Parameters
+    ----------
+    money:
+        The value to render.
+    spec:
+        Format specifier. See module docstring.
+    locale:
+        Optional locale identifier (e.g. ``"en_GB"``). Overrides ``spec``
+        when provided. Requires ``simweave[intl]`` (babel).
+
+    Returns
+    -------
+    str
+        The formatted string.
+    """
+    if locale is not None:
+        return _babel_format(money, locale)
+    if not spec:
+        return _ascii_format(money, round_first=True)
+    if spec == "r":
+        return _ascii_format(money, round_first=True)
+    if spec == "raw":
+        # Full-precision decimal text, no currency tag, no grouping.
+        return str(money.amount)
+    if "_" in spec:
+        return _babel_format(money, spec)
+    raise ValueError(
+        f"Unknown Money format spec: {spec!r}. "
+        f"Use '' / 'r' / 'raw' or a locale like 'en_GB'."
+    )

simweave/currency/fx.py

@@ -0,0 +1,126 @@
+"""Foreign exchange conversion protocol and built-in strategies.
+
+simweave deliberately **does not ship live FX rates.** Network data,
+API keys, and rate-limits don't belong in a simulation kernel. Users
+supply their own converter — either a static in-memory table for
+deterministic testing, or a callable wrapper around whatever service
+their application uses (Bloomberg, OANDA, ECB reference rates, etc.).
+
+The :class:`FXConverter` protocol keeps this contract minimal: one
+method, ``rate(source, target, at=None) -> Decimal``.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING, Callable, Mapping, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+@runtime_checkable
+class FXConverter(Protocol):
+    """Protocol for anything that can quote an FX rate.
+
+    ``rate(source, target, at=None)`` returns the number of ``target``
+    units per one unit of ``source``. A rate of ``1.27`` for
+    ``("GBP", "USD")`` means one pound buys 1.27 dollars.
+    """
+
+    def rate(
+        self,
+        source: str,
+        target: str,
+        at: "datetime | None" = None,
+    ) -> Decimal: ...
+
+
+class StaticFXConverter:
+    """Fixed-rate converter backed by an in-memory table.
+
+    Automatically handles inverses: if ``("GBP", "USD") -> 1.27`` is
+    registered, ``rate("USD", "GBP")`` returns ``1 / 1.27`` without
+    needing an explicit entry.
+
+    Parameters
+    ----------
+    rates:
+        Mapping of ``(source, target)`` tuples to the rate. Rates may
+        be ``Decimal``, ``float``, ``int``, or a numeric string; all
+        are coerced to ``Decimal`` via ``Decimal(str(value))``.
+    """
+
+    __slots__ = ("_rates",)
+
+    def __init__(
+        self,
+        rates: Mapping[tuple[str, str], Decimal | float | int | str],
+    ) -> None:
+        self._rates: dict[tuple[str, str], Decimal] = {}
+        for (src, tgt), r in rates.items():
+            key = (src.upper(), tgt.upper())
+            if key[0] == key[1]:
+                # Identity rate is always 1 — silently ignore explicit entry.
+                continue
+            self._rates[key] = Decimal(str(r))
+
+    def rate(
+        self,
+        source: str,
+        target: str,
+        at: "datetime | None" = None,  # noqa: ARG002 - signature compatibility
+    ) -> Decimal:
+        src = source.upper()
+        tgt = target.upper()
+        if src == tgt:
+            return Decimal("1")
+        if (src, tgt) in self._rates:
+            return self._rates[(src, tgt)]
+        if (tgt, src) in self._rates:
+            return Decimal("1") / self._rates[(tgt, src)]
+        raise KeyError(
+            f"No FX rate defined for {src} -> {tgt}. "
+            f"Provide it explicitly or register the inverse."
+        )
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"StaticFXConverter({len(self._rates)} rates)"
+
+
+class CallableFXConverter:
+    """Wrap an arbitrary callable as an :class:`FXConverter`.
+
+    The wrapped callable must accept ``(source, target, at)`` and return
+    something coercible to ``Decimal`` (via ``Decimal(str(...))``).
+    Useful when you already have a rate-lookup function.
+
+    Example
+    -------
+    >>> def my_lookup(src, tgt, at=None):
+    ...     return 1.27 if (src, tgt) == ("GBP", "USD") else 1.0
+    >>> fx = CallableFXConverter(my_lookup)
+    >>> fx.rate("GBP", "USD")
+    Decimal('1.27')
+    """
+
+    __slots__ = ("_fn",)
+
+    def __init__(
+        self,
+        fn: Callable[[str, str, "datetime | None"], Decimal | float | int | str],
+    ) -> None:
+        self._fn = fn
+
+    def rate(
+        self,
+        source: str,
+        target: str,
+        at: "datetime | None" = None,
+    ) -> Decimal:
+        src = source.upper()
+        tgt = target.upper()
+        if src == tgt:
+            return Decimal("1")
+        raw = self._fn(src, tgt, at)
+        return Decimal(str(raw))

simweave/currency/money.py

@@ -0,0 +1,328 @@
+"""The :class:`Money` type — a currency-tagged Decimal value.
+
+Design notes
+------------
+* **Decimal everywhere, no float drift.** Amounts are stored as
+  :class:`decimal.Decimal`. Integer, float, and string inputs are
+  coerced through ``Decimal(str(value))`` to avoid the classic
+  ``Decimal(0.1) -> Decimal('0.1000000000000000055511151231257827021181583404541015625')``
+  surprise.
+* **Banker's rounding at display/quantisation time.** Computation keeps
+  full precision; rounding is only applied when the caller asks for it
+  (``round_to_currency`` or ``format_money``). ``ROUND_HALF_EVEN`` is
+  the default — configurable via ``rounding=`` where supported.
+* **Cross-currency arithmetic refuses.** ``GBP + USD`` raises
+  :class:`CurrencyMismatchError` rather than silently coercing. Users
+  must call ``money.to(target, converter)`` with an explicit FX
+  converter to change currencies.
+* **Scalar-only multiplication.** ``Money * int/float/Decimal`` returns
+  a ``Money`` in the same currency. ``Money * Money`` is ill-defined
+  dimensionally (square-pounds?) and raises.
+* **Ratios are dimensionless.** ``Money / Money`` (same currency)
+  returns a plain ``float``. Different currencies raise.
+* **Negatives allowed.** Debts, refunds, and signed cashflows are
+  legitimate — no ``ValueError`` on negative amounts.
+* **Frozen, hashable.** Two ``Money`` values are equal iff both
+  currency and amount match exactly. Hash is consistent with equality.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal, ROUND_HALF_EVEN, InvalidOperation
+from typing import TYPE_CHECKING, Any, Union
+
+from simweave.currency.codes import get_decimals, is_valid_currency
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from simweave.currency.fx import FXConverter
+
+
+Numeric = Union[int, float, Decimal, str]
+
+
+class CurrencyMismatchError(TypeError):
+    """Raised when an operation requires two Money values to share a currency
+    but they don't (e.g. ``GBP + USD``).
+
+    Subclasses :class:`TypeError` so that ``except TypeError`` catches it in
+    legacy code, while new code can ``except CurrencyMismatchError`` for
+    precise handling.
+    """
+
+
+def _coerce_amount(value: Any) -> Decimal:
+    """Coerce ``value`` to Decimal without float-binary drift."""
+    if isinstance(value, Decimal):
+        return value
+    if isinstance(value, bool):
+        # bool is a subclass of int — refuse it explicitly; "True pounds"
+        # is almost certainly a bug.
+        raise TypeError("Money amount cannot be a bool.")
+    if isinstance(value, int):
+        return Decimal(value)
+    if isinstance(value, float):
+        # Route through str so 0.1 becomes Decimal('0.1'), not the binary
+        # expansion.
+        return Decimal(str(value))
+    if isinstance(value, str):
+        try:
+            return Decimal(value.strip())
+        except InvalidOperation as exc:
+            raise ValueError(f"Cannot parse {value!r} as a decimal amount.") from exc
+    raise TypeError(
+        f"Money amount must be numeric (int/float/Decimal/str); got {type(value).__name__}."
+    )
+
+
+def _normalise_code(code: Any) -> str:
+    if not isinstance(code, str):
+        raise TypeError(f"Currency code must be a string; got {type(code).__name__}.")
+    up = code.strip().upper()
+    if not up:
+        raise ValueError("Currency code must not be empty.")
+    return up
+
+
+@dataclass(frozen=True, slots=True)
+class Money:
+    """A currency-tagged monetary amount.
+
+    Parameters
+    ----------
+    amount:
+        The numeric amount. Accepts ``int``, ``float``, ``Decimal``, or
+        ``str``. Float inputs are routed via :class:`str` to avoid
+        binary-float drift.
+    currency:
+        ISO 4217 three-letter code (case-insensitive; normalised to
+        uppercase). Must be either a known ISO 4217 code or a code
+        previously registered via
+        :func:`simweave.currency.codes.register_custom`.
+
+    Examples
+    --------
+    >>> from simweave.currency import Money
+    >>> Money(100, "GBP") + Money("50.25", "GBP")
+    Money(Decimal('150.25'), 'GBP')
+    >>> Money(100, "GBP") * 3
+    Money(Decimal('300'), 'GBP')
+    """
+
+    amount: Decimal
+    currency: str
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+    def __post_init__(self) -> None:
+        # Coerce and validate. Frozen dataclass requires object.__setattr__.
+        object.__setattr__(self, "amount", _coerce_amount(self.amount))
+        code = _normalise_code(self.currency)
+        if not is_valid_currency(code):
+            raise ValueError(
+                f"Unknown currency code: {code!r}. "
+                f"Use simweave.currency.register_custom({code!r}, decimals=...) "
+                f"if intentional."
+            )
+        object.__setattr__(self, "currency", code)
+
+    # ------------------------------------------------------------------
+    # Rounding / quantisation
+    # ------------------------------------------------------------------
+    @property
+    def decimals(self) -> int:
+        """Canonical minor-unit decimal places for this currency."""
+        return get_decimals(self.currency)
+
+    def round_to_currency(self, rounding: str = ROUND_HALF_EVEN) -> "Money":
+        """Return a new ``Money`` rounded to the currency's minor-unit
+        precision. Defaults to banker's rounding (``ROUND_HALF_EVEN``)."""
+        quant = Decimal(10) ** -self.decimals
+        return Money(self.amount.quantize(quant, rounding=rounding), self.currency)
+
+    # ------------------------------------------------------------------
+    # Sign / absolute
+    # ------------------------------------------------------------------
+    def __neg__(self) -> "Money":
+        return Money(-self.amount, self.currency)
+
+    def __pos__(self) -> "Money":
+        return self
+
+    def __abs__(self) -> "Money":
+        return Money(abs(self.amount), self.currency)
+
+    def is_negative(self) -> bool:
+        return self.amount < 0
+
+    def is_zero(self) -> bool:
+        return self.amount == 0
+
+    # ------------------------------------------------------------------
+    # Additive operators
+    # ------------------------------------------------------------------
+    def _check_same_currency(self, other: "Money", op: str) -> None:
+        if self.currency != other.currency:
+            raise CurrencyMismatchError(
+                f"Cannot {op} {self.currency} and {other.currency}: "
+                f"different currencies. Use .to(target, converter) to convert."
+            )
+
+    def __add__(self, other: object) -> "Money":
+        if not isinstance(other, Money):
+            return NotImplemented
+        self._check_same_currency(other, "+")
+        return Money(self.amount + other.amount, self.currency)
+
+    def __radd__(self, other: object) -> "Money":
+        # Permit sum([...], start=Money(0, "GBP")) without weird interactions;
+        # but refuse bare int 0 which is what ``sum()`` defaults to, because
+        # mixing currencies via sum() with default start is a common bug.
+        if other == 0:
+            raise TypeError(
+                "Cannot add Money to bare 0; pass start=Money(0, currency) "
+                "to sum() to accumulate Money values."
+            )
+        return NotImplemented
+
+    def __sub__(self, other: object) -> "Money":
+        if not isinstance(other, Money):
+            return NotImplemented
+        self._check_same_currency(other, "-")
+        return Money(self.amount - other.amount, self.currency)
+
+    # ------------------------------------------------------------------
+    # Multiplicative operators
+    # ------------------------------------------------------------------
+    def __mul__(self, other: object) -> "Money":
+        if isinstance(other, Money):
+            raise TypeError(
+                "Money * Money is not dimensionally meaningful. "
+                "Multiply Money by a scalar (int/float/Decimal) instead."
+            )
+        if isinstance(other, bool):
+            raise TypeError("Cannot multiply Money by bool.")
+        if isinstance(other, (int, float, Decimal, str)):
+            return Money(self.amount * _coerce_amount(other), self.currency)
+        return NotImplemented
+
+    def __rmul__(self, other: object) -> "Money":
+        return self.__mul__(other)
+
+    def __truediv__(self, other: object) -> Union["Money", float]:
+        if isinstance(other, Money):
+            self._check_same_currency(other, "/")
+            if other.amount == 0:
+                raise ZeroDivisionError("Division by zero Money.")
+            return float(self.amount / other.amount)
+        if isinstance(other, bool):
+            raise TypeError("Cannot divide Money by bool.")
+        if isinstance(other, (int, float, Decimal, str)):
+            divisor = _coerce_amount(other)
+            if divisor == 0:
+                raise ZeroDivisionError("Division by zero.")
+            return Money(self.amount / divisor, self.currency)
+        return NotImplemented
+
+    def __floordiv__(self, other: object) -> Union["Money", int]:
+        if isinstance(other, Money):
+            self._check_same_currency(other, "//")
+            if other.amount == 0:
+                raise ZeroDivisionError("Floor-division by zero Money.")
+            return int(self.amount // other.amount)
+        if isinstance(other, (int, float, Decimal, str)) and not isinstance(
+            other, bool
+        ):
+            divisor = _coerce_amount(other)
+            if divisor == 0:
+                raise ZeroDivisionError("Floor-division by zero.")
+            return Money(self.amount // divisor, self.currency)
+        return NotImplemented
+
+    # ------------------------------------------------------------------
+    # Comparison
+    # ------------------------------------------------------------------
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Money):
+            return NotImplemented
+        return self.currency == other.currency and self.amount == other.amount
+
+    def __hash__(self) -> int:
+        return hash((type(self).__name__, self.currency, self.amount))
+
+    def _check_comparable(self, other: object, op: str) -> "Money":
+        if not isinstance(other, Money):
+            raise TypeError(
+                f"Cannot compare Money with {type(other).__name__} using {op!r}."
+            )
+        self._check_same_currency(other, op)
+        return other
+
+    def __lt__(self, other: object) -> bool:
+        other_m = self._check_comparable(other, "<")
+        return self.amount < other_m.amount
+
+    def __le__(self, other: object) -> bool:
+        other_m = self._check_comparable(other, "<=")
+        return self.amount <= other_m.amount
+
+    def __gt__(self, other: object) -> bool:
+        other_m = self._check_comparable(other, ">")
+        return self.amount > other_m.amount
+
+    def __ge__(self, other: object) -> bool:
+        other_m = self._check_comparable(other, ">=")
+        return self.amount >= other_m.amount
+
+    # ------------------------------------------------------------------
+    # Conversion
+    # ------------------------------------------------------------------
+    def to(
+        self,
+        target: str,
+        converter: "FXConverter",
+        at: "datetime | None" = None,
+    ) -> "Money":
+        """Convert to ``target`` currency using ``converter.rate(...)``.
+
+        Short-circuits to ``self`` (no-op) when the target currency
+        already matches. Preserves full Decimal precision; call
+        :meth:`round_to_currency` afterwards if you want to quantise
+        to the target's minor-unit precision.
+
+        Parameters
+        ----------
+        target:
+            ISO 4217 code to convert to.
+        converter:
+            Any object satisfying :class:`simweave.currency.FXConverter`.
+        at:
+            Optional datetime passed through to the converter (for
+            historical-rate lookups). Converters may ignore it.
+        """
+        target_code = _normalise_code(target)
+        if target_code == self.currency:
+            return self
+        rate = converter.rate(self.currency, target_code, at=at)
+        rate_d = _coerce_amount(rate)
+        return Money(self.amount * rate_d, target_code)
+
+    # ------------------------------------------------------------------
+    # Representation
+    # ------------------------------------------------------------------
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"Money({self.amount!r}, {self.currency!r})"
+
+    def __str__(self) -> str:
+        # Delayed import avoids a circular dependency at module load time.
+        from simweave.currency.format import format_money
+
+        return format_money(self)
+
+    def __format__(self, spec: str) -> str:
+        from simweave.currency.format import format_money
+
+        return format_money(self, spec=spec)

simweave/discrete/__init__.py

@@ -0,0 +1,28 @@
+"""Discrete-event primitives: queues, services, resources, arrival generators."""
+
+from simweave.discrete.properties import (
+    EntityProperties,
+    exponential,
+    uniform,
+    normal,
+    deterministic,
+    set_default_seed,
+)
+from simweave.discrete.queues import Queue, PriorityQueue
+from simweave.discrete.resources import Resource, ResourcePool
+from simweave.discrete.services import Service, ArrivalGenerator
+
+__all__ = [
+    "EntityProperties",
+    "exponential",
+    "uniform",
+    "normal",
+    "deterministic",
+    "set_default_seed",
+    "Queue",
+    "PriorityQueue",
+    "Resource",
+    "ResourcePool",
+    "Service",
+    "ArrivalGenerator",
+]

simweave/discrete/properties.py

@@ -0,0 +1,113 @@
+"""Service-time distributions and per-entity sim properties.
+
+The previous ``simProperites`` class conflated the distribution configuration
+with a ``dt`` attribute that gets overwritten whenever ``next_service_time()``
+is called. Here we split the two: ``ServiceTime`` knows how to *draw*; an
+:class:`EntityProperties` record carries the distribution plus any static
+attributes the modeller wants to track.
+
+Every distribution accepts an optional ``rng`` (``numpy.random.Generator``)
+so that Monte Carlo runs can be seeded independently without touching the
+legacy global ``np.random`` state.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+import numpy as np
+
+
+RNG = np.random.Generator
+Distribution = Callable[[RNG], float]
+
+
+def exponential(mean: float) -> Distribution:
+    """Exponential inter-arrival / service time."""
+    if mean <= 0:
+        raise ValueError("Exponential mean must be positive.")
+
+    def draw(rng: RNG) -> float:
+        return float(rng.exponential(mean))
+
+    return draw
+
+
+def uniform(low: float, high: float) -> Distribution:
+    if high <= low:
+        raise ValueError("Uniform requires high > low.")
+
+    def draw(rng: RNG) -> float:
+        return float(rng.uniform(low, high))
+
+    return draw
+
+
+def normal(mean: float, std: float, *, clip_nonnegative: bool = True) -> Distribution:
+    """Normal distribution; by default clips at 0 since negative service times are nonsense."""
+    if std <= 0:
+        raise ValueError("normal std must be positive.")
+
+    def draw(rng: RNG) -> float:
+        x = float(rng.normal(mean, std))
+        return max(0.0, x) if clip_nonnegative else x
+
+    return draw
+
+
+def deterministic(value: float) -> Distribution:
+    if value < 0:
+        raise ValueError("deterministic value cannot be negative.")
+
+    def draw(rng: RNG) -> float:
+        return float(value)
+
+    return draw
+
+
+@dataclass
+class EntityProperties:
+    """Per-entity sim properties. Pass the same instance to many entities.
+
+    Attributes
+    ----------
+    entity_type:
+        Free-form tag, useful for stratified summaries.
+    service_time:
+        Distribution drawn whenever a Service pulls this entity into a work
+        channel.
+    balk_on_length:
+        If the waiting queue has more than this many items on arrival, the
+        entity refuses to join. ``None`` disables balking.
+    renege_after:
+        If the entity's ``current_wait_time`` exceeds this threshold, it
+        leaves the queue. ``None`` disables reneging.
+    extras:
+        Arbitrary additional fields the modeller wants to track.
+    """
+
+    entity_type: str = "default"
+    service_time: Distribution = field(default_factory=lambda: exponential(1.0))
+    balk_on_length: int | None = None
+    renege_after: float | None = None
+    extras: dict[str, Any] = field(default_factory=dict)
+
+    def draw_service_time(self, rng: RNG | None = None) -> float:
+        if rng is None:
+            rng = _default_rng()
+        return float(self.service_time(rng))
+
+
+# A shared default generator so users can omit ``rng`` in tests / quick demos.
+_DEFAULT_RNG = np.random.default_rng()
+
+
+def _default_rng() -> RNG:
+    return _DEFAULT_RNG
+
+
+def set_default_seed(seed: int) -> None:
+    """Replace the module-level generator with a seeded one."""
+    global _DEFAULT_RNG
+    _DEFAULT_RNG = np.random.default_rng(seed)