synkit 1.6.5__py3-none-win_amd64.whl

synkit/Rule/Apply/rule_matcher.py

@@ -0,0 +1,218 @@
+"""rule_matcher.py
+=================
+Immutable matcher for applying a reaction‑template rule to a reaction SMILES.
+
+Key features
+------------
+* **Standardization** – canonicalize the input RSMI.
+* **Balanced vs. partial matching** – uses stoichiometric balance checks.
+* **SMARTS extraction** – extracts SMARTS that reproduce the RSMI.
+* **Introspective API** – stores the match on init; exposes `get_result()`, `help()`,
+  `__str__()`, and `__repr__()` for inspection.
+
+Quick start
+-----------
+>>> from synkit.Graph.rule_matcher import RuleMatcher
+>>> matcher = RuleMatcher('CCO>>CC=O', some_rule_graph)
+>>> smarts, rule = matcher.get_result()
+"""
+
+from typing import List, Optional, Tuple, Union
+
+import networkx as nx
+from synkit.IO import rsmi_to_graph, rsmi_to_its
+from synkit.Chem.Reaction.standardize import Standardize
+from synkit.Chem.Reaction.balance_check import BalanceReactionCheck
+from synkit.Synthesis.Reactor import SynReactor
+
+__all__ = ["RuleMatcher"]
+
+
+class RuleMatcher:
+    """Match a reaction SMILES against a transformation‑rule graph and extract
+    the SMARTS pattern that reproduces the reaction.
+
+    On initialization, the matcher standardizes the RSMI, builds reactant/product
+    graphs, checks balance, and finds the matching SMARTS (stored in `self.result`).
+
+    :param rsmi: Reaction SMILES in 'reactant>>product' format.
+    :type rsmi: str
+    :param rule: A NetworkX graph encoding the reaction template.
+    :type rule: nx.Graph
+
+    :ivar std: SMILES standardizer instance.
+    :vartype std: Standardize
+    :ivar rsmi: Standardized reaction SMILES.
+    :vartype rsmi: str
+    :ivar r_graph: Reactant graph extracted from `rsmi`.
+    :vartype r_graph: nx.Graph
+    :ivar p_graph: Product graph extracted from `rsmi`.
+    :vartype p_graph: nx.Graph
+    :ivar balanced: True if reaction passes stoichiometric balance check.
+    :vartype balanced: bool
+    :ivar result: The matching SMARTS and rule graph tuple.
+    :vartype result: Tuple[str, nx.Graph]
+    """
+
+    def __init__(
+        self,
+        rsmi: str,
+        rule: Union[str, nx.Graph],
+        explicit_h: bool = True,
+        electron_diagnostics: bool = False,
+    ) -> None:
+        """Initialize the matcher by standardizing the RSMI, building graphs,
+        checking balance, and computing the match.
+
+        :param rsmi: Reaction SMILES in 'reactant>>product' format.
+        :type rsmi: str
+        :param rule: Transformation-rule graph.
+        :type rule: nx.Graph
+        :raises ValueError: If no SMARTS reproduces the RSMI under the
+            given rule.
+        """
+        self.std = Standardize()
+        self.rsmi = self.std.fit(rsmi)
+        self.r_graph, self.p_graph = rsmi_to_graph(self.rsmi, drop_non_aam=False)
+        if isinstance(rule, str):
+            rule = rsmi_to_its(rule, core=True)
+        self.rule = rule
+        self.explicit_h = explicit_h
+        self.electron_diagnostics = electron_diagnostics
+        self._diagnostics: list[dict] = []
+        self.balanced = BalanceReactionCheck(n_jobs=1).rsmi_balance_check(self.rsmi)
+
+        # Compute and store the match result
+        if self.balanced:
+            match = self._match_valid()
+        else:
+            match = self._match_reverse()
+
+        if match is None:
+            raise ValueError(
+                f"No matching SMARTS for RSMI '{self.rsmi}' with given rule"
+            )
+        self.result = match
+
+    def get_result(self) -> Tuple[str, nx.Graph]:
+        """Return the SMARTS and rule graph found during initialization.
+
+        :return: A tuple (smarts, rule_graph).
+        :rtype: tuple[str, nx.Graph]
+        """
+        return self.result
+
+    def _match_valid(self) -> Optional[Tuple[str, nx.Graph]]:
+        """Attempt a direct (balanced) match of the rule.
+
+        :return: (smarts, rule) if direct match succeeds; otherwise
+            None.
+        :rtype: Optional[tuple[str, nx.Graph]]
+        """
+        reactor = SynReactor(
+            substrate=self.r_graph,
+            template=self.rule,
+            electron_diagnostics=self.electron_diagnostics,
+        )
+        for smarts in reactor.smarts_list:
+            if self.std.fit(smarts) == self.rsmi:
+                self._diagnostics = reactor.diagnostics
+                return smarts, self.rule
+        return None
+
+    def _match_reverse(self) -> Optional[Tuple[str, nx.Graph]]:
+        """Attempt a reverse‑balance (partial) match for unbalanced reactions.
+
+        First tries matching on product fragments, then on reactant
+        fragments with the template inverted.
+
+        :return: (smarts, rule) if a partial match is found; otherwise
+            None.
+        :rtype: Optional[tuple[str, nx.Graph]]
+        """
+        # Product‑side fragments
+        reactor = SynReactor(
+            substrate=self.r_graph,
+            template=self.rule,
+            electron_diagnostics=self.electron_diagnostics,
+        )
+        for smarts in reactor.smarts_list:
+            std_r = self.std.fit(smarts)
+            if self.all_in(
+                self.rsmi.split(">>")[1].split("."), std_r.split(">>")[1].split(".")
+            ):
+                self._diagnostics = reactor.diagnostics
+                return smarts, self.rule
+
+        # Reactant‑side with inverted template
+        reactor = SynReactor(
+            substrate=self.p_graph,
+            template=self.rule,
+            invert=True,
+            explicit_h=self.explicit_h,
+            electron_diagnostics=self.electron_diagnostics,
+        )
+        for smarts in reactor.smarts_list:
+            std_r = self.std.fit(smarts)
+            if self.all_in(
+                self.rsmi.split(">>")[0].split("."), std_r.split(">>")[0].split(".")
+            ):
+                self._diagnostics = reactor.diagnostics
+                return smarts, self.rule
+
+        return None
+
+    @staticmethod
+    def all_in(a: List[str], b: List[str]) -> bool:
+        """Check if every element of list `a` appears in list `b`.
+
+        :param a: List of elements to test for membership.
+        :type a: list[str]
+        :param b: List in which to test membership.
+        :type b: list[str]
+        :return: True if set(a) is a subset of set(b); otherwise False.
+        :rtype: bool
+        """
+        return set(a).issubset(b)
+
+    @property
+    def diagnostics(self) -> list[dict]:
+        """Electron diagnostics from the reactor that produced the match."""
+        return list(self._diagnostics)
+
+    def help(self) -> None:
+        """Print internal state and candidate SMARTS patterns for debugging.
+
+        :return: None
+        :rtype: NoneType
+        """
+        print(f"RuleMatcher for RSMI: {self.rsmi!r}")
+        print(f"Balanced: {self.balanced}")
+        print("Candidate SMARTS patterns:")
+        reactor = SynReactor(substrate=self.r_graph, template=self.rule)
+        for smarts in reactor.smarts_list:
+            print("  ", smarts)
+
+    def __str__(self) -> str:
+        """Short string showing the RSMI and balance status.
+
+        :return: Human‑readable summary.
+        :rtype: str
+        """
+        status = "balanced" if self.balanced else "unbalanced"
+        return f"<RuleMatcher {self.rsmi!r} ({status})>"
+
+    def __repr__(self) -> str:
+        """Detailed representation including rule size and balance.
+
+        :return: repr string.
+        :rtype: str
+        """
+        try:
+            v, e = self.rule.number_of_nodes(), self.rule.number_of_edges()
+        except Exception:
+            v = e = 0
+        return (
+            f"RuleMatcher(rsmi={self.rsmi!r}, "
+            f"rule=(|V|={v},|E|={e}), balanced={self.balanced})"
+        )

