synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Molecule/_helical_loci.py

@@ -0,0 +1,167 @@
+"""Topology-only perception of helicene-like molecular path carriers."""
+
+from __future__ import annotations
+
+import networkx as nx
+from rdkit import Chem
+
+from synkit.Graph.Stereo.supports import PathStereoSupport
+
+
+def _aromatic_six_rings(molecule: Chem.Mol) -> tuple[tuple[int, ...], ...]:
+    return tuple(
+        tuple(ring)
+        for ring in molecule.GetRingInfo().AtomRings()
+        if len(ring) == 6
+        and all(molecule.GetAtomWithIdx(atom).GetIsAromatic() for atom in ring)
+    )
+
+
+def _ring_edge_index(ring: tuple[int, ...], edge: frozenset[int]) -> int:
+    for index, left in enumerate(ring):
+        if frozenset((left, ring[(index + 1) % len(ring)])) == edge:
+            return index
+    raise ValueError("Fused aromatic-ring atoms do not form a ring edge.")
+
+
+def _is_angular_chain(
+    ring_order: tuple[int, ...],
+    rings: tuple[tuple[int, ...], ...],
+    fusion_edges: dict[frozenset[int], frozenset[int]],
+) -> bool:
+    for position, ring_index in enumerate(ring_order[1:-1], start=1):
+        left_edge = fusion_edges[frozenset((ring_order[position - 1], ring_index))]
+        right_edge = fusion_edges[frozenset((ring_index, ring_order[position + 1]))]
+        if left_edge & right_edge:
+            return False
+        ring = rings[ring_index]
+        left_index = _ring_edge_index(ring, left_edge)
+        right_index = _ring_edge_index(ring, right_edge)
+        separation = abs(left_index - right_index)
+        separation = min(separation, len(ring) - separation)
+        if separation != 2:
+            return False
+    return True
+
+
+def _terminal_candidates(
+    molecule_graph: nx.Graph,
+    ring: tuple[int, ...],
+    fusion_edge: frozenset[int],
+) -> tuple[int, int] | None:
+    left, right = tuple(fusion_edge)
+    perimeter = molecule_graph.subgraph(ring).copy()
+    perimeter.remove_edge(left, right)
+    try:
+        free_path = nx.shortest_path(perimeter, left, right)
+    except (nx.NetworkXNoPath, nx.NodeNotFound):
+        return None
+    if len(free_path) != 6:
+        return None
+    return free_path[1], free_path[-2]
+
+
+def _unique_shortest_path(
+    graph: nx.Graph,
+    start: int,
+    end: int,
+) -> tuple[int, ...] | None:
+    try:
+        paths = nx.all_shortest_paths(graph, start, end)
+        first = tuple(next(paths))
+    except (nx.NetworkXNoPath, nx.NodeNotFound):
+        return None
+    try:
+        next(paths)
+    except StopIteration:
+        return first
+    return None
+
+
+def _fusion_topology(
+    molecule: Chem.Mol,
+    rings: tuple[tuple[int, ...], ...],
+) -> tuple[nx.Graph, dict[frozenset[int], frozenset[int]]]:
+    """Build the ring-fusion graph and retain each material fusion edge."""
+    fusion_graph = nx.Graph()
+    fusion_graph.add_nodes_from(range(len(rings)))
+    fusion_edges = {}
+    for left in range(len(rings)):
+        for right in range(left + 1, len(rings)):
+            shared = frozenset(rings[left]) & frozenset(rings[right])
+            if len(shared) != 2:
+                continue
+            first, second = tuple(shared)
+            if molecule.GetBondBetweenAtoms(first, second) is None:
+                continue
+            fusion_graph.add_edge(left, right)
+            fusion_edges[frozenset((left, right))] = shared
+    return fusion_graph, fusion_edges
+
+
+def detect_helicene_supports(
+    molecule: Chem.Mol,
+) -> tuple[PathStereoSupport, ...]:
+    """Return curled, angular, fused-aromatic path carriers.
+
+    A candidate is a chain of at least five edge-fused aromatic six-rings.
+    Every internal fusion must be angular, and the two terminal rings must
+    expose one unique closest pair joined by one unique shortest molecular
+    path. This distinguishes a curled helicene-like topology from linear or
+    ambiguous fused-ring chains without assigning handedness or stability.
+    """
+    if molecule is None:
+        raise ValueError("Helical carrier detection requires a molecule.")
+    rings = _aromatic_six_rings(molecule)
+    if len(rings) < 5:
+        return ()
+    molecular_graph = nx.Graph(
+        (bond.GetBeginAtomIdx(), bond.GetEndAtomIdx()) for bond in molecule.GetBonds()
+    )
+    fusion_graph, fusion_edges = _fusion_topology(molecule, rings)
+
+    supports = set()
+    for component in nx.connected_components(fusion_graph):
+        chain = fusion_graph.subgraph(component)
+        if (
+            len(component) < 5
+            or chain.number_of_edges() != len(component) - 1
+            or any(degree > 2 for _, degree in chain.degree())
+        ):
+            continue
+        terminals = sorted(node for node, degree in chain.degree() if degree == 1)
+        if len(terminals) != 2:
+            continue
+        ring_order = tuple(nx.shortest_path(chain, *terminals))
+        if not _is_angular_chain(ring_order, rings, fusion_edges):
+            continue
+        left_candidates = _terminal_candidates(
+            molecular_graph,
+            rings[ring_order[0]],
+            fusion_edges[frozenset(ring_order[:2])],
+        )
+        right_candidates = _terminal_candidates(
+            molecular_graph,
+            rings[ring_order[-1]],
+            fusion_edges[frozenset(ring_order[-2:])],
+        )
+        if left_candidates is None or right_candidates is None:
+            continue
+        distances = {
+            (left, right): nx.shortest_path_length(molecular_graph, left, right)
+            for left in left_candidates
+            for right in right_candidates
+        }
+        minimum = min(distances.values())
+        closest = [pair for pair, distance in distances.items() if distance == minimum]
+        if len(closest) != 1:
+            continue
+        path = _unique_shortest_path(molecular_graph, *closest[0])
+        if path is None or len(path) < len(component) + 1:
+            continue
+        canonical_path = min(path, tuple(reversed(path)))
+        supports.add(PathStereoSupport(canonical_path))
+    return tuple(sorted(supports, key=lambda support: support.path))
+
+
+__all__ = ["detect_helicene_supports"]

