synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Wildcard/wildcard.py

@@ -0,0 +1,225 @@
+import networkx as nx
+from typing import Dict, Any, Tuple, Optional
+from synkit.IO import rsmi_to_graph, graph_to_smi
+
+
+class WildCard:
+    """Static utility class for generating reaction SMILES with wildcards by
+    augmenting the product graph with subgraphs unique to the reactant and
+    patching lost external connections with wildcard atoms ('*').
+
+    Optionally, can rebalance the reactant side to ensure both sides have
+    matching atom maps (by adding wildcard atoms if needed).
+
+    All methods are static and do not store any internal state.
+
+    .. rubric:: Example
+
+    >>> WildCard.rsmi_with_wildcards('CCO>>CC')
+    'CCO>>CC*'
+
+    >>> WildCard.rsmi_with_wildcards('CCO>>CC', rebalance=True)
+    'CCO*>>CC*'
+    """
+
+    @staticmethod
+    def rsmi_with_wildcards(
+        rsmi: str,
+        attributes_defaults: Optional[Dict[str, Any]] = None,
+        rebalance: bool = False,
+    ) -> str:
+        """Given a reaction SMILES string, returns a new reaction SMILES where the product
+        side contains any disconnected subgraphs unique to the reactant, with lost
+        external bonds patched with wildcard atoms. Optionally, also adds wildcards to
+        the reactant side to ensure matching atom maps (rebalance).
+
+        :param rsmi: Reaction SMILES (e.g., 'CCO>>CC')
+        :type rsmi: str
+        :param attributes_defaults: Optional dictionary of default attributes for wildcards
+        :type attributes_defaults: dict, optional
+        :param rebalance: Whether to rebalance the reactant side by adding wildcards
+        :type rebalance: bool
+        :return: Augmented reaction SMILES string
+        :rtype: str
+        :raises ValueError: If parsing or output generation fails.
+
+        .. rubric:: Example
+
+        >>> WildCard.rsmi_with_wildcards('CCO>>CC')
+        'CCO>>CC*'
+        >>> WildCard.rsmi_with_wildcards('CCO>>CC', rebalance=True)
+        'CCO*>>CC*'
+        """
+        r, p = WildCard.from_rsmi(rsmi)
+        new_r, new_p = WildCard.add_unique_subgraph_with_wildcards(
+            r, p, attributes_defaults, rebalance=rebalance
+        )
+        try:
+            return f"{WildCard.to_smi(new_r)}>>{WildCard.to_smi(new_p)}"
+        except Exception as e:
+            raise ValueError(
+                "Could not convert to RSMI after wildcard patching."
+            ) from e
+
+    @staticmethod
+    def add_unique_subgraph_with_wildcards(
+        G: nx.Graph,
+        H: nx.Graph,
+        attributes_defaults: Optional[Dict[str, Any]] = None,
+        rebalance: bool = False,
+    ) -> Tuple[nx.Graph, nx.Graph]:
+        """Add the subgraph unique to G as a disconnected union to H,
+        and patch lost external connections with plain wildcard bonds.
+        Optionally, rebalance the reactant side to ensure both sides have
+        matching atom maps by adding wildcards.
+
+        :param G: Reactant graph
+        :type G: nx.Graph
+        :param H: Product graph
+        :type H: nx.Graph
+        :param attributes_defaults: Optional attribute defaults for wildcard nodes
+        :type attributes_defaults: dict, optional
+        :param rebalance: Whether to rebalance the reactant side with wildcards
+        :type rebalance: bool
+        :return: Tuple (new_G, new_H) with both graphs possibly augmented by wildcards
+        :rtype: Tuple[nx.Graph, nx.Graph]
+        :raises ValueError: If G or H are not valid graphs.
+
+        .. rubric:: Example
+
+        >>> r, p = WildCard.from_rsmi('CCO>>CC')
+        >>> r2, p2 = WildCard.add_unique_subgraph_with_wildcards(r, p, rebalance=True)
+        """
+        if not isinstance(G, nx.Graph) or not isinstance(H, nx.Graph):
+            raise ValueError("G and H must be networkx.Graph instances")
+        if G.number_of_nodes() == 0 or H.number_of_nodes() == 0:
+            raise ValueError("Both G and H must have at least one node.")
+        if not all("atom_map" in d for _, d in G.nodes(data=True)):
+            raise ValueError(
+                "All reactant nodes must have 'atom_map' attributes for unique subgraph logic."
+            )
+        if not all("atom_map" in d for _, d in H.nodes(data=True)):
+            raise ValueError(
+                "All product nodes must have 'atom_map' attributes for unique subgraph logic."
+            )
+
+        if attributes_defaults is None:
+            attributes_defaults = {
+                "element": "*",
+                "aromatic": False,
+                "hcount": 0,
+                "charge": 0,
+                "neighbors": [],
+            }
+
+        # Make working copies
+        G_new = G.copy()
+        H_new = H.copy()
+
+        # ---------------------------
+        # 1. PATCH PRODUCT SIDE (add unique reactant subgraphs and wildcards)
+        # ---------------------------
+        react_atom_maps = {d["atom_map"] for _, d in G.nodes(data=True)}
+        prod_atom_maps = {d["atom_map"] for _, d in H.nodes(data=True)}
+
+        # Identify nodes and subgraphs unique to reactant
+        unique_atom_maps = react_atom_maps - prod_atom_maps
+        node_map = {d["atom_map"]: n for n, d in G.nodes(data=True)}
+        unique_nodes = [node_map[a] for a in unique_atom_maps if a in node_map]
+
+        G_unique = G.subgraph(unique_nodes).copy()
+        # Add unique reactant fragments to product
+        for n, d in G_unique.nodes(data=True):
+            H_new.add_node(n, **d)
+        for u, v, d in G_unique.edges(data=True):
+            H_new.add_edge(u, v, **d)
+
+        # Add wildcards to patch lost external bonds (reactant → outside)
+        existing_ids = set(H_new.nodes)
+        next_id = (
+            max([n for n in existing_ids if isinstance(n, int)], default=0) + 1
+            if existing_ids
+            else 1
+        )
+
+        for n in unique_nodes:
+            for nbr in G.neighbors(n):
+                nbr_map = G.nodes[nbr]["atom_map"]
+                if nbr_map not in unique_atom_maps:
+                    wc_id = next_id
+                    next_id += 1
+                    H_new.add_node(
+                        wc_id,
+                        **attributes_defaults,
+                        atom_map=wc_id,
+                        typesGH=(("*", False, 0, 0, []), ("*", False, 0, 0, [])),
+                    )
+                    H_new.add_edge(n, wc_id)
+
+        # ---------------------------
+        # 2. REBALANCE REACTANT SIDE (add wildcards to reactant if required)
+        # ---------------------------
+        if rebalance:
+            prod_atom_maps = {d["atom_map"] for _, d in H_new.nodes(data=True)}
+            missing_in_react = prod_atom_maps - react_atom_maps
+            if missing_in_react:
+                react_existing_ids = set(G_new.nodes)
+                react_next_id = (
+                    max(
+                        [n for n in react_existing_ids if isinstance(n, int)], default=0
+                    )
+                    + 1
+                    if react_existing_ids
+                    else 1
+                )
+                for missing_map in missing_in_react:
+                    wc_id = react_next_id
+                    react_next_id += 1
+                    G_new.add_node(
+                        wc_id,
+                        **attributes_defaults,
+                        atom_map=missing_map,
+                        typesGH=(("*", False, 0, 0, []), ("*", False, 0, 0, [])),
+                    )
+
+        return G_new, H_new
+
+    @staticmethod
+    def from_rsmi(rsmi: str) -> Tuple[nx.Graph, nx.Graph]:
+        """Convert a reaction SMILES string into reactant and product graphs.
+
+        :param rsmi: Reaction SMILES string
+        :type rsmi: str
+        :return: Tuple (reactant_graph, product_graph)
+        :rtype: Tuple[nx.Graph, nx.Graph]
+        :raises ValueError: If input cannot be parsed.
+        """
+        try:
+            return rsmi_to_graph(rsmi)
+        except Exception as e:
+            raise ValueError(f"Could not parse RSMI: {rsmi}") from e
+
+    @staticmethod
+    def to_smi(G: nx.Graph) -> str:
+        """Convert a networkx molecular graph to a canonical SMILES string.
+
+        :param G: Molecular graph
+        :type G: nx.Graph
+        :return: SMILES string
+        :rtype: str
+        :raises ValueError: If conversion fails.
+        """
+        try:
+            return graph_to_smi(G)
+        except Exception as e:
+            raise ValueError("Could not convert graph to SMILES") from e
+
+    @staticmethod
+    def describe():
+        """
+        Print a description and usage example for this class.
+        """
+        print(WildCard.__doc__)
+
+    def __repr__(self):
+        return "<WildCard: static wildcard-augmentation for reaction SMILES>"