synkit/Rule/Apply/validation.py

@@ -0,0 +1,354 @@
+"""Independent finite checks for injective natural DPO squares.
+
+The checker uses carrier coverage, exact intersection, coordinate unions and
+coordinate agreement. It does not assume an adhesive ambient category.
+"""
+
+from __future__ import annotations
+
+from synkit.Graph.Morphism import (
+    LLGError,
+    derive_electron_labeled_graph,
+    is_electron_schema,
+)
+
+
+def _image_edges(graph, mapping):
+    return {frozenset(mapping[node] for node in edge) for edge in graph.edge_keys}
+
+
+def _morphism(source, target, pairs, name, issues):
+    from .dpo import DPOIssue, DPOIssueCode
+
+    mapping = dict(pairs)
+    if (
+        len(mapping) != len(pairs)
+        or set(mapping) != set(source.node_ids)
+        or len(set(mapping.values())) != len(mapping)
+        or not set(mapping.values()) <= set(target.node_ids)
+    ):
+        issues.append(
+            DPOIssue(
+                DPOIssueCode.NONCOMMUTATIVE,
+                "A certificate map is not a total injective carrier map.",
+                {"map": name},
+            )
+        )
+        return None
+    for node, image in mapping.items():
+        labels = source.node_labels(node, semantic=True)
+        target_labels = target.node_labels(image, semantic=True)
+        if any(
+            key not in target_labels or target_labels[key] != value
+            for key, value in labels.items()
+        ):
+            issues.append(
+                DPOIssue(
+                    DPOIssueCode.MATCH_LABEL,
+                    "A certificate map does not preserve defined node labels.",
+                    {"map": name},
+                )
+            )
+    for edge in source.edge_keys:
+        image = frozenset(mapping[node] for node in edge)
+        if image not in target.edge_keys:
+            issues.append(
+                DPOIssue(
+                    DPOIssueCode.MATCH_INCIDENCE,
+                    "A certificate map does not preserve incidence.",
+                    {"map": name},
+                )
+            )
+            continue
+        labels = source.edge_labels(edge, semantic=True)
+        target_labels = target.edge_labels(image, semantic=True)
+        if any(
+            key not in target_labels or target_labels[key] != value
+            for key, value in labels.items()
+        ):
+            issues.append(
+                DPOIssue(
+                    DPOIssueCode.MATCH_LABEL,
+                    "A certificate map does not preserve defined edge labels.",
+                    {"map": name},
+                )
+            )
+    return mapping
+
+
+def _square(
+    interface,
+    first,
+    context,
+    target,
+    arm,
+    to_context,
+    first_target,
+    context_target,
+    issues,
+):
+    from .dpo import DPOIssue, DPOIssueCode
+
+    for edge_mode in (False, True):
+        if edge_mode:
+            first_image = _image_edges(first, first_target)
+            context_image = _image_edges(context, context_target)
+            interface_image = _image_edges(
+                interface, {n: first_target[arm[n]] for n in interface.node_ids}
+            )
+            target_carriers = set(target.edge_keys)
+            first_carriers = first.edge_keys
+            context_carriers = context.edge_keys
+            interface_carriers = interface.edge_keys
+            keys = target.schema.semantic_edge_keys
+
+            def labels(graph, item):
+                return graph.edge_labels(item, semantic=True)
+
+            def transport(mapping, item):
+                return frozenset(mapping[n] for n in item)
+
+        else:
+            first_image = set(first_target.values())
+            context_image = set(context_target.values())
+            interface_image = {first_target[arm[n]] for n in interface.node_ids}
+            target_carriers = set(target.node_ids)
+            first_carriers = first.node_ids
+            context_carriers = context.node_ids
+            interface_carriers = interface.node_ids
+            keys = target.schema.semantic_node_keys
+
+            def labels(graph, item):
+                return graph.node_labels(item, semantic=True)
+
+            def transport(mapping, item):
+                return mapping[item]
+
+        if (
+            first_image | context_image != target_carriers
+            or first_image & context_image != interface_image
+        ):
+            issues.append(
+                DPOIssue(
+                    DPOIssueCode.NONCOMMUTATIVE,
+                    "A square fails carrier coverage or exact interface intersection.",
+                    {"edges": edge_mode},
+                )
+            )
+            continue
+        _label_square(
+            interface,
+            first,
+            context,
+            target,
+            arm,
+            to_context,
+            first_target,
+            context_target,
+            labels,
+            transport,
+            keys,
+            first_carriers,
+            context_carriers,
+            target_carriers,
+            interface_carriers,
+            issues,
+        )
+
+
+def _label_square(
+    interface,
+    first,
+    context,
+    target,
+    arm,
+    to_context,
+    first_target,
+    context_target,
+    labels,
+    transport,
+    keys,
+    first_carriers,
+    context_carriers,
+    target_carriers,
+    interface_carriers,
+    issues,
+):
+    from .dpo import DPOIssue, DPOIssueCode
+
+    supplied = {}
+    for graph, carriers, mapping in (
+        (first, first_carriers, first_target),
+        (context, context_carriers, context_target),
+    ):
+        for item in carriers:
+            image = transport(mapping, item)
+            union = supplied.setdefault(image, {})
+            for key, value in labels(graph, item).items():
+                if key in union and union[key] != value:
+                    issues.append(
+                        DPOIssue(DPOIssueCode.RESULT_LABEL, "Pushout labels conflict.")
+                    )
+                union[key] = value
+    for item in target_carriers:
+        if supplied[item] != labels(target, item):
+            issues.append(
+                DPOIssue(
+                    DPOIssueCode.RESULT_LABEL,
+                    "Target labels are not the union of the two arms.",
+                )
+            )
+    for item in interface_carriers:
+        first_labels = labels(first, transport(arm, item))
+        context_labels = labels(context, transport(to_context, item))
+        agreement = {
+            key: first_labels[key]
+            for key in keys
+            if key in first_labels
+            and key in context_labels
+            and first_labels[key] == context_labels[key]
+        }
+        if labels(interface, item) != agreement:
+            issues.append(
+                DPOIssue(
+                    DPOIssueCode.RESULT_LABEL,
+                    "The interface is not the coordinate agreement pullback.",
+                )
+            )
+
+
+def validate_certificate(certificate):
+    """Check map shape, labels, naturality, resources, policy and edit metadata."""
+    from .dpo import DPOError, DPOIssue, DPOIssueCode, RuleEmbedding
+
+    c = certificate
+    issues = []
+    schema = c.rule.left.schema
+    if any(
+        graph.schema != schema
+        for graph in (c.rule.interface, c.rule.right, c.host, c.context, c.result)
+    ):
+        return [
+            DPOIssue(
+                DPOIssueCode.SCHEMA_MISMATCH, "All square objects must use one schema."
+            )
+        ]
+    if c.host.partial or c.result.partial or not c.context.partial:
+        return [
+            DPOIssue(
+                DPOIssueCode.INTERFACE_PARTIAL,
+                "Host and result are total; context is partial.",
+            )
+        ]
+    try:
+        RuleEmbedding(c.rule.interface, c.rule.left, c.rule.left_arm.f)
+        RuleEmbedding(c.rule.interface, c.rule.right, c.rule.right_arm.f)
+        c.rule.__post_init__()
+    except DPOError as error:
+        return list(error.issues)
+    maps = [
+        _morphism(source, target, pairs, name, issues)
+        for source, target, pairs, name in (
+            (c.rule.left, c.host, c.match, "match"),
+            (
+                c.rule.interface,
+                c.context,
+                c.interface_to_context,
+                "interface_to_context",
+            ),
+            (c.context, c.host, c.context_to_host, "context_to_host"),
+            (c.context, c.result, c.context_to_result, "context_to_result"),
+            (c.rule.right, c.result, c.right_to_result, "right_to_result"),
+        )
+    ]
+    if issues:
+        return issues
+    match, to_context, context_host, context_result, right_result = maps
+    for arm, first_target, context_target in (
+        (c.rule.left_arm.mapping, match, context_host),
+        (c.rule.right_arm.mapping, right_result, context_result),
+    ):
+        if any(
+            first_target[arm[n]] != context_target[to_context[n]]
+            for n in c.rule.interface.node_ids
+        ):
+            return [
+                DPOIssue(
+                    DPOIssueCode.NONCOMMUTATIVE,
+                    "A certificate square does not commute.",
+                )
+            ]
+    _square(
+        c.rule.interface,
+        c.rule.left,
+        c.context,
+        c.host,
+        c.rule.left_arm.mapping,
+        to_context,
+        match,
+        context_host,
+        issues,
+    )
+    _square(
+        c.rule.interface,
+        c.rule.right,
+        c.context,
+        c.result,
+        c.rule.right_arm.mapping,
+        to_context,
+        right_result,
+        context_result,
+        issues,
+    )
+    _validate_edits_and_condition(c, match, context_result, issues)
+    if c.resource_delta != c.rule.resource_delta:
+        issues.append(
+            DPOIssue(
+                DPOIssueCode.OPEN_TOKEN_MISMATCH,
+                "Recorded resource delta is incorrect.",
+            )
+        )
+    if is_electron_schema(schema):
+        for graph in (c.host, c.result):
+            try:
+                derive_electron_labeled_graph(graph.to_networkx())
+            except LLGError:
+                issues.append(
+                    DPOIssue(
+                        DPOIssueCode.RESULT_LABEL,
+                        "A total electron host has incoherent derived labels.",
+                    )
+                )
+    return issues
+
+
+def _validate_edits_and_condition(c, match, context_result, issues):
+    from .dpo import DPOError, DPOIssue, DPOIssueCode, _deletion_plan
+
+    try:
+        deletion = _deletion_plan(c.rule, c.host, match)
+        if c.rule.condition is not None:
+            c.rule.condition.validate(c.host, match)
+    except DPOError as error:
+        issues.extend(error.issues)
+    else:
+        expected_added_nodes = set(c.result.node_ids) - set(context_result.values())
+        expected_added_edges = set(c.result.edge_keys) - _image_edges(
+            c.context, context_result
+        )
+        metadata = (
+            (c.deleted_nodes, deletion.nodes),
+            (c.deleted_edges, deletion.edges),
+            (c.added_nodes, expected_added_nodes),
+            (c.added_edges, expected_added_edges),
+        )
+        if any(
+            len(items) != len(set(items)) or set(items) != set(expected)
+            for items, expected in metadata
+        ):
+            issues.append(
+                DPOIssue(
+                    DPOIssueCode.NONCOMMUTATIVE,
+                    "Edit provenance does not match the squares.",
+                )
+            )

