synkit 1.6.5__py3-none-win_amd64.whl

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

@@ -0,0 +1,203 @@
+"""Prove normalized full Lewis PMCD without adding or enumerating H atoms.
+
+Ordinary terminal H is represented by counts on heavy atoms. For a proposed
+heavy bijection f its exact minimum H cost is sum_i |h_R[i]-h_P[f(i)]|, also
+with unequal H inventories under zero-state dummy padding. This term enters
+the native objective before optimization. No H graph, transport enumeration,
+ITS classification or mapped-reaction rendering is performed.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import asdict, dataclass
+import math
+from numbers import Real
+import time
+
+from rdkit import Chem
+
+from synkit.IO.mol_to_graph import MolToGraph
+from ....graph.labeled_graph import LabeledGraph
+from ...slap.lap import _adjacency_and_elements, chemical_distance
+from .candidates import minimize_native_candidates, prepare_native_candidates
+from .search import _profile_seed
+
+
+class _UnsupportedHydrogen(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class PMCDProofResult:
+    """An optimum proof, separate from complete mapping-class enumeration.
+
+    heavy_mapping uses the padded heavy-atom order (real atoms, then dummies).
+    minimum_cost is set only after a completed proof. The feasible incumbent
+    can remain available if the proof is interrupted. Unsupported H states
+    are explicit and never silently drop out of the objective.
+    """
+
+    minimum_cost: float | None
+    incumbent_cost: float | None
+    optimality_proven: bool
+    status: str
+    reason: str | None
+    heavy_mapping: tuple[int, ...] | None
+    heavy_atom_counts: tuple[int, int] | None
+    hydrogen_counts: tuple[int, int] | None
+    search_atoms: int
+    visited_nodes: int
+    elapsed_seconds: float
+    search_result: dict | None = None
+    objective: str = "normalized_full_lewis_distance"
+    hydrogen_nodes_added: int = 0
+    hydrogen_vertices_searched: int = 0
+    enumeration_complete: bool = False
+
+    def as_dict(self):
+        return asdict(self)
+
+
+# Keep hydrogen eligibility, balancing and anchor construction in one reduction.
+def _implicit_quotient_graphs(reaction, balance):  # noqa: C901
+    """Read endpoint H counts and electron states without Chem.AddHs."""
+    if not isinstance(reaction, str):
+        raise TypeError("reaction must be reaction SMILES")
+    parts = reaction.split(">")
+    if len(parts) != 3 or not parts[0] or not parts[2]:
+        raise ValueError("Expected reactants>agents>products or reactants>>products")
+    endpoints = []
+    for side in (parts[0], parts[2]):
+        params = Chem.SmilesParserParams()
+        params.removeHs = False
+        mol = Chem.MolFromSmiles(side, params)
+        if mol is None:
+            raise ValueError("Could not parse reaction endpoint")
+        heavy = []
+        for atom in mol.GetAtoms():
+            atom.SetAtomMapNum(0)
+            if atom.GetAtomicNum() == 0:
+                raise ValueError("Wildcard atoms require a concrete element")
+            if atom.GetAtomicNum() != 1:
+                heavy.append(atom)
+                continue
+            if atom.GetIsotope():
+                raise _UnsupportedHydrogen("isotopic_hydrogen")
+            if atom.GetFormalCharge() or atom.GetNumRadicalElectrons():
+                raise _UnsupportedHydrogen("nonneutral_or_radical_hydrogen")
+            bonds = list(atom.GetBonds())
+            if (len(bonds) != 1 or bonds[0].GetBondTypeAsDouble() != 1
+                    or bonds[0].GetOtherAtom(atom).GetAtomicNum() <= 1):
+                raise _UnsupportedHydrogen("nonordinary_terminal_hydrogen")
+        labels = [(atom.GetAtomicNum(), atom.GetIsotope()) for atom in heavy]
+        hcounts = [MolToGraph._total_h_count(atom) for atom in heavy]
+        electrons = [2 * MolToGraph.estimate_lone_pairs(atom)
+                     + atom.GetNumRadicalElectrons() for atom in heavy]
+        endpoints.append((mol, heavy, labels, hcounts, electrons))
+    inventories = [Counter(value[2]) for value in endpoints]
+    totals = tuple(sum(value[3]) for value in endpoints)
+    if balance == "strict" and (inventories[0] != inventories[1] or totals[0] != totals[1]):
+        raise ValueError("Unbalanced atom inventories; select balance='dummy' explicitly")
+    universe = inventories[0] | inventories[1]
+    graphs = []
+    for (mol, heavy, labels, hcounts, electrons), inventory in zip(endpoints, inventories):
+        positions = {atom.GetIdx(): i for i, atom in enumerate(heavy)}
+        missing = sorted((universe - inventory).elements())
+        labels = labels + missing
+        hcounts = hcounts + [0] * len(missing)
+        electrons = electrons + [0] * len(missing)
+        size = len(labels)
+        adjacency = {i: {} for i in range(size + 2)}
+        for bond in mol.GetBonds():
+            i, j = bond.GetBeginAtomIdx(), bond.GetEndAtomIdx()
+            if i in positions and j in positions:
+                x, y = positions[i], positions[j]
+                adjacency[x][y] = adjacency[y][x] = bond.GetBondTypeAsDouble()
+        # Separate forced anchors encode the electron and minimum-H unary terms.
+        for i, (count, electron) in enumerate(zip(hcounts, electrons)):
+            if electron:
+                adjacency[i][size] = adjacency[size][i] = electron / 2
+            if count:
+                adjacency[i][size + 1] = adjacency[size + 1][i] = count
+        graph = LabeledGraph(adjacency, labels + [(0, -1), (0, -2)])
+        graph.props["hcounts"] = hcounts + [0, 0]
+        graph.props["electrons"] = electrons + [0, 0]
+        graphs.append(graph)
+    return tuple(graphs), tuple(len(value[1]) for value in endpoints), totals
+
+
+def prove_reaction_pmcd(
+    reaction,
+    *,
+    library_path,
+    balance="strict",
+    time_limit_seconds=10.0,
+    symmetry=True,
+):
+    """Prove full Lewis PMCD using only heavy vertices and H counts.
+
+    Supported H atoms are neutral, nonradical, nonisotopic terminal single-bond
+    H. Other H states return status='unsupported' without expanding anything.
+    Stereo does not need expansion for the existing numerical CD objective:
+    it remains an output-class distinction, and this API returns no classes.
+    The ordinary map_reaction/Mapper minimum query still enumerates all minima.
+    """
+    started = time.perf_counter()
+    if balance not in {"strict", "dummy"}:
+        raise ValueError("balance must be 'strict' or 'dummy'")
+    if not isinstance(symmetry, bool):
+        raise TypeError("symmetry must be boolean")
+    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 must be finite and nonnegative")
+    deadline = None if time_limit_seconds is None else started + time_limit_seconds
+
+    def outcome(record=None, *, reason=None, status=None, graphs=(), heavy=None, hydrogens=None):
+        proven = record is not None and record["complete"]
+        mapping = tuple(record["mapping"][:-2]) if record else None
+        return PMCDProofResult(
+            minimum_cost=record["minimum_cost"] if proven else None,
+            incumbent_cost=record["incumbent_cost"] if record else None,
+            optimality_proven=proven,
+            status=status or ("proven" if proven else "time_limit"),
+            reason=reason if reason is not None else record["reason"] if record else None,
+            heavy_mapping=mapping, heavy_atom_counts=heavy, hydrogen_counts=hydrogens,
+            search_atoms=len(graphs[0].labels) if graphs else 0,
+            visited_nodes=record["visited_nodes"] if record else 0,
+            elapsed_seconds=time.perf_counter() - started, search_result=record,
+        )
+
+    try:
+        graphs, heavy, hydrogens = _implicit_quotient_graphs(reaction, balance)
+    except _UnsupportedHydrogen as error:
+        return outcome(status="unsupported", reason=str(error))
+    if len(graphs[0].labels) > 256:
+        return outcome(status="unsupported", reason="native_node_limit", graphs=graphs,
+                       heavy=heavy, hydrogens=hydrogens)
+    if deadline is not None and time.perf_counter() >= deadline:
+        return outcome(status="time_limit", reason="time_limit", graphs=graphs,
+                       heavy=heavy, hydrogens=hydrogens)
+    a, labels = _adjacency_and_elements(graphs[0], False)
+    b, product_labels = _adjacency_and_elements(graphs[1], False)
+    if len(set(a.ravel()) | set(b.ravel())) > 16:
+        return outcome(status="unsupported", reason="native_bond_level_limit", graphs=graphs,
+                       heavy=heavy, hydrogens=hydrogens)
+    seed = _profile_seed(a, b, labels, product_labels)
+    prepared = prepare_native_candidates(
+        graphs, 0, library_path=library_path, initial_mapping=seed,
+        binary=False, symmetry=symmetry, node_properties=(), allow_partial_symmetry=True,
+    )
+    seconds = 1e100 if deadline is None else max(0, deadline - time.perf_counter())
+    record = minimize_native_candidates(
+        graphs, library_path=library_path, initial_mapping=seed,
+        time_limit_seconds=seconds, _prepared=prepared,
+    )
+    if chemical_distance(graphs, record["mapping"], False) != record["incumbent_cost"]:
+        raise RuntimeError("Native proof witness does not match its reduced Lewis cost")
+    return outcome(record, graphs=graphs, heavy=heavy, hydrogens=hydrogens)
+
+
+__all__ = ["PMCDProofResult", "prove_reaction_pmcd"]

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

@@ -0,0 +1,40 @@
+"""Optional operating-system controls for native mapper workers."""
+
+import os
+
+WORKER_ADDRESS_SPACE_BYTES = 4 * 1024**3
+
+
+def limit_worker_address_space(resource):
+    """Lower supported soft limits, preserving inherited soft and hard ceilings."""
+    if resource is None or not hasattr(resource, "RLIMIT_AS"):
+        return None
+    try:
+        soft, hard = resource.getrlimit(resource.RLIMIT_AS)
+        ceilings = [value for value in (soft, hard) if value != resource.RLIM_INFINITY]
+        limit = min([WORKER_ADDRESS_SPACE_BYTES, *ceilings])
+        resource.setrlimit(resource.RLIMIT_AS, (limit, hard))
+        return limit
+    except (OSError, ValueError):
+        # Some macOS kernels expose RLIMIT_AS but reject setting this limit.
+        # This optional control must not prevent worker startup and barriers.
+        return None
+
+
+def worker_cpus(workers):
+    """Return available CPU IDs to pin, or an empty list when unsupported."""
+    if not hasattr(os, "sched_getaffinity") or not hasattr(os, "sched_setaffinity"):
+        return []
+    try:
+        return sorted(os.sched_getaffinity(0))[:workers]
+    except OSError:
+        return []
+
+
+def pin_worker_cpu(cpu):
+    """Apply optional CPU pinning without making an OS tuning failure fatal."""
+    if cpu is not None and hasattr(os, "sched_setaffinity"):
+        try:
+            os.sched_setaffinity(0, {cpu})
+        except OSError:
+            pass

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

@@ -0,0 +1,294 @@
+"""Full-space minimum and distance-range adapters for optional C++ search."""
+
+import math
+import time
+from collections import Counter
+from functools import partial
+from numbers import Integral, Real
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+from ...slap.lap import _adjacency_and_elements
+from ..distance_search.bounds import atom_profile_costs
+from ..distance_search.records import (
+    DistanceEnumerationResult,
+    ExactEnumerationLimitError,
+    normalize_distance_target,
+)
+from ..pabs.cost_lattice import CostLattice
+from .candidates import (
+    enumerate_native_range,
+    minimize_native_candidates,
+    prepare_native_candidates,
+)
+
+
+def _profile_seed(a, b, labels, product_labels):
+    """Choose a compatible feasible incumbent; its cost is verified in C++."""
+    profiles = atom_profile_costs(a, b, labels, product_labels)
+    mapping = [-1] * len(labels)
+    for element in dict.fromkeys(labels):
+        rows = [i for i, value in enumerate(labels) if value == element]
+        columns = [i for i, value in enumerate(product_labels) if value == element]
+        left, right = linear_sum_assignment(profiles[np.ix_(rows, columns)])
+        for i, j in zip(left, right):
+            mapping[rows[i]] = columns[j]
+    return mapping
+
+
+def enumerate_cpp_mappings(  # noqa: C901
+    lgp,
+    *,
+    library_path,
+    CD="minimal",
+    CD_mode="exact",
+    binary=True,
+    initial_mapping=None,
+    max_bijections=1_000_000,
+    max_mappings=None,
+    time_limit_seconds=None,
+    collect_mappings=True,
+    mapping_callback=None,
+    compute_minimum_cost=True,
+    tolerance=1e-9,
+    symmetry=False,
+    node_properties=(),
+    separator_config=None,
+):
+    """Prove PMCD and enumerate its full shell, or enumerate a supplied CD.
+
+    A numeric query defaults to CD_mode='exact'. 'at_most' instead selects
+    every distance at or below CD in one traversal. Returned distances and
+    callbacks carry each mapping's actual cost.
+
+    The default preserves every compatible labeled mapping. symmetry=True uses
+    verified side automorphisms preserving node_properties; partial subgroup
+    discovery only weakens pruning. Chemical frontends still perform exact ITS
+    classification and report representative counts separately from labeled
+    counts. Requires 1..256 atoms, symmetric loop-free half-integer weights and
+    at most 16 bond levels. Compilation remains explicit.
+
+    Minimum proof and complete enumeration are independent passes sharing one
+    deadline. An interrupted proof never publishes its incumbent as PMCD.
+    ``separator_config`` explicitly enables an experimental bounded residual
+    oracle, with ``residual_limit`` (0..12) and ``max_states`` per call. Unknown
+    oracle results retain ordinary search. The default leaves it disabled.
+    """
+    started = time.perf_counter()
+    target = normalize_distance_target(CD)
+    minimum_function = minimize_native_candidates
+    range_function = enumerate_native_range
+    separator_options = separator_statistics = None
+    if separator_config is not None:
+        from .separator import (
+            _normalize_separator_config,
+            enumerate_native_range_separator,
+            minimize_native_candidates_separator,
+        )
+
+        separator_options = _normalize_separator_config(separator_config)
+        minimum_function = partial(minimize_native_candidates_separator, **separator_options)
+        range_function = partial(enumerate_native_range_separator, **separator_options)
+        separator_statistics = dict.fromkeys(("calls", "known", "pruned", "states"), 0)
+    if CD_mode not in {"exact", "at_most"}:
+        raise ValueError("CD_mode must be 'exact' or 'at_most'")
+    if target == "minimal" and CD_mode != "exact":
+        raise ValueError("CD_mode='at_most' requires numeric CD")
+    for name, value in (
+        ("binary", binary),
+        ("collect_mappings", collect_mappings),
+        ("compute_minimum_cost", compute_minimum_cost),
+        ("symmetry", symmetry),
+    ):
+        if not isinstance(value, bool):
+            raise TypeError(f"{name} must be boolean")
+    for name, value in (
+        ("max_bijections", max_bijections),
+        ("max_mappings", max_mappings),
+    ):
+        if value is not None and (
+            isinstance(value, bool) or not isinstance(value, Integral) or value < 1
+        ):
+            raise ValueError(f"{name} must be a positive integer or None")
+    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 non-negative")
+    if (
+        isinstance(tolerance, bool)
+        or not isinstance(tolerance, Real)
+        or not math.isfinite(tolerance)
+        or not 0 <= tolerance < 0.25
+    ):
+        raise ValueError("C++ tolerance must be finite, nonnegative and less than 0.25")
+    if mapping_callback is not None and not callable(mapping_callback):
+        raise TypeError("mapping_callback must be callable")
+    a, labels = _adjacency_and_elements(lgp[0], binary)
+    b, product_labels = _adjacency_and_elements(lgp[1], binary)
+    if a.shape != b.shape or Counter(labels) != Counter(product_labels):
+        raise ValueError("Endpoints must have equal atom-type inventories")
+    total = math.prod(math.factorial(count) for count in Counter(labels).values())
+    if max_bijections is not None and total > max_bijections:
+        raise ExactEnumerationLimitError(
+            f"{total:,} bijections exceed max_bijections={max_bijections:,}"
+        )
+    maximum = float(np.abs(a).sum() + np.abs(b).sum()) / 2
+    if maximum > 250000:
+        raise ValueError("C++ total distance range exceeds 250000")
+    seed = (
+        _profile_seed(a, b, labels, product_labels)
+        if initial_mapping is None
+        else initial_mapping
+    )
+    prepared = prepare_native_candidates(
+        lgp,
+        0,
+        library_path=library_path,
+        initial_mapping=seed,
+        binary=binary,
+        symmetry=symmetry,
+        node_properties=node_properties,
+        allow_partial_symmetry=True,
+    )
+    lattice = CostLattice.from_matrices(np.rint(a * 4), np.rint(b * 4))
+    deadline = None if time_limit_seconds is None else started + time_limit_seconds
+    nodes = leaves = pruned = count = 0
+    minimum = reason = proof = None
+    mappings, distances = [], []
+    first_cost = None
+    mixed_costs = False
+
+    def remaining():
+        return 1e100 if deadline is None else max(0, deadline - time.perf_counter())
+
+    def record_statistics(record):
+        nonlocal nodes, leaves, pruned
+        nodes += int(record["visited_nodes"])
+        leaves += int(record["visited_leaves"])
+        pruned += int(record["pruned"])
+        if separator_statistics is not None:
+            for name in separator_statistics:
+                separator_statistics[name] += record["separator_statistics"][name]
+
+    if target == "minimal" or compute_minimum_cost:
+        proof = minimum_function(
+            lgp,
+            library_path=library_path,
+            initial_mapping=seed,
+            time_limit_seconds=remaining(),
+            _prepared=prepared,
+        )
+        record_statistics(proof)
+        minimum = proof["minimum_cost"]
+        reason = proof["reason"]
+
+    def receive(mapping, cost):
+        nonlocal count, first_cost, mixed_costs
+        count += 1
+        if first_cost is None:
+            first_cost = cost
+        elif cost != first_cost:
+            mixed_costs = True
+        if collect_mappings:
+            mappings.append(list(mapping))
+            distances.append(cost)
+        if mapping_callback is not None:
+            mapping_callback(list(mapping), cost)
+
+    selected = minimum if target == "minimal" else float(target)
+    if reason is None and selected is not None:
+        if CD_mode == "at_most":
+            lower = 0.0
+            upper = min(
+                maximum, math.floor((min(selected, maximum) + tolerance) * 2) / 2
+            )
+            reachable = lattice.intersects(0, round(upper * 4))
+        elif selected > maximum + tolerance:
+            reachable = False
+        else:
+            lower = upper = round(selected * 2) / 2
+            reachable = (
+                abs(selected - upper) <= tolerance
+                and upper <= maximum
+                and lattice.intersects(round(upper * 4), round(upper * 4))
+            )
+        if reachable:
+            record = range_function(
+                lgp,
+                lower,
+                upper,
+                library_path=library_path,
+                time_limit_seconds=remaining(),
+                max_mappings=None if max_mappings is None else int(max_mappings),
+                callback=receive,
+                _prepared=prepared,
+            )
+            record_statistics(record)
+            reason = record["reason"]
+    complete = reason is None
+    reactant_order, product_order = prepared[6:8]
+    group_order = (
+        reactant_order * product_order
+        if reactant_order is not None and product_order is not None
+        else None
+    )
+    labeled_count = count if count == 0 or not symmetry or group_order == 1 else None
+    symmetry_complete = prepared.symmetry_search_complete
+    generator_count = len(prepared[4]) + len(prepared[5]) - 2
+    return DistanceEnumerationResult(
+        target=target,
+        cost=first_cost if count and not mixed_costs else None,
+        minimum_cost=minimum,
+        mappings=mappings,
+        distances=distances,
+        total_bijections=total,
+        maximum_cost_upper_bound=maximum,
+        visited_leaves=leaves,
+        pruned_branches=pruned,
+        visited_nodes=nodes,
+        elapsed_seconds=time.perf_counter() - started,
+        status=("complete" if count else "no_solutions") if complete else "timeout",
+        complete=complete,
+        truncation_reason=reason,
+        scope=(
+            "atom_compatible_assignment_space_modulo_verified_side_symmetry"
+            if symmetry
+            else "complete_atom_compatible_assignment_space"
+        ),
+        selected_mapping_count=count,
+        selected_labeled_mapping_count=labeled_count,
+        symmetry_automorphism_count=generator_count + 1,
+        symmetry_search_complete=symmetry_complete,
+        symmetry_group_order=group_order,
+        symmetry_quotient_complete=complete and symmetry_complete,
+        backend="pabs_cpp",
+        backend_statistics={
+            "method": "PABS",
+            "requested_backend": "cpp",
+            "implementation": "native_assignment_branch_and_bound",
+            "minimum_shell_probes": 0,
+            "minimum_optimization": proof,
+            "CD_mode": CD_mode,
+            "mapping_count_scope": (
+                "symmetry_candidates" if symmetry else "labeled_mappings"
+            ),
+            "symmetry_enabled": symmetry,
+            "side_groups_complete": symmetry_complete,
+            "symmetry_generator_count": generator_count,
+            "library_path": str(library_path),
+            "cost_lattice_modulus_quarters": lattice.modulus,
+            "cost_lattice_residue_quarters": lattice.residue,
+            **(
+                {"separator_config": separator_options,
+                 "separator_statistics": separator_statistics}
+                if separator_options is not None else {}
+            ),
+        },
+    )
+
+
+__all__ = ["enumerate_cpp_mappings"]