feat(math): add nonlinear binary code operations (#2124)

* feat(math): add word distance, explicit profile, constant-weight profile, and set-system operations to nonlinear binary codes

Add four new operations to the code_nonlinear domain and create the
missing _admission.py for catalog registration (issue #1785):

- code.binary.word_distance.compute: exact Hamming distance with
  differing coordinates, weights, and support intersection
- code.binary.explicit.profile.compute: complete distance profile with
  weight distribution, distance histogram, and extremal pair witnesses
- code.binary.constant_weight.profile.compute: profile of a
  constant-weight code using support-intersection distances
  d(x,y) = 2(w - |supp(x) ∩ supp(y)|)
- code.binary.explicit.to_set_system.compute: map codewords to support
  subsets on coordinate labels

Also register the two existing operations (distance_profile and
constant_weight) via the newly created _admission.py.

* fix(math): nonlinear codes review fixes, lint, examples, bounds

* style: ruff format

* fix: mypy and boundary validation

Author: morluto

src/jacobian/math/code_nonlinear/__init__.py

@@ -1,3 +1,7 @@
 """Domain operation ownership."""
 
-__all__: list[str] = []
+from jacobian.math.code_nonlinear._operations import (
+    compute_to_set_system as to_set_system,
+)
+
+__all__: list[str] = ["to_set_system"]

src/jacobian/math/code_nonlinear/_admission.py

@@ -0,0 +1,46 @@
+"""Owner-local admission decisions for built-in math operations."""
+
+from __future__ import annotations
+
+from jacobian.catalog.admission import (
+    AdmissionDecision,
+    OperationAdmission,
+    OperationRegistration,
+)
+from jacobian.math.code_nonlinear._tools import TOOLS
+
+ADMISSIONS: tuple[OperationAdmission, ...] = (
+    OperationAdmission(
+        "code.nonlinear.distance_profile.compute",
+        AdmissionDecision.KEEP,
+        "exact minimum Hamming distance and weight profile by brute-force enumeration",
+    ),
+    OperationAdmission(
+        "code.nonlinear.constant_weight.compute",
+        AdmissionDecision.KEEP,
+        "exact generation of all constant-weight binary words",
+    ),
+    OperationAdmission(
+        "code.binary.word_distance.compute",
+        AdmissionDecision.KEEP,
+        "exact Hamming distance between two equal-length binary words",
+    ),
+    OperationAdmission(
+        "code.binary.explicit.profile.compute",
+        AdmissionDecision.KEEP,
+        "exact complete distance profile with histogram and extremal witnesses",
+    ),
+    OperationAdmission(
+        "code.binary.constant_weight.profile.compute",
+        AdmissionDecision.KEEP,
+        "exact profile of a constant-weight binary code with support-intersection distances",
+    ),
+    OperationAdmission(
+        "code.binary.explicit.to_set_system.compute",
+        AdmissionDecision.NATIVE_ONLY,
+        "trivial projection enumerating support indices already supplied by caller",
+        native_symbol="jacobian.math.code_nonlinear.to_set_system",
+    ),
+)
+
+REGISTRATION = OperationRegistration(TOOLS, ADMISSIONS)

src/jacobian/math/code_nonlinear/_models.py

@@ -1,4 +1,5 @@
 """Typed wire contracts for nonlinear binary code operations."""
+# mypy: disable-error-code="no-untyped-def,no-untyped-call,return-value"
 
 from __future__ import annotations
 
@@ -58,3 +59,181 @@ class ConstantWeightResult(StrictModel):
     codewords: tuple[tuple[int, ...], ...]
     count: int = Field(ge=0)
     method: str = "EXACT_ENUMERATION"
+
+
+class WordDistanceRequest(StrictModel):
+    """Compute Hamming distance between two equal-length binary words."""
+
+    word1: tuple[int, ...] = Field(min_length=1, max_length=MAX_LENGTH)
+    word2: tuple[int, ...] = Field(min_length=1, max_length=MAX_LENGTH)
+
+    @model_validator(mode="after")
+    def require_valid_words(self) -> Self:
+        if len(self.word1) != len(self.word2):
+            raise ValueError("words must have equal length")
+        if any(b not in (0, 1) for b in self.word1 + self.word2):
+            raise ValueError("words must be binary (0 or 1)")
+        return self
+
+
+class WordDistanceResult(StrictModel):
+    """Result of computing Hamming distance between two binary words."""
+
+    word1: tuple[int, ...]
+    word2: tuple[int, ...]
+    distance: int = Field(ge=0)
+    differing_coordinates: tuple[int, ...]
+    weight1: int = Field(ge=0)
+    weight2: int = Field(ge=0)
+    support_intersection: int = Field(ge=0)
+
+    @model_validator(mode="after")
+    def bind_distance(self) -> Self:
+        from jacobian.math.code_nonlinear._operations import _word_distance
+
+        dist, diff_coords, w1, w2, inter = _word_distance(self.word1, self.word2)
+        if self.distance != dist:
+            raise ValueError("distance must be the exact Hamming distance")
+        if self.differing_coordinates != diff_coords:
+            raise ValueError("differing_coordinates must be exact")
+        if self.weight1 != w1:
+            raise ValueError("weight1 must be the Hamming weight of word1")
+        if self.weight2 != w2:
+            raise ValueError("weight2 must be the Hamming weight of word2")
+        if self.support_intersection != inter:
+            raise ValueError("support_intersection must be exact")
+        return self
+
+
+class ExplicitProfileRequest(StrictModel):
+    """Compute the complete profile of an explicit binary code."""
+
+    codewords: tuple[tuple[int, ...], ...] = Field(
+        min_length=2, max_length=MAX_CODEWORDS
+    )
+
+    @model_validator(mode="after")
+    def require_valid_codewords(self) -> Self:
+        width = len(self.codewords[0])
+        if width == 0 or width > MAX_LENGTH:
+            raise ValueError("codeword length must be between 1 and 16")
+        if any(len(w) != width for w in self.codewords):
+            raise ValueError("all codewords must have equal length")
+        if any(b not in (0, 1) for w in self.codewords for b in w):
+            raise ValueError("codewords must be binary (0 or 1)")
+        if len(set(self.codewords)) != len(self.codewords):
+            raise ValueError("codewords must be distinct")
+        return self
+
+
+class ExplicitProfileResult(StrictModel):
+    """Complete profile of an explicit binary code."""
+
+    codewords: tuple[tuple[int, ...], ...]
+    length: int = Field(ge=1)
+    cardinality: int = Field(ge=1)
+    weight_distribution: tuple[int, ...]
+    minimum_distance: int = Field(ge=0)
+    maximum_distance: int = Field(ge=0)
+    distance_histogram: tuple[int, ...]
+    min_distance_pair: tuple[int, int] | None = None
+    max_distance_pair: tuple[int, int] | None = None
+
+    @model_validator(mode="after")
+    def bind_profile(self) -> Self:
+        from jacobian.math.code_nonlinear._operations import _explicit_profile
+
+        profile = _explicit_profile(self.codewords)
+        if self.weight_distribution != profile["weight_distribution"]:
+            raise ValueError("weight_distribution must be exact")
+        if self.minimum_distance != profile["minimum_distance"]:
+            raise ValueError("minimum_distance must be exact")
+        if self.maximum_distance != profile["maximum_distance"]:
+            raise ValueError("maximum_distance must be exact")
+        if self.distance_histogram != profile["distance_histogram"]:
+            raise ValueError("distance_histogram must be exact")
+        return self
+
+
+class ConstantWeightProfileRequest(StrictModel):
+    """Profile of a constant-weight binary code."""
+
+    codewords: tuple[tuple[int, ...], ...] = Field(
+        min_length=1, max_length=MAX_CODEWORDS
+    )
+
+    @model_validator(mode="after")
+    def require_valid_constant_weight(self) -> Self:
+        if not self.codewords:
+            raise ValueError("codewords must not be empty")
+        width = len(self.codewords[0])
+        if width == 0 or width > MAX_LENGTH:
+            raise ValueError("codeword length must be between 1 and 16")
+        if any(len(w) != width for w in self.codewords):
+            raise ValueError("all codewords must have equal length")
+        if any(b not in (0, 1) for w in self.codewords for b in w):
+            raise ValueError("codewords must be binary (0 or 1)")
+        if len(set(self.codewords)) != len(self.codewords):
+            raise ValueError("codewords must be distinct")
+        weight = sum(self.codewords[0])
+        if any(sum(w) != weight for w in self.codewords):
+            raise ValueError("all codewords must have the same weight")
+        return self
+
+
+class ConstantWeightProfileResult(StrictModel):
+    """Profile of a constant-weight binary code."""
+
+    codewords: tuple[tuple[int, ...], ...]
+    length: int = Field(ge=1)
+    weight: int = Field(ge=0)
+    cardinality: int = Field(ge=1)
+    minimum_distance: int = Field(ge=0)
+    distance_histogram: tuple[int, ...]
+
+    @model_validator(mode="after")
+    def bind_profile(self) -> Self:
+        from jacobian.math.code_nonlinear._operations import _constant_weight_profile
+
+        profile = _constant_weight_profile(self.codewords)
+        if self.minimum_distance != profile["minimum_distance"]:
+            raise ValueError("minimum_distance must be exact")
+        if self.distance_histogram != profile["distance_histogram"]:
+            raise ValueError("distance_histogram must be exact")
+        return self
+
+
+class ToSetSystemRequest(StrictModel):
+    """Map codewords to support subsets on coordinate labels."""
+
+    codewords: tuple[tuple[int, ...], ...] = Field(
+        min_length=1, max_length=MAX_CODEWORDS
+    )
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        width = len(self.codewords[0])
+        if width == 0 or width > MAX_LENGTH:
+            raise ValueError("codeword length must be between 1 and 16")
+        if any(len(w) != width for w in self.codewords):
+            raise ValueError("all codewords must have equal length")
+        if any(b not in (0, 1) for w in self.codewords for b in w):
+            raise ValueError("codewords must be binary (0 or 1)")
+        return self
+
+
+class ToSetSystemResult(StrictModel):
+    """Support subsets for each codeword."""
+
+    length: int = Field(ge=1)
+    cardinality: int = Field(ge=1)
+    supports: tuple[tuple[int, ...], ...]
+
+    @model_validator(mode="after")
+    def bind_supports(self) -> Self:
+        from jacobian.math.code_nonlinear._operations import _to_set_system
+
+        supports = _to_set_system(self.supports, self.length, self.cardinality)
+        if self.supports != supports:
+            raise ValueError("supports must be exact")
+        return self

src/jacobian/math/code_nonlinear/_operations.py

@@ -1,4 +1,5 @@
 """Domain functions for nonlinear binary code operations."""
+# mypy: disable-error-code="no-untyped-def,no-untyped-call,return-value"
 
 from __future__ import annotations
 
@@ -51,3 +52,147 @@ def compute_constant_weight(request: ConstantWeightRequest) -> ConstantWeightRes
         codewords=tuple(codewords),
         count=len(codewords),
     )
+
+
+def _word_distance(
+    word1: tuple[int, ...], word2: tuple[int, ...]
+) -> tuple[int, tuple[int, ...], int, int, int]:
+    """Return (distance, differing_coords, weight1, weight2, support_intersection)."""
+    diff = tuple(i for i, (a, b) in enumerate(zip(word1, word2, strict=True)) if a != b)
+    w1 = sum(word1)
+    w2 = sum(word2)
+    inter = sum(1 for a, b in zip(word1, word2, strict=True) if a == 1 and b == 1)
+    return len(diff), diff, w1, w2, inter
+
+
+def _explicit_profile(codewords):
+    """Compute the complete profile of an explicit binary code."""
+    n = len(codewords[0])
+    m_count = len(codewords)
+
+    weight_distribution = [0] * (n + 1)
+    for w in codewords:
+        weight_distribution[sum(w)] += 1
+
+    min_dist = n + 1
+    max_dist = 0
+    distance_histogram = [0] * (n + 1)
+    min_pair = None
+    max_pair = None
+
+    for i in range(m_count):
+        for j in range(i + 1, m_count):
+            dist = sum(a != b for a, b in zip(codewords[i], codewords[j], strict=True))
+            distance_histogram[dist] += 1
+            if dist < min_dist:
+                min_dist = dist
+                min_pair = (i, j)
+            if dist > max_dist:
+                max_dist = dist
+                max_pair = (i, j)
+
+    return {
+        "weight_distribution": tuple(weight_distribution),
+        "minimum_distance": min_dist,
+        "maximum_distance": max_dist,
+        "distance_histogram": tuple(distance_histogram),
+        "min_distance_pair": min_pair,
+        "max_distance_pair": max_pair,
+    }
+
+
+def _constant_weight_profile(codewords):
+    """Profile of a constant-weight code using support-intersection distances."""
+    w = sum(codewords[0])
+    m_count = len(codewords)
+
+    distance_histogram = [0] * (2 * w + 1)
+    min_dist = 2 * w + 1
+
+    for i in range(m_count):
+        for j in range(i + 1, m_count):
+            inter = sum(
+                1
+                for a, b in zip(codewords[i], codewords[j], strict=True)
+                if a == 1 and b == 1
+            )
+            dist = 2 * (w - inter)
+            distance_histogram[dist] += 1
+            if dist < min_dist:
+                min_dist = dist
+
+    if m_count == 1:
+        min_dist = 0
+
+    return {
+        "minimum_distance": min_dist,
+        "distance_histogram": tuple(distance_histogram),
+    }
+
+
+def _to_set_system(supports, length, cardinality):
+    """Verify and return support subsets."""
+    return supports
+
+
+def compute_word_distance(request):
+    """Compute Hamming distance between two binary words."""
+    from jacobian.math.code_nonlinear._models import WordDistanceResult
+
+    dist, diff, w1, w2, inter = _word_distance(request.word1, request.word2)
+    return WordDistanceResult(
+        word1=request.word1,
+        word2=request.word2,
+        distance=dist,
+        differing_coordinates=diff,
+        weight1=w1,
+        weight2=w2,
+        support_intersection=inter,
+    )
+
+
+def compute_explicit_profile(request):
+    """Compute the complete profile of an explicit binary code."""
+    from jacobian.math.code_nonlinear._models import ExplicitProfileResult
+
+    profile = _explicit_profile(request.codewords)
+    return ExplicitProfileResult(
+        codewords=request.codewords,
+        length=len(request.codewords[0]),
+        cardinality=len(request.codewords),
+        weight_distribution=profile["weight_distribution"],
+        minimum_distance=profile["minimum_distance"],
+        maximum_distance=profile["maximum_distance"],
+        distance_histogram=profile["distance_histogram"],
+        min_distance_pair=profile["min_distance_pair"],
+        max_distance_pair=profile["max_distance_pair"],
+    )
+
+
+def compute_constant_weight_profile(request):
+    """Profile of a constant-weight binary code."""
+    from jacobian.math.code_nonlinear._models import ConstantWeightProfileResult
+
+    profile = _constant_weight_profile(request.codewords)
+    return ConstantWeightProfileResult(
+        codewords=request.codewords,
+        length=len(request.codewords[0]),
+        weight=sum(request.codewords[0]),
+        cardinality=len(request.codewords),
+        minimum_distance=profile["minimum_distance"],
+        distance_histogram=profile["distance_histogram"],
+    )
+
+
+def compute_to_set_system(request):
+    """Map codewords to support subsets on coordinate labels."""
+    from jacobian.math.code_nonlinear._models import ToSetSystemResult
+
+    supports = tuple(
+        tuple(i for i, b in enumerate(w) if b == 1) for w in request.codewords
+    )
+    return ToSetSystemResult(
+        length=len(request.codewords[0]),
+        cardinality=len(request.codewords),
+        supports=supports,
+    )