synkit 1.6.5__py3-none-win_amd64.whl

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

@@ -0,0 +1,66 @@
+"""Budgeted verified cyclic-subgroup selection for exact propagation search."""
+
+from .propagation_limits import PropagationDeadline, check_deadline
+
+
+def bounded_cyclic_subgroup(permutations, *, max_order, deadline):
+    """Retain a fully closed subgroup; interruption never returns partial powers."""
+    if not permutations:
+        return ()
+    identity = tuple(range(len(permutations[0])))
+    best = (identity,)
+    for generator in permutations:
+        check_deadline(deadline)
+        powers, seen, current = [identity], {identity}, identity
+        while len(powers) <= max_order:
+            check_deadline(deadline)
+            current = tuple(generator[image] for image in current)
+            if current == identity:
+                if len(powers) > len(best):
+                    best = tuple(powers)
+                break
+            if current in seen:
+                break
+            seen.add(current)
+            powers.append(current)
+    return best
+
+
+def bounded_generated_subgroup(permutations, *, max_order, deadline):
+    """Close verified generators, retaining only fully completed subgroups."""
+    if not permutations:
+        return ()
+    identity = tuple(range(len(permutations[0])))
+    subgroup = {identity}
+    try:
+        for generator in permutations:
+            check_deadline(deadline)
+            if generator in subgroup:
+                continue
+            inverse = [0] * len(generator)
+            for index, image in enumerate(generator):
+                inverse[image] = index
+            inverse = tuple(inverse)
+            closure = set(subgroup)
+            pending = list(subgroup)
+            exceeded = False
+            factors = (*subgroup, generator, inverse)
+            while pending and not exceeded:
+                check_deadline(deadline)
+                current = pending.pop()
+                for factor in factors:
+                    product = tuple(
+                        current[factor[index]] for index in range(len(identity))
+                    )
+                    if product in closure:
+                        continue
+                    if len(closure) >= max_order:
+                        exceeded = True
+                        break
+                    closure.add(product)
+                    pending.append(product)
+            if not exceeded:
+                subgroup = closure
+    except PropagationDeadline:
+        pass
+    return tuple(sorted(subgroup))

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

