synkit 1.6.5__py3-none-win_amd64.whl

synkit/Vis/epd/arrows.py

@@ -0,0 +1,425 @@
+from __future__ import annotations
+
+"""Geometry helpers for electron-pushing arrows."""
+
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+import networkx as nx
+import numpy as np
+
+from .constants import transition_family
+from .chem import infer_shared_atom, other_in_bond
+from .utils import as_tuple, mid, rot90, tget, unit
+
+
+def best_free_direction(
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    atom: int,
+    preferred: Optional[np.ndarray] = None,
+) -> np.ndarray:
+    """Choose a direction around an atom that avoids existing bonds."""
+    p = pos[atom]
+    blocked = []
+
+    for nb in graph.neighbors(atom):
+        vec = pos[nb] - p
+        if np.linalg.norm(vec) > 1e-12:
+            blocked.append(unit(vec))
+
+    preferred = (
+        np.array([1.0, 0.0], dtype=float) if preferred is None else unit(preferred)
+    )
+
+    best = None
+    best_score = -1e18
+    for deg in range(0, 360, 12):
+        th = np.deg2rad(deg)
+        cand = np.array([np.cos(th), np.sin(th)], dtype=float)
+        sep = min((1.0 - float(np.dot(cand, b)) for b in blocked), default=2.0)
+        score = sep + 0.35 * float(np.dot(cand, preferred))
+        if score > best_score:
+            best_score = score
+            best = cand
+    return unit(best)
+
+
+def lp_anchor(
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    atom: int,
+    toward: Optional[np.ndarray],
+    dist: float,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Return lone-pair anchor position and direction."""
+    pref = None if toward is None else (np.asarray(toward, dtype=float) - pos[atom])
+    d = best_free_direction(graph, pos, atom, preferred=pref)
+    return pos[atom] + dist * d, d
+
+
+def virtual_h_position(
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    donor_atom: int,
+    acceptor_atom: int,
+    dist: float,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Place a virtual proton near the donor atom."""
+    d = best_free_direction(
+        graph,
+        pos,
+        donor_atom,
+        preferred=(pos[acceptor_atom] - pos[donor_atom]),
+    )
+    return pos[donor_atom] + dist * d, d
+
+
+def bond_lobe_anchor(
+    p_shared: np.ndarray,
+    p_other: np.ndarray,
+    side: float,
+    along: float,
+    offset: float,
+) -> np.ndarray:
+    """Anchor an arrow near one side of a bond instead of the midpoint."""
+    vec = p_other - p_shared
+    u = unit(vec)
+    perp = rot90(u)
+    return p_shared + along * vec + side * offset * perp
+
+
+def choose_side_from_turn(
+    p_shared: np.ndarray,
+    p_src_other: np.ndarray,
+    p_dst_other: np.ndarray,
+) -> float:
+    """Choose curvature sign from the source-to-destination turn direction."""
+    a = unit(p_src_other - p_shared)
+    b = unit(p_dst_other - p_shared)
+    turn = a[0] * b[1] - a[1] * b[0]
+    return 1.0 if turn >= 0 else -1.0
+
+
+def build_proton_pair_context(
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    transitions: Sequence[Any],
+    h_dist: float,
+) -> Dict[int, Dict[str, Any]]:
+    """Associate LP-/H+ and H-/LP+ or H-/B+ steps with a shared virtual proton."""
+    ctx: Dict[int, Dict[str, Any]] = {}
+
+    for i in range(len(transitions) - 1):
+        t1 = transitions[i]
+        t2 = transitions[i + 1]
+
+        if tget(t1, "kind") != "LP-/H+":
+            continue
+        if tget(t2, "kind") not in {"H-/LP+", "H-/B+"}:
+            continue
+
+        acceptor = as_tuple(tget(t1, "src"))[0]
+        donor = as_tuple(tget(t2, "src"))[0]
+        h_pos, _ = virtual_h_position(graph, pos, donor, acceptor, h_dist)
+
+        ctx[i] = {
+            "pair_id": (i, i + 1),
+            "acceptor_atom": acceptor,
+            "donor_atom": donor,
+            "h_pos": h_pos,
+        }
+        ctx[i + 1] = {
+            "pair_id": (i, i + 1),
+            "acceptor_atom": acceptor,
+            "donor_atom": donor,
+            "h_pos": h_pos,
+        }
+
+    return ctx
+
+
+def _base_spec(step: int) -> Dict[str, Any]:
+    """Create a default arrow spec container."""
+    return {
+        "step": step,
+        "tail": None,
+        "head": None,
+        "rad": 0.18 if step % 2 else -0.18,
+        "lp_tail": None,
+        "lp_tail_dir": None,
+        "lp_head": None,
+        "lp_head_dir": None,
+        "virtual_h": None,
+        "transition": None,
+    }
+
+
+def _maybe_add_virtual_h(
+    spec: Dict[str, Any],
+    info: Dict[str, Any],
+    pos: Dict[int, np.ndarray],
+    drawn_virtual_h: set,
+) -> None:
+    """Add the virtual proton guide once per proton-transfer pair."""
+    if info["pair_id"] not in drawn_virtual_h:
+        spec["virtual_h"] = (pos[info["donor_atom"]], info["h_pos"])
+        drawn_virtual_h.add(info["pair_id"])
+
+
+def _handle_lp_to_bond(
+    spec: Dict[str, Any],
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    src: Tuple[int, ...],
+    dst: Tuple[int, ...],
+    scale: float,
+    lp_dist: float,
+) -> None:
+    """Handle LP-/B+."""
+    donor = src[0]
+    target = other_in_bond(dst, donor) if len(dst) == 2 else dst[0]
+    if target is None:
+        target = dst[-1]
+
+    spec["tail"], spec["lp_tail_dir"] = lp_anchor(
+        graph, pos, donor, toward=pos[target], dist=lp_dist
+    )
+    spec["lp_tail"] = spec["tail"]
+    spec["head"] = pos[target] - unit(pos[target] - spec["tail"]) * 0.14 * scale
+
+
+def _handle_bond_to_lp(
+    spec: Dict[str, Any],
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    src: Tuple[int, ...],
+    dst: Tuple[int, ...],
+    lp_dist: float,
+) -> None:
+    """Handle B-/LP+."""
+    u, v = src
+    acceptor = dst[0]
+    spec["tail"] = mid(pos[u], pos[v])
+    spec["head"], spec["lp_head_dir"] = lp_anchor(
+        graph, pos, acceptor, toward=spec["tail"], dist=lp_dist
+    )
+    spec["lp_head"] = spec["head"]
+
+
+def _handle_lp_to_proton(
+    spec: Dict[str, Any],
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    src: Tuple[int, ...],
+    info: Dict[str, Any],
+    drawn_virtual_h: set,
+    lp_dist: float,
+    scale: float,
+) -> None:
+    """Handle LP-/H+."""
+    _maybe_add_virtual_h(spec, info, pos, drawn_virtual_h)
+
+    acceptor = src[0]
+    h_pos = info["h_pos"]
+    spec["tail"], spec["lp_tail_dir"] = lp_anchor(
+        graph, pos, acceptor, toward=h_pos, dist=lp_dist
+    )
+    spec["lp_tail"] = spec["tail"]
+    spec["head"] = h_pos - unit(h_pos - spec["tail"]) * 0.04 * scale
+
+
+def _handle_proton_to_lp(
+    spec: Dict[str, Any],
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    dst: Tuple[int, ...],
+    info: Dict[str, Any],
+    drawn_virtual_h: set,
+    lp_dist: float,
+) -> None:
+    """Handle H-/LP+."""
+    _maybe_add_virtual_h(spec, info, pos, drawn_virtual_h)
+
+    donor = info["donor_atom"]
+    h_pos = info["h_pos"]
+    acceptor = dst[0]
+
+    spec["tail"] = mid(pos[donor], h_pos)
+    spec["head"], spec["lp_head_dir"] = lp_anchor(
+        graph, pos, acceptor, toward=spec["tail"], dist=lp_dist
+    )
+    spec["lp_head"] = spec["head"]
+
+
+def _handle_proton_to_bond(
+    spec: Dict[str, Any],
+    pos: Dict[int, np.ndarray],
+    dst: Tuple[int, ...],
+    info: Dict[str, Any],
+    drawn_virtual_h: set,
+) -> None:
+    """Handle H-/B+."""
+    _maybe_add_virtual_h(spec, info, pos, drawn_virtual_h)
+
+    donor = info["donor_atom"]
+    h_pos = info["h_pos"]
+
+    spec["tail"] = mid(pos[donor], h_pos)
+    spec["head"] = mid(pos[dst[0]], pos[dst[1]]) if len(dst) == 2 else pos[dst[0]]
+
+
+def _handle_bond_to_bond_shared(
+    spec: Dict[str, Any],
+    pos: Dict[int, np.ndarray],
+    src: Tuple[int, ...],
+    dst: Tuple[int, ...],
+    shared: int,
+    along: float,
+    offset: float,
+) -> None:
+    """Handle B-/B+ when source and destination bonds share an atom."""
+    src_other = other_in_bond(src, shared)
+    dst_other = other_in_bond(dst, shared)
+
+    if src_other is None or dst_other is None:
+        spec["tail"] = mid(pos[src[0]], pos[src[1]])
+        spec["head"] = mid(pos[dst[0]], pos[dst[1]])
+        return
+
+    p_shared = pos[shared]
+    side = choose_side_from_turn(p_shared, pos[src_other], pos[dst_other])
+    spec["rad"] = 0.23 * side
+    spec["tail"] = bond_lobe_anchor(p_shared, pos[src_other], side, along, offset)
+    spec["head"] = bond_lobe_anchor(p_shared, pos[dst_other], side, along, offset)
+
+
+def _handle_bond_to_bond(
+    spec: Dict[str, Any],
+    pos: Dict[int, np.ndarray],
+    src: Tuple[int, ...],
+    dst: Tuple[int, ...],
+    data: Dict[str, Any],
+    along: float,
+    offset: float,
+) -> None:
+    """Handle B-/B+."""
+    if len(src) != 2:
+        return
+
+    if len(dst) != 2:
+        spec["tail"] = mid(pos[src[0]], pos[src[1]])
+        spec["head"] = pos[dst[0]]
+        return
+
+    shared = infer_shared_atom(src, dst, data)
+    if shared is None:
+        spec["tail"] = mid(pos[src[0]], pos[src[1]])
+        spec["head"] = mid(pos[dst[0]], pos[dst[1]])
+        return
+
+    _handle_bond_to_bond_shared(spec, pos, src, dst, shared, along, offset)
+
+
+def _populate_spec_for_transition(
+    spec: Dict[str, Any],
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    kind: str,
+    src: Tuple[int, ...],
+    dst: Tuple[int, ...],
+    data: Dict[str, Any],
+    proton_ctx: Dict[int, Dict[str, Any]],
+    transition_index0: int,
+    drawn_virtual_h: set,
+    scale: float,
+    lp_dist: float,
+    along: float,
+    offset: float,
+) -> None:
+    """Populate one spec according to transition kind."""
+    kind = transition_family(kind)
+    if kind == "LP-/B+":
+        _handle_lp_to_bond(spec, graph, pos, src, dst, scale, lp_dist)
+        return
+
+    if kind == "B-/LP+":
+        _handle_bond_to_lp(spec, graph, pos, src, dst, lp_dist)
+        return
+
+    info = proton_ctx.get(transition_index0)
+    if kind == "LP-/H+":
+        if info is None:
+            return
+        _handle_lp_to_proton(
+            spec, graph, pos, src, info, drawn_virtual_h, lp_dist, scale
+        )
+        return
+
+    if kind == "H-/LP+":
+        if info is None:
+            return
+        _handle_proton_to_lp(spec, graph, pos, dst, info, drawn_virtual_h, lp_dist)
+        return
+
+    if kind == "H-/B+":
+        if info is None:
+            return
+        _handle_proton_to_bond(spec, pos, dst, info, drawn_virtual_h)
+        return
+
+    if kind == "B-/B+":
+        _handle_bond_to_bond(spec, pos, src, dst, data, along, offset)
+
+
+def arrow_specs_from_transitions(
+    graph: nx.Graph,
+    pos: Dict[int, np.ndarray],
+    transitions: Sequence[Any],
+    scale: float,
+) -> list[dict]:
+    """Convert transition records into drawable arrow specifications."""
+    proton_ctx = build_proton_pair_context(graph, pos, transitions, h_dist=0.34 * scale)
+    drawn_virtual_h = set()
+
+    lp_dist = 0.23 * scale
+    lp_sep = 0.034 * scale
+    lp_radius = 0.011 * scale
+    along = 0.68
+    offset = 0.055 * scale
+
+    specs: list[dict] = []
+
+    for idx0, t in enumerate(transitions):
+        step = idx0 + 1
+        kind = tget(t, "kind")
+        src = as_tuple(tget(t, "src"))
+        dst = as_tuple(tget(t, "dst"))
+        data = tget(t, "data", {}) or {}
+
+        spec = _base_spec(step)
+        spec["transition"] = t
+        _populate_spec_for_transition(
+            spec=spec,
+            graph=graph,
+            pos=pos,
+            kind=kind,
+            src=src,
+            dst=dst,
+            data=data,
+            proton_ctx=proton_ctx,
+            transition_index0=idx0,
+            drawn_virtual_h=drawn_virtual_h,
+            scale=scale,
+            lp_dist=lp_dist,
+            along=along,
+            offset=offset,
+        )
+
+        if spec["tail"] is None or spec["head"] is None:
+            continue
+
+        spec["lp_sep"] = lp_sep
+        spec["lp_radius"] = lp_radius
+        specs.append(spec)
+
+    return specs

synkit/Vis/epd/chem.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+"""Chemistry-specific helpers for bond order and electron-flow semantics."""
+
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+import networkx as nx
+
+from .constants import transition_family
+from .mapping import edge_amap_key_from_nodes, edge_nodes_from_amap_key
+from .utils import canonical_bond_order, bond_symbol, tget, as_tuple
+
+
+def other_in_bond(bond: Tuple[int, int], atom: int) -> Optional[int]:
+    """Return the other atom in a 2-center bond tuple."""
+    u, v = bond
+    if atom == u:
+        return v
+    if atom == v:
+        return u
+    return None
+
+
+def infer_shared_atom(
+    src: Tuple[int, ...],
+    dst: Tuple[int, ...],
+    data: Dict[str, Any],
+) -> Optional[int]:
+    """Infer the shared atom in a source/destination bond transition."""
+    shared = data.get("shared_atom", None)
+    if shared is not None:
+        return shared
+    inter = set(src) & set(dst)
+    if len(inter) == 1:
+        return next(iter(inter))
+    return None
+
+
+def edge_order(edata: Dict[str, Any]) -> Optional[float]:
+    """Read a bond order from an edge attribute dictionary."""
+    bond_type = edata.get("bond_type", None)
+    if bond_type == "AROMATIC":
+        return 1.5
+
+    kek = edata.get("kekule_order", None)
+    if kek is not None and not isinstance(kek, (tuple, list)):
+        return canonical_bond_order(kek)
+
+    order = edata.get("order", None)
+    if order is not None and not isinstance(order, (tuple, list)):
+        return canonical_bond_order(order)
+
+    return 1.0
+
+
+def edge_symbol(edata: Dict[str, Any]) -> str:
+    """Single-state symbolic bond label for a graph edge."""
+    return bond_symbol(edge_order(edata))
+
+
+def edge_order_from_amap_key(
+    graph: Optional[nx.Graph],
+    amap_edge: Tuple[int, int],
+    atom_map_key: str = "atom_map",
+) -> Optional[float]:
+    """Resolve an atom-map edge and return its bond order."""
+    node_edge = edge_nodes_from_amap_key(graph, amap_edge, atom_map_key=atom_map_key)
+    if node_edge is None or graph is None:
+        return None
+    u, v = node_edge
+    if not graph.has_edge(u, v):
+        return None
+    return edge_order(graph.get_edge_data(u, v))
+
+
+def collect_rc_amap_sets(
+    transitions: Sequence[Any],
+    reactant_graph: nx.Graph,
+    atom_map_key: str = "atom_map",
+) -> Tuple[set[Tuple[int, int]], set[Tuple[int, int]]]:
+    """Collect broken and forming reaction-center edges in atom-map space."""
+    broken: set[Tuple[int, int]] = set()
+    forming: set[Tuple[int, int]] = set()
+
+    for t in transitions:
+        _raw_kind = tget(t, "kind")
+        kind = transition_family(_raw_kind)
+        src = as_tuple(tget(t, "src"))
+        dst = as_tuple(tget(t, "dst"))
+
+        if kind in {"B-/LP+", "B-/B+"} and len(src) == 2:
+            broken.add(
+                edge_amap_key_from_nodes(
+                    reactant_graph,
+                    (src[0], src[1]),
+                    atom_map_key=atom_map_key,
+                )
+            )
+
+        if kind in {"LP-/B+", "B-/B+", "H-/B+"} and len(dst) == 2:
+            forming.add(
+                edge_amap_key_from_nodes(
+                    reactant_graph,
+                    (dst[0], dst[1]),
+                    atom_map_key=atom_map_key,
+                )
+            )
+
+    return broken, forming
+
+
+def its_pair_orders_from_edge(
+    its_graph: nx.Graph,
+    u: int,
+    v: int,
+    reactant_graph: Optional[nx.Graph] = None,
+    product_graph: Optional[nx.Graph] = None,
+    atom_map_key: str = "atom_map",
+) -> Tuple[Optional[float], Optional[float]]:
+    """Return (reactant_order, product_order) for an ITS edge."""
+    edata = its_graph.get_edge_data(u, v, default={})
+
+    for key in ("order", "kekule_order"):
+        val = edata.get(key, None)
+        if isinstance(val, (tuple, list)) and len(val) >= 2:
+            return canonical_bond_order(val[0]), canonical_bond_order(val[1])
+
+    amap_u = int(its_graph.nodes[u].get(atom_map_key, u))
+    amap_v = int(its_graph.nodes[v].get(atom_map_key, v))
+    amap_edge = tuple(sorted((amap_u, amap_v)))
+
+    r_order = edge_order_from_amap_key(
+        reactant_graph, amap_edge, atom_map_key=atom_map_key
+    )
+    p_order = edge_order_from_amap_key(
+        product_graph, amap_edge, atom_map_key=atom_map_key
+    )
+    return canonical_bond_order(r_order), canonical_bond_order(p_order)
+
+
+def its_pair_label(
+    its_graph: nx.Graph,
+    u: int,
+    v: int,
+    reactant_graph: Optional[nx.Graph] = None,
+    product_graph: Optional[nx.Graph] = None,
+    atom_map_key: str = "atom_map",
+) -> str:
+    """Return a label like ``(—,=)`` for an ITS edge."""
+    r_order, p_order = its_pair_orders_from_edge(
+        its_graph,
+        u,
+        v,
+        reactant_graph=reactant_graph,
+        product_graph=product_graph,
+        atom_map_key=atom_map_key,
+    )
+    return f"({bond_symbol(r_order)},{bond_symbol(p_order)})"
+
+
+def its_edge_change_sign(
+    its_graph: nx.Graph,
+    u: int,
+    v: int,
+    reactant_graph: Optional[nx.Graph] = None,
+    product_graph: Optional[nx.Graph] = None,
+    atom_map_key: str = "atom_map",
+) -> int:
+    """Return +1 for decrease/breaking, -1 for increase/forming, 0 unchanged."""
+    edata = its_graph.get_edge_data(u, v, default={})
+    std = edata.get("standard_order", None)
+    if std is not None and not isinstance(std, (tuple, list)):
+        try:
+            val = float(std)
+            if val > 0:
+                return +1
+            if val < 0:
+                return -1
+            return 0
+        except Exception:
+            pass
+
+    r_order, p_order = its_pair_orders_from_edge(
+        its_graph,
+        u,
+        v,
+        reactant_graph=reactant_graph,
+        product_graph=product_graph,
+        atom_map_key=atom_map_key,
+    )
+    r_val = 0.0 if r_order is None else float(r_order)
+    p_val = 0.0 if p_order is None else float(p_order)
+    if p_val > r_val:
+        return -1
+    if p_val < r_val:
+        return +1
+    return 0

synkit/Vis/epd/constants.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+"""Visual constants for mechanism plotting."""
+
+from typing import Dict
+
+ACS_ATOM_COLORS: Dict[str, str] = {
+    "H": "#FFFFFF",
+    "C": "#303030",
+    "N": "#3B5BDB",
+    "O": "#D94841",
+    "F": "#2B8A3E",
+    "Cl": "#2B8A3E",
+    "Br": "#8C4A2F",
+    "I": "#6741D9",
+    "P": "#C77D00",
+    "S": "#C9A227",
+    "B": "#B3541E",
+    "Si": "#6C757D",
+    "Na": "#4DABF7",
+    "K": "#845EF7",
+    "Li": "#9775FA",
+    "Mg": "#37B24D",
+    "Ca": "#51CF66",
+}
+
+DEFAULT_ATOM_COLOR = "#ADB5BD"
+
+BOND_SYMBOLS = {
+    None: "∅",
+    0: "∅",
+    1: "—",
+    2: "=",
+    3: "≡",
+    1.5: ":",
+}
+
+KIND_FAMILY: Dict[str, str] = {
+    "LP-/B+": "LP-/B+",
+    "B-/LP+": "B-/LP+",
+    "B-/B+": "B-/B+",
+    "LP-/H+": "LP-/H+",
+    "H-/LP+": "H-/LP+",
+    "H-/B+": "H-/B+",
+    "LP-/Sigma+": "LP-/B+",
+    "LP-/Pi+": "LP-/B+",
+    "Sigma-/LP+": "B-/LP+",
+    "Pi-/LP+": "B-/LP+",
+    "Sigma-/Sigma+": "B-/B+",
+    "Sigma-/Pi+": "B-/B+",
+    "Pi-/Sigma+": "B-/B+",
+    "Pi-/Pi+": "B-/B+",
+    "Sigma-/H+": "B-/H+",
+    "Pi-/H+": "B-/H+",
+    "H-/Sigma+": "H-/B+",
+    "H-/Pi+": "H-/B+",
+}
+
+
+def transition_family(kind: str) -> str:
+    """Return the generic rendering family for a typed EPD action."""
+    return KIND_FAMILY.get(kind, kind)
+
+
+class NatureStyle:
+    """Default restrained styling for two-panel mechanism figures."""
+
+    broken_color = "#C92A2A"
+    forming_color = "#2B8A3E"
+    shift_color = "#2563EB"
+    proton_color = "#B7791F"
+    arrow_color = "#111111"
+    neutral_bond_color = "#2A2A2A"
+    faded_bond_color = "#8A8F98"
+    bond_label_color = "#4A4F57"
+    map_text_color = "#5C6770"
+    charge_badge_color = "#6D1F1F"
+    electron_badge_color = "#1F3A5F"
+    panel_title_color = "#111111"
+    background_color = "white"
+
+    main_title_fontsize = 18
+    panel_title_fontsize = 15