synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Hyrogen/hextend_legacy.py

@@ -0,0 +1,215 @@
+"""Legacy all-variant hydrogen extension.
+
+Use :mod:`synkit.Graph.Hyrogen.hextend` for provenance-aware transfer
+enumeration. This module exists for reproducibility and regression comparison.
+"""
+
+from typing import Dict, List, Optional, Tuple
+
+import networkx as nx
+from joblib import Parallel, delayed
+
+from synkit.Graph.Hyrogen._misc import check_hcount_change
+from synkit.Graph.Hyrogen.hcomplete import HComplete, ITSFormatInput
+from synkit.Graph.Hyrogen.hcomplete_legacy import LegacyHComplete
+from synkit.Graph.Matcher.graph_cluster import GraphCluster
+
+legacy_cluster = GraphCluster()
+
+
+class LegacyHExtend(LegacyHComplete):
+    """Historical extension driven by shared hydrogen-ID permutations."""
+
+    @staticmethod
+    def extend_its(
+        its: nx.Graph,
+        ignore_aromaticity: bool = False,
+        balance_its: bool = True,
+        format: ITSFormatInput = "auto",
+        max_candidates: Optional[int] = None,
+    ) -> Tuple[List[nx.Graph], List[nx.Graph], List[str]]:
+        if not isinstance(its, nx.Graph) or its.number_of_nodes() == 0:
+            return [], [], []
+
+        resolved_format = HComplete._resolve_format(its, format)
+        react_graph, prod_graph = HComplete._decompose_its(its, resolved_format)
+        if check_hcount_change(react_graph, prod_graph) == 0:
+            rc = HComplete._extract_rc(its, resolved_format)
+            if not HComplete._valid_rc(rc):
+                return [], [], []
+            return [rc], [its], [HComplete._rc_signature(rc, resolved_format)]
+
+        rc_list, its_list, signatures = [], [], []
+        for (
+            _,
+            _,
+            completed_its,
+            rc,
+            signature,
+        ) in LegacyHComplete._iter_hydrogen_node_completions(
+            react_graph,
+            prod_graph,
+            ignore_aromaticity,
+            balance_its,
+            resolved_format,
+            max_candidates,
+        ):
+            if HComplete._valid_rc(rc):
+                rc_list.append(rc)
+                its_list.append(completed_its)
+                signatures.append(signature)
+        return rc_list, its_list, signatures
+
+    @staticmethod
+    def _extend(
+        its: nx.Graph,
+        ignore_aromaticity: bool,
+        balance_its: bool,
+        format: ITSFormatInput = "auto",
+        max_candidates: Optional[int] = None,
+    ) -> Tuple[List[nx.Graph], List[nx.Graph], List[str]]:
+        return LegacyHExtend.extend_its(
+            its,
+            ignore_aromaticity,
+            balance_its,
+            format,
+            max_candidates,
+        )
+
+    @staticmethod
+    def _extend_unique(
+        its: nx.Graph,
+        ignore_aromaticity: bool = False,
+        balance_its: bool = True,
+        format: ITSFormatInput = "auto",
+        max_candidates: Optional[int] = None,
+    ) -> Tuple[List[nx.Graph], List[nx.Graph], List[str]]:
+        if not isinstance(its, nx.Graph) or its.number_of_nodes() == 0:
+            return [], [], []
+
+        resolved_format = HComplete._resolve_format(its, format)
+        react_graph, prod_graph = HComplete._decompose_its(its, resolved_format)
+        if check_hcount_change(react_graph, prod_graph) == 0:
+            rc = HComplete._extract_rc(its, resolved_format)
+            if not HComplete._valid_rc(rc):
+                return [], [], []
+            return [rc], [its], [HComplete._rc_signature(rc, resolved_format)]
+
+        side_candidates = []
+        comparison_graphs = []
+        signatures = []
+        static_tuple_nodes = (
+            HComplete._tuple_static_node_changes(react_graph, prod_graph)
+            if resolved_format == "tuple"
+            else None
+        )
+        for (
+            current_react_graph,
+            current_prod_graph,
+        ) in LegacyHComplete._iter_hydrogen_side_graph_completions(
+            react_graph,
+            prod_graph,
+            max_candidates,
+        ):
+            comparison = HComplete._candidate_comparison_graph(
+                current_react_graph,
+                current_prod_graph,
+                resolved_format,
+                ignore_aromaticity,
+                static_tuple_nodes,
+            )
+            if comparison.number_of_nodes() == 0:
+                continue
+            side_candidates.append((current_react_graph, current_prod_graph))
+            comparison_graphs.append(comparison)
+            signatures.append(HComplete._comparison_graph_signature(comparison))
+
+        if not comparison_graphs:
+            return [], [], []
+
+        clusters, _ = legacy_cluster.iterative_cluster(comparison_graphs, signatures)
+        rc_list, its_list, rc_signatures = [], [], []
+        for indices in clusters:
+            if not indices:
+                continue
+            current_react_graph, current_prod_graph = side_candidates[min(indices)]
+            completed_its = HComplete._construct_its(
+                current_react_graph,
+                current_prod_graph,
+                ignore_aromaticity,
+                balance_its,
+                resolved_format,
+            )
+            rc = HComplete._extract_rc(completed_its, resolved_format)
+            if HComplete._valid_rc(rc):
+                rc_list.append(rc)
+                its_list.append(completed_its)
+                rc_signatures.append(HComplete._rc_signature(rc, resolved_format))
+        return rc_list, its_list, rc_signatures
+
+    @staticmethod
+    def _process(
+        data_dict: Dict,
+        its_key: str,
+        rc_key: str,
+        ignore_aromaticity: bool,
+        balance_its: bool,
+        format: ITSFormatInput = "auto",
+        max_candidates: Optional[int] = None,
+    ) -> Dict:
+        rc_list, its_list, _ = LegacyHExtend._extend_unique(
+            data_dict[its_key],
+            ignore_aromaticity,
+            balance_its,
+            format,
+            max_candidates,
+        )
+        data_dict[rc_key] = rc_list
+        data_dict[its_key] = its_list
+        return data_dict
+
+    @staticmethod
+    def fit(
+        data,
+        its_key: str,
+        rc_key: str,
+        ignore_aromaticity: bool = False,
+        balance_its: bool = True,
+        n_jobs: int = 1,
+        verbose: int = 0,
+        format: ITSFormatInput = "auto",
+        max_candidates: Optional[int] = None,
+        backend: Optional[str] = None,
+    ) -> List:
+        if n_jobs == 1 and backend is None:
+            return [
+                LegacyHExtend._process(
+                    item,
+                    its_key,
+                    rc_key,
+                    ignore_aromaticity,
+                    balance_its,
+                    format,
+                    max_candidates,
+                )
+                for item in data
+            ]
+
+        parallel_kwargs = {"n_jobs": n_jobs, "verbose": verbose}
+        if backend is not None:
+            parallel_kwargs["backend"] = backend
+        return Parallel(**parallel_kwargs)(
+            delayed(LegacyHExtend._process)(
+                item,
+                its_key,
+                rc_key,
+                ignore_aromaticity,
+                balance_its,
+                format,
+                max_candidates,
+            )
+            for item in data
+        )
+
+
+__all__ = ["LegacyHExtend", "legacy_cluster"]