@@ -0,0 +1,136 @@
+"""Reversible typed bond masses for cheap exact graph-search bounds."""
+
+import numpy as np
+
+
+class ResidualTypedBonds:
+    """Track signed sums by unordered atom-type pairs and absolute edge mass."""
+
+    def __init__(self, a, b, labels, product_labels, rows, columns):
+        types = {
+            label: i
+            for i, label in enumerate(dict.fromkeys([*labels, *product_labels]))
+        }
+        size = len(types)
+        self.a, self.b = a, b
+
+        def buckets(values):
+            colors = np.asarray([types[label] for label in values], dtype=int)
+            return np.minimum(colors[:, None], colors) * size + np.maximum(
+                colors[:, None], colors
+            )
+
+        self.reactant_buckets, self.product_buckets = buckets(labels), buckets(
+            product_labels
+        )
+        # Small exact bond alphabets are common in this objective. Keep a
+        # reversible histogram only when its dense representation is bounded;
+        # uncommon large alphabets retain the existing linear bound.
+        weights = np.concatenate((a[np.triu_indices(len(a), 1)],
+                                  b[np.triu_indices(len(b), 1)]))
+        self.levels = np.unique(weights)
+        if not len(self.levels):
+            self.levels = np.asarray([0], dtype=np.int64)
+        self.histogram_enabled = len(self.levels) <= 16
+        self.level_index = (
+            {int(value): index for index, value in enumerate(self.levels)}
+            if self.histogram_enabled
+            else None
+        )
+        self.reactant_histogram = None
+        self.product_histogram = None
+        if self.histogram_enabled:
+            shape = (size * size, len(self.levels))
+            self.reactant_histogram = np.zeros(shape, dtype=np.int64)
+            self.product_histogram = np.zeros(shape, dtype=np.int64)
+            self._initialize_histogram(
+                a, self.reactant_buckets, rows, self.reactant_histogram, self.levels
+            )
+            self._initialize_histogram(
+                b, self.product_buckets, columns, self.product_histogram, self.levels
+            )
+        self.reactant = np.zeros(size * size, dtype=np.int64)
+        self.product = np.zeros(size * size, dtype=np.int64)
+        self.reactant_absolute = self._initialize(
+            a, self.reactant_buckets, rows, self.reactant
+        )
+        self.product_absolute = self._initialize(
+            b, self.product_buckets, columns, self.product
+        )
+
+    @staticmethod
+    def _initialize(matrix, buckets, positions, mass):
+        positions = np.asarray(positions, dtype=int)
+        i, j = np.triu_indices(len(positions), 1)
+        left, right = positions[i], positions[j]
+        weights = matrix[left, right]
+        np.add.at(mass, buckets[left, right], weights)
+        return int(np.abs(weights).sum())
+
+    def lower_bound(self):
+        """Sum reverse-triangle bounds over disjoint, preserved type classes."""
+        return int(np.abs(self.reactant - self.product).sum())
+
+    @staticmethod
+    def _initialize_histogram(matrix, buckets, positions, histogram, levels):
+        positions = np.asarray(positions, dtype=int)
+        i, j = np.triu_indices(len(positions), 1)
+        left, right = positions[i], positions[j]
+        weight_index = np.searchsorted(levels, matrix[left, right])
+        np.add.at(histogram, (buckets[left, right], weight_index), 1)
+
+    def transport_lower_bound(self):
+        """Return the typed residual pair-transport bound, if cheaply indexed.
+
+        Within each unordered atom-type pair, a compatible vertex bijection
+        induces a bijection on unordered residual pairs. Matching those pair
+        weights without the vertex-consistency constraints gives a relaxation.
+        For one-dimensional absolute cost, sorted matching equals the integral
+        of the absolute difference between cumulative histograms.
+        """
+        if not self.histogram_enabled:
+            return None
+        cumulative = np.cumsum(
+            self.reactant_histogram - self.product_histogram, axis=1
+        )
+        gaps = np.diff(self.levels)
+        # A valid completion has equal pair counts in every compatible type
+        # bucket, so the final cumulative count must be zero.
+        if np.any(cumulative[:, -1]):
+            return None
+        return int((np.abs(cumulative[:, :-1]) @ gaps).sum())
+
+    def upper_bound(self):
+        """Bound residual disagreement by the sum of absolute bond masses."""
+        return self.reactant_absolute + self.product_absolute
+
+    def remove(self, row, image, rows, columns):
+        """Remove incident residual edges and return an exact restoration token."""
+        rows, columns = np.asarray(rows, dtype=int), np.asarray(columns, dtype=int)
+        rb, pb = self.reactant_buckets[row, rows], self.product_buckets[image, columns]
+        rw, pw = self.a[row, rows], self.b[image, columns]
+        ra, pa = int(np.abs(rw).sum()), int(np.abs(pw).sum())
+        np.add.at(self.reactant, rb, -rw)
+        np.add.at(self.product, pb, -pw)
+        histogram_token = None
+        if self.histogram_enabled:
+            ri = np.fromiter((self.level_index[int(x)] for x in rw), dtype=int)
+            pi = np.fromiter((self.level_index[int(x)] for x in pw), dtype=int)
+            np.add.at(self.reactant_histogram, (rb, ri), -1)
+            np.add.at(self.product_histogram, (pb, pi), -1)
+            histogram_token = rb, ri, pb, pi
+        self.reactant_absolute -= ra
+        self.product_absolute -= pa
+        return rb, rw, pb, pw, ra, pa, histogram_token
+
+    def restore(self, token):
+        """Restore the signed typed sums and absolute masses after a child."""
+        rb, rw, pb, pw, ra, pa, histogram_token = token
+        np.add.at(self.reactant, rb, rw)
+        np.add.at(self.product, pb, pw)
+        if histogram_token is not None:
+            rb, ri, pb, pi = histogram_token
+            np.add.at(self.reactant_histogram, (rb, ri), 1)
+            np.add.at(self.product_histogram, (pb, pi), 1)
+        self.reactant_absolute += ra
+        self.product_absolute += pa

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