synkit/Chem/Molecule/_stereo_axis_evidence.py

@@ -0,0 +1,202 @@
+"""Exact constitutional evidence for broad molecular stereo-axis candidates."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+import networkx as nx
+from networkx.algorithms.isomorphism import (
+    GraphMatcher,
+    categorical_edge_match,
+    categorical_node_match,
+)
+from rdkit import Chem
+
+from synkit.Graph.Stereo.descriptors import Reference, virtual_reference
+from synkit.Graph.Stereo.supports import AxisStereoSupport
+
+
+class StereoCarrierStatus(str, Enum):
+    """Constitutional conclusion for a perceived carrier.
+
+    ``CONFIRMED`` means only that the represented constitution has
+    distinguishable carrier references. It is not a configurational-stability
+    claim. ``SYMMETRY_RELATED`` retains a broad topology candidate while
+    recording why it must not be promoted to a confirmed stereo carrier.
+    """
+
+    CONFIRMED = "confirmed"
+    SYMMETRY_RELATED = "symmetry_related"
+
+
+def validated_carrier_status(
+    value: StereoCarrierStatus | str,
+    reason: str | None,
+) -> StereoCarrierStatus:
+    """Normalize a carrier status and enforce its diagnostic invariant."""
+    status = StereoCarrierStatus(value)
+    if status is StereoCarrierStatus.SYMMETRY_RELATED and not reason:
+        raise ValueError(
+            "Symmetry-related stereo carriers require a diagnostic reason."
+        )
+    return status
+
+
+_NODE_ATTRIBUTES = (
+    "atomic_number",
+    "isotope",
+    "formal_charge",
+    "radical_electrons",
+    "hcount",
+    "aromatic",
+    "stereo_anchor",
+    "stereo_marker",
+    "axis_anchor",
+    "ligand_probe",
+)
+_EDGE_ATTRIBUTES = ("bond_type", "aromatic")
+_NODE_DEFAULTS = (0, 0, 0, 0, 0, False, False, None, None, False)
+_EDGE_DEFAULTS = ("", False)
+
+
+def _refinement_fingerprint(graph: nx.Graph) -> str:
+    """Return an isomorphism-invariant rejection fingerprint.
+
+    Unequal Weisfeiler-Lehman fingerprints prove that the rooted attributed
+    graphs cannot be isomorphic. Equal fingerprints remain inconclusive and
+    therefore continue to the exact VF2 witness check.
+    """
+    node_label = "_synkit_symmetry_node_label"
+    edge_label = "_synkit_symmetry_edge_label"
+    for _node, attributes in graph.nodes(data=True):
+        attributes[node_label] = repr(
+            tuple(
+                attributes.get(name, default)
+                for name, default in zip(_NODE_ATTRIBUTES, _NODE_DEFAULTS)
+            )
+        )
+    for _left, _right, attributes in graph.edges(data=True):
+        attributes[edge_label] = repr(
+            tuple(
+                attributes.get(name, default)
+                for name, default in zip(_EDGE_ATTRIBUTES, _EDGE_DEFAULTS)
+            )
+        )
+    return nx.weisfeiler_lehman_graph_hash(
+        graph,
+        node_attr=node_label,
+        edge_attr=edge_label,
+        iterations=max(1, graph.number_of_nodes()),
+    )
+
+
+def cumulene_terminal_references(
+    molecule: Chem.Mol,
+    owner: int,
+    path_neighbor: int,
+) -> tuple[Reference, Reference] | None:
+    """Return two represented references at one cumulene endpoint."""
+    atom = molecule.GetAtomWithIdx(owner)
+    references: list[Reference] = [
+        neighbor.GetIdx()
+        for neighbor in atom.GetNeighbors()
+        if neighbor.GetIdx() != path_neighbor
+    ]
+    hidden_hydrogens = int(atom.GetNumExplicitHs()) + int(atom.GetNumImplicitHs())
+    references.extend(virtual_reference("H", owner) for _ in range(hidden_hydrogens))
+    if len(references) == 1 and atom.GetAtomicNum() == 15:
+        references.append(virtual_reference("LP", owner))
+    if len(references) != 2 or references[0] == references[1]:
+        return None
+    return references[0], references[1]
+
+
+def _axis_fixed_reference_symmetry_witness(
+    graph: nx.Graph,
+    support: AxisStereoSupport,
+    left: Reference,
+    right: Reference,
+) -> tuple[tuple[int, int], ...] | None:
+    """Return an exact terminal-reference automorphism witness, if one exists."""
+    if type(left) is not int or type(right) is not int:
+        return None
+    left_rooted = graph.copy()
+    right_rooted = graph.copy()
+    for rooted, probe in ((left_rooted, left), (right_rooted, right)):
+        nx.set_node_attributes(rooted, None, "axis_anchor")
+        nx.set_node_attributes(rooted, False, "ligand_probe")
+        for position, atom in enumerate(support.path):
+            rooted.nodes[atom]["axis_anchor"] = position
+        rooted.nodes[probe]["ligand_probe"] = True
+    if _refinement_fingerprint(left_rooted) != _refinement_fingerprint(right_rooted):
+        return None
+    matcher = GraphMatcher(
+        left_rooted,
+        right_rooted,
+        node_match=categorical_node_match(
+            _NODE_ATTRIBUTES,
+            _NODE_DEFAULTS,
+        ),
+        edge_match=categorical_edge_match(
+            _EDGE_ATTRIBUTES,
+            _EDGE_DEFAULTS,
+        ),
+    )
+    mapping = next(matcher.isomorphisms_iter(), None)
+    if mapping is None:
+        return None
+    return tuple(
+        sorted((int(source), int(target)) for source, target in mapping.items())
+    )
+
+
+def axis_terminal_symmetry_witnesses(
+    graph: nx.Graph,
+    support: AxisStereoSupport,
+) -> tuple[tuple[tuple[int, int], ...] | None, ...]:
+    """Return one exact symmetry witness for each terminal reference pair.
+
+    Axis atoms are fixed in path order and one terminal ligand probe is mapped
+    to the other. A non-``None`` witness proves terminal-reference equivalence
+    under that constitutional stabilizer. The same map can exchange the other
+    terminal pair as well, preserving a configured axial orientation. These
+    witnesses alone do not decide whole-configuration mirror equivalence or
+    rotational barriers.
+    """
+    return tuple(
+        _axis_fixed_reference_symmetry_witness(
+            graph,
+            support,
+            frame[0],
+            frame[1],
+        )
+        for frame in support.terminal_frames
+    )
+
+
+def axis_carrier_status(
+    graph: nx.Graph,
+    element_type: str,
+    support: AxisStereoSupport,
+) -> tuple[StereoCarrierStatus, str | None]:
+    """Return exact terminal-symmetry evidence for a broad axis candidate."""
+    if any(
+        witness is not None
+        for witness in axis_terminal_symmetry_witnesses(graph, support)
+    ):
+        reason = (
+            "symmetry_related_terminal_paths"
+            if element_type == "atrop_axis"
+            else "duplicate_terminal_ligands"
+        )
+        return StereoCarrierStatus.SYMMETRY_RELATED, reason
+    return StereoCarrierStatus.CONFIRMED, None
+
+
+__all__ = [
+    "StereoCarrierStatus",
+    "axis_carrier_status",
+    "axis_terminal_symmetry_witnesses",
+    "cumulene_terminal_references",
+    "validated_carrier_status",
+]

synkit/Chem/Molecule/_stereo_element_detection.py

@@ -0,0 +1,193 @@
+"""Internal non-tetrahedral stereo-element detection helpers."""
+
+from __future__ import annotations
+
+import networkx as nx
+from rdkit import Chem
+
+from synkit.Graph.Stereo.supports import (
+    AxisStereoSupport,
+    BondStereoSupport,
+    PathStereoSupport,
+)
+
+from ._helical_loci import detect_helicene_supports
+from ._stereo_axis_evidence import (
+    StereoCarrierStatus,
+    axis_carrier_status,
+    cumulene_terminal_references,
+)
+from .stereo_perception import (
+    PotentialStereoElement,
+    StereoConfigurationState,
+    StereoElementType,
+    _configuration_state,
+    _constitutional_graph,
+    _cumulated_double_bonds,
+)
+
+
+def rdkit_double_bond_elements(
+    molecule: Chem.Mol,
+) -> tuple[PotentialStereoElement, ...]:
+    """Project and complete double-bond perception as typed support evidence."""
+    cumulated_bonds = _cumulated_double_bonds(molecule)
+    elements = []
+    perceived_bonds = set()
+    for info in Chem.FindPotentialStereo(molecule):
+        centered_on = int(info.centeredOn)
+        if info.type != Chem.StereoType.Bond_Double:
+            continue
+        if centered_on in cumulated_bonds:
+            continue
+        perceived_bonds.add(centered_on)
+        bond = molecule.GetBondWithIdx(centered_on)
+        elements.append(
+            PotentialStereoElement(
+                StereoElementType.DOUBLE_BOND,
+                BondStereoSupport(
+                    bond.GetBeginAtomIdx(),
+                    bond.GetEndAtomIdx(),
+                ),
+                _configuration_state(info),
+                "rdkit_find_potential_stereo",
+                f"Bond_Double:{centered_on}",
+            )
+        )
+    for bond in molecule.GetBonds():
+        bond_index = bond.GetIdx()
+        if (
+            bond.GetBondType() != Chem.BondType.DOUBLE
+            or bond_index in cumulated_bonds
+            or bond_index in perceived_bonds
+        ):
+            continue
+        left, right = bond.GetBeginAtomIdx(), bond.GetEndAtomIdx()
+        left_refs = cumulene_terminal_references(molecule, left, right)
+        right_refs = cumulene_terminal_references(molecule, right, left)
+        if left_refs is None or right_refs is None:
+            continue
+        if not any(
+            type(reference) is int
+            and molecule.GetAtomWithIdx(reference).GetIsotope() != 0
+            for frame in (left_refs, right_refs)
+            for reference in frame
+        ):
+            continue
+        support = AxisStereoSupport((left, right), (left_refs, right_refs))
+        status, _reason = axis_carrier_status(
+            _constitutional_graph(molecule, left),
+            StereoElementType.DOUBLE_BOND.value,
+            support,
+        )
+        if status is not StereoCarrierStatus.CONFIRMED:
+            continue
+        elements.append(
+            PotentialStereoElement(
+                StereoElementType.DOUBLE_BOND,
+                BondStereoSupport(left, right),
+                StereoConfigurationState.UNSPECIFIED,
+                "synkit_double_bond_exact_terminal_symmetry",
+                f"Bond_Double:{bond_index}",
+            )
+        )
+    return tuple(elements)
+
+
+def extended_cis_trans_elements(
+    molecule: Chem.Mol,
+) -> tuple[PotentialStereoElement, ...]:
+    """Detect odd-bond extended cumulene E/Z supports without inventing state."""
+    double_graph = nx.Graph()
+    double_graph.add_edges_from(
+        (bond.GetBeginAtomIdx(), bond.GetEndAtomIdx())
+        for bond in molecule.GetBonds()
+        if bond.GetBondType() == Chem.BondType.DOUBLE
+    )
+    elements = []
+    for component in nx.connected_components(double_graph):
+        path_graph = double_graph.subgraph(component)
+        edge_count = path_graph.number_of_edges()
+        if edge_count < 3 or edge_count % 2 != 1:
+            continue
+        if edge_count != path_graph.number_of_nodes() - 1:
+            continue
+        if any(degree > 2 for _, degree in path_graph.degree()):
+            continue
+        ends = sorted(node for node, degree in path_graph.degree() if degree == 1)
+        if len(ends) != 2:
+            continue
+        path = tuple(nx.shortest_path(path_graph, ends[0], ends[1]))
+        if any(molecule.GetAtomWithIdx(node).GetDegree() != 2 for node in path[1:-1]):
+            continue
+        left = cumulene_terminal_references(molecule, path[0], path[1])
+        right = cumulene_terminal_references(molecule, path[-1], path[-2])
+        if left is None or right is None:
+            continue
+        support = AxisStereoSupport(path, (left, right))
+        carrier_status, carrier_reason = axis_carrier_status(
+            _constitutional_graph(molecule, support.path[0]),
+            StereoElementType.EXTENDED_CIS_TRANS.value,
+            support,
+        )
+        elements.append(
+            PotentialStereoElement(
+                StereoElementType.EXTENDED_CIS_TRANS,
+                support,
+                StereoConfigurationState.UNSPECIFIED,
+                "synkit_odd_cumulene_path_perception",
+                "Extended_CisTrans:" + "-".join(str(atom) for atom in path),
+                carrier_status=carrier_status,
+                carrier_reason=carrier_reason,
+            )
+        )
+    return tuple(elements)
+
+
+def axis_elements(
+    molecule: Chem.Mol,
+    *,
+    include_extended_ring_axes: bool,
+) -> tuple[PotentialStereoElement, ...]:
+    """Adapt the conservative axial-locus detector to typed elements."""
+    from .chirality import detect_potential_stereo_loci
+
+    elements = []
+    for locus in detect_potential_stereo_loci(
+        molecule,
+        include_extended_ring_axes=include_extended_ring_axes,
+    ):
+        element_type = StereoElementType(locus.locus_type.value)
+        carrier_status, carrier_reason = axis_carrier_status(
+            _constitutional_graph(molecule, locus.support.path[0]),
+            element_type.value,
+            locus.support,
+        )
+        elements.append(
+            PotentialStereoElement(
+                element_type,
+                locus.support,
+                StereoConfigurationState.UNSPECIFIED,
+                locus.evidence_provenance,
+                locus.identifier,
+                carrier_status=carrier_status,
+                carrier_reason=carrier_reason,
+            )
+        )
+    return tuple(elements)
+
+
+def helical_elements(
+    molecule: Chem.Mol,
+) -> tuple[PotentialStereoElement, ...]:
+    """Return helicene-like path carriers without orientation claims."""
+    return tuple(
+        PotentialStereoElement(
+            StereoElementType.HELICAL,
+            PathStereoSupport(support.path, support.cyclic),
+            StereoConfigurationState.UNSPECIFIED,
+            "synkit_angular_fused_aromatic_helicene_topology",
+            "Helical:" + "-".join(str(atom) for atom in support.path),
+        )
+        for support in detect_helicene_supports(molecule)
+    )