synkit 1.6.5__py3-none-win_amd64.whl

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

@@ -0,0 +1,247 @@
+"""Exact integer assignments with inherited, repaired primal--dual state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.sparse import csr_matrix
+from scipy.sparse.csgraph import connected_components
+
+from .assignment_certificate import AssignmentCertificate
+from .assignment_verification import verify_supported_assignment
+from ..pabs.propagation_limits import check_deadline
+
+
+@dataclass(frozen=True)
+class AssignmentState:
+    """Certified residual matching; costs and potentials are scaled by four."""
+
+    rows: tuple[int, ...]
+    columns: tuple[int, ...]
+    certificate: AssignmentCertificate
+    augmentations: int
+    inherited_edges: int
+
+    @property
+    def lower_bound(self):
+        """Return the exact integer objective of this residual assignment."""
+        return self.certificate.scaled_objective
+
+
+def _initial_state(costs, rows, columns, parent):
+    n = len(costs)
+    v = np.zeros(n, dtype=np.int64)
+    old_matches = {}
+    if parent is not None:
+        prior = parent.certificate
+        old_columns = dict(zip(parent.columns, prior.column_potentials))
+        v[:] = [old_columns.get(image, 0) for image in columns]
+        old_matches = {
+            row: parent.columns[prior.permutation[i]]
+            for i, row in enumerate(parent.rows)
+        }
+    # Repair feasibility after arbitrary residual cost changes. Old potentials
+    # are suggestions; each new row minimum restores u[i]+v[j] <= C[i,j].
+    u = np.min(costs - v[None, :], axis=1)
+    p = np.full(n, -1, dtype=int)
+    positions = {image: j for j, image in enumerate(columns)}
+    inherited = 0
+    for i, row in enumerate(rows):
+        j = positions.get(old_matches.get(row))
+        if j is not None and p[j] < 0 and costs[i, j] == u[i] + v[j]:
+            p[j] = i
+            inherited += 1
+    return u, v, p, inherited
+
+
+def _augment(costs, u, v, p, root, deadline=None):
+    """Hungarian shortest augmenting path from one unmatched row."""
+    n = len(costs)
+    infinity = np.int64(2**60)
+    slack = np.full(n, infinity, dtype=np.int64)
+    predecessor = np.full(n, -1, dtype=int)
+    used = np.zeros(n, dtype=bool)
+    row, previous = root, -1
+    while True:
+        check_deadline(deadline)
+        reduced = costs[row] - u[row] - v
+        improve = ~used & (reduced < slack)
+        slack[improve] = reduced[improve]
+        predecessor[improve] = previous
+        image = int(np.argmin(np.where(used, infinity, slack)))
+        delta = int(slack[image])
+        u[root] += delta
+        if used.any():
+            u[p[used]] += delta
+            v[used] -= delta
+        slack[~used] -= delta
+        used[image] = True
+        if p[image] < 0:
+            break
+        row, previous = int(p[image]), image
+    while image >= 0:
+        previous = int(predecessor[image])
+        p[image] = root if previous < 0 else p[previous]
+        image = previous
+
+
+def solve_assignment(costs, allowed, rows, columns, parent=None, *, deadline=None):
+    """Solve a nonnegative integer LAP and independently check its certificate.
+
+    Unsupported edges get a finite penalty above every all-supported matching.
+    A returned None means no supported perfect matching exists. The bounded
+    matrix and potential range keeps all working integer operations exact.
+    """
+    check_deadline(deadline)
+    original = np.asarray(costs)
+    if original.dtype.kind not in "iu":
+        raise ValueError("Assignment costs must be exact integers")
+    costs = original.astype(np.int64)
+    allowed = np.asarray(allowed, dtype=bool)
+    n = len(rows)
+    if costs.shape != (n, n) or allowed.shape != costs.shape or len(columns) != n:
+        raise ValueError("Residual assignment must be square")
+    if np.any(costs < 0) or np.max(costs, initial=0) > 2**30 or n > 512:
+        raise ValueError("Synister-CP assignment exceeds its exact integer domain")
+    if not n:
+        return AssignmentState((), (), AssignmentCertificate((), (), (), 0), 0, 0)
+    penalty = (n + 1) * int(costs.max(initial=0)) + 1
+    matrix = np.where(allowed, costs, penalty)
+    u, v, p, inherited = _initial_state(matrix, rows, columns, parent)
+    augmentations = 0
+    for row in range(n):
+        check_deadline(deadline)
+        if row not in p:
+            _augment(matrix, u, v, p, row, deadline)
+            augmentations += 1
+    permutation = np.empty(n, dtype=int)
+    permutation[p] = np.arange(n)
+    if not allowed[np.arange(n), permutation].all():
+        return None
+    certificate = AssignmentCertificate(
+        tuple(map(int, permutation)),
+        tuple(map(int, u)),
+        tuple(map(int, v)),
+        sum(int(matrix[i, j]) for i, j in enumerate(permutation)),
+    )
+    if not verify_supported_assignment(costs, allowed, certificate):
+        raise ArithmeticError(
+            "Synister-CP assignment failed independent integer verification"
+        )
+    return AssignmentState(
+        tuple(rows), tuple(columns), certificate, augmentations, inherited
+    )
+
+
+def reduced_cost_filter(costs, allowed, state, budget):
+    """Keep every edge whose certified forced-cost lower bound fits the budget."""
+    certificate = state.certificate
+    reduced = (
+        costs
+        - np.asarray(certificate.row_potentials)[:, None]
+        - np.asarray(certificate.column_potentials)[None, :]
+    )
+    return allowed & (state.lower_bound + reduced <= budget)
+
+
+def cycle_edge_lower_bounds(costs, allowed, state, *, deadline=None):
+    """Certify forced-edge LAP costs by minimum alternating completion cycles.
+
+    Relative to the certified matching, reduced-cost arcs are nonnegative.
+    Forcing i to the column owned by j needs a path from j back to i. A
+    completed all-pairs shortest-path calculation gives the exact forced LAP
+    optimum. Interrupted calculations are never used to prune.
+    """
+    certificate = state.certificate
+    permutation = np.asarray(certificate.permutation, dtype=int)
+    reduced = (
+        costs[:, permutation]
+        - np.asarray(certificate.row_potentials)[:, None]
+        - np.asarray(certificate.column_potentials)[permutation][None, :]
+    )
+    domain = allowed[:, permutation]
+    if np.any(reduced[domain] < 0):
+        raise ArithmeticError(
+            "Forced-edge calculation requires a feasible assignment dual"
+        )
+    # <=512 vertices, |potentials|<=2**50: every simple finite path <2**61.
+    infinity = np.int64(2**61)
+    arcs = np.where(domain, reduced, infinity)
+    _, component = connected_components(
+        csr_matrix(domain), directed=True, connection="strong"
+    )
+    distances = np.full_like(arcs, infinity)
+    for label in np.unique(component):
+        vertices = np.flatnonzero(component == label)
+        local = arcs[np.ix_(vertices, vertices)].copy()
+        for pivot in range(len(vertices)):
+            check_deadline(deadline)
+            local = np.minimum(
+                local, local[:, pivot, None] + local[pivot, None, :]
+            )
+        distances[np.ix_(vertices, vertices)] = local
+    result = np.empty_like(costs)
+    result[:, permutation] = state.lower_bound + arcs + distances.T
+    return result
+
+
+def solve_partitioned_assignment(
+    costs,
+    allowed,
+    rows,
+    columns,
+    row_labels,
+    column_labels,
+    parent=None,
+    *,
+    deadline=None,
+):
+    """Solve independent atom-type blocks and verify their combined certificate."""
+    groups = {}
+    for i, label in enumerate(row_labels):
+        groups.setdefault(label, ([], []))[0].append(i)
+    for j, label in enumerate(column_labels):
+        groups.setdefault(label, ([], []))[1].append(j)
+    if len(groups) <= 1:
+        return solve_assignment(
+            costs, allowed, rows, columns, parent, deadline=deadline
+        )
+    n = len(rows)
+    permutation, u, v = [0] * n, [0] * n, [0] * n
+    augmentations = inherited = 0
+    for left, right in groups.values():
+        check_deadline(deadline)
+        if len(left) != len(right):
+            return None
+        state = solve_assignment(
+            costs[np.ix_(left, right)],
+            allowed[np.ix_(left, right)],
+            tuple(rows[i] for i in left),
+            tuple(columns[j] for j in right),
+            parent,
+            deadline=deadline,
+        )
+        if state is None:
+            return None
+        certificate = state.certificate
+        for i, position in enumerate(left):
+            permutation[position] = right[certificate.permutation[i]]
+            u[position] = certificate.row_potentials[i]
+        for j, position in enumerate(right):
+            v[position] = certificate.column_potentials[j]
+        augmentations += state.augmentations
+        inherited += state.inherited_edges
+    certificate = AssignmentCertificate(
+        tuple(permutation),
+        tuple(u),
+        tuple(v),
+        sum(int(costs[i, j]) for i, j in enumerate(permutation)),
+    )
+    if not verify_supported_assignment(costs, allowed, certificate):
+        raise ArithmeticError(
+            "Combined assignment blocks failed independent verification"
+        )
+    return AssignmentState(
+        tuple(rows), tuple(columns), certificate, augmentations, inherited
+    )

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

@@ -0,0 +1,128 @@
+"""
+Optimality certificates and gap reporting.
+
+A :class:`Certificate` pairs the cost of a concrete mapping (an *upper bound* on
+the optimal chemical distance) with an admissible *lower bound*, and reports the
+gap between them. When the gap is zero the mapping is *proven optimal*:
+
+* ``method="dual-lap"`` -- the lower bound is the Gilmore-Lawler / dual-LAP
+  relaxation (:func:`mapper.slap.lap.dual_lap_lower_bound`). A zero gap means the
+  cheap relaxation already certifies optimality; a positive gap is honest about
+  the relaxation not being tight, *not* about the mapping being suboptimal.
+* ``method="milp-exact"`` -- the lower bound equals the optimum returned by the
+  exact MILP/QAP solver (:mod:`mapper.exact.milp`), which CBC proves optimal, so
+  the gap is zero by construction.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..slap.lap import dual_lap_lower_bound, chemical_distance, recover_mapping
+
+# Costs are integer/half-integer in cd units; this tolerance absorbs float noise.
+_TOL = 1e-6
+
+
+@dataclass
+class Certificate:
+    """Optimality certificate for a single mapping.
+
+    :ivar upper_bound: Cost of the concrete mapping (chemical distance, cd units).
+    :vartype upper_bound: float
+    :ivar lower_bound: Admissible lower bound on the optimal chemical distance.
+    :vartype lower_bound: float
+    :ivar method: How ``lower_bound`` was obtained (``"dual-lap"`` or ``"milp-exact"``).
+    :vartype method: str
+    """
+
+    upper_bound: float
+    lower_bound: float
+    method: str = "dual-lap"
+
+    @property
+    def gap(self) -> float:
+        """Optimality gap ``upper_bound - lower_bound`` (>= 0)."""
+        return self.upper_bound - self.lower_bound
+
+    @property
+    def proven_optimal(self) -> bool:
+        """True iff the lower bound certifies the mapping is optimal."""
+        import math
+
+        return math.isfinite(self.lower_bound) and self.gap <= _TOL
+
+    def __str__(self) -> str:
+        status = "PROVEN OPTIMAL" if self.proven_optimal else "not certified"
+        return (
+            f"Certificate(cost={self.upper_bound:g}, "
+            f"lower_bound={self.lower_bound:g}, gap={self.gap:g}, "
+            f"method={self.method!r}) -> {status}"
+        )
+
+
+def certify_result(result, binary, method="dual-lap"):
+    """Build and attach a :class:`Certificate` to a single result dict.
+
+    Uses the result's ``"cd"`` as the incumbent upper bound (falling back to a
+    recomputed chemical distance) and the dual-LAP lower bound. The certificate
+    is stored under ``result["certificate"]`` and returned.
+
+    :param result: A result entry with ``"lgp"`` and (optionally) ``"cd"``.
+    :type result: dict
+    :param binary: Whether bond orders are binarised (matches the matcher's ``binary``).
+    :type binary: bool
+    :param method: Lower-bound provenance label.
+    :type method: str, optional
+
+    :rtype: Certificate
+    """
+    lgp = result["lgp"]
+    if "cd" in result:
+        ub = float(result["cd"])
+    else:
+        ub = chemical_distance(lgp, recover_mapping(lgp), binary)
+    lb = dual_lap_lower_bound(lgp, binary)
+    cert = Certificate(upper_bound=ub, lower_bound=lb, method=method)
+    result["certificate"] = cert
+    return cert
+
+
+def certify_results_exact(results, binary):
+    """Attach exact (MILP/QAP) certificates to a set of optimal results.
+
+    The uncertainty-region kernel is extracted from the results and solved to
+    proven optimality with the MILP/QAP solver. The proven kernel optimum becomes
+    the lower bound for every result, so results whose cost equals it are
+    certified optimal over the uncertainty region (``method="milp-exact"``).
+
+    Falls back to the dual-LAP certificate when PuLP is unavailable or the kernel
+    is degenerate.
+
+    :param results: Optimal results sharing a common reaction (each with ``"lgp"``/``"cd"``).
+    :type results: list[dict]
+    :param binary: Whether bond orders are binarised.
+    :type binary: bool
+    """
+    if not results:
+        return
+
+    from .kernel_solvers.kernel import extract_kernel
+    from .kernel_solvers.milp import solve_kernel_milp, HAS_PULP
+
+    if not HAS_PULP:
+        for r in results:
+            certify_result(r, binary)
+        return
+
+    lgp = results[0]["lgp"]
+    kernel = extract_kernel(results, lgp, binary=binary)
+    sol = solve_kernel_milp(kernel)
+    lb = sol.cost
+    method = "milp-exact" if sol.proven_optimal else "milp"
+    for r in results:
+        if "cd" in r:
+            ub = float(r["cd"])
+        else:
+            ub = chemical_distance(r["lgp"], recover_mapping(r["lgp"]), binary)
+        r["certificate"] = Certificate(upper_bound=ub, lower_bound=lb, method=method)

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