@@ -0,0 +1,201 @@
+"""Exact residual spectra using sparse source bonds and a frontier state.
+
+For signed weights, ``|a-b| = |a| + |b| - w(a,b)``, where ``w`` is
+twice the smaller magnitude when the signs agree, and zero otherwise.
+Product bond mass is constant under a bijection. Consequently the only
+prefix images needed for future pair rewards are those on the source-bond
+frontier. The used-image subset still retains every assigned image.
+"""
+
+from __future__ import annotations
+
+import time
+from numbers import Integral
+
+import numpy as np
+
+from .suffix_spectrum import SuffixCostSpectrum, _StateLimit
+
+
+class RewardFrontierSpectrum(SuffixCostSpectrum):
+    """Bounded exact CD supports computed from sparse preserved-bond rewards.
+
+    Domains and unary costs are static within this prepared instance. Source
+    rows retain their supplied order. Canonicalization remains in reconstruction
+    so the memoized support does not depend on a prefix-specific subgroup.
+    An excessive reward envelope or interrupted preparation is a fallback,
+    never an infeasibility certificate.
+
+    At each assignment the increment is unary cost plus source bond mass to
+    earlier rows plus product bond mass to used images, minus the conserved
+    bond reward. This equals the literal sum of nonnegative pair disagreements,
+    so distance-cap pruning remains valid without retaining a future-cost table.
+    """
+
+    def __init__(self, *args, max_reward=4096, **kwargs):
+        super().__init__(*args, **kwargs)
+        if (
+            isinstance(max_reward, bool)
+            or not isinstance(max_reward, Integral)
+            or max_reward < 1
+        ):
+            raise ValueError("max_reward must be a positive integer")
+        if len(set(self.rows)) != self.n or len(set(self.columns)) != self.n:
+            raise ValueError("residual rows and columns must be distinct")
+        a = self.a[np.ix_(self.rows, self.rows)]
+        b = self.b[np.ix_(self.columns, self.columns)]
+        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("reward spectra require symmetric zero-diagonal matrices")
+        # Python integers avoid overflowing sums and signed magnitudes.
+        self.source = tuple(tuple(int(x) for x in row) for row in a)
+        self.product = tuple(tuple(int(x) for x in row) for row in b)
+        self.domain_masks = tuple(
+            sum(1 << col for col in range(self.n) if self.allowed[row, col])
+            for row in range(self.n)
+        )
+        shifts = tuple(
+            max(
+                (
+                    int(self.unary[row, col])
+                    for col in range(self.n)
+                    if self.allowed[row, col]
+                ),
+                default=0,
+            )
+            for row in range(self.n)
+        )
+        self.unary_costs = tuple(
+            tuple(int(value) for value in row) for row in self.unary
+        )
+        self.prefix_mass = tuple(
+            sum(abs(self.source[row][depth]) for row in range(depth))
+            for depth in range(self.n)
+        )
+        self.product_mass_edges = tuple(
+            tuple(
+                (1 << image, abs(weight)) for image, weight in enumerate(row) if weight
+            )
+            for row in self.product
+        )
+        self._product_mass_cache = {}
+        self.constant = sum(shifts) + sum(
+            abs(self.source[i][k]) + abs(self.product[i][k])
+            for i in range(self.n)
+            for k in range(i + 1, self.n)
+        )
+        self.max_reward = int(max_reward)
+        self.frontiers = tuple(
+            tuple(
+                row
+                for row in range(depth)
+                if any(self.source[row][next_row] for next_row in range(depth, self.n))
+            )
+            for depth in range(self.n + 1)
+        )
+        self.max_frontier = max(map(len, self.frontiers), default=0)
+        self._advance = tuple(
+            tuple(
+                -1 if row == depth else self.frontiers[depth].index(row)
+                for row in self.frontiers[depth + 1]
+            )
+            for depth in range(self.n)
+        )
+        self._incident = tuple(
+            tuple(
+                (position, self.source[row][depth])
+                for position, row in enumerate(self.frontiers[depth])
+                if self.source[row][depth]
+            )
+            for depth in range(self.n)
+        )
+
+    @staticmethod
+    def _reward(source, product):
+        if (source > 0 and product > 0) or (source < 0 and product < 0):
+            return 2 * min(abs(source), abs(product))
+        return 0
+
+    def _used_mass(self, used, col):
+        if not self.product_mass_edges[col]:
+            return 0
+        key = used, col
+        value = self._product_mass_cache.get(key)
+        if value is None:
+            value = sum(
+                weight for bit, weight in self.product_mass_edges[col] if used & bit
+            )
+            self._product_mass_cache[key] = value
+        return value
+
+    def _frontier_state(self, depth, used, frontier):
+        self._check()
+        key = depth, used, frontier
+        cached = self.memo.get(key)
+        if cached is not None:
+            return key, cached[0]
+        self._tick()
+        if depth == self.n:
+            self.memo[key] = (1, ())
+            return key, 1
+        support, branches = 0, []
+        candidates = self.domain_masks[depth] & ~used
+        while candidates:
+            self._check()
+            bit = candidates & -candidates
+            col = bit.bit_length() - 1
+            candidates ^= bit
+            increment = (
+                self.unary_costs[depth][col]
+                + self.prefix_mass[depth]
+                + self._used_mass(used, col)
+            )
+            for position, weight in self._incident[depth]:
+                increment -= self._reward(weight, self.product[frontier[position]][col])
+            if increment < 0:
+                raise ArithmeticError(
+                    "Sparse reward increment disagrees with a nonnegative CD"
+                )
+            if increment > self.max_cost:
+                continue
+            child_frontier = tuple(
+                col if position == -1 else frontier[position]
+                for position in self._advance[depth]
+            )
+            child_key, child_support = self._frontier_state(
+                depth + 1, used | bit, child_frontier
+            )
+            if child_support:
+                support |= child_support << increment
+                branches.append((col, increment, child_key))
+                self.transitions += 1
+        support &= (1 << (self.max_cost + 1)) - 1
+        self.memo[key] = support, tuple(branches)
+        return key, support
+
+    def prepare(self):
+        """Prepare exact supports in the admitted envelope, or request fallback."""
+        if self._prepared:
+            return not self._prepare_failed
+        self._prepared = True
+        self._prepare_started = time.perf_counter()
+        self.support = 0
+        if self.constant > self.max_reward:
+            self._prepare_failed = True
+            return False
+        try:
+            self.root_key, self.support = self._frontier_state(0, 0, ())
+            return True
+        except _StateLimit:
+            self._prepare_failed = True
+            self.memo.clear()
+            self._product_mass_cache.clear()
+            self.support = 0
+            return False
+
+
+__all__ = ["RewardFrontierSpectrum"]

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

