MATE-runtime 1.0.0__py3-none-any.whl

MATE/compat/interface.py

@@ -0,0 +1,248 @@
+"""The interface compatibility test between a system's specs and a method's requirements.
+
+The test runs before ``configure``, blueprint by blueprint, for every subpopulation and the
+roles it holds ([X] I2, I9). It has three outcomes: compatible, compatible under condition (a
+size bound the method may exceed), incompatible (a required dimension diverges) ([X] I1).
+"""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from MATE_contract import (
+    Capabilities,
+    Integer,
+    NetworkSpec,
+    ParamsSpec,
+    PerformanceSpec,
+    PhenotypeSpec,
+    ProgramSpec,
+    Requirements,
+)
+
+from MATE.compat.sizes import bounded_sizes
+
+__all__ = ["Outcome", "Mismatch", "ConditionalBound", "InterfaceReport", "check_interface"]
+
+# Organ types are keyed by the class name of the organ ([X] §5.2 stage 1).
+_ORGAN_TYPES: tuple[tuple[type, str], ...] = (
+    (ParamsSpec, "Params"),
+    (NetworkSpec, "Network"),
+    (ProgramSpec, "Program"),
+)
+
+
+class Outcome(Enum):
+    """The three outcomes of the interface compatibility test ([X] I1)."""
+
+    COMPATIBLE = "compatible"
+    CONDITIONAL = "compatible under condition"
+    INCOMPATIBLE = "incompatible"
+
+
+@dataclass(frozen=True)
+class Mismatch:
+    """A required dimension on which the system's specs and the method's requirements diverge.
+
+    Parameters
+    ----------
+    stage : {"organs", "ports", "performance", "capabilities"}
+        The stage of the test that found it.
+    role : str
+        The role concerned.
+    organ : str or None
+        The failing organ(s), comma-separated, when the stage has organs.
+    dimension : str
+        ``"organs.<type>"``, ``"ports.<attribute>"``, ``"objectives"``, ``"descriptors"``,
+        ``"constraints"`` or ``"interruptible"``.
+    required : str
+        What the system's specs require.
+    offered : str
+        What the method's requirements declare.
+    """
+
+    stage: Literal["organs", "ports", "performance", "capabilities"]
+    role: str
+    organ: str | None
+    dimension: str
+    required: str
+    offered: str
+
+
+@dataclass(frozen=True)
+class ConditionalBound:
+    """A size bound the method may exceed: individuals are checked one by one.
+
+    Parameters
+    ----------
+    role : str
+        The role.
+    organ : str
+        The organ name.
+    bound : str
+        The bound name, e.g. ``"number_of_hidden_nodes"``.
+    domain : Integer
+        The interface spec's bound.
+    declared : int or "any"
+        What the method declared (``"any"`` when it declared nothing).
+    """
+
+    role: str
+    organ: str
+    bound: str
+    domain: Integer
+    declared: int | Literal["any"]
+
+
+@dataclass(frozen=True)
+class InterfaceReport:
+    """The result of the interface compatibility test.
+
+    Parameters
+    ----------
+    outcome : Outcome
+        ``INCOMPATIBLE`` if any mismatch, else ``CONDITIONAL`` if any conditional bound,
+        else ``COMPATIBLE``.
+    mismatches : tuple of Mismatch
+        Every mismatch, ordered by stage, then role.
+    conditional : tuple of ConditionalBound
+        Every bound the method may exceed.
+    """
+
+    outcome: Outcome
+    mismatches: tuple[Mismatch, ...]
+    conditional: tuple[ConditionalBound, ...]
+
+
+def _organ_type(organ_spec: object) -> str:
+    """Return the organ type name of an organ spec."""
+    for cls, name in _ORGAN_TYPES:
+        if isinstance(organ_spec, cls):
+            return name
+    return type(organ_spec).__name__
+
+
+def _range(bounds: tuple[int, int | str]) -> str:
+    """Render a ``(min, max | "any")`` interval."""
+    return f"({bounds[0]}, {bounds[1]!r})"
+
+
+def _within(n: int, bounds: tuple[int, int | str]) -> bool:
+    """Tell whether ``n`` lies in a ``(min, max | "any")`` interval, inclusive."""
+    lo, hi = bounds
+    return n >= lo and (hi == "any" or n <= hi)
+
+
+def _organs(role: str, spec: PhenotypeSpec, req: Requirements) -> list[Mismatch]:
+    """Stage 1: organ composition against the maxima ([X] §5.2, [K] RQ1)."""
+    by_type: dict[str, list[str]] = {}
+    for organ, organ_spec in spec.organs.items():
+        by_type.setdefault(_organ_type(organ_spec), []).append(organ)
+    out = []
+    for t, organs in by_type.items():
+        m = req.organs.get(t, 0)
+        if m != "any" and len(organs) > m:
+            out.append(Mismatch("organs", role, ", ".join(organs), f"organs.{t}",
+                                f"{len(organs)} {t} organ(s)", f"organs['{t}'] = {m}"))
+    return out
+
+
+def _ports(role: str, spec: PhenotypeSpec, req: Requirements) -> list[Mismatch]:
+    """Stage 2: required port attributes on both ends of every network ([X] §5.2, [K] RQ3)."""
+    out = []
+    for port in req.ports:
+        for organ, organ_spec in spec.organs.items():
+            if not isinstance(organ_spec, NetworkSpec):
+                continue
+            ins, outs = tuple(organ_spec.input_attributes), tuple(organ_spec.output_attributes)
+            if port not in ins or port not in outs:
+                out.append(Mismatch("ports", role, organ, f"ports.{port}",
+                                    f"input attributes {ins}, output attributes {outs}",
+                                    f"ports {tuple(req.ports)}"))
+    return out
+
+
+def _performance(role: str, perf: PerformanceSpec, req: Requirements) -> list[Mismatch]:
+    """Stage 3: numbers of objectives, descriptors and constraints ([X] §5.2, [K] RQ4, RQ5)."""
+    out = []
+    k, d, c = len(perf.objectives), len(perf.descriptors), len(perf.constraints)
+    if not _within(k, req.objectives):
+        out.append(Mismatch("performance", role, None, "objectives", f"{k} objective(s)",
+                            f"objectives = {_range(req.objectives)}"))
+    if not _within(d, req.descriptors):
+        out.append(Mismatch("performance", role, None, "descriptors", f"{d} descriptor(s)",
+                            f"descriptors = {_range(req.descriptors)}"))
+    if c >= 1 and not req.constraints:
+        out.append(Mismatch("performance", role, None, "constraints", f"{c} constraint(s)",
+                            "constraints = False"))
+    return out
+
+
+def _sizes(role: str, spec: PhenotypeSpec, req: Requirements) -> list[ConditionalBound]:
+    """Size bounds: compatible under ``"spec"`` or a maximum within the bound ([X] I5-I7)."""
+    out = []
+    for organ, organ_spec in spec.organs.items():
+        for bound, domain in bounded_sizes(organ_spec).items():
+            declared = req.sizes.get(bound, "any")
+            if declared == "spec":
+                continue
+            if isinstance(declared, int) and domain.hi is not None and declared <= domain.hi:
+                continue
+            out.append(ConditionalBound(role, organ, bound, domain, declared))
+    return out
+
+
+def check_interface(
+    specs: Mapping[str, PhenotypeSpec],
+    performance: Mapping[str, PerformanceSpec],
+    roles: Sequence[str],
+    requirements: Requirements,
+    system_capabilities: Capabilities,
+) -> InterfaceReport:
+    """Test a method's requirements against the specs of the roles it holds.
+
+    Parameters
+    ----------
+    specs : mapping of str to PhenotypeSpec
+        Role -> normalised interface spec.
+    performance : mapping of str to PerformanceSpec
+        Role -> performance spec.
+    roles : sequence of str
+        The roles the subpopulation holds.
+    requirements : Requirements
+        The method's requirements, computed at its construction.
+    system_capabilities : Capabilities
+        The system's capabilities.
+
+    Returns
+    -------
+    InterfaceReport
+        Every stage is evaluated; the mismatches of all stages are reported together, in the
+        stage order organs, ports, performance, capabilities.
+
+    Notes
+    -----
+    [X] §5, I1-I7; [K] RQ1-RQ7. Content values are never tested (I3).
+    """
+    stages: dict[str, list[Mismatch]] = {s: [] for s in ("organs", "ports", "performance",
+                                                          "capabilities")}
+    conditional: list[ConditionalBound] = []
+    for role in roles:
+        spec = specs[role]
+        stages["organs"] += _organs(role, spec, requirements)
+        stages["ports"] += _ports(role, spec, requirements)
+        stages["performance"] += _performance(role, performance[role], requirements)
+        if requirements.interruptible and not system_capabilities.interruptible:
+            stages["capabilities"].append(
+                Mismatch("capabilities", role, None, "interruptible", "interruptible = False",
+                         "interruptible = True"))
+        conditional += _sizes(role, spec, requirements)
+    mismatches = tuple(m for stage in stages.values() for m in stage)
+    if mismatches:
+        outcome = Outcome.INCOMPATIBLE
+    elif conditional:
+        outcome = Outcome.CONDITIONAL
+    else:
+        outcome = Outcome.COMPATIBLE
+    return InterfaceReport(outcome, mismatches, tuple(conditional))

