synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Stereo/wire.py

@@ -0,0 +1,339 @@
+"""Versioned, deterministic wire value for reaction stereochemistry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from types import MappingProxyType
+from typing import Any, Iterable, Mapping
+
+from .changes import StereoChange
+from .couplings import StereoCoupling
+from .descriptors import StereoValue, descriptor_id, stereo_from_dict
+from .outcomes import StereoOutcome
+from .semantics import (
+    StereoReactionSemantics,
+    StereoRefusal,
+    StereoRefusalCode,
+)
+
+LEGACY_REACTION_STEREO_SCHEMA = "synkit.reaction-stereo/1"
+REACTION_STEREO_SCHEMA = "synkit.reaction-stereo/2"
+SUPPORTED_REACTION_STEREO_SCHEMAS = frozenset(
+    {LEGACY_REACTION_STEREO_SCHEMA, REACTION_STEREO_SCHEMA}
+)
+
+
+class ReactionStereoSchemaError(ValueError):
+    """Raised when a reaction-stereo payload is invalid or would lose data."""
+
+    def __init__(self, refusal: StereoRefusal) -> None:
+        self.refusal = refusal
+        super().__init__(f"{refusal.code.value}: {refusal.detail}")
+
+
+def _normalized_items(
+    values: Mapping[str, Any] | Iterable[tuple[str, Any]] | None,
+    *,
+    field: str,
+) -> tuple[tuple[str, Any], ...]:
+    if values is None:
+        return ()
+    items = tuple(values.items() if isinstance(values, Mapping) else values)
+    keys = [key for key, _value in items]
+    if any(not isinstance(key, str) or not key for key in keys):
+        raise ReactionStereoSchemaError(
+            StereoRefusal(
+                StereoRefusalCode.CONTRADICTORY_ASSERTION,
+                f"{field} targets must be nonempty strings.",
+            )
+        )
+    if len(keys) != len(set(keys)):
+        raise ReactionStereoSchemaError(
+            StereoRefusal(
+                StereoRefusalCode.CONTRADICTORY_ASSERTION,
+                f"{field} contains duplicate targets.",
+                tuple(keys),
+            )
+        )
+    return tuple(sorted(items, key=lambda item: item[0]))
+
+
+@dataclass(frozen=True, init=False)
+class StereoReactionValue:
+    """Immutable normalized reaction-stereo values and assertions."""
+
+    schema: str
+    _guards: tuple[tuple[str, StereoValue], ...]
+    _effects: tuple[tuple[str, StereoChange], ...]
+    _outcomes: tuple[tuple[str, StereoOutcome], ...]
+    _couplings: tuple[tuple[str, StereoCoupling], ...]
+    _assertions: tuple[tuple[str, StereoReactionSemantics], ...]
+    refusals: tuple[StereoRefusal, ...]
+
+    def __init__(
+        self,
+        *,
+        guards: (
+            Mapping[str, StereoValue] | Iterable[tuple[str, StereoValue]] | None
+        ) = None,
+        effects: (
+            Mapping[str, StereoChange] | Iterable[tuple[str, StereoChange]] | None
+        ) = None,
+        outcomes: (
+            Mapping[str, StereoOutcome | str | Mapping[str, Any]]
+            | Iterable[tuple[str, StereoOutcome | str | Mapping[str, Any]]]
+            | None
+        ) = None,
+        couplings: (
+            Mapping[str, StereoCoupling | Mapping[str, Any]]
+            | Iterable[tuple[str, StereoCoupling | Mapping[str, Any]]]
+            | None
+        ) = None,
+        assertions: (
+            Mapping[str, StereoReactionSemantics]
+            | Iterable[tuple[str, StereoReactionSemantics]]
+            | None
+        ) = None,
+        refusals: Iterable[StereoRefusal] = (),
+        schema: str = REACTION_STEREO_SCHEMA,
+    ) -> None:
+        if schema not in SUPPORTED_REACTION_STEREO_SCHEMAS:
+            raise ReactionStereoSchemaError(
+                StereoRefusal(
+                    StereoRefusalCode.CONTRADICTORY_ASSERTION,
+                    f"Unsupported reaction-stereo schema: {schema!r}.",
+                )
+            )
+        normalized_guards = _normalized_items(guards, field="guards")
+        normalized_effects = _normalized_items(effects, field="effects")
+        normalized_outcomes = tuple(
+            (target, StereoOutcome.from_value(value))
+            for target, value in _normalized_items(
+                outcomes,
+                field="outcomes",
+            )
+        )
+        normalized_couplings = tuple(
+            (target, StereoCoupling.from_value(value))
+            for target, value in _normalized_items(
+                couplings,
+                field="couplings",
+            )
+        )
+        normalized_assertions = _normalized_items(
+            assertions,
+            field="assertions",
+        )
+        normalized_refusals = tuple(
+            sorted(
+                refusals,
+                key=lambda item: (
+                    item.code.value,
+                    item.targets,
+                    item.detail,
+                ),
+            )
+        )
+
+        self._validate(
+            normalized_guards,
+            normalized_effects,
+            normalized_outcomes,
+            normalized_couplings,
+            normalized_assertions,
+        )
+        object.__setattr__(self, "schema", schema)
+        object.__setattr__(self, "_guards", normalized_guards)
+        object.__setattr__(self, "_effects", normalized_effects)
+        object.__setattr__(self, "_outcomes", normalized_outcomes)
+        object.__setattr__(self, "_couplings", normalized_couplings)
+        object.__setattr__(self, "_assertions", normalized_assertions)
+        object.__setattr__(self, "refusals", normalized_refusals)
+
+    @staticmethod
+    def _validate(
+        guards: tuple[tuple[str, StereoValue], ...],
+        effects: tuple[tuple[str, StereoChange], ...],
+        outcomes: tuple[tuple[str, StereoOutcome], ...],
+        couplings: tuple[tuple[str, StereoCoupling], ...],
+        assertions: tuple[tuple[str, StereoReactionSemantics], ...],
+    ) -> None:
+        del assertions
+        for target, guard in guards:
+            if descriptor_id(guard) != target:
+                raise ReactionStereoSchemaError(
+                    StereoRefusal(
+                        StereoRefusalCode.INVALID_REFERENCE,
+                        f"Guard belongs to {descriptor_id(guard)}, " f"not {target}.",
+                        (target,),
+                    )
+                )
+        effect_map = dict(effects)
+        for target, effect in effects:
+            for descriptor in (
+                effect.before,
+                effect.after,
+                effect.transition,
+            ):
+                if descriptor is not None and descriptor_id(descriptor) != target:
+                    raise ReactionStereoSchemaError(
+                        StereoRefusal(
+                            StereoRefusalCode.INVALID_REFERENCE,
+                            f"Effect descriptor belongs to "
+                            f"{descriptor_id(descriptor)}, not {target}.",
+                            (target,),
+                        )
+                    )
+        for target, _outcome in outcomes:
+            if target not in effect_map:
+                raise ReactionStereoSchemaError(
+                    StereoRefusal(
+                        StereoRefusalCode.CONTRADICTORY_ASSERTION,
+                        "A product outcome requires an effect at the same " "target.",
+                        (target,),
+                    )
+                )
+        for target, coupling in couplings:
+            if coupling.target != target:
+                raise ReactionStereoSchemaError(
+                    StereoRefusal(
+                        StereoRefusalCode.INVALID_COUPLING,
+                        f"Coupling belongs to {coupling.target}, " f"not {target}.",
+                        (target,),
+                    )
+                )
+
+    @property
+    def guards(self) -> Mapping[str, StereoValue]:
+        return MappingProxyType(dict(self._guards))
+
+    @property
+    def effects(self) -> Mapping[str, StereoChange]:
+        return MappingProxyType(dict(self._effects))
+
+    @property
+    def outcomes(self) -> Mapping[str, StereoOutcome]:
+        return MappingProxyType(dict(self._outcomes))
+
+    @property
+    def couplings(self) -> Mapping[str, StereoCoupling]:
+        return MappingProxyType(dict(self._couplings))
+
+    @property
+    def assertions(self) -> Mapping[str, StereoReactionSemantics]:
+        return MappingProxyType(dict(self._assertions))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return normalized schema-v2 content."""
+        return {
+            "schema": REACTION_STEREO_SCHEMA,
+            "guards": {target: value.to_dict() for target, value in self._guards},
+            "effects": {target: value.to_dict() for target, value in self._effects},
+            "outcomes": {target: value.to_dict() for target, value in self._outcomes},
+            "couplings": {target: value.to_dict() for target, value in self._couplings},
+            "assertions": {
+                target: value.to_dict() for target, value in self._assertions
+            },
+            "refusals": [value.to_dict() for value in self.refusals],
+        }
+
+    def normalized_json(self) -> str:
+        """Return byte-stable normalized JSON."""
+        return json.dumps(
+            self.to_dict(),
+            ensure_ascii=True,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "StereoReactionValue":
+        """Read schema v1/v2 or the equivalent unversioned v1 value."""
+        schema = str(value.get("schema", LEGACY_REACTION_STEREO_SCHEMA))
+        if schema not in SUPPORTED_REACTION_STEREO_SCHEMAS:
+            raise ReactionStereoSchemaError(
+                StereoRefusal(
+                    StereoRefusalCode.CONTRADICTORY_ASSERTION,
+                    f"Unsupported reaction-stereo schema: {schema!r}.",
+                )
+            )
+        return cls(
+            guards={
+                target: stereo_from_dict(item)
+                for target, item in value.get("guards", {}).items()
+            },
+            effects={
+                target: StereoChange.from_dict(item)
+                for target, item in value.get("effects", {}).items()
+            },
+            outcomes=value.get("outcomes", {}),
+            couplings=value.get("couplings", {}),
+            assertions={
+                target: StereoReactionSemantics.from_dict(item)
+                for target, item in value.get("assertions", {}).items()
+            },
+            refusals=tuple(
+                StereoRefusal.from_dict(item) for item in value.get("refusals", ())
+            ),
+            schema=REACTION_STEREO_SCHEMA,
+        )
+
+    @classmethod
+    def from_json(cls, value: str) -> "StereoReactionValue":
+        """Read one JSON value."""
+        return cls.from_dict(json.loads(value))
+
+    def to_legacy_dict(self) -> dict[str, Any]:
+        """Downgrade only when schema v1 can preserve all assertions."""
+        if self._assertions or self.refusals:
+            raise ReactionStereoSchemaError(
+                StereoRefusal(
+                    StereoRefusalCode.LOSSY_PROJECTION,
+                    "Schema v1 cannot carry normalized assertions " "or refusals.",
+                    tuple(target for target, _value in self._assertions),
+                )
+            )
+        payload = self.to_dict()
+        payload["schema"] = LEGACY_REACTION_STEREO_SCHEMA
+        payload.pop("assertions")
+        payload.pop("refusals")
+        return payload
+
+
+def reaction_stereo_schema() -> dict[str, Any]:
+    """Return the dependency-free JSON-Schema view of schema v2."""
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": REACTION_STEREO_SCHEMA,
+        "type": "object",
+        "additionalProperties": False,
+        "required": [
+            "schema",
+            "guards",
+            "effects",
+            "outcomes",
+            "couplings",
+            "assertions",
+            "refusals",
+        ],
+        "properties": {
+            "schema": {"const": REACTION_STEREO_SCHEMA},
+            "guards": {"type": "object"},
+            "effects": {"type": "object"},
+            "outcomes": {"type": "object"},
+            "couplings": {"type": "object"},
+            "assertions": {"type": "object"},
+            "refusals": {"type": "array"},
+        },
+    }
+
+
+__all__ = [
+    "LEGACY_REACTION_STEREO_SCHEMA",
+    "REACTION_STEREO_SCHEMA",
+    "SUPPORTED_REACTION_STEREO_SCHEMAS",
+    "ReactionStereoSchemaError",
+    "StereoReactionValue",
+    "reaction_stereo_schema",
+]