synkit/Graph/__init__.py

@@ -0,0 +1,17 @@
+# from .Canon import GraphCanonicaliser, CanonicalGraph
+from .utils import (
+    remove_wildcard_nodes,
+    add_wildcard_subgraph_for_unmapped,
+    print_graph_attributes,
+    clean_graph_keep_largest_component,
+    has_wildcard_node,
+)
+
+# __all__ = [
+#     "GraphCanonicaliser",
+#     "CanonicalGraph",
+#     "remove_wildcard_nodes",
+#     "add_wildcard_subgraph_for_unmapped",
+#     "print_graph_attributes",
+#     "clean_graph_keep_largest_component",
+# ]

synkit/Graph/canon_graph.py

@@ -0,0 +1,14 @@
+"""Backward-compatible import path for graph canonicalization.
+
+The maintained implementation lives in :mod:`synkit.Graph.Canon.canon_graph`.
+Keeping this module as a pure re-export prevents the two historical paths from
+silently diverging again.
+"""
+
+from .Canon.canon_graph import (
+    CanonicalGraph,
+    CanonicalRule,
+    GraphCanonicaliser,
+)
+
+__all__ = ["CanonicalGraph", "CanonicalRule", "GraphCanonicaliser"]

synkit/Graph/syn_graph.py

