synkit 1.4.0__tar.gz → 1.4.1b1__tar.gz

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

@@ -37,3 +37,4 @@ test_syn.py
 .gitignore
 measure_candidate_stages.py
 run_valid_bug_cases.py
+debug/*

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synkit
-Version: 1.4.0
+Version: 1.4.1b1
 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.1b1}/pyproject.toml

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

{synkit-1.4.0 → synkit-1.4.1b1}/synkit/Graph/ITS/its_expand.py

@@ -100,31 +100,19 @@ class ITSExpand:
             )
 
     @staticmethod
-    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``.
+    def _validate_positive_atom_maps(atom_maps: list[int]) -> None:
+        """Validate that atom-map numbers can be used as node IDs.
 
         :param atom_maps: Nonzero atom-map numbers.
         :type atom_maps: list[int]
-        :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``.
+        :raises ValueError: If any atom-map number is not positive.
         """
-        bad_targets = [
-            atom_map for atom_map in atom_maps if atom_map < 1 or atom_map > n_nodes
-        ]
+        bad_targets = [atom_map for atom_map in atom_maps if atom_map < 1]
 
         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}"
+                "Cannot use non-positive atom_map values as node ids. "
+                f"Invalid atom maps: {bad_targets}"
             )
 
     @staticmethod
@@ -153,17 +141,33 @@ 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 preserving contiguous node IDs.
+        """Assign unmapped atoms while avoiding mapped atom-map IDs.
 
         Unmapped atoms keep their original node ID when possible. If an
-        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``.
+        unmapped atom's node ID conflicts with a mapped atom-map target, it is
+        moved into the smallest unused positive ID.
 
         :param graph: Molecular side graph.
         :type graph: networkx.Graph
@@ -174,9 +178,7 @@ class ITSExpand:
         :returns: Complete old-node to new-node mapping.
         :rtype: dict
         """
-        n_nodes = graph.number_of_nodes()
-        free_ids = set(range(1, n_nodes + 1)) - used_ids
-        pending_unmapped = []
+        next_candidate = 1
 
         for node, data in graph.nodes(data=True):
             atom_map = ITSExpand._atom_map(data)
@@ -184,36 +186,39 @@ class ITSExpand:
             if atom_map != 0:
                 continue
 
-            if isinstance(node, int) and node in free_ids:
+            if isinstance(node, int) and node > 0 and node not in used_ids:
                 mapping[node] = node
-                free_ids.remove(node)
-            else:
-                pending_unmapped.append(node)
+                used_ids.add(node)
+                next_candidate = max(next_candidate, node + 1)
+                continue
 
-        for old_node, new_node in zip(pending_unmapped, sorted(free_ids)):
-            mapping[old_node] = new_node
+            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
 
         return mapping
 
     @staticmethod
-    def _validate_contiguous_mapping(mapping: dict, n_nodes: int) -> None:
-        """Validate that a mapping produces exactly node IDs ``1..N``.
+    def _validate_complete_unique_mapping(mapping: dict, n_nodes: int) -> None:
+        """Validate that every source node maps to a unique target node.
 
         :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 mapped node IDs are not exactly ``1..N``.
+        :raises RuntimeError: If the mapping is incomplete or has collisions.
         """
-        expected_ids = set(range(1, n_nodes + 1))
-        actual_ids = set(mapping.values())
+        if len(mapping) != n_nodes:
+            raise RuntimeError(
+                f"Reindexing failed. Expected {n_nodes} mapped nodes; "
+                f"got {len(mapping)}."
+            )
 
-        if actual_ids != expected_ids:
-            missing = sorted(expected_ids - actual_ids)
-            extra = sorted(actual_ids - expected_ids)
+        if len(set(mapping.values())) != n_nodes:
             raise RuntimeError(
-                f"Reindexing failed. Missing node ids: {missing}; "
-                f"extra node ids: {extra}"
+                "Reindexing failed. Multiple source nodes map to the same "
+                "target node id."
             )
 
     @staticmethod
@@ -224,25 +229,25 @@ class ITSExpand:
 
         1. Every atom with ``atom_map != 0`` is assigned to node ID
            ``atom_map``.
-        2. The final node IDs are exactly contiguous from ``1..N``.
+        2. Every unmapped atom is assigned a unique positive node ID that does
+           not collide with preserved atom-map 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 incompatible
-            with contiguous node IDs.
+        :raises ValueError: If atom-map values are duplicated or non-positive.
         """
         n_nodes = graph.number_of_nodes()
         atom_maps = ITSExpand._nonzero_atom_maps(graph)
 
         ITSExpand._validate_unique_atom_maps(atom_maps)
-        ITSExpand._validate_atom_maps_within_range(atom_maps, n_nodes)
+        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_contiguous_mapping(mapping, n_nodes)
+        ITSExpand._validate_complete_unique_mapping(mapping, n_nodes)
 
         return mapping
 
@@ -317,7 +322,9 @@ class ITSExpand:
     def reindex_side_graph_by_atom_map(graph):
         """Reindex a side graph so mapped atoms use ``atom_map`` as node ID.
 
-        The returned graph keeps node IDs contiguous from ``1..N``.
+        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.
 
         This is useful because the reaction-center graph produced by
         ``ITSConstruction().ITSGraph(...)`` uses atom-map numbers as node IDs,
@@ -344,10 +351,10 @@ class ITSExpand:
 
         :param graph: Molecular side graph.
         :type graph: networkx.Graph
-        :returns: Reindexed side graph with contiguous node IDs.
+        :returns: Reindexed side graph with preserved mapped node IDs.
         :rtype: networkx.Graph
         :raises ValueError: If atom-map numbers cannot be safely used as node
-            IDs while preserving ``1..N`` indexing.
+            IDs.
         """
         mapping = ITSExpand._build_side_graph_reindex_mapping(graph)
         return ITSExpand._rebuild_graph_with_mapping(graph, mapping)

synkit-1.4.1b1/synkit/Graph/Mech/__init__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synkit.Graph.Mech.lwg_editor import LWGEditResult, LWGEditor, LWGStepReport
+
+__all__ = ["LWGEditor", "LWGEditResult", "LWGStepReport"]
+
+
+def __getattr__(name: str):
+    if name in __all__:
+        from synkit.Graph.Mech.lwg_editor import (
+            LWGEditResult,
+            LWGEditor,
+            LWGStepReport,
+        )
+
+        exports = {
+            "LWGEditor": LWGEditor,
+            "LWGEditResult": LWGEditResult,
+            "LWGStepReport": LWGStepReport,
+        }
+        return exports[name]
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

synkit-1.4.1b1/synkit/Graph/Mech/electron_accounting.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import networkx as nx
+from rdkit import Chem
+
+
+@dataclass(frozen=True)
+class ChargeRefresh:
+    """VE/NBE/B charge refresh report for one atom map.
+
+    :param atom_map: Refreshed atom map.
+    :type atom_map: int
+    :param node: NetworkX node corresponding to ``atom_map``.
+    :type node: Any
+    :param previous_charge: Charge before refresh.
+    :type previous_charge: int | float
+    :param refreshed_charge: Charge computed by ``VE - NBE - B``.
+    :type refreshed_charge: int | float
+    :param valence_electrons: Atom valence electron count used as ``VE``.
+    :type valence_electrons: float
+    :param nonbonding_electrons: Nonbonding electron count used as ``NBE``.
+    :type nonbonding_electrons: float
+    :param bond_electrons: Bond electron count used as ``B``.
+    :type bond_electrons: float
+    """
+
+    atom_map: int
+    node: Any
+    previous_charge: int | float
+    refreshed_charge: int | float
+    valence_electrons: float
+    nonbonding_electrons: float
+    bond_electrons: float
+
+
+@dataclass(frozen=True)
+class ChargeEdit:
+    """Incremental local charge edit for one atom map.
+
+    :param atom_map: Edited atom map.
+    :type atom_map: int
+    :param node: NetworkX node corresponding to ``atom_map``.
+    :type node: Any
+    :param delta: Applied formal-charge delta.
+    :type delta: int | float
+    :param previous_charge: Charge before the edit.
+    :type previous_charge: int | float
+    :param new_charge: Charge after the edit.
+    :type new_charge: int | float
+    """
+
+    atom_map: int
+    node: Any
+    delta: int | float
+    previous_charge: int | float
+    new_charge: int | float
+
+
+def bond_order_sum(graph: nx.Graph, node: Any) -> float:
+    """Return the sigma-plus-pi bond-order sum around one node.
+
+    :param graph: Lewis graph.
+    :type graph: nx.Graph
+    :param node: Node whose incident bond orders should be summed.
+    :type node: Any
+    :returns: Sum of incident ``sigma_order + pi_order`` values.
+    :rtype: float
+    """
+    total = 0.0
+    for _, _, data in graph.edges(node, data=True):
+        total += float(data.get("sigma_order", 0.0)) + float(data.get("pi_order", 0.0))
+    return total
+
+
+def recompute_charge(graph: nx.Graph, node: Any) -> int | float:
+    """Recompute formal charge from stored electron-state fields.
+
+    This diagnostic helper uses ``Formal Charge = VE - NBE - B``. The
+    :class:`synkit.Graph.Mech.lwg_editor.LWGEditor` production edit path uses
+    local charge deltas instead.
+
+    :param graph: Lewis graph.
+    :type graph: nx.Graph
+    :param node: Node whose charge should be recomputed.
+    :type node: Any
+    :returns: Recomputed formal charge.
+    :rtype: int | float
+    """
+    attrs = graph.nodes[node]
+    charge = (
+        float(attrs["valence_electrons"])
+        - nonbonding_electron_count(graph, node)
+        - bond_electron_count(graph, node)
+    )
+    return int(charge) if charge.is_integer() else charge
+
+
+def nonbonding_electron_count(graph: nx.Graph, node: Any) -> float:
+    """Return NBE for one atom from stored lone-pair/radical fields.
+
+    :param graph: Lewis graph.
+    :type graph: nx.Graph
+    :param node: Node whose nonbonding electrons should be counted.
+    :type node: Any
+    :returns: ``2 * lone_pairs + radical``.
+    :rtype: float
+    """
+    attrs = graph.nodes[node]
+    return 2 * float(attrs.get("lone_pairs", 0)) + float(attrs.get("radical", 0))
+
+
+def bond_electron_count(graph: nx.Graph, node: Any) -> float:
+    """Return B for one atom, including implicit hydrogen bonds.
+
+    :param graph: Lewis graph.
+    :type graph: nx.Graph
+    :param node: Node whose bonding electrons should be counted.
+    :type node: Any
+    :returns: ``hcount`` plus incident sigma/pi bond-order sum.
+    :rtype: float
+    """
+    attrs = graph.nodes[node]
+    return float(attrs.get("hcount", 0)) + bond_order_sum(graph, node)
+
+
+def atom_map_to_node(graph: nx.Graph) -> dict[int, Any]:
+    """Build an atom-map to node lookup, ignoring unmapped atoms.
+
+    :param graph: Graph with node ``atom_map`` attributes.
+    :type graph: nx.Graph
+    :returns: Mapping from atom-map number to graph node.
+    :rtype: dict[int, Any]
+    :raises ValueError: If a nonzero atom map appears on multiple nodes.
+    """
+    lookup: dict[int, Any] = {}
+    duplicates: dict[int, list[Any]] = {}
+
+    for node, attrs in graph.nodes(data=True):
+        atom_map = attrs.get("atom_map", node)
+        if atom_map in (None, 0, "0"):
+            continue
+
+        atom_map_int = int(atom_map)
+        if atom_map_int in lookup:
+            duplicates.setdefault(atom_map_int, [lookup[atom_map_int]]).append(node)
+            continue
+        lookup[atom_map_int] = node
+
+    if duplicates:
+        raise ValueError(f"Duplicate atom maps in graph: {duplicates}")
+
+    return lookup
+
+
+def refresh_changed_atom_charge(
+    graph: nx.Graph,
+    atom_maps: list[int] | tuple[int, ...] | set[int],
+) -> list[ChargeRefresh]:
+    """Refresh formal charges only for selected atom maps.
+
+    Uses ``Formal Charge = VE - NBE - B`` where ``B`` includes implicit
+    hydrogens stored as ``hcount`` plus incident sigma/pi order.
+
+    :param graph: Lewis graph to mutate.
+    :type graph: nx.Graph
+    :param atom_maps: Atom maps whose ``charge`` field should be recomputed.
+    :type atom_maps: list[int] | tuple[int, ...] | set[int]
+    :returns: Per-atom refresh reports.
+    :rtype: list[ChargeRefresh]
+    :raises ValueError: If any atom map is missing or lacks
+        ``valence_electrons``.
+    """
+    lookup = atom_map_to_node(graph)
+    reports: list[ChargeRefresh] = []
+
+    for atom_map in sorted({int(value) for value in atom_maps}):
+        if atom_map not in lookup:
+            raise ValueError(f"Atom map {atom_map} is missing from graph.")
+
+        node = lookup[atom_map]
+        attrs = graph.nodes[node]
+
+        if "valence_electrons" not in attrs:
+            raise ValueError(f"Atom map {atom_map} has no valence_electrons field.")
+
+        previous_charge = attrs.get("charge", 0)
+        refreshed_charge = recompute_charge(graph, node)
+        attrs["charge"] = refreshed_charge
+        attrs["bond_order_sum"] = bond_order_sum(graph, node)
+        attrs["recomputed_charge"] = refreshed_charge
+        attrs["charge_mismatch"] = False
+
+        reports.append(
+            ChargeRefresh(
+                atom_map=atom_map,
+                node=node,
+                previous_charge=previous_charge,
+                refreshed_charge=refreshed_charge,
+                valence_electrons=float(attrs["valence_electrons"]),
+                nonbonding_electrons=nonbonding_electron_count(graph, node),
+                bond_electrons=bond_electron_count(graph, node),
+            )
+        )
+
+    return reports
+
+
+def change_atom_charge(
+    graph: nx.Graph,
+    atom_maps: list[int] | tuple[int, ...] | set[int],
+    *,
+    delta: int | float,
+) -> list[ChargeEdit]:
+    """Apply a local formal-charge delta to selected atom maps.
+
+    This is the charge update primitive used by
+    :class:`synkit.Graph.Mech.lwg_editor.LWGEditor`.
+
+    :param graph: Lewis graph to mutate.
+    :type graph: nx.Graph
+    :param atom_maps: Atom maps whose formal charge should be edited.
+    :type atom_maps: list[int] | tuple[int, ...] | set[int]
+    :param delta: Formal-charge delta to add to each selected atom.
+    :type delta: int | float
+    :returns: Per-atom charge edit reports.
+    :rtype: list[ChargeEdit]
+    :raises ValueError: If any atom map is missing.
+    """
+    lookup = atom_map_to_node(graph)
+    reports: list[ChargeEdit] = []
+
+    for atom_map in [int(value) for value in atom_maps]:
+        if atom_map not in lookup:
+            raise ValueError(f"Atom map {atom_map} is missing from graph.")
+
+        node = lookup[atom_map]
+        attrs = graph.nodes[node]
+        previous_charge = attrs.get("charge", 0)
+        new_charge = previous_charge + delta
+        if isinstance(new_charge, float) and new_charge.is_integer():
+            new_charge = int(new_charge)
+
+        attrs["charge"] = new_charge
+        reports.append(
+            ChargeEdit(
+                atom_map=atom_map,
+                node=node,
+                delta=delta,
+                previous_charge=previous_charge,
+                new_charge=new_charge,
+            )
+        )
+
+    return reports
+
+
+def refresh_electron_fields(graph: nx.Graph, *, in_place: bool = False) -> nx.Graph:
+    """Refresh derived electron bookkeeping on a molecular graph.
+
+    The graph is expected to store scalar ``sigma_order`` and ``pi_order`` edge
+    fields plus node-level electron state. Presentation-facing ``order`` is not
+    rewritten here; RDKit reconstruction remains responsible for aromatic
+    re-perception at the product boundary.
+
+    :param graph: Lewis graph to refresh.
+    :type graph: nx.Graph
+    :param in_place: If ``True``, mutate ``graph`` directly.
+    :type in_place: bool
+    :returns: Graph with refreshed ``kekule_order``, ``bond_order_sum``,
+        ``recomputed_charge``, and ``charge_mismatch`` fields.
+    :rtype: nx.Graph
+    """
+    target = graph if in_place else graph.copy()
+
+    for _, _, data in target.edges(data=True):
+        sigma = float(data.get("sigma_order", 0.0))
+        pi = float(data.get("pi_order", 0.0))
+        data["kekule_order"] = sigma + pi
+
+    for node, attrs in target.nodes(data=True):
+        attrs["bond_order_sum"] = bond_order_sum(target, node)
+        if "valence_electrons" not in attrs:
+            continue
+        attrs["recomputed_charge"] = recompute_charge(target, node)
+        represented_charge = float(attrs.get("charge", 0))
+        attrs["charge_mismatch"] = represented_charge != attrs["recomputed_charge"]
+
+    return target
+
+
+def graph_to_sanitized_kekule_mol(graph: nx.Graph) -> Chem.Mol:
+    """Reconstruct a product from ``kekule_order`` and let RDKit sanitize it.
+
+    :param graph: Lewis graph with ``kekule_order`` edge fields.
+    :type graph: nx.Graph
+    :returns: Sanitized RDKit molecule.
+    :rtype: Chem.Mol
+    """
+    from synkit.IO.graph_to_mol import GraphToMol
+
+    refreshed = refresh_electron_fields(graph)
+    return GraphToMol(edge_attributes={"order": "kekule_order"}).graph_to_mol(
+        refreshed,
+        sanitize=True,
+        use_h_count=True,
+    )