synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/__init__.py

@@ -0,0 +1,255 @@
+"""
+synkit.Chem.Mapper
+==================
+
+Atom-to-atom mapping offers several explicit workflows:
+
+* Platform wheels include the shared C++ PABS–SLAP core. Custom builds use
+  ``_native.build.build_mapper_native``. The
+  ``map_reaction_implicit`` interface scores heavy-atom classes
+  with minimum implicit-H Lewis completion, without expanding hydrogen.
+  Optional OR-Tools builds add checked integer LP bounds; floating solver
+  status and heuristic proposals never establish optimality on their own.
+* ``Mapper(method='propagate').map(...)`` provides one interface and result
+  type for eight named methods. ``Mapper.methods()`` lists their names.
+* ``map_reaction(...)`` defaults to full-space Python exact propagation search.
+  ``backend='cpp'`` selects the optional compiled minimum and cost-range search.
+  Reaction SMILES use Lewis CD (bonds plus nonbonding-electron changes) and
+  explicit hydrogens by default. ``objective='bond'`` selects bond-only CD.
+  Omitting CD enumerates all minimum-distance classes; native search also
+  supports numeric ``CD_mode='at_most'`` for classes at distance <= CD.
+* ``AAMapper().map_smiles(...)`` defaults to the approximate WL/SLAP mapper.
+* ``AAMapper().map_smiles(..., enumerate_exact=True)`` runs SLAP followed by
+  exact refinement of a reduced uncertainty kernel.
+* ``AAMapper().map_smiles(..., certify='exact')`` requests optional kernel MILP
+  certification of the SLAP results.
+* ``AAMapper().enumerate_smiles(...)`` or ``map_smiles(..., CD=...)`` runs the
+  established full-distance search; SLAP may provide a seed for a minimum query.
+
+PABS means Propagation and Assignment-Bounded Search. It is the package's
+descriptive name for the exact interface used by ``map_reaction`` and
+``enumerate_pabs_mappings``. Its Python solver combines one-to-one domain
+propagation with LAP bounds; its C++ backend uses a separate traversal.
+LAP means linear assignment problem. SLAP uses sequential LAP decisions for
+heuristic matching. A kernel is the reduced subproblem extracted from SLAP
+results for optional refinement; optimality within it is scoped to its fixed
+assignments and candidate domains. The PABS routes search without extracting
+this uncertainty kernel or invoking its MILP solver.
+
+Research basis
+--------------
+The approximate SLAP mapper develops the mapping idea from:
+Shin-ichi Koda and Shinji Saito, "General and scalable atom-to-atom mapping
+via Weisfeiler-Lehman-like approximate graph matching", ChemRxiv (2025).
+DOI: 10.26434/chemrxiv-2025-hthwn
+
+Quick start
+-----------
+>>> from synkit.Chem.Mapper import Mapper
+>>> result = Mapper(method="propagate").map("CO>>CO")
+>>> result.complete, result.minimum_cost
+(True, 0.0)
+
+Several inequivalent symmetry classes can share a minimum. Inspect
+``result.mapped_reactions`` and ``result.complete`` separately.
+``Mapper("native")`` uses the bundled wheel library; an explicit
+``library_path`` selects a custom build. The older
+``solvers.exact.native.build.build_native`` ABI3-only builder remains supported.
+
+Package layout
+--------------
+:mod:`synkit.Chem.Mapper.graph`
+    Labeled-graph data structure, WL/2-WL refinement, automorphisms,
+    block-cut-tree decomposition.
+:mod:`synkit.Chem.Mapper.solvers.slap`
+    Sequential-LAP engine (:class:`GraphMatcher`) and LAP utilities
+    (chemical distance, Gilmore-Lawler lower bound).
+:mod:`synkit.Chem.Mapper.solvers.exact`
+    Distinct exact methods live in ``distance_search/``, ``kernel_solvers/``,
+    ``pabs/``, and ``native/``. Shared LAP proofs live in ``assignment/`` and
+    feasible-incumbent heuristics in ``seeds/``. ``enumerate_pabs_mappings``
+    selects Python or C++ through one interface. The legacy ABI3 source and
+    builder are adjacent in ``solvers/exact/native/``.
+:mod:`synkit.Chem.Mapper.solvers.native`
+    Thin bindings, explicit immutable builds and chemistry preparation for the
+    shared C++ core in ``solvers/native/cpp/``. Production builds omit internal oracle exports;
+    a separate ``test_hooks=True`` build enables mathematical tests.
+:mod:`synkit.Chem.Mapper.reaction_search`
+    Unmapped reaction SMILES, exact symmetry class representatives,
+    explicit or compressed hydrogen, and optional missing-atom padding.
+:mod:`synkit.Chem.Mapper.chem`
+    RDKit SMILES I/O and ITS-based deduplication / electron-balance checks.
+:mod:`synkit.Chem.Mapper.io`
+    Index-mapping-string helpers.
+:mod:`synkit.Chem.Mapper.validation`
+    AAM validation, identifiability, and bond/annotation/cohort evaluation.
+:mod:`synkit.Chem.Mapper.reporting`
+    Reference-blinded shell analysis, ITS spectra, structural alternatives,
+    and native two-sided orbit reports.
+:mod:`synkit.Chem.Mapper.adapters`
+    Prediction seeds, validated class correspondences, and executable rules.
+
+Historical flat module imports remain aliases to the same implementation
+objects. See ``README.rst`` beside this module for method scopes and examples.
+
+Public API
+----------
+"""
+
+from ._compat import (
+    MAPPER_MODULE_ALIASES as _MAPPER_MODULE_ALIASES,
+)
+from ._compat import (
+    register_module_aliases as _register_module_aliases,
+    install_solver_aliases as _install_solver_aliases,
+)
+
+from .adapters.template import (
+    ClassCorrespondence,
+    ProductRecoveryScore,
+    SourceReplayResult,
+    class_correspondence_from_export,
+    correspondence_from_export,
+    executable_rule_from_correspondence,
+    mapped_reaction_from_correspondence,
+    prospective_products,
+    replay_executable_rule_on_source,
+    score_product_recovery,
+)
+from .chem.aam import AAMapper
+from .chem.blind import BlindedReactionProblem, blinded_mapped_reaction_problem
+from .solvers.exact.core import (
+    ITSComponentReduction,
+    reduce_to_reference_its_components,
+)
+from .solvers.exact.distance_search.search import (
+    CertificateVerificationError,
+    DistanceEnumerationCertificate,
+    DistanceEnumerationResult,
+    ExactEnumerationLimitError,
+    enumerate_distance_mappings,
+    verify_distance_enumeration_certificate,
+)
+from .solvers.exact.edit_support import (
+    BinaryEditBudget,
+    BinaryEditSupportResult,
+    binary_edit_budget,
+    enumerate_binary_edit_support_mappings,
+)
+from .solvers.exact.hybrid import (
+    HybridBackend,
+    HybridBackendDecision,
+    enumerate_hybrid_distance_mappings,
+)
+from .solvers.exact.hydrogen import (
+    HydrogenEnumerationResult,
+    HydrogenTransferPlan,
+    enumerate_lgp_hydrogen_transfers,
+    enumerate_minimal_hydrogen_transfers,
+)
+from .solvers.exact.pabs.propagation import PropagationConfig, enumerate_synister_cp_mappings
+from .solvers.exact.search import enumerate_pabs_mappings
+from .graph.labeled_graph import LabeledGraph
+from .mapper import Mapper, MappingResult
+from .reaction_search import ReactionMapping, ReactionMappingResult, map_reaction
+from .reporting.alternatives import (
+    AlternativeTarget,
+    ExactITSAlternative,
+    ExactITSAlternativeResult,
+    MappedReactionITSAlternativeResult,
+    SeedMode,
+    enumerate_exact_its_alternatives,
+    enumerate_mapped_reaction_its_alternatives,
+)
+from .reporting.analysis import (
+    GlobalShellAnalysisResult,
+    GlobalShellConfig,
+    ReactionCenterSpectrum,
+    analyze_reference_blinded_global_shell,
+)
+from .reporting.spectrum import (
+    ExactStructureSpectrum,
+    ExactStructureSpectrumAccumulator,
+    exact_its_and_template_codes,
+)
+from .solvers.slap.sequential import GraphMatcher
+from .solvers.native.implicit import map_reaction_implicit
+from .validation.aam_validator import AAMValidator
+from .solvers import exact, native as _native, slap
+
+RESEARCH_BASIS_TITLE = (
+    "General and scalable atom-to-atom mapping via "
+    "Weisfeiler-Lehman-like approximate graph matching"
+)
+RESEARCH_BASIS_DOI = "10.26434/chemrxiv-2025-hthwn"
+RESEARCH_BASIS_URL = f"https://doi.org/{RESEARCH_BASIS_DOI}"
+RESEARCH_BASIS_AUTHORS = "Shin-ichi Koda and Shinji Saito"
+
+__all__ = [
+    "RESEARCH_BASIS_AUTHORS",
+    "RESEARCH_BASIS_DOI",
+    "RESEARCH_BASIS_TITLE",
+    "RESEARCH_BASIS_URL",
+    "AAMValidator",
+    "AAMapper",
+    "AlternativeTarget",
+    "BinaryEditBudget",
+    "BinaryEditSupportResult",
+    "BlindedReactionProblem",
+    "CertificateVerificationError",
+    "ClassCorrespondence",
+    "DistanceEnumerationCertificate",
+    "DistanceEnumerationResult",
+    "ExactEnumerationLimitError",
+    "ExactITSAlternative",
+    "ExactITSAlternativeResult",
+    "ExactStructureSpectrum",
+    "ExactStructureSpectrumAccumulator",
+    "GlobalShellAnalysisResult",
+    "GlobalShellConfig",
+    "GraphMatcher",
+    "HybridBackend",
+    "HybridBackendDecision",
+    "HydrogenEnumerationResult",
+    "HydrogenTransferPlan",
+    "ITSComponentReduction",
+    "LabeledGraph",
+    "MappedReactionITSAlternativeResult",
+    "Mapper",
+    "MappingResult",
+    "ProductRecoveryScore",
+    "PropagationConfig",
+    "ReactionCenterSpectrum",
+    "ReactionMapping",
+    "ReactionMappingResult",
+    "SeedMode",
+    "SourceReplayResult",
+    "analyze_reference_blinded_global_shell",
+    "binary_edit_budget",
+    "blinded_mapped_reaction_problem",
+    "class_correspondence_from_export",
+    "correspondence_from_export",
+    "enumerate_binary_edit_support_mappings",
+    "enumerate_distance_mappings",
+    "enumerate_exact_its_alternatives",
+    "enumerate_hybrid_distance_mappings",
+    "enumerate_lgp_hydrogen_transfers",
+    "enumerate_mapped_reaction_its_alternatives",
+    "enumerate_minimal_hydrogen_transfers",
+    "enumerate_pabs_mappings",
+    "enumerate_synister_cp_mappings",
+    "exact_its_and_template_codes",
+    "executable_rule_from_correspondence",
+    "map_reaction",
+    "map_reaction_implicit",
+    "mapped_reaction_from_correspondence",
+    "prospective_products",
+    "reduce_to_reference_its_components",
+    "replay_executable_rule_on_source",
+    "score_product_recovery",
+    "verify_distance_enumeration_certificate",
+]
+
+# Preserve flat imports while keeping implementation files in focused packages.
+_install_solver_aliases()
+_register_module_aliases(__name__, _MAPPER_MODULE_ALIASES)

