synkit 1.6.5__py3-none-win_amd64.whl

synkit/IO/combinatorial/__init__.py

@@ -0,0 +1,8 @@
+import warnings
+
+warnings.warn(
+    "⚠️ This module is under active development and may be unstable. "
+    "APIs, behaviors, or outputs are subject to change without notice.",
+    category=UserWarning,
+    stacklevel=2,
+)

synkit/IO/combinatorial/gml_to_graph.py

@@ -0,0 +1,223 @@
+import re
+import networkx as nx
+from typing import Tuple, List, Dict
+
+
+class GMLToGraph:
+    """Parses a GML-like reaction rule into three NetworkX graphs: reactant (left),
+    conserved context (context), and product (right). Preserves atom-map indices
+    and original SMARTS labels, and attaches placeholder constraints (both
+    table-style and multi-block Rest-style) to node and edge attributes.
+
+    :param gml_text: The GML-like reaction rule text, containing 'left', 'context', 'right',
+                     and 'constrainLabelAny' sections.
+    :type gml_text: str
+
+    :ivar graphs: A mapping of section names ('left', 'context', 'right') to the
+                  corresponding parsed graphs.
+    :vartype graphs: Dict[str, nx.Graph]
+    :ivar placeholder_constraints: A mapping from placeholder labels (e.g. '_X') to their allowed values,
+                                   extracted from the 'constrainLabelAny' block.
+    :vartype placeholder_constraints: Dict[str, List[str]]
+    """
+
+    def __init__(self, gml_text: str):
+        """Initialize the parser with the full GML text.
+
+        :param gml_text: GML-like rule text to be parsed.
+        :type gml_text: str
+
+        :raises ValueError: If the provided gml_text is empty.
+        """
+        if not gml_text:
+            raise ValueError("gml_text must be a non-empty string")
+        self.gml_text = gml_text
+        self.graphs: Dict[str, nx.Graph] = {
+            sec: nx.Graph() for sec in ("left", "context", "right")
+        }
+        self.placeholder_constraints: Dict[str, List[str]] = {}
+
+    def _parse_element(self, line: str, sec: str) -> None:
+        """Parse a single GML line describing a node or an edge and insert it
+        into the specified graph section.
+
+        :param line: A line starting with 'node' or 'edge', e.g., 'node [ id 1 label "C" ]'.
+        :type line: str
+        :param sec: The target section in 'left', 'context', or 'right'.
+        :type sec: str
+
+        :raises ValueError: If `sec` is not one of 'left', 'context', or 'right'.
+        """
+        if sec not in self.graphs:
+            raise ValueError(f"Unknown section: {sec}")
+        tokens = line.split()
+        order_map = {"-": 1, ":": 1.5, "=": 2, "#": 3}
+        if tokens[0] == "node":
+            # Extract node attributes
+            nid = int(tokens[tokens.index("id") + 1])
+            raw_label = tokens[tokens.index("label") + 1].strip('"')
+            m = re.fullmatch(r"([A-Za-z*_]+?)(\d+)?([+-])?", raw_label)
+            if m:
+                element = m.group(1)
+                charge = int(m.group(2)) if m.group(2) else 1 if m.group(3) else 0
+                if m.group(3) == "-":
+                    charge = -charge
+            else:
+                element = raw_label
+                charge = 0
+            attrs = {
+                "element": element,
+                "charge": charge,
+                "atom_map": nid,
+                "hcount": 0,
+                "label": raw_label,
+            }
+            self.graphs[sec].add_node(nid, **attrs)
+        elif tokens[0] == "edge":
+            # Extract edge attributes
+            src = int(tokens[tokens.index("source") + 1])
+            tgt = int(tokens[tokens.index("target") + 1])
+            lbl = tokens[tokens.index("label") + 1].strip('"')
+            order = order_map.get(lbl, 0)
+            self.graphs[sec].add_edge(src, tgt, order=order, label=lbl)
+
+    def _synchronize(self) -> None:
+        """
+        Ensure that every node and edge in the 'context' graph also appears in
+        both 'left' and 'right' graphs, carrying over node and edge attributes.
+        """
+        ctx = self.graphs["context"]
+        # Nodes
+        for n, data in ctx.nodes(data=True):
+            for sec in ("left", "right"):
+                if n not in self.graphs[sec]:
+                    self.graphs[sec].add_node(n, **data)
+                else:
+                    self.graphs[sec].nodes[n].update(data)
+        # Edges
+        for u, v, data in ctx.edges(data=True):
+            for sec in ("left", "right"):
+                if not self.graphs[sec].has_edge(u, v):
+                    self.graphs[sec].add_edge(u, v, **data)
+
+    def _parse_constraints(self, lines: List[str], idx: int) -> int:
+        """Parse placeholder constraints from the 'constrainLabelAny' block,
+        supporting both table and multi-block Rest styles.
+
+        :param lines: All lines of the GML text.
+        :type lines: List[str]
+        :param idx: The index of the first line inside the '[' of the block.
+        :type idx: int
+
+        :return: The index of the closing ']' line of the block.
+        :rtype: int
+        """
+        while idx < len(lines):
+            line = lines[idx].strip()
+            if line.startswith("]"):
+                return idx
+            m = re.match(r'label\s+"[^\(]+\(([^)]+)\)"', line)
+            if m:
+                placeholders = [p.strip() for p in m.group(1).split(",")]
+                # Table style if multiple placeholders
+                if len(placeholders) > 1:
+                    table: List[Tuple[str, ...]] = []
+                    idx += 1
+                    # Find rows
+                    while idx < len(lines) and "labels [" not in lines[idx]:
+                        idx += 1
+                    while idx < len(lines):
+                        row_line = lines[idx].strip()
+                        matches = re.findall(r'label\s+"[^\(]+\(([^)]+)\)"', row_line)
+                        for row in matches:
+                            table.append(tuple(val.strip() for val in row.split(",")))
+                        if "]" in row_line:
+                            break
+                        idx += 1
+                    for j, ph in enumerate(placeholders):
+                        self.placeholder_constraints[ph] = [row[j] for row in table]
+                    idx += 1
+                    continue
+                # Multi-block Rest style
+                ph = placeholders[0]
+                self.placeholder_constraints[ph] = []
+                idx += 1
+                while idx < len(lines) and "labels [" not in lines[idx]:
+                    idx += 1
+                if idx < len(lines):
+                    while idx < len(lines):
+                        lbl_line = lines[idx].strip()
+                        matches = re.findall(r'label\s+"[^\(]+\(([^)]+)\)"', lbl_line)
+                        self.placeholder_constraints[ph].extend(matches)
+                        if "]" in lbl_line:
+                            break
+                        idx += 1
+                idx += 1
+                continue
+            idx += 1
+        return idx
+
+    def _attach_constraints(self) -> None:
+        """
+        Attach the parsed placeholder constraints to nodes (as 'constraint')
+        and edges (as 'bond_constraint') across all graphs, and store the
+        raw mapping on the context graph's .graph metadata.
+        """
+        pc = self.placeholder_constraints
+        for graph in self.graphs.values():
+            for n, data in graph.nodes(data=True):
+                lbl = data.get("label")
+                if lbl in pc:
+                    data["constraint"] = pc[lbl]
+            for u, v, data in graph.edges(data=True):
+                lbl = data.get("label")
+                if lbl in pc:
+                    data["bond_constraint"] = pc[lbl]
+        self.graphs["context"].graph["placeholder_constraints"] = pc
+
+    def transform(self) -> Tuple[nx.Graph, nx.Graph, nx.Graph]:
+        """Parse the GML text, build the left, right, and context graphs, and return them.
+
+        :return: A tuple (left_graph, right_graph, context_graph), each with attached constraints.
+        :rtype: Tuple[nx.Graph, nx.Graph, nx.Graph]
+        """
+        lines = self.gml_text.splitlines()
+        section: str = ""
+        i = 0
+        while i < len(lines):
+            line = lines[i].strip()
+            if line.startswith("constrainLabelAny"):
+                while i < len(lines) and not lines[i].strip().endswith("["):
+                    i += 1
+                i = self._parse_constraints(lines, i + 1)
+            elif any(line.startswith(x) for x in ("left", "right", "context")):
+                section = line.split("[")[0].strip()
+            elif line.startswith(("node", "edge")) and section:
+                self._parse_element(line, section)
+            i += 1
+        self._synchronize()
+        self._attach_constraints()
+        return (self.graphs["left"], self.graphs["right"], self.graphs["context"])
+
+    def __repr__(self) -> str:
+        """Return a summary indicating the number of nodes in each graph.
+
+        :return: A brief representation with node counts.
+        :rtype: str
+        """
+        return (
+            f"<GMLToGraph left={self.graphs['left'].number_of_nodes()} nodes, "
+            f"right={self.graphs['right'].number_of_nodes()} nodes, "
+            f"context={self.graphs['context'].number_of_nodes()} nodes>"
+        )
+
+    def help(self) -> str:
+        """Return a usage summary for the GMLToGraph parser.
+
+        :return: Multi-line help text explaining the API.
+        :rtype: str
+        """
+        return (
+            "GMLToGraph(gml_text) -> (left, right, context) graphs\n"
+            "Supports Nuc-style and Rest-style constraint parsing."
+        )

