synkit 1.6.5__py3-none-win_amd64.whl

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

@@ -0,0 +1,266 @@
+"""Thin prepared-graph adapter for deterministic weighted SLAP in C++."""
+
+from __future__ import annotations
+
+import ctypes as ct
+import math
+import time
+from collections import Counter
+from dataclasses import dataclass
+from functools import lru_cache
+from numbers import Integral, Real
+from pathlib import Path
+
+import numpy as np
+
+from ..slap.lap import _adjacency_and_elements
+
+
+class _Statistics(ct.Structure):
+    _fields_ = (
+        [
+            (name, ct.c_int64)
+            for name in (
+                "states",
+                "lap_calls",
+                "fingerprints",
+                "candidates",
+                "best_proxy2",
+            )
+        ]
+        + [(name, ct.c_int32) for name in ("completed", "reason")]
+        + [(name, ct.c_double) for name in ("elapsed_seconds", "callback_seconds")]
+    )
+
+
+_INT = ct.POINTER(ct.c_int32)
+_LONG = ct.POINTER(ct.c_int64)
+_CALLBACK = ct.CFUNCTYPE(ct.c_int, _INT, ct.c_int64, ct.c_void_p)
+
+
+@lru_cache(maxsize=4)
+def _load(path):
+    library = ct.CDLL(str(Path(path).resolve()))
+    if library.synkit_mapper_abi() != 1:
+        raise RuntimeError(
+            "Unsupported native mapper ABI; rebuild with build_mapper_native"
+        )
+    library.synkit_mapper_error.restype = ct.c_char_p
+    library.synkit_slap_solve.argtypes = [
+        ct.c_int,
+        _LONG,
+        _LONG,
+        _INT,
+        _INT,
+        _INT,
+        ct.c_int,
+        ct.c_double,
+        ct.c_int64,
+        ct.c_int64,
+        _CALLBACK,
+        ct.c_void_p,
+        ct.POINTER(_Statistics),
+    ]
+    library.synkit_slap_solve.restype = ct.c_int
+    return library
+
+
+@dataclass(frozen=True)
+class NativeSlapResult:
+    """Reached heuristic candidates; finished SLAP is not exact enumeration."""
+
+    mappings: list[list[int]]
+    distances: list[float]
+    selected_mapping_count: int
+    heuristic_finished: bool
+    truncation_reason: str | None
+    elapsed_seconds: float
+    backend_statistics: dict
+    backend: str = "slap_cpp"
+    scope: str = "heuristic_candidates"
+    minimum_cost: None = None
+    optimality_proven: bool = False
+    complete: bool = False
+
+    @property
+    def selected_labeled_mapping_count(self):
+        return self.selected_mapping_count
+
+
+# Array ownership and output callbacks must span the complete native solve.
+def solve_slap(  # noqa: C901
+    lgp,
+    *,
+    library_path,
+    binary=False,
+    max_lap_fingerprints=10_000,
+    time_limit_seconds=None,
+    max_states=None,
+    max_mappings=None,
+    collect_mappings=True,
+    mapping_callback=None,
+):
+    """Run SLAP refinement, LAP/fingerprint exploration and splitting in C++.
+
+    This deterministic weighted variant preserves half-integer chemical weights.
+    It does not reproduce Python hash labels, LAP tie order, or historical
+    fractional-cost truncation. All algorithmic decisions and final rescoring
+    occur in C++; Python only prepares arrays and handles output callbacks.
+    The caller can use ordinary reaction parsing/classification via Mapper.
+    """
+    started = time.perf_counter()
+    if len(lgp) != 2:
+        raise ValueError("SLAP requires two endpoint graphs")
+    if not isinstance(binary, bool) or not isinstance(collect_mappings, bool):
+        raise TypeError("binary and collect_mappings must be boolean")
+    for name, value in (
+        ("max_lap_fingerprints", max_lap_fingerprints),
+        ("max_states", max_states),
+        ("max_mappings", max_mappings),
+    ):
+        if value is None and name != "max_lap_fingerprints":
+            continue
+        if (
+            isinstance(value, bool)
+            or not isinstance(value, Integral)
+            or not 1 <= value < 2**63
+        ):
+            raise ValueError(
+                f"{name} must be a positive integer"
+                + (" or None" if name != "max_lap_fingerprints" else "")
+            )
+    if max_lap_fingerprints >= 2**31:
+        raise ValueError("max_lap_fingerprints exceeds the C ABI integer range")
+    if time_limit_seconds is not None and (
+        isinstance(time_limit_seconds, bool)
+        or not isinstance(time_limit_seconds, Real)
+        or not math.isfinite(time_limit_seconds)
+        or time_limit_seconds < 0
+    ):
+        raise ValueError("time_limit_seconds must be finite and nonnegative")
+    if mapping_callback is not None and not callable(mapping_callback):
+        raise TypeError("mapping_callback must be callable")
+    matrices, elements = zip(*(_adjacency_and_elements(g, binary) for g in lgp))
+    if any(g.graph[i].get(i, 0) for g in lgp for i in range(len(g.labels))):
+        raise ValueError("Native SLAP requires loop-free graphs")
+    a, b = matrices
+    labels = [list(graph.labels) for graph in lgp]
+    n = len(labels[0])
+    if not 1 <= n <= 512 or a.shape != (n, n) or b.shape != (n, n):
+        raise ValueError(
+            "Native SLAP requires compatible endpoints with 1..512 vertices"
+        )
+    if Counter(labels[0]) != Counter(labels[1]) or Counter(elements[0]) != Counter(
+        elements[1]
+    ):
+        raise ValueError("SLAP endpoints must have equal atom-type inventories")
+    encoded_matrices = []
+    for matrix in matrices:
+        if (
+            not np.isfinite(matrix).all()
+            or np.any(matrix < 0)
+            or np.any(matrix > 500000)
+            or not np.array_equal(matrix, matrix.T)
+            or np.any(np.diag(matrix))
+            or not np.allclose(matrix * 2, np.rint(matrix * 2), atol=1e-9, rtol=0)
+        ):
+            raise ValueError(
+                "Native SLAP requires symmetric loop-free nonnegative half-integer weights"
+            )
+        encoded_matrices.append(
+            np.ascontiguousarray(np.rint(matrix * 2), dtype=np.int64)
+        )
+    registry = {}
+    encoded_labels = [
+        np.asarray(
+            [
+                registry.setdefault((x, element), len(registry))
+                for x, element in zip(side, atoms)
+            ],
+            dtype=np.int32,
+        )
+        for side, atoms in zip(labels, elements)
+    ]
+    if Counter(encoded_labels[0]) != Counter(encoded_labels[1]):
+        raise ValueError(
+            "Initial SLAP partitions have incompatible atom-type inventories"
+        )
+    # Preserve the Python matcher's special original-label rule. Reencoded
+    # numeric type 1 must not accidentally activate it for another atom type.
+    stop_flags = np.asarray([int(value == 1) for value in labels[0]], dtype=np.int32)
+    mappings, distances, errors = [], [], []
+
+    def receive(pointer, cost2, _userdata):
+        try:
+            mapping = list(pointer[:n])
+            if sorted(mapping) != list(range(n)) or any(
+                labels[0][i] != labels[1][j] or elements[0][i] != elements[1][j]
+                for i, j in enumerate(mapping)
+            ):
+                raise RuntimeError(
+                    "Native SLAP returned an incompatible atom bijection"
+                )
+            cost = cost2 / 2
+            if collect_mappings:
+                mappings.append(mapping)
+                distances.append(cost)
+            if mapping_callback is not None:
+                mapping_callback(mapping, cost)
+            return 0
+        except BaseException as error:  # noqa: BLE001 -- Never cross the C callback boundary.
+            errors.append(error)
+            return 1
+
+    callback = _CALLBACK(receive)
+    library = _load(str(Path(library_path).resolve()))
+    seconds = (
+        -1.0
+        if time_limit_seconds is None
+        else max(0, time_limit_seconds - (time.perf_counter() - started))
+    )
+    stats = _Statistics()
+    status = library.synkit_slap_solve(
+        n,
+        *(array.ctypes.data_as(_LONG) for array in encoded_matrices),
+        *(array.ctypes.data_as(_INT) for array in encoded_labels),
+        stop_flags.ctypes.data_as(_INT),
+        int(max_lap_fingerprints),
+        seconds,
+        -1 if max_states is None else int(max_states),
+        -1 if max_mappings is None else int(max_mappings),
+        callback,
+        None,
+        ct.byref(stats),
+    )
+    if errors:
+        raise errors[0]
+    if status:
+        raise RuntimeError(library.synkit_mapper_error().decode())
+    reasons = {
+        0: None,
+        1: "time_limit",
+        2: "max_states",
+        3: "max_mappings",
+        4: "callback",
+    }
+    statistics = {name: getattr(stats, name) for name, _ in stats._fields_}
+    statistics.update(
+        variant="deterministic_weighted_slap_v1",
+        cost_scale=2,
+        implementation="cpp_sequential_lap_fingerprints_refinement",
+        library_path=str(Path(library_path).resolve()),
+        max_lap_fingerprints=int(max_lap_fingerprints),
+        symmetry_policy="heuristic_stable_wl_split_representatives",
+    )
+    return NativeSlapResult(
+        mappings,
+        distances,
+        stats.candidates,
+        bool(stats.completed),
+        reasons[stats.reason],
+        time.perf_counter() - started,
+        statistics,
+    )
+
+
+__all__ = ["NativeSlapResult", "solve_slap"]

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