synkit/Chem/Mapper/_compat.py

@@ -0,0 +1,130 @@
+"""Historical module names for the reorganized mapper implementation.
+
+Aliases share module objects, so monkeypatching and classes retain their
+identity across old and new imports. Internal code uses canonical paths.
+"""
+
+from importlib import import_module
+from importlib.abc import Loader, MetaPathFinder
+from importlib.util import find_spec, spec_from_loader
+import sys
+
+
+MAPPER_MODULE_ALIASES = {
+    "analysis": "reporting.analysis",
+    "native_analysis": "reporting.native_analysis",
+    "spectrum": "reporting.spectrum",
+    "alternatives": "reporting.alternatives",
+    "prediction_adapter": "adapters.prediction",
+    "template_adapter": "adapters.template",
+    "aam_validator": "validation.aam_validator",
+    "identifiability": "validation.identifiability",
+    "evaluation": "validation.bonds",
+    "annotation_evaluation": "validation.annotations",
+    "orbit_evaluation": "validation.orbits",
+    "cohort_evaluation": "validation.cohorts",
+    "numerical_scope": "validation.numerical_scope",
+}
+
+EXACT_MODULE_ALIASES = {
+    "distance": "distance_search.search",
+    "distance_bounds": "distance_search.bounds",
+    "distance_inputs": "distance_search.inputs",
+    "distance_records": "distance_search.records",
+    "distance_verify": "distance_search.verify",
+    "assignment_certificate": "assignment.assignment_certificate",
+    "assignment_domains": "assignment.assignment_domains",
+    "assignment_verification": "assignment.assignment_verification",
+    "incremental_assignment": "assignment.incremental_assignment",
+    "kernel": "kernel_solvers.kernel",
+    "branching": "kernel_solvers.branching",
+    "exhaustive": "distance_search.exhaustive",
+    "milp": "kernel_solvers.milp",
+    "enumerate": "kernel_solvers.enumerate",
+    "enumeration_result": "kernel_solvers.enumeration_result",
+    "propagation": "pabs.propagation",
+    "propagation_search": "pabs.propagation_search",
+    "propagation_bounds": "pabs.propagation_bounds",
+    "propagation_limits": "pabs.propagation_limits",
+    "propagation_symmetry": "pabs.propagation_symmetry",
+    "multi_shell": "pabs.multi_shell",
+    "suffix_spectrum": "pabs.suffix_spectrum",
+    "factor_spectrum": "pabs.factor_spectrum",
+    "separator_spectrum": "pabs.separator_spectrum",
+    "separator_bound": "pabs.separator_bound",
+    "cost_lattice": "pabs.cost_lattice",
+    "residual_typed_bonds": "pabs.residual_typed_bonds",
+    "reward_frontier": "pabs.reward_frontier",
+    "sparse_reward_bound": "pabs.sparse_reward_bound",
+    "seed": "seeds.seed",
+    "seed_fragments": "seeds.seed_fragments",
+    "seed_relaxation": "seeds.seed_relaxation",
+    "native_candidates": "native.candidates",
+    "native_canonical": "native.canonical",
+    "native_frontier": "native.frontier",
+    "native_its": "native.its",
+    "native_parallel": "native.parallel",
+    "native_search": "native.search",
+    "orbit_aggregation": "native.orbit_aggregation",
+    "disk_frontier": "native.disk_frontier",
+}
+
+
+_SOLVER_PREFIXES = {
+    f"{namespace}.{old}": f"synkit.Chem.Mapper.solvers.{new}"
+    for namespace in ("synkit.Chem.Mapper", "synkit.Chem.Reaction.Mapper")
+    for old, new in (("exact", "exact"), ("slap", "slap"), ("_native", "native"))
+}
+
+
+class _SolverAliasLoader(Loader):
+    """Resolve a historical solver module without creating a second implementation."""
+
+    def __init__(self, canonical_name):
+        self.canonical_name = canonical_name
+
+    def create_module(self, spec):
+        return None
+
+    def exec_module(self, module):
+        sys.modules[module.__spec__.name] = import_module(self.canonical_name)
+
+    def get_code(self, fullname):
+        # runpy requests code without importing the alias. Call the canonical
+        # builder's main directly so its relative imports keep their new base.
+        if self.canonical_name.endswith((".build", ".native_build", ".reaction_build")):
+            source = f"from importlib import import_module\nimport_module({self.canonical_name!r}).main()\n"
+        else:
+            source = f"import runpy\nrunpy.run_module({self.canonical_name!r}, run_name='__main__')\n"
+        return compile(source, f"<compatibility {fullname}>", "exec")
+
+
+class _SolverAliasFinder(MetaPathFinder):
+    def find_spec(self, fullname, path=None, target=None):
+        for old, canonical in _SOLVER_PREFIXES.items():
+            if fullname == old or fullname.startswith(old + "."):
+                name = canonical + fullname[len(old):]
+                original = find_spec(name)
+                if original is None:
+                    return None
+                return spec_from_loader(
+                    fullname, _SolverAliasLoader(name),
+                    origin=original.origin,
+                    is_package=original.submodule_search_locations is not None,
+                )
+        return None
+
+
+def install_solver_aliases():
+    """Keep old solver imports and build commands working after the source move."""
+    if not any(isinstance(finder, _SolverAliasFinder) for finder in sys.meta_path):
+        sys.meta_path.insert(0, _SolverAliasFinder())
+
+
+def register_module_aliases(package_name, aliases):
+    """Bind historical children to canonical modules on an existing package."""
+    package = sys.modules[package_name]
+    for old_name, canonical_name in aliases.items():
+        module = import_module(f".{canonical_name}", package_name)
+        sys.modules[f"{package_name}.{old_name}"] = module
+        setattr(package, old_name, module)