synkit/Graph/ITS/__init__.py

@@ -0,0 +1,4 @@
+from .its_construction import ITSConstruction
+from .its_decompose import its_decompose, get_rc
+
+__all__ = ["its_decompose", "get_rc", "ITSConstruction"]

synkit/Graph/ITS/its_builder.py

@@ -0,0 +1,120 @@
+import networkx as nx
+
+
+class ITSBuilder:
+    """Build and annotate an Imaginary Transition State (ITS) graph from a base
+    graph and a reaction-center (RC) graph.
+
+    This class only provides static methods and does not maintain state.
+    """
+
+    @staticmethod
+    def update_atom_map(graph: nx.Graph) -> None:
+        """Reset and renumber the 'atom_map' attribute of every node to match
+        its node index.
+
+        :param graph: The graph whose nodes will be renumbered.
+        :type graph: nx.Graph
+        :return: None
+        :rtype: NoneType
+
+        .. rubric:: Examples
+
+        >>> G = nx.Graph()
+        >>> G.add_node(5)
+        >>> ITSBuilder.update_atom_map(G)
+        >>> G.nodes[5]['atom_map']
+        5
+        """
+        for node in graph.nodes():
+            graph.nodes[node]["atom_map"] = node
+
+    @staticmethod
+    def ITSGraph(G: nx.Graph, RC: nx.Graph) -> nx.Graph:
+        """Create an ITS graph by merging attributes from a reaction-center
+        graph (RC) into a copy of the base graph G and initializing transition-
+        state metadata.
+
+        The returned ITS graph will have:
+          1. An independent shallow copy of G’s nodes and edges.
+          2. A new node attribute 'typesGH' storing G‑side and H‑side element/aromaticity/etc.
+          3. Edge attributes:
+             - 'order': tuple of the original order replicated for G and H.
+             - 'standard_order': initialized to 0.0.
+          4. All node and edge attributes from RC grafted onto corresponding nodes/edges
+             in the copy of G, matched by RC’s 'atom_map' values.
+          5. A final renumbering of 'atom_map' to each node’s index.
+
+        :param G: The original molecular graph representing either reactants or products.
+        :type G: nx.Graph
+        :param RC: The reaction-center graph containing updated atom and bond changes.
+        :type RC: nx.Graph
+        :return: A new graph representing the ITS, with merged and initialized attributes.
+        :rtype: nx.Graph
+        :raises KeyError: If a required attribute is missing from G or RC during merging.
+
+        .. rubric:: Examples
+
+        >>> from synkit.Graph.ITS.its_construction import ITSConstruction
+        >>> base = nx.Graph()
+        >>> # ... populate base with 'atom_map' and other attrs ...
+        >>> rc = ITSConstruction().ITSGraph(base, some_other_graph)
+        >>> its = ITSBuilder.ITSGraph(base, rc)
+        >>> isinstance(its, nx.Graph)
+        True
+        """
+        # 1) Copy base graph
+        # NetworkX copies node/edge attribute dictionaries, which is sufficient
+        # here: this builder replaces top-level values and never mutates the
+        # nested values inherited from ``G``.  A recursive deepcopy dominated
+        # normal expansion time for larger Lewis-labelled graphs.
+        its = G.copy()
+
+        # 2) Initialize 'typesGH' for each node
+        for node, attrs in its.nodes(data=True):
+            common = (
+                attrs.get("element", "*"),
+                attrs.get("aromatic", False),
+                attrs.get("hcount", 0),
+                attrs.get("charge", 0),
+                attrs.get("neighbors", []),
+            )
+            its.nodes[node]["typesGH"] = (common, common)
+
+        # 3) Initialize edge orders and standard_order
+        for u, v, edge_attrs in its.edges(data=True):
+            order = edge_attrs.get("order", 1.0)
+            its[u][v]["order"] = (order, order)
+            its[u][v]["standard_order"] = 0.0
+
+        # 4) Build mapping from RC atom_map to its node index in G
+        atom_map_to_node = {
+            attrs["atom_map"]: node
+            for node, attrs in G.nodes(data=True)
+            if attrs.get("atom_map", 0) != 0
+        }
+
+        # 5) Merge node attributes from RC
+        for rc_node, rc_attrs in RC.nodes(data=True):
+            amap = rc_attrs.get("atom_map")
+            target = atom_map_to_node.get(amap)
+            if target is not None:
+                its.nodes[target].update(rc_attrs)
+
+        # 6) Merge or add edges from RC
+        for u_rc, v_rc, rc_edge_attrs in RC.edges(data=True):
+            u_map = RC.nodes[u_rc].get("atom_map", u_rc)
+            v_map = RC.nodes[v_rc].get("atom_map", v_rc)
+            u_target = atom_map_to_node.get(u_map)
+            v_target = atom_map_to_node.get(v_map)
+            if u_target is None or v_target is None:
+                continue
+            if its.has_edge(u_target, v_target):
+                its[u_target][v_target].update(rc_edge_attrs)
+            else:
+                its.add_edge(u_target, v_target, **rc_edge_attrs)
+
+        # 7) Renumber atom_map to node indices
+        ITSBuilder.update_atom_map(its)
+
+        return its