synkit/Rule/Compose/__init__.py

@@ -0,0 +1,106 @@
+"""Native proof-bearing rule identity and composition."""
+
+from ._identity import cluster_rule_objects, rule_objects_isomorphic
+from .composition import (
+    CompositionCertificate,
+    CompositionError,
+    CompositionIssue,
+    CompositionIssueCode,
+    CompositionProvenance,
+    CompositionReplay,
+    CompositionResult,
+    ProvenanceRef,
+    RuleOverlap,
+    compose_rules,
+)
+from .search import (
+    CompositionClass,
+    CompositionSearchResult,
+    CompositionWitness,
+    ExtendedMatchMatrix,
+    OverlapSearchError,
+    OverlapSearchIssue,
+    OverlapSearchIssueCode,
+    OverlapSearchLimits,
+    RejectedOverlap,
+    RuleSpanIsomorphism,
+    canonical_overlap_digest,
+    canonical_rule_identity,
+    enumerate_overlaps,
+    extended_component_match_matrix,
+    find_rule_span_isomorphism,
+    quotient_composition_witnesses,
+    rule_spans_isomorphic,
+    search_compositions,
+)
+from .laws import (
+    CommutationCertificate,
+    LawError,
+    LawIssue,
+    LawIssueCode,
+    ParallelIndependenceCertificate,
+    RuleAccess,
+    check_parallel_independence,
+    commute_independent,
+    find_llg_isomorphism,
+    identity_rule,
+    reverse_rule,
+)
+from .synrule import (
+    SynRuleCompositionError,
+    SynRuleCompositionIssue,
+    SynRuleCompositionIssueCode,
+    compose_synrules,
+    search_synrule_compositions,
+    synrule_to_span,
+)
+
+__all__ = [
+    "CompositionCertificate",
+    "CompositionClass",
+    "CompositionError",
+    "CompositionIssue",
+    "CompositionIssueCode",
+    "CompositionProvenance",
+    "CompositionReplay",
+    "CompositionResult",
+    "CompositionSearchResult",
+    "CompositionWitness",
+    "ExtendedMatchMatrix",
+    "CommutationCertificate",
+    "LawError",
+    "LawIssue",
+    "LawIssueCode",
+    "OverlapSearchError",
+    "OverlapSearchIssue",
+    "OverlapSearchIssueCode",
+    "OverlapSearchLimits",
+    "ParallelIndependenceCertificate",
+    "ProvenanceRef",
+    "RuleOverlap",
+    "RuleAccess",
+    "RejectedOverlap",
+    "RuleSpanIsomorphism",
+    "SynRuleCompositionError",
+    "SynRuleCompositionIssue",
+    "SynRuleCompositionIssueCode",
+    "canonical_overlap_digest",
+    "canonical_rule_identity",
+    "check_parallel_independence",
+    "cluster_rule_objects",
+    "compose_rules",
+    "compose_synrules",
+    "commute_independent",
+    "enumerate_overlaps",
+    "extended_component_match_matrix",
+    "find_rule_span_isomorphism",
+    "quotient_composition_witnesses",
+    "find_llg_isomorphism",
+    "identity_rule",
+    "rule_objects_isomorphic",
+    "rule_spans_isomorphic",
+    "reverse_rule",
+    "search_compositions",
+    "search_synrule_compositions",
+    "synrule_to_span",
+]