synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/validation/orbits.py

@@ -0,0 +1,137 @@
+"""Exact bond-label orbits via point-stabilizer transversals.
+
+Only the action on vertices supporting the label is needed. For a base
+b_1,...,b_k of those vertices let H_j fix its first j points. One witnessed
+transversal T_j for H_{j-1}/H_j gives G = T_1 ... T_k H_k. Since H_k fixes the
+label, its orbit is obtained by applying T_k,...,T_1 and deduplicating images.
+Thus irrelevant spectator permutations need never be listed. This uses
+standard group decomposition, not a new graph-isomorphism algorithm.
+"""
+
+import math
+from time import monotonic
+
+import networkx as nx
+
+from .bonds import ExactBondEvaluator, IncompleteSymmetry, ScoreWitness, _graph, bond_f1, transport_bonds
+
+
+class SupportOrbitEvaluator(ExactBondEvaluator):
+    """Exact quotient scorer without explicit enumeration of the entire group.
+
+    Every transporter is a full attributed-graph automorphism. Failure to
+    complete any orbit query raises; no partial group is reported as exact.
+    Deadlines are cooperative around isomorphism calls and need an external
+    process deadline for a hard wall-clock guarantee.
+    """
+
+    def __init__(self, reactant, *, max_label_images=100000, time_limit_seconds=30):
+        if (not isinstance(max_label_images, int) or max_label_images < 1
+                or not math.isfinite(time_limit_seconds) or time_limit_seconds <= 0):
+            raise ValueError("Require positive finite time and label-image limits")
+        self.n = len(reactant.atomic_numbers)
+        self.graph = _graph(reactant)
+        self.identity = tuple(range(self.n))
+        self.deadline = monotonic() + time_limit_seconds
+        self.max_label_images = max_label_images
+        self._orbits = {}
+        self._transversals = {}
+        self.isomorphism_calls = 0
+        self.colors = self._refine_colors()
+
+    def _check(self):
+        if monotonic() > self.deadline:
+            raise IncompleteSymmetry("Label-orbit deadline exceeded")
+
+    def _refine_colors(self):
+        def number(signatures):
+            numbers = {value: i for i, value in enumerate(sorted(set(signatures)))}
+            return tuple(numbers[x] for x in signatures)
+        colors = number([self.graph.nodes[i]["color"] for i in range(self.n)])
+        for _ in range(self.n):
+            self._check()
+            refined = number([(colors[i], tuple(sorted(
+                (self.graph.edges[i, j]["order"], colors[j]) for j in self.graph[i])))
+                              for i in range(self.n)])
+            if len(set(refined)) == len(set(colors)):
+                return refined
+            colors = refined
+        return colors
+
+    def _extension(self, fixed, source, target):
+        self._check()
+        if source == target:
+            return self.identity
+        left, right = self.graph.copy(), self.graph.copy()
+        for i in range(self.n):
+            left.nodes[i]["constraint"] = (self.colors[i], -1)
+            right.nodes[i]["constraint"] = (self.colors[i], -1)
+        for i in fixed:
+            left.nodes[i]["constraint"] = right.nodes[i]["constraint"] = (self.colors[i], i)
+        left.nodes[source]["constraint"] = (self.colors[source], source)
+        right.nodes[target]["constraint"] = (self.colors[target], source)
+        matcher = nx.algorithms.isomorphism.GraphMatcher(
+            left, right,
+            node_match=nx.algorithms.isomorphism.categorical_node_match("constraint", None),
+            edge_match=nx.algorithms.isomorphism.categorical_edge_match("order", None),
+        )
+        self.isomorphism_calls += 1
+        mapping = next(matcher.isomorphisms_iter(), None)
+        self._check()
+        if mapping is None:
+            return None
+        return tuple(mapping[i] for i in range(self.n))
+
+    def _transversal(self, fixed, source):
+        key = (fixed, source)
+        if key not in self._transversals:
+            values = []
+            for target in range(self.n):
+                if target in fixed or self.colors[target] != self.colors[source]:
+                    continue
+                witness = self._extension(fixed, source, target)
+                if witness is not None:
+                    values.append(witness)
+            self._transversals[key] = tuple(values)
+        return self._transversals[key]
+
+    def orbit(self, label):
+        """Return each distinct image with a verified full-graph transporter."""
+        self._check()
+        label = self._validate(label)
+        if label not in self._orbits:
+            base = self._support(label)
+            levels = [self._transversal(base[:j], source) for j, source in enumerate(base)]
+            images = {label: self.identity}
+            for transversal in reversed(levels):
+                next_images = {}
+                for t in transversal:
+                    for current, witness in images.items():
+                        self._check()
+                        image = self._transport(current, t)
+                        if image not in next_images:
+                            next_images[image] = tuple(t[witness[i]] for i in range(self.n))
+                            if len(next_images) > self.max_label_images:
+                                raise IncompleteSymmetry("Label-image cap exceeded")
+                images = next_images
+            self._orbits[label] = images
+        return self._orbits[label]
+
+    def _support(self, label):
+        return tuple(sorted({i for pair in label for i in pair}))
+
+    def _transport(self, label, permutation):
+        return transport_bonds(label, permutation)
+
+    def score(self, prediction, label):
+        prediction = self._validate(prediction)
+        best = None
+        for image, witness in self.orbit(label).items():
+            self._check()
+            score = bond_f1(prediction, image)
+            if best is None or score > best.score:
+                best = ScoreWitness(score, witness)
+        return best
+
+    def orbit_key(self, label):
+        return min(tuple(sorted(image)) for image in self.orbit(label))