@@ -0,0 +1,67 @@
+"""Thin prepared-graph and reaction adapters for optional native solver engines.
+
+The common core loads prebuilt libraries explicitly. No engine is compiled on
+import, and an unavailable requested C++ backend never falls back to Python.
+"""
+
+from __future__ import annotations
+
+from .core import enumerate_core_mappings, map_reaction_core
+
+SOLVERS = frozenset({"cp_sat", "scip", "maxsat", "kmilp"})
+
+
+def _backend(solver):
+    if solver not in SOLVERS:
+        raise ValueError("solver must be 'cp_sat', 'scip', 'maxsat', or 'kmilp'")
+    return solver
+
+
+def enumerate_solver_mappings(lgp, *, library_path, solver="cp_sat", **options):
+    """Run a full-space or explicit-kernel engine through the doubled-CD ABI.
+
+    CP-SAT enumerates the objective-free satisfaction model after minimum
+    proof. SCIP and Open-WBO enumerate projected assignments with no-goods.
+    Native class construction is requested separately from raw enumeration.
+    """
+    return enumerate_core_mappings(
+        lgp, library_path=library_path, backend=_backend(solver), **options
+    )
+
+
+def map_reaction_solver(reaction, *, library_path, solver="cp_sat", **options):
+    """Use the common chemistry frontend with an explicitly selected engine."""
+    return map_reaction_core(
+        reaction, library_path=library_path, backend=_backend(solver), **options
+    )
+
+
+def enumerate_kernel_milp_mappings(lgp, *, library_path, allowed_domains, **options):
+    """Enumerate only the explicitly supplied compatible assignment kernel."""
+    if allowed_domains is None:
+        raise ValueError("KMILP requires explicit allowed_domains")
+    return enumerate_core_mappings(
+        lgp,
+        library_path=library_path,
+        backend="kmilp",
+        allowed_domains=allowed_domains,
+        **options,
+    )
+
+
+def map_reaction_kernel_milp(reaction, *, library_path, allowed_domains, **options):
+    """Map within explicit domains using native classification by default.
+
+    Set native_classification=False to select reference Python classification.
+    The proof and enumeration scope remains the supplied kernel.
+    """
+    if allowed_domains is None:
+        raise ValueError("KMILP requires explicit allowed_domains")
+    options.setdefault("native_classification", True)
+    return map_reaction_core(
+        reaction,
+        library_path=library_path,
+        backend="kmilp",
+        allowed_domains=allowed_domains,
+        **options,
+    )

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