@@ -0,0 +1,183 @@
+"""Reference-ITS component reduction for staged exact AAM enumeration.
+
+The reduction is intentionally explicit about scope.  Given a *known* mapped
+reaction (or any trusted seed mapping), it keeps every connected component of
+the union ITS that contains a changed heavy-atom bond, H-count change, or charge
+change.  Completely unchanged disconnected components are fixed to the seed
+mapping and can subsequently be represented by endpoint automorphism orbits.
+
+This is exact for the seed-conditioned active-component space and is useful for
+reference-AAM reproduction.  It is not an unrestricted proof over mappings that
+exchange atoms between active and inactive components; callers must not label it
+as the complete atom-compatible CD shell.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+import numpy as np
+
+from ...graph.labeled_graph import LabeledGraph
+from ..slap.lap import _adjacency_and_elements
+
+
+def _node_property(lg, name, default=0):
+    values = lg.props.get(name)
+    if values is None:
+        return [default] * len(lg.labels)
+    if len(values) != len(lg.labels):
+        raise ValueError(f"{name} must contain one value per graph atom")
+    return list(values)
+
+
+def _induced_labeled_graph(lg, nodes):
+    nodes = tuple(nodes)
+    position = {node: index for index, node in enumerate(nodes)}
+    graph = {index: {} for index in range(len(nodes))}
+    for source in nodes:
+        for target, weight in lg.graph.get(source, {}).items():
+            if target in position:
+                graph[position[source]][position[target]] = weight
+    reduced = LabeledGraph(graph, [lg.labels[node] for node in nodes])
+    for name in ("atomic numbers", "hcounts", "charges"):
+        values = lg.props.get(name)
+        if values is not None:
+            reduced.set_prop(name, [values[node] for node in nodes])
+    return reduced
+
+
+def _union_components(reactant, mapped_product):
+    size = reactant.shape[0]
+    neighbours = [set() for _ in range(size)]
+    for left in range(size):
+        for right in range(left + 1, size):
+            if reactant[left, right] != 0 or mapped_product[left, right] != 0:
+                neighbours[left].add(right)
+                neighbours[right].add(left)
+    components = []
+    unseen = set(range(size))
+    while unseen:
+        root = min(unseen)
+        component = set()
+        pending = [root]
+        while pending:
+            node = pending.pop()
+            if node in component:
+                continue
+            component.add(node)
+            pending.extend(neighbours[node] - component)
+        unseen.difference_update(component)
+        components.append(frozenset(component))
+    return tuple(components)
+
+
+@dataclass(frozen=True)
+class ITSComponentReduction:
+    """A seed-conditioned active ITS problem and its exact lifting map."""
+
+    lgp: tuple[LabeledGraph, LabeledGraph]
+    reference_mapping: tuple[int, ...]
+    reactant_atoms: tuple[int, ...]
+    product_atoms: tuple[int, ...]
+    inactive_atoms: tuple[int, ...]
+    fixed_mapping: tuple[int, ...]
+    changed_atoms: tuple[int, ...]
+    heavy_distance: float
+    hydrogen_distance: int
+    scope: str = "reference_active_its_component_space"
+
+    def lift(self, core_mapping) -> list[int]:
+        """Lift one reduced mapping while retaining the seed outside the ITS core."""
+        core_mapping = tuple(int(image) for image in core_mapping)
+        size = len(self.reactant_atoms)
+        if sorted(core_mapping) != list(range(size)):
+            raise ValueError("core_mapping must be a complete reduced permutation")
+        lifted = list(self.fixed_mapping)
+        for position, reactant_atom in enumerate(self.reactant_atoms):
+            lifted[reactant_atom] = self.product_atoms[core_mapping[position]]
+        return lifted
+
+
+def reduce_to_reference_its_components(
+    lgp,
+    reference_mapping,
+    *,
+    binary=False,
+    tolerance=1e-9,
+) -> ITSComponentReduction:
+    """Keep union-ITS components changed by a trusted reference mapping.
+
+    Hydrogens remain implicit.  Per-heavy-atom H counts are carried in the
+    reduced graph metadata and H-count changes participate in reaction-center
+    selection.  ``hydrogen_distance`` is the L1 H-count discrepancy induced by
+    the seed heavy-atom mapping; it is the minimum explicit H--parent bond-edit
+    contribution when the two hydrogen inventories are balanced.
+    """
+    reactant, reactant_elements = _adjacency_and_elements(lgp[0], binary)
+    product, product_elements = _adjacency_and_elements(lgp[1], binary)
+    if reactant.shape != product.shape:
+        raise ValueError("reactant and product must contain the same atom count")
+    size = reactant.shape[0]
+    mapping = tuple(int(image) for image in reference_mapping)
+    if sorted(mapping) != list(range(size)):
+        raise ValueError("reference_mapping must be a complete permutation")
+    if any(
+        reactant_elements[atom] != product_elements[image]
+        for atom, image in enumerate(mapping)
+    ):
+        raise ValueError("reference_mapping must preserve atom types")
+
+    images = np.asarray(mapping, dtype=int)
+    mapped_product = product[images[:, None], images[None, :]]
+    changed = set()
+    for left in range(size):
+        for right in range(left + 1, size):
+            if not math.isclose(
+                float(reactant[left, right]),
+                float(mapped_product[left, right]),
+                abs_tol=tolerance,
+                rel_tol=0.0,
+            ):
+                changed.update((left, right))
+
+    h_r = _node_property(lgp[0], "hcounts")
+    h_p = _node_property(lgp[1], "hcounts")
+    charge_r = _node_property(lgp[0], "charges")
+    charge_p = _node_property(lgp[1], "charges")
+    hydrogen_distance = 0
+    for atom, image in enumerate(mapping):
+        h_delta = abs(int(h_r[atom]) - int(h_p[image]))
+        hydrogen_distance += h_delta
+        if h_delta or charge_r[atom] != charge_p[image]:
+            changed.add(atom)
+
+    components = _union_components(reactant, mapped_product)
+    active = (
+        set().union(*(component for component in components if component & changed))
+        if changed
+        else set()
+    )
+    reactant_atoms = tuple(sorted(active))
+    product_atoms = tuple(mapping[atom] for atom in reactant_atoms)
+    inactive_atoms = tuple(atom for atom in range(size) if atom not in active)
+    reduced_pair = (
+        _induced_labeled_graph(lgp[0], reactant_atoms),
+        _induced_labeled_graph(lgp[1], product_atoms),
+    )
+    heavy_distance = 0.5 * float(np.abs(reactant - mapped_product).sum())
+    return ITSComponentReduction(
+        lgp=reduced_pair,
+        reference_mapping=tuple(range(len(reactant_atoms))),
+        reactant_atoms=reactant_atoms,
+        product_atoms=product_atoms,
+        inactive_atoms=inactive_atoms,
+        fixed_mapping=mapping,
+        changed_atoms=tuple(sorted(changed)),
+        heavy_distance=heavy_distance,
+        hydrogen_distance=hydrogen_distance,
+    )
+
+
+__all__ = ["ITSComponentReduction", "reduce_to_reference_its_components"]

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

@@ -0,0 +1 @@
+"""Full-space distance enumeration, replay certificates, and small-graph exhaustive search."""