synkit/Chem/Molecule/_chirality_loci.py

@@ -0,0 +1,165 @@
+"""Topology-only detection of potential molecular stereo axes."""
+
+from __future__ import annotations
+
+import networkx as nx
+from rdkit import Chem
+
+from synkit.Graph.Stereo.descriptors import Reference, virtual_reference
+from synkit.Graph.Stereo.supports import AxisStereoSupport
+
+
+def _cumulene_end_references(
+    atom: Chem.Atom,
+    axis_neighbor: int,
+) -> tuple[Reference, Reference] | None:
+    """Return zero-based terminal references for one cumulene end."""
+    center = atom.GetIdx()
+    references: list[Reference] = [
+        neighbor.GetIdx()
+        for neighbor in atom.GetNeighbors()
+        if neighbor.GetIdx() != axis_neighbor
+    ]
+    hidden_hydrogens = int(atom.GetNumExplicitHs()) + int(atom.GetNumImplicitHs())
+    references.extend(virtual_reference("H", center) for _ in range(hidden_hydrogens))
+    if len(references) == 1 and atom.GetAtomicNum() == 15:
+        references.append(virtual_reference("LP", center))
+    if len(references) != 2 or references[0] == references[1]:
+        return None
+    return references[0], references[1]
+
+
+def _potential_cumulene_supports(
+    molecule: Chem.Mol,
+) -> tuple[AxisStereoSupport, ...]:
+    """Detect even-cumulene axes without assigning their orientation."""
+    double_graph = nx.Graph()
+    double_graph.add_edges_from(
+        (bond.GetBeginAtomIdx(), bond.GetEndAtomIdx())
+        for bond in molecule.GetBonds()
+        if bond.GetBondType() == Chem.BondType.DOUBLE
+    )
+    supports = []
+    for component in nx.connected_components(double_graph):
+        axis = double_graph.subgraph(component)
+        edge_count = axis.number_of_edges()
+        if edge_count < 2 or edge_count % 2 != 0:
+            continue
+        if edge_count != axis.number_of_nodes() - 1:
+            continue
+        degrees = dict(axis.degree())
+        if any(degree > 2 for degree in degrees.values()):
+            continue
+        ends = sorted(node for node, degree in degrees.items() if degree == 1)
+        if len(ends) != 2:
+            continue
+        path = nx.shortest_path(axis, ends[0], ends[1])
+        if any(molecule.GetAtomWithIdx(node).GetDegree() != 2 for node in path[1:-1]):
+            continue
+        left_refs = _cumulene_end_references(
+            molecule.GetAtomWithIdx(path[0]),
+            path[1],
+        )
+        right_refs = _cumulene_end_references(
+            molecule.GetAtomWithIdx(path[-1]),
+            path[-2],
+        )
+        if left_refs is None or right_refs is None:
+            continue
+        supports.append(AxisStereoSupport(tuple(path), (left_refs, right_refs)))
+    return tuple(supports)
+
+
+def _potential_biaryl_supports(
+    molecule: Chem.Mol,
+    *,
+    include_extended_ring_axes: bool,
+) -> tuple[AxisStereoSupport, ...]:
+    """Detect ring-associated bond axes without orientation or barrier claims."""
+    supports = []
+    for bond in molecule.GetBonds():
+        if bond.GetBondType() not in {
+            Chem.BondType.SINGLE,
+            Chem.BondType.AROMATIC,
+        }:
+            continue
+        left_atom = bond.GetBeginAtom()
+        right_atom = bond.GetEndAtom()
+        hybridizations = {
+            left_atom.GetHybridization(),
+            right_atom.GetHybridization(),
+        }
+        containing_ring_sizes = tuple(
+            len(ring)
+            for ring in molecule.GetRingInfo().BondRings()
+            if bond.GetIdx() in ring
+        )
+        aromatic_ring_axis = (
+            bond.GetIsAromatic()
+            and left_atom.GetIsAromatic()
+            and right_atom.GetIsAromatic()
+            and any(size > 6 for size in containing_ring_sizes)
+        )
+        linked_ring_axis = (
+            not bond.GetIsAromatic()
+            and (left_atom.IsInRing() or right_atom.IsInRing())
+            and Chem.HybridizationType.SP2 in hybridizations
+            and hybridizations
+            <= {
+                Chem.HybridizationType.SP2,
+                Chem.HybridizationType.SP3,
+            }
+        )
+        standard_biaryl_axis = (
+            not bond.GetIsAromatic()
+            and left_atom.GetIsAromatic()
+            and right_atom.GetIsAromatic()
+        )
+        if not standard_biaryl_axis and not (
+            include_extended_ring_axes and (aromatic_ring_axis or linked_ring_axis)
+        ):
+            continue
+        left, right = left_atom.GetIdx(), right_atom.GetIdx()
+        left_refs = tuple(
+            neighbor.GetIdx()
+            for neighbor in left_atom.GetNeighbors()
+            if neighbor.GetIdx() != right_atom.GetIdx()
+        )
+        right_refs = tuple(
+            neighbor.GetIdx()
+            for neighbor in right_atom.GetNeighbors()
+            if neighbor.GetIdx() != left_atom.GetIdx()
+        )
+        if len(left_refs) != 2 or len(right_refs) != 2:
+            continue
+        supports.append(
+            AxisStereoSupport(
+                (left, right),
+                (left_refs, right_refs),
+            )
+        )
+    return tuple(supports)
+
+
+def detect_potential_axis_supports(
+    molecule: Chem.Mol,
+    *,
+    include_extended_ring_axes: bool = False,
+) -> tuple[tuple[str, AxisStereoSupport], ...]:
+    """Return typed topology supports for potential molecular stereo axes."""
+    if molecule is None:
+        raise ValueError("Potential stereo-locus detection requires a molecule.")
+    working = Chem.Mol(molecule)
+    return (
+        *(
+            ("cumulene_axis", support)
+            for support in _potential_cumulene_supports(working)
+        ),
+        *(
+            ("atrop_axis", support)
+            for support in _potential_biaryl_supports(
+                working,
+                include_extended_ring_axes=include_extended_ring_axes,
+            )
+        ),
+    )

