synkit 1.4.2b1__tar.gz → 1.5.0__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synkit
-Version: 1.4.2b1
+Version: 1.5.0
 Summary: Utility for reaction modeling using graph grammar
 Project-URL: homepage, https://github.com/TieuLongPhan/SynKit
 Project-URL: source, https://github.com/TieuLongPhan/SynKit
@@ -19,6 +19,7 @@ Requires-Dist: rdkit>=2025.3.1
 Requires-Dist: regex>=2024.11.6
 Requires-Dist: requests>=2.32.3
 Requires-Dist: scikit-learn>=1.4.0
+Requires-Dist: scipy>=1.14.0
 Requires-Dist: seaborn>=0.13.2
 Provides-Extra: all
 Requires-Dist: numpy>=2.2.0; extra == 'all'

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synkit"
-version = "1.4.2b1"
+version = "1.5.0"
 description = "Utility for reaction modeling using graph grammar"
 readme = "README.md"
 long-description = { file = "CHANGELOG.md" }
@@ -25,6 +25,7 @@ dependencies = [
   "pandas>=1.5.3",
   "rdkit>=2025.3.1",
   "networkx>=3.3",
+  "scipy>=1.14.0",
   "seaborn>=0.13.2",
   "requests>=2.32.3",
   "regex>=2024.11.6",

{synkit-1.4.2b1 → synkit-1.5.0}/synkit/Chem/Fingerprint/transformation_fp.py

@@ -36,14 +36,18 @@ class TransformationFP:
 
     @staticmethod
     def convert_arr2vec(arr: np.ndarray) -> cDataStructs.ExplicitBitVect:
-        """Convert a NumPy array of bits into an RDKit ExplicitBitVect.
+        """Convert a non-negative NumPy array into an RDKit bit vector.
 
-        :param arr: Array of 0/1 values representing a fingerprint.
+        :param arr: Array of non-negative fingerprint values.
         :type arr: np.ndarray
-        :returns: RDKit bit vector constructed from the bit string.
+        :returns: RDKit bit vector with positive values encoded as 1.
         :rtype: cDataStructs.ExplicitBitVect
+        :raises ValueError: If the array contains negative or non-finite values.
         """
-        bitstr = "".join(str(int(x)) for x in arr.flatten())
+        flat = np.asarray(arr).flatten()
+        if not np.isfinite(flat).all() or (flat < 0).any():
+            raise ValueError("Bit-vector output requires non-negative finite values.")
+        bitstr = "".join("1" if x else "0" for x in flat)
         return cDataStructs.CreateFromBitString(bitstr)
 
     def fit(

{synkit-1.4.2b1 → synkit-1.5.0}/synkit/Chem/Reaction/__init__.py

@@ -1,6 +1,7 @@
 from .aam_validator import AAMValidator
+from synkit.Chem.utils import remove_explicit_H_from_rsmi
 
 # from .standardize import Standardize
 # from .canon_rsmi import CanonRSMI
 
-__all__ = ["AAMValidator"]
+__all__ = ["AAMValidator", "remove_explicit_H_from_rsmi"]

{synkit-1.4.2b1 → synkit-1.5.0}/synkit/Chem/Reaction/tautomerize.py

@@ -121,10 +121,7 @@ class Tautomerize:
         mol = Chem.MolFromSmiles(smiles)
         if mol is None:
             return []
-        try:
-            graph, groups = smiles_to_graph_and_functional_groups(smiles)
-        except ValueError:
-            return []
+        graph, groups = smiles_to_graph_and_functional_groups(smiles)
         node_to_idx = {
             (
                 atom.GetAtomMapNum() if atom.GetAtomMapNum() else atom.GetIdx() + 1

{synkit-1.4.2b1 → synkit-1.5.0}/synkit/Graph/ITS/its_expand.py

@@ -100,13 +100,36 @@ class ITSExpand:
             )
 
     @staticmethod
-    def _validate_positive_atom_maps(atom_maps: list[int]) -> None:
-        """Validate that atom-map numbers can be used as node IDs.
+    def _validate_atom_maps_within_range(
+        atom_maps: list[int],
+        n_nodes: int,
+    ) -> None:
+        """Validate that atom-map numbers can be used as contiguous node IDs.
+
+        In the side graph, we want final node IDs to remain exactly ``1..N``.
+        Therefore, a mapped atom can only be moved to its atom-map number if
+        that number is within ``1..N``.
 
         :param atom_maps: Nonzero atom-map numbers.
         :type atom_maps: list[int]
-        :raises ValueError: If any atom-map number is not positive.
+        :param n_nodes: Number of nodes in the side graph.
+        :type n_nodes: int
+        :raises ValueError: If any atom-map number is outside ``1..N``.
         """
+        bad_targets = [
+            atom_map for atom_map in atom_maps if atom_map < 1 or atom_map > n_nodes
+        ]
+
+        if bad_targets:
+            raise ValueError(
+                "Cannot keep side graph node ids contiguous from 1..N while "
+                f"also using atom_map as node id. The following atom maps are "
+                f"outside 1..{n_nodes}: {bad_targets}"
+            )
+
+    @staticmethod
+    def _validate_positive_atom_maps(atom_maps: list[int]) -> None:
+        """Validate that atom-map numbers are valid positive node IDs."""
         bad_targets = [atom_map for atom_map in atom_maps if atom_map < 1]
 
         if bad_targets:
@@ -141,33 +164,17 @@ class ITSExpand:
 
         return mapping, used_ids
 
-    @staticmethod
-    def _next_free_positive_id(used_ids: set[int], start: int = 1) -> int:
-        """Return the smallest positive integer not present in ``used_ids``.
-
-        :param used_ids: Node IDs already occupied by mapped atoms.
-        :type used_ids: set[int]
-        :param start: First candidate ID.
-        :type start: int
-        :returns: Available positive node ID.
-        :rtype: int
-        """
-        candidate = max(1, start)
-        while candidate in used_ids:
-            candidate += 1
-        return candidate
-
     @staticmethod
     def _assign_unmapped_nodes(
         graph,
         mapping: dict,
         used_ids: set[int],
     ) -> dict:
-        """Assign unmapped atoms while avoiding mapped atom-map IDs.
+        """Assign unmapped atoms while preserving contiguous node IDs.
 
         Unmapped atoms keep their original node ID when possible. If an
-        unmapped atom's node ID conflicts with a mapped atom-map target, it is
-        moved into the smallest unused positive ID.
+        unmapped atom's node ID conflicts with a mapped atom's target ID, it is
+        moved into one of the remaining free IDs inside ``1..N``.
 
         :param graph: Molecular side graph.
         :type graph: networkx.Graph
@@ -178,7 +185,9 @@ class ITSExpand:
         :returns: Complete old-node to new-node mapping.
         :rtype: dict
         """
-        next_candidate = 1
+        n_nodes = graph.number_of_nodes()
+        free_ids = set(range(1, n_nodes + 1)) - used_ids
+        pending_unmapped = []
 
         for node, data in graph.nodes(data=True):
             atom_map = ITSExpand._atom_map(data)
@@ -186,29 +195,68 @@ class ITSExpand:
             if atom_map != 0:
                 continue
 
+            if isinstance(node, int) and node in free_ids:
+                mapping[node] = node
+                free_ids.remove(node)
+            else:
+                pending_unmapped.append(node)
+
+        for old_node, new_node in zip(pending_unmapped, sorted(free_ids)):
+            mapping[old_node] = new_node
+
+        return mapping
+
+    @staticmethod
+    def _assign_unmapped_nodes_sparse(
+        graph,
+        mapping: dict,
+        used_ids: set[int],
+    ) -> dict:
+        """Assign unmapped atoms without changing preserved sparse map IDs."""
+        next_candidate = 1
+
+        for node, data in graph.nodes(data=True):
+            if ITSExpand._atom_map(data) != 0:
+                continue
+
             if isinstance(node, int) and node > 0 and node not in used_ids:
                 mapping[node] = node
                 used_ids.add(node)
                 next_candidate = max(next_candidate, node + 1)
                 continue
 
-            new_node = ITSExpand._next_free_positive_id(used_ids, next_candidate)
-            mapping[node] = new_node
-            used_ids.add(new_node)
-            next_candidate = new_node + 1
+            while next_candidate in used_ids:
+                next_candidate += 1
+            mapping[node] = next_candidate
+            used_ids.add(next_candidate)
+            next_candidate += 1
 
         return mapping
 
     @staticmethod
-    def _validate_complete_unique_mapping(mapping: dict, n_nodes: int) -> None:
-        """Validate that every source node maps to a unique target node.
+    def _validate_contiguous_mapping(mapping: dict, n_nodes: int) -> None:
+        """Validate that a mapping produces exactly node IDs ``1..N``.
 
         :param mapping: Old-node to new-node mapping.
         :type mapping: dict
         :param n_nodes: Number of nodes in the graph.
         :type n_nodes: int
-        :raises RuntimeError: If the mapping is incomplete or has collisions.
+        :raises RuntimeError: If the mapped node IDs are not exactly ``1..N``.
         """
+        expected_ids = set(range(1, n_nodes + 1))
+        actual_ids = set(mapping.values())
+
+        if actual_ids != expected_ids:
+            missing = sorted(expected_ids - actual_ids)
+            extra = sorted(actual_ids - expected_ids)
+            raise RuntimeError(
+                f"Reindexing failed. Missing node ids: {missing}; "
+                f"extra node ids: {extra}"
+            )
+
+    @staticmethod
+    def _validate_complete_unique_mapping(mapping: dict, n_nodes: int) -> None:
+        """Validate that every source node maps to one unique target node."""
         if len(mapping) != n_nodes:
             raise RuntimeError(
                 f"Reindexing failed. Expected {n_nodes} mapped nodes; "
@@ -222,32 +270,48 @@ class ITSExpand:
             )
 
     @staticmethod
-    def _build_side_graph_reindex_mapping(graph) -> dict:
+    def _build_side_graph_reindex_mapping(
+        graph,
+        contiguous: bool = True,
+    ) -> dict:
         """Build an old-node to new-node mapping for a side graph.
 
         The mapping satisfies two conditions:
 
         1. Every atom with ``atom_map != 0`` is assigned to node ID
            ``atom_map``.
-        2. Every unmapped atom is assigned a unique positive node ID that does
-           not collide with preserved atom-map IDs.
+        2. The final node IDs are exactly contiguous from ``1..N`` when
+           ``contiguous=True``. With ``contiguous=False``, existing positive,
+           sparse atom-map IDs are retained and unmapped atoms receive unused
+           positive IDs.
 
         :param graph: Molecular side graph.
         :type graph: networkx.Graph
         :returns: Old-node to new-node mapping.
         :rtype: dict
-        :raises ValueError: If atom-map values are duplicated or non-positive.
+        :raises ValueError: If atom-map values are duplicated or incompatible
+            with contiguous node IDs.
         """
         n_nodes = graph.number_of_nodes()
         atom_maps = ITSExpand._nonzero_atom_maps(graph)
 
         ITSExpand._validate_unique_atom_maps(atom_maps)
-        ITSExpand._validate_positive_atom_maps(atom_maps)
+        if contiguous:
+            ITSExpand._validate_atom_maps_within_range(atom_maps, n_nodes)
+        else:
+            ITSExpand._validate_positive_atom_maps(atom_maps)
 
         mapping, used_ids = ITSExpand._assign_mapped_nodes(graph)
-        mapping = ITSExpand._assign_unmapped_nodes(graph, mapping, used_ids)
-
-        ITSExpand._validate_complete_unique_mapping(mapping, n_nodes)
+        if contiguous:
+            mapping = ITSExpand._assign_unmapped_nodes(graph, mapping, used_ids)
+            ITSExpand._validate_contiguous_mapping(mapping, n_nodes)
+        else:
+            mapping = ITSExpand._assign_unmapped_nodes_sparse(
+                graph,
+                mapping,
+                used_ids,
+            )
+            ITSExpand._validate_complete_unique_mapping(mapping, n_nodes)
 
         return mapping
 
@@ -319,12 +383,12 @@ class ITSExpand:
         return new_graph
 
     @staticmethod
-    def reindex_side_graph_by_atom_map(graph):
+    def reindex_side_graph_by_atom_map(graph, contiguous: bool = True):
         """Reindex a side graph so mapped atoms use ``atom_map`` as node ID.
 
-        The returned graph keeps mapped atom node IDs equal to their atom-map
-        values. Unmapped atom node IDs remain compact where possible, but may
-        become sparse to avoid collisions with preserved atom maps.
+        By default, the returned graph keeps node IDs contiguous from ``1..N``.
+        Set ``contiguous=False`` to preserve valid sparse map IDs such as
+        ``:10`` and ``:21``; this is needed by the EF-SMIRKS expansion path.
 
         This is useful because the reaction-center graph produced by
         ``ITSConstruction().ITSGraph(...)`` uses atom-map numbers as node IDs,
@@ -351,12 +415,14 @@ class ITSExpand:
 
         :param graph: Molecular side graph.
         :type graph: networkx.Graph
-        :returns: Reindexed side graph with preserved mapped node IDs.
+        :param contiguous: Whether the returned node IDs must be ``1..N``.
+        :type contiguous: bool
+        :returns: Reindexed side graph.
         :rtype: networkx.Graph
         :raises ValueError: If atom-map numbers cannot be safely used as node
-            IDs.
+            IDs while preserving ``1..N`` indexing.
         """
-        mapping = ITSExpand._build_side_graph_reindex_mapping(graph)
+        mapping = ITSExpand._build_side_graph_reindex_mapping(graph, contiguous)
         return ITSExpand._rebuild_graph_with_mapping(graph, mapping)
 
     @staticmethod
@@ -431,7 +497,10 @@ class ITSExpand:
 
         # Node IDs remain contiguous from 1..N.
         if preserve_older_map:
-            side_graph = ITSExpand.reindex_side_graph_by_atom_map(side_graph)
+            side_graph = ITSExpand.reindex_side_graph_by_atom_map(
+                side_graph,
+                contiguous=False,
+            )
 
         # Reconstruct the full ITS graph.
         its_graph = ITSBuilder().ITSGraph(side_graph, rc_graph)

{synkit-1.4.2b1 → synkit-1.5.0}/synkit/Graph/Matcher/subgraph_matcher.py

@@ -128,10 +128,6 @@ def electron_aware_node_match(
             attr, 0 if attr in {"hcount", "lone_pairs"} else None
         )
         if attr in {"hcount", "lone_pairs"}:
-            if host_value is None:
-                host_value = 0
-            if pattern_value is None:
-                pattern_value = 0
             if host_value < pattern_value:
                 return False
             continue

{synkit-1.4.2b1 → synkit-1.5.0}/synkit/Graph/Mech/conversion.py

@@ -73,6 +73,69 @@ def split_arrow_code(arrow_code: str) -> list[str]:
     return [s.strip() for s in arrow_code.split(";") if s.strip()]
 
 
+def ef_arrow_code_to_arrow_code(ef_arrow_code: str) -> str:
+    """Normalize an EF-SMIRKS hyphen-form flow code for SynKit conversion.
+
+    EF-SMIRKS stores one electron-flow step as ``source-target``; SynKit's
+    internal arrow-code helpers use ``source=target``.  For example,
+    ``"10,20-20,21"`` becomes ``"10,20=20,21"``.
+
+    :param ef_arrow_code: Semicolon-separated hyphen-form electron-flow code.
+    :type ef_arrow_code: str
+    :returns: Equivalent equals-form SynKit arrow code.
+    :rtype: str
+    :raises ValueError: If a step does not contain exactly one ``"-"``.
+    """
+    normalized_steps = []
+    for step in split_arrow_code(ef_arrow_code):
+        if step.count("-") != 1:
+            raise ValueError(
+                "An EF-SMIRKS electron-flow step must contain exactly one '-': "
+                f"{step!r}"
+            )
+        lhs, rhs = step.split("-", 1)
+        normalized_steps.append(f"{lhs.strip()}={rhs.strip()}")
+    if not normalized_steps:
+        raise ValueError("EF-SMIRKS electron-flow code is empty.")
+    return ";".join(normalized_steps)
+
+
+def arrow_code_to_ef_arrow_code(arrow_code: str) -> str:
+    """Convert internal equals-form arrow code to EF-SMIRKS hyphen form.
+
+    :param arrow_code: Semicolon-separated SynKit arrow code.
+    :type arrow_code: str
+    :returns: Equivalent hyphen-form electron-flow code.
+    :rtype: str
+    """
+    return ";".join(step.replace("=", "-", 1) for step in split_arrow_code(arrow_code))
+
+
+def split_ef_smirks(ef_smirks: str) -> tuple[str, str]:
+    """Split an EF-SMIRKS string into reaction SMILES and flow code.
+
+    An EF-SMIRKS is an atom-mapped reaction SMILES followed by whitespace and
+    a hyphen-form electron-flow code, e.g. ``"[CH3:1][Cl:2]>>[CH3:1].[Cl-:2]
+    1-1,2"``.
+
+    :param ef_smirks: RSMI followed by whitespace and electron-flow code.
+    :type ef_smirks: str
+    :returns: Reaction SMILES and hyphen-form electron-flow code.
+    :rtype: tuple[str, str]
+    :raises ValueError: If the input lacks an RSMI arrow or flow code.
+    """
+    try:
+        reaction_smiles, ef_arrow_code = ef_smirks.strip().rsplit(None, 1)
+    except ValueError as exc:
+        raise ValueError(
+            "EF-SMIRKS must contain reaction SMILES followed by whitespace and "
+            "an electron-flow code."
+        ) from exc
+    if ">>" not in reaction_smiles:
+        raise ValueError("EF-SMIRKS reaction component must contain '>>'.")
+    return reaction_smiles, ef_arrow_code
+
+
 def arrow_atom_maps(arrow_code: str) -> set[int]:
     """Return all atom maps used in an arrow code.
 
@@ -946,6 +1009,105 @@ def convert_reaction_arrow(
     return result
 
 
+def ef_smirks_to_epd(
+    ef_smirks: str,
+    orbital_class: Optional[str] = None,
+    strict_bond_lookup: bool = True,
+) -> dict[str, Any]:
+    """Complete AAM and convert an EF-SMIRKS string into EPD data.
+
+    The supplied atom maps used by the electron-flow code are preserved. All
+    remaining atoms receive maps through :class:`ITSExpand`.  The result
+    contains both generic ``epd`` and Lewis-wavefunction-aware ``epd_lw``
+    records; the latter uses local ITS bond orders to distinguish sigma and pi
+    edits.
+
+    :param ef_smirks: RSMI followed by a hyphen-form electron-flow code.
+    :type ef_smirks: str
+    :param orbital_class: Optional source-dataset metadata.
+    :type orbital_class: Optional[str]
+    :param strict_bond_lookup: Whether missing ITS bond lookups should raise.
+    :type strict_bond_lookup: bool
+    :returns: Completed AAM, generic EPD, typed ``epd_lw``, and diagnostics.
+    :rtype: dict[str, Any]
+    """
+    reaction_smiles, ef_arrow_code = split_ef_smirks(ef_smirks)
+    arrow_code = ef_arrow_code_to_arrow_code(ef_arrow_code)
+    result = convert_reaction_arrow(
+        reaction_smiles=reaction_smiles,
+        arrow_code=arrow_code,
+        orbital_class=orbital_class,
+        expand_aam=True,
+        remove_non_arrow_maps=True,
+        strict_bond_lookup=strict_bond_lookup,
+    )
+    result.update(
+        {
+            "ef_smirks": ef_smirks,
+            "ef_arrow_code": ef_arrow_code,
+            "complete_aam": result["expanded_rsmi"],
+            "epd": result["converted"],
+            "epd_lw": result["typed_converted"],
+        }
+    )
+    return result
+
+
+def epd_to_ef_smirks(complete_aam: str, epd: list[list[Any]]) -> str:
+    """Reconstruct an EF-SMIRKS string from complete AAM and EPD records.
+
+    ``epd`` may contain generic action names (``"B-/B+"``) or typed Lewis
+    names (``"Sigma-/Pi+"``). Only action direction and source/target map
+    lists are needed to reconstruct the electron-flow code.
+
+    :param complete_aam: Fully atom-mapped reaction SMILES.
+    :type complete_aam: str
+    :param epd: Generic or typed EPD records of ``[action, source, target]``.
+    :type epd: list[list[Any]]
+    :returns: EF-SMIRKS text with a hyphen-form electron-flow code.
+    :rtype: str
+    :raises ValueError: If AAM or EPD records are malformed or unsupported.
+    """
+    if complete_aam.count(">>") != 1:
+        raise ValueError("complete_aam must contain exactly one '>>'.")
+    if not epd:
+        raise ValueError("epd must contain at least one electron-pushing step.")
+
+    def format_maps(atom_maps: list[int]) -> str:
+        """Format an atom-map sequence for one EF-SMIRKS endpoint."""
+        return ",".join(str(atom_map) for atom_map in atom_maps)
+
+    steps = []
+    for record in epd:
+        if len(record) < 3:
+            raise ValueError(f"Invalid EPD record: {record!r}")
+        action, source, target = record[:3]
+        action_parts = str(action).split("/", 1)
+        if len(action_parts) != 2:
+            raise ValueError(f"Invalid EPD action: {action!r}")
+        consumed, produced = action_parts
+        source = [int(atom_map) for atom_map in source]
+        target = [int(atom_map) for atom_map in target]
+
+        if consumed == "LP-" and len(source) == 1 and len(target) in {1, 2}:
+            lhs, rhs = source, target
+        elif produced == "LP+" and len(source) == 2 and len(target) == 1:
+            lhs, rhs = source, target
+        elif (
+            consumed.endswith("-")
+            and produced.endswith("+")
+            and len(source) == 2
+            and len(target) == 2
+        ):
+            lhs, rhs = source, target
+        else:
+            raise ValueError(f"Unsupported EPD record for EF-SMIRKS: {record!r}")
+
+        steps.append(f"{format_maps(lhs)}-{format_maps(rhs)}")
+
+    return f"{complete_aam} {';'.join(steps)}"
+
+
 def convert_record(
     record: dict[str, Any],
     reaction_key: str = "SMIRKS",