synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Stereo/rdkit_identity.py

@@ -0,0 +1,118 @@
+"""Versioned RDKit identity profiles and complete resonance-family keys."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from functools import cached_property
+import hashlib
+import json
+from typing import Any
+
+from .canonical import CanonicalStereographResult, _rdkit_graph_and_registry
+from .configured import (
+    MirrorIdentityProfile,
+    _mirror_profile_options,
+    _resonance_graphs,
+    canonicalize_configured_registry,
+)
+from .descriptors import StereoValue
+
+RDKIT_IDENTITY_SCHEMA = "synkit.rdkit-stereograph/1"
+RESONANCE_FAMILY_SCHEMA = "synkit.resonance-family-stereograph/1"
+
+
+def profile_certificate(result: CanonicalStereographResult, profile: str):
+    """Namespace a single drawing's full key without changing its witnesses."""
+    code = f"{RDKIT_IDENTITY_SCHEMA}\n{profile}\n{result.canonical_code}"
+    return replace(
+        result, schema=RDKIT_IDENTITY_SCHEMA, canonical_code=code,
+        canonical_digest=hashlib.sha256(code.encode("utf-8")).hexdigest(),
+        identity_profile=profile,
+    )
+
+
+@dataclass(frozen=True)
+class ResonanceFamilyCanonicalResult:
+    """Identity of an entire declared resonance family.
+
+    ``members`` retain one witness per distinct canonical drawing.  An atom
+    order or automorphism of one member must not be interpreted as a unique
+    atom order or the full automorphism group of the family.  Equality uses
+    the complete sorted family, never a finite digest or a selected member.
+    """
+
+    members: tuple[CanonicalStereographResult, ...]
+    schema: str = RESONANCE_FAMILY_SCHEMA
+    identity_profile: str = "chemical"
+
+    def __post_init__(self):
+        if not self.members or any(not member.complete or not member.exact for member in self.members):
+            raise ValueError("A family certificate requires complete exact members.")
+        codes = tuple(member.canonical_code for member in self.members)
+        if codes != tuple(sorted(set(codes))):
+            raise ValueError("Family members must have sorted distinct full certificates.")
+
+    @cached_property
+    def canonical_code(self) -> str:
+        return f"{self.schema}\n" + json.dumps(
+            [self.identity_profile, [member.canonical_code for member in self.members]],
+            ensure_ascii=True, separators=(",", ":"),
+        )
+
+    @cached_property
+    def canonical_digest(self) -> str:
+        return hashlib.sha256(self.canonical_code.encode("utf-8")).hexdigest()
+
+    @property
+    def canonical_certificate(self) -> str:
+        return self.canonical_code
+
+    @property
+    def complete(self) -> bool:
+        return True
+
+    @property
+    def exact(self) -> bool:
+        return True
+
+    def same_stereograph(self, other: object) -> bool:
+        return (
+            isinstance(other, ResonanceFamilyCanonicalResult)
+            and self.schema == other.schema
+            and self.identity_profile == other.identity_profile
+            and self.canonical_code == other.canonical_code
+        )
+
+
+RDKitIdentityResult = CanonicalStereographResult | ResonanceFamilyCanonicalResult
+
+
+def canonicalize_rdkit_registry(
+    molecule: Any,
+    registry: Mapping[str, StereoValue],
+    *,
+    identity_profile: MirrorIdentityProfile,
+) -> RDKitIdentityResult:
+    """Canonize a registry in the molecule's shared atom-handle namespace."""
+    options = _mirror_profile_options(identity_profile)
+    if identity_profile != "chemical":
+        graph, _source = _rdkit_graph_and_registry(molecule)
+        return profile_certificate(
+            canonicalize_configured_registry(graph, registry, **options), identity_profile,
+        )
+    members = {}
+    for graph in _resonance_graphs(molecule):
+        result = profile_certificate(canonicalize_configured_registry(graph, registry), "lewis_state")
+        members.setdefault(result.canonical_code, result)
+    return ResonanceFamilyCanonicalResult(tuple(members[code] for code in sorted(members)))
+
+
+def canonicalize_rdkit_identity(
+    molecule: Any,
+    *,
+    identity_profile: MirrorIdentityProfile = "lewis_state",
+) -> RDKitIdentityResult:
+    """Produce a full source-declared configured identity in one profile."""
+    _graph, registry = _rdkit_graph_and_registry(molecule)
+    return canonicalize_rdkit_registry(molecule, registry, identity_profile=identity_profile)