@@ -0,0 +1,199 @@
+"""synkit.Graph.syn_graph
+======================
+
+Wrapper around `networkx.Graph` providing both original and canonical forms,
+plus a SHA‑256 signature for fast isomorphism checks.
+
+Key features
+------------
+* **Value‑object semantics** – `__eq__` and `__hash__` use structural plus
+  map-invariant stereo identity, so graphs can be used in sets/dicts.
+* **Lazy canonicalisation** – canonical graph & signature are computed once on demand
+  (cached internally) to avoid upfront cost when not needed.
+* **Transparent delegation** – any unknown attribute/method is forwarded to the raw graph.
+
+.. rubric:: Example
+
+>>> G = nx.Graph(); G.add_node(1, element='C')
+>>> SG = SynGraph(G)
+>>> SG.signature   # 32‑hex SHA‑256 digest
+'8dc1f7b843e447ff4b67bf0ccc175f63'
+>>> SG.canonical  # relabelled, sorted graph
+<networkx.Graph with 1 nodes>
+>>>
+"""
+
+from __future__ import annotations
+import hashlib
+from typing import Any, Dict, Iterable, Optional, Tuple, Union
+
+import networkx as nx
+
+from synkit.Graph.canon_graph import GraphCanonicaliser
+from synkit.Graph.Stereo.identity import (
+    stereo_identity_edge_match,
+    stereo_identity_form,
+    stereo_identity_node_match,
+    stereo_identity_signature,
+)
+from synkit.Graph.Stereo.matching import stereo_isomorphic
+
+__all__ = ["SynGraph"]
+
+
+class SynGraph:
+    """Wrapper around networkx.Graph providing both its original and
+    (optionally) canonicalized form, plus a SHA-256 signature.
+
+    :param graph: The NetworkX graph to wrap.
+    :type graph: nx.Graph
+    :param canonicaliser: If provided, used to
+                          produce the canonical form; otherwise a default is constructed.
+    :type canonicaliser: Optional[GraphCanonicaliser]
+    :param canon: If True (default), computes and stores both
+                  `.canonical` and `.signature`. Otherwise they remain None.
+    :type canon: bool
+
+    .. rubric:: Attributes
+
+    * raw           nx.Graph            The original graph.
+    * canonical     Optional[nx.Graph]  The canonicalized graph (or None).
+    * signature     Optional[str]       The SHA-256 hex digest (or None).
+
+    .. rubric:: Methods
+
+    * get_nodes(data: bool = True) -> Iterable[…]
+    * get_edges(data: bool = True) -> Iterable[…]
+    * help()              Print this API summary.
+    """
+
+    def __init__(
+        self,
+        graph: nx.Graph,
+        canonicaliser: Optional[GraphCanonicaliser] = None,
+        canon: bool = True,
+    ) -> None:
+        """Initialize a SynGraph wrapper.
+
+        :param graph: Input graph.
+        :type graph: nx.Graph
+        :param canonicaliser: Canonicaliser instance.
+        :type canonicaliser: Optional[GraphCanonicaliser]
+        :param canon: Whether to compute canonical form/signature.
+        :type canon: bool
+        """
+        self._raw: nx.Graph = graph
+        self._canonicaliser: GraphCanonicaliser = canonicaliser or GraphCanonicaliser()
+        self._do_canon: bool = canon
+
+        if self._do_canon:
+            # build & store canonical graph
+            self._canonical: nx.Graph = self._canonicaliser.make_canonical_graph(graph)
+        else:
+            # skip canonicalisation
+            self._canonical = None
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate any unknown attribute lookup to the underlying ._raw
+        graph."""
+        return getattr(self._raw, name)
+
+    def __eq__(self, other: object) -> bool:
+        """Compare canonical identity, resolving stereo collisions exactly."""
+        if not isinstance(other, SynGraph):
+            return False
+        if self.signature != other.signature:
+            return False
+        left_stereo = self.stereo_signature
+        right_stereo = other.stereo_signature
+        if left_stereo is None or right_stereo is None:
+            return left_stereo is right_stereo
+        return stereo_isomorphic(
+            self._raw,
+            other._raw,
+            node_match=stereo_identity_node_match,
+            edge_match=stereo_identity_edge_match,
+            unknown_policy="exact",
+        )
+
+    def __hash__(self) -> int:
+        """Hash on the signature, allowing use in sets and as dict keys."""
+        return hash(self.signature)
+
+    @property
+    def raw(self) -> nx.Graph:
+        """The original NetworkX graph."""
+        return self._raw
+
+    @property
+    def canonical(self) -> Optional[nx.Graph]:
+        """The canonicalized graph, or None if canon=False."""
+        return self._canonical
+
+    @property
+    def signature(self) -> Optional[str]:
+        """Combined structural/stereo digest, preserving legacy plain graphs."""
+        structural = self.structural_signature
+        stereo = self.stereo_signature
+        if stereo is None:
+            return structural
+        return hashlib.sha256(
+            f"{structural}|stereo:{stereo}".encode("utf-8")
+        ).hexdigest()[:32]
+
+    @property
+    def structural_signature(self) -> str:
+        """Legacy connectivity/Lewis-state signature from the canonicaliser."""
+        return self._canonicaliser.canonical_signature(self._raw)
+
+    @property
+    def stereo_form(self) -> tuple[Any, ...]:
+        """Inspectable map-invariant form of all molecule or ITS stereo layers."""
+        return stereo_identity_form(self._raw)
+
+    @property
+    def stereo_signature(self) -> str | None:
+        """Digest of :attr:`stereo_form`, or ``None`` when stereo is absent."""
+        return stereo_identity_signature(self._raw)
+
+    def get_nodes(
+        self, data: bool = True
+    ) -> Iterable[Union[Any, Tuple[Any, Dict[str, Any]]]]:
+        """Yield nodes from the original graph.
+
+        :param data: If True, yield (node, data_dict), else just node IDs.
+        :type data: bool, default True
+        """
+        return self._raw.nodes(data=data)
+
+    def get_edges(
+        self, data: bool = True
+    ) -> Iterable[Union[Tuple[Any, Any], Tuple[Any, Any, Dict[str, Any]]]]:
+        """Yield edges from the original graph.
+
+        :param data: If True, yield (u, v, data_dict), else just (u, v).
+        :type data: bool, default True
+        """
+        return self._raw.edges(data=data)
+
+    def __repr__(self) -> str:
+        try:
+            v = self._raw.number_of_nodes()
+            e = self._raw.number_of_edges()
+        except Exception:
+            v = e = 0
+        return f"<SynGraph |V|={v} |E|={e} sig={self.signature[:8]}>"
+
+    def help(self) -> None:
+        """Print a summary of the SynGraph API."""
+        print(
+            "SynGraph Help\n"
+            "----------\n"
+            "raw          original networkx.Graph\n"
+            "canonical    canonical networkx.Graph\n"
+            "signature    combined structural/stereo SHA-256 digest\n"
+            "stereo_form  inspectable map-invariant descriptor form\n"
+            "get_nodes()  nodes (with data)\n"
+            "get_edges()  edges (with data)\n"
+            "__eq__/__hash__ use signature for comparisons"
+        )