synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/solvers/exact/__init__.py

@@ -0,0 +1,141 @@
+"""
+Exact mapping methods, enumeration, and optimality certificates.
+
+Full-space search and kernel refinement are distinct workflows. PABS
+(Propagation and Assignment-Bounded Search) selects Python propagation or
+optional C++ full-space search. The kernel solvers optimize a reduced
+uncertainty region supplied by the SLAP workflow. A LAP (linear assignment
+problem) provides a bound or a matching step in several of these methods.
+
+Submodules
+----------
+search
+    PABS public interface with explicit Python or C++ backend selection.
+distance_search
+    Full atom-compatible distance enumeration, replay certificates, admissible
+    bounds, and the standalone small-graph exhaustive mapper.
+kernel_solvers
+    WL/SLAP uncertainty-kernel extraction, orbital branching, optional MILP,
+    and enumeration within the supplied kernel restrictions.
+pabs
+    Python reversible-domain propagation search and residual cost spectra.
+native
+    Optional C++ search, canonicalization, orbit scheduling, and explicit
+    compilation of the adjacent ``native_distance.cpp`` source. Execution
+    requires a supplied library path.
+assignment
+    Shared LAP domains, incremental solves, and integer primal-dual proofs.
+seeds
+    Feasible-incumbent heuristics; these do not establish optimality.
+hybrid, edit_support
+    Exact-backend selection and binary edit-support enumeration.
+core, hydrogen, symmetry, certificate
+    Reference-component reduction, hydrogen lifting, permutation-group helpers,
+    and optimality-gap reporting.
+
+Historical flat modules remain aliases to these canonical implementations.
+"""
+
+from .kernel_solvers.kernel import Kernel, extract_kernel, apply_kernel_solution
+from .kernel_solvers.branching import KernelSolution, solve_kernel, solve_kernel_blockwise
+from .distance_search.exhaustive import ExactResult, ExactMapper
+from .certificate import Certificate, certify_result, certify_results_exact
+from .kernel_solvers.enumerate import (
+    EnumerationResult,
+    canonical_mapping_key,
+    canonical_partial_mapping_key,
+    dedup_mappings_by_automorphism,
+    enumerate_kernel_optima,
+    enumerate_symmetry_distinct_optima,
+)
+from .distance_search.search import (
+    CertificateVerificationError,
+    DistanceEnumerationCertificate,
+    DistanceEnumerationResult,
+    EnumerationStatus,
+    ExactEnumerationLimitError,
+    enumerate_distance_mappings,
+    verify_distance_enumeration_certificate,
+)
+from .core import ITSComponentReduction, reduce_to_reference_its_components
+from .hydrogen import (
+    HydrogenEnumerationResult,
+    HydrogenLiftSummary,
+    HydrogenTransferPlan,
+    enumerate_lgp_hydrogen_transfers,
+    enumerate_minimal_hydrogen_transfers,
+    summarize_minimal_hydrogen_lifts,
+)
+from .edit_support import (
+    BinaryEditBudget,
+    BinaryEditSupportResult,
+    binary_edit_budget,
+    enumerate_binary_edit_support_mappings,
+)
+from .hybrid import (
+    HybridBackend,
+    HybridBackendDecision,
+    enumerate_hybrid_distance_mappings,
+)
+from .pabs.propagation import PropagationConfig, enumerate_synister_cp_mappings
+from .search import enumerate_pabs_mappings
+from .pabs.multi_shell import enumerate_pabs_shells
+
+from ..._compat import (
+    EXACT_MODULE_ALIASES as _EXACT_MODULE_ALIASES,
+    register_module_aliases as _register_module_aliases,
+)
+
+_register_module_aliases(__name__, _EXACT_MODULE_ALIASES)
+
+__all__ = [
+    # kernel
+    "Kernel",
+    "extract_kernel",
+    "apply_kernel_solution",
+    # branching
+    "KernelSolution",
+    "solve_kernel",
+    "solve_kernel_blockwise",
+    # exhaustive
+    "ExactResult",
+    "ExactMapper",
+    # certificate
+    "Certificate",
+    "certify_result",
+    "certify_results_exact",
+    # enumerate
+    "EnumerationResult",
+    "canonical_mapping_key",
+    "canonical_partial_mapping_key",
+    "dedup_mappings_by_automorphism",
+    "enumerate_kernel_optima",
+    "enumerate_symmetry_distinct_optima",
+    # distance
+    "CertificateVerificationError",
+    "DistanceEnumerationCertificate",
+    "DistanceEnumerationResult",
+    "EnumerationStatus",
+    "ExactEnumerationLimitError",
+    "enumerate_distance_mappings",
+    "verify_distance_enumeration_certificate",
+    "ITSComponentReduction",
+    "reduce_to_reference_its_components",
+    "HydrogenEnumerationResult",
+    "HydrogenLiftSummary",
+    "HydrogenTransferPlan",
+    "enumerate_lgp_hydrogen_transfers",
+    "enumerate_minimal_hydrogen_transfers",
+    "summarize_minimal_hydrogen_lifts",
+    "BinaryEditBudget",
+    "BinaryEditSupportResult",
+    "binary_edit_budget",
+    "enumerate_binary_edit_support_mappings",
+    "HybridBackend",
+    "HybridBackendDecision",
+    "enumerate_hybrid_distance_mappings",
+    "PropagationConfig",
+    "enumerate_synister_cp_mappings",
+    "enumerate_pabs_mappings",
+    "enumerate_pabs_shells",
+]

