synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/solvers/exact/pabs/separator_spectrum.py

@@ -0,0 +1,308 @@
+"""Bounded separator cost spectra with exact mapping backtracking.
+
+The spectrum dynamic program stores reachable quarter-unit costs and split
+backpointers. It reconstructs only mappings in the requested shell. A state
+budget makes this an optional residual strategy; callers can fall back to the
+ordinary complete assignment search if preparation exceeds that budget.
+"""
+
+from __future__ import annotations
+
+import itertools
+
+import numpy as np
+
+from .propagation_limits import check_deadline
+from .separator_bound import _find_separator
+
+
+class _StateLimit(Exception):
+    pass
+
+
+class SeparatorCostSpectrum:
+    """Exact target-shell enumerator for a bounded residual QAP."""
+
+    def __init__(
+        self,
+        a,
+        b,
+        rows,
+        columns,
+        unary,
+        allowed,
+        *,
+        deadline=None,
+        max_separator_size=2,
+        max_states=20_000,
+        base_case=4,
+        max_cost=None,
+    ):
+        self.a = np.asarray(a, dtype=np.int64)
+        self.b = np.asarray(b, dtype=np.int64)
+        self.rows, self.columns = tuple(rows), tuple(columns)
+        self.unary = np.asarray(unary, dtype=np.int64)
+        self.allowed = np.asarray(allowed, dtype=bool)
+        self.deadline = deadline
+        self.max_separator_size = max_separator_size
+        self.max_states = max_states
+        self.base_case = base_case
+        self.max_cost = None if max_cost is None else int(max_cost)
+        self.adjacency = self.a != 0
+        self.states = 0
+        self.memo = {}
+        self._prepared = False
+        self._prepare_failed = False
+        if (
+            len(self.rows) != len(self.columns)
+            or self.unary.shape
+            != (
+                len(self.rows),
+                len(self.columns),
+            )
+            or self.allowed.shape != self.unary.shape
+        ):
+            raise ValueError("residual arrays must be square and match row/column sets")
+        if np.any(self.unary < 0):
+            raise ValueError("separator spectra require nonnegative unary costs")
+
+    def has_separator(self):
+        """Whether the root has a balanced separator suitable for recursion."""
+        return bool(
+            self.rows
+            and len(self.rows) > self.base_case
+            and _find_separator(
+                self.rows, self.adjacency, self.max_separator_size, 2 / 3
+            )
+        )
+
+    def _tick(self):
+        check_deadline(self.deadline)
+        self.states += 1
+        if self.states > self.max_states:
+            raise _StateLimit
+
+    @staticmethod
+    def _key(rows, columns, unary, allowed, max_cost):
+        return (
+            tuple(rows),
+            tuple(columns),
+            max_cost,
+            np.ascontiguousarray(unary, dtype=np.int64).tobytes(),
+            np.ascontiguousarray(allowed, dtype=np.uint8).tobytes(),
+        )
+
+    def _pair(self, i, k, j, image):
+        return abs(int(self.a[i, k]) - int(self.b[j, image]))
+
+    def _leaf(self, rows, columns, unary, allowed, max_cost):
+        spectrum = set()
+        branches = []
+        n = len(rows)
+        for permutation in itertools.permutations(range(n)):
+            self._tick()
+            if any(not allowed[i, permutation[i]] for i in range(n)):
+                continue
+            value = sum(int(unary[i, permutation[i]]) for i in range(n))
+            for i in range(n):
+                for k in range(i + 1, n):
+                    value += self._pair(
+                        rows[i],
+                        rows[k],
+                        columns[permutation[i]],
+                        columns[permutation[k]],
+                    )
+            if max_cost is not None and value > max_cost:
+                continue
+            spectrum.add(value)
+            branches.append(("leaf", value, tuple(columns[p] for p in permutation)))
+        return frozenset(spectrum), branches
+
+    def _state(self, rows, columns, unary, allowed, max_cost):  # noqa: C901
+        self._tick()
+        key = self._key(rows, columns, unary, allowed, max_cost)
+        cached = self.memo.get(key)
+        if cached is not None:
+            return key, cached[0]
+        n = len(rows)
+        if max_cost is not None and max_cost < 0:
+            self.memo[key] = (frozenset(), [])
+            return key, frozenset()
+        if n <= self.base_case:
+            spectrum, branches = self._leaf(rows, columns, unary, allowed, max_cost)
+            self.memo[key] = (spectrum, branches)
+            return key, spectrum
+        found = _find_separator(rows, self.adjacency, self.max_separator_size, 2 / 3)
+        if found is None:
+            spectrum, branches = self._leaf(rows, columns, unary, allowed, max_cost)
+            self.memo[key] = (spectrum, branches)
+            return key, spectrum
+
+        separator, (left_rows, right_rows) = found
+        separator_positions = [rows.index(i) for i in separator]
+        branches = []
+        spectrum = set()
+        column_positions = {image: position for position, image in enumerate(columns)}
+        for chosen in itertools.permutations(columns, len(separator)):
+            self._tick()
+            if any(
+                not allowed[position, column_positions[image]]
+                for position, image in zip(separator_positions, chosen)
+            ):
+                continue
+            chosen_map = dict(zip(separator, chosen))
+            offset = sum(
+                int(unary[position, column_positions[chosen_map[row]]])
+                for position, row in zip(separator_positions, separator)
+            )
+            for left_index, row in enumerate(separator):
+                for other in separator[left_index + 1 :]:
+                    offset += self._pair(row, other, chosen_map[row], chosen_map[other])
+            free_columns = tuple(image for image in columns if image not in set(chosen))
+            left_positions = [rows.index(i) for i in left_rows]
+            right_positions = [rows.index(i) for i in right_rows]
+            for left_columns in itertools.combinations(free_columns, len(left_rows)):
+                self._tick()
+                left_column_set = set(left_columns)
+                right_columns = tuple(
+                    i for i in free_columns if i not in left_column_set
+                )
+                left_costs = (
+                    np.asarray(
+                        [
+                            [unary[x, column_positions[j]] for j in left_columns]
+                            for x in left_positions
+                        ],
+                        dtype=np.int64,
+                    )
+                    .reshape(len(left_rows), len(left_columns))
+                    .copy()
+                )
+                right_costs = (
+                    np.asarray(
+                        [
+                            [unary[x, column_positions[j]] for j in right_columns]
+                            for x in right_positions
+                        ],
+                        dtype=np.int64,
+                    )
+                    .reshape(len(right_rows), len(right_columns))
+                    .copy()
+                )
+                left_allowed = np.asarray(
+                    [
+                        [allowed[x, column_positions[j]] for j in left_columns]
+                        for x in left_positions
+                    ],
+                    dtype=bool,
+                ).reshape(len(left_rows), len(left_columns))
+                right_allowed = np.asarray(
+                    [
+                        [allowed[x, column_positions[j]] for j in right_columns]
+                        for x in right_positions
+                    ],
+                    dtype=bool,
+                ).reshape(len(right_rows), len(right_columns))
+                for x, source in enumerate(left_rows):
+                    for y, image in enumerate(left_columns):
+                        left_costs[x, y] += sum(
+                            self._pair(source, sep, image, chosen_map[sep])
+                            for sep in separator
+                        )
+                for x, source in enumerate(right_rows):
+                    for y, image in enumerate(right_columns):
+                        right_costs[x, y] += sum(
+                            self._pair(source, sep, image, chosen_map[sep])
+                            for sep in separator
+                        )
+                cut = sum(
+                    abs(int(self.b[j, k])) for j in left_columns for k in right_columns
+                )
+                branch_offset = offset + cut
+                child_limit = None if max_cost is None else max_cost - branch_offset
+                if child_limit is not None and child_limit < 0:
+                    continue
+                left_key, left_spectrum = self._state(
+                    left_rows, left_columns, left_costs, left_allowed, child_limit
+                )
+                if not left_spectrum:
+                    continue
+                right_key, right_spectrum = self._state(
+                    right_rows, right_columns, right_costs, right_allowed, child_limit
+                )
+                if not right_spectrum:
+                    continue
+                branches.append(
+                    (
+                        "split",
+                        branch_offset,
+                        tuple(chosen_map.items()),
+                        left_key,
+                        right_key,
+                    )
+                )
+                spectrum.update(
+                    branch_offset + first + second
+                    for first in left_spectrum
+                    for second in right_spectrum
+                    if child_limit is None or first + second <= child_limit
+                )
+        frozen = frozenset(spectrum)
+        self.memo[key] = (frozen, branches)
+        return key, frozen
+
+    def prepare(self):
+        """Build the exact reachable-cost support, or return False on state cap."""
+        if self._prepared:
+            return not self._prepare_failed
+        self._prepared = True
+        try:
+            self.root_key, self.root_spectrum = self._state(
+                self.rows, self.columns, self.unary, self.allowed, self.max_cost
+            )
+            return True
+        except _StateLimit:
+            self._prepare_failed = True
+            self.memo.clear()
+            return False
+
+    def _reconstruct(self, key, target):
+        check_deadline(self.deadline)
+        spectrum, branches = self.memo[key]
+        if target not in spectrum:
+            return
+        for branch in branches:
+            check_deadline(self.deadline)
+            if branch[0] == "leaf":
+                _, value, images = branch
+                if value == target:
+                    yield dict(zip(key[0], images))
+                continue
+            _, offset, separator_map, left_key, right_key = branch
+            left_spectrum = self.memo[left_key][0]
+            right_spectrum = self.memo[right_key][0]
+            right_by_cost = right_spectrum
+            for left_cost in left_spectrum:
+                right_cost = target - offset - left_cost
+                if right_cost not in right_by_cost:
+                    continue
+                for left_mapping in self._reconstruct(left_key, left_cost):
+                    for right_mapping in self._reconstruct(right_key, right_cost):
+                        yield {
+                            **dict(separator_map),
+                            **left_mapping,
+                            **right_mapping,
+                        }
+
+    def mappings_between(self, lower, upper):
+        """Yield ``(complete-row-order mapping, residual cost)`` in the shell."""
+        if not self.prepare():
+            raise RuntimeError("prepare() must succeed before shell reconstruction")
+        for cost in sorted(
+            value for value in self.root_spectrum if lower <= value <= upper
+        ):
+            for mapping in self._reconstruct(self.root_key, cost):
+                yield tuple(mapping[row] for row in self.rows), cost
+
+
+__all__ = ["SeparatorCostSpectrum"]

