MATE-libraries 1.0.0.dev0__tar.gz → 1.0.0rc1__tar.gz

{mate_libraries-1.0.0.dev0 → mate_libraries-1.0.0rc1}/.gitignore

@@ -10,3 +10,5 @@ dist/
 .coverage
 htmlcov/
 .project.settings
+public/
+docs/_build/

{mate_libraries-1.0.0.dev0 → mate_libraries-1.0.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: MATE-libraries
-Version: 1.0.0.dev0
+Version: 1.0.0rc1
 Summary: Libraries of MATE, the Modular Algorithmic Toolkit for Evolution: network library and standard operators library for MATE modules
 Project-URL: Homepage, https://gitlab.com/artificial_evolution/mate/mate
 Project-URL: Issues, https://gitlab.com/artificial_evolution/mate/mate/-/issues
@@ -15,7 +15,7 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.14
-Requires-Dist: mate-contract<2,>=1.0.0.dev0
+Requires-Dist: mate-contract<2,>=1.0.0rc1
 Description-Content-Type: text/markdown
 
 # MATE-libraries
@@ -25,8 +25,11 @@ Modular Algorithmic Toolkit for Evolution: the network library and the standard
 operators library, which method and system modules may use. It depends on
 `MATE-contract` only.
 
-**Status: under development.** This release only reserves the name; it
-contains no functionality yet.
+The standard operators library (`MATE_libraries.operators`) gives a variation
+operator per domain and the standard selections. The network library
+(`MATE_libraries.networks`) compiles batches of `Network` organs and propagates
+them on the CPU, with results that do not depend on the batch. Each library has
+its own `version`, recorded in every run whose modules import it.
 
 ## Installation
 

{mate_libraries-1.0.0.dev0 → mate_libraries-1.0.0rc1}/README.md

@@ -5,8 +5,11 @@ Modular Algorithmic Toolkit for Evolution: the network library and the standard
 operators library, which method and system modules may use. It depends on
 `MATE-contract` only.
 
-**Status: under development.** This release only reserves the name; it
-contains no functionality yet.
+The standard operators library (`MATE_libraries.operators`) gives a variation
+operator per domain and the standard selections. The network library
+(`MATE_libraries.networks`) compiles batches of `Network` organs and propagates
+them on the CPU, with results that do not depend on the batch. Each library has
+its own `version`, recorded in every run whose modules import it.
 
 ## Installation
 

{mate_libraries-1.0.0.dev0 → mate_libraries-1.0.0rc1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "MATE-libraries"
-version = "1.0.0.dev0"
+version = "1.0.0rc1"
 description = "Libraries of MATE, the Modular Algorithmic Toolkit for Evolution: network library and standard operators library for MATE modules"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -21,7 +21,7 @@ classifiers = [
   "Programming Language :: Python :: 3",
   "Topic :: Scientific/Engineering",
 ]
-dependencies = ["MATE-contract>=1.0.0.dev0,<2"]
+dependencies = ["MATE-contract>=1.0.0rc1,<2"]
 
 [project.urls]
 Homepage = "https://gitlab.com/artificial_evolution/mate/mate"

mate_libraries-1.0.0rc1/src/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-1.0.0rc1/src/MATE_libraries/networks/_catalogue.py

@@ -0,0 +1,258 @@
+"""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] = 1
+"""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.
+
+    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.
+
+    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)
+
+
+ACTIVATIONS: Final[Mapping[str, Activation]] = MappingProxyType(
+    {
+        "id": Activation(_identity),
+        "tanh": Activation(_tanh),
+        "relu": Activation(_relu),
+        "sigmoid": Activation(_sigmoid),
+        "neat_sigmoid": Activation(_neat_sigmoid),
+        "sin": Activation(_sin),
+        "gauss": Activation(_gauss),
+        "abs": Activation(_abs),
+        "step": Activation(_step),
+    }
+)
+"""Read-only catalogue of activation functions, dated by ``VERSION`` (rule K3)."""
+
+AGGREGATIONS: Final[Mapping[str, Aggregation]] = MappingProxyType(
+    {
+        "sum": Aggregation(np.add, 0.0),
+        "product": Aggregation(np.multiply, 1.0),
+        "max": Aggregation(np.maximum, 0.0),
+        "min": Aggregation(np.minimum, 0.0),
+        "mean": Aggregation(np.add, 0.0, finalize=_mean),
+    }
+)
+"""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)