synkit/Graph/Stereo/rdkit_resonance.py

@@ -0,0 +1,140 @@
+"""Declared RDKit resonance closure and profile-aware phosphate equivalence."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import networkx as nx
+
+from .canonical import _rdkit_graph
+
+MirrorIdentityProfile = Literal["chemical", "lewis_state", "acs_topology"]
+_MAX_RESONANCE_FORMS = 4096
+
+
+def _resonance_graphs(molecule: Any) -> tuple[nx.Graph, ...]:
+    """Return RDKit resonance forms closed under the declared phosphate move.
+
+    This is an explicit computational identity convention, not a guarantee
+    of exhaustive enumeration of every chemically possible resonance form.
+    The terminal phosphate move is needed because RDKit's supplier does not
+    supply those charge/bond-order exchanges itself.
+    """
+    from rdkit import Chem
+
+    supplier = Chem.ResonanceMolSupplier(
+        molecule,
+        flags=(Chem.ResonanceFlags.ALLOW_CHARGE_SEPARATION | Chem.ResonanceFlags.KEKULE_ALL),
+        maxStructs=_MAX_RESONANCE_FORMS,
+    )
+    forms = tuple(supplier)
+    if len(forms) >= _MAX_RESONANCE_FORMS:
+        raise RuntimeError(
+            "Exact resonance-family enumeration reached the "
+            f"{_MAX_RESONANCE_FORMS}-form safety limit."
+        )
+    if not forms:
+        forms = (Chem.Mol(molecule),)
+    pending = list(forms)
+    seen = set()
+    graphs = []
+    while pending:
+        form = pending.pop()
+        drawing = (
+            tuple(atom.GetFormalCharge() for atom in form.GetAtoms()),
+            tuple(str(bond.GetBondType()) for bond in form.GetBonds()),
+        )
+        if drawing in seen:
+            continue
+        seen.add(drawing)
+        if len(seen) >= _MAX_RESONANCE_FORMS:
+            raise RuntimeError(
+                "Exact resonance-family closure reached the "
+                f"{_MAX_RESONANCE_FORMS}-form safety limit."
+            )
+        normalized = Chem.Mol(form)
+        Chem.SetAromaticity(normalized)
+        graphs.append(_rdkit_graph(normalized))
+        for center, left, right in _terminal_phosphate_pairs(form):
+            alternate = Chem.RWMol(form)
+            alternate.GetAtomWithIdx(left).SetFormalCharge(-1)
+            alternate.GetAtomWithIdx(right).SetFormalCharge(0)
+            alternate.GetBondBetweenAtoms(center, left).SetBondType(Chem.BondType.SINGLE)
+            alternate.GetBondBetweenAtoms(center, right).SetBondType(Chem.BondType.DOUBLE)
+            alternate = alternate.GetMol()
+            Chem.SanitizeMol(alternate)
+            pending.append(alternate)
+    return tuple(graphs)
+
+
+def _terminal_phosphate_pairs(molecule: Any) -> tuple[tuple[int, int, int], ...]:
+    """Locate the narrowly declared terminal phosphate resonance move.
+
+    Only neutral, nonradical, four-coordinate P with a terminal neutral O
+    double bond and a terminal anionic O single bond is included.  Both O
+    atoms have no hydrogens or radicals.  The move exchanges charge and bond
+    order while preserving atom identity, isotope and total charge/valence.
+    """
+    from rdkit import Chem
+
+    pairs = []
+    for atom in molecule.GetAtoms():
+        if (
+            atom.GetAtomicNum() != 15
+            or atom.GetFormalCharge() != 0
+            or atom.GetDegree() != 4
+            or atom.GetTotalValence() != 5
+            or atom.GetNumRadicalElectrons() != 0
+            or atom.GetTotalNumHs() != 0
+        ):
+            continue
+        double = []
+        single = []
+        for oxygen in atom.GetNeighbors():
+            if (
+                oxygen.GetAtomicNum() != 8
+                or oxygen.GetDegree() != 1
+                or oxygen.GetTotalNumHs() != 0
+                or oxygen.GetNumRadicalElectrons() != 0
+                or oxygen.GetIsAromatic()
+            ):
+                continue
+            bond = molecule.GetBondBetweenAtoms(atom.GetIdx(), oxygen.GetIdx())
+            if oxygen.GetFormalCharge() == 0 and bond.GetBondType() == Chem.BondType.DOUBLE:
+                double.append(oxygen.GetIdx())
+            if oxygen.GetFormalCharge() == -1 and bond.GetBondType() == Chem.BondType.SINGLE:
+                single.append(oxygen.GetIdx())
+        pairs.extend((atom.GetIdx(), left, right) for left in double for right in single)
+    return tuple(pairs)
+
+
+def _is_terminal_phosphate_resonance_locus(
+    molecule: Any,
+    element: Any,
+    *,
+    identity_profile: MirrorIdentityProfile,
+) -> bool:
+    """Return whether an apparent P center differs only by localized resonance.
+
+    A neutral tetra-coordinate phosphorus with terminal ``P=O`` and
+    ``P-[O-]`` ligands contains two drawings of the same delocalized phosphate
+    oxygen environment.  Treating bond order and formal charge as ligand
+    identity makes this look tetrahedral even though exchanging those terminal
+    oxygens is resonance-equivalent in the molecular-identity task.
+    """
+    if identity_profile == "lewis_state":
+        return False
+    support = element.support
+    if not hasattr(support, "center"):
+        return False
+    # Degree-one ligands have no remaining environment.  Their transposition
+    # fixes every other atom, and the declared move supplies exactly the
+    # exchanged charge/bond-order drawing in the chemical profile.  The ACS
+    # profile omits those attributes outright.  Isotope remains identity in
+    # both profiles; atom-map labels remain transport handles only.
+    return any(
+        center == support.center
+        and molecule.GetAtomWithIdx(left).GetIsotope()
+        == molecule.GetAtomWithIdx(right).GetIsotope()
+        for center, left, right in _terminal_phosphate_pairs(molecule)
+    )

synkit/Graph/Stereo/reaction_interchange.py

@@ -0,0 +1,266 @@
+"""Loss-accounted interchange for complete reaction-stereo values.
+
+Molecule and reaction line notations do not have fields for executable rule
+guards, stereo changes, branch populations, coupled outcomes, or typed
+refusals.  This module therefore distinguishes lossless sidecar-capable
+formats from endpoint-only carriers and makes every omitted semantic axis a
+stable machine-readable issue.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Any, Mapping
+
+import networkx as nx
+
+from .wire import StereoReactionValue
+
+REACTION_STEREO_INTERCHANGE_SCHEMA = "synkit.reaction-stereo-interchange/1"
+REACTION_STEREO_SIDECAR_KEY = "reaction_stereo_json"
+REACTION_STEREO_DIGEST_KEY = "reaction_stereo_sha256"
+
+_SIDECAR_FORMATS = frozenset({"internal_graph", "gml"})
+_WIRE_FORMATS = frozenset({"canonical_dict", "canonical_json"})
+_ENDPOINT_FORMATS = frozenset({"reaction_smiles", "cxsmiles", "mol_v3000"})
+SUPPORTED_REACTION_STEREO_FORMATS = _SIDECAR_FORMATS | _WIRE_FORMATS | _ENDPOINT_FORMATS
+_AXES = (
+    "guards",
+    "effects",
+    "outcomes",
+    "couplings",
+    "assertions",
+    "refusals",
+)
+
+
+class ReactionStereoInterchangeError(ValueError):
+    """Raised when strict projection would discard reaction semantics."""
+
+    def __init__(self, report: "ReactionStereoInterchangeReport") -> None:
+        self.report = report
+        super().__init__(
+            f"{report.target_format} cannot losslessly encode "
+            f"{', '.join(issue.axis for issue in report.issues)}"
+        )
+
+
+@dataclass(frozen=True)
+class ReactionStereoInterchangeIssue:
+    """One semantic axis not representable in the target carrier."""
+
+    code: str
+    axis: str
+    targets: tuple[str, ...]
+    severity: str = "ERROR"
+    detail: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "code": self.code,
+            "axis": self.axis,
+            "targets": list(self.targets),
+            "severity": self.severity,
+            "detail": self.detail,
+        }
+
+
+@dataclass(frozen=True)
+class ReactionStereoInterchangeReport:
+    """Stable loss/refusal ledger for one projection."""
+
+    target_format: str
+    issues: tuple[ReactionStereoInterchangeIssue, ...] = ()
+    sidecar_available: bool = False
+    schema: str = REACTION_STEREO_INTERCHANGE_SCHEMA
+
+    @property
+    def lossless(self) -> bool:
+        return not self.issues
+
+    @property
+    def status(self) -> str:
+        return "PRESERVED" if self.lossless else "REFUSED"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema": self.schema,
+            "target_format": self.target_format,
+            "status": self.status,
+            "lossless": self.lossless,
+            "sidecar_available": self.sidecar_available,
+            "issues": [issue.to_dict() for issue in self.issues],
+        }
+
+
+def _axis_targets(
+    value: StereoReactionValue,
+) -> tuple[tuple[str, tuple[str, ...]], ...]:
+    return (
+        ("guards", tuple(value.guards)),
+        ("effects", tuple(value.effects)),
+        ("outcomes", tuple(value.outcomes)),
+        ("couplings", tuple(value.couplings)),
+        ("assertions", tuple(value.assertions)),
+        (
+            "refusals",
+            tuple(
+                target
+                for refusal in value.refusals
+                for target in (refusal.targets or ("reaction",))
+            ),
+        ),
+    )
+
+
+def _endpoint_report(
+    value: StereoReactionValue,
+    target_format: str,
+) -> ReactionStereoInterchangeReport:
+    issues = tuple(
+        ReactionStereoInterchangeIssue(
+            "REACTION_AXIS_NOT_REPRESENTABLE",
+            axis,
+            tuple(sorted(set(targets))),
+            detail=(
+                f"{target_format} is an endpoint carrier and has no normative "
+                f"field for reaction-stereo {axis}."
+            ),
+        )
+        for axis, targets in _axis_targets(value)
+        if targets
+    )
+    return ReactionStereoInterchangeReport(
+        target_format,
+        issues,
+        sidecar_available=True,
+    )
+
+
+def project_reaction_stereo(
+    value: StereoReactionValue,
+    target_format: str,
+    *,
+    carrier: Any | None = None,
+    strict: bool = True,
+) -> tuple[Any, ReactionStereoInterchangeReport]:
+    """Project a complete value, preserving it or reporting every lost axis.
+
+    ``carrier`` is the endpoint text/value supplied by the caller for
+    reaction SMILES, CXSMILES, or MOL V3000.  SynKit never claims that such a
+    carrier contains rule semantics merely because the endpoints retain local
+    stereochemical labels.
+    """
+    target_format = target_format.lower()
+    if target_format not in SUPPORTED_REACTION_STEREO_FORMATS:
+        raise ValueError(f"Unsupported reaction-stereo format: {target_format!r}.")
+    if target_format == "canonical_dict":
+        return value.to_dict(), ReactionStereoInterchangeReport(target_format)
+    if target_format == "canonical_json":
+        return (
+            value.normalized_json(),
+            ReactionStereoInterchangeReport(target_format),
+        )
+    if target_format == "internal_graph":
+        if carrier is not None and not isinstance(carrier, nx.Graph):
+            raise TypeError("internal_graph carrier must be a NetworkX graph.")
+        graph = nx.Graph() if carrier is None else nx.Graph(carrier)
+        _attach_sidecar(graph, value)
+        return graph, ReactionStereoInterchangeReport(
+            target_format,
+            sidecar_available=True,
+        )
+    if target_format == "gml":
+        if carrier is not None and not isinstance(carrier, nx.Graph):
+            raise TypeError("gml carrier must be a NetworkX graph.")
+        graph = nx.Graph() if carrier is None else nx.Graph(carrier)
+        _attach_sidecar(graph, value)
+        text = "\n".join(nx.generate_gml(graph))
+        return text, ReactionStereoInterchangeReport(
+            target_format,
+            sidecar_available=True,
+        )
+
+    report = _endpoint_report(value, target_format)
+    if strict and not report.lossless:
+        raise ReactionStereoInterchangeError(report)
+    return carrier, report
+
+
+def _attach_sidecar(graph: nx.Graph, value: StereoReactionValue) -> None:
+    payload = value.normalized_json()
+    graph.graph[REACTION_STEREO_SIDECAR_KEY] = payload
+    graph.graph[REACTION_STEREO_DIGEST_KEY] = sha256(
+        payload.encode("utf-8")
+    ).hexdigest()
+
+
+def _value_from_sidecar(
+    attributes: Mapping[str, Any],
+) -> StereoReactionValue:
+    try:
+        payload = str(attributes[REACTION_STEREO_SIDECAR_KEY])
+        observed = str(attributes[REACTION_STEREO_DIGEST_KEY])
+    except KeyError as error:
+        raise ValueError("Reaction-stereo sidecar or digest is missing.") from error
+    expected = sha256(payload.encode("utf-8")).hexdigest()
+    if observed != expected:
+        raise ValueError("Reaction-stereo sidecar digest mismatch.")
+    return StereoReactionValue.from_json(payload)
+
+
+def reaction_stereo_from_graph(
+    graph: nx.Graph,
+) -> StereoReactionValue:
+    """Read and authenticate a reaction-stereo internal-graph sidecar."""
+    return _value_from_sidecar(graph.graph)
+
+
+def reaction_stereo_from_gml(
+    text: str,
+) -> tuple[nx.Graph, StereoReactionValue]:
+    """Read GML and authenticate its complete reaction-stereo sidecar."""
+    graph = nx.parse_gml(text.splitlines())
+    return graph, _value_from_sidecar(graph.graph)
+
+
+def reaction_stereo_interchange_schema() -> dict[str, Any]:
+    """Return the dependency-free schema for the loss ledger."""
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": REACTION_STEREO_INTERCHANGE_SCHEMA,
+        "type": "object",
+        "additionalProperties": False,
+        "required": [
+            "schema",
+            "target_format",
+            "status",
+            "lossless",
+            "sidecar_available",
+            "issues",
+        ],
+        "properties": {
+            "schema": {"const": REACTION_STEREO_INTERCHANGE_SCHEMA},
+            "target_format": {"enum": sorted(SUPPORTED_REACTION_STEREO_FORMATS)},
+            "status": {"enum": ["PRESERVED", "REFUSED"]},
+            "lossless": {"type": "boolean"},
+            "sidecar_available": {"type": "boolean"},
+            "issues": {"type": "array"},
+        },
+    }
+
+
+__all__ = [
+    "REACTION_STEREO_DIGEST_KEY",
+    "REACTION_STEREO_INTERCHANGE_SCHEMA",
+    "REACTION_STEREO_SIDECAR_KEY",
+    "SUPPORTED_REACTION_STEREO_FORMATS",
+    "ReactionStereoInterchangeError",
+    "ReactionStereoInterchangeIssue",
+    "ReactionStereoInterchangeReport",
+    "project_reaction_stereo",
+    "reaction_stereo_from_gml",
+    "reaction_stereo_from_graph",
+    "reaction_stereo_interchange_schema",
+]