synkit 1.6.5__py3-none-win_amd64.whl

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

@@ -0,0 +1,181 @@
+"""Bounded typed quadratic-overlap relaxation for feasible search seeds."""
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+from scipy.sparse import csr_matrix
+
+
+def improve_relaxed_seed_mapping(  # noqa: C901
+    a, b, er, ep, mapping, *, iterations=40, fixed_mapping=None
+):
+    """Find a better typed bijection using four bounded relaxed starts.
+
+    At permutation vertices, layered same-sign bond overlap equals a constant
+    minus chemical distance. Sparse matrix products give its quadratic gradient;
+    element-blocked LAP steps and quadratic line searches optimize a doubly
+    stochastic relaxation. Only a fully evaluated feasible mapping is returned.
+    The relaxation is a heuristic, never an optimality certificate or a domain
+    restriction. Size/layer limits bound this optional preprocessing.
+    """
+    n = len(mapping)
+    fixed = dict(fixed_mapping or {})
+    if any(i < 0 or i >= n or mapping[i] != image for i, image in fixed.items()):
+        raise ValueError("seed must agree with heuristic anchors")
+    if sorted(mapping) != list(range(len(er))) or any(
+        er[i] != ep[image] for i, image in enumerate(mapping)
+    ):
+        raise ValueError("seed must be a complete element-compatible bijection")
+    if n > 256 or not np.isfinite(a).all() or not np.isfinite(b).all():
+        return list(mapping), {"iterations": 0, "skipped": "size_or_nonfinite_input"}
+    if len(np.unique(np.concatenate((a.ravel(), b.ravel())))) > 16:
+        return list(mapping), {"iterations": 0, "skipped": "weight_layer_limit"}
+    fixed_images = set(fixed.values())
+    blocks = [
+        (
+            np.asarray(
+                [i for i in range(n) if er[i] == e and i not in fixed], dtype=int
+            ),
+            np.asarray(
+                [j for j in range(n) if ep[j] == e and j not in fixed_images], dtype=int
+            ),
+        )
+        for e in sorted(set(er))
+    ]
+    blocks = [(rows, cols) for rows, cols in blocks if len(rows)]
+    layers = []
+    for sign in (1, -1):
+        values = np.unique(np.concatenate(((sign * a).ravel(), (sign * b).ravel())))
+        previous = 0.0
+        for value in values[values > 0]:
+            ar = csr_matrix((sign * a >= value).astype(float))
+            bp = csr_matrix((sign * b >= value).astype(float))
+            layers.append((float(value - previous), ar, bp, ar.T.tocsr(), bp.T.tocsr()))
+            previous = value
+
+    def gradient(p):
+        g = np.zeros_like(p)
+        for weight, ar, bp, at, bt in layers:
+            g += weight * ((bp @ (ar @ p).T).T + (bt @ (at @ p).T).T)
+        return g
+
+    def project(p):
+        result = np.asarray(mapping).copy()
+        for rows, cols in blocks:
+            i, j = linear_sum_assignment(-p[np.ix_(rows, cols)])
+            result[rows[i]] = cols[j]
+        return result
+
+    def cost(m):
+        return 0.5 * float(np.abs(a - b[np.ix_(m, m)]).sum())
+
+    best = np.asarray(mapping).copy()
+    best_cost = cost(best)
+    identity = np.zeros((n, n))
+    identity[np.arange(n), best] = 1
+    uniform = np.zeros((n, n))
+    for i, j in fixed.items():
+        uniform[i, j] = 1
+    for rows, cols in blocks:
+        uniform[np.ix_(rows, cols)] = 1 / len(cols)
+    count = 0
+    for mixing in (0.95, 0.7, 0.3, 0.0):
+        p = mixing * identity + (1 - mixing) * uniform
+        for _ in range(iterations):
+            g = gradient(p)
+            candidate = project(g)
+            candidate_cost = cost(candidate)
+            if candidate_cost < best_cost:
+                best, best_cost = candidate.copy(), candidate_cost
+            q = np.zeros_like(p)
+            q[np.arange(n), candidate] = 1
+            d = q - p
+            slope = float((g * d).sum())
+            curve = 0.5 * float((d * gradient(d)).sum())
+            t = (
+                min(1.0, max(0.0, -slope / (2 * curve)))
+                if curve < 0
+                else float(slope + curve > 0)
+            )
+            count += 1
+            if t < 1e-8 or np.linalg.norm(d) < 1e-8:
+                break
+            p += t * d
+        candidate = project(p)
+        candidate_cost = cost(candidate)
+        if candidate_cost < best_cost:
+            best, best_cost = candidate.copy(), candidate_cost
+    return best.tolist(), {
+        "cost": best_cost,
+        "iterations": count,
+        "max_iterations_per_start": iterations,
+        "starts": 4,
+    }
+
+
+def refine_seed_mapping(a, b, er, ep, mapping, *, restarts=24):
+    """Polish relaxed seeds and escape local basins with bounded typed shakes.
+
+    A graph-only profile lower bound stops optional work once the incumbent
+    reaches it. This stopping check makes no proof claim; exact search follows.
+    Deterministic perturbations change only the heuristic seed, never domains.
+    """
+    from ..distance_search.bounds import atom_profile_costs, blocked_assignment_extreme
+    from .seed import improve_seed_mapping
+
+    best, initial = improve_relaxed_seed_mapping(a, b, er, ep, mapping)
+    if "skipped" in initial:
+        return best, initial
+    best, _ = improve_seed_mapping(a, b, er, ep, best)
+    best = np.asarray(best, dtype=int)
+
+    def cost(m):
+        return 0.5 * float(np.abs(a - b[np.ix_(m, m)]).sum())
+
+    best_cost = cost(best)
+    bound = blocked_assignment_extreme(
+        atom_profile_costs(a, b, er, ep), range(len(er)), range(len(ep)), er, ep
+    )
+    statistics = {
+        "initial": initial,
+        "profile_lower_bound": bound,
+        "restarts": 0,
+        "refinements": 0,
+        "improvements": 0,
+    }
+    for _ in range(2):
+        if best_cost <= bound + 1e-9:
+            break
+        candidate, _ = improve_relaxed_seed_mapping(a, b, er, ep, best.tolist())
+        candidate, _ = improve_seed_mapping(a, b, er, ep, candidate)
+        candidate_cost = cost(candidate)
+        statistics["refinements"] += 1
+        if candidate_cost >= best_cost:
+            break
+        best, best_cost = np.asarray(candidate), candidate_cost
+        statistics["improvements"] += 1
+    left, right = np.triu_indices(len(er), 1)
+    labels = np.asarray(er)
+    compatible = labels[left] == labels[right]
+    left, right = left[compatible], right[compatible]
+    rng = np.random.default_rng(0)
+    for attempt in range(restarts):
+        if not len(left) or best_cost <= bound + 1e-9:
+            break
+        scores = np.abs(a - b[np.ix_(best, best)]).sum(axis=1)
+        weights = scores[left] + scores[right] + 0.1
+        weights /= weights.sum()
+        candidate = best.copy()
+        for index in rng.choice(
+            len(left), size=min(2 + attempt % 5, len(left)), replace=False, p=weights
+        ):
+            i, j = left[index], right[index]
+            candidate[i], candidate[j] = candidate[j], candidate[i]
+        candidate, _ = improve_relaxed_seed_mapping(a, b, er, ep, candidate.tolist())
+        candidate, _ = improve_seed_mapping(a, b, er, ep, candidate)
+        candidate_cost = cost(candidate)
+        statistics["restarts"] += 1
+        if candidate_cost < best_cost:
+            best, best_cost = np.asarray(candidate), candidate_cost
+            statistics["improvements"] += 1
+    statistics["cost"] = best_cost
+    return best.tolist(), statistics

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

