synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Mech/conversion_debug.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .conversion import (
+    build_its_from_rsmi,
+    classify_arrow_shape,
+    convert_reaction_arrow,
+    get_its_bond_order,
+    parse_arrow_step,
+    remove_non_arrow_atom_maps,
+    split_arrow_code,
+    validate_arrow_maps,
+)
+
+
+def debug_arrow_bond_orders(
+    reaction_smiles: str,
+    arrow_code: str,
+    expand_aam: bool = True,
+    remove_non_arrow_maps: bool = True,
+    strict_bond_lookup: bool = True,
+) -> None:
+    """Print the ITS bond orders used by each arrow step.
+
+    :param reaction_smiles: Reaction SMILES in ``reactants>>products`` format.
+    :type reaction_smiles: str
+    :param arrow_code: Semicolon-separated arrow code.
+    :type arrow_code: str
+    :param expand_aam: Whether to expand atom mapping before ITS construction.
+    :type expand_aam: bool
+    :param remove_non_arrow_maps: Whether to remove atom maps not used by the arrow code.
+    :type remove_non_arrow_maps: bool
+    :param strict_bond_lookup: Whether missing typed bond lookups should raise.
+    :type strict_bond_lookup: bool
+    :return: ``None``.
+    :rtype: None
+    """
+    its, expanded_rsmi, rsmi_for_its, diagnostics = build_its_from_rsmi(
+        rsmi=reaction_smiles,
+        arrow_code=arrow_code,
+        expand_aam=expand_aam,
+        remove_non_arrow_maps=remove_non_arrow_maps,
+    )
+
+    print("Diagnostics:")
+    print(diagnostics)
+    print()
+
+    print("RSMI used for ITS:")
+    print(rsmi_for_its)
+    print()
+
+    print("Expanded RSMI:")
+    print(expanded_rsmi)
+    print()
+
+    for step in split_arrow_code(arrow_code):
+        lhs, rhs = parse_arrow_step(step)
+
+        print(f"Step: {step}")
+        print(f"  shape: {classify_arrow_shape(step)}")
+
+        if len(lhs) == 1 and len(rhs) == 1:
+            a = lhs[0]
+            b = rhs[0]
+            print(
+                f"  destination bond {a}-{b}: "
+                f"{get_its_bond_order(its, a, b, strict=strict_bond_lookup, context=step)}"
+            )
+
+        elif len(lhs) == 1 and len(rhs) == 2:
+            a = lhs[0]
+            b, c = rhs
+            print(f"  LP source atom    {a}")
+            print(
+                f"  destination bond {b}-{c}: "
+                f"{get_its_bond_order(its, b, c, strict=strict_bond_lookup, context=step)}"
+            )
+
+        elif len(lhs) == 2 and len(rhs) == 1:
+            a, b = lhs
+            c = rhs[0]
+            print(
+                f"  source bond      {a}-{b}: "
+                f"{get_its_bond_order(its, a, b, strict=strict_bond_lookup, context=step)}"
+            )
+            print(f"  LP destination atom {c}")
+
+        elif len(lhs) == 2 and len(rhs) == 2:
+            a, b = lhs
+            c, d = rhs
+            print(
+                f"  source bond      {a}-{b}: "
+                f"{get_its_bond_order(its, a, b, strict=strict_bond_lookup, context=step)}"
+            )
+            print(
+                f"  destination bond {c}-{d}: "
+                f"{get_its_bond_order(its, c, d, strict=strict_bond_lookup, context=step)}"
+            )
+
+        print()
+
+
+def debug_record(
+    record: dict[str, Any],
+    reaction_key: str = "SMIRKS",
+    arrow_key: str = "arrow_code",
+    orbital_key: str = "orbital pair classification",
+) -> dict[str, Any]:
+    """Print full debug output for one record.
+
+    :param record: Source record to inspect.
+    :type record: dict[str, Any]
+    :param reaction_key: Key containing reaction SMILES.
+    :type reaction_key: str
+    :param arrow_key: Key containing arrow code.
+    :type arrow_key: str
+    :param orbital_key: Key containing optional orbital classification metadata.
+    :type orbital_key: str
+    :return: Converted record.
+    :rtype: dict[str, Any]
+    """
+    from pprint import pprint
+
+    rsmi = record[reaction_key]
+    arrow_code = record[arrow_key]
+    orbital_class = record.get(orbital_key)
+
+    print("=" * 100)
+    print("DEBUG RECORD")
+    print("=" * 100)
+
+    print("orbital_class:")
+    print(orbital_class)
+    print()
+
+    print("arrow_code:")
+    print(arrow_code)
+    print()
+
+    print("arrow shapes:")
+    for step in split_arrow_code(arrow_code):
+        print(f"  {step:25s} -> {classify_arrow_shape(step)}")
+    print()
+
+    print("raw map diagnostics:")
+    diagnostics = validate_arrow_maps(
+        rsmi=rsmi,
+        arrow_code=arrow_code,
+        raise_on_arrow_duplicates=False,
+        raise_on_missing_arrow_maps=False,
+    )
+    pprint(diagnostics, width=160)
+    print()
+
+    print("RSMI after removing non-arrow maps:")
+    cleaned = remove_non_arrow_atom_maps(rsmi, arrow_code)
+    print(cleaned)
+    print()
+
+    print("Arrow bond orders:")
+    debug_arrow_bond_orders(
+        reaction_smiles=rsmi,
+        arrow_code=arrow_code,
+        expand_aam=True,
+        remove_non_arrow_maps=True,
+        strict_bond_lookup=True,
+    )
+
+    result = convert_reaction_arrow(
+        reaction_smiles=rsmi,
+        arrow_code=arrow_code,
+        orbital_class=orbital_class,
+        expand_aam=True,
+        remove_non_arrow_maps=True,
+        strict_bond_lookup=True,
+    )
+
+    print("converted:")
+    pprint(result["converted"], width=120)
+    print()
+
+    print("typed_converted:")
+    pprint(result["typed_converted"], width=120)
+    print()
+
+    return result
+
+
+def check_typed_conversion_quality(results: list[dict[str, Any]]) -> dict[str, Any]:
+    """Check whether typed conversions still contain generic B-/B+ labels.
+
+    :param results: Conversion results to inspect.
+    :type results: list[dict[str, Any]]
+    :return: Error and untyped-step diagnostics.
+    :rtype: dict[str, Any]
+    """
+    errors = []
+    untyped = []
+
+    for result in results:
+        if "error" in result:
+            errors.append(result)
+            continue
+
+        typed = result.get("typed_converted")
+
+        if typed is None:
+            untyped.append(
+                {
+                    "row_index": result.get("row_index"),
+                    "reason": "typed_converted is None",
+                }
+            )
+            continue
+
+        for step in typed:
+            label = step[0]
+            if "B-" in label or "B+" in label:
+                untyped.append(
+                    {
+                        "row_index": result.get("row_index"),
+                        "orbital_class": result.get("orbital_class"),
+                        "arrow_code": result.get("arrow_code"),
+                        "step": step,
+                    }
+                )
+
+    return {
+        "n_results": len(results),
+        "n_errors": len(errors),
+        "n_untyped_steps": len(untyped),
+        "all_fully_typed": len(errors) == 0 and len(untyped) == 0,
+        "errors": errors,
+        "untyped": untyped,
+    }

