synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/FG/detector.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+import networkx as nx
+from networkx.algorithms.isomorphism import GraphMatcher
+
+from .catalog import default_registry
+from .model import FunctionalGroupMatch, FunctionalGroupPattern, FunctionalGroupRegistry
+from .ring_system import AromaticRingSystemDetector
+
+
+def _node_match(host: dict[str, Any], pattern: dict[str, Any]) -> bool:
+    element = pattern.get("element")
+    if element is not None:
+        allowed = element if isinstance(element, tuple) else (element,)
+        if host.get("element") not in allowed:
+            return False
+
+    for attr in ("aromatic", "charge", "radical", "in_ring"):
+        if attr in pattern and host.get(attr) != pattern[attr]:
+            return False
+
+    hcount = host.get("hcount", 0)
+    if "hcount_min" in pattern and hcount < pattern["hcount_min"]:
+        return False
+    if "hcount_max" in pattern and hcount > pattern["hcount_max"]:
+        return False
+    return True
+
+
+def _edge_match(host: dict[str, Any], pattern: dict[str, Any]) -> bool:
+    if "order" in pattern and host.get("order") != pattern["order"]:
+        return False
+    if "aromatic" in pattern and host.get("aromatic") != pattern["aromatic"]:
+        return False
+    return True
+
+
+class FunctionalGroupDetector:
+    """Detect functional groups from an input molecular ``nx.Graph``."""
+
+    def __init__(self, registry: FunctionalGroupRegistry | None = None) -> None:
+        self.registry = default_registry() if registry is None else registry
+        self.profile_counts: Counter[str] = Counter()
+
+    def raw_matches(
+        self,
+        graph: nx.Graph,
+        *,
+        include_internal: bool = False,
+    ) -> list[FunctionalGroupMatch]:
+        """Return raw public matches before hierarchy resolution."""
+        matches: list[FunctionalGroupMatch] = []
+        matched_names: set[str] = set()
+        for pattern in self.registry.execution_order():
+            if pattern.requires and not any(
+                required in matched_names for required in pattern.requires
+            ):
+                self.profile_counts[f"skip:{pattern.name}"] += 1
+                continue
+            self.profile_counts[f"attempt:{pattern.name}"] += 1
+            if pattern.recognizer is not None:
+                found = pattern.recognizer(graph, pattern)
+                matches.extend(found)
+                if found:
+                    matched_names.add(pattern.name)
+                continue
+            if pattern.anchor_node is not None:
+                anchor_data = pattern.graph.nodes[pattern.anchor_node]
+                anchor_candidates = [
+                    node
+                    for node, host_data in graph.nodes(data=True)
+                    if _node_match(host_data, anchor_data)
+                ]
+                if not anchor_candidates:
+                    continue
+            matcher = GraphMatcher(
+                graph,
+                pattern.graph,
+                node_match=_node_match,
+                edge_match=_edge_match,
+            )
+            seen: set[tuple[int, ...]] = set()
+            for host_to_pattern in matcher.subgraph_monomorphisms_iter():
+                mapping = {
+                    pattern_node: host_node
+                    for host_node, pattern_node in host_to_pattern.items()
+                }
+                if pattern.validator is not None and not pattern.validator(
+                    graph, mapping
+                ):
+                    continue
+                group_nodes = tuple(
+                    sorted(mapping[node] for node in pattern.group_nodes)
+                )
+                if group_nodes in seen:
+                    continue
+                seen.add(group_nodes)
+                matches.append(
+                    FunctionalGroupMatch(
+                        name=pattern.name,
+                        group_nodes=group_nodes,
+                        mapping=mapping,
+                        pattern=pattern,
+                    )
+                )
+            if any(match.name == pattern.name for match in matches):
+                matched_names.add(pattern.name)
+        matches.extend(self._heteroaromatic_matches(graph))
+        if include_internal:
+            return matches
+        return [match for match in matches if match.pattern.public]
+
+    def matches(self, graph: nx.Graph) -> list[FunctionalGroupMatch]:
+        """Return hierarchy-resolved matches."""
+        raw = self.raw_matches(graph)
+        raw.sort(
+            key=lambda match: (
+                match.pattern.priority,
+                len(match.group_nodes),
+                match.name,
+                match.group_nodes,
+            ),
+            reverse=True,
+        )
+
+        accepted: list[FunctionalGroupMatch] = []
+        for candidate in raw:
+            if any(self._suppressed_by(candidate, chosen) for chosen in accepted):
+                continue
+            accepted.append(candidate)
+        return sorted(accepted, key=lambda match: (match.group_nodes, match.name))
+
+    def detect(self, graph: nx.Graph) -> list[tuple[str, tuple[int, ...]]]:
+        """Return simple ``(name, node_ids)`` functional-group labels."""
+        return [(match.name, match.group_nodes) for match in self.matches(graph)]
+
+    def _suppressed_by(
+        self,
+        candidate: FunctionalGroupMatch,
+        chosen: FunctionalGroupMatch,
+    ) -> bool:
+        if not self.registry.is_ancestor(candidate.name, chosen.name):
+            if candidate.name not in chosen.pattern.suppresses:
+                return False
+        return set(candidate.group_nodes).issubset(chosen.group_nodes)
+
+    @staticmethod
+    def _heteroaromatic_matches(graph: nx.Graph) -> list[FunctionalGroupMatch]:
+        matches: list[FunctionalGroupMatch] = []
+        for system in AromaticRingSystemDetector.detect(graph):
+            if not system.hetero_nodes:
+                continue
+            pattern_graph = nx.Graph()
+            pattern = FunctionalGroupPattern(
+                name="heteroaromatic_ring",
+                graph=pattern_graph,
+                group_nodes=(),
+                suppresses=("amine",),
+                priority=60,
+            )
+            matches.append(
+                FunctionalGroupMatch(
+                    name="heteroaromatic_ring",
+                    group_nodes=system.nodes,
+                    mapping={},
+                    pattern=pattern,
+                )
+            )
+            for (
+                classifier_name,
+                group_nodes,
+            ) in FunctionalGroupDetector._classify_ring_system(
+                graph,
+                system,
+            ):
+                named_pattern = FunctionalGroupPattern(
+                    name=classifier_name,
+                    graph=nx.Graph(),
+                    group_nodes=(),
+                    priority=70,
+                )
+                matches.append(
+                    FunctionalGroupMatch(
+                        name=classifier_name,
+                        group_nodes=group_nodes,
+                        mapping={},
+                        pattern=named_pattern,
+                    )
+                )
+        return matches
+
+    @staticmethod
+    def _classify_ring_system(
+        graph: nx.Graph, system
+    ) -> list[tuple[str, tuple[int, ...]]]:
+        labels: list[tuple[str, tuple[int, ...]]] = []
+        for ring in system.subrings:
+            ring_size = len(ring.nodes)
+            counts = ring.element_counts
+            sequence = ring.hetero_sequence
+            if counts == {"C": 5, "N": 1} and ring_size == 6:
+                labels.append(("pyridine", ring.nodes))
+            elif counts == {"C": 4, "N": 2} and ring_size == 6:
+                labels.append(("diazine", ring.nodes))
+            elif counts == {"C": 4, "N": 1} and ring_size == 5:
+                labels.append(("pyrrole", ring.nodes))
+            elif counts == {"C": 4, "O": 1} and ring_size == 5:
+                labels.append(("furan", ring.nodes))
+            elif counts == {"C": 4, "S": 1} and ring_size == 5:
+                labels.append(("thiophene", ring.nodes))
+            elif counts == {"C": 3, "N": 2} and ring_size == 5:
+                if sequence == ("C", "C", "C", "N", "N"):
+                    labels.append(("pyrazole", ring.nodes))
+                elif sequence == ("C", "C", "N", "C", "N"):
+                    labels.append(("imidazole", ring.nodes))
+            elif counts == {"C": 3, "N": 1, "S": 1} and ring_size == 5:
+                if sequence == ("C", "C", "C", "N", "S"):
+                    labels.append(("isothiazole", ring.nodes))
+                elif sequence == ("C", "C", "N", "C", "S"):
+                    labels.append(("thiazole", ring.nodes))
+            elif counts == {"C": 3, "N": 1, "O": 1} and ring_size == 5:
+                if sequence == ("C", "C", "C", "N", "O"):
+                    labels.append(("isoxazole", ring.nodes))
+                elif sequence == ("C", "C", "N", "C", "O"):
+                    labels.append(("oxazole", ring.nodes))
+            elif counts == {"C": 2, "N": 3} and ring_size == 5:
+                labels.append(("triazole", ring.nodes))
+            elif counts == {"C": 2, "N": 2, "O": 1} and ring_size == 5:
+                labels.append(("oxadiazole", ring.nodes))
+            elif counts == {"C": 1, "N": 4} and ring_size == 5:
+                labels.append(("tetrazole", ring.nodes))
+            elif counts == {"C": 2, "N": 2, "S": 1} and ring_size == 5:
+                labels.append(("thiadiazole", ring.nodes))
+            elif counts == {"C": 3, "N": 3} and ring_size == 6:
+                labels.append(("triazine", ring.nodes))
+        labels.extend(FunctionalGroupDetector._classify_fused_ring_system(system))
+        return labels
+
+    @staticmethod
+    def _classify_fused_ring_system(system) -> list[tuple[str, tuple[int, ...]]]:
+        if not system.is_fused or system.ring_sizes != (5, 6):
+            return []
+        sequences = {ring.hetero_sequence for ring in system.subrings}
+        if (
+            system.element_counts == {"C": 8, "N": 1}
+            and (
+                "C",
+                "C",
+                "C",
+                "C",
+                "N",
+            )
+            in sequences
+        ):
+            return [("indole", system.nodes)]
+        if system.element_counts == {"C": 7, "N": 2}:
+            if ("C", "C", "N", "C", "N") in sequences:
+                return [("benzimidazole", system.nodes)]
+            if ("C", "C", "C", "N", "N") in sequences:
+                return [("indazole", system.nodes)]
+        if (
+            system.element_counts == {"C": 7, "N": 1, "O": 1}
+            and (
+                "C",
+                "C",
+                "N",
+                "C",
+                "O",
+            )
+            in sequences
+        ):
+            return [("benzoxazole", system.nodes)]
+        if (
+            system.element_counts == {"C": 7, "N": 1, "S": 1}
+            and (
+                "C",
+                "C",
+                "N",
+                "C",
+                "S",
+            )
+            in sequences
+        ):
+            return [("benzothiazole", system.nodes)]
+        return []

