synkit 1.4.0__tar.gz → 1.4.2b1__tar.gz

{synkit-1.4.0 → synkit-1.4.2b1}/.gitignore

@@ -37,3 +37,6 @@ test_syn.py
 .gitignore
 measure_candidate_stages.py
 run_valid_bug_cases.py
+debug/*
+diag_postproc.py
+diag_nofused.py

{synkit-1.4.0 → synkit-1.4.2b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synkit
-Version: 1.4.0
+Version: 1.4.2b1
 Summary: Utility for reaction modeling using graph grammar
 Project-URL: homepage, https://github.com/TieuLongPhan/SynKit
 Project-URL: source, https://github.com/TieuLongPhan/SynKit

{synkit-1.4.0 → synkit-1.4.2b1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synkit"
-version = "1.4.0"
+version = "1.4.2b1"
 description = "Utility for reaction modeling using graph grammar"
 readme = "README.md"
 long-description = { file = "CHANGELOG.md" }

synkit-1.4.2b1/synkit/Chem/Reaction/Mapper/__init__.py

@@ -0,0 +1,70 @@
+"""
+synkit.Chem.Reaction.Mapper
+===========================
+
+An atom-to-atom mapping (AAM) toolkit built on Weisfeiler-Lehman label
+refinement coupled with sequential linear assignment problems (SLAP). The
+approximate SLAP result can be refined into a *certified* optimum on the
+ambiguous reaction-center kernel using the
+:mod:`synkit.Chem.Reaction.Mapper.exact` solvers.
+
+Research basis
+--------------
+This enhanced mapper develops the SLAP 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.Reaction.Mapper import AAMapper, AAMValidator
+>>> m = AAMapper(binary=True)
+>>> m.map_smiles("CC(=O)O.OC>>CC(=O)OC")
+>>> print(m.results[0]["smiles"])
+>>> validator = AAMValidator()
+
+Package layout
+--------------
+:mod:`synkit.Chem.Reaction.Mapper.graph`
+    Labeled-graph data structure, WL/2-WL refinement, automorphisms,
+    block-cut-tree decomposition.
+:mod:`synkit.Chem.Reaction.Mapper.slap`
+    Sequential-LAP engine (:class:`GraphMatcher`) and LAP utilities
+    (chemical distance, Gilmore-Lawler lower bound).
+:mod:`synkit.Chem.Reaction.Mapper.exact`
+    Kernelization, MILP/QAP solver, orbital-branching solver, exhaustive
+    DFS mapper, symmetry-distinct enumeration, and optimality certificates.
+:mod:`synkit.Chem.Reaction.Mapper.chem`
+    RDKit SMILES I/O and ITS-based deduplication / electron-balance checks.
+:mod:`synkit.Chem.Reaction.Mapper.io`
+    Index-mapping-string helpers.
+:mod:`synkit.Chem.Reaction.Mapper.aam_validator`
+    AAM validation against ground-truth mapped reaction SMILES.
+
+Public API
+----------
+"""
+
+from .graph.labeled_graph import LabeledGraph
+from .slap.sequential import GraphMatcher
+from .chem.aam import AAMapper
+from .aam_validator import AAMValidator
+
+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__ = [
+    "LabeledGraph",
+    "GraphMatcher",
+    "AAMapper",
+    "AAMValidator",
+    "RESEARCH_BASIS_TITLE",
+    "RESEARCH_BASIS_DOI",
+    "RESEARCH_BASIS_URL",
+    "RESEARCH_BASIS_AUTHORS",
+]

{synkit-1.4.0/synkit/Chem/Reaction → synkit-1.4.2b1/synkit/Chem/Reaction/Mapper}/aam_validator.py

@@ -2,6 +2,7 @@ import pandas as pd
 import networkx as nx
 from operator import eq
 from itertools import combinations
+from functools import wraps
 from joblib import Parallel, delayed
 from typing import Dict, List, Tuple, Union, Optional
 from networkx.algorithms.isomorphism import generic_node_match, generic_edge_match
@@ -12,6 +13,21 @@ from synkit.Graph.ITS.its_construction import ITSConstruction
 from synkit.Chem.utils import enumerate_tautomers, mapping_success_rate
 
 
+class _DualMethod:
+    """Bind a method to either an instance or the class."""
+
+    def __init__(self, func):
+        self.func = func
+        wraps(func)(self)
+
+    def __get__(self, obj, cls=None):
+        @wraps(self.func)
+        def wrapper(*args, **kwargs):
+            return self.func(obj, cls, *args, **kwargs)
+
+        return wrapper
+
+
 class AAMValidator:
     """A utility class for validating atom‐atom mappings (AAM) in reaction
     SMILES.
@@ -22,7 +38,7 @@ class AAMValidator:
 
     Quick start
     -----------
-    >>> from synkit.Chem.Reaction import AAMValidator
+    >>> from synkit.Chem.Reaction.Mapper import AAMValidator
     >>> validator = AAMValidator()
     >>> rsmi_1 = (
        '[CH3:1][C:2](=[O:3])[OH:4].[CH3:5][OH:6]'
@@ -37,9 +53,76 @@ class AAMValidator:
     >>> True
     """
 
-    def __init__(self) -> None:
-        """Initialize the AAMValidator."""
-        pass
+    def __init__(self, strip_unbalanced_maps: bool = True) -> None:
+        """Initialize the AAMValidator.
+
+        :param strip_unbalanced_maps: If True, remove atoms whose atom-map
+            labels are present on only one side before building ITS/RC graphs.
+            This reproduces the more permissive SynRXN benchmark behavior.
+        :type strip_unbalanced_maps: bool
+        """
+        self.strip_unbalanced_maps = strip_unbalanced_maps
+
+    @staticmethod
+    def _resolve_strip_unbalanced_maps(
+        instance: Optional["AAMValidator"],
+        strip_unbalanced_maps: Optional[bool],
+    ) -> bool:
+        """Resolve call-level override against the instance default."""
+        if strip_unbalanced_maps is not None:
+            return strip_unbalanced_maps
+        if instance is not None:
+            return instance.strip_unbalanced_maps
+        return True
+
+    @staticmethod
+    def _node_atom_map(graph: nx.Graph, node: object) -> Optional[int]:
+        """Return a node's atom-map label when available."""
+        value = graph.nodes[node].get("atom_map", node)
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
+    @staticmethod
+    def _strip_unbalanced_map_nodes(
+        reactant_graph: nx.Graph,
+        product_graph: nx.Graph,
+    ) -> Tuple[nx.Graph, nx.Graph]:
+        """Remove nodes whose atom maps are not present on both sides."""
+        reactant_maps = {
+            atom_map
+            for node in reactant_graph.nodes
+            if (atom_map := AAMValidator._node_atom_map(reactant_graph, node))
+            is not None
+        }
+        product_maps = {
+            atom_map
+            for node in product_graph.nodes
+            if (atom_map := AAMValidator._node_atom_map(product_graph, node))
+            is not None
+        }
+        common_maps = reactant_maps & product_maps
+
+        stripped_reactant = reactant_graph.copy()
+        stripped_product = product_graph.copy()
+        stripped_reactant.remove_nodes_from(
+            [
+                node
+                for node in stripped_reactant.nodes
+                if AAMValidator._node_atom_map(stripped_reactant, node)
+                not in common_maps
+            ]
+        )
+        stripped_product.remove_nodes_from(
+            [
+                node
+                for node in stripped_product.nodes
+                if AAMValidator._node_atom_map(stripped_product, node)
+                not in common_maps
+            ]
+        )
+        return stripped_reactant, stripped_product
 
     @staticmethod
     def check_equivariant_graph(
@@ -72,12 +155,15 @@ class AAMValidator:
 
         return classified, len(classified)
 
-    @staticmethod
+    @_DualMethod
     def smiles_check(
+        self,
+        cls,
         mapped_smile: str,
         ground_truth: str,
         check_method: str = "RC",
         ignore_aromaticity: bool = False,
+        strip_unbalanced_maps: Optional[bool] = None,
     ) -> bool:
         """Validate a single mapped SMILES string against ground truth.
 
@@ -92,14 +178,23 @@ class AAMValidator:
         :param ignore_aromaticity: If True, ignore aromaticity
             differences in ITS construction.
         :type ignore_aromaticity: bool
+        :param strip_unbalanced_maps: If True, remove atom-map labels present
+            on only one side before graph comparison. If None, use the
+            instance default or False for class-level calls.
+        :type strip_unbalanced_maps: bool or None
         :returns: True if exactly one isomorphic match is found; False
             otherwise.
         :rtype: bool
         """
         its_graphs, rc_graphs = [], []
+        strip_unbalanced_maps = cls._resolve_strip_unbalanced_maps(
+            self, strip_unbalanced_maps
+        )
         try:
             for rsmi in (mapped_smile, ground_truth):
                 G, H = rsmi_to_graph(rsmi=rsmi, sanitize=True, drop_non_aam=True)
+                if strip_unbalanced_maps:
+                    G, H = cls._strip_unbalanced_map_nodes(G, H)
                 its = ITSConstruction().ITSGraph(
                     G, H, ignore_aromaticity=ignore_aromaticity
                 )
@@ -112,12 +207,15 @@ class AAMValidator:
         except Exception:
             return False
 
-    @staticmethod
+    @_DualMethod
     def smiles_check_tautomer(
+        self,
+        cls,
         mapped_smile: str,
         ground_truth: str,
         check_method: str = "RC",
         ignore_aromaticity: bool = False,
+        strip_unbalanced_maps: Optional[bool] = None,
     ) -> Optional[bool]:
         """Validate against all tautomers of a ground truth SMILES.
 
@@ -129,31 +227,45 @@ class AAMValidator:
         :type check_method: str
         :param ignore_aromaticity: If True, ignore aromaticity in ITS construction.
         :type ignore_aromaticity: bool
+        :param strip_unbalanced_maps: If True, remove atom-map labels present
+            on only one side before graph comparison. If None, use the
+            instance default or False for class-level calls.
+        :type strip_unbalanced_maps: bool or None
         :returns:
             - `True` if any tautomer matches.
             - `False` if none match.
             - `None` if an error occurs.
         :rtype: bool or None
         """
+        strip_unbalanced_maps = cls._resolve_strip_unbalanced_maps(
+            self, strip_unbalanced_maps
+        )
         try:
             tautomers = enumerate_tautomers(ground_truth)
             return any(
-                AAMValidator.smiles_check(
-                    mapped_smile, taut, check_method, ignore_aromaticity
+                cls.smiles_check(
+                    mapped_smile,
+                    taut,
+                    check_method,
+                    ignore_aromaticity,
+                    strip_unbalanced_maps,
                 )
                 for taut in tautomers
             )
         except Exception:
             return None
 
-    @staticmethod
+    @_DualMethod
     def check_pair(
+        self,
+        cls,
         mapping: Dict[str, str],
         mapped_col: str,
         ground_truth_col: str,
         check_method: str = "RC",
         ignore_aromaticity: bool = False,
         ignore_tautomers: bool = True,
+        strip_unbalanced_maps: Optional[bool] = None,
     ) -> bool:
         """Validate a single record (dict) entry for equivalence.
 
@@ -169,26 +281,37 @@ class AAMValidator:
         :type ignore_aromaticity: bool
         :param ignore_tautomers: If True, skip tautomer enumeration.
         :type ignore_tautomers: bool
+        :param strip_unbalanced_maps: If True, remove atom-map labels present
+            on only one side before graph comparison. If None, use the
+            instance default or False for class-level calls.
+        :type strip_unbalanced_maps: bool or None
         :returns: Validation result for this single pair.
         :rtype: bool
         """
+        strip_unbalanced_maps = cls._resolve_strip_unbalanced_maps(
+            self, strip_unbalanced_maps
+        )
         if ignore_tautomers:
-            return AAMValidator.smiles_check(
+            return cls.smiles_check(
                 mapping[mapped_col],
                 mapping[ground_truth_col],
                 check_method,
                 ignore_aromaticity,
+                strip_unbalanced_maps,
             )
         else:
-            return AAMValidator.smiles_check_tautomer(
+            return cls.smiles_check_tautomer(
                 mapping[mapped_col],
                 mapping[ground_truth_col],
                 check_method,
                 ignore_aromaticity,
+                strip_unbalanced_maps,
             )
 
-    @staticmethod
+    @_DualMethod
     def validate_smiles(
+        self,
+        cls,
         data: Union[pd.DataFrame, List[Dict[str, str]]],
         ground_truth_col: str = "ground_truth",
         mapped_cols: List[str] = ["rxn_mapper", "graphormer", "local_mapper"],
@@ -197,6 +320,7 @@ class AAMValidator:
         n_jobs: int = 1,
         verbose: int = 0,
         ignore_tautomers: bool = True,
+        strip_unbalanced_maps: Optional[bool] = None,
     ) -> List[Dict[str, Union[str, float, List[bool]]]]:
         """Batch-validate mapped SMILES in tabular or list-of-dicts form.
 
@@ -217,6 +341,10 @@ class AAMValidator:
         :type verbose: int
         :param ignore_tautomers: If True, use simple pairwise check; otherwise enumerate tautomers.
         :type ignore_tautomers: bool
+        :param strip_unbalanced_maps: If True, remove atom-map labels present
+            on only one side before graph comparison. If None, use the
+            instance default or False for class-level calls.
+        :type strip_unbalanced_maps: bool or None
         :returns: A list of dicts, one per mapper, with keys:
                   - `"mapper"`: the mapper name
                   - `"accuracy"`: percentage correct (float)
@@ -237,15 +365,19 @@ class AAMValidator:
                 "Data must be either a pandas DataFrame or a list of dictionaries."
             )
 
+        strip_unbalanced_maps = cls._resolve_strip_unbalanced_maps(
+            self, strip_unbalanced_maps
+        )
         for mapped_col in mapped_cols:
             results = Parallel(n_jobs=n_jobs, verbose=verbose)(
-                delayed(AAMValidator.check_pair)(
+                delayed(cls.check_pair)(
                     mapping,
                     mapped_col,
                     ground_truth_col,
                     check_method,
                     ignore_aromaticity,
                     ignore_tautomers,
+                    strip_unbalanced_maps,
                 )
                 for mapping in mappings
             )

synkit-1.4.2b1/synkit/Chem/Reaction/Mapper/chem/__init__.py

@@ -0,0 +1,46 @@
+"""
+mapper.chem — chemistry front-end (RDKit SMILES, ITS analysis).
+
+Submodules
+----------
+aam
+    :class:`AAMapper`: high-level reaction-SMILES atom-to-atom mapper.
+smiles
+    SMILES ↔ LabeledGraph conversion and reaction-SMILES annotation utilities.
+its
+    ITS graph hashing, electron-balance checks, and symmetry-distinct
+    deduplication via synkit.
+"""
+
+from .aam import AAMapper
+from .its import (
+    its_canonical_hash,
+    dedup_mapped_rxns,
+    mapped_rxn_is_electron_balanced,
+    is_electron_balanced,
+    electron_balance_status,
+)
+from .smiles import (
+    HAS_RDKIT,
+    smiles2lgp,
+    get_numbered_rxn_smiles,
+    canonicalize_rxn_smiles,
+    expand_reaction_center_hydrogens,
+)
+
+__all__ = [
+    # aam
+    "AAMapper",
+    # its
+    "its_canonical_hash",
+    "dedup_mapped_rxns",
+    "mapped_rxn_is_electron_balanced",
+    "is_electron_balanced",
+    "electron_balance_status",
+    # smiles
+    "HAS_RDKIT",
+    "smiles2lgp",
+    "get_numbered_rxn_smiles",
+    "canonicalize_rxn_smiles",
+    "expand_reaction_center_hydrogens",
+]