synkit/Chem/Mapper/solvers/exact/assignment/__init__.py

@@ -0,0 +1 @@
+"""Shared reversible LAP domains and bounded-integer assignment certificates."""

synkit/Chem/Mapper/solvers/exact/assignment/assignment_certificate.py

@@ -0,0 +1,113 @@
+"""Integer primal--dual certificates for bounded quarter-lattice assignments.
+
+The floating-point LAP routine supplies a candidate permutation, not a trusted
+lower bound. Exact integer dual feasibility and equality certify optimality.
+This module does not certify the surrounding graph-search arithmetic.
+"""
+
+from dataclasses import dataclass
+from numbers import Integral
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+
+MAX_ORDER = 512
+MAX_SCALED_ENTRY = 2**40
+SCALE = 4
+
+
+@dataclass(frozen=True)
+class AssignmentCertificate:
+    """All objective and potential values are scaled by four."""
+
+    permutation: tuple[int, ...]
+    row_potentials: tuple[int, ...]
+    column_potentials: tuple[int, ...]
+    scaled_objective: int
+
+
+def scaled_lattice_costs(costs):
+    """Validate the supported domain before any fixed-width integer algebra."""
+    array = np.asarray(costs, dtype=float)
+    if array.ndim != 2 or array.shape[0] != array.shape[1]:
+        raise ValueError("Assignment costs must be a square matrix")
+    if array.shape[0] > MAX_ORDER or not np.isfinite(array).all():
+        raise ValueError("Assignment certificate domain requires finite order <= 512")
+    if np.max(np.abs(array), initial=0) > MAX_SCALED_ENTRY / SCALE:
+        raise ValueError("Assignment entry exceeds the certified lattice range")
+    scaled = array * SCALE
+    if not np.equal(scaled, np.rint(scaled)).all():
+        raise ValueError("Assignment costs must lie on the quarter-integer lattice")
+    return scaled.astype(np.int64)
+
+
+def verify_assignment_certificate(costs, certificate):
+    """Check a candidate with Python integers, independent of LAP/dual search.
+
+    For every i,p, u[i]+v[p] <= C[i,p]. Equality of the feasible matching
+    objective and sum(u)+sum(v) then proves its minimum by weak duality.
+    Invalid certificates return False; unsupported cost matrices raise ValueError.
+    """
+    matrix = scaled_lattice_costs(costs)
+    n = len(matrix)
+    if not isinstance(certificate, AssignmentCertificate):
+        return False
+    permutation = certificate.permutation
+    u, v = certificate.row_potentials, certificate.column_potentials
+    if not all(isinstance(value, tuple) for value in (permutation, u, v)):
+        return False
+    if len(permutation) != n or len(u) != n or len(v) != n:
+        return False
+    values = (*permutation, *u, *v, certificate.scaled_objective)
+    if any(isinstance(x, bool) or not isinstance(x, Integral) for x in values):
+        return False
+    if sorted(permutation) != list(range(n)):
+        return False
+    # Explicit Python-int operations avoid trusting fixed-width arithmetic
+    # when verifying an externally supplied, possibly malicious certificate.
+    primal = sum(int(matrix[i, p]) for i, p in enumerate(permutation))
+    dual = sum(map(int, u)) + sum(map(int, v))
+    if primal != int(certificate.scaled_objective) or primal != dual:
+        return False
+    return all(int(u[i]) + int(v[p]) <= int(matrix[i, p])
+               for i in range(n) for p in range(n))
+
+
+def certified_lattice_assignment(costs):
+    """Return a minimum assignment and an exact independently checkable proof.
+
+    For candidate permutation p define d[i,j] = C[i,p[j]]-C[i,p[i]].
+    A minimum matching has no negative alternating cycle. Synchronous
+    Bellman--Ford from an implicit zero-cost source finds potentials t with
+    t[j]-t[i] <= d[i,j]. Set u[i]=C[i,p[i]]-t[i], v[p[i]]=t[i].
+
+    With n<=512 and |C|<=2**40, each n-edge path has magnitude <=2**50;
+    all intermediate distance/difference additions fit signed int64. The
+    independent verifier uses unbounded Python integers. A bad LAP candidate
+    is refused rather than returned as an unsafe pruning bound.
+    """
+    matrix = scaled_lattice_costs(costs)
+    n = len(matrix)
+    if not n:
+        return AssignmentCertificate((), (), (), 0)
+    rows, permutation = linear_sum_assignment(np.asarray(costs, dtype=float))
+    if list(rows) != list(range(n)) or sorted(permutation.tolist()) != list(range(n)):
+        raise ArithmeticError("LAP returned an invalid permutation")
+    matched = matrix[np.arange(n), permutation]
+    edges = matrix[:, permutation] - matched[:, None]
+    potentials = np.zeros(n, dtype=np.int64)
+    for _ in range(n-1):
+        updated = np.minimum(potentials, np.min(potentials[:, None] + edges, axis=0))
+        if np.array_equal(updated, potentials):
+            break
+        potentials = updated
+    row_dual = matched - potentials
+    column_dual = np.empty(n, dtype=np.int64)
+    column_dual[permutation] = potentials
+    certificate = AssignmentCertificate(
+        tuple(map(int, permutation)), tuple(map(int, row_dual)),
+        tuple(map(int, column_dual)), sum(map(int, matched)))
+    if not verify_assignment_certificate(costs, certificate):
+        raise ArithmeticError("LAP candidate failed exact primal-dual verification")
+    return certificate

