synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/solvers/exact/kernel_solvers/enumeration_result.py

@@ -0,0 +1,30 @@
+"""Result container and graph-label reconstruction for exact enumeration."""
+
+from dataclasses import dataclass
+from typing import Dict, List
+
+
+@dataclass
+class EnumerationResult:
+    """Symmetry-distinct exact optima for a kernel."""
+
+    cost: float
+    mappings: List[List[int]]
+    sub_mappings: List[Dict[int, int]]
+    results: List[dict]
+    proven_optimal: bool = True
+    enumeration_complete: bool = True
+
+
+def mapping_to_lgp(lgp, mapping):
+    """Return a resolved graph pair whose labels encode ``mapping``."""
+    out = [lgp[0].copy(), lgp[1].copy()]
+    labels0 = list(range(1, len(mapping) + 1))
+    labels1 = [0] * len(mapping)
+    for i, p in enumerate(mapping):
+        labels1[p] = i + 1
+    out[0].labels = labels0
+    out[1].labels = labels1
+    out[0].build_label2idxs()
+    out[1].build_label2idxs()
+    return out

synkit/Chem/Mapper/solvers/exact/kernel_solvers/kernel.py

@@ -0,0 +1,256 @@
+"""
+Reduced uncertainty subproblems derived from supplied SLAP mapping results.
+
+The supplied heuristic mappings determine which atom assignments agree and
+which vary. ``extract_kernel`` holds agreeing assignments fixed and builds
+candidate domains for the remaining atoms, with fallback label-class domains
+and closure of small same-element uncertain blocks where applicable. Agreement
+among supplied SLAP results is not a proof that an assignment is forced across
+all global optima.
+
+``Kernel`` is this reduced problem, not a mapping algorithm. Branch-and-bound
+or optional MILP solves its remaining assignments exactly while respecting the
+fixed assignments and candidate domains. ``apply_kernel_solution`` combines
+the subsolution with the fixed part. An exact kernel solution is optimal within
+the supplied restrictions; a full-space global optimum requires a full-space
+search or an independent global proof. WL colour agreement alone is not used
+as a certainty test because a reaction can change an atom's environment.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Set
+
+from ...slap.lap import recover_mapping
+
+_MAX_CLOSED_ELEMENT_BLOCK = 4
+
+
+@dataclass
+class Kernel:
+    """Reduced atom-assignment problem with fixed assignments and candidate domains.
+
+    :ivar r_idx, p_idx: Original reactant/product atom indices that remain uncertain.
+    :vartype r_idx, p_idx: list[int]
+    :ivar r_colors, p_colors: Atom type (atomic number) of each kernel atom; reactant atom
+                              ``r_idx[a]`` may map to product atom ``p_idx[b]`` only if
+                              ``r_colors[a] == p_colors[b]``.
+    :vartype r_colors, p_colors: list[int]
+    :ivar fixed_mapping: Assignments held fixed: original reactant index -> product index.
+    :vartype fixed_mapping: dict[int, int]
+    :ivar candidate_images: Allowed product atom indices for each uncertain atom in ``r_idx``.
+                            Extraction derives these from supplied SLAP results, with fallback
+                            label-class domains and closure of small uncertain element blocks.
+                            The exact kernel solver stays inside the supplied candidate sets.
+    :vartype candidate_images: list[list[int]]
+    :ivar lgp: The original reactant/product graph pair (for adjacency look-ups).
+    :vartype lgp: list
+    :ivar binary: Whether bond orders are binarised.
+    :vartype binary: bool
+    """
+
+    r_idx: List[int]
+    p_idx: List[int]
+    r_colors: List[int]
+    p_colors: List[int]
+    fixed_mapping: Dict[int, int]
+    lgp: list
+    binary: bool = False
+    candidate_images: Optional[List[List[int]]] = None
+
+    @property
+    def size(self) -> int:
+        """Number of uncertain reactant atoms (== uncertain product atoms)."""
+        return len(self.r_idx)
+
+    @property
+    def is_trivial(self) -> bool:
+        """True when the supplied kernel has no uncertain atoms to optimize."""
+        return self.size == 0
+
+
+def _atomic_numbers(lg):
+    nums = lg.props.get("atomic numbers")
+    if nums is None:
+        nums = list(lg.labels)
+    return list(nums)
+
+
+def extract_kernel(results, lgp, binary=False):
+    """Extract a restricted uncertainty problem from supplied SLAP results.
+
+    Agreement among the supplied heuristic mappings defines fixed assignments;
+    variation defines uncertain domains. These restrictions are local to the
+    supplied results and do not establish certainty over every global optimum.
+
+    :param results: Best observed results from :meth:`GraphMatcher.get_maps`; each must carry a
+                    fully resolved ``"lgp"`` graph pair.
+    :type results: list[dict]
+    :param lgp: The original reactant/product graph pair (equal atom counts).
+    :type lgp: list[LabeledGraph]
+    :param binary: Whether bond orders are binarised (recorded on the kernel).
+    :type binary: bool, optional
+
+    :rtype: Kernel
+    """
+    n = len(lgp[0].labels)
+    mappings = [recover_mapping(r["lgp"]) for r in results]
+    if not mappings:
+        mappings = [list(range(n))]
+
+    images = [set(m[i] for m in mappings) for i in range(n)]
+    elements_r = _atomic_numbers(lgp[0])
+    elements_p = _atomic_numbers(lgp[1])
+    fixed_mapping, r_idx, p_idx, candidate_images = _compact_kernel_parts(images)
+
+    if not _kernel_parts_are_valid(fixed_mapping, r_idx, p_idx, candidate_images):
+        images = _label_class_candidate_images(results, lgp, elements_r, elements_p)
+        fixed_mapping, r_idx, p_idx, candidate_images = _propagated_kernel_parts(images)
+
+    candidate_images = _close_small_element_blocks(
+        r_idx,
+        p_idx,
+        candidate_images,
+        elements_r,
+        elements_p,
+    )
+
+    return Kernel(
+        r_idx=r_idx,
+        p_idx=p_idx,
+        r_colors=[elements_r[i] for i in r_idx],
+        p_colors=[elements_p[p] for p in p_idx],
+        fixed_mapping=fixed_mapping,
+        lgp=lgp,
+        binary=binary,
+        candidate_images=candidate_images,
+    )
+
+
+def _compact_kernel_parts(images):
+    fixed_mapping = {}
+    r_idx = []
+    for i, candidates in enumerate(images):
+        if len(candidates) == 1:
+            fixed_mapping[i] = next(iter(candidates))
+        else:
+            r_idx.append(i)
+
+    p_set = set()
+    for i in r_idx:
+        p_set.update(images[i])
+    p_idx = sorted(p_set)
+    candidate_images = [sorted(images[i]) for i in r_idx]
+    return fixed_mapping, r_idx, p_idx, candidate_images
+
+
+def _kernel_parts_are_valid(fixed_mapping, r_idx, p_idx, candidate_images):
+    if len(p_idx) != len(r_idx):
+        return False
+    p_set = set(p_idx)
+    return all(
+        candidates and set(candidates) <= p_set for candidates in candidate_images
+    )
+
+
+def _label_class_candidate_images(results, lgp, elements_r, elements_p):
+    n = len(lgp[0].labels)
+    images: List[Set[int]] = [set() for _ in range(n)]
+    for result in results:
+        left, right = result["lgp"]
+        fallback = recover_mapping(result["lgp"])
+        for i, label in enumerate(left.labels):
+            for p in right.label2idxs.get(label, []):
+                if 0 <= p < n and elements_r[i] == elements_p[p]:
+                    images[i].add(p)
+            p = fallback[i] if i < len(fallback) else -1
+            if 0 <= p < n and elements_r[i] == elements_p[p]:
+                images[i].add(p)
+    if not results:
+        images = [{i} for i in range(n)]
+    return images
+
+
+def _propagated_kernel_parts(images):
+    images = [set(candidates) for candidates in images]
+    fixed_mapping = {}
+    unresolved = set(range(len(images)))
+    used_products = set()
+    changed = True
+    while changed:
+        changed = False
+        for i in list(unresolved):
+            images[i].difference_update(used_products)
+            if len(images[i]) != 1:
+                continue
+            p = next(iter(images[i]))
+            fixed_mapping[i] = p
+            used_products.add(p)
+            unresolved.remove(i)
+            for j in unresolved:
+                images[j].discard(p)
+            changed = True
+            break
+
+    r_idx = sorted(unresolved)
+    p_set = set()
+    for i in r_idx:
+        p_set.update(images[i])
+    p_idx = sorted(p_set)
+    candidate_images = [sorted(images[i]) for i in r_idx]
+    return fixed_mapping, r_idx, p_idx, candidate_images
+
+
+def _close_small_element_blocks(r_idx, p_idx, candidate_images, elements_r, elements_p):
+    """Let exact mode fully permute small same-element uncertain blocks."""
+    if not candidate_images:
+        return candidate_images
+
+    out = [sorted(set(candidates)) for candidates in candidate_images]
+    positions_by_element = {}
+    products_by_element = {}
+    for a, i in enumerate(r_idx):
+        positions_by_element.setdefault(elements_r[i], []).append(a)
+    for p in p_idx:
+        products_by_element.setdefault(elements_p[p], []).append(p)
+
+    for element, positions in positions_by_element.items():
+        pool = sorted(products_by_element.get(element, []))
+        if (
+            not pool
+            or len(pool) != len(positions)
+            or len(pool) > _MAX_CLOSED_ELEMENT_BLOCK
+        ):
+            continue
+        pool_set = set(pool)
+        if any(not set(out[a]) <= pool_set for a in positions):
+            continue
+        for a in positions:
+            out[a] = pool
+    return out
+
+
+def apply_kernel_solution(kernel, sub_mapping):
+    """Combine a kernel sub-mapping with its fixed assignments into a full mapping.
+
+    :param kernel:
+    :type kernel: Kernel
+    :param sub_mapping: Mapping over kernel positions: either a dict ``a -> b`` (positions into
+                        ``kernel.r_idx`` / ``kernel.p_idx``) or a sequence ``sub_mapping[a] = b``.
+    :type sub_mapping: dict[int, int] or sequence[int]
+
+    :return: ``mapping[i] = p`` over original atom indices.
+    :rtype: list[int]
+    """
+    n = len(kernel.lgp[0].labels)
+    mapping = [-1] * n
+    for i, p in kernel.fixed_mapping.items():
+        mapping[i] = p
+    if isinstance(sub_mapping, dict):
+        items = sub_mapping.items()
+    else:
+        items = enumerate(sub_mapping)
+    for a, b in items:
+        mapping[kernel.r_idx[a]] = kernel.p_idx[b]
+    return mapping

synkit/Chem/Mapper/solvers/exact/kernel_solvers/milp.py

@@ -0,0 +1,194 @@
+"""
+Exact MILP/QAP formulation of the kernel mapping problem (PuLP + CBC backend).
+
+The chemical-distance objective is a quadratic assignment problem (QAP). Over the
+small uncertainty-region kernel (:mod:`mapper.exact.kernel`) we write it as a
+Koopmans-Beckmann QAP and linearise it to a mixed-integer linear program:
+
+* binary ``x[a,b] = 1`` iff kernel reactant atom ``a`` maps to kernel product
+  atom ``b`` (created only for element-compatible pairs);
+* assignment constraints ``sum_b x[a,b] = 1`` and ``sum_a x[a,b] = 1``;
+* products ``y[a,b,a',b'] = x[a,b] * x[a',b']`` linearised by
+  ``y <= x[a,b]``, ``y <= x[a',b']``, ``y >= x[a,b] + x[a',b'] - 1``.
+
+Writing the chemical distance ``1/2 * sum_{i,j} |A_R[i,j] - A_P[m(i),m(j)]|`` and
+splitting atoms into certain/kernel, the certain-certain part is a constant, the
+kernel-certain part becomes linear coefficients on ``x``, and the kernel-kernel
+part becomes coefficients on ``y`` (the factor 1/2 and the two ordered directions
+of each undirected edge cancel). CBC solves the MILP to proven optimality, so the
+returned cost certifies the kernel optimum (see :mod:`mapper.exact.certificate`).
+
+The solver is isolated behind :func:`solve_qap`; :func:`solve_kernel_milp` adapts
+a :class:`~mapper.exact.kernel.Kernel` to it and returns the same
+:class:`~mapper.exact.branching.KernelSolution` type as the orbital-branching
+solver, so callers can use either interchangeably.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+import warnings
+
+from ...slap.lap import _adjacency_and_elements
+from .branching import KernelSolution
+
+try:
+    import pulp
+
+    HAS_PULP = True
+except Exception:  # pragma: no cover - exercised only without pulp installed
+    HAS_PULP = False
+
+
+def _cbc_solver():
+    """Return a silent CBC solver, preferring the non-deprecated entry point."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        try:
+            solver = pulp.COIN_CMD(msg=False)
+            if solver.available():
+                return solver
+        except Exception:
+            pass
+        return pulp.PULP_CBC_CMD(msg=False)
+
+
+def solve_qap(lin, quad, n, compatible, const=0.0):
+    """Solve a linearised QAP assignment with PuLP/CBC.
+
+    :param lin: Linear cost ``lin[a, b]`` for assigning ``a -> b``.
+    :type lin: dict[(int, int), float]
+    :param quad: Quadratic cost ``quad[a, b, a', b']`` (defined for ``a < a'``) added when
+                 both ``a -> b`` and ``a' -> b'`` hold.
+    :type quad: dict[(int, int, int, int), float]
+    :param n: Number of reactant positions (== product positions).
+    :type n: int
+    :param compatible: Allowed ``(a, b)`` assignments (element-compatible pairs).
+    :type compatible: set[(int, int)]
+    :param const: Constant added to the objective.
+    :type const: float
+
+    :return: **(cost, mapping, proven)** -- Optimal cost, the assignment ``a -> b``, and whether CBC proved
+              optimality.
+    :rtype: (float, dict[int, int], bool)
+    """
+    if not HAS_PULP:
+        raise ImportError("pulp is required for the MILP/QAP solver")
+
+    prob = pulp.LpProblem("kernel_qap", pulp.LpMinimize)
+
+    # PuLP 3.x emits 4.0-migration DeprecationWarnings from the supported
+    # LpVariable API; silence that noise around variable construction.
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        x = {
+            (a, b): pulp.LpVariable(f"x_{a}_{b}", cat="Binary") for (a, b) in compatible
+        }
+        y = {}
+        for (a, b, a2, b2), c in quad.items():
+            if (a, b) in x and (a2, b2) in x:
+                y[(a, b, a2, b2)] = pulp.LpVariable(
+                    f"y_{a}_{b}_{a2}_{b2}", lowBound=0, upBound=1, cat="Continuous"
+                )
+
+    # Objective.
+    obj = [lin[(a, b)] * x[(a, b)] for (a, b) in x if lin.get((a, b))]
+    obj += [quad[k] * y[k] for k in y if quad.get(k)]
+    prob += pulp.lpSum(obj) + const
+
+    # Assignment constraints.
+    for a in range(n):
+        prob += pulp.lpSum(x[(a, b)] for b in range(n) if (a, b) in x) == 1
+    for b in range(n):
+        prob += pulp.lpSum(x[(a, b)] for a in range(n) if (a, b) in x) == 1
+
+    # McCormick linearisation of the products.
+    for (a, b, a2, b2), yv in y.items():
+        prob += yv <= x[(a, b)]
+        prob += yv <= x[(a2, b2)]
+        prob += yv >= x[(a, b)] + x[(a2, b2)] - 1
+
+    prob.solve(_cbc_solver())
+
+    proven = pulp.LpStatus[prob.status] == "Optimal"
+    mapping = {}
+    for (a, b), var in x.items():
+        if var.value() is not None and var.value() > 0.5:
+            mapping[a] = b
+    cost = pulp.value(prob.objective)
+    if cost is None and proven and not obj:
+        cost = float(const)
+    if cost is None:
+        raise RuntimeError(
+            "MILP solver returned no objective value — problem may be infeasible. "
+            "Verify that element-compatible assignments exist for all kernel atoms."
+        )
+    return float(cost), mapping, proven
+
+
+def solve_kernel_milp(kernel):  # noqa: C901
+    """Solve a :class:`~mapper.exact.kernel.Kernel` exactly via MILP/QAP.
+
+    :return: With ``proven_optimal`` reflecting CBC's status.
+    :rtype: KernelSolution
+    """
+    lgp = kernel.lgp
+    binary = kernel.binary
+    A, _ = _adjacency_and_elements(lgp[0], binary)
+    B, _ = _adjacency_and_elements(lgp[1], binary)
+    N = A.shape[0]
+    n = kernel.size
+
+    base_map = [-1] * N
+    for i, p in kernel.fixed_mapping.items():
+        base_map[i] = p
+    certain = [i for i in range(N) if base_map[i] != -1]
+
+    # Certain-certain constant (0.5 * ordered sum).
+    const = 0.0
+    for i in certain:
+        for j in certain:
+            const += abs(A[i, j] - B[base_map[i], base_map[j]])
+    const *= 0.5
+
+    if n == 0:
+        return KernelSolution(cost=const, sub_mappings=[{}], proven_optimal=True)
+
+    compatible = set()
+    lin: Dict[Tuple[int, int], float] = {}
+    for a in range(n):
+        i = kernel.r_idx[a]
+        for b in range(n):
+            if kernel.r_colors[a] != kernel.p_colors[b]:
+                continue
+            p = kernel.p_idx[b]
+            if (
+                kernel.candidate_images is not None
+                and p not in kernel.candidate_images[a]
+            ):
+                continue
+            compatible.add((a, b))
+            # Kernel-certain: 0.5 * (ordered i,j + ordered j,i) = sum_j |A-B|.
+            lin[(a, b)] = sum(abs(A[i, j] - B[p, base_map[j]]) for j in certain)
+
+    quad: Dict[Tuple[int, int, int, int], float] = {}
+    for a in range(n):
+        i = kernel.r_idx[a]
+        for a2 in range(a + 1, n):
+            i2 = kernel.r_idx[a2]
+            for b in range(n):
+                if (a, b) not in compatible:
+                    continue
+                p = kernel.p_idx[b]
+                for b2 in range(n):
+                    if (a2, b2) not in compatible or b2 == b:
+                        continue
+                    p2 = kernel.p_idx[b2]
+                    # 0.5 * (ordered (i,i') + (i',i)) = |A_R[i,i'] - A_P[p,p']|.
+                    c = abs(A[i, i2] - B[p, p2])
+                    if c:
+                        quad[(a, b, a2, b2)] = c
+
+    cost, mapping, proven = solve_qap(lin, quad, n, compatible, const=const)
+    return KernelSolution(cost=cost, sub_mappings=[mapping], proven_optimal=proven)

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

@@ -0,0 +1 @@
+"""Optional C++ search, explicit compilation, canonicalization, and orbit scheduling."""

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

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Explicitly build the optional native solver into an immutable, hashed artifact."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def _verify_library(library):
+    """Check loadability and ABI in a child so Windows can release the DLL file."""
+    script = (
+        "import ctypes, sys; library = ctypes.CDLL(sys.argv[1]); "
+        "abi = library.synkit_distance_abi(); "
+        "assert abi == 3, f'unsupported native ABI: {abi}'"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", script, str(library)], capture_output=True, text=True
+    )
+    if result.returncode:
+        raise RuntimeError(f"Native artifact cannot be loaded: {library}\n{result.stderr}")
+
+
+def build_native(output_dir, compiler="g++", *, native_arch=False):
+    """Build and verify a source/compiler-bound optional C++ solver artifact."""
+    source = Path(__file__).with_name("native_distance.cpp")
+    compiler_path = shutil.which(compiler)
+    if compiler_path is None:
+        raise RuntimeError(f"C++17 compiler unavailable: {compiler}")
+    version = subprocess.run(
+        [compiler_path, "--version"], check=True, capture_output=True, text=True
+    ).stdout
+    flags = ["-std=c++17", "-O3", "-Wall", "-Wextra"]
+    if sys.platform == "win32":
+        # MinGW runtime DLLs on PATH are not searched by modern ctypes loaders.
+        # Link their code into the artifact and explicitly export the C ABI.
+        flags += ["-shared", "-static", "-Wl,--export-all-symbols"]
+        suffix = ".dll"
+    elif sys.platform == "darwin":
+        flags += ["-fPIC", "-dynamiclib"]
+        suffix = ".dylib"
+    else:
+        flags += ["-fPIC", "-shared"]
+        suffix = ".so"
+    target_options = None
+    if native_arch:
+        flags += ["-march=native", "-mtune=native"]
+        # Include resolved CPU options in the cache key: the same source and
+        # literal -march=native flags can generate different code on another host.
+        target_options = subprocess.run(
+            [
+                compiler_path,
+                *flags,
+                "-Q",
+                "--help=target",
+                "-x",
+                "c++",
+                "-c",
+                "-",
+                "-o",
+                os.devnull,
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+            input="",
+        ).stdout
+    provenance = {
+        "source_sha256": hashlib.sha256(source.read_bytes()).hexdigest(),
+        "compiler": compiler_path,
+        "compiler_version": version,
+        "flags": flags,
+        "platform": sys.platform,
+        "machine": platform.machine(),
+    }
+    if native_arch:
+        provenance["resolved_target_options"] = target_options
+        provenance["portability"] = (
+            "requires the recorded host CPU instruction features"
+        )
+    build_key = hashlib.sha256(
+        json.dumps(provenance, sort_keys=True).encode()
+    ).hexdigest()
+    output_dir = Path(output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    library = output_dir / f"libsynkit_distance_{build_key[:20]}{suffix}"
+    manifest = library.with_suffix(".json")
+    if library.exists():
+        if not manifest.exists():
+            raise RuntimeError(f"Existing library lacks build provenance: {library}")
+        recorded = json.loads(manifest.read_text())
+        if (
+            recorded["build_key"] != build_key
+            or recorded["library_sha256"]
+            != hashlib.sha256(library.read_bytes()).hexdigest()
+        ):
+            raise RuntimeError(
+                f"Existing native artifact failed integrity verification: {library}"
+            )
+        _verify_library(library)
+        return library
+    # A distinct path avoids overwriting code already mapped into another process.
+    with tempfile.TemporaryDirectory(
+        prefix="synkit-build-", dir=output_dir
+    ) as temporary:
+        candidate = Path(temporary) / f"kernel{suffix}"
+        result = subprocess.run(
+            [compiler_path, *flags, str(source), "-o", str(candidate)],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        _verify_library(candidate)
+        provenance.update(
+            build_key=build_key,
+            library=str(library),
+            library_sha256=hashlib.sha256(candidate.read_bytes()).hexdigest(),
+            compiler_stderr=result.stderr,
+        )
+        # Hard-link installation refuses to replace any concurrently installed binary.
+        try:
+            os.link(candidate, library)
+        except FileExistsError:
+            raise RuntimeError(
+                f"Concurrent build installed {library}; rerun to verify it"
+            )
+    manifest.write_text(json.dumps(provenance, indent=2) + "\n")
+    return library
+
+
+def main():
+    """Build the optional C++ solver from an installed SynKit package."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output-dir", type=Path, default=Path(tempfile.gettempdir()) / "synkit-native")
+    parser.add_argument("--compiler", default="g++")
+    parser.add_argument(
+        "--native-arch",
+        action="store_true",
+        help="Opt in to host CPU instructions; resulting library is host-specific.",
+    )
+    args = parser.parse_args()
+    print(build_native(args.output_dir, args.compiler, native_arch=args.native_arch))
+
+
+if __name__ == "__main__":
+    main()