synkit/Graph/FG/model.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Iterable
+
+import networkx as nx
+
+Mapping = dict[int, int]
+Validator = Callable[[nx.Graph, Mapping], bool]
+Recognizer = Callable[
+    [nx.Graph, "FunctionalGroupPattern"], list["FunctionalGroupMatch"]
+]
+
+
+@dataclass(frozen=True)
+class FunctionalGroupPattern:
+    """Graph-native functional-group definition."""
+
+    name: str
+    graph: nx.Graph
+    group_nodes: tuple[int, ...]
+    parents: tuple[str, ...] = ()
+    suppresses: tuple[str, ...] = ()
+    requires: tuple[str, ...] = ()
+    anchor_node: int | None = None
+    priority: int = 0
+    validator: Validator | None = None
+    recognizer: Recognizer | None = None
+    public: bool = True
+
+
+@dataclass(frozen=True)
+class FunctionalGroupMatch:
+    """One matched functional group in a host graph."""
+
+    name: str
+    group_nodes: tuple[int, ...]
+    mapping: Mapping
+    pattern: FunctionalGroupPattern
+
+
+@dataclass
+class FunctionalGroupRegistry:
+    """Container for functional-group patterns and hierarchy metadata."""
+
+    patterns: list[FunctionalGroupPattern] = field(default_factory=list)
+
+    def add(self, pattern: FunctionalGroupPattern) -> None:
+        self.patterns.append(pattern)
+
+    def extend(self, patterns: Iterable[FunctionalGroupPattern]) -> None:
+        self.patterns.extend(patterns)
+
+    def by_name(self, name: str) -> FunctionalGroupPattern:
+        for pattern in self.patterns:
+            if pattern.name == name:
+                return pattern
+        raise KeyError(name)
+
+    def is_ancestor(self, ancestor: str, child: str) -> bool:
+        """Return whether ``ancestor`` is an ancestor of ``child``."""
+        seen: set[str] = set()
+        stack = [child]
+        while stack:
+            current = stack.pop()
+            if current in seen:
+                continue
+            seen.add(current)
+            try:
+                parents = self.by_name(current).parents
+            except KeyError:
+                parents = ()
+            for parent in parents:
+                if parent == ancestor:
+                    return True
+                stack.append(parent)
+        return False
+
+    def execution_order(self) -> list[FunctionalGroupPattern]:
+        """Return patterns in prerequisite-respecting order."""
+        by_name = {pattern.name: pattern for pattern in self.patterns}
+        visited: set[str] = set()
+        ordered: list[FunctionalGroupPattern] = []
+
+        def visit(name: str) -> None:
+            if name in visited:
+                return
+            visited.add(name)
+            pattern = by_name[name]
+            for required in pattern.requires:
+                if required in by_name:
+                    visit(required)
+            ordered.append(pattern)
+
+        for pattern in self.patterns:
+            visit(pattern.name)
+        return ordered

