MATE-contract 1.0.0__py3-none-any.whl

MATE_contract/__init__.py

@@ -0,0 +1,52 @@
+"""MATE contract: the exchange types and interfaces shared by all MATE modules.
+
+A system and a method depend only on this distribution (and NumPy). Every public name is
+imported from here; the submodules are private.
+"""
+
+from importlib.metadata import version as _distribution_version
+
+from ._context import Context, EventSink, Logger
+from ._declarations import Capabilities, Device, Requirements
+from ._domains import Categorical, Domain, Integer, Log, Ordinal, Real
+from ._exchange import Budget, Candidate, Environment, Invalid, Operation, Partial, Performance
+from ._interfaces import Genome, Method, System
+from ._keys import Key
+from ._phenotype import Network, Params, Phenotype, Program
+from ._specs import (
+    EnvironmentSpec,
+    EvaluationSpec,
+    FieldArray,
+    NetworkSpec,
+    ObservableSpec,
+    ParamsSpec,
+    PerformanceSpec,
+    PhenotypeSpec,
+    ProgramSpec,
+    Role,
+    Setting,
+    TraceSpec,
+)
+
+__version__ = _distribution_version("MATE-contract")
+
+__all__ = [
+    # _domains
+    "Domain", "Real", "Log", "Integer", "Ordinal", "Categorical",
+    # _keys
+    "Key",
+    # _specs
+    "FieldArray", "ParamsSpec", "NetworkSpec", "ProgramSpec", "PhenotypeSpec",
+    "EnvironmentSpec", "TraceSpec", "PerformanceSpec", "ObservableSpec",
+    "Role", "EvaluationSpec", "Setting",
+    # _phenotype
+    "Params", "Network", "Program", "Phenotype",
+    # _exchange
+    "Budget", "Partial", "Performance", "Operation", "Invalid", "Candidate", "Environment",
+    # _declarations
+    "Requirements", "Capabilities", "Device",
+    # _context
+    "Context", "Logger", "EventSink",
+    # _interfaces
+    "System", "Method", "Genome",
+]  # fmt: skip

MATE_contract/_base.py