synkit/IO/combinatorial/graph_to_gml.py

@@ -0,0 +1,280 @@
+import networkx as nx
+from typing import Dict, List, Tuple, Any, Set
+
+
+class GraphToGML:
+    """Convert two NetworkX graphs into a minimal GML reaction rule string,
+    using canonical context detection and SynKit-style constraint annotations.
+
+    This class identifies the conserved context (nodes/edges unchanged between
+    reactant and product graphs), extracts minimal changing portions,
+    and generates a GML block including left, context, right, and placeholder constraints.
+
+    :param left: Graph representing the reactant state.
+    :type  left: nx.Graph
+    :param right: Graph representing the product state.
+    :type  right: nx.Graph
+    :param rule_id: Identifier for the reaction rule (default: "1").
+    :type  rule_id: str
+    :raises ValueError: If input graphs have mismatched mapping nodes.
+
+    .. rubric:: Examples
+
+    >>> from networkx import Graph
+    >>> G1, G2 = Graph(), Graph()
+    >>> # populate G1, G2 with atom_map nodes, constraints, etc.
+    >>> g2g = GraphToGML(G1, G2, rule_id="rxn1")
+    >>> gml = g2g.to_gml()
+    >>> print(gml)
+    """
+
+    def __init__(self, left: nx.Graph, right: nx.Graph, rule_id: str = "1") -> None:
+        """Initialize the GraphToGML converter.
+
+        :param left: Reactant graph with node and edge attributes.
+        :type  left: nx.Graph
+        :param right: Product graph with node and edge attributes.
+        :type  right: nx.Graph
+        :param rule_id: Unique identifier for the rule output.
+        :type  rule_id: str
+        :return: None
+        :rtype: None
+        :raises ValueError: If graphs have nodes without atom_map attribute.
+        """
+        self.left: nx.Graph = left
+        self.right: nx.Graph = right
+        self.rule_id: str = rule_id
+
+        self.context_nodes: Set[int] = set()
+        self.context_edges: Set[Tuple[int, int]] = set()
+        self.left_nodes: Set[int] = set()
+        self.right_nodes: Set[int] = set()
+        self.left_edges: List[Tuple[int, int, Dict[str, Any]]] = []
+        self.right_edges: List[Tuple[int, int, Dict[str, Any]]] = []
+        self.context: nx.Graph = nx.Graph()
+        self.constraint_dict: Dict[str, List[str]] = {}
+
+    @staticmethod
+    def same_node(nl: Dict[str, Any], nr: Dict[str, Any]) -> bool:
+        """Compare two node attribute dictionaries, ignoring 'atom_map'.
+
+        :param nl: Node attribute dict from left graph.
+        :type  nl: Dict[str, Any]
+        :param nr: Node attribute dict from right graph.
+        :type  nr: Dict[str, Any]
+        :return: True if all attributes (except 'atom_map') match.
+        :rtype: bool
+        """
+        keys = set(nl) | set(nr)
+        keys.discard("atom_map")
+        return all(nl.get(k) == nr.get(k) for k in keys)
+
+    @staticmethod
+    def same_edge(el: Dict[str, Any], er: Dict[str, Any]) -> bool:
+        """Compare two edge attribute dictionaries for equality.
+
+        :param el: Edge attribute dict from left graph.
+        :type  el: Dict[str, Any]
+        :param er: Edge attribute dict from right graph.
+        :type  er: Dict[str, Any]
+        :return: True if all edge attributes match.
+        :rtype: bool
+        """
+        keys = set(el) | set(er)
+        return all(el.get(k) == er.get(k) for k in keys)
+
+    def compute(self) -> None:
+        """Compute conserved context and minimal changing nodes/edges,
+        then collect placeholder constraints from context graph.
+
+        :return: None
+        :rtype: None
+        """
+        # Identify conserved context nodes
+        self.context_nodes = {
+            n
+            for n in set(self.left.nodes) & set(self.right.nodes)
+            if self.same_node(self.left.nodes[n], self.right.nodes[n])
+        }
+        # Identify conserved context edges
+        self.context_edges = {
+            tuple(sorted((u, v)))
+            for u, v in set(self.left.edges) & set(self.right.edges)
+            if u in self.context_nodes
+            and v in self.context_nodes
+            and self.same_edge(self.left.edges[u, v], self.right.edges[u, v])
+        }
+        # Compute minimal changing edges and nodes
+        self.left_edges, left_extra = self.get_changing_edges_and_nodes(
+            self.left, self.context_edges, self.context_nodes
+        )
+        self.right_edges, right_extra = self.get_changing_edges_and_nodes(
+            self.right, self.context_edges, self.context_nodes
+        )
+        self.left_nodes = {
+            n for n in self.left.nodes if n not in self.context_nodes
+        } | left_extra
+        self.right_nodes = {
+            n for n in self.right.nodes if n not in self.context_nodes
+        } | right_extra
+        # Build context subgraph
+        self.context = nx.Graph()
+        for n in sorted(self.context_nodes):
+            self.context.add_node(n, **self.left.nodes[n])
+        for u, v in self.context_edges:
+            self.context.add_edge(u, v, **self.left.edges[u, v])
+        # Gather constraints from context
+        self.constraint_dict.clear()
+        for _, d in self.context.nodes(data=True):
+            if "constraint" in d:
+                self.constraint_dict[d["label"]] = d["constraint"]
+        for _, _, d in self.context.edges(data=True):
+            if "bond_constraint" in d:
+                self.constraint_dict[d["label"]] = d["bond_constraint"]
+
+    @staticmethod
+    def get_changing_edges_and_nodes(
+        G: nx.Graph, context_edges: Set[Tuple[int, int]], context_nodes: Set[int]
+    ) -> Tuple[List[Tuple[int, int, Dict[str, Any]]], Set[int]]:
+        """Identify edges and nodes in G that are not in the conserved context.
+
+        :param G: Input graph.
+        :type  G: nx.Graph
+        :param context_edges: Edges part of context.
+        :type  context_edges: Set[Tuple[int, int]]
+        :param context_nodes: Nodes part of context.
+        :type  context_nodes: Set[int]
+        :return: A tuple of (changed_edges, changed_nodes).
+        :rtype: Tuple[List[Tuple[int, int, Dict[str, Any]]], Set[int]]
+        """
+        changed_edges: List[Tuple[int, int, Dict[str, Any]]] = []
+        changed_nodes: Set[int] = set()
+        for u, v in G.edges():
+            key = tuple(sorted((u, v)))
+            if key not in context_edges:
+                changed_edges.append((u, v, G.edges[u, v]))
+                if u not in context_nodes:
+                    changed_nodes.add(u)
+                if v not in context_nodes:
+                    changed_nodes.add(v)
+        return changed_edges, changed_nodes
+
+    @staticmethod
+    def graph_section(
+        name: str,
+        G: nx.Graph,
+        nodes: Set[int],
+        edges: List[Tuple[int, int, Dict[str, Any]]],
+    ) -> List[str]:
+        """Render a GML block for a subgraph section.
+
+        :param name: Section name ('left', 'context', or 'right').
+        :type  name: str
+        :param G: Graph containing nodes/edges.
+        :type  G: nx.Graph
+        :param nodes: Node IDs to include.
+        :type  nodes: Set[int]
+        :param edges: Edges to include (u,v,attr).
+        :type  edges: List[Tuple[int,int,Dict[str,Any]]]
+        :return: Lines of GML representing the section.
+        :rtype: List[str]
+        """
+        lines: List[str] = [f" {name} ["]
+        for n in sorted(nodes):
+            d = G.nodes[n]
+            lbl = d.get("label", d.get("element", str(n)))
+            lines.append(f'  node [ id {n} label "{lbl}" ]')
+        order_map = {1: "-", 1.5: ":", 2: "=", 3: "#"}
+        for u, v, d in sorted(edges):
+            lbl = d.get("label", order_map.get(d.get("order", 1), "-"))
+            lines.append(f'  edge [ source {u} target {v} label "{lbl}" ]')
+        lines.append(" ]")
+        return lines
+
+    @staticmethod
+    def context_section(G: nx.Graph) -> List[str]:
+        """Render the conserved context GML block.
+
+        :param G: Context graph.
+        :type  G: nx.Graph
+        :return: Lines of GML for context.
+        :rtype: List[str]
+        """
+        lines: List[str] = [" context []"]  # placeholder, updated in full block
+        lines = [" context ["]
+        for n, d in sorted(G.nodes(data=True)):
+            lbl = d.get("label", d.get("element", str(n)))
+            lines.append(f'  node [ id {n} label "{lbl}" ]')
+        order_map = {1: "-", 1.5: ":", 2: "=", 3: "#"}
+        for u, v, d in sorted(G.edges(data=True)):
+            lbl = d.get("label", order_map.get(d.get("order", 1), "-"))
+            lines.append(f'  edge [ source {u} target {v} label "{lbl}" ]')
+        lines.append(" ]")
+        return lines
+
+    def constraints_section(self) -> List[str]:
+        """Render placeholder constraints as one constrainLabelAny block.
+
+        :return: Lines of GML for constraints.
+        :rtype: List[str]
+        """
+        lines: List[str] = []
+        if not self.constraint_dict:
+            return lines
+        lines.append(" constrainLabelAny [")
+        for ph, children in self.constraint_dict.items():
+            lines.append(f'  label "Rest({ph})"')
+            if children:
+                labels_inner = " ".join(f'label "Rest({c})"' for c in children)
+                lines.append(f"  labels [{labels_inner}]")
+            else:
+                lines.append("  labels []")
+        lines.append(" ]")
+        return lines
+
+    def to_gml(self) -> str:
+        """Generate the full GML reaction rule string.
+
+        :return: Complete GML string for the reaction rule.
+        :rtype: str
+        """
+        self.compute()
+        out: List[str] = ["rule [", f' ruleID "{self.rule_id}"']
+        out += self.graph_section("left", self.left, self.left_nodes, self.left_edges)
+        out += self.context_section(self.context)
+        out += self.graph_section(
+            "right", self.right, self.right_nodes, self.right_edges
+        )
+        out += self.constraints_section()
+        out.append("]")
+        return "\n".join(out)
+
+    def __repr__(self) -> str:
+        """Return a summary of the rule converter.
+
+        :return: Brief description with node counts.
+        :rtype: str
+        """
+        return (
+            f"<GraphToGML rule_id='{self.rule_id}', "
+            f"left_nodes={len(self.left_nodes)}, "
+            f"right_nodes={len(self.right_nodes)}, "
+            f"context_nodes={len(self.context_nodes)}>"
+        )
+
+    def help(self) -> str:
+        """Show usage instructions for GraphToGML.
+
+        :return: Multi-line help text.
+        :rtype: str
+        """
+        return (
+            "GraphToGML(left, right, rule_id='374')\n"
+            " - left: nx.Graph for reactant state\n"
+            " - right: nx.Graph for product state\n"
+            " - rule_id: identifier for the GML rule\n"
+            "\n"
+            "Usage:\n"
+            "    g2g = GraphToGML(G_left, G_right, rule_id='374')\n"
+            "    print(g2g.to_gml())\n"
+        )