synkit/Chem/Mapper/solvers/exact/assignment/assignment_domains.py

@@ -0,0 +1,162 @@
+"""Reversible assignment domains and exact AllDifferent support filtering.
+
+For balanced domains, an unmatched edge belongs to a perfect matching exactly
+when it lies on an alternating cycle. Strong components in the graph of matched
+rows identify these cycles. Filtering uses no bond-preservation assumption.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.sparse import csr_matrix
+from scipy.sparse.csgraph import connected_components, maximum_bipartite_matching
+
+
+def bits(mask):
+    """Yield set-bit indices without allocating a full Boolean vector."""
+    while mask:
+        bit = mask & -mask
+        yield bit.bit_length() - 1
+        mask ^= bit
+
+
+class AssignmentDomains:
+    """Candidate image bitsets with a reversible change trail."""
+
+    def __init__(self, masks):
+        self.masks = list(map(int, masks))
+        self.trail = []
+        self._supported_state = None
+
+    def checkpoint(self):
+        """Return a token for exact restoration after a child search."""
+        return len(self.trail)
+
+    def intersect(self, row, permitted):
+        """Restrict one domain and record only actual changes."""
+        previous = self.masks[row]
+        updated = previous & int(permitted)
+        if updated != previous:
+            self.trail.append((row, previous))
+            self.masks[row] = updated
+        return previous.bit_count() - updated.bit_count()
+
+    def restore(self, token):
+        """Restore all domains changed since a checkpoint."""
+        while len(self.trail) > token:
+            row, previous = self.trail.pop()
+            self.masks[row] = previous
+
+    def matrix(self, rows, columns):
+        """Return the current residual bipartite adjacency matrix."""
+        if not rows:
+            return np.empty((0, len(columns)), dtype=bool)
+        extent = max(
+            max(self.masks[row].bit_length() for row in rows),
+            max(columns, default=-1) + 1,
+        )
+        width = max(1, (extent + 7) // 8)
+        data = b"".join(self.masks[row].to_bytes(width, "little") for row in rows)
+        packed = np.frombuffer(data, dtype=np.uint8).reshape(len(rows), width)
+        return np.unpackbits(packed, axis=1, bitorder="little")[:, columns].astype(bool)
+
+    def _balanced_blocks(self, rows):
+        """Recognize disjoint complete bipartite blocks with perfect support."""
+        blocks = {}
+        for row in rows:
+            mask = self.masks[row]
+            blocks[mask] = blocks.get(mask, 0) + 1
+        union = 0
+        for mask, count in blocks.items():
+            if mask.bit_count() != count or union & mask:
+                return False
+            union |= mask
+        return True
+
+    def restrict_matrix(self, rows, columns, allowed):
+        """Convert a residual Boolean domain matrix to global bitsets in bulk."""
+        extent = max(columns, default=-1) + 1
+        images = np.zeros((len(rows), extent), dtype=bool)
+        images[:, columns] = allowed
+        packed = np.packbits(images, axis=1, bitorder="little")
+        return sum(
+            self.intersect(row, int.from_bytes(packed[i].tobytes(), "little"))
+            for i, row in enumerate(rows)
+        )
+
+    def propagate(self, rows, available, *, full=True, matching=None, cache=True):
+        """Remove unsupported edges, returning feasibility and removed count.
+
+        Singleton propagation precedes a Hopcroft--Karp matching. The stronger
+        mode then removes edges outside every perfect matching using alternating
+        strong components. A False result is an exact Hall infeasibility claim.
+        """
+        signature = (
+            tuple(rows),
+            int(available),
+            tuple(self.masks[row] for row in rows),
+        )
+        if full and cache and signature == self._supported_state:
+            return True, 0
+        feasible, removed = self._propagate(
+            rows, available, full=full, matching=matching
+        )
+        if full and cache and feasible:
+            self._supported_state = (
+                tuple(rows),
+                int(available),
+                tuple(self.masks[row] for row in rows),
+            )
+        return feasible, removed
+
+    def _propagate(self, rows, available, *, full, matching):
+        """Perform singleton filtering followed by optional perfect support."""
+        removed = sum(self.intersect(row, available) for row in rows)
+        pending = [row for row in rows if self.masks[row].bit_count() == 1]
+        processed = set()
+        while pending:
+            row = pending.pop()
+            if row in processed:
+                continue
+            processed.add(row)
+            singleton = self.masks[row]
+            for other in rows:
+                if other == row or not self.masks[other] & singleton:
+                    continue
+                removed += self.intersect(other, ~singleton)
+                if not self.masks[other]:
+                    return False, removed
+                if self.masks[other].bit_count() == 1:
+                    pending.append(other)
+        if any(not self.masks[row] for row in rows):
+            return False, removed
+        if not rows or not full:
+            return True, removed
+        columns = list(bits(available))
+        if len(rows) != len(columns):
+            return False, removed
+        # Disjoint balanced complete blocks need no matching/SCC calculation.
+        # This is common after atom-type or attained-profile filtering.
+        if self._balanced_blocks(rows):
+            return True, removed
+        feasible, filtered = self._filter_support(rows, columns, matching)
+        return feasible, removed + filtered
+
+    def _filter_support(self, rows, columns, matching):
+        """Keep precisely the edges supported by a residual perfect matching."""
+        allowed = self.matrix(rows, columns)
+        if matching is None or not allowed[np.arange(len(rows)), matching].all():
+            matching = maximum_bipartite_matching(
+                csr_matrix(allowed), perm_type="column"
+            )
+        matching = np.asarray(matching, dtype=int)
+        if np.any(matching < 0):
+            return False, 0
+        owner = np.empty(len(rows), dtype=int)
+        owner[matching] = np.arange(len(rows))
+        _, component = connected_components(
+            csr_matrix(allowed[:, matching]), directed=True, connection="strong"
+        )
+        supported = allowed & (component[:, None] == component[owner][None, :])
+        removed = self.restrict_matrix(rows, columns, supported)
+        return True, removed

synkit/Chem/Mapper/solvers/exact/assignment/assignment_verification.py

@@ -0,0 +1,58 @@
+"""Independent bounded-integer verification of supported-domain LAP proofs."""
+
+from numbers import Integral
+
+import numpy as np
+
+from .assignment_certificate import AssignmentCertificate
+
+
+def verify_supported_assignment(costs, allowed, certificate):
+    """Verify primal/dual equality and every allowed-edge dual inequality.
+
+    Matrix entries are at most 2**40 and potentials at most 2**50 in absolute
+    value; their differences fit int64. Objective sums use Python integers.
+    Unsupported edges do not constrain this domain-restricted assignment.
+    """
+    matrix = np.asarray(costs)
+    domain = np.asarray(allowed, dtype=bool)
+    if (
+        matrix.ndim != 2
+        or matrix.shape[0] != matrix.shape[1]
+        or domain.shape != matrix.shape
+    ):
+        return False
+    n = len(matrix)
+    if (
+        n > 512
+        or matrix.dtype.kind not in "iu"
+        or np.any(matrix < 0)
+        or np.max(matrix, initial=0) > 2**40
+    ):
+        return False
+    if not isinstance(certificate, AssignmentCertificate):
+        return False
+    p, u, v = (
+        certificate.permutation,
+        certificate.row_potentials,
+        certificate.column_potentials,
+    )
+    if any(not isinstance(values, tuple) or len(values) != n for values in (p, u, v)):
+        return False
+    values = (*p, *u, *v, certificate.scaled_objective)
+    if any(isinstance(x, bool) or not isinstance(x, Integral) for x in values):
+        return False
+    if sorted(p) != list(range(n)) or any(abs(int(x)) > 2**50 for x in (*u, *v)):
+        return False
+    if not domain[np.arange(n), p].all():
+        return False
+    primal = sum(int(matrix[i, j]) for i, j in enumerate(p))
+    dual = sum(map(int, u)) + sum(map(int, v))
+    if primal != int(certificate.scaled_objective) or primal != dual:
+        return False
+    reduced = (
+        matrix.astype(np.int64)
+        - np.asarray(u, dtype=np.int64)[:, None]
+        - np.asarray(v, dtype=np.int64)[None, :]
+    )
+    return bool(np.all(reduced[domain] >= 0))