@@ -0,0 +1,292 @@
+"""Shared helpers of the contract types: closed families, read-only storage, value equality, names.
+
+Everything here is private to ``MATE_contract``. The public behaviours it implements are those of
+the contract specification: closed families ([K] §3 "Enforcement", P1b), arrays and mappings
+stored as private read-only copies ([K] §1 "Immutability"), value equality of array-holding
+types ([K] §1.1) and the checks on names ([K] OB3, NS2).
+"""
+
+import dataclasses
+import numbers
+from collections.abc import Hashable, ItemsView, Iterable, Iterator, KeysView, Mapping, ValuesView
+from typing import Any, ClassVar
+
+import numpy as np
+from numpy.typing import ArrayLike, DTypeLike
+
+_PACKAGE = "MATE_contract"
+
+
+def _in_contract(module: str) -> bool:
+    """Tell whether a module name belongs to the contract distribution."""
+    return module == _PACKAGE or module.startswith(_PACKAGE + ".")
+
+
+class Closed:
+    """Mixin making a class family closed to classes defined outside ``MATE_contract``.
+
+    A direct subclass of ``Closed`` is the root of a family. Any class of the family, the root or
+    a member, can be subclassed only by a class whose module belongs to ``MATE_contract``.
+    """
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        root = _family_root(cls)
+        if root is not cls and not _in_contract(cls.__module__):
+            raise TypeError(
+                f"{root.__name__} is a closed family: {cls.__qualname__} cannot subclass it; "
+                f"see {_PACKAGE}.{root.__name__}"
+            )
+
+
+def _family_root(cls: type) -> type:
+    """Return the root of the closed family ``cls`` belongs to (the class listing ``Closed``)."""
+    for klass in cls.__mro__:
+        if Closed in klass.__bases__:
+            return klass
+    return cls
+
+
+def check_exact_type(value: object, types: tuple[type, ...], where: str) -> None:
+    """Raise ``TypeError`` unless ``type(value)`` is exactly one of ``types``.
+
+    The membership test of closed families is by exact type ([K] §3, P1b), never by
+    ``isinstance``.
+    """
+    if type(value) not in types:
+        names = ", ".join(t.__name__ for t in types)
+        raise TypeError(f"{where}: {type(value).__name__} is not one of {names}")
+
+
+def readonly(a: ArrayLike, dtype: DTypeLike | None = None) -> np.ndarray:
+    """Return a private read-only copy of ``np.asarray(a, dtype)``.
+
+    The copy is made even when ``a`` is already an array of that dtype: a caller who later
+    writes into its own array (a buffer reused across genomes, say) does not change the object
+    that stores the copy ([K] §1 "Immutability").
+    """
+    arr = np.array(a, dtype=dtype, copy=True)
+    arr.flags.writeable = False
+    return arr
+
+
+class ReadOnlyMapping(Mapping[Any, Any]):
+    """Read-only mapping holding its own copy of the items it is built from.
+
+    It takes the place of ``types.MappingProxyType``, which cannot be pickled, so that a module
+    keeping a contract mapping (``self.fields = spec.fields``) can still be sent to a worker
+    process. It pickles and deep-copies through :meth:`__reduce__`, compares equal to any
+    mapping with the same items, is unhashable, prints as a ``dict`` and keeps the read
+    methods of ``MappingProxyType``: ``copy()`` and ``|`` return a ``dict``.
+    """
+
+    __slots__ = ("_items",)
+
+    _items: dict[Any, Any]
+
+    def __init__(self, items: Mapping[Any, Any] | Iterable[tuple[Any, Any]] = ()) -> None:
+        object.__setattr__(self, "_items", dict(items))
+
+    def __getitem__(self, key: Any) -> Any:
+        return self._items[key]
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._items)
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._items
+
+    def __reversed__(self) -> Iterator[Any]:
+        return reversed(self._items)
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        return self._items.get(key, default)
+
+    def keys(self) -> KeysView[Any]:
+        return self._items.keys()
+
+    def values(self) -> ValuesView[Any]:
+        return self._items.values()
+
+    def items(self) -> ItemsView[Any, Any]:
+        return self._items.items()
+
+    def copy(self) -> dict[Any, Any]:
+        """Return the items as a new ``dict``."""
+        return dict(self._items)
+
+    def __or__(self, other: object) -> dict[Any, Any]:
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        return {**self._items, **other}
+
+    def __ror__(self, other: object) -> dict[Any, Any]:
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        return {**other, **self._items}
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, ReadOnlyMapping):
+            other = other._items
+        elif not isinstance(other, Mapping):
+            return NotImplemented
+        elif not isinstance(other, dict):
+            other = dict(other.items())
+        return self._items == other
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def __repr__(self) -> str:
+        return repr(self._items)
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (ReadOnlyMapping, (self._items,))
+
+    def __setattr__(self, name: str, value: object) -> None:
+        raise AttributeError(f"{type(self).__name__} is read-only")
+
+    def __delattr__(self, name: str) -> None:
+        raise AttributeError(f"{type(self).__name__} is read-only")
+
+
+def frozen_mapping(mapping: Mapping[str, Any], where: str) -> ReadOnlyMapping:
+    """Return a read-only copy of ``mapping`` whose keys are checked names.
+
+    Raises
+    ------
+    TypeError
+        If ``mapping`` is not a mapping, or a key is not a ``str``.
+    ValueError
+        If a key is the empty string.
+    """
+    if not isinstance(mapping, Mapping):
+        raise TypeError(f"{where}: expected a mapping, got {type(mapping).__name__}")
+    for key in mapping:
+        check_name(key, where)
+    return ReadOnlyMapping(mapping)
+
+
+def check_name(name: object, where: str) -> str:
+    """Return ``name`` if it is a non-empty ``str``.
+
+    Raises
+    ------
+    TypeError
+        If ``name`` is not a ``str``.
+    ValueError
+        If ``name`` is empty.
+    """
+    if not isinstance(name, str):
+        raise TypeError(f"{where}: a name must be a str, got {type(name).__name__} {name!r}")
+    if not name:
+        raise ValueError(f"{where}: a name must be a non-empty str")
+    return name
+
+
+def check_names(names: Iterable[object], where: str) -> tuple[str, ...]:
+    """Return ``names`` as a tuple of distinct non-empty strings.
+
+    Raises
+    ------
+    TypeError
+        If ``names`` is a single ``str`` or not iterable, or an element is not a ``str``.
+    ValueError
+        If an element is empty or repeated.
+    """
+    result = tuple(check_name(name, where) for name in as_tuple(names, where))
+    seen: set[str] = set()
+    for name in result:
+        if name in seen:
+            raise ValueError(
+                f"{where}: name '{name}' appears more than once; names must be distinct"
+            )
+        seen.add(name)
+    return result
+
+
+def as_tuple(values: Iterable[Any], where: str) -> tuple[Any, ...]:
+    """Return ``values`` as a tuple; a ``str`` or ``bytes`` is refused, not split into items."""
+    if isinstance(values, (str, bytes)):
+        raise TypeError(f"{where}: expected a sequence, got {type(values).__name__} {values!r}")
+    try:
+        return tuple(values)
+    except TypeError:
+        raise TypeError(f"{where}: expected a sequence, got {type(values).__name__}") from None
+
+
+def check_hashable(value: object, where: str) -> Hashable:
+    """Return ``value`` if it is hashable, else raise ``TypeError``."""
+    try:
+        hash(value)
+    except TypeError:
+        raise TypeError(f"{where}: {type(value).__name__} {value!r} is not hashable") from None
+    return value
+
+
+def is_bool(value: object) -> bool:
+    """Tell whether ``value`` is a Python or numpy boolean (refused where an int is expected)."""
+    return isinstance(value, (bool, np.bool_))
+
+
+def as_int(value: object, where: str) -> int:
+    """Return ``value`` as a Python ``int``; booleans and non-integral types raise ``TypeError``."""
+    if is_bool(value) or not isinstance(value, numbers.Integral):
+        raise TypeError(f"{where}: expected an int, got {type(value).__name__} {value!r}")
+    return int(value)
+
+
+def values_equal(a: object, b: object) -> bool:
+    """Compare two contract values by the value-equality rule of [K] §1.1.
+
+    Arrays are equal when dtype, shape and bytes are equal (so NaN equals NaN of the same bit
+    pattern and ``0.0 != -0.0``); mappings when they have the same keys and equal values; tuples
+    and lists elementwise; anything else by ``==``.
+    """
+    if isinstance(a, np.ndarray) or isinstance(b, np.ndarray):
+        if not (isinstance(a, np.ndarray) and isinstance(b, np.ndarray)):
+            return False
+        return (
+            a.dtype == b.dtype
+            and a.shape == b.shape
+            and np.ascontiguousarray(a).tobytes() == np.ascontiguousarray(b).tobytes()
+        )
+    if isinstance(a, Mapping) or isinstance(b, Mapping):
+        if not (isinstance(a, Mapping) and isinstance(b, Mapping)):
+            return False
+        return a.keys() == b.keys() and all(values_equal(a[k], b[k]) for k in a)
+    if isinstance(a, (tuple, list)) or isinstance(b, (tuple, list)):
+        if type(a) is not type(b) or len(a) != len(b):
+            return False
+        return all(values_equal(x, y) for x, y in zip(a, b))
+    result = a == b
+    return isinstance(result, (bool, np.bool_)) and bool(result)
+
+
+class ValueEquality:
+    """Mixin giving a dataclass the value equality of [K] §1.1 and making it unhashable.
+
+    Two instances are equal when they have the same exact type and their comparison keys are
+    equal under :func:`values_equal`. The key is the tuple of dataclass field values, minus the
+    fields named in ``_eq_ignore``; a class overrides :meth:`_eq_key` to normalise a field (for
+    instance an absent ``filled`` mask, equal to an all-true mask).
+    """
+
+    _eq_ignore: ClassVar[tuple[str, ...]] = ()
+
+    def _eq_key(self) -> tuple[Any, ...]:
+        """Return the values compared by ``==``."""
+        return tuple(
+            getattr(self, f.name)
+            for f in dataclasses.fields(self)  # type: ignore[arg-type]
+            if f.compare and f.name not in self._eq_ignore
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if type(other) is not type(self):
+            return NotImplemented
+        return values_equal(self._eq_key(), other._eq_key())  # type: ignore[attr-defined]
+
+    __hash__ = None  # type: ignore[assignment]

MATE_contract/_context.py

@@ -0,0 +1,215 @@
+"""The execution context of a module call, and its two output streams ([K] §8.2-8.3).
+
+Every module call receives a :class:`Context`: its random stream and key, its logger (messages
+for humans), its event sink (structured events for machines), its configuration block and the
+run's budget. The runtime passes its own subclass, which extends the log path in
+:meth:`Context.spawn` and implements the checkpoint hooks of a system that owns its loop; a
+module author can build a plain :class:`Context` to test a module without the runtime.
+"""
+
+import dataclasses
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+import numpy as np
+
+from ._declarations import Device
+from ._exchange import Budget
+from ._keys import Key
+
+
+class Logger(Protocol):
+    """Journal of messages for humans, filtered by a verbosity level.
+
+    Any object with these four methods is a logger. A message is formatted as ``msg % args``
+    only after the level test, so that a discarded message costs one comparison.
+
+    Notes
+    -----
+    Rule LG1.
+    """
+
+    def debug(self, msg: str, /, *args: object) -> None:
+        """Log a debugging message.
+
+        Parameters
+        ----------
+        msg : str
+            Message, a ``%``-format string when ``args`` are given.
+        *args : object
+            Values formatted into ``msg`` after the level test.
+        """
+        ...
+
+    def info(self, msg: str, /, *args: object) -> None:
+        """Log an informative message.
+
+        Parameters
+        ----------
+        msg : str
+            Message, a ``%``-format string when ``args`` are given.
+        *args : object
+            Values formatted into ``msg`` after the level test.
+        """
+        ...
+
+    def warning(self, msg: str, /, *args: object) -> None:
+        """Log a warning.
+
+        Parameters
+        ----------
+        msg : str
+            Message, a ``%``-format string when ``args`` are given.
+        *args : object
+            Values formatted into ``msg`` after the level test.
+        """
+        ...
+
+    def error(self, msg: str, /, *args: object) -> None:
+        """Log an error.
+
+        Parameters
+        ----------
+        msg : str
+            Message, a ``%``-format string when ``args`` are given.
+        *args : object
+            Values formatted into ``msg`` after the level test.
+        """
+        ...
+
+
+class EventSink(Protocol):
+    """Receiver of structured events: a name and typed fields.
+
+    ``ctx.emit(name, value=v)`` publishes a value of a declared series or summary;
+    ``ctx.emit(name, **fields)`` for a declared trace publishes one record; any other name is
+    a free event. Field values are plain data.
+
+    Notes
+    -----
+    Rules LG2, LG3. A method emits the names of its declaration; MATE publishes them under
+    ``method.``.
+    """
+
+    def __call__(self, name: str, /, **fields: object) -> None:
+        """Publish one event.
+
+        Parameters
+        ----------
+        name : str
+            Event name, as declared by the module.
+        **fields : object
+            Event fields, plain data.
+        """
+        ...
+
+
+@dataclass
+class Context:
+    """What a module call receives from MATE besides its arguments.
+
+    Parameters
+    ----------
+    rng : numpy.random.Generator
+        Random stream of this component, ``key.rng()``.
+    key : Key
+        Its key in the seed tree.
+    log : Logger
+        Journal of messages.
+    emit : EventSink
+        Events, series and traces.
+    config : Mapping
+        Its block of the resolved blueprint, read-only.
+    workdir : pathlib.Path
+        The run's directory, for resolving module-relative resources; a module writes nothing
+        there.
+    stopping : callable
+        ``stopping()`` is true when a cooperative stop is requested.
+    device : Device, default Device()
+        Device designated by the executor.
+    ceiling : Budget or None, default None
+        The run's total budget.
+    spent : Budget, default Budget(0, 0)
+        Consumption up to the last result returned.
+
+    Notes
+    -----
+    Rules CT1-CT8. A module never keeps a generator in its state: it draws from the context of
+    each call. Outside a run, a plain ``Context`` serves standalone tests of a module:
+    ``Context(rng=key.rng(), key=key, log=logger, emit=sink, config={}, workdir=Path.cwd(),
+    stopping=lambda: False)``.
+    """
+
+    rng: np.random.Generator
+    key: Key
+    log: Logger
+    emit: EventSink
+    config: Mapping[str, Any]
+    workdir: Path
+    stopping: Callable[[], bool]
+    device: Device = Device()
+    ceiling: Budget | None = None
+    spent: Budget = Budget(0, 0)
+
+    def spawn(self, label: str) -> Context:
+        """Return the context of a child component.
+
+        Parameters
+        ----------
+        label : str
+            Name of the child; it extends the seed-tree branch (and, in a run, the log path).
+
+        Returns
+        -------
+        Context
+            A context of the same type with ``key = self.key.child(label)`` and a fresh
+            ``rng = key.rng()``; the other fields, ``log`` and ``emit`` included, are shared.
+
+        Notes
+        -----
+        Rule CT4. The runtime's subclass also extends the logger's path.
+        """
+        key = self.key.child(label)
+        return dataclasses.replace(self, key=key, rng=key.rng())
+
+    def checkpoint_due(self, date: int | float) -> bool:
+        """Tell a system that owns its loop whether a checkpoint is due at ``date``.
+
+        Parameters
+        ----------
+        date : int or float
+            Current date, in the system's clock unit.
+
+        Returns
+        -------
+        bool
+            Always ``False`` outside a run.
+
+        Notes
+        -----
+        Rule CT7.
+        """
+        return False
+
+    def checkpoint(self, date: int | float, state: bytes) -> None:
+        """Hand MATE a checkpoint of a system that owns its loop.
+
+        Parameters
+        ----------
+        date : int or float
+            Date of the state, in the system's clock unit.
+        state : bytes
+            The system's serialised state, in its own format.
+
+        Raises
+        ------
+        RuntimeError
+            Always outside a run.
+
+        Notes
+        -----
+        Rule CT7.
+        """
+        raise RuntimeError("no checkpoint outside a run")