se-interpretive-kernel 0.1.0__py3-none-any.whl

se_interpretive_kernel/partition.py

@@ -0,0 +1,363 @@
+"""partition.py - Finite partition algebra over a declared carrier.
+
+This module provides the lattice operations the interpretive kernel is built
+from and knows nothing about interpretation, frames, probes, or occurrences.
+It imports nothing else in this package.
+
+A :class:`Partition` is an equivalence relation on a finite ordered carrier,
+stored as a canonical block label for each carrier position.
+Two partitions over the same carrier are equal exactly when they induce the
+same blocks, regardless of how their blocks were originally labeled.
+
+The order is refinement.
+``a.refines(b)`` holds when every pair related by ``a`` is also related by
+``b``, so finer partitions are lower.
+The discrete partition is the bottom element and
+the one-block partition is the top element.
+Meet is intersection and join is the equivalence closure of the union.
+
+This layer is written to be extractable.
+It has no dependencies beyond the standard library and no vocabulary from the
+layers above it.
+Extraction is not justified until a second consumer needs this same public
+surface.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterable, Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from itertools import pairwise
+
+type Item = Hashable
+"""One element of a carrier. Any hashable value may be used."""
+
+type Pair = tuple[Item, Item]
+"""An unordered relationship between two carrier elements, written in order."""
+
+
+class _UnionFind:
+    """Maintain disjoint carrier groups generated by supplied pairs.
+
+    Each element begins in its own group.
+    Joining two elements merges their groups,
+    and finding an element returns the representative used as that
+    group's label.
+
+    Path compression shortens previously traversed parent chains so later
+    lookups require less work.
+
+    This class is duplicated in spirit across the Structural Explainability
+    repositories on purpose.
+    Where two implementations exist to check each other,
+    sharing this code would remove the independence that makes the comparison
+    meaningful.
+    """
+
+    def __init__(self, items: Iterable[Item]) -> None:
+        """Create one singleton group for every supplied element."""
+        self.parent: dict[Item, Item] = {x: x for x in items}
+
+    def find(self, x: Item) -> Item:
+        """Return the representative of the group containing ``x``.
+
+        The first loop follows parent links to the current root.
+        The second loop compresses the traversed path
+        so those elements point directly to that root.
+        """
+        root = x
+        while self.parent[root] != root:
+            root = self.parent[root]
+        while self.parent[x] != root:  # path compression
+            self.parent[x], x = root, self.parent[x]
+        return root
+
+    def union(self, a: Item, b: Item) -> None:
+        """Merge the groups containing ``a`` and ``b``.
+
+        Nothing changes when the two elements already belong to the same
+        group.
+        """
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            self.parent[rb] = ra
+
+
+def _canonical_labels(
+    carrier: Sequence[Item], raw: Mapping[Item, object]
+) -> tuple[int, ...]:
+    """Return block labels renumbered by first appearance in carrier order.
+
+    Any label values may be supplied.
+    They are replaced by integers assigned in the order their blocks are first
+    encountered, so two partitions with the same blocks receive the same
+    labels and compare equal.
+    """
+    seen: dict[object, int] = {}
+    out: list[int] = []
+    for item in carrier:
+        key = raw[item]
+        if key not in seen:
+            seen[key] = len(seen)
+        out.append(seen[key])
+    return tuple(out)
+
+
+@dataclass(frozen=True)
+class Partition:
+    """Represent one equivalence relation on a finite ordered carrier.
+
+    ``carrier`` is the finite domain, in a fixed order.
+    Carrier order determines canonical block numbering and the order in which
+    witnesses are searched, so results are deterministic.
+
+    ``labels`` gives the canonical block number of each carrier element, at
+    the same position as that element in ``carrier``.
+
+    Instances are constructed through the class methods rather than directly,
+    because those apply canonical renumbering.
+    """
+
+    carrier: tuple[Item, ...]
+    labels: tuple[int, ...]
+    _position: Mapping[Item, int] = field(
+        init=False, repr=False, compare=False, default_factory=dict
+    )
+
+    def __post_init__(self) -> None:
+        """Reject a malformed partition and build the position index.
+
+        Carrier elements must be distinct and every element must carry a
+        label.
+        """
+        if len(set(self.carrier)) != len(self.carrier):
+            msg = "carrier elements must be distinct"
+            raise ValueError(msg)
+        if len(self.labels) != len(self.carrier):
+            msg = "labels must supply one block number per carrier element"
+            raise ValueError(msg)
+        object.__setattr__(
+            self, "_position", {item: i for i, item in enumerate(self.carrier)}
+        )
+
+    # === Constructors ===
+
+    @classmethod
+    def from_labels(
+        cls, carrier: Sequence[Item], labels: Mapping[Item, object]
+    ) -> Partition:
+        """Return the partition grouping elements that share a label.
+
+        Label values are arbitrary and are renumbered canonically, so callers
+        may use whatever grouping key is natural for their domain.
+        """
+        seq = tuple(carrier)
+        return cls(seq, _canonical_labels(seq, labels))
+
+    @classmethod
+    def discrete(cls, carrier: Sequence[Item]) -> Partition:
+        """Return the finest partition, in which every element is alone.
+
+        This is the bottom element of the refinement order.
+        """
+        seq = tuple(carrier)
+        return cls(seq, tuple(range(len(seq))))
+
+    @classmethod
+    def indiscrete(cls, carrier: Sequence[Item]) -> Partition:
+        """Return the coarsest partition, in which all elements are together.
+
+        This is the top element of the refinement order.
+        """
+        seq = tuple(carrier)
+        return cls(seq, (0,) * len(seq))
+
+    @classmethod
+    def from_pairs(cls, carrier: Sequence[Item], pairs: Iterable[Pair]) -> Partition:
+        """Return the equivalence relation generated by the supplied pairs.
+
+        The supplied pairs need not be reflexive, symmetric, or transitive.
+        Their equivalence closure is computed by union-find, so only a
+        generating set has to be supplied.
+
+        This is the operation that makes the threshold construction cheap: a
+        spanning forest of a regime generates the same closure as the full
+        relation.
+        """
+        seq = tuple(carrier)
+        uf = _UnionFind(seq)
+        for x, y in pairs:
+            uf.union(x, y)
+        return cls.from_labels(seq, {item: uf.find(item) for item in seq})
+
+    @classmethod
+    def from_blocks(
+        cls, carrier: Sequence[Item], blocks: Iterable[Iterable[Item]]
+    ) -> Partition:
+        """Return the partition with the supplied blocks.
+
+        Elements of the carrier not named in any supplied block are placed in
+        singleton blocks of their own.
+        """
+        seq = tuple(carrier)
+        pairs: list[Pair] = []
+        for block in blocks:
+            members = list(block)
+            pairs.extend(pairwise(members))
+        return cls.from_pairs(seq, pairs)
+
+    # === Queries ===
+
+    def blocks(self) -> tuple[tuple[Item, ...], ...]:
+        """Return the blocks, each in carrier order, ordered by first member."""
+        groups: dict[int, list[Item]] = {}
+        for item, label in zip(self.carrier, self.labels, strict=True):
+            groups.setdefault(label, []).append(item)
+        return tuple(tuple(groups[k]) for k in sorted(groups))
+
+    def label_of(self, item: Item) -> int:
+        """Return the canonical block number of one carrier element."""
+        return self.labels[self._position[item]]
+
+    def same(self, x: Item, y: Item) -> bool:
+        """Return whether two carrier elements lie in the same block."""
+        return self.label_of(x) == self.label_of(y)
+
+    def refines(self, other: Partition) -> bool:
+        """Return whether this partition refines ``other``.
+
+        Refinement holds when every pair this partition relates is also
+        related by ``other``.
+        A finer partition may make additional distinctions,
+        but it may not merge elements the coarser partition separates.
+
+        The check records the first ``other`` label seen for each of this
+        partition's labels and fails on a later conflict, so no pair of
+        carrier elements is enumerated.
+        """
+        self._require_same_carrier(other)
+        seen: dict[int, int] = {}
+        for item in self.carrier:
+            fine, coarse = self.label_of(item), other.label_of(item)
+            if fine in seen:
+                if seen[fine] != coarse:
+                    return False
+            else:
+                seen[fine] = coarse
+        return True
+
+    def refinement_witness(self, other: Partition) -> Pair | None:
+        """Return a pair showing why this partition does not refine ``other``.
+
+        The returned pair is related by this partition and separated by
+        ``other``.
+        Carrier order is searched in order and the first such pair is
+        returned, so the witness is deterministic.
+
+        None is returned when this partition does refine ``other``.
+        """
+        self._require_same_carrier(other)
+        anchor: dict[int, Item] = {}
+        for item in self.carrier:
+            fine = self.label_of(item)
+            if fine not in anchor:
+                anchor[fine] = item
+            elif not other.same(anchor[fine], item):
+                return (anchor[fine], item)
+        return None
+
+    # === Lattice operations ===
+
+    def meet(self, other: Partition) -> Partition:
+        """Return the greatest lower bound: elements related by both.
+
+        Meet is intersection.
+        The result relates two elements exactly when this partition and
+        ``other`` both relate them.
+        """
+        self._require_same_carrier(other)
+        return Partition.from_labels(
+            self.carrier,
+            {
+                item: (self.label_of(item), other.label_of(item))
+                for item in self.carrier
+            },
+        )
+
+    def join(self, other: Partition) -> Partition:
+        """Return the least upper bound: the closure of both relations.
+
+        Join is the equivalence closure of the union.
+        Each partition contributes a spanning path through every one of its
+        blocks, which generates the same closure as the full relations.
+        """
+        self._require_same_carrier(other)
+        pairs: list[Pair] = []
+        for part in (self, other):
+            for block in part.blocks():
+                pairs.extend(pairwise(block))
+        return Partition.from_pairs(self.carrier, pairs)
+
+    def _require_same_carrier(self, other: Partition) -> None:
+        """Reject a comparison between partitions over different carriers.
+
+        Refinement is only defined between partitions of one domain.
+        Comparing across carriers is the mistyping this guard exists to
+        surface rather than silently permit.
+        """
+        if self.carrier != other.carrier:
+            msg = "partitions must be over the same carrier, in the same order"
+            raise ValueError(msg)
+
+
+def all_partitions(carrier: Sequence[Item]) -> Iterator[Partition]:
+    """Yield every partition of a finite carrier, once each.
+
+    Partitions are generated as restricted growth strings, which are already
+    the canonical labeling, so each partition is produced exactly once.
+
+    The count is the Bell number of the carrier size and grows quickly.
+    This is intended for exhaustive law checking over the small carriers the
+    counterexamples and property tests use, not for enumeration at scale.
+    """
+    seq = tuple(carrier)
+    size = len(seq)
+    if size == 0:
+        yield Partition(seq, ())
+        return
+
+    def grow(prefix: list[int], used: int) -> Iterator[tuple[int, ...]]:
+        if len(prefix) == size:
+            yield tuple(prefix)
+            return
+        for label in range(used + 1):
+            prefix.append(label)
+            yield from grow(prefix, max(used, label + 1))
+            prefix.pop()
+
+    for labels in grow([], 0):
+        yield Partition(seq, labels)
+
+
+def meet_all(carrier: Sequence[Item], parts: Iterable[Partition]) -> Partition:
+    """Return the meet of every supplied partition over a carrier.
+
+    An empty collection yields the top element, which is the identity for
+    meet.
+    """
+    result = Partition.indiscrete(carrier)
+    for part in parts:
+        result = result.meet(part)
+    return result
+
+
+def join_all(carrier: Sequence[Item], parts: Iterable[Partition]) -> Partition:
+    """Return the join of every supplied partition over a carrier.
+
+    An empty collection yields the bottom element, which is the identity for
+    join.
+    """
+    result = Partition.discrete(carrier)
+    for part in parts:
+        result = result.join(part)
+    return result

se_interpretive_kernel/probes.py

@@ -0,0 +1,124 @@
+"""probes.py - Probe sensitivity of the kernel and the threshold.
+
+Every result in this package is relative to the declared probe family Q. This
+module reports how much each result depends on which probes are in Q.
+
+For the kernel K_Q(rho):
+
+- :func:`separating_probes` lists the probes that tell two frames apart.
+- :func:`sole_separated_pairs` lists, for each probe, the frame pairs that no
+  other selected probe separates.
+- :func:`load_bearing_probes` lists the probes whose removal changes the
+  kernel.
+- :func:`minimal_probe_sets` lists every smallest-by-inclusion subset of Q that
+  gives the same kernel.
+
+For the threshold L_Q(phi):
+
+- :func:`probe_contributions` gives the threshold each probe forces alone. By
+  probe-union duality (Lean: ``liftRel_probeUnion``), L_Q(phi) is the join of
+  these.
+
+Nothing here decides whether the probe family is complete. It reports how the
+answer moves when probes are added or removed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from itertools import combinations
+
+from .artifact import Artifact
+from .generated import generated
+from .kernel import kernel
+from .partition import Item, Partition
+
+
+def separating_probes(
+    artifact: Artifact,
+    selected: Sequence[Item],
+    rho: Partition,
+    x: Item,
+    y: Item,
+) -> tuple[Item, ...]:
+    """Return the selected probes whose outputs for x and y rho does not relate.
+
+    The frames x and y are related by K_Q(rho) exactly when this is empty.
+    """
+    artifact.require_selected(selected)
+    if rho.carrier != artifact.outputs:
+        msg = "rho must be a partition of the artifact's outputs, in order"
+        raise ValueError(msg)
+    return tuple(
+        probe
+        for probe in selected
+        if not rho.same(artifact.interpret(probe, x), artifact.interpret(probe, y))
+    )
+
+
+def sole_separated_pairs(
+    artifact: Artifact, selected: Sequence[Item], rho: Partition
+) -> dict[Item, list[tuple[Item, Item]]]:
+    """Return, for each selected probe, the frame pairs only that probe separates.
+
+    A pair listed under probe p is related by K_Q(rho) minus p and separated by
+    K_Q(rho): removing p from the family would merge the two frames. Pairs are
+    listed once, in frame order. Every selected probe appears as a key, with an
+    empty list when it is the sole separator of nothing.
+    """
+    result: dict[Item, list[tuple[Item, Item]]] = {probe: [] for probe in selected}
+    frames = artifact.frames
+    for i, x in enumerate(frames):
+        for y in frames[i + 1 :]:
+            separators = separating_probes(artifact, selected, rho, x, y)
+            if len(separators) == 1:
+                result[separators[0]].append((x, y))
+    return result
+
+
+def load_bearing_probes(
+    artifact: Artifact, selected: Sequence[Item], rho: Partition
+) -> tuple[Item, ...]:
+    """Return the selected probes whose removal changes K_Q(rho).
+
+    Because the kernel only gets coarser as probes are removed, a load-bearing
+    probe belongs to every minimal probe set.
+    """
+    full = kernel(artifact, selected, rho)
+    return tuple(
+        probe
+        for probe in selected
+        if kernel(artifact, [p for p in selected if p != probe], rho) != full
+    )
+
+
+def minimal_probe_sets(
+    artifact: Artifact, selected: Sequence[Item], rho: Partition
+) -> list[tuple[Item, ...]]:
+    """Return every subset of Q that gives the same kernel and has no smaller one.
+
+    The search is exhaustive over subsets, smallest first, so it is intended
+    for small probe families. :func:`load_bearing_probes` and
+    :func:`sole_separated_pairs` scale polynomially and give the same
+    information about single probes.
+    """
+    target = kernel(artifact, selected, rho)
+    found: list[tuple[Item, ...]] = []
+    for size in range(len(selected) + 1):
+        for subset in combinations(selected, size):
+            if any(set(smaller) <= set(subset) for smaller in found):
+                continue
+            if kernel(artifact, subset, rho) == target:
+                found.append(subset)
+    return found
+
+
+def probe_contributions(
+    artifact: Artifact, selected: Sequence[Item], phi: Partition
+) -> dict[Item, Partition]:
+    """Return, for each selected probe, the threshold that probe forces alone.
+
+    The threshold of the whole family is the join of these partitions.
+    """
+    artifact.require_selected(selected)
+    return {probe: generated(artifact, (probe,), phi) for probe in selected}