@@ -0,0 +1,86 @@
+"""Preserve supplied geometry and assign complete modern CIP descriptors."""
+
+import json
+
+from rdkit import Chem
+from rdkit.Chem import rdCIPLabeler
+
+
+def assign_stereo(mol):
+    """Assign true CIP labels without legacy cleanup of supplied chiral tags.
+
+    Highly symmetric recursion is bounded and raises explicitly rather than
+    returning a silently incomplete stereo palette. No H atoms are created.
+    """
+    for obj in list(mol.GetAtoms()) + list(mol.GetBonds()):
+        if obj.HasProp("_CIPCode"):
+            obj.ClearProp("_CIPCode")
+    rdCIPLabeler.AssignCIPLabels(mol, maxRecursiveIterations=1000000)
+    return mol
+
+
+def stereo_smiles(mol, *, canonical=True):
+    """Serialize existing stereo without RDKit's lossy legacy cleanup pass."""
+    parameters = Chem.SmilesWriteParams()
+    parameters.canonical = canonical
+    parameters.doIsomericSmiles = True
+    parameters.cleanStereo = False
+    return Chem.MolToSmiles(mol, parameters)
+
+
+def endpoint_identity_key(mol):
+    """Canonical colored-graph identity, avoiding stereo-SMILES rank ambiguity.
+
+    Modern CIP is encoded as an ordinary node color. Bond state is encoded by
+    colored auxiliary vertices; these are identity-code gadgets, not H atoms or
+    chemical participants. The original palette accompanies the graph code.
+    """
+    assign_stereo(mol)
+    node_tokens = [
+        json.dumps(
+            (
+                "a",
+                a.GetAtomicNum(),
+                a.GetIsotope(),
+                a.GetFormalCharge(),
+                a.GetNumRadicalElectrons(),
+                a.GetTotalNumHs(),
+                a.GetIsAromatic(),
+                a.GetProp("_CIPCode") if a.HasProp("_CIPCode") else "",
+            )
+        )
+        for a in mol.GetAtoms()
+    ]
+    edge_tokens = [
+        json.dumps(("b", str(b.GetBondType()), str(b.GetStereo())))
+        for b in mol.GetBonds()
+    ]
+    directed = {Chem.BondType.DATIVE, Chem.BondType.DATIVEL, Chem.BondType.DATIVER}
+    tokens = sorted(set(node_tokens + edge_tokens + ['"tail"', '"head"']))
+    colors = {token: i + 1 for i, token in enumerate(tokens)}
+    graph = Chem.RWMol()
+
+    def add(token):
+        atom = Chem.Atom(0)
+        atom.SetNoImplicit(True)
+        atom.SetIsotope(colors[token])
+        return graph.AddAtom(atom)
+
+    for token in node_tokens:
+        add(token)
+    for bond, token in zip(mol.GetBonds(), edge_tokens):
+        i, j = bond.GetBeginAtomIdx(), bond.GetEndAtomIdx()
+        middle = add(token)
+        if bond.GetBondType() in directed:
+            tail, head = add('"tail"'), add('"head"')
+            graph.AddBond(i, tail, Chem.BondType.SINGLE)
+            graph.AddBond(tail, middle, Chem.BondType.SINGLE)
+            graph.AddBond(middle, head, Chem.BondType.SINGLE)
+            graph.AddBond(head, j, Chem.BondType.SINGLE)
+        else:
+            graph.AddBond(i, middle, Chem.BondType.SINGLE)
+            graph.AddBond(middle, j, Chem.BondType.SINGLE)
+    return json.dumps(
+        (tokens, Chem.MolToSmiles(graph, canonical=True, isomericSmiles=True)),
+        separators=(",", ":"),
+    )

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