synkit/Graph/FG/recognizers.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import networkx as nx
+
+from .model import FunctionalGroupPattern, Mapping
+from .model import FunctionalGroupMatch
+
+
+def _graph(
+    nodes: Iterable[tuple[int, dict]],
+    edges: Iterable[tuple[int, int, dict]],
+) -> nx.Graph:
+    graph = nx.Graph()
+    graph.add_nodes_from(nodes)
+    graph.add_edges_from(edges)
+    return graph
+
+
+def _single_heavy_neighbors(
+    graph: nx.Graph, node: int, *, exclude: set[int]
+) -> list[int]:
+    return [
+        neighbor
+        for neighbor in graph.neighbors(node)
+        if neighbor not in exclude and graph.nodes[neighbor].get("element") != "H"
+    ]
+
+
+def _alcohol_carbon_heavy_degree(expected: int):
+    def validator(graph: nx.Graph, mapping: Mapping) -> bool:
+        carbon, oxygen = mapping[1], mapping[2]
+        if not _alcohol_like(graph, mapping):
+            return False
+        return len(_single_heavy_neighbors(graph, carbon, exclude={oxygen})) == expected
+
+    return validator
+
+
+def _alcohol_like(graph: nx.Graph, mapping: Mapping) -> bool:
+    carbon, oxygen = mapping[1], mapping[2]
+    if graph.nodes[carbon].get("aromatic"):
+        return False
+    if graph.nodes[oxygen].get("hcount", 0) < 1:
+        return False
+    return all(
+        graph.edges[carbon, neighbor].get("order") == 1.0
+        for neighbor in graph.neighbors(carbon)
+    )
+
+
+def _aldehyde(graph: nx.Graph, mapping: Mapping) -> bool:
+    carbon, oxygen = mapping[1], mapping[2]
+    if graph.nodes[carbon].get("hcount", 0) < 1:
+        return False
+    others = _single_heavy_neighbors(graph, carbon, exclude={oxygen})
+    return all(graph.nodes[node].get("element") == "C" for node in others)
+
+
+def _amine(graph: nx.Graph, mapping: Mapping) -> bool:
+    nitrogen = mapping[1]
+    if graph.nodes[nitrogen].get("aromatic"):
+        return False
+    return all(
+        graph.edges[nitrogen, neighbor].get("order") == 1.0
+        for neighbor in graph.neighbors(nitrogen)
+    )
+
+
+def _phenol(graph: nx.Graph, mapping: Mapping) -> bool:
+    carbon, oxygen = mapping[1], mapping[2]
+    return (
+        graph.nodes[carbon].get("aromatic") is True
+        and graph.nodes[oxygen].get("hcount", 0) >= 1
+    )
+
+
+def _enol(graph: nx.Graph, mapping: Mapping) -> bool:
+    return graph.nodes[mapping[3]].get("hcount", 0) >= 1
+
+
+def _epoxide(graph: nx.Graph, mapping: Mapping) -> bool:
+    return all(graph.nodes[mapping[node]].get("in_ring") for node in (1, 2, 3))
+
+
+def _phosphite(graph: nx.Graph, mapping: Mapping) -> bool:
+    phosphorus = mapping[1]
+    return all(
+        not (
+            graph.nodes[neighbor].get("element") == "O"
+            and graph.edges[phosphorus, neighbor].get("order") == 2.0
+        )
+        for neighbor in graph.neighbors(phosphorus)
+    )
+
+
+def _azide(graph: nx.Graph, mapping: Mapping) -> bool:
+    middle, terminal = mapping[2], mapping[3]
+    return (
+        graph.nodes[middle].get("charge") == 1
+        and graph.nodes[terminal].get("charge") == -1
+    )
+
+
+def _hydrazone(graph: nx.Graph, mapping: Mapping) -> bool:
+    imine_nitrogen = mapping[2]
+    hydrazine_nitrogen = mapping[3]
+    return not (
+        graph.nodes[imine_nitrogen].get("charge") == 1
+        and graph.nodes[hydrazine_nitrogen].get("charge") == -1
+    )
+
+
+def _amidine(graph: nx.Graph, mapping: Mapping) -> bool:
+    carbon = mapping[1]
+    imine_nitrogen = mapping[2]
+    amino_nitrogen = mapping[3]
+    if any(
+        graph.nodes[neighbor].get("element") == "O"
+        for neighbor in graph.neighbors(imine_nitrogen)
+        if neighbor != carbon
+    ):
+        return False
+    if any(
+        graph.nodes[neighbor].get("element") == "O"
+        for neighbor in graph.neighbors(amino_nitrogen)
+        if neighbor != carbon
+    ):
+        return False
+    return True
+
+
+def _imine(graph: nx.Graph, mapping: Mapping) -> bool:
+    carbon = mapping[1]
+    nitrogen = mapping[2]
+    if graph.nodes[carbon].get("aromatic") or graph.nodes[nitrogen].get("aromatic"):
+        return False
+    carbon_neighbors = {
+        graph.nodes[neighbor].get("element")
+        for neighbor in graph.neighbors(carbon)
+        if neighbor != nitrogen
+    }
+    nitrogen_neighbors = {
+        graph.nodes[neighbor].get("element")
+        for neighbor in graph.neighbors(nitrogen)
+        if neighbor != carbon
+    }
+    if carbon_neighbors & {"O", "S", "N"}:
+        return False
+    if nitrogen_neighbors & {"O", "N"}:
+        return False
+    return True
+
+
+def _aniline(graph: nx.Graph, mapping: Mapping) -> bool:
+    return graph.nodes[mapping[1]].get("aromatic") is True and _amine(
+        graph, {1: mapping[2]}
+    )
+
+
+def _aryl_halide(graph: nx.Graph, mapping: Mapping) -> bool:
+    return graph.nodes[mapping[1]].get("aromatic") is True
+
+
+def _oxygen_has_h(graph: nx.Graph, node: int) -> bool:
+    return graph.nodes[node].get("hcount", 0) >= 1
+
+
+def _carbon_substituent_count(graph: nx.Graph, carbon: int, excluded: set[int]) -> int:
+    return len(_single_heavy_neighbors(graph, carbon, exclude=excluded))
+
+
+def _aromatic_ring_nodes(graph: nx.Graph, mapping: Mapping) -> set[int]:
+    return {mapping[node] for node in mapping}
+
+
+def _all_aromatic(graph: nx.Graph, nodes: set[int]) -> bool:
+    return all(graph.nodes[node].get("aromatic") for node in nodes)
+
+
+def _single_node_recognizer(element: str):
+    def recognize(
+        graph: nx.Graph, pattern: FunctionalGroupPattern
+    ) -> list[FunctionalGroupMatch]:
+        matches: list[FunctionalGroupMatch] = []
+        for node, data in graph.nodes(data=True):
+            if data.get("element") != element:
+                continue
+            mapping = {1: node}
+            if pattern.validator is not None and not pattern.validator(graph, mapping):
+                continue
+            matches.append(
+                FunctionalGroupMatch(
+                    name=pattern.name,
+                    group_nodes=(node,),
+                    mapping=mapping,
+                    pattern=pattern,
+                )
+            )
+        return matches
+
+    return recognize
+
+
+def _two_node_bond_recognizer(
+    left_element: str,
+    right_elements: tuple[str, ...],
+    order: float,
+):
+    def recognize(
+        graph: nx.Graph, pattern: FunctionalGroupPattern
+    ) -> list[FunctionalGroupMatch]:
+        matches: list[FunctionalGroupMatch] = []
+        seen: set[tuple[int, ...]] = set()
+        for left, right, data in graph.edges(data=True):
+            if data.get("order") != order:
+                continue
+            pairs = ((left, right), (right, left))
+            for first, second in pairs:
+                if graph.nodes[first].get("element") != left_element:
+                    continue
+                if graph.nodes[second].get("element") not in right_elements:
+                    continue
+                mapping = {1: first, 2: second}
+                if pattern.validator is not None and not pattern.validator(
+                    graph, mapping
+                ):
+                    continue
+                group_nodes = tuple(
+                    sorted(mapping[node] for node in pattern.group_nodes)
+                )
+                if group_nodes in seen:
+                    continue
+                seen.add(group_nodes)
+                matches.append(
+                    FunctionalGroupMatch(
+                        name=pattern.name,
+                        group_nodes=group_nodes,
+                        mapping=mapping,
+                        pattern=pattern,
+                    )
+                )
+        return matches
+
+    return recognize
+
+
+def _symmetric_two_node_bond_recognizer(element: str, order: float):
+    def recognize(
+        graph: nx.Graph, pattern: FunctionalGroupPattern
+    ) -> list[FunctionalGroupMatch]:
+        matches: list[FunctionalGroupMatch] = []
+        for left, right, data in graph.edges(data=True):
+            if data.get("order") != order:
+                continue
+            if graph.nodes[left].get("element") != element:
+                continue
+            if graph.nodes[right].get("element") != element:
+                continue
+            mapping = {1: left, 2: right}
+            if pattern.validator is not None and not pattern.validator(graph, mapping):
+                continue
+            matches.append(
+                FunctionalGroupMatch(
+                    name=pattern.name,
+                    group_nodes=tuple(sorted((left, right))),
+                    mapping=mapping,
+                    pattern=pattern,
+                )
+            )
+        return matches
+
+    return recognize