se_interpretive_kernel/sampling.py

@@ -0,0 +1,36 @@
+"""sampling.py - Random small artifacts for property checks.
+
+Deterministic for a given seed. Sizes are kept small so that exhaustive
+enumeration of partitions of the outputs and the frames stays cheap.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from random import Random
+
+from .artifact import Artifact
+from .partition import Item
+
+
+def random_artifact(
+    rng: Random, max_frames: int = 4, max_outputs: int = 4, max_probes: int = 3
+) -> Artifact:
+    """Return a random total artifact of small size."""
+    n_frames = rng.randint(1, max_frames)
+    n_outputs = rng.randint(1, max_outputs)
+    n_probes = rng.randint(0, max_probes)
+    frames = tuple(range(n_frames))
+    outputs = tuple(range(n_outputs))
+    probes = tuple(f"p{i}" for i in range(n_probes))
+    table: dict[tuple[Item, Item], Item] = {
+        (p, f): rng.choice(outputs) for p in probes for f in frames
+    }
+    return Artifact(frames, outputs, probes, table, "random")
+
+
+def random_artifacts(count: int, seed: int) -> Iterator[Artifact]:
+    """Yield ``count`` random artifacts for the given seed."""
+    rng = Random(seed)
+    for _ in range(count):
+        yield random_artifact(rng)

se_interpretive_kernel/witness.py

@@ -0,0 +1,69 @@
+"""witness.py - Finite incompatibility witnesses.
+
+A witness against coherence of phi with rho (Lean:
+``IncompatibilityWitness``) consists of two frames related by phi, a selected
+probe, and the two outputs, which rho does not relate.
+
+A witness shows that the supplied phi, rho, probes, and interpretation are
+incompatible. It does not show which of them is the faulty choice.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .artifact import Artifact
+from .partition import Item, Partition
+
+
+@dataclass(frozen=True)
+class Witness:
+    """Contain one finite incompatibility witness."""
+
+    frame_1: Item
+    frame_2: Item
+    probe: Item
+    output_1: Item
+    output_2: Item
+
+
+def find_witness(
+    artifact: Artifact, selected: Sequence[Item], phi: Partition, rho: Partition
+) -> Witness | None:
+    """Return a witness against coherence, or None when phi is coherent.
+
+    Within each block of phi the first frame is compared with every later
+    frame. This finds a witness whenever one exists: if the first frame agrees
+    with each later frame under every selected probe, transitivity of rho gives
+    agreement for every pair in the block.
+    """
+    artifact.require_selected(selected)
+    for block in phi.blocks():
+        anchor = block[0]
+        for frame in block[1:]:
+            for probe in selected:
+                out_anchor = artifact.interpret(probe, anchor)
+                out_frame = artifact.interpret(probe, frame)
+                if not rho.same(out_anchor, out_frame):
+                    return Witness(anchor, frame, probe, out_anchor, out_frame)
+    return None
+
+
+def witness_is_valid(
+    artifact: Artifact,
+    selected: Sequence[Item],
+    phi: Partition,
+    rho: Partition,
+    witness: Witness,
+) -> bool:
+    """Return whether a witness satisfies the definition of a witness."""
+    if witness.probe not in set(selected):
+        return False
+    if not phi.same(witness.frame_1, witness.frame_2):
+        return False
+    if artifact.interpret(witness.probe, witness.frame_1) != witness.output_1:
+        return False
+    if artifact.interpret(witness.probe, witness.frame_2) != witness.output_2:
+        return False
+    return not rho.same(witness.output_1, witness.output_2)