synkit/Graph/Wildcard/fuse_graph.py

@@ -0,0 +1,156 @@
+import logging
+from typing import Any, Callable, Dict, Optional, Union, Set
+
+import networkx as nx
+from networkx.algorithms import isomorphism
+
+# Alias for any NetworkX graph type
+GraphType = Union[nx.Graph, nx.DiGraph, nx.MultiGraph, nx.MultiDiGraph]
+
+
+def find_wc_graph_isomorphism(
+    G1: GraphType,
+    G2: GraphType,
+    node_match: Optional[Callable[[Dict[str, Any], Dict[str, Any]], bool]] = None,
+    edge_match: Optional[Callable[[Dict[str, Any], Dict[str, Any]], bool]] = None,
+    logger: Optional[logging.Logger] = None,
+) -> Optional[Dict[Any, Any]]:
+    """Wildcard‑aware sub‑graph isomorphism.  Returns a mapping from every node
+    in the **smaller** graph to a node in the **larger** graph, allowing any
+    node whose ``element == "*"`` to match *any* concrete node (or group of
+    nodes) on the host side.
+
+    :param G1: First input graph.
+    :type  G1: nx.Graph | nx.DiGraph | nx.MultiGraph | nx.MultiDiGraph
+    :param G2: Second input graph.
+    :type  G2: nx.Graph | nx.DiGraph | nx.MultiGraph | nx.MultiDiGraph
+    :param node_match: Optional node‑predicate; default treats “*” as a joker.
+    :type  node_match: Callable[[dict, dict], bool] | None
+    :param edge_match: Optional edge‑predicate; default ignores edge data.
+    :type  edge_match: Callable[[dict, dict], bool] | None
+    :param logger: Optional logger for diagnostics.
+    :type  logger: logging.Logger | None
+    :return: Mapping *pattern‑node → host‑node* if a wildcard isomorphism
+              exists; otherwise ``None``.
+    :rtype: dict[Any, Any] | None
+    """
+    log = logger or logging.getLogger(__name__)
+
+    # ------------------------------------------------------------------ helpers
+    if node_match is None:
+
+        def node_match(a: Dict[str, Any], b: Dict[str, Any]) -> bool:  # noqa: W shadow
+            return (
+                a.get("element") == "*"
+                or b.get("element") == "*"
+                or a.get("element") == b.get("element")
+            )
+
+    if edge_match is None:
+
+        def edge_match(a: Dict[str, Any], b: Dict[str, Any]) -> bool:
+            return True
+
+    # ------------------------------------------------------------------ choose host|pattern
+    if G1.number_of_nodes() >= G2.number_of_nodes():
+        host, pattern = G1, G2
+        invert = False
+    else:
+        host, pattern = G2, G1
+        invert = True
+
+    Matcher = (
+        isomorphism.MultiGraphMatcher
+        if isinstance(host, (nx.MultiGraph, nx.MultiDiGraph))
+        else isomorphism.GraphMatcher
+    )
+
+    GM = Matcher(host, pattern, node_match=node_match, edge_match=edge_match)
+
+    for mapping_host_to_pattern in GM.subgraph_isomorphisms_iter():
+        log.debug("Wildcard match found: %s", mapping_host_to_pattern)
+        return (
+            {v: k for k, v in mapping_host_to_pattern.items()}  # pattern → host
+            if invert
+            else mapping_host_to_pattern
+        )
+
+    log.debug("No wildcard mapping exists between the two graphs.")
+    return None
+
+
+def fuse_wc_graphs(
+    G1: GraphType,
+    G2: GraphType,
+    mapping: Dict[Any, Any],
+    wildcard: str = "*",
+    logger: Optional[logging.Logger] = None,
+) -> GraphType:
+    """Fuse a wildcard‑pattern graph *G1* into the concrete host *G2*.
+
+    The result lives **entirely in G2’s node‑ID space** and contains:
+
+    • every host‑node ``mapping[p]`` for a **non‑wildcard** node *p* in G1
+      (and its attributes are overridden with those from G1, so no “*” leaks
+      back in);
+
+    • every host‑node ``mapping[w]`` for a **wildcard** node *w* in G1 **plus
+      all one‑hop neighbours of that host** that were not already used by a
+      non‑wildcard;
+
+    • **all edges present in G2** among the nodes kept above.
+
+    :param G1: `G1` may contain nodes whose ``element`` is the wildcard marker
+               (default ``"*"``, change via `wildcard`).
+               `G2` is the concrete graph we will graft from.
+    :type G1: GraphType
+    :param G2: `G1` may contain nodes whose ``element`` is the wildcard marker
+               (default ``"*"``, change via `wildcard`).
+               `G2` is the concrete graph we will graft from.
+    :type G2: GraphType
+    :param mapping: The full node–node map returned by `find_wc_graph_isomorphism`
+                    (must include *every* node of `G1`).
+    :type mapping: Dict[Any, Any]
+    :param wildcard: The value of the ``"element"`` attribute that marks a wildcard node.
+    :type wildcard: str, default "*"
+    :param logger: Optional logger for debug output.
+    :type logger: logging.Logger or None
+
+    :return: A new graph of the same class as G2 containing the fused structure.
+    :rtype: GraphType
+    """
+    log = logger or logging.getLogger(__name__)
+
+    # ----------------------------------------------------------------- helpers
+    def is_wildcard(node_id: Any) -> bool:
+        return G1.nodes[node_id].get("element") == wildcard
+
+    # 1) gather core (non‑wc) and wc nodes in G1 -------------------------------
+    core_nodes = [n for n in G1 if not is_wildcard(n)]
+    wc_nodes = [n for n in G1 if is_wildcard(n)]
+
+    # 2) host nodes that *must* be present (mapping of core) -------------------
+    host_nodes: Set[Any] = {mapping[p] for p in core_nodes}
+
+    # 3) for every wildcard, keep its host anchor + all one‑hop extras ---------
+    for w in wc_nodes:
+        h_anchor = mapping[w]
+        host_nodes.add(h_anchor)
+        # neighbours of anchor not already used by the core
+        for nbr in G2.neighbors(h_anchor):
+            host_nodes.add(nbr)
+
+    # 4) build H as the *induced* sub‑graph of G2 on that node‑set -------------
+    H: GraphType = G2.subgraph(host_nodes).copy()
+
+    # 5) overwrite attributes on core‑hosts with G1’s concrete data -----------
+    for p in core_nodes:
+        h = mapping[p]
+        H.nodes[h].update(G1.nodes[p])
+
+    log.debug(
+        "Fused graph has %d nodes and %d edges",
+        H.number_of_nodes(),
+        H.number_of_edges(),
+    )
+    return H