@@ -0,0 +1,223 @@
+"""Memory-bounded permutation-group helpers for exact mapper branching."""
+
+from __future__ import annotations
+
+_MAX_STABILIZER_GENERATORS = 512
+_MAX_SCHREIER_WORK = 100_000
+
+
+def _identity(size):
+    return tuple(range(size))
+
+
+def _compose(first, second):
+    """Return ``second`` after ``first`` for image-tuple permutations."""
+    return tuple(second[first[index]] for index in range(len(first)))
+
+
+def _inverse(permutation):
+    inverse = [0] * len(permutation)
+    for source, image in enumerate(permutation):
+        inverse[image] = source
+    return tuple(inverse)
+
+
+def _deduplicate_generators(generators):
+    generators = tuple(tuple(permutation) for permutation in generators)
+    if not generators:
+        return ()
+    identity = _identity(len(generators[0]))
+    return tuple(dict.fromkeys(g for g in generators if g != identity))
+
+
+def _point_stabilizer_data(
+    generators,
+    point,
+    *,
+    max_generators=_MAX_STABILIZER_GENERATORS,
+    max_work=_MAX_SCHREIER_WORK,
+):
+    """Return stabilizer generators, orbit size, and budget-completion status."""
+    seeds = _deduplicate_generators(generators)
+    if not seeds:
+        return (), 1, True
+    if all(generator[point] == point for generator in seeds):
+        # Identity transports reproduce the input subgroup; preserve budgets.
+        if len(seeds) > max_work or len(seeds) > max_generators:
+            return (), 1, False
+        return seeds, 1, True
+    size = len(seeds[0])
+    identity = _identity(size)
+    transversals = {point: identity}
+    pending = [point]
+    work = 0
+    while pending:
+        current = pending.pop()
+        current_transversal = transversals[current]
+        for generator in seeds:
+            work += 1
+            if work > max_work:
+                return (), len(transversals), False
+            image = generator[current]
+            if image not in transversals:
+                transversals[image] = _compose(current_transversal, generator)
+                pending.append(image)
+
+    inverses = {image: _inverse(transport) for image, transport in transversals.items()}
+    stabilizers = {}
+    for current, current_transversal in transversals.items():
+        for generator in seeds:
+            image = generator[current]
+            schreier = _compose(
+                _compose(current_transversal, generator),
+                inverses[image],
+            )
+            if schreier == identity:
+                continue
+            stabilizers.setdefault(schreier, None)
+            if len(stabilizers) > max_generators:
+                return (), len(transversals), False
+    return tuple(stabilizers), len(transversals), True
+
+
+def point_stabilizer_generators_checked(
+    generators,
+    point,
+    *,
+    max_generators=_MAX_STABILIZER_GENERATORS,
+    max_work=_MAX_SCHREIER_WORK,
+):
+    """Return ``(generators, complete)`` for the subgroup fixing ``point``.
+
+    ``complete=False`` means the bounded Schreier construction deliberately
+    disabled deeper symmetry pruning.  Callers that only need safe pruning may
+    ignore the flag; callers deriving orbit multiplicities must retain it.
+    """
+    stabilizers, _, complete = _point_stabilizer_data(
+        generators,
+        point,
+        max_generators=max_generators,
+        max_work=max_work,
+    )
+    return stabilizers, complete
+
+
+def point_stabilizer_generators(
+    generators,
+    point,
+    *,
+    max_generators=_MAX_STABILIZER_GENERATORS,
+    max_work=_MAX_SCHREIER_WORK,
+):
+    """Return Schreier generators fixing ``point``, or identity on budget exit.
+
+    Returning no generators on a work-budget exit is conservative: subsequent
+    levels perform less symmetry pruning but cannot lose a mapping.
+    """
+    stabilizers, _ = point_stabilizer_generators_checked(
+        generators,
+        point,
+        max_generators=max_generators,
+        max_work=max_work,
+    )
+    return stabilizers
+
+
+def permutation_group_order(
+    generators,
+    *,
+    max_generators=_MAX_STABILIZER_GENERATORS,
+    max_work=_MAX_SCHREIER_WORK,
+):
+    """Return the generated subgroup order without enumerating its elements.
+
+    Orbit--stabilizer is applied along a deterministic point chain.  ``None``
+    is returned on a Schreier work-budget exit, so callers never promote a
+    partial stabilizer calculation to an exact labeled-solution count.
+    """
+    stabilizers = _deduplicate_generators(generators)
+    if not stabilizers:
+        return 1
+    size = len(stabilizers[0])
+    order = 1
+    for point in range(size):
+        stabilizers, orbit_size, complete = _point_stabilizer_data(
+            stabilizers,
+            point,
+            max_generators=max_generators,
+            max_work=max_work,
+        )
+        if not complete:
+            return None
+        order *= orbit_size
+        if not stabilizers:
+            break
+    return order
+
+
+def orbital_candidate_witnesses(candidates, generators):
+    """Map candidates to ``None`` representatives or exact pruning witnesses."""
+    candidates = tuple(sorted(candidates))
+    seeds = _deduplicate_generators(generators)
+    if not seeds:
+        return {candidate: None for candidate in candidates}
+
+    size = len(seeds[0])
+    identity = _identity(size)
+    candidate_set = set(candidates)
+    seen = set()
+    witnesses = {}
+    for representative in candidates:
+        if representative in seen:
+            continue
+        transversals = {representative: identity}
+        pending = [representative]
+        while pending:
+            current = pending.pop()
+            current_transversal = transversals[current]
+            for generator in seeds:
+                image = generator[current]
+                if image in transversals:
+                    continue
+                transversals[image] = _compose(current_transversal, generator)
+                pending.append(image)
+        orbit = candidate_set.intersection(transversals)
+        seen.update(orbit)
+        witnesses[representative] = None
+        for candidate in orbit:
+            if candidate != representative:
+                # The inverse transporter maps the rejected candidate to the
+                # least representative while fixing the existing prefix.
+                witnesses[candidate] = _inverse(transversals[candidate])
+    return witnesses
+
+
+def largest_cyclic_subgroup(permutations, *, max_order=256):
+    """Return the largest fully enumerated cyclic subgroup found safely."""
+    permutations = tuple(tuple(permutation) for permutation in permutations)
+    if not permutations:
+        return ()
+    identity = _identity(len(permutations[0]))
+    best = (identity,)
+    for generator in permutations:
+        powers = [identity]
+        current = identity
+        while len(powers) <= max_order:
+            current = _compose(current, generator)
+            if current == identity:
+                if len(powers) > len(best):
+                    best = tuple(powers)
+                break
+            if current in powers:
+                break
+            powers.append(current)
+    return best
+
+
+__all__ = [
+    "largest_cyclic_subgroup",
+    "orbital_candidate_witnesses",
+    "permutation_group_order",
+    "point_stabilizer_generators",
+    "point_stabilizer_generators_checked",
+]

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