synkit/Chem/Mapper/adapters/__init__.py

@@ -0,0 +1 @@
+"""Prediction seeds and conversion of mapping classes into executable rules."""

synkit/Chem/Mapper/adapters/prediction.py

@@ -0,0 +1,126 @@
+"""Reference-free prediction inputs and strict coordinate alignment.
+
+The connectivity contract matches :mod:`identifiability`. Alignment uses only
+each endpoint graph; neither a deposited mapping nor an optimal candidate set
+is accepted by this interface. Alternative endpoint isomorphisms differ by
+endpoint automorphisms, so quotient bond scores are independent of that choice.
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass
+
+import networkx as nx
+from rdkit import Chem
+
+from ..validation.bonds import _graph
+from ..validation.identifiability import extract_label, parse_reaction
+from ..solvers.slap.sequential import GraphMatcher
+
+
+def unmapped_input(reaction: str) -> str:
+    """Remove all map labels before serialization; retain every component.
+
+    Coordinates for the prediction study are those of the returned string.
+    Stereo is intentionally removed for the connectivity-only task, after the
+    strict parser rejects unsupported inventories, isotopes and radicals.
+    """
+    parse_reaction(reaction)
+    sides = []
+    for side in reaction.split(">>"):
+        params = Chem.SmilesParserParams()
+        params.removeHs = False
+        mol = Chem.MolFromSmiles(side, params)
+        for atom in mol.GetAtoms():
+            atom.SetAtomMapNum(0)
+        mol = Chem.RemoveHs(mol)
+        sides.append(Chem.MolToSmiles(mol, canonical=False, isomericSmiles=False))
+    result = ">>".join(sides)
+    parse_reaction(result)
+    return result
+
+
+def _map_ids(side):
+    params = Chem.SmilesParserParams()
+    params.removeHs = False
+    mol = Chem.MolFromSmiles(side, params)
+    if mol is None:
+        raise ValueError("Invalid predicted SMILES")
+    # RemoveHs retains heavy-atom relative order. H mapping is outside scope.
+    ids = tuple(a.GetAtomMapNum() for a in mol.GetAtoms() if a.GetAtomicNum() > 1)
+    if not ids or any(i <= 0 for i in ids) or len(set(ids)) != len(ids):
+        raise ValueError("Every predicted heavy atom needs one unique positive map ID")
+    return ids
+
+
+def _align(source, target):
+    matcher = nx.algorithms.isomorphism.GraphMatcher(
+        _graph(source), _graph(target),
+        node_match=nx.algorithms.isomorphism.categorical_node_match("color", None),
+        edge_match=nx.algorithms.isomorphism.categorical_edge_match("order", None),
+    )
+    match = next(matcher.isomorphisms_iter(), None)
+    if match is None:
+        raise ValueError("Prediction changed an attributed endpoint graph")
+    return tuple(match[i] for i in range(len(source.atomic_numbers)))
+
+
+@dataclass(frozen=True)
+class AlignedPrediction:
+    mapping: tuple[int, ...]
+    reactant_to_output: tuple[int, ...]
+    product_to_output: tuple[int, ...]
+
+
+def align_mapped_prediction(unmapped_reaction: str, mapped_output: str) -> AlignedPrediction:
+    """Validate an untouched mapped output and return alignment witnesses."""
+    r, p = parse_reaction(unmapped_reaction)
+    rr, pp = parse_reaction(mapped_output)
+    rid, pid = map(_map_ids, mapped_output.split(">>"))
+    if set(rid) != set(pid):
+        raise ValueError("Predicted map-ID inventories differ between endpoints")
+    ra, pa = _align(r, rr), _align(p, pp)
+    product_by_id = {pid[out]: original for original, out in enumerate(pa)}
+    mapping = tuple(product_by_id[rid[out]] for out in ra)
+    extract_label(r, p, mapping)  # complete element-compatible permutation
+    return AlignedPrediction(mapping, ra, pa)
+
+
+def predict_slap(unmapped_reaction: str):
+    """SLAP heavy-atom symmetry splitting with deterministic residual ties.
+
+    Requests splitting for every heavy atom, uses the first returned partition,
+    then pairs sorted indices
+    within each common final label. This is a declared single-map baseline,
+    not an exact optimizer, a ground-truth repair, or a claim that all unresolved
+    label blocks contain automorphism-equivalent atoms.
+    """
+    r, p = parse_reaction(unmapped_reaction)
+    matcher = GraphMatcher(binary=False, max_lap_fingerprints=1000,
+                           cache_label_blocks=True, deterministic_labels=True)
+    matcher.get_maps([r.graph(), p.graph()], break_sym_targets=list(range(len(r.atomic_numbers))))
+    if not matcher.results:
+        raise ValueError("SLAP returned no partition")
+    result = matcher.results[0]
+    lr, lp = result["lgp"]
+    left, right = defaultdict(list), defaultdict(list)
+    for i, label in enumerate(lr.labels):
+        left[label].append(i)
+    for i, label in enumerate(lp.labels):
+        right[label].append(i)
+    if set(left) != set(right) or any(len(left[k]) != len(right[k]) for k in left):
+        raise ValueError("SLAP partition multiplicities disagree")
+    mapping = [-1] * len(r.atomic_numbers)
+    for label in sorted(left):
+        for i, j in zip(left[label], right[label]):
+            mapping[i] = j
+    extract_label(r, p, mapping)
+    return {
+        "method": "slap-heavy-split-v1",
+        "mapping": mapping,
+        "raw_reactant_labels": list(lr.labels),
+        "raw_product_labels": list(lp.labels),
+        "returned_partition_count": len(matcher.results),
+        "reported_partition_cost": int(result["val"]),
+        "heavy_atom_splitting": True,
+        "tie_policy": "first-returned-partition_then_increasing-index-within-label",
+    }