synkit/Graph/Mech/electron_accounting.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import networkx as nx
+from rdkit import Chem
+
+
+@dataclass(frozen=True)
+class ChargeRefresh:
+    """VE/NBE/B charge refresh report for one atom map."""
+
+    atom_map: int
+    node: Any
+    previous_charge: int | float
+    refreshed_charge: int | float
+    valence_electrons: float
+    nonbonding_electrons: float
+    bond_electrons: float
+
+
+@dataclass(frozen=True)
+class ChargeEdit:
+    """Incremental local formal-charge edit for one atom map."""
+
+    atom_map: int
+    node: Any
+    delta: int | float
+    previous_charge: int | float
+    new_charge: int | float
+
+
+def bond_order_sum(graph: nx.Graph, node: Any) -> float:
+    """Return the sigma-plus-pi bond-order sum around one node."""
+    total = 0.0
+    for _, _, data in graph.edges(node, data=True):
+        total += float(data.get("sigma_order", 0.0)) + float(data.get("pi_order", 0.0))
+    return total
+
+
+def nonbonding_electron_count(graph: nx.Graph, node: Any) -> float:
+    """Return the nonbonding-electron count for one atom."""
+    attrs = graph.nodes[node]
+    return 2 * float(attrs.get("lone_pairs", 0)) + float(attrs.get("radical", 0))
+
+
+def bond_electron_count(graph: nx.Graph, node: Any) -> float:
+    """Return the atom's formal-charge bonding allocation.
+
+    Each bond pair contributes one electron to this atom; this is therefore
+    not the complete two-electron population of the bonds.
+    """
+    return float(graph.nodes[node].get("hcount", 0)) + bond_order_sum(graph, node)
+
+
+def recompute_charge(graph: nx.Graph, node: Any) -> int | float:
+    """Recompute formal charge from stored electron-state fields."""
+    attrs = graph.nodes[node]
+    charge = (
+        float(attrs["valence_electrons"])
+        - nonbonding_electron_count(
+            graph,
+            node,
+        )
+        - bond_electron_count(graph, node)
+    )
+    return int(charge) if charge.is_integer() else charge
+
+
+def atom_map_to_node(graph: nx.Graph) -> dict[int, Any]:
+    """Build a unique atom-map-to-node lookup for a molecular graph."""
+    lookup: dict[int, Any] = {}
+    duplicates: dict[int, list[Any]] = {}
+
+    for node, attrs in graph.nodes(data=True):
+        atom_map = attrs.get("atom_map", node)
+        if atom_map in (None, 0, "0"):
+            continue
+
+        atom_map_int = int(atom_map)
+        if atom_map_int in lookup:
+            duplicates.setdefault(atom_map_int, [lookup[atom_map_int]]).append(node)
+        else:
+            lookup[atom_map_int] = node
+
+    if duplicates:
+        raise ValueError(f"Duplicate atom maps in graph: {duplicates}")
+
+    return lookup
+
+
+def refresh_changed_atom_charge(
+    graph: nx.Graph,
+    atom_maps: list[int] | tuple[int, ...] | set[int],
+) -> list[ChargeRefresh]:
+    """Refresh formal charges for selected mapped atoms in place."""
+    lookup = atom_map_to_node(graph)
+    reports: list[ChargeRefresh] = []
+
+    for atom_map in sorted({int(value) for value in atom_maps}):
+        if atom_map not in lookup:
+            raise ValueError(f"Atom map {atom_map} is missing from graph.")
+
+        node = lookup[atom_map]
+        attrs = graph.nodes[node]
+        if "valence_electrons" not in attrs:
+            raise ValueError(f"Atom map {atom_map} has no valence_electrons field.")
+
+        previous_charge = attrs.get("charge", 0)
+        refreshed_charge = recompute_charge(graph, node)
+        attrs["charge"] = refreshed_charge
+        attrs["bond_order_sum"] = bond_order_sum(graph, node)
+        attrs["recomputed_charge"] = refreshed_charge
+        attrs["charge_mismatch"] = False
+        reports.append(
+            ChargeRefresh(
+                atom_map=atom_map,
+                node=node,
+                previous_charge=previous_charge,
+                refreshed_charge=refreshed_charge,
+                valence_electrons=float(attrs["valence_electrons"]),
+                nonbonding_electrons=nonbonding_electron_count(graph, node),
+                bond_electrons=bond_electron_count(graph, node),
+            )
+        )
+
+    return reports
+
+
+def change_atom_charge(
+    graph: nx.Graph,
+    atom_maps: list[int] | tuple[int, ...] | set[int],
+    *,
+    delta: int | float,
+) -> list[ChargeEdit]:
+    """Apply a local formal-charge delta to selected mapped atoms."""
+    lookup = atom_map_to_node(graph)
+    reports: list[ChargeEdit] = []
+
+    for atom_map in [int(value) for value in atom_maps]:
+        if atom_map not in lookup:
+            raise ValueError(f"Atom map {atom_map} is missing from graph.")
+
+        node = lookup[atom_map]
+        attrs = graph.nodes[node]
+        previous_charge = attrs.get("charge", 0)
+        new_charge = previous_charge + delta
+        if isinstance(new_charge, float) and new_charge.is_integer():
+            new_charge = int(new_charge)
+        attrs["charge"] = new_charge
+        reports.append(
+            ChargeEdit(
+                atom_map=atom_map,
+                node=node,
+                delta=delta,
+                previous_charge=previous_charge,
+                new_charge=new_charge,
+            )
+        )
+
+    return reports
+
+
+def refresh_electron_fields(graph: nx.Graph, *, in_place: bool = False) -> nx.Graph:
+    """Refresh derived electron bookkeeping on a molecular graph.
+
+    The graph is expected to store scalar ``sigma_order`` and ``pi_order`` edge
+    fields plus node-level electron state. Presentation-facing ``order`` is not
+    rewritten here; RDKit reconstruction remains responsible for aromatic
+    re-perception at the product boundary.
+    """
+    target = graph if in_place else graph.copy()
+
+    for _, _, data in target.edges(data=True):
+        sigma = float(data.get("sigma_order", 0.0))
+        pi = float(data.get("pi_order", 0.0))
+        data["kekule_order"] = sigma + pi
+
+    for node, attrs in target.nodes(data=True):
+        attrs["bond_order_sum"] = bond_order_sum(target, node)
+        if "valence_electrons" not in attrs:
+            continue
+        attrs["recomputed_charge"] = recompute_charge(target, node)
+        represented_charge = float(attrs.get("charge", 0))
+        attrs["charge_mismatch"] = represented_charge != attrs["recomputed_charge"]
+
+    return target
+
+
+def graph_to_sanitized_kekule_mol(graph: nx.Graph) -> Chem.Mol:
+    """Reconstruct a product from ``kekule_order`` and let RDKit sanitize it."""
+    from synkit.IO.graph_to_mol import GraphToMol
+
+    refreshed = refresh_electron_fields(graph)
+    return GraphToMol(edge_attributes={"order": "kekule_order"}).graph_to_mol(
+        refreshed,
+        sanitize=True,
+        use_h_count=True,
+    )