@@ -0,0 +1,34 @@
+"""Native exhaustive DFS and binary edit-support enumeration adapters."""
+
+from .core import enumerate_core_mappings, map_reaction_core
+
+
+def enumerate_dfs_mappings(graphs, *, library_path, **options):
+    """Exhaustive compatible permutation traversal with no assignment bound."""
+    return enumerate_core_mappings(
+        graphs, library_path=library_path, backend="dfs", **options
+    )
+
+
+def enumerate_edit_mappings(graphs, *, library_path, **options):
+    """Enumerate binary edge-flip supports then exact typed graph isomorphisms.
+
+    This backend supports only binary bond presence. Supplying ``binary=True``
+    explicitly converts a weighted input to that separate objective; requesting
+    weighted EDIT without conversion returns unsupported from the native core.
+    """
+    return enumerate_core_mappings(
+        graphs, library_path=library_path, backend="edit", **options
+    )
+
+
+def map_reaction_dfs(reaction, *, library_path, **options):
+    return map_reaction_core(
+        reaction, library_path=library_path, backend="dfs", **options
+    )
+
+
+def map_reaction_edit(reaction, *, library_path, **options):
+    return map_reaction_core(
+        reaction, library_path=library_path, backend="edit", **options
+    )

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

@@ -0,0 +1,91 @@
+"""Opt-in canonical construction traversal and its measured symmetry work."""
+
+import ctypes as ct
+from pathlib import Path
+
+
+class _Profile(ct.Structure):
+    _fields_ = [
+        (name, ct.c_int64)
+        for name in (
+            "discovery_nodes",
+            "subgroup_order",
+            "canonical_calls",
+            "augmentations",
+            "canonical_rejections",
+            "bound_rejections",
+        )
+    ] + [
+        ("identity_fallback_r", ct.c_int32),
+        ("identity_fallback_p", ct.c_int32),
+        ("discovery_seconds", ct.c_double),
+        ("canonical_seconds", ct.c_double),
+    ]
+
+
+class _ProfileV2(ct.Structure):
+    _fields_ = (
+        [("base", _Profile)]
+        + [
+            (name, ct.c_int64)
+            for name in (
+                "twin_blocks_r",
+                "twin_blocks_p",
+                "quotient_order_r",
+                "quotient_order_p",
+                "bound_calls",
+                "seed_cost2",
+            )
+        ]
+        + [("bound_seconds", ct.c_double), ("seed_seconds", ct.c_double)]
+    )
+
+
+def cpabs_profile(library_path):
+    """Read same-thread diagnostics from the latest cPABS run in this library."""
+    library = ct.CDLL(str(Path(library_path).resolve()))
+    function = library.synkit_mapper_cpabs_profile
+    function.argtypes = [ct.POINTER(_Profile)]
+    function.restype = None
+    value = _Profile()
+    function(ct.byref(value))
+    result = {name: getattr(value, name) for name, _ in _Profile._fields_}
+    if hasattr(library, "synkit_mapper_cpabs_profile_v2"):
+        function = library.synkit_mapper_cpabs_profile_v2
+        function.argtypes = [ct.POINTER(_ProfileV2)]
+        function.restype = None
+        detail = _ProfileV2()
+        function(ct.byref(detail))
+        result.update(
+            {
+                name: getattr(detail, name)
+                for name, _ in _ProfileV2._fields_
+                if name != "base"
+            }
+        )
+    return result
+
+
+def enumerate_cpabs_mappings(lgp, *, library_path, **kwargs):
+    """Run the complete canonical-parent traversal through the shared adapter.
+
+    Symmetry pruning is explicitly enabled with ``symmetry=True``. The method
+    changes the extension tree to unordered partial matchings; it does not add
+    a canonical deletion filter to fixed/adaptive source-row PABS. Exact twin
+    factors remain active even when quotient-group discovery is capped.
+    Raw output enumerates subgroup orbits and requires class deduplication.
+    """
+    from .core import enumerate_core_mappings
+
+    return enumerate_core_mappings(
+        lgp, library_path=library_path, backend="cpabs", **kwargs
+    )
+
+
+def map_reaction_cpabs(reaction, *, library_path, **kwargs):
+    """Use the shared chemistry frontend with the explicit native variant."""
+    from .core import map_reaction_core
+
+    return map_reaction_core(
+        reaction, backend="cpabs", library_path=library_path, **kwargs
+    )

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

@@ -0,0 +1,29 @@
+"""
+Sequential linear-assignment (SLAP) matching and LAP-based utilities.
+
+LAP means linear assignment problem: match reactant atoms to product atoms
+using a matrix of pair costs. SLAP combines successive LAP decisions with
+WL graph-label refinement to construct heuristic graph mappings. It is the
+default solver used by ``AAMapper.map_smiles``. The utility functions here
+also serve exact solvers; importing a LAP helper does not select the SLAP
+matching workflow.
+
+Submodules
+----------
+sequential
+    :class:`GraphMatcher`: iterative WL-label refinement with LAP branching.
+lap
+    LAP utilities, :func:`chemical_distance`, :func:`dual_lap_lower_bound`,
+    and :func:`recover_mapping`.
+"""
+
+from .sequential import GraphMatcher
+from .lap import solve_lap, recover_mapping, chemical_distance, dual_lap_lower_bound
+
+__all__ = [
+    "GraphMatcher",
+    "solve_lap",
+    "recover_mapping",
+    "chemical_distance",
+    "dual_lap_lower_bound",
+]