synkit/Chem/Mapper/solvers/exact/pabs/sparse_reward_bound.py

@@ -0,0 +1,207 @@
+"""Checked Lagrangean lower bounds for sparse signed bond rewards.
+
+Every source bond contributes a pair factor ``-w``. Messages enter its endpoint
+unaries positively and the pair factor negatively, cancelling on any complete
+mapping. The LAP minimum plus independent exact pair minima is therefore a
+lower bound. Overlapping bounds must be combined by maximum, never addition.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..assignment.incremental_assignment import solve_assignment
+from .propagation_limits import check_deadline
+
+
+@dataclass(frozen=True)
+class SparseRewardBound:
+    lower_bound: int
+    assignment: object
+    unary_offsets: tuple
+    factor_minima: tuple
+    adjacency_entries_scanned: int
+
+
+def product_adjacency(matrix):
+    return tuple(
+        tuple((j, int(weight)) for j, weight in enumerate(row) if weight and j != i)
+        for i, row in enumerate(matrix)
+    )
+
+
+def factor_row_minima(
+    weight,
+    adjacency,
+    left_domain,
+    right_domain,
+    left_message,
+    right_message,
+    *,
+    deadline=None,
+):
+    """Exact pair min-marginals without a dense product-image pair table.
+
+    The unrewarded baseline considers every allowed distinct image pair. The
+    second term scans nonzero product bonds, discounting only equal-sign bonds.
+    Scanned entries include sign- and domain-rejected adjacency entries.
+    """
+    right = set(right_domain)
+    best = sorted((-int(right_message[j]), j) for j in right)[:2]
+    result, scanned = {}, 0
+    for image in left_domain:
+        check_deadline(deadline)
+        baseline = next((value for value, j in best if j != image), None)
+        if baseline is None:
+            continue
+        left = -int(left_message[image])
+        minimum = left + baseline
+        for partner, product_weight in adjacency[image]:
+            scanned += 1
+            if partner not in right:
+                continue
+            if (weight > 0 and product_weight > 0) or (
+                weight < 0 and product_weight < 0
+            ):
+                value = (
+                    left
+                    - int(right_message[partner])
+                    - 2 * min(abs(weight), abs(product_weight))
+                )
+                minimum = min(minimum, value)
+        result[image] = minimum
+    return result, scanned
+
+
+def checked_sparse_reward_bound(a, b, unary, allowed, messages=None, *, deadline=None):
+    """Return a verified integer bound, or None for a proved infeasible residual.
+
+    ``messages[(i,k)]`` contains one integer vector per endpoint for a nonzero
+    source bond i<k. This first diagnostic implementation admits n<=256 and
+    signed input/message magnitudes <=2**20. LAP row shifts make its costs
+    nonnegative; the existing independent assignment verifier checks the LAP.
+    """
+    check_deadline(deadline)
+    a, b, unary = (np.asarray(x) for x in (a, b, unary))
+    n = len(a)
+    if n > 256 or any(x.shape != (n, n) or x.dtype.kind != "i" for x in (a, b, unary)):
+        raise ValueError(
+            "sparse reward bounds require square signed integer arrays of order <=256"
+        )
+    if any(np.any(x < -(2**20)) or np.any(x > 2**20) for x in (a, b, unary)):
+        raise ValueError("sparse reward bound input exceeds its exact integer envelope")
+    if (
+        not np.array_equal(a, a.T)
+        or not np.array_equal(b, b.T)
+        or np.any(np.diag(a))
+        or np.any(np.diag(b))
+    ):
+        raise ValueError(
+            "sparse reward bounds require symmetric zero-diagonal matrices"
+        )
+    allowed = np.asarray(allowed, dtype=bool)
+    if allowed.shape != (n, n):
+        raise ValueError("allowed must match the residual arrays")
+    edges = [(i, k) for i in range(n) for k in range(i + 1, n) if a[i, k]]
+    messages = {} if messages is None else messages
+    if set(messages) - set(edges):
+        raise ValueError("messages must refer to nonzero source bonds")
+    modified = unary.astype(np.int64).copy()
+    adjacency = product_adjacency(b)
+    domains = tuple(tuple(np.flatnonzero(row)) for row in allowed)
+    factors, scanned = [], 0
+    zero = (0,) * n
+    for i, k in edges:
+        check_deadline(deadline)
+        left, right = messages.get((i, k), (zero, zero))
+        for values in (left, right):
+            array = np.asarray(values)
+            if (
+                array.shape != (n,)
+                or array.dtype.kind != "i"
+                or np.any(array < -(2**20))
+                or np.any(array > 2**20)
+            ):
+                raise ValueError("message vectors exceed the exact integer envelope")
+        modified[i] += left
+        modified[k] += right
+        minima, inspected = factor_row_minima(
+            int(a[i, k]),
+            adjacency,
+            domains[i],
+            domains[k],
+            left,
+            right,
+            deadline=deadline,
+        )
+        if not minima:
+            return None
+        factors.append(min(minima.values()))
+        scanned += inspected
+    if any(not domain for domain in domains):
+        return None
+    offsets = tuple(
+        min(int(modified[i, j]) for j in domain) for i, domain in enumerate(domains)
+    )
+    costs = np.where(
+        allowed, modified - np.asarray(offsets, dtype=np.int64)[:, None], 0
+    )
+    assignment = solve_assignment(
+        costs, allowed, tuple(range(n)), tuple(range(n)), deadline=deadline
+    )
+    if assignment is None:
+        return None
+    mass = sum(
+        abs(int(a[i, k])) + abs(int(b[i, k])) for i in range(n) for k in range(i + 1, n)
+    )
+    value = mass + sum(offsets) + assignment.lower_bound + sum(factors)
+    return SparseRewardBound(value, assignment, offsets, tuple(factors), scanned)
+
+
+def diffuse_factor_messages(a, b, allowed, messages=None, *, deadline=None):
+    """One exact factor-to-unary min-marginal sweep for offline diagnostics.
+
+    Every finite push preserves the objective. A complete checked evaluation
+    determines the useful bound; no convergence or monotonicity is promised
+    when pair-infeasible image choices remain in the relaxed domains. This is
+    deliberately separate from production search.
+    """
+    n = len(a)
+    adjacency = product_adjacency(b)
+    domains = tuple(tuple(np.flatnonzero(row)) for row in allowed)
+    result = (
+        {}
+        if messages is None
+        else {
+            edge: (list(left), list(right)) for edge, (left, right) in messages.items()
+        }
+    )
+    for i in range(n):
+        for k in range(i + 1, n):
+            check_deadline(deadline)
+            if not a[i, k]:
+                continue
+            left, right = result.setdefault((i, k), ([0] * n, [0] * n))
+            minima, _ = factor_row_minima(
+                int(a[i, k]),
+                adjacency,
+                domains[i],
+                domains[k],
+                left,
+                right,
+                deadline=deadline,
+            )
+            for image, value in minima.items():
+                left[image] += value
+            minima, _ = factor_row_minima(
+                int(a[i, k]),
+                adjacency,
+                domains[k],
+                domains[i],
+                right,
+                left,
+                deadline=deadline,
+            )
+            for image, value in minima.items():
+                right[image] += value
+    return result