synkit 1.6.5__py3-none-win_amd64.whl

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

@@ -0,0 +1,299 @@
+"""Exact bounded decision diagram for residual assignment cost spectra.
+
+The diagram assigns residual source rows in a fixed order. A state retains the
+used product columns and the exact accumulated cost of the assigned prefix for
+every remaining row/image choice. Prefixes with the same future cost table and
+used-column set have identical suffix problems and can be merged safely.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+
+import numpy as np
+
+from .propagation_limits import check_deadline
+
+
+class _StateLimit(Exception):
+    pass
+
+
+class SuffixCostSpectrum:
+    """Build and query an exact residual CD decision diagram.
+
+    Costs are nonnegative integer quarter units. The unary matrix contains all
+    costs from rows assigned before this residual; pair costs within the
+    residual are added as rows are assigned. ``max_cost`` bounds total residual
+    cost and therefore caps the stored bitset. A state-cap or deadline failure
+    leaves no partial spectrum available to callers.
+    """
+
+    def __init__(
+        self,
+        a,
+        b,
+        rows,
+        columns,
+        unary,
+        allowed,
+        *,
+        max_cost,
+        max_states=20_000,
+        max_seconds=None,
+        deadline=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.max_cost = int(max_cost)
+        self.max_states = int(max_states)
+        self.max_seconds = max_seconds
+        self.deadline = deadline
+        self.n = len(self.rows)
+        self.states = 0
+        self.transitions = 0
+        self.orbits_pruned = 0
+        self._validated_symmetry_groups = set()
+        self.memo = {}
+        self._prepared = False
+        self._prepare_failed = False
+        self._prepare_started = None
+        if (
+            len(self.columns) != self.n
+            or self.unary.shape != (self.n, self.n)
+            or self.allowed.shape != self.unary.shape
+        ):
+            raise ValueError("residual arrays must be square and match row/column sets")
+        if self.max_cost < 0:
+            raise ValueError("max_cost must be nonnegative")
+        if self.max_states < 1:
+            raise ValueError("max_states must be positive")
+        if self.max_seconds is not None and (
+            isinstance(self.max_seconds, bool)
+            or not isinstance(self.max_seconds, (int, float))
+            or not math.isfinite(self.max_seconds)
+            or self.max_seconds <= 0
+        ):
+            raise ValueError("max_seconds must be finite and positive")
+        if np.any(self.unary < 0):
+            raise ValueError("suffix spectra require nonnegative unary costs")
+        if self.a.ndim != 2 or self.b.ndim != 2:
+            raise ValueError("endpoint cost matrices must be two-dimensional")
+        if any(i < 0 or i >= len(self.a) for i in self.rows):
+            raise ValueError("residual rows are outside the source matrix")
+        if any(j < 0 or j >= len(self.b) for j in self.columns):
+            raise ValueError("residual columns are outside the product matrix")
+
+    def _key(self, depth, used, future_cost):
+        available = tuple(j for j in range(self.n) if not used & (1 << j))
+        future = tuple(
+            int(future_cost[row, col])
+            for row in range(self.n - depth)
+            for col in available
+        )
+        return depth, used, future
+
+    def _tick(self):
+        self._check()
+        self.states += 1
+        if self.states > self.max_states:
+            raise _StateLimit
+
+    def _check(self):
+        check_deadline(self.deadline)
+        if (
+            self._prepare_started is not None
+            and self.max_seconds is not None
+            and time.perf_counter() - self._prepare_started > self.max_seconds
+        ):
+            raise _StateLimit
+
+    def _state(self, depth, used, future_cost):
+        key = self._key(depth, used, future_cost)
+        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 = 0
+        branches = []
+        remaining_columns = tuple(col for col in range(self.n) if not used & (1 << col))
+        row = self.rows[depth]
+        for col_pos in remaining_columns:
+            self._check()
+            if not self.allowed[depth, col_pos]:
+                continue
+            edge_cost = int(future_cost[0, col_pos])
+            if edge_cost > self.max_cost:
+                continue
+            child_costs = future_cost[1:, :].copy()
+            if depth + 1 < self.n:
+                image = self.columns[col_pos]
+                remaining_positions = tuple(
+                    pos for pos in remaining_columns if pos != col_pos
+                )
+                for next_depth in range(depth + 1, self.n):
+                    next_row = self.rows[next_depth]
+                    for next_col in remaining_positions:
+                        child_costs[next_depth - depth - 1, next_col] += abs(
+                            int(self.a[row, next_row])
+                            - int(self.b[image, self.columns[next_col]])
+                        )
+                if remaining_positions:
+                    used_columns = set(range(self.n)) - set(remaining_positions)
+                    if used_columns:
+                        child_costs[:, tuple(sorted(used_columns))] = 0
+            child_key, child_support = self._state(
+                depth + 1, used | (1 << col_pos), child_costs
+            )
+            if child_support:
+                branches.append((col_pos, edge_cost, child_key))
+                support |= child_support << edge_cost
+                self.transitions += 1
+        support &= (1 << (self.max_cost + 1)) - 1
+        self.memo[key] = (support, tuple(branches))
+        return key, support
+
+    def prepare(self):
+        """Build the bounded exact support, or discard it on a state-cap miss."""
+        if self._prepared:
+            return not self._prepare_failed
+        self._prepared = True
+        self._prepare_started = time.perf_counter()
+        try:
+            self.root_key, self.support = self._state(
+                0,
+                0,
+                self.unary.copy(),
+            )
+            return True
+        except _StateLimit:
+            self._prepare_failed = True
+            self.memo.clear()
+            self.support = 0
+            return False
+
+    @staticmethod
+    def _has_cost(support, cost):
+        return cost >= 0 and bool(support & (1 << cost))
+
+    def reachable_costs(self, lower=0, upper=None):
+        """Return exact reachable costs in the requested inclusive interval."""
+        if not self._prepared and not self.prepare():
+            return frozenset()
+        if self._prepare_failed:
+            return frozenset()
+        upper = self.max_cost if upper is None else min(int(upper), self.max_cost)
+        lower = max(0, int(lower))
+        if upper < lower:
+            return frozenset()
+        return frozenset(
+            cost
+            for cost in range(lower, upper + 1)
+            if self._has_cost(self.support, cost)
+        )
+
+    def _walk(self, key, target, mapping, symmetry_group):
+        check_deadline(self.deadline)
+        support, branches = self.memo[key]
+        if not self._has_cost(support, target):
+            return
+        depth = key[0]
+        if depth == self.n:
+            if target == 0:
+                yield tuple(mapping)
+            return
+        for col_pos, edge_cost, child_key in branches:
+            remainder = target - edge_cost
+            if remainder < 0:
+                continue
+            child_support = self.memo[child_key][0]
+            if not self._has_cost(child_support, remainder):
+                continue
+            image = self.columns[col_pos]
+            if len(symmetry_group) > 1:
+                orbit = {permutation[image] for permutation in symmetry_group}
+                if image != min(orbit):
+                    self.orbits_pruned += 1
+                    continue
+                child_group = tuple(
+                    permutation
+                    for permutation in symmetry_group
+                    if permutation[image] == image
+                )
+            else:
+                child_group = symmetry_group
+            mapping[depth] = image
+            yield from self._walk(child_key, remainder, mapping, child_group)
+            mapping[depth] = -1
+
+    def _validate_symmetry_group(self, symmetry_group):
+        """Check that a supplied product group preserves this residual problem."""
+        group = tuple(tuple(permutation) for permutation in symmetry_group)
+        if not group:
+            return group
+        cache_key = frozenset(group)
+        if cache_key in self._validated_symmetry_groups:
+            return group
+        identity = tuple(range(len(self.b)))
+        if identity not in group:
+            raise ValueError("symmetry_group must contain the identity")
+        if len(group) == 1:
+            self._validated_symmetry_groups.add(cache_key)
+            return group
+        positions = {column: index for index, column in enumerate(self.columns)}
+        for permutation in group:
+            if (
+                len(permutation) != len(self.b)
+                or set(permutation) != set(range(len(self.b)))
+            ):
+                raise ValueError("symmetry_group entries must be permutations")
+            if any(permutation[column] not in positions for column in self.columns):
+                raise ValueError("symmetry_group must preserve residual columns")
+            image_positions = np.asarray(
+                [positions[permutation[column]] for column in self.columns],
+                dtype=int,
+            )
+            if not np.array_equal(
+                self.allowed, self.allowed[:, image_positions]
+            ) or not np.array_equal(self.unary, self.unary[:, image_positions]):
+                raise ValueError(
+                    "symmetry_group must preserve residual domains and costs"
+                )
+            if not np.array_equal(
+                self.b[np.ix_(permutation, permutation)], self.b
+            ):
+                raise ValueError("symmetry_group must preserve product bonds")
+        self._validated_symmetry_groups.add(cache_key)
+        return group
+
+    def mappings_at(self, target, *, symmetry_group=()):
+        """Yield residual mappings at one cost, optionally one per orbit.
+
+        ``symmetry_group`` must be a product-index permutation group that
+        preserves this residual instance's allowed entries, unary costs, and
+        pair costs. The yielded mapping is the lexicographically least member
+        of its orbit in the fixed ``rows`` order.
+        """
+        if not self._prepared and not self.prepare():
+            return
+        if self._prepare_failed or not self._has_cost(self.support, int(target)):
+            return
+        group = self._validate_symmetry_group(symmetry_group)
+        yield from self._walk(self.root_key, int(target), [-1] * self.n, group)
+
+    def mappings_between(self, lower, upper, *, symmetry_group=()):
+        """Yield ``(mapping, cost)`` pairs for an inclusive cost interval."""
+        for cost in sorted(self.reachable_costs(lower, upper)):
+            for mapping in self.mappings_at(cost, symmetry_group=symmetry_group):
+                yield mapping, cost
+
+
+__all__ = ["SuffixCostSpectrum"]

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

@@ -0,0 +1,55 @@
+"""Dispatch full-space exact mapping to Python propagation or C++ shell search.
+
+PABS stands for Propagation and Assignment-Bounded Search. It is this package's
+descriptive interface name. The Python implementation combines one-to-one
+domain propagation and LAP cost bounds; the C++ implementation has a separate
+integer-shell traversal. These routes do not use the reduced SLAP uncertainty
+kernel or its MILP solver.
+"""
+
+from dataclasses import replace
+
+from .pabs.propagation import PropagationConfig, enumerate_synister_cp_mappings
+from .pabs.multi_shell import enumerate_pabs_shells
+
+
+def enumerate_pabs_mappings(lgp, *, backend="python", library_path=None, **options):
+    """Enumerate a minimum or selected-distance shell with an exact backend.
+
+    PABS means Propagation and Assignment-Bounded Search. ``backend='python'``
+    is the default and selects full-space propagation with linear-assignment
+    bounds. It does not run the SLAP mapper or extract its uncertainty kernel.
+    Explicit fixed assignments restrict the search if supplied by the caller.
+    Unsupported Python inputs use a recorded full-distance-search fallback.
+
+    ``cpp`` selects the optional
+    compiled integer shell search and requires an explicitly built library.
+    Both return DistanceEnumerationResult. Backend-specific unsupported options
+    raise errors; selecting C++ never silently executes Python search.
+    The C++ traversal is distinct from the Python propagation implementation.
+    """
+    if backend not in ("python", "cpp"):
+        raise ValueError("backend must be 'python' or 'cpp'")
+    if backend == "cpp":
+        if library_path is None:
+            raise ValueError(
+                "backend='cpp' requires library_path; build with native_build"
+            )
+        from .native.search import enumerate_cpp_mappings
+
+        return enumerate_cpp_mappings(lgp, library_path=library_path, **options)
+    if library_path is not None:
+        raise ValueError("library_path is only used by backend='cpp'")
+    result = enumerate_synister_cp_mappings(lgp, **options)
+    statistics = dict(result.backend_statistics or {})
+    statistics.update(
+        method="PABS", requested_backend="python", implementation=result.backend
+    )
+    return replace(result, backend_statistics=statistics)
+
+
+__all__ = [
+    "PropagationConfig",
+    "enumerate_pabs_mappings",
+    "enumerate_pabs_shells",
+]

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

@@ -0,0 +1 @@
+"""Reference-free heuristics for feasible search incumbents."""

synkit/Chem/Mapper/solvers/exact/seeds/seed.py

@@ -0,0 +1,104 @@
+"""Bounded, reference-free improvement of feasible search incumbents."""
+
+import numpy as np
+
+
+def _swap_deltas(reactant, mapped_product, left, right):
+    """Exact objective differences for simultaneous evaluation of pair swaps."""
+    a, b = reactant, mapped_product
+    rows = (
+        np.abs(a[left] - b[right])
+        - np.abs(a[left] - b[left])
+        + np.abs(a[right] - b[left])
+        - np.abs(a[right] - b[right])
+    )
+    columns = (
+        np.abs(a[:, left].T - b[:, right].T)
+        - np.abs(a[:, left].T - b[:, left].T)
+        + np.abs(a[:, right].T - b[:, left].T)
+        - np.abs(a[:, right].T - b[:, right].T)
+    )
+    delta = rows + columns
+    index = np.arange(len(left))
+    delta[index, left] = 0
+    delta[index, right] = 0
+    internal = (
+        np.abs(a[left, left] - b[right, right])
+        - np.abs(a[left, left] - b[left, left])
+        + np.abs(a[right, right] - b[left, left])
+        - np.abs(a[right, right] - b[right, right])
+        + np.abs(a[left, right] - b[right, left])
+        - np.abs(a[left, right] - b[left, right])
+        + np.abs(a[right, left] - b[left, right])
+        - np.abs(a[right, left] - b[right, left])
+    )
+    return 0.5 * (delta.sum(axis=1) + internal)
+
+
+def improve_seed_mapping(
+    reactant,
+    product,
+    elements,
+    product_elements,
+    mapping,
+    *,
+    max_steps=64,
+    max_pool_atoms=256,
+):
+    """Improve a typed bijection with bounded best-improvement pair swaps.
+
+    This supplies an incumbent only: no optimum proof or domain restriction.
+    Pool/step limits bound work and batches have at most 256 pairs. Every
+    accepted swap must improve the freshly recomputed complete objective.
+    """
+    current = np.asarray(mapping, dtype=int).copy()
+    n = len(elements)
+    if sorted(current.tolist()) != list(range(n)) or any(
+        elements[atom] != product_elements[image] for atom, image in enumerate(current)
+    ):
+        raise ValueError("seed must be a complete element-compatible bijection")
+    mapped = product[np.ix_(current, current)]
+    cost = 0.5 * float(np.abs(reactant - mapped).sum())
+    pool = np.arange(n)
+    if n > max_pool_atoms:
+        mismatch = np.abs(reactant - mapped)
+        scores = mismatch.sum(axis=0) + mismatch.sum(axis=1)
+        pool = np.asarray(
+            sorted(pool, key=lambda atom: (-scores[atom], atom))[:max_pool_atoms]
+        )
+        pool.sort()
+    left, right = np.triu_indices(len(pool), 1)
+    left, right = pool[left], pool[right]
+    labels = np.asarray(elements)
+    compatible = labels[left] == labels[right]
+    left, right = left[compatible], right[compatible]
+    accepted = 0
+    evaluated = 0
+    for _ in range(max_steps):
+        best_delta, best_index = -1e-9, None
+        for start in range(0, len(left), 256):
+            deltas = _swap_deltas(
+                reactant, mapped, left[start : start + 256], right[start : start + 256]
+            )
+            evaluated += len(deltas)
+            index = int(np.argmin(deltas))
+            if deltas[index] < best_delta:
+                best_delta, best_index = float(deltas[index]), start + index
+        if best_index is None:
+            break
+        i, j = left[best_index], right[best_index]
+        current[i], current[j] = current[j], current[i]
+        candidate_product = product[np.ix_(current, current)]
+        candidate_cost = 0.5 * float(np.abs(reactant - candidate_product).sum())
+        if candidate_cost >= cost - 1e-9:
+            current[i], current[j] = current[j], current[i]
+            break
+        mapped, cost = candidate_product, candidate_cost
+        accepted += 1
+    return current.tolist(), {
+        "accepted_swaps": accepted,
+        "evaluated_swaps": evaluated,
+        "pool_atoms": len(pool),
+        "max_steps": max_steps,
+        "max_pool_atoms": max_pool_atoms,
+    }

synkit/Chem/Mapper/solvers/exact/seeds/seed_fragments.py

@@ -0,0 +1,148 @@
+"""Bounded common-fragment anchors used only for feasible seed construction."""
+
+import time
+
+import numpy as np
+from rdkit import Chem
+from rdkit.Chem import rdFMCS
+
+from .seed import improve_seed_mapping
+from .seed_relaxation import improve_relaxed_seed_mapping
+
+_MAX_FRAGMENT_SEARCH_SECONDS = 0.025
+
+
+class _FragmentProgress(rdFMCS.MCSProgress):
+    def __init__(self, deadline):
+        super().__init__()
+        self.deadline = deadline
+        self.search_deadline = None
+
+    def __call__(self, progress, parameters):
+        now = time.process_time()
+        if self.search_deadline is None:
+            # MCS setup may exceed the tiny slice before any search progress.
+            # Keep setup inside the overall cover budget, but start the
+            # per-fragment search allowance at its first progress callback.
+            self.search_deadline = min(
+                self.deadline, now + _MAX_FRAGMENT_SEARCH_SECONDS
+            )
+        return now < self.search_deadline
+
+
+def _molecule(matrix, elements):
+    molecule = Chem.RWMol()
+    for element in elements:
+        molecule.AddAtom(Chem.Atom(int(element)))
+    orders = {
+        1: Chem.BondType.SINGLE,
+        1.5: Chem.BondType.AROMATIC,
+        2: Chem.BondType.DOUBLE,
+        3: Chem.BondType.TRIPLE,
+    }
+    for i, j in zip(*np.triu_indices(len(elements), 1)):
+        if matrix[i, j]:
+            molecule.AddBond(int(i), int(j), orders[matrix[i, j]])
+    result = molecule.GetMol()
+    result.UpdatePropertyCache(strict=False)
+    Chem.GetSymmSSSR(result)
+    return result
+
+
+def improve_fragment_seed(  # noqa: C901
+    a, b, er, ep, mapping, *, max_fragments=16, budget_seconds=0.5
+):
+    """Anchor a greedy common-fragment cover, then polish a feasible bijection.
+
+    Anchors constrain only this optional heuristic. They are never passed to
+    exact search. The fragment finder has a shared cooperative process-CPU budget,
+    so scheduler descheduling does not consume its tiny search slices. The
+    enclosing analysis still enforces its independent wall-clock deadline, and
+    unsupported matrix semantics simply retain the existing seed.
+    """
+    if len(mapping) > 256 or not np.array_equal(a, a.T) or not np.array_equal(b, b.T):
+        return list(mapping), {"skipped": "size_or_directed_matrix"}
+    values = set(np.unique(a)) | set(np.unique(b))
+    if not values <= {0, 1, 1.5, 2, 3}:
+        return list(mapping), {"skipped": "unsupported_bond_orders"}
+    if sorted(mapping) != list(range(len(er))) or any(
+        er[i] != ep[p] for i, p in enumerate(mapping)
+    ):
+        raise ValueError("seed must be a complete element-compatible bijection")
+    fixed = {}
+    working = list(mapping)
+    orientation_evaluations = 0
+    sizes = []
+    canceled = False
+    deadline = time.process_time() + budget_seconds
+    for _ in range(max_fragments):
+        if time.process_time() >= deadline:
+            break
+        rows = [i for i in range(len(er)) if i not in fixed]
+        used = set(fixed.values())
+        columns = [i for i in range(len(ep)) if i not in used]
+        if len(rows) < 3:
+            break
+        reactant = _molecule(a[np.ix_(rows, rows)], [er[i] for i in rows])
+        product = _molecule(b[np.ix_(columns, columns)], [ep[i] for i in columns])
+        parameters = rdFMCS.MCSParameters()
+        parameters.Timeout = 1
+        parameters.BondCompareParameters.RingMatchesRingOnly = True
+        parameters.AtomCompareParameters.RingMatchesRingOnly = True
+        callback = _FragmentProgress(deadline)
+        parameters.ProgressCallback = callback
+        result = rdFMCS.FindMCS([reactant, product], parameters)
+        canceled |= result.canceled
+        if result.numAtoms < 3:
+            break
+        query = Chem.MolFromSmarts(result.smartsString)
+        left_matches = reactant.GetSubstructMatches(query, uniquify=False, maxMatches=8)
+        right_matches = product.GetSubstructMatches(
+            query, uniquify=False, maxMatches=32
+        )
+        best = None
+        for left in left_matches:
+            for right in right_matches:
+                if len(left) != len(right) or len(left) < 3:
+                    continue
+                anchors = {rows[i]: columns[j] for i, j in zip(left, right)}
+                if any(er[i] != ep[j] for i, j in anchors.items()):
+                    continue
+                trial = working.copy()
+                for atom, image in anchors.items():
+                    owner = trial.index(image)
+                    trial[atom], trial[owner] = trial[owner], trial[atom]
+                trial_cost = 0.5 * float(np.abs(a - b[np.ix_(trial, trial)]).sum())
+                orientation_evaluations += 1
+                if best is None or trial_cost < best[0]:
+                    best = trial_cost, trial, anchors
+                if time.process_time() >= deadline:
+                    break
+            if time.process_time() >= deadline:
+                break
+        if best is None:
+            break
+        _, working, anchors = best
+        fixed.update(anchors)
+        sizes.append(len(anchors))
+    candidate = working
+    if fixed:
+        candidate, _ = improve_relaxed_seed_mapping(
+            a, b, er, ep, candidate, fixed_mapping=fixed
+        )
+        candidate, _ = improve_seed_mapping(a, b, er, ep, candidate)
+    old_cost = 0.5 * float(np.abs(a - b[np.ix_(mapping, mapping)]).sum())
+    new_cost = 0.5 * float(np.abs(a - b[np.ix_(candidate, candidate)]).sum())
+    if new_cost >= old_cost:
+        candidate, new_cost = list(mapping), old_cost
+    return candidate, {
+        "fragment_sizes": sizes,
+        "orientation_evaluations": orientation_evaluations,
+        "anchored_atoms": len(fixed),
+        "canceled": canceled,
+        "cost": new_cost,
+        "budget_seconds": budget_seconds,
+        "budget_clock": "process_cpu",
+        "fragment_search_seconds": _MAX_FRAGMENT_SEARCH_SECONDS,
+        "fragment_slice_scope": "from_first_progress_callback",
+    }