MATE-libraries 1.0.0__py3-none-any.whl

MATE_libraries/__init__.py

@@ -0,0 +1,5 @@
+"""MATE libraries: the network library and the standard operators library, for MATE modules."""
+
+from importlib.metadata import version
+
+__version__ = version("MATE-libraries")

MATE_libraries/networks/__init__.py

@@ -0,0 +1,67 @@
+"""The network library: compile and propagate batches of ``Network`` organs.
+
+Three objects are never fused: the organ (frozen arrays, one per individual), the compiled
+network (immutable, batched, shared between threads, never serialised) and the activation
+state (the node values of individual x episode rows, mutable and serialised by copy). The
+caller chooses what changes the result (propagation mode, refresh rate, activation functions,
+aggregation, fate of unfilled cells, compute dtype); the library chooses only what does not
+(batching technique, shortcuts derived from the graph). Each individual's results are
+bit-identical whether it is compiled alone or in any batch, under any technique.
+``from_networkx`` builds an organ from a networkx graph, for hand-designed networks.
+
+Attributes
+----------
+version : int
+    What the library computes; changes whenever a definition, a default, a convergence rule
+    or the set of accepted inputs changes (rules V1, V4 of the libraries specification). A
+    protocol may hold it fixed under the key ``networks.version``.
+TECHNIQUES : tuple of str
+    The batching techniques: ``"dense"``, ``"padded"``, ``"block_diagonal"``.
+ACTIVATIONS : Mapping[str, Activation]
+    Read-only catalogue of activation functions: ``id``, ``tanh``, ``relu``, ``sigmoid``,
+    ``neat_sigmoid``, ``sin``, ``gauss``, ``abs``, ``step``.
+AGGREGATIONS : Mapping[str, Aggregation]
+    Read-only catalogue of aggregations: ``sum`` (the default), ``product``, ``max``,
+    ``min``, ``mean``.
+
+Notes
+-----
+Section 4 of the libraries specification. The device path is deferred in MATE-libraries
+1.0.0: ``Device("opencl")`` is refused, any other non-CPU device runs on the CPU, and
+``CompiledNetwork.kernels()`` raises.
+
+Examples
+--------
+>>> from MATE_libraries import networks as nets
+>>> compiled = nets.compile(organs, spec, unfilled={"activation": "id"},
+...                         device=ctx.device)                      # doctest: +SKIP
+>>> act = compiled.state(10)                                        # doctest: +SKIP
+>>> y = compiled.step(act, x[t], refresh_rate=1)                    # doctest: +SKIP
+>>> res = compiled.settle(u, max_steps=50, tol=1e-6)                # doctest: +SKIP
+"""
+
+from typing import Final
+
+from ._catalogue import ACTIVATIONS, AGGREGATIONS, VERSION, Activation, Aggregation
+from ._compiled import TECHNIQUES, CompileDiagnostics, CompiledNetwork, compile, validate
+from ._networkx import from_networkx
+from ._state import ActivationState, IndividualActivation, SettleResult
+
+version: Final[int] = VERSION
+
+__all__ = [
+    "version",
+    "TECHNIQUES",
+    "Activation",
+    "Aggregation",
+    "ACTIVATIONS",
+    "AGGREGATIONS",
+    "compile",
+    "validate",
+    "from_networkx",
+    "CompileDiagnostics",
+    "CompiledNetwork",
+    "ActivationState",
+    "IndividualActivation",
+    "SettleResult",
+]

MATE_libraries/networks/_catalogue.py

