synkit 1.6.5__py3-none-win_amd64.whl

synkit/Vis/epd/layout.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+"""RDKit-driven coordinate generation and shared-frame alignment."""
+
+from typing import Dict, Sequence, Tuple
+
+import networkx as nx
+import numpy as np
+from rdkit import Chem
+from rdkit.Chem import rdDepictor
+
+from .chem import edge_order
+from .mapping import amap_to_node
+from .utils import normalize_scalar_attr
+
+
+def edge_to_rdkit_bond_type(edata: Dict[str, object]) -> Chem.BondType:
+    """Map graph edge annotations to an RDKit bond type."""
+    order = edge_order(edata)
+    bond_type = edata.get("bond_type")
+
+    if bond_type == "AROMATIC" or order == 1.5:
+        return Chem.BondType.AROMATIC
+    if bond_type == "TRIPLE" or (order is not None and order >= 2.9):
+        return Chem.BondType.TRIPLE
+    if bond_type == "DOUBLE" or (order is not None and order >= 1.9):
+        return Chem.BondType.DOUBLE
+    return Chem.BondType.SINGLE
+
+
+def _build_rdkit_atom(
+    node: int,
+    data: Dict[str, object],
+    atom_map_key: str,
+) -> Chem.Atom:
+    """Create one RDKit atom from graph node data."""
+    elem = str(normalize_scalar_attr(data.get("element", "C"), "C"))
+    charge = int(normalize_scalar_attr(data.get("charge", 0), 0))
+    aromatic = bool(normalize_scalar_attr(data.get("aromatic", False), False))
+    atom_map = int(normalize_scalar_attr(data.get(atom_map_key, node), node))
+
+    atom = Chem.Atom(elem)
+    atom.SetFormalCharge(charge)
+    atom.SetAtomMapNum(atom_map)
+    if aromatic:
+        atom.SetIsAromatic(True)
+    return atom
+
+
+def _add_rdkit_bond(
+    rw: Chem.RWMol,
+    node_to_idx: Dict[int, int],
+    u: int,
+    v: int,
+    edata: Dict[str, object],
+) -> None:
+    """Add one RDKit bond from graph edge data."""
+    bond_type = edge_to_rdkit_bond_type(edata)
+    rw.AddBond(node_to_idx[u], node_to_idx[v], bond_type)
+    bond = rw.GetBondBetweenAtoms(node_to_idx[u], node_to_idx[v])
+    if bond_type == Chem.BondType.AROMATIC:
+        bond.SetIsAromatic(True)
+
+
+def _sanitize_or_cache(mol: Chem.Mol) -> None:
+    """Sanitize molecule, falling back to relaxed property-cache update."""
+    try:
+        Chem.SanitizeMol(mol)
+    except Exception:
+        mol.UpdatePropertyCache(strict=False)
+
+
+def graph_to_rdkit_mol(
+    graph: nx.Graph,
+    atom_map_key: str = "atom_map",
+) -> Tuple[Chem.Mol, Dict[int, int], Dict[int, int]]:
+    """Convert a NetworkX molecular graph to an RDKit molecule."""
+    rw = Chem.RWMol()
+    node_to_idx: Dict[int, int] = {}
+
+    for node, data in graph.nodes(data=True):
+        atom = _build_rdkit_atom(node, data, atom_map_key=atom_map_key)
+        node_to_idx[node] = rw.AddAtom(atom)
+
+    for u, v, edata in graph.edges(data=True):
+        _add_rdkit_bond(rw, node_to_idx, u, v, edata)
+
+    mol = rw.GetMol()
+    _sanitize_or_cache(mol)
+
+    idx_to_node = {idx: node for node, idx in node_to_idx.items()}
+    return mol, node_to_idx, idx_to_node
+
+
+def _conformer_to_pos_dict(
+    mol: Chem.Mol,
+    idx_to_node: Dict[int, int],
+) -> Dict[int, np.ndarray]:
+    """Convert an RDKit conformer into node-position mapping."""
+    conf = mol.GetConformer()
+    pos: Dict[int, np.ndarray] = {}
+
+    for idx in range(mol.GetNumAtoms()):
+        p = conf.GetAtomPosition(idx)
+        pos[idx_to_node[idx]] = np.array([p.x, p.y], dtype=float)
+
+    return pos
+
+
+def rdkit_positions(
+    graph: nx.Graph,
+    atom_map_key: str = "atom_map",
+) -> Dict[int, np.ndarray]:
+    """Compute 2D coordinates from RDKit depiction."""
+    mol, _, idx_to_node = graph_to_rdkit_mol(graph, atom_map_key=atom_map_key)
+    rdDepictor.SetPreferCoordGen(True)
+    rdDepictor.Compute2DCoords(mol)
+    return _conformer_to_pos_dict(mol, idx_to_node)
+
+
+def its_reference_positions(
+    its_graph: nx.Graph,
+    atom_map_key: str = "atom_map",
+) -> Dict[int, np.ndarray]:
+    """Compute ITS positions using a single-bond scaffold graph."""
+    ref = nx.Graph()
+
+    for node, data in its_graph.nodes(data=True):
+        elem = str(normalize_scalar_attr(data.get("element", "C"), "C"))
+        charge = int(normalize_scalar_attr(data.get("charge", 0), 0))
+        ref.add_node(
+            node,
+            element=elem,
+            charge=charge,
+            aromatic=False,
+            atom_map=int(normalize_scalar_attr(data.get(atom_map_key, node), node)),
+        )
+
+    for u, v in its_graph.edges():
+        ref.add_edge(u, v, order=1.0, kekule_order=1.0, bond_type="SINGLE")
+
+    return rdkit_positions(ref, atom_map_key=atom_map_key)
+
+
+def rigid_align_points(
+    moving: np.ndarray,
+    target: np.ndarray,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Return rotation/translation aligning *moving* onto *target*."""
+    mc = moving.mean(axis=0)
+    tc = target.mean(axis=0)
+
+    X = moving - mc
+    Y = target - tc
+
+    H = X.T @ Y
+    U, _, Vt = np.linalg.svd(H)
+    R = Vt.T @ U.T
+
+    if np.linalg.det(R) < 0:
+        Vt[-1, :] *= -1
+        R = Vt.T @ U.T
+
+    t = tc - mc @ R
+    return R, t
+
+
+def apply_rigid_transform(
+    pos: Dict[int, np.ndarray],
+    R: np.ndarray,
+    t: np.ndarray,
+) -> Dict[int, np.ndarray]:
+    """Apply rigid transform to all coordinates."""
+    return {k: v @ R + t for k, v in pos.items()}
+
+
+def align_pos_dict_to_reference(
+    moving_pos: Dict[int, np.ndarray],
+    moving_nodes: Sequence[int],
+    target_points: Sequence[np.ndarray],
+) -> Dict[int, np.ndarray]:
+    """Align a coordinate dictionary using corresponding anchor points."""
+    if len(moving_nodes) == 0:
+        return {k: v.copy() for k, v in moving_pos.items()}
+
+    if len(moving_nodes) == 1:
+        shift = np.asarray(target_points[0], dtype=float) - moving_pos[moving_nodes[0]]
+        return {k: v + shift for k, v in moving_pos.items()}
+
+    moving = np.array([moving_pos[n] for n in moving_nodes], dtype=float)
+    target = np.array(target_points, dtype=float)
+    R, t = rigid_align_points(moving, target)
+    return apply_rigid_transform(moving_pos, R, t)
+
+
+def _master_amap_positions(
+    pos_r_raw: Dict[int, np.ndarray],
+    pos_its_raw: Dict[int, np.ndarray],
+    r_amap_to_node: Dict[int, int],
+    its_amap_to_node: Dict[int, int],
+    reference_layout: str,
+) -> Dict[int, np.ndarray]:
+    """Choose the master atom-map frame used for shared alignment."""
+    if reference_layout == "reactant":
+        return {amap: pos_r_raw[node].copy() for amap, node in r_amap_to_node.items()}
+
+    if reference_layout == "its":
+        return {
+            amap: pos_its_raw[node].copy() for amap, node in its_amap_to_node.items()
+        }
+
+    raise ValueError("reference_layout must be 'reactant' or 'its'.")
+
+
+def _align_graph_to_master(
+    raw_pos: Dict[int, np.ndarray],
+    amap_to_node_dict: Dict[int, int],
+    master_amap_pos: Dict[int, np.ndarray],
+) -> Dict[int, np.ndarray]:
+    """Align one graph position dictionary to the shared atom-map frame."""
+    common_amaps = sorted(set(amap_to_node_dict) & set(master_amap_pos))
+    aligned = align_pos_dict_to_reference(
+        raw_pos,
+        moving_nodes=[amap_to_node_dict[a] for a in common_amaps],
+        target_points=[master_amap_pos[a] for a in common_amaps],
+    )
+
+    for amap in common_amaps:
+        aligned[amap_to_node_dict[amap]] = master_amap_pos[amap].copy()
+
+    return aligned
+
+
+def build_shared_layout(
+    reactant_graph: nx.Graph,
+    its_graph: nx.Graph,
+    atom_map_key: str = "atom_map",
+    reference_layout: str = "its",
+) -> Tuple[Dict[int, np.ndarray], Dict[int, np.ndarray]]:
+    """Build a shared layout for reactant and ITS using one master frame."""
+    pos_r_raw = rdkit_positions(reactant_graph, atom_map_key=atom_map_key)
+    pos_its_raw = its_reference_positions(its_graph, atom_map_key=atom_map_key)
+
+    r_amap_to_node = amap_to_node(reactant_graph, atom_map_key=atom_map_key)
+    its_amap_to_node = amap_to_node(its_graph, atom_map_key=atom_map_key)
+
+    master_amap_pos = _master_amap_positions(
+        pos_r_raw=pos_r_raw,
+        pos_its_raw=pos_its_raw,
+        r_amap_to_node=r_amap_to_node,
+        its_amap_to_node=its_amap_to_node,
+        reference_layout=reference_layout,
+    )
+
+    pos_r = _align_graph_to_master(pos_r_raw, r_amap_to_node, master_amap_pos)
+    pos_its = _align_graph_to_master(pos_its_raw, its_amap_to_node, master_amap_pos)
+    return pos_r, pos_its
+
+
+def separate_left_right(
+    pos_left: Dict[int, np.ndarray],
+    pos_right: Dict[int, np.ndarray],
+    gap: float = 3.0,
+) -> Tuple[Dict[int, np.ndarray], Dict[int, np.ndarray]]:
+    """Translate two layouts side-by-side while keeping their orientation."""
+    left = {k: v.copy() for k, v in pos_left.items()}
+    right = {k: v.copy() for k, v in pos_right.items()}
+
+    lx = [p[0] for p in left.values()]
+    ly = [p[1] for p in left.values()]
+    rx = [p[0] for p in right.values()]
+    ry = [p[1] for p in right.values()]
+
+    shift_x = (max(lx) - min(lx)) + gap + (min(lx) - min(rx))
+    right = {k: v + np.array([shift_x, 0.0], dtype=float) for k, v in right.items()}
+
+    cy_left = 0.5 * (min(ly) + max(ly))
+    cy_right = 0.5 * (min(ry) + max(ry))
+    right = {
+        k: v + np.array([0.0, cy_left - cy_right], dtype=float)
+        for k, v in right.items()
+    }
+    return left, right

synkit/Vis/epd/mapping.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+"""Atom-map helpers and edge lookup utilities."""
+
+from typing import Dict, Optional, Tuple
+
+import networkx as nx
+
+from .utils import normalize_scalar_attr
+
+
+def node_to_amap(graph: nx.Graph, atom_map_key: str = "atom_map") -> Dict[int, int]:
+    """Return node -> atom-map dictionary."""
+    return {
+        n: int(normalize_scalar_attr(graph.nodes[n].get(atom_map_key, n), n))
+        for n in graph.nodes()
+    }
+
+
+def amap_to_node(graph: nx.Graph, atom_map_key: str = "atom_map") -> Dict[int, int]:
+    """Return atom-map -> node dictionary."""
+    return {
+        int(normalize_scalar_attr(graph.nodes[n].get(atom_map_key, n), n)): n
+        for n in graph.nodes()
+    }
+
+
+def edge_amap_key_from_nodes(
+    graph: nx.Graph,
+    edge: Tuple[int, int],
+    atom_map_key: str = "atom_map",
+) -> Tuple[int, int]:
+    """Return a sorted atom-map edge key from a node edge."""
+    n2a = node_to_amap(graph, atom_map_key=atom_map_key)
+    u, v = edge
+    return tuple(sorted((n2a[u], n2a[v])))
+
+
+def edge_nodes_from_amap_key(
+    graph: Optional[nx.Graph],
+    amap_edge: Tuple[int, int],
+    atom_map_key: str = "atom_map",
+) -> Optional[Tuple[int, int]]:
+    """Resolve an atom-map edge back to node ids."""
+    if graph is None:
+        return None
+    a2n = amap_to_node(graph, atom_map_key=atom_map_key)
+    a1, a2 = amap_edge
+    if a1 not in a2n or a2 not in a2n:
+        return None
+    return tuple(sorted((a2n[a1], a2n[a2])))

synkit/Vis/epd/models.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+"""Simple data models for mechanism visualization."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Mapping, Sequence, Tuple
+
+from synkit.Mechanism.symbols import internal_action_label, legacy_action_label
+
+from .constants import transition_family
+
+
+@dataclass(frozen=True)
+class Transition:
+    """Minimal transition record used by the visualizer.
+
+    :param kind: Transition kind, e.g. ``'LP-/B+'`` or ``'B-/B+'``.
+    :type kind: str
+    :param src: Source atom/bond tuple.
+    :type src: Tuple[int, ...]
+    :param dst: Destination atom/bond tuple.
+    :type dst: Tuple[int, ...]
+    :param data: Auxiliary metadata such as ``shared_atom``.
+    :type data: Dict[str, Any]
+    """
+
+    kind: str
+    src: Tuple[int, ...]
+    dst: Tuple[int, ...]
+    data: Dict[str, Any]
+
+
+def transition_from_epd_step(step: Any) -> Transition:
+    """Normalize one SynKit EPD step into a drawable transition.
+
+    :param step: Transition-like object. Supported forms are ``Transition``,
+        a mapping with ``kind``, ``src`` and ``dst`` keys, or an ``epd_lw``
+        row of ``[typed_action, source, target]``.
+    :type step: Any
+    :return: Drawable transition with typed action preserved in ``data``.
+    :rtype: Transition
+    :raises ValueError: If the step cannot be interpreted.
+
+    .. rubric:: Example
+
+    .. code-block:: python
+
+        from synkit.Vis.epd import transition_from_epd_step
+
+        step = ["LP-/Sigma+", [1], [1, 2]]
+        transition = transition_from_epd_step(step)
+        assert transition.kind == "LP-/B+"
+        assert transition.data["typed_kind"] == "LP-/Sigma+"
+    """
+    if isinstance(step, Transition):
+        return step
+
+    # Avoid coupling the visual model to a concrete Mechanism class while
+    # accepting ElectronMove-compatible objects directly.
+    if all(hasattr(step, name) for name in ("source", "target", "electron_count")):
+        source_locus = step.source
+        target_locus = step.target
+        raw_kind = legacy_action_label(source_locus.kind, target_locus.kind)
+        src = source_locus.atom_maps
+        dst = target_locus.atom_maps
+        data = {
+            "internal_kind": internal_action_label(
+                source_locus.kind, target_locus.kind
+            ),
+            "typed_kind": raw_kind,
+            "electron_count": int(step.electron_count),
+            "arrow_type": getattr(step, "arrow_type", None),
+            "group_id": getattr(step, "group_id", None),
+            "coupling_id": getattr(step, "coupling_id", None),
+        }
+
+    elif isinstance(step, Mapping):
+        raw_kind = step.get("kind")
+        src = step.get("src")
+        dst = step.get("dst")
+        data = dict(step.get("data", {}) or {})
+    elif (
+        isinstance(step, Sequence)
+        and not isinstance(step, (str, bytes))
+        and len(step) >= 3
+    ):
+        raw_kind, src, dst = step[:3]
+        data = {}
+    else:
+        raise ValueError(f"Unsupported EPD transition step: {step!r}")
+
+    if raw_kind is None or src is None or dst is None:
+        raise ValueError(f"Incomplete EPD transition step: {step!r}")
+
+    raw_kind = str(raw_kind)
+    family = transition_family(raw_kind)
+    if family != raw_kind:
+        data.setdefault("typed_kind", raw_kind)
+    if "internal_kind" not in data:
+        try:
+            source_token, target_token = raw_kind.split("-/", 1)
+            data["internal_kind"] = internal_action_label(
+                source_token, target_token.removesuffix("+")
+            )
+        except (TypeError, ValueError):
+            pass
+
+    return Transition(
+        kind=family,
+        src=tuple(int(x) for x in src),
+        dst=tuple(int(x) for x in dst),
+        data=data,
+    )
+
+
+def transitions_from_epd(epd: Iterable[Any]) -> List[Transition]:
+    """Normalize SynKit ``epd_lw`` data for the mechanism visualizer.
+
+    :param epd: Iterable of EPD transition steps.
+    :type epd: Iterable[Any]
+    :return: List of normalized transitions.
+    :rtype: List[Transition]
+
+    .. rubric:: Example
+
+    .. code-block:: python
+
+        from synkit.Vis.epd import transitions_from_epd
+
+        epd_lw = [
+            ["LP-/Sigma+", [1], [1, 2]],
+            ["Sigma-/LP+", [2, 3], [3]],
+        ]
+        transitions = transitions_from_epd(epd_lw)
+    """
+    return [transition_from_epd_step(step) for step in epd]