MATE/compat/sizes.py

@@ -0,0 +1,144 @@
+"""Bounded sizes of organ specs, and the per-individual size checks they call for.
+
+A size bound is a field of an organ spec that bounds the size of the organs a method may
+produce. In MATE 1.0.0 the catalogue holds one bound, ``NetworkSpec.number_of_hidden_nodes``
+([X] I8); a fixed size is the bound on a single-element domain ([X] I7).
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from MATE_contract import Integer, Network, NetworkSpec, PhenotypeSpec
+
+if TYPE_CHECKING:
+    from MATE.compat.interface import InterfaceReport
+
+__all__ = ["SizeCheck", "bounded_sizes", "measure_size", "size_checks"]
+
+HIDDEN = "number_of_hidden_nodes"
+
+
+@dataclass(frozen=True)
+class SizeCheck:
+    """One bounded size to check on every decoded individual.
+
+    Parameters
+    ----------
+    organ : str
+        Organ name in the interface spec.
+    bound : str
+        Bound name, e.g. ``"number_of_hidden_nodes"``.
+    domain : Integer
+        The interface spec's bound.
+    conditional : bool
+        ``True`` when the pair is compatible under condition: a violation becomes
+        ``Invalid(DECODE)``. ``False``: the method committed to the bound and a violation is
+        a method error.
+
+    Notes
+    -----
+    [X] SZ1, SZ2.
+    """
+
+    organ: str
+    bound: str
+    domain: Integer
+    conditional: bool
+
+
+def bounded_sizes(organ_spec: object) -> dict[str, Integer]:
+    """Return the bounded sizes of an organ spec.
+
+    Parameters
+    ----------
+    organ_spec : object
+        A ``ParamsSpec``, ``NetworkSpec`` or any other organ spec.
+
+    Returns
+    -------
+    dict of str to Integer
+        Bound name -> domain. A fixed size ``n`` is ``Integer(n, n)``; an organ spec without
+        bounded size gives ``{}``.
+
+    Notes
+    -----
+    [X] I7, I8.
+    """
+    if isinstance(organ_spec, NetworkSpec):
+        hidden = organ_spec.number_of_hidden_nodes
+        if isinstance(hidden, Integer):
+            return {HIDDEN: hidden}
+        if isinstance(hidden, int):
+            return {HIDDEN: Integer(hidden, hidden)}
+    return {}
+
+
+def measure_size(organ: object, organ_spec: object, bound: str) -> int:
+    """Return the size of one organ for one bound.
+
+    Parameters
+    ----------
+    organ : object
+        The decoded organ.
+    organ_spec : object
+        Its organ spec.
+    bound : str
+        A bound of :func:`bounded_sizes` of ``organ_spec``.
+
+    Returns
+    -------
+    int
+        For ``number_of_hidden_nodes``: ``n_nodes`` minus the organ spec's input and output
+        port counts, the nodes beyond the ports being hidden ([K] §5.2).
+
+    Raises
+    ------
+    ValueError
+        For a bound the organ spec does not have, or an organ of another type.
+
+    Notes
+    -----
+    [X] I8.
+    """
+    if bound not in bounded_sizes(organ_spec):
+        raise ValueError(
+            f"size bound '{bound}' is not a bounded size of {type(organ_spec).__name__}"
+        )
+    if not isinstance(organ, Network):
+        raise ValueError(
+            f"size bound '{bound}': expected a Network organ, got {type(organ).__name__}"
+        )
+    assert isinstance(organ_spec, NetworkSpec)
+    n_in = organ_spec.number_of_input_nodes or 0
+    n_out = organ_spec.number_of_output_nodes or 0
+    return int(organ.n_nodes) - n_in - n_out
+
+
+def size_checks(spec: PhenotypeSpec, report: InterfaceReport, role: str) -> tuple[SizeCheck, ...]:
+    """Return the size checks to apply to the individuals of one role.
+
+    Parameters
+    ----------
+    spec : PhenotypeSpec
+        The role's interface spec.
+    report : InterfaceReport
+        The interface compatibility report of the method holding the role.
+    role : str
+        The role.
+
+    Returns
+    -------
+    tuple of SizeCheck
+        One per bounded size of every organ, in organ order; ``conditional`` is ``True`` iff
+        the report lists the bound as conditional for this role and organ.
+
+    Notes
+    -----
+    [X] SZ2: every bounded size is checked, whatever the outcome of the test.
+    """
+    conditional = {(c.organ, c.bound) for c in report.conditional if c.role == role}
+    return tuple(
+        SizeCheck(organ, bound, domain, (organ, bound) in conditional)
+        for organ, organ_spec in spec.organs.items()
+        for bound, domain in bounded_sizes(organ_spec).items()
+    )

MATE/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration of the runtime: the blueprint model, its canonical form and the seeds."""