MATE-runtime 1.0.0__py3-none-any.whl

MATE/config/calendar.py

@@ -0,0 +1,371 @@
+"""The environment calendar: parsing ``[environment]``, building and evaluating it.
+
+:class:`Calendar` is the single calendar implementation: the loop evaluates it at each
+request date ([X] §10.1) and a system that owns its loop receives it as a dated function
+([C] R10.6).
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+import numpy as np
+from MATE_contract import (
+    Categorical,
+    Domain,
+    Environment,
+    EnvironmentSpec,
+    Integer,
+    Log,
+    Ordinal,
+    Real,
+)
+
+from MATE.config.model import EnvironmentDecl, Phase, Value
+from MATE.errors import Refusal
+
+__all__ = ["parse_environment", "build_calendar", "Calendar"]
+
+_UNITS = ("generation", "evaluation")
+_RESERVED = ("unit", "phase")
+_PHASE_KEYS = frozenset({"until", "settings", "interpolation"})
+
+
+def _is_int(x: object) -> bool:
+    """A TOML integer (booleans excluded)."""
+    return isinstance(x, int) and not isinstance(x, bool)
+
+
+def _reactive(value: object) -> bool:
+    """A condition-shaped value: a table with a ``serie`` key (R10.15)."""
+    return isinstance(value, Mapping) and "serie" in value
+
+
+def _reactive_refusal(where: str) -> Refusal:
+    """``P-PHASE-FORM`` for a setting written as a condition on a series."""
+    return Refusal("P-PHASE-FORM", where,
+                   "calendar form not available in MATE 1.0.0: reactive (a setting written "
+                   "as a condition on a series); reactive calendars are not yet specified")
+
+
+def _freeze(value: object) -> Value:
+    """Arrays as tuples, tables as read-only mappings."""
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze(v) for v in value)
+    if isinstance(value, Mapping):
+        return MappingProxyType({k: _freeze(v) for k, v in value.items()})
+    return value
+
+
+def parse_environment(table: Mapping) -> tuple[EnvironmentDecl | None, list[Refusal]]:
+    """Parse an ``[environment]`` table.
+
+    Parameters
+    ----------
+    table : mapping
+        The ``[environment]`` table (empty when absent).
+
+    Returns
+    -------
+    EnvironmentDecl or None
+        Settings as written (labels for ``Ordinal`` and ``Categorical``, linear pairs as
+        tuples); ``None`` when refused.
+    list of Refusal
+        ``P-PHASE-ORDER``, ``P-PHASE-UNTIL``, ``P-PHASE-LINEAR``, ``P-PHASE-FORM``,
+        ``P-UNKNOWN-KEY`` (a phase key, or ``unit`` not a string).
+
+    Notes
+    -----
+    [C] R10.7 (keys other than ``unit`` and ``phase`` are settings from date 0), R10.9,
+    R10.10 syntax, R10.15. Domains, units and completeness are :func:`build_calendar`'s.
+    """
+    if not isinstance(table, Mapping):
+        return None, [Refusal("P-UNKNOWN-KEY", "[environment]",
+                              f"[environment] is a table, got {table!r}")]
+    refusals: list[Refusal] = []
+    unit = table.get("unit")
+    if "unit" in table and (not isinstance(unit, str) or not unit):
+        refusals.append(Refusal("P-UNKNOWN-KEY", "[environment] unit",
+                                f"unit is \"generation\" or \"evaluation\", got {unit!r}"))
+    base: dict[str, Value] = {}
+    for name, value in table.items():
+        if name in _RESERVED:
+            continue
+        if _reactive(value):
+            refusals.append(_reactive_refusal(f"[environment] {name}"))
+        base[name] = _freeze(value)
+
+    raw_phases = table.get("phase", [])
+    if not isinstance(raw_phases, (list, tuple)):
+        refusals.append(Refusal("P-PHASE-UNTIL", "[environment] phase",
+                                "phases are an array of tables ([[environment.phase]])"))
+        raw_phases = []
+    phases: list[Phase] = []
+    previous = 0
+    last = len(raw_phases) - 1
+    for i, raw in enumerate(raw_phases):
+        where = f"[[environment.phase]] #{i + 1}"
+        if not isinstance(raw, Mapping):
+            refusals.append(Refusal("P-PHASE-UNTIL", where, f"a phase is a table, got {raw!r}"))
+            continue
+        refusals.extend(Refusal("P-UNKNOWN-KEY", f"{where} {k}",
+                                f"unknown phase key '{k}'; known keys: until, settings, "
+                                f"interpolation") for k in raw if k not in _PHASE_KEYS)
+        until = raw.get("until")
+        if until is None:
+            if i != last:
+                refusals.append(Refusal("P-PHASE-UNTIL", where,
+                                        "only the last phase may omit until"))
+        elif not _is_int(until):
+            refusals.append(Refusal("P-PHASE-UNTIL", f"{where} until",
+                                    f"until is an integer date, got {until!r}"))
+            until = None
+        elif until <= previous:
+            refusals.append(Refusal(
+                "P-PHASE-ORDER", f"{where} until",
+                f"until values increase strictly from 0: {until} follows {previous}"))
+        else:
+            previous = until
+        interpolation = raw.get("interpolation")
+        if interpolation is not None and interpolation != "linear":
+            refusals.append(Refusal(
+                "P-PHASE-FORM", f"{where} interpolation",
+                f"calendar form not available in MATE 1.0.0: {interpolation}; "
+                f"periodic and random calendars are not yet specified"))
+            interpolation = None
+        settings = raw.get("settings", {})
+        if not isinstance(settings, Mapping):
+            refusals.append(Refusal("P-UNKNOWN-KEY", f"{where} settings",
+                                    f"settings is a table, got {settings!r}"))
+            settings = {}
+        frozen: dict[str, Value] = {}
+        for name, value in settings.items():
+            if _reactive(value):
+                refusals.append(_reactive_refusal(f"{where} settings.{name}"))
+            elif interpolation == "linear" and (not isinstance(value, (list, tuple))
+                                                or len(value) != 2):
+                refusals.append(Refusal(
+                    "P-PHASE-LINEAR", f"{where} settings.{name}",
+                    f"a linear phase writes [from, to] pairs, got {value!r}"))
+            frozen[name] = _freeze(value)
+        if interpolation == "linear" and raw.get("until") is None:
+            refusals.append(Refusal("P-PHASE-LINEAR", where, "a linear phase needs until"))
+        phases.append(Phase(until, MappingProxyType(frozen), interpolation))
+    if refusals:
+        return None, refusals
+    return EnvironmentDecl(unit, MappingProxyType(base), tuple(phases)), []
+
+
+def _on_circle(value: Value, domain: Domain) -> Value:
+    """A value of a periodic ``Real``, ``hi`` written as ``lo``: the same point of the circle."""
+    if isinstance(domain, Real) and domain.periodic and value == domain.hi:
+        return domain.lo  # type: ignore[return-value]
+    return value
+
+
+def _normalise(value: object, domain: Domain, *, point: bool = True
+               ) -> tuple[Value, str | None]:
+    """Normalise one written value in its domain (R6.10); return (value, error).
+
+    A point of a periodic ``Real`` written at ``hi`` becomes ``lo``. ``point=False`` keeps it
+    for an end of a linear pair, which bounds a path: ``[lo, hi]`` is a full turn.
+    """
+    if isinstance(domain, (Ordinal, Categorical)):
+        for label in domain.values:
+            if (isinstance(value, bool) == isinstance(label, bool) and type(value) is not tuple
+                    and value == label):
+                return label, None
+        return value, f"{value!r} is not one of {list(domain.values)}"
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return value, f"{value!r} is not a number"
+    if isinstance(domain, Integer):
+        if not isinstance(value, int):
+            return value, f"{value!r} is not an integer"
+    else:
+        value = float(value)
+    if not bool(domain.contains(np.asarray(value))):
+        return value, f"{value!r} is outside {domain!r}"
+    return (_on_circle(value, domain) if point else value), None
+
+
+def build_calendar(decl: EnvironmentDecl, spec: EnvironmentSpec, *, clock: str | None,
+                   dated: bool) -> tuple["Calendar | None", list[Refusal]]:
+    """Check a calendar against the system's environment spec and build it.
+
+    Parameters
+    ----------
+    decl : EnvironmentDecl
+        From :func:`parse_environment`.
+    spec : EnvironmentSpec
+        The system's environment spec.
+    clock : str or None
+        The system's ``capabilities.clock`` when it owns its loop, else ``None``.
+    dated : bool
+        Some ``[[event]]`` has an ``at`` date.
+
+    Returns
+    -------
+    Calendar or None
+        With values normalised (R6.10) and, under a clock, ``unit`` resolved to it;
+        ``None`` when refused.
+    list of Refusal
+        ``P-ENV-RESERVED`` (R10.7), ``P-ENV-UNKNOWN``, ``P-ENV-DOMAIN`` (R10.8),
+        ``P-PHASE-LINEAR-DOMAIN`` (R10.10), ``P-ENV-UNSET`` (R10.12), ``P-UNIT-MISSING``,
+        ``P-UNIT-CLOCK`` (R10.13; also a unit other than ``"generation"`` and
+        ``"evaluation"`` without a clock).
+    """
+    refusals: list[Refusal] = []
+    fields = spec.fields
+    for name in fields:
+        if name in _RESERVED:
+            refusals.append(Refusal(
+                "P-ENV-RESERVED", f"[environment] {name}",
+                f"the environment spec declares a dimension named '{name}', a reserved "
+                f"key of [environment]"))
+
+    unit = decl.unit
+    if clock is not None:
+        if unit is None:
+            unit = clock
+        elif unit != clock:
+            refusals.append(Refusal(
+                "P-UNIT-CLOCK", "[environment] unit",
+                f"the system owns its loop and dates in its clock '{clock}'; unit = '{unit}'",
+                f"unit = \"{clock}\", or omit unit"))
+    elif unit is not None and unit not in _UNITS:
+        refusals.append(Refusal(
+            "P-UNIT-CLOCK", "[environment] unit",
+            f"unit is \"generation\" or \"evaluation\", got '{unit}' (the system does not "
+            f"own its loop)"))
+    if unit is None and (dated or any(p.until is not None for p in decl.phases)):
+        refusals.append(Refusal(
+            "P-UNIT-MISSING", "[environment] unit",
+            "a date is written (a phase until or an event at) without its unit",
+            "unit = \"generation\" or unit = \"evaluation\""))
+
+    def check(where: str, name: str, value: Value, linear: bool) -> Value:
+        domain = fields.get(name)
+        if domain is None:
+            refusals.append(Refusal(
+                "P-ENV-UNKNOWN", where,
+                f"'{name}' is not a dimension of the environment spec "
+                f"(dimensions: {', '.join(fields) or 'none'})"))
+            return value
+        if linear:
+            if not isinstance(domain, (Real, Log)):
+                refusals.append(Refusal(
+                    "P-PHASE-LINEAR-DOMAIN", where,
+                    f"linear interpolation applies to Real and Log dimensions; "
+                    f"'{name}' is {domain!r}"))
+                return value
+            pair = []
+            for member in value:
+                v, error = _normalise(member, domain, point=False)
+                if error is not None:
+                    refusals.append(Refusal("P-ENV-DOMAIN", where, f"'{name}': {error}"))
+                pair.append(v)
+            return tuple(pair)
+        v, error = _normalise(value, domain)
+        if error is not None:
+            refusals.append(Refusal("P-ENV-DOMAIN", where, f"'{name}': {error}"))
+        return v
+
+    base = {n: check(f"[environment] {n}", n, v, False) for n, v in decl.base.items()}
+    phases = []
+    for i, p in enumerate(decl.phases):
+        linear = p.interpolation == "linear"
+        settings = {n: check(f"[[environment.phase]] #{i + 1} settings.{n}", n, v, linear)
+                    for n, v in p.settings.items()}
+        phases.append(Phase(p.until, MappingProxyType(settings), p.interpolation))
+
+    first = decl.phases[0].settings if decl.phases else {}
+    for name in fields:
+        if name in _RESERVED or name in base or name in first:
+            continue
+        later = [i + 1 for i, p in enumerate(decl.phases) if name in p.settings]
+        detail = (f"it is first set in phase #{later[0]}, so it has no value from date 0"
+                  if later else "the calendar never sets it")
+        refusals.append(Refusal(
+            "P-ENV-UNSET", f"[environment] {name}",
+            f"environment dimension '{name}' has no value at every date: {detail}",
+            f"write [environment] {name} = <value>"))
+    if refusals:
+        return None, refusals
+    normalised = EnvironmentDecl(unit, MappingProxyType(base), tuple(phases))
+    return Calendar(normalised, spec), []
+
+
+@dataclass(frozen=True)
+class Calendar:
+    """A checked calendar: the environment point at each date.
+
+    Parameters
+    ----------
+    decl : EnvironmentDecl
+        Normalised by :func:`build_calendar`.
+    spec : EnvironmentSpec
+        The system's environment spec.
+
+    Notes
+    -----
+    [C] §10.2, [X] CA2. Phase ``i`` covers ``[until_{i-1}, until_i)`` with
+    ``until_{-1} = 0``; a dimension a phase does not write keeps its value at the end of
+    the previous phase; a linear phase gives ``from + (to - from) (d - start) /
+    (until - start)``; after the last ``until`` every value holds. On a periodic ``Real``,
+    a linear phase runs from ``from`` to ``to`` as written, at most one turn, and the point
+    gives ``lo`` for ``hi``.
+    """
+
+    decl: EnvironmentDecl
+    spec: EnvironmentSpec
+
+    def point(self, date: int | float) -> Environment:
+        """Return the environment point at a date.
+
+        Parameters
+        ----------
+        date : int or float
+            In the calendar's unit, ``>= 0``.
+
+        Returns
+        -------
+        Environment
+            One value per dimension of the spec, in its order; ``Ordinal`` and
+            ``Categorical`` values as codes (contract EN1), a periodic ``Real`` in
+            ``[lo, hi)``.
+
+        Raises
+        ------
+        ValueError
+            If ``date`` is negative or not a number.
+        """
+        if isinstance(date, bool) or not isinstance(date, (int, float)) or not date >= 0:
+            raise ValueError(f"Calendar.point: date must be a number >= 0, got {date!r}")
+        values: dict[str, Value] = dict(self.decl.base)
+        start = 0
+        for p in self.decl.phases:
+            inside = p.until is None or date < p.until
+            for name, v in p.settings.items():
+                if p.interpolation != "linear":
+                    values[name] = v
+                elif inside:
+                    lo, hi = v
+                    values[name] = lo + (hi - lo) * (date - start) / (p.until - start)
+                else:
+                    values[name] = v[1]
+            if inside:
+                break
+            start = p.until
+        point: dict[str, int | float] = {}
+        for name, domain in self.spec.fields.items():
+            v = values[name]
+            if isinstance(domain, (Ordinal, Categorical)):
+                point[name] = next(i for i, label in enumerate(domain.values)
+                                   if label == v and isinstance(label, bool) == isinstance(v, bool))
+            else:
+                point[name] = _on_circle(v, domain)  # the end of a linear turn
+        return Environment(point)
+
+    def __call__(self, date: int | float) -> Environment:
+        """The dated function handed to a system that owns its loop: :meth:`point`."""
+        return self.point(date)