@@ -0,0 +1,258 @@
+"""Bounded exact separator lower bound for residual weighted assignments.
+
+This is an optimization oracle, not a shell enumerator. It returns the exact
+minimum residual cost when it finishes within its state budget; callers may
+only use that value as an admissible lower bound. If the budget is exceeded it
+returns ``None`` and the ordinary PABS bounds remain in force.
+"""
+
+from __future__ import annotations
+
+import itertools
+import math
+
+import numpy as np
+
+from .propagation_limits import check_deadline
+
+
+class _StateLimit(Exception):
+    pass
+
+
+def _components(rows, adjacency, removed):
+    remaining = set(rows) - set(removed)
+    result = []
+    while remaining:
+        root = min(remaining)
+        component = {root}
+        stack = [root]
+        remaining.remove(root)
+        while stack:
+            node = stack.pop()
+            neighbors = [other for other in remaining if adjacency[node, other]]
+            for other in neighbors:
+                remaining.remove(other)
+                component.add(other)
+                stack.append(other)
+        result.append(tuple(sorted(component)))
+    return result
+
+
+def _balanced_component_split(components, n, alpha):
+    """Group disconnected components into two balanced nonempty sides."""
+    if len(components) < 2:
+        return None
+    limit = math.floor(alpha * n)
+    best = None
+    # Components are disjoint, so a subset determines one side of the cut.
+    for mask in range(1, (1 << len(components)) - 1):
+        if not (mask & 1):
+            continue  # remove the symmetric duplicate
+        left = tuple(
+            sorted(i for k, c in enumerate(components) if mask >> k & 1 for i in c)
+        )
+        right = tuple(
+            sorted(
+                i for k, c in enumerate(components) if not (mask >> k & 1) for i in c
+            )
+        )
+        if not left or not right or max(len(left), len(right)) > limit:
+            continue
+        candidate = (max(len(left), len(right)), left, right)
+        if best is None or candidate < best:
+            best = candidate
+    return None if best is None else (best[1], best[2])
+
+
+def _find_separator(rows, adjacency, max_separator_size, alpha):
+    n = len(rows)
+    for size in range(1, min(max_separator_size, n - 2) + 1):
+        for separator in itertools.combinations(rows, size):
+            components = _components(rows, adjacency, separator)
+            split = _balanced_component_split(components, n, alpha)
+            if split is not None:
+                return tuple(separator), split
+    return None
+
+
+def minimum_separator_residual_cost(  # noqa: C901
+    a,
+    b,
+    rows,
+    columns,
+    unary,
+    allowed,
+    *,
+    deadline=None,
+    max_separator_size=2,
+    balance_alpha=2 / 3,
+    max_states=20_000,
+    base_case=4,
+):
+    """Return an exact minimum residual QAP cost in integer quarter units.
+
+    ``unary[x, y]`` contains all costs between residual assignment ``x -> y``
+    and already-fixed rows. Pair costs use the mapper's exact absolute edge
+    disagreement ``abs(a[i,k] - b[j,l])``; one undirected pair is counted once.
+    Element compatibility and propagated domains are represented by ``allowed``.
+
+    A separator's assigned image is absorbed into child unary costs. Once the
+    source sides are disconnected, their cross cost is independent of the
+    particular child maps and is the product cut insertion cost. This is the
+    SR-GED decomposition specialized to the mapper's fixed-cardinality,
+    weighted assignment objective.
+    """
+    rows, columns = tuple(rows), tuple(columns)
+    unary = np.asarray(unary, dtype=np.int64)
+    allowed = np.asarray(allowed, dtype=bool)
+    if (
+        len(rows) != len(columns)
+        or unary.shape != allowed.shape
+        or unary.shape != (len(rows), len(columns))
+    ):
+        raise ValueError("residual arrays must be square and match row/column sets")
+    if not rows:
+        return 0
+    if len(rows) > 12:
+        return None
+    adjacency = np.asarray(a != 0, dtype=bool)
+    states = 0
+
+    def tick():
+        nonlocal states
+        check_deadline(deadline)
+        states += 1
+        if states > max_states:
+            raise _StateLimit
+
+    def pair_cost(i, k, j, image):
+        return abs(int(a[i, k]) - int(b[j, image]))
+
+    def brute(rset, cset, costs, domains):
+        best = None
+        for permutation in itertools.permutations(range(len(cset))):
+            tick()
+            if any(not domains[x, permutation[x]] for x in range(len(rset))):
+                continue
+            value = sum(int(costs[x, permutation[x]]) for x in range(len(rset)))
+            for x in range(len(rset)):
+                for y in range(x + 1, len(rset)):
+                    value += pair_cost(
+                        rset[x], rset[y], cset[permutation[x]], cset[permutation[y]]
+                    )
+            best = value if best is None else min(best, value)
+        return best
+
+    def solve(rset, cset, costs, domains):
+        tick()
+        n = len(rset)
+        if n <= base_case:
+            return brute(rset, cset, costs, domains)
+        found = _find_separator(rset, adjacency, max_separator_size, balance_alpha)
+        if found is None:
+            return brute(rset, cset, costs, domains)
+        separator, (left_rows, right_rows) = found
+        separator_positions = [rset.index(i) for i in separator]
+        best = None
+        for chosen in itertools.permutations(cset, len(separator)):
+            tick()
+            if any(
+                not domains[pos, cset.index(j)]
+                for pos, j in zip(separator_positions, chosen)
+            ):
+                continue
+            chosen_map = dict(zip(separator, chosen))
+            separator_cost = sum(
+                int(costs[pos, cset.index(chosen_map[row])])
+                for pos, row in zip(separator_positions, separator)
+            )
+            for p, row in enumerate(separator):
+                for q in range(p + 1, len(separator)):
+                    other = separator[q]
+                    separator_cost += pair_cost(
+                        row, other, chosen_map[row], chosen_map[other]
+                    )
+            free_columns = tuple(j for j in cset if j not in set(chosen))
+            left_size = len(left_rows)
+            if left_size > len(free_columns):
+                continue
+            left_positions = [rset.index(i) for i in left_rows]
+            right_positions = [rset.index(i) for i in right_rows]
+            for left_columns in itertools.combinations(free_columns, left_size):
+                tick()
+                right_columns = tuple(
+                    j for j in free_columns if j not in set(left_columns)
+                )
+                if len(right_columns) != len(right_rows):
+                    continue
+                left_costs = (
+                    np.asarray(
+                        [
+                            [costs[x, cset.index(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(
+                        [
+                            [costs[x, cset.index(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(
+                    [
+                        [domains[x, cset.index(j)] for j in left_columns]
+                        for x in left_positions
+                    ],
+                    dtype=bool,
+                ).reshape(len(left_rows), len(left_columns))
+                right_allowed = np.asarray(
+                    [
+                        [domains[x, cset.index(j)] for j in right_columns]
+                        for x in right_positions
+                    ],
+                    dtype=bool,
+                ).reshape(len(right_rows), len(right_columns))
+                for x, row in enumerate(left_rows):
+                    for y, image in enumerate(left_columns):
+                        left_costs[x, y] += sum(
+                            pair_cost(row, sep_row, image, chosen_map[sep_row])
+                            for sep_row in separator
+                        )
+                for x, row in enumerate(right_rows):
+                    for y, image in enumerate(right_columns):
+                        right_costs[x, y] += sum(
+                            pair_cost(row, sep_row, image, chosen_map[sep_row])
+                            for sep_row in separator
+                        )
+                left_value = solve(left_rows, left_columns, left_costs, left_allowed)
+                if left_value is None:
+                    continue
+                right_value = solve(
+                    right_rows, right_columns, right_costs, right_allowed
+                )
+                if right_value is None:
+                    continue
+                cut = sum(
+                    abs(int(b[j, k])) for j in left_columns for k in right_columns
+                )
+                total = separator_cost + left_value + right_value + cut
+                best = total if best is None else min(best, total)
+        return best
+
+    try:
+        return solve(rows, columns, unary, allowed)
+    except _StateLimit:
+        return None
+
+
+__all__ = ["minimum_separator_residual_cost"]