@@ -0,0 +1,4 @@
+"""Explicit native-library builds and thin adapters for mapper algorithms.
+
+Importing this package never compiles code or loads an optional shared library.
+"""

synkit/Chem/Mapper/solvers/native/assignment.py

@@ -0,0 +1,99 @@
+"""Native assignment B&B and explicitly restricted uncertainty kernels."""
+
+import ctypes as ct
+from numbers import Integral
+
+import numpy as np
+
+from .core import enumerate_core_mappings
+from .runtime import INT, load_core
+
+
+def kernel_domains(mappings, types_r, types_p, *, library_path, close_block_size=4):
+    """Build restricted domains in C++ from compatible supplied candidates.
+
+    Agreement among heuristic candidates is not a global-optimality proof.
+    """
+    left, right = list(types_r), list(types_p)
+    n = len(left)
+    rows = list(mappings)
+    if not 1 <= n <= 1024 or len(right) != n or not rows:
+        raise ValueError(
+            "Kernel requires nonempty equal endpoint inventories and candidates"
+        )
+    if any(len(row) != n for row in rows) or any(
+        isinstance(j, bool) or not isinstance(j, Integral) or not 0 <= j < n
+        for row in rows
+        for j in row
+    ):
+        raise ValueError("Kernel candidates require valid integer image indices")
+    if (
+        isinstance(close_block_size, bool)
+        or not isinstance(close_block_size, Integral)
+        or not 0 <= close_block_size < 2**31
+    ):
+        raise ValueError("close_block_size must be a nonnegative C ABI integer")
+    registry = {}
+    codes = [
+        np.asarray(
+            [registry.setdefault(v, len(registry)) for v in side], dtype=np.int32
+        )
+        for side in (left, right)
+    ]
+    permutations = np.ascontiguousarray(rows, dtype=np.int32)
+    domains = np.zeros((n, n), dtype=np.uint8)
+    lib = load_core(str(library_path))
+    if not hasattr(lib, "synkit_mapper_kernel_domains"):
+        raise RuntimeError("Library lacks native uncertainty-kernel construction")
+    lib.synkit_mapper_assignment_error.restype = ct.c_char_p
+    lib.synkit_mapper_kernel_domains.argtypes = [
+        ct.c_int32,
+        ct.c_int64,
+        INT,
+        INT,
+        INT,
+        ct.c_int32,
+        ct.POINTER(ct.c_uint8),
+    ]
+    result = lib.synkit_mapper_kernel_domains(
+        n,
+        len(rows),
+        permutations.ctypes.data_as(INT),
+        *[v.ctypes.data_as(INT) for v in codes],
+        close_block_size,
+        domains.ctypes.data_as(ct.POINTER(ct.c_uint8)),
+    )
+    if result:
+        raise ValueError(lib.synkit_mapper_assignment_error().decode())
+    return domains
+
+
+def enumerate_assignment_mappings(lgp, *, library_path, **options):
+    return enumerate_core_mappings(
+        lgp, library_path=library_path, backend="abb", **options
+    )
+
+
+def enumerate_kernel_mappings(kernel, *, library_path, backend="kbb", **options):
+    """Solve an existing Kernel in its fixed/uncertain domains, entirely natively."""
+    if backend not in {"kbb", "kmilp"}:
+        raise ValueError("Kernel backend must be kbb or kmilp")
+    n = len(kernel.lgp[0].labels)
+    allowed = np.zeros((n, n), dtype=np.uint8)
+    for i, j in kernel.fixed_mapping.items():
+        allowed[i, j] = 1
+    for position, i in enumerate(kernel.r_idx):
+        candidates = (
+            kernel.p_idx
+            if kernel.candidate_images is None
+            else kernel.candidate_images[position]
+        )
+        allowed[i, candidates] = 1
+    return enumerate_core_mappings(
+        kernel.lgp,
+        library_path=library_path,
+        backend=backend,
+        binary=kernel.binary,
+        allowed_domains=allowed,
+        **options,
+    )

synkit/Chem/Mapper/solvers/native/astar.py

@@ -0,0 +1,22 @@
+"""Thin adapter for the full-space native best-first weighted A* backend."""
+
+from .core import enumerate_core_mappings, map_reaction_core
+
+
+def enumerate_astar_mappings(graphs, *, library_path, **options):
+    """Enumerate the requested labeled shell; frontend classifies exact ITSs.
+
+    All search decisions and admissible assignment bounds execute in C++.
+    The backend uses no symmetry pruning. Its memory cap measures accounted
+    frontier allocations, not whole-process RSS. A weighted chemical objective
+    is optimized with heuristic multiplier one, preserving exactness.
+    """
+    return enumerate_core_mappings(
+        graphs, library_path=library_path, backend="astar", **options
+    )
+
+
+def map_reaction_astar(reaction, *, library_path, **options):
+    return map_reaction_core(
+        reaction, library_path=library_path, backend="astar", **options
+    )