@@ -0,0 +1,282 @@
+"""Catalogues of activation functions and aggregations, and name resolution ([L] §4.5)."""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any, Final
+
+import numpy as np
+
+VERSION: Final[int] = 2
+"""What the network library computes (rules V1, V4); exposed as ``networks.version``."""
+
+
+def _kernels(value: Mapping[str, str], where: str) -> Mapping[str, str]:
+    """Return a read-only copy of a backend-to-kernel-source mapping."""
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{where}.kernels: expected a mapping, got {type(value).__name__}")
+    for backend, source in value.items():
+        if not isinstance(backend, str) or not isinstance(source, str):
+            raise TypeError(f"{where}.kernels: keys and values are str (backend -> source)")
+    return MappingProxyType(dict(value))
+
+
+@dataclass(frozen=True)
+class Activation:
+    """An activation function of the network library.
+
+    Parameters
+    ----------
+    function : callable
+        Elementwise, pure and dtype-preserving map of an array; its result for an element
+        must not depend on the element's position, the array length, alignment or strides.
+    kernels : mapping of str to str, default {}
+        Device kernel source per backend name; without one, the device path is lost. The
+        ``"opencl"`` source defines ``real activate(real x)``, where ``real`` is the compute
+        type (``float`` or ``double``) and ``MATE_REAL(1.0)`` a literal of that type, with
+        the operations of ``function`` in the same order.
+
+    Raises
+    ------
+    TypeError
+        If ``function`` is not callable or ``kernels`` is not a mapping of str to str.
+
+    Notes
+    -----
+    Rules K2, K5 of the libraries specification. Pickles through its constructor, so that a
+    module keeping it can be sent to a worker process.
+    """
+
+    function: Callable[[np.ndarray], np.ndarray]
+    kernels: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not callable(self.function):
+            raise TypeError(
+                f"Activation.function: expected a callable, got {type(self.function).__name__}"
+            )
+        object.__setattr__(self, "kernels", _kernels(self.kernels, "Activation"))
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (Activation, (self.function, dict(self.kernels)))
+
+
+@dataclass(frozen=True)
+class Aggregation:
+    """How a node combines the weighted terms of its present incoming edges.
+
+    Parameters
+    ----------
+    combine : callable
+        ``(accumulator, term) -> accumulator``, elementwise; the fold starts from the first
+        term and follows the canonical edge order.
+    empty : float
+        Value of a node without any present incoming edge.
+    finalize : callable, optional
+        ``(accumulator, count) -> value``, applied after the fold.
+    kernels : mapping of str to str, default {}
+        Device kernel source per backend name. The ``"opencl"`` source defines
+        ``real combine(real acc, real term)`` and, when ``finalize`` is given,
+        ``real finalize(real acc, int count)``, on the compute type ``real`` (see
+        :class:`Activation`).
+
+    Raises
+    ------
+    TypeError
+        If ``combine`` or ``finalize`` is not callable, ``empty`` is not a real number, or
+        ``kernels`` is not a mapping of str to str.
+
+    Notes
+    -----
+    Rules K2, K4, K5 and S9a of the libraries specification. Pickles through its constructor,
+    so that a module keeping it can be sent to a worker process.
+    """
+
+    combine: Callable[[np.ndarray, np.ndarray], np.ndarray]
+    empty: float
+    finalize: Callable[[np.ndarray, np.ndarray], np.ndarray] | None = None
+    kernels: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not callable(self.combine):
+            raise TypeError(
+                f"Aggregation.combine: expected a callable, got {type(self.combine).__name__}"
+            )
+        if self.finalize is not None and not callable(self.finalize):
+            raise TypeError(
+                "Aggregation.finalize: expected a callable or None, got "
+                f"{type(self.finalize).__name__}"
+            )
+        if isinstance(self.empty, bool) or not isinstance(self.empty, (int, float, np.number)):
+            raise TypeError(
+                f"Aggregation.empty: expected a real number, got {type(self.empty).__name__}"
+            )
+        object.__setattr__(self, "empty", float(self.empty))
+        object.__setattr__(self, "kernels", _kernels(self.kernels, "Aggregation"))
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (Aggregation, (self.combine, self.empty, self.finalize, dict(self.kernels)))
+
+
+# Catalogue functions: built from numpy ufuncs evaluated in the array's own dtype, so that
+# each element goes through one code path whatever its position (K5).
+
+
+def _identity(x: np.ndarray) -> np.ndarray:
+    """x (a new array, so that callers never alias their input)."""
+    return np.positive(x)
+
+
+def _tanh(x: np.ndarray) -> np.ndarray:
+    """tanh(x)."""
+    return np.tanh(x)
+
+
+def _relu(x: np.ndarray) -> np.ndarray:
+    """max(x, 0)."""
+    return np.maximum(x, x.dtype.type(0))
+
+
+def _sigmoid(x: np.ndarray) -> np.ndarray:
+    """1 / (1 + exp(-x))."""
+    one = x.dtype.type(1)
+    return one / (one + np.exp(-x))
+
+
+def _neat_sigmoid(x: np.ndarray) -> np.ndarray:
+    """1 / (1 + exp(-4.9 x)), the steepened sigmoid of the original NEAT paper."""
+    one = x.dtype.type(1)
+    return one / (one + np.exp(x.dtype.type(-4.9) * x))
+
+
+def _sin(x: np.ndarray) -> np.ndarray:
+    """sin(x)."""
+    return np.sin(x)
+
+
+def _gauss(x: np.ndarray) -> np.ndarray:
+    """exp(-x²)."""
+    return np.exp(-(x * x))
+
+
+def _abs(x: np.ndarray) -> np.ndarray:
+    """|x|."""
+    return np.abs(x)
+
+
+def _step(x: np.ndarray) -> np.ndarray:
+    """1 if x > 0 else 0."""
+    return (x > 0).astype(x.dtype)
+
+
+def _mean(acc: np.ndarray, count: np.ndarray) -> np.ndarray:
+    """Sum divided by the term count (0 where there is no term)."""
+    count = np.asarray(count).astype(acc.dtype)
+    return np.divide(acc, count, out=np.zeros_like(acc), where=count > 0)
+
+
+def _opencl(body: str, signature: str = "real activate(real x)") -> dict[str, str]:
+    """The ``kernels`` mapping of a catalogue entry: one OpenCL function."""
+    return {"opencl": f"inline {signature} {{ {body} }}"}
+
+
+# The OpenCL sources repeat the numpy expressions operation by operation. numpy's maximum and
+# minimum propagate a NaN of either side and, on equal operands (+0 and -0 included), return
+# the second one, as the x86 vector instructions they run on do.
+ACTIVATIONS: Final[Mapping[str, Activation]] = MappingProxyType(
+    {
+        "id": Activation(_identity, _opencl("return x;")),
+        "tanh": Activation(_tanh, _opencl("return tanh(x);")),
+        "relu": Activation(_relu, _opencl(
+            "return (isnan(x) || x > MATE_REAL(0.0)) ? x : MATE_REAL(0.0);")),
+        "sigmoid": Activation(_sigmoid, _opencl(
+            "return MATE_REAL(1.0) / (MATE_REAL(1.0) + exp(-x));")),
+        "neat_sigmoid": Activation(_neat_sigmoid, _opencl(
+            "return MATE_REAL(1.0) / (MATE_REAL(1.0) + exp(-MATE_REAL(4.9) * x));")),
+        "sin": Activation(_sin, _opencl("return sin(x);")),
+        "gauss": Activation(_gauss, _opencl("return exp(-(x * x));")),
+        "abs": Activation(_abs, _opencl("return fabs(x);")),
+        "step": Activation(_step, _opencl(
+            "return x > MATE_REAL(0.0) ? MATE_REAL(1.0) : MATE_REAL(0.0);")),
+    }
+)
+"""Read-only catalogue of activation functions, dated by ``VERSION`` (rule K3)."""
+
+_COMBINE = "real combine(real acc, real term)"
+AGGREGATIONS: Final[Mapping[str, Aggregation]] = MappingProxyType(
+    {
+        "sum": Aggregation(np.add, 0.0, kernels=_opencl("return acc + term;", _COMBINE)),
+        "product": Aggregation(np.multiply, 1.0,
+                               kernels=_opencl("return acc * term;", _COMBINE)),
+        "max": Aggregation(np.maximum, 0.0, kernels=_opencl(
+            "return (isnan(acc) || acc > term) ? acc : term;", _COMBINE)),
+        "min": Aggregation(np.minimum, 0.0, kernels=_opencl(
+            "return (isnan(acc) || acc < term) ? acc : term;", _COMBINE)),
+        "mean": Aggregation(np.add, 0.0, finalize=_mean, kernels={"opencl": (
+            f"inline {_COMBINE} {{ return acc + term; }}\n"
+            "inline real finalize(real acc, int count) { return acc / (real)count; }")}),
+    }
+)
+"""Read-only catalogue of aggregations, dated by ``VERSION`` (rule K4)."""
+
+_KINDS: Final[Mapping[str, tuple[Mapping[str, object], type, str]]] = MappingProxyType(
+    {
+        "activation": (ACTIVATIONS, Activation, "activations"),
+        "aggregation": (AGGREGATIONS, Aggregation, "aggregations"),
+    }
+)
+
+
+def caller_definitions[T](
+    given: Mapping[str, T] | None, kind: str
+) -> Mapping[str, T]:
+    """Check the definitions a caller supplies for ``kind`` and return them (R2, K2, K6)."""
+    catalogue, cls, keyword = _KINDS[kind]
+    if given is None:
+        return MappingProxyType({})
+    if not isinstance(given, Mapping):
+        raise TypeError(f"{keyword}=: expected a mapping of str to {cls.__name__}, "
+                        f"got {type(given).__name__}")
+    for name, definition in given.items():
+        if not isinstance(name, str):
+            raise TypeError(f"{keyword}=: names are str, got {type(name).__name__}")
+        if not isinstance(definition, cls):
+            raise TypeError(
+                f"{keyword}['{name}']: expected an {cls.__name__}, got "
+                f"{type(definition).__name__}"
+            )
+        if name in catalogue:
+            raise ValueError(
+                f"'{name}' is a catalogue name of the network library (version {VERSION}); "
+                "give your variant another name"
+            )
+    return MappingProxyType(dict(given))
+
+
+def missing_names_message(kind: str, missing: Mapping[str, list[str]]) -> str:
+    """Build the K6 message for names of ``kind`` found nowhere.
+
+    ``missing`` maps each unknown name to the places it was read from, in order of appearance.
+    """
+    catalogue, cls, keyword = _KINDS[kind]
+    names = list(missing)
+    places: list[str] = []
+    for where in missing.values():
+        places.extend(w for w in where if w not in places)
+    quoted = ", ".join(f"'{n}'" for n in names)
+    supply = ", ".join(f"'{n}': {cls.__name__}(...)" for n in names)
+    noun = kind if len(names) == 1 else f"{kind}s"
+    pronoun = "it" if len(names) == 1 else "them"
+    return (
+        f"network library (version {VERSION}): unknown {noun} {quoted} in "
+        f"{' and '.join(places)}; the catalogue offers {list(catalogue)}; "
+        f"pass {keyword}={{{supply}}} to supply {pronoun}"
+    )
+
+
+def lookup[T](name: str, kind: str, given: Mapping[str, T]) -> T | None:
+    """Resolve ``name``: the catalogue first, then the caller's definitions (K6)."""
+    catalogue = _KINDS[kind][0]
+    if name in catalogue:
+        return catalogue[name]  # type: ignore[return-value]
+    return given.get(name)