synkit/Chem/Molecule/_chirality_types.py

@@ -0,0 +1,231 @@
+"""Data models and topology-colour helpers for molecular chirality."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Mapping
+
+from synkit.Graph.Stereo.descriptors import Reference
+from synkit.Graph.Stereo.supports import AxisStereoSupport
+
+
+class MolecularChirality(str, Enum):
+    """Global relationship between a molecule and its mirror image."""
+
+    ACHIRAL = "Achiral"
+    CHIRAL = "Chiral"
+
+
+class MolecularChiralityOutcome(str, Enum):
+    """Configuration-aware conclusion for possibly underspecified input."""
+
+    NECESSARILY_ACHIRAL = "necessarily_achiral"
+    NECESSARILY_CHIRAL = "necessarily_chiral"
+    CONFIGURATION_DEPENDENT = "configuration_dependent"
+    UNSUPPORTED_OR_INCOMPLETE = "unsupported_or_incomplete"
+
+
+class PotentialStereoLocusType(str, Enum):
+    """Topology-supported stereo locus whose configuration is not supplied."""
+
+    CUMULENE_AXIS = "cumulene_axis"
+    ATROP_AXIS = "atrop_axis"
+
+
+class StereoOrientationState(str, Enum):
+    """Information state of a potential stereo locus."""
+
+    UNSPECIFIED = "unspecified"
+
+
+class StereoStabilityStatus(str, Enum):
+    """Configurational-stability evidence attached to a potential locus."""
+
+    UNASSESSED = "unassessed"
+
+
+class UnspecifiedMolecularStereoError(ValueError):
+    """Raised when strict binary classification receives unresolved stereo."""
+
+    def __init__(self, loci: tuple[str, ...]) -> None:
+        self.loci = loci
+        joined = ", ".join(loci)
+        super().__init__(f"Molecular stereochemistry is underspecified at: {joined}")
+
+
+@dataclass(frozen=True)
+class MolecularChiralityResult:
+    """Evidence returned by whole-molecule mirror classification."""
+
+    classification: MolecularChirality
+    mirror_isomorphism: tuple[tuple[int, int], ...] | None
+    descriptor_count: int
+    completed_tetrahedral_centers: tuple[int, ...]
+    # Compatibility fields retained for readers of the exploratory report.
+    # Sound classification never populates them from 2D connectivity alone.
+    completed_extended_tetrahedral_axes: tuple[tuple[int, int], ...] = ()
+    completed_biaryl_atrop_axes: tuple[tuple[int, int], ...] = ()
+    identity_profile: str = "element-isotope-hydrogen-connectivity"
+    decision_method: str = "exact_mirror_isomorphism"
+    input_stereo_status: str = "specified"
+    unspecified_stereo_loci: tuple[str, ...] = ()
+    potential_stereo_loci: tuple["PotentialStereoLocus", ...] = ()
+    configured_extended_descriptor_count: int = 0
+    stereo_evidence_source: str | None = None
+    extended_stability_status: str | None = None
+    population_fraction: float | None = None
+
+    @property
+    def is_chiral(self) -> bool:
+        """Return ``True`` when no orientation-preserving mirror map exists."""
+        return self.classification is MolecularChirality.CHIRAL
+
+
+@dataclass(frozen=True, init=False)
+class PotentialStereoLocus:
+    """A typed candidate locus without an invented configuration.
+
+    Atom indices and material terminal references are zero-based RDKit atom
+    indices. Virtual hydrogen references use ``@H:<owner-index>``. Detection
+    from 2D connectivity proves only that the topology can support the locus;
+    it supplies neither handedness nor configurational-stability evidence.
+    """
+
+    locus_type: PotentialStereoLocusType
+    support: AxisStereoSupport
+    orientation_state: StereoOrientationState = StereoOrientationState.UNSPECIFIED
+    evidence_provenance: str = "two_dimensional_connectivity"
+    stability_status: StereoStabilityStatus = StereoStabilityStatus.UNASSESSED
+
+    def __init__(
+        self,
+        locus_type: PotentialStereoLocusType,
+        atom_indices: tuple[int, ...] | None = None,
+        terminal_references: tuple[tuple[Reference, ...], ...] | None = None,
+        orientation_state: StereoOrientationState = StereoOrientationState.UNSPECIFIED,
+        evidence_provenance: str = "two_dimensional_connectivity",
+        stability_status: StereoStabilityStatus = StereoStabilityStatus.UNASSESSED,
+        *,
+        support: AxisStereoSupport | None = None,
+    ) -> None:
+        """Build from typed support or the compatible legacy field pair."""
+        if support is None:
+            if atom_indices is None or terminal_references is None:
+                raise TypeError(
+                    "Potential stereo loci require axis support or both legacy "
+                    "atom_indices and terminal_references."
+                )
+            support = AxisStereoSupport(
+                tuple(atom_indices),
+                tuple(tuple(frame) for frame in terminal_references),  # type: ignore[arg-type]
+            )
+        elif atom_indices is not None or terminal_references is not None:
+            raise TypeError("Supply typed support or legacy support fields, not both.")
+        object.__setattr__(self, "locus_type", PotentialStereoLocusType(locus_type))
+        object.__setattr__(self, "support", support)
+        object.__setattr__(
+            self, "orientation_state", StereoOrientationState(orientation_state)
+        )
+        object.__setattr__(self, "evidence_provenance", evidence_provenance)
+        object.__setattr__(
+            self, "stability_status", StereoStabilityStatus(stability_status)
+        )
+
+    @property
+    def atom_indices(self) -> tuple[int, ...]:
+        """Return the compatible axis-path view."""
+        return self.support.path
+
+    @property
+    def terminal_references(self) -> tuple[tuple[Reference, Reference], ...]:
+        """Return the compatible terminal-frame view."""
+        return self.support.terminal_frames
+
+    @property
+    def identifier(self) -> str:
+        """Return a deterministic diagnostic identifier."""
+        support = "-".join(str(index) for index in self.atom_indices)
+        return f"{self.locus_type.value}:{support}"
+
+
+@dataclass(frozen=True)
+class MolecularChiralityAssessment:
+    """Configuration-aware result over every enumerated stereo completion."""
+
+    outcome: MolecularChiralityOutcome
+    observed_classifications: tuple[MolecularChirality, ...]
+    input_stereo_status: str
+    unspecified_stereo_loci: tuple[str, ...]
+    unsupported_stereo_loci: tuple[str, ...]
+    theoretical_isomer_upper_bound: int
+    evaluated_isomer_count: int
+    enumeration_complete: bool
+    max_isomers: int
+    representative_isomers: tuple[tuple[str, MolecularChirality], ...] = ()
+    configured_alternative_count: int = 0
+    configured_population_status: str | None = None
+    decision_method: str = "stereo_completion_enumeration"
+
+    @property
+    def is_definitive(self) -> bool:
+        """Return whether the outcome is proven despite possible truncation."""
+        return self.outcome is not MolecularChiralityOutcome.UNSUPPORTED_OR_INCOMPLETE
+
+
+def molecular_node_match(
+    left: Mapping[str, Any],
+    right: Mapping[str, Any],
+) -> bool:
+    """Match StereoMolGraph's explicit-H topology without expanding H atoms."""
+    return (
+        left.get("element") == right.get("element")
+        and int(left.get("isotope", 0)) == int(right.get("isotope", 0))
+        and int(left.get("hcount", 0)) == int(right.get("hcount", 0))
+        and left.get("_molecular_colour") == right.get("_molecular_colour")
+    )
+
+
+def connectivity_edge_match(
+    _left: Mapping[str, Any],
+    _right: Mapping[str, Any],
+) -> bool:
+    """Use connectivity, not one selected Lewis/resonance bond assignment."""
+    return True
+
+
+def _intern_colours(signatures: Mapping[int, Any]) -> dict[int, int]:
+    """Intern comparable signatures into deterministic compact integers."""
+    palette = {
+        signature: index
+        for index, signature in enumerate(sorted(set(signatures.values()), key=repr))
+    }
+    return {node: palette[signature] for node, signature in signatures.items()}
+
+
+def molecular_node_colours(graph: Any) -> dict[int, int]:
+    """Return map-independent 1-WL molecular identity colours."""
+    colours = _intern_colours(
+        {
+            node: (
+                attributes.get("element"),
+                int(attributes.get("isotope", 0)),
+                int(attributes.get("hcount", 0)),
+            )
+            for node, attributes in graph.nodes(data=True)
+        }
+    )
+    for _iteration in range(max(1, len(graph))):
+        refined = _intern_colours(
+            {
+                node: (
+                    colours[node],
+                    tuple(sorted(colours[neighbor] for neighbor in graph[node])),
+                )
+                for node in graph
+            }
+        )
+        if refined == colours:
+            break
+        colours = refined
+    return colours