synkit 1.6.5__py3-none-win_amd64.whl

synkit/Rule/Compose/synrule.py

@@ -0,0 +1,170 @@
+"""Native non-stereo graph-composition facade for :class:`SynRule`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Mapping
+
+from synkit.Rule.Apply import (
+    EnvironmentToken,
+    RuleSpan,
+    SystemBoundary,
+    rule_from_synrule,
+)
+
+from .composition import CompositionResult, RuleOverlap, compose_rules
+from .search import (
+    CompositionSearchResult,
+    OverlapSearchLimits,
+    search_compositions,
+)
+
+
+class SynRuleCompositionIssueCode(str, Enum):
+    """Typed losses refused by the native SynRule composition adapter."""
+
+    WRONG_TYPE = "SYNRULE_COMPOSITION_WRONG_TYPE"
+    STEREO_UNSUPPORTED = "SYNRULE_COMPOSITION_STEREO_UNSUPPORTED"
+    WILDCARD_UNSUPPORTED = "SYNRULE_COMPOSITION_WILDCARD_UNSUPPORTED"
+
+
+@dataclass(frozen=True)
+class SynRuleCompositionIssue:
+    code: SynRuleCompositionIssueCode
+    message: str
+    context: Mapping[str, Any] = field(default_factory=dict)
+
+
+class SynRuleCompositionError(ValueError):
+    """Raised rather than silently dropping unsupported SynRule semantics."""
+
+    def __init__(self, *issues: SynRuleCompositionIssue):
+        self.issues = tuple(issues)
+        super().__init__("; ".join(issue.message for issue in issues))
+
+
+def _validate_synrule(rule: Any) -> None:
+    from synkit.Rule.syn_rule import SynRule
+
+    if not isinstance(rule, SynRule):
+        raise SynRuleCompositionError(
+            SynRuleCompositionIssue(
+                SynRuleCompositionIssueCode.WRONG_TYPE,
+                "Native SynRule composition expects SynRule values.",
+            )
+        )
+    stereo_fields = (
+        "stereo_guards",
+        "stereo_effects",
+        "stereo_outcomes",
+        "stereo_couplings",
+        "stereo_query_policies",
+    )
+    active_stereo = tuple(name for name in stereo_fields if getattr(rule, name, {}))
+    if active_stereo:
+        raise SynRuleCompositionError(
+            SynRuleCompositionIssue(
+                SynRuleCompositionIssueCode.STEREO_UNSUPPORTED,
+                "The non-stereo LLG compositor cannot erase SynRule stereo semantics.",
+                {"fields": active_stereo},
+            )
+        )
+    wildcard_nodes = tuple(
+        sorted(
+            {
+                repr(node)
+                for graph in (rule.left.raw, rule.right.raw)
+                for node, attrs in graph.nodes(data=True)
+                if "wildcard_role" in attrs
+            }
+        )
+    )
+    if wildcard_nodes:
+        raise SynRuleCompositionError(
+            SynRuleCompositionIssue(
+                SynRuleCompositionIssueCode.WILDCARD_UNSUPPORTED,
+                "The current LLG schema cannot erase typed-wildcard contracts.",
+                {"nodes": wildcard_nodes},
+            )
+        )
+
+
+def _electron_mode(rule: Any, requested: bool | None) -> bool:
+    return getattr(rule, "_format", None) == "tuple" if requested is None else requested
+
+
+def synrule_to_span(
+    rule: Any,
+    *,
+    electron_complete: bool | None = None,
+    boundary: SystemBoundary | str = SystemBoundary.ABSTRACT,
+    environment: EnvironmentToken | None = None,
+) -> RuleSpan:
+    """Adapt a supported SynRule to a native DPO span without optional backends."""
+    _validate_synrule(rule)
+    return rule_from_synrule(
+        rule,
+        electron_complete=_electron_mode(rule, electron_complete),
+        boundary=boundary,
+        environment=environment,
+    )
+
+
+def _synrule_pair(
+    first: Any,
+    second: Any,
+    electron_complete: bool | None,
+) -> tuple[RuleSpan, RuleSpan]:
+    _validate_synrule(first)
+    _validate_synrule(second)
+    complete = (
+        getattr(first, "_format", None) == getattr(second, "_format", None) == "tuple"
+        if electron_complete is None
+        else electron_complete
+    )
+    return (
+        synrule_to_span(first, electron_complete=complete),
+        synrule_to_span(second, electron_complete=complete),
+    )
+
+
+def compose_synrules(
+    first: Any,
+    second: Any,
+    overlap: Mapping[Any, Any],
+    *,
+    overlap_edges: set[frozenset[Any]] | None = None,
+    electron_complete: bool | None = None,
+) -> CompositionResult:
+    """Compose two SynRules along one caller-declared material overlap."""
+    first_span, second_span = _synrule_pair(first, second, electron_complete)
+    witness = RuleOverlap.from_mapping(
+        first_span.right,
+        second_span.left,
+        overlap,
+        overlap_edges=overlap_edges,
+    )
+    return compose_rules(first_span, second_span, witness)
+
+
+def search_synrule_compositions(
+    first: Any,
+    second: Any,
+    *,
+    limits: OverlapSearchLimits | None = None,
+    electron_complete: bool | None = None,
+) -> CompositionSearchResult:
+    """Return the complete bounded family; never choose a preferred composite."""
+    first_span, second_span = _synrule_pair(first, second, electron_complete)
+    return search_compositions(first_span, second_span, limits=limits)
+
+
+__all__ = [
+    "SynRuleCompositionError",
+    "SynRuleCompositionIssue",
+    "SynRuleCompositionIssueCode",
+    "compose_synrules",
+    "search_synrule_compositions",
+    "synrule_to_span",
+]

synkit/Rule/Modify/implict_rule.py

@@ -0,0 +1,56 @@
+from typing import Union, List, Any
+from synkit.Chem.Reaction import remove_explicit_H_from_rsmi
+from synkit.IO import rsmi_to_graph, setup_logging
+from synkit.Graph.ITS import ITSConstruction, get_rc
+
+logger = setup_logging()
+
+
+def implicit_rule(
+    rsmi: Union[str, List[str]], disconnected: bool = True, balance_its: bool = False
+) -> Union[Any, List[Any]]:
+    """Construct reaction-center objects from reaction SMILES by applying
+    implicit‐H rules and ITS graph construction.
+
+    :param rsmi: A reaction SMILES string, or a list thereof.
+    :type rsmi: str or list of str
+    :param disconnected: Whether to allow disconnected components in the reaction center (default: True).
+    :type disconnected: bool, optional
+    :param balance_its: Whether to enforce atom‐balance in the ITS graph (default: False).
+    :type balance_its: bool, optional
+
+    :return: The reaction‐center object(s) extracted from the ITS graph.
+    :rtype: RC or list of RC
+
+    :raises ValueError: If an empty SMILES string is provided.
+    :raises TypeError: If `rsmi` is not a string or list of strings.
+    :raises RuntimeError: If graph conversion or ITS construction fails.
+    """
+
+    def _process(smiles: str) -> Any:
+        if not smiles:
+            raise ValueError("Empty reaction SMILES provided.")
+        try:
+            # 1. Remove explicit hydrogens
+            sanitized = remove_explicit_H_from_rsmi(smiles)
+            # 2. Convert to reactant/product graphs
+            react_graph, prod_graph = rsmi_to_graph(sanitized)
+            # 3. Build ITS graph
+            its_graph = ITSConstruction().ITSGraph(
+                react_graph, prod_graph, balance_its=balance_its
+            )
+            # 4. Extract reaction center
+            return get_rc(its_graph, disconnected=disconnected)
+        except Exception as e:
+            logger.error("Error processing RSMI '%s': %s", smiles, e)
+            raise RuntimeError(f"Failed to construct ITS for '{smiles}': {e}")
+
+    # Handle single string or list of strings
+    if isinstance(rsmi, str):
+        return _process(rsmi)
+    elif isinstance(rsmi, list):
+        return [_process(s) for s in rsmi]
+    else:
+        raise TypeError(
+            f"`rsmi` must be a str or list of str, not {type(rsmi).__name__}"
+        )

synkit/Rule/Modify/longest_path.py

@@ -0,0 +1,92 @@
+import networkx as nx
+from collections import deque
+from typing import Tuple, List, Set
+
+
+class LongestPath:
+    def __init__(self, G: nx.Graph):
+        """Initializes the LongestPath object with a graph.
+
+        :param G: The networkx graph.
+        :type G: nx.Graph
+        """
+        self.G = G
+        self.vertices = len(G.nodes)
+
+    def BFS(self, u: int) -> Tuple[int, int]:
+        """Performs a Breadth-First Search (BFS) from a given node `u` to find
+        the farthest node and its distance.
+
+        :param u: The starting node for the BFS.
+        :type u: int
+
+        :return: The farthest node from `u` and its distance.
+        :rtype: Tuple[int, int]
+        """
+        # Initialize visited and distance dictionaries
+        visited = {i: False for i in self.G.nodes}
+        distance = {i: -1 for i in self.G.nodes}
+
+        # Distance of `u` from itself is 0
+        distance[u] = 0
+        queue = deque([u])
+        visited[u] = True
+
+        while queue:
+            front = queue.popleft()
+
+            # Explore neighbors of the current node
+            for neighbor in self.G.neighbors(front):
+                if not visited[neighbor]:
+                    visited[neighbor] = True
+                    distance[neighbor] = distance[front] + 1
+                    queue.append(neighbor)
+
+        # Find the farthest node and its distance
+        maxDis = 0
+        nodeIdx = u  # Default to start node if no farther node is found
+        for node, dist in distance.items():
+            if dist > maxDis:
+                maxDis = dist
+                nodeIdx = node
+
+        return nodeIdx, maxDis
+
+    def LongestPathInDisconnectedGraph(self) -> int:
+        """Finds the longest path in a potentially disconnected graph. The
+        graph can consist of multiple components.
+
+        This method performs a BFS on every unvisited component to find the
+        farthest node and computes the longest path across all components.
+
+        :return: The length of the longest path in the graph across all components.
+        :rtype: int
+        """
+        visited_components: Set[int] = set()
+        longest_path: int = 0
+        component_paths: List[Tuple[int, int, int]] = []
+
+        # Iterate over all nodes to ensure all components are covered
+        for node in self.G.nodes:
+            if node not in visited_components:
+                # First BFS to find one end point of the longest path in this component
+                farthest_node, _ = self.BFS(node)
+
+                # Second BFS from that node to find the actual longest path
+                node_2, component_longest_path = self.BFS(farthest_node)
+
+                # Track the longest path found
+                longest_path = max(longest_path, component_longest_path)
+                component_paths.append((farthest_node, node_2, component_longest_path))
+
+                # Mark all nodes in this component as visited
+                queue = deque([farthest_node])
+                while queue:
+                    current = queue.popleft()
+                    if current not in visited_components:
+                        visited_components.add(current)
+                        for neighbor in self.G.neighbors(current):
+                            if neighbor not in visited_components:
+                                queue.append(neighbor)
+
+        return longest_path

synkit/Rule/Modify/molecule_rule.py

@@ -0,0 +1,115 @@
+import re
+from rdkit import Chem
+from typing import Optional
+from synkit.IO.chem_converter import smart_to_gml
+from synkit.Rule.Modify.strip_rule import strip_context
+
+
+class MoleculeRule:
+    """A class for generating molecule rules, atom-mapped SMILES, and GML
+    representations from SMILES strings."""
+
+    def __init__(self) -> None:
+        """Initializes the MoleculeRule object."""
+        pass
+
+    @staticmethod
+    def remove_edges_from_left_right(input_str: str) -> str:
+        """Remove all contents from the 'left' and 'right' sections of a
+        chemical rule description.
+
+        :param input_str: The string representation of the rule.
+        :type input_str: str
+
+        :return: The modified string with cleared 'left' and 'right' sections.
+        :rtype: str
+        """
+        # Pattern to match 'left [' to the matching ']'
+        left_pattern = r"(left \[)(.*?)(^\s*\])"
+        # Pattern to match 'right [' to the matching ']'
+        right_pattern = r"(right \[)(.*?)(^\s*\])"
+
+        # Replace contents within 'left [' and 'right [' sections using non-greedy matching
+        # Multiline mode to handle newlines and match start of lines with '^'
+        input_str = re.sub(
+            left_pattern, r"\1\n    \3", input_str, flags=re.DOTALL | re.MULTILINE
+        )
+        input_str = re.sub(
+            right_pattern, r"\1\n    \3", input_str, flags=re.DOTALL | re.MULTILINE
+        )
+
+        return input_str
+
+    @staticmethod
+    def generate_atom_map(smiles: str) -> Optional[str]:
+        """Generate atom-mapped SMILES by assigning unique map numbers to each
+        atom in the molecule.
+
+        :param smiles: The SMILES string representing the molecule.
+        :type smiles: str
+
+        :return: The atom-mapped SMILES string, or None if the SMILES string is invalid.
+        :rtype: Optional[str]
+        """
+        mol = Chem.MolFromSmiles(smiles)
+        if not mol:
+            return None  # Invalid SMILES
+
+        # Assign atom map numbers (1-based index)
+        for idx, atom in enumerate(mol.GetAtoms()):
+            atom.SetAtomMapNum(idx + 1)
+
+        # Return the SMILES with atom map
+        return Chem.MolToSmiles(mol, canonical=True)
+
+    @staticmethod
+    def generate_molecule_smart(smiles: str) -> Optional[str]:
+        """Generate a SMARTS-like string from atom-mapped SMILES.
+
+        :param smiles: The SMILES string representing the molecule.
+        :type smiles: str
+
+        :return: The SMARTS-like string derived from atom-mapped SMILES, or None if the SMILES is invalid.
+        :rtype: Optional[str]
+        """
+        atom_map_smiles = MoleculeRule.generate_atom_map(smiles)
+        if atom_map_smiles is None:
+            return None  # Invalid SMILES
+
+        # Return the SMARTS-like string
+        return f"{atom_map_smiles}>>{atom_map_smiles}"
+
+    def generate_molecule_rule(
+        self,
+        smiles: str,
+        name: str = "molecule",
+        explicit_hydrogen: bool = True,
+        sanitize: bool = True,
+    ) -> Optional[str]:
+        """Generate a GML representation of the molecule rule from SMILES.
+
+        :param smiles: The SMILES string representing the molecule.
+        :type smiles: str
+        :param name: The rule name used in GML generation. Defaults to 'molecule'.
+        :type name: str, optional
+        :param explicit_hydrogen: Whether to include explicit hydrogen atoms in GML. Defaults to True.
+        :type explicit_hydrogen: bool, optional
+        :param sanitize: Whether to sanitize the molecule before conversion. Defaults to True.
+        :type sanitize: bool, optional
+
+        :return: The GML representation of the molecule rule, or None if invalid.
+        :rtype: Optional[str]
+        """
+        rsmi = self.generate_molecule_smart(smiles)
+        if rsmi is None:
+            return None  # Invalid SMARTS string
+        # Return the GML representation
+        gml = smart_to_gml(
+            rsmi,
+            core=False,
+            sanitize=sanitize,
+            explicit_hydrogen=explicit_hydrogen,
+            rule_name=name,
+        )
+        gml = strip_context(gml, False)
+        return gml

synkit/Rule/Modify/prune_templates.py

@@ -0,0 +1,78 @@
+import networkx as nx
+from copy import deepcopy
+from synkit.Rule.Modify.longest_path import LongestPath
+from typing import List, Dict, Any
+
+
+class PruneTemplate:
+    def __init__(self, templates: List[List[Dict[str, Any]]], graph_key: str) -> None:
+        """Initialize the PruneTemplate object with the provided templates and
+        graph key.
+
+        :param templates: A list of lists containing dictionaries
+                          where the graph can be accessed by the provided graph_key.
+        :type templates: List[List[Dict[str, Any]]]
+        :param graph_key: The key used to access the graph from each template dictionary.
+        :type graph_key: str
+        """
+        self.max_radius = len(templates)
+        self.templates = deepcopy(templates)
+        self.graph_key = graph_key
+
+    @staticmethod
+    def remove_edges_by_attribute(
+        input_graph: nx.Graph, attribute: str = "standard_order", value: Any = 0
+    ) -> nx.Graph:
+        """Remove edges from the input graph where a given attribute equals a
+        specified value.
+
+        :param input_graph: The input graph from which edges will be removed.
+        :type input_graph: nx.Graph
+        :param attribute: The edge attribute based on which edges will
+                          be removed. Default is 'standard_order'.
+        :type attribute: str, optional
+        :param value: The value of the attribute that determines
+                      which edges to remove. Default is 0.
+        :type value: Any, optional
+
+        :return: A new graph with the specified edges removed.
+        :rtype: nx.Graph
+        """
+        # Find edges where the specified attribute equals the given value
+        graph = deepcopy(input_graph)
+        edges_to_remove = [
+            (u, v)
+            for u, v, attrs in graph.edges(data=True)
+            if attrs.get(attribute) != value
+        ]
+
+        graph.remove_edges_from(edges_to_remove)
+
+        return graph
+
+    def fit(self) -> List[List[Dict[str, Any]]]:
+        """Prune the templates by removing subgraphs where the longest path is
+        shorter than the radius.
+
+        :return: The pruned list of templates.
+        :rtype: List[List[Dict[str, Any]]]
+        """
+        for radius, template in enumerate(self.templates):
+            if radius > 0:
+                for key in reversed(range(len(template))):
+                    temp = template[key]
+
+                    subgraph = temp.get(self.graph_key, None)[2]
+
+                    if subgraph is None:
+                        continue
+
+                    pruned_graph = PruneTemplate.remove_edges_by_attribute(subgraph)
+
+                    path_calculator = LongestPath(pruned_graph)
+                    longest_path = path_calculator.LongestPathInDisconnectedGraph()
+
+                    if longest_path < radius:
+                        template.pop(key)
+
+        return self.templates