molbuilder 1.0.0__py3-none-any.whl

molbuilder/core/geometry.py

@@ -0,0 +1,232 @@
+"""
+3D geometry utilities for molecular coordinate construction.
+
+Public API for functions that were previously private (_normalize,
+_rotation_matrix, etc.) in molecular_conformations.py.  Also includes
+coordinate conversions from quantum_wavefunctions.py.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from molbuilder.molecule.graph import Molecule
+
+# Tolerance constants for near-zero comparisons
+_ZERO_VECTOR_TOL = 1e-12     # For zero-length vector detection
+_COLLINEAR_TOL = 1e-10       # For collinear atom detection
+
+
+# ===================================================================
+# Vector utilities
+# ===================================================================
+
+def normalize(v: np.ndarray) -> np.ndarray:
+    """Return unit vector, or zero vector if input is near-zero."""
+    n = np.linalg.norm(v)
+    if n < _ZERO_VECTOR_TOL:
+        return np.zeros(3)
+    return v / n
+
+
+def rotation_matrix(axis: np.ndarray, theta: float) -> np.ndarray:
+    """Rodrigues rotation matrix: rotate by *theta* radians about *axis*."""
+    u = normalize(axis)
+    K = np.array([
+        [0.0,   -u[2],  u[1]],
+        [u[2],   0.0,  -u[0]],
+        [-u[1],  u[0],  0.0],
+    ])
+    return np.eye(3) + math.sin(theta) * K + (1.0 - math.cos(theta)) * (K @ K)
+
+
+# ===================================================================
+# Z-matrix atom placement
+# ===================================================================
+
+def place_atom_zmatrix(pos_ref: np.ndarray,
+                       pos_angle_ref: np.ndarray,
+                       pos_dihedral_ref: np.ndarray,
+                       bond_length: float,
+                       bond_angle_deg: float,
+                       dihedral_deg: float) -> np.ndarray:
+    """Place an atom using internal (z-matrix) coordinates.
+
+    Given three reference positions (j, i, k), place a new atom m so that
+    distance(j,m)=bond_length, angle(i-j-m)=bond_angle_deg, and
+    dihedral(k-i-j-m)=dihedral_deg.
+
+    Parameters
+    ----------
+    pos_ref : position of bonded atom j.
+    pos_angle_ref : position of atom i (defines bond angle).
+    pos_dihedral_ref : position of atom k (defines dihedral).
+    bond_length, bond_angle_deg, dihedral_deg : internal coordinates.
+    """
+    theta = math.radians(bond_angle_deg)
+    phi = math.radians(dihedral_deg)
+
+    v_ij = normalize(pos_ref - pos_angle_ref)
+    v_ki = normalize(pos_angle_ref - pos_dihedral_ref)
+
+    # Plane normal
+    n = np.cross(v_ki, v_ij)
+    if np.linalg.norm(n) < _COLLINEAR_TOL:
+        # Collinear fallback
+        perp = np.array([1.0, 0.0, 0.0])
+        if abs(np.dot(v_ij, perp)) > 0.9:
+            perp = np.array([0.0, 1.0, 0.0])
+        n = np.cross(v_ij, perp)
+    n = normalize(n)
+
+    # In-plane perpendicular
+    d = normalize(np.cross(n, v_ij))
+
+    new_dir = (
+        -v_ij * math.cos(theta)
+        + d * math.sin(theta) * math.cos(phi)
+        + n * math.sin(theta) * math.sin(phi)
+    )
+    return pos_ref + bond_length * normalize(new_dir)
+
+
+# ===================================================================
+# Tetrahedral direction computation
+# ===================================================================
+
+def available_tetrahedral_dirs(
+        existing_dirs: list[np.ndarray],
+        count: int,
+) -> list[np.ndarray]:
+    """Compute *count* tetrahedral directions that avoid *existing_dirs*.
+
+    Given the unit-direction vectors of bonds already on a tetrahedral
+    centre, returns *count* new unit-direction vectors that complete the
+    tetrahedral arrangement.
+    """
+    n = len(existing_dirs)
+    tet_angle = math.acos(-1.0 / 3.0)  # ~109.47 deg
+
+    if n == 0:
+        dirs = [
+            np.array([1, 1, 1]) / math.sqrt(3),
+            np.array([1, -1, -1]) / math.sqrt(3),
+            np.array([-1, 1, -1]) / math.sqrt(3),
+            np.array([-1, -1, 1]) / math.sqrt(3),
+        ]
+        return dirs[:count]
+
+    if n == 1:
+        v0 = normalize(existing_dirs[0])
+        perp = np.array([1.0, 0.0, 0.0])
+        if abs(np.dot(v0, perp)) > 0.9:
+            perp = np.array([0.0, 1.0, 0.0])
+        p = normalize(np.cross(v0, perp))
+        q = normalize(np.cross(v0, p))
+
+        ct = math.cos(tet_angle)
+        st = math.sin(tet_angle)
+
+        dirs = []
+        for i in range(count):
+            phi = math.radians(120.0 * i)
+            d = v0 * ct + (p * math.cos(phi) + q * math.sin(phi)) * st
+            dirs.append(normalize(d))
+        return dirs
+
+    if n == 2:
+        v0 = normalize(existing_dirs[0])
+        v1 = normalize(existing_dirs[1])
+        bisector = normalize(v0 + v1)
+        out_of_plane = normalize(np.cross(v0, v1))
+
+        bv0 = float(np.dot(bisector, v0))
+        if abs(bv0) > _COLLINEAR_TOL:
+            cb = (1.0 / 3.0) / bv0
+        else:
+            cb = 0.0
+        cb = np.clip(cb, -1.0, 1.0)
+        sb = math.sqrt(max(0.0, 1.0 - cb * cb))
+
+        dirs = []
+        if count >= 1:
+            dirs.append(normalize(-bisector * cb + out_of_plane * sb))
+        if count >= 2:
+            dirs.append(normalize(-bisector * cb - out_of_plane * sb))
+        return dirs
+
+    if n >= 3:
+        centroid = normalize(sum(existing_dirs))
+        return [normalize(-centroid)][:count]
+
+    return []
+
+
+# ===================================================================
+# Hydrogen placement helper
+# ===================================================================
+
+def add_sp3_hydrogens(mol: Molecule, carbon_idx: int, count: int) -> None:
+    """Add *count* hydrogens to fill remaining tetrahedral positions.
+
+    Uses direct 3D geometry to find available tetrahedral directions
+    relative to the existing bonds on the carbon.
+
+    Parameters
+    ----------
+    mol : Molecule
+        Molecule object to modify in-place.
+    carbon_idx : int
+        Index of the atom to add hydrogens to.
+    count : int
+        Number of hydrogens to add.
+    """
+    from molbuilder.core.bond_data import bond_length as _bond_length
+
+    c_pos = mol.atoms[carbon_idx].position
+    existing = mol.neighbors(carbon_idx)
+    if not existing:
+        return
+
+    existing_dirs = [
+        normalize(mol.atoms[n].position - c_pos) for n in existing
+    ]
+
+    CH = _bond_length("C", "H", 1)
+    new_dirs = available_tetrahedral_dirs(existing_dirs, count)
+
+    for d in new_dirs:
+        h_pos = c_pos + CH * d
+        h_idx = mol.add_atom("H", h_pos)
+        mol.add_bond(carbon_idx, h_idx, order=1, rotatable=False)
+
+
+# ===================================================================
+# Coordinate conversions (from quantum_wavefunctions.py)
+# ===================================================================
+
+def cartesian_to_spherical(x, y, z):
+    """Convert (x, y, z) to (r, theta, phi).
+
+    theta: polar angle [0, pi],  phi: azimuthal [0, 2*pi].
+    """
+    x, y, z = np.asarray(x, float), np.asarray(y, float), np.asarray(z, float)
+    r = np.sqrt(x**2 + y**2 + z**2)
+    theta = np.where(r > 0, np.arccos(np.clip(z / np.where(r > 0, r, 1.0), -1, 1)), 0.0)
+    phi = np.arctan2(y, x) % (2 * np.pi)
+    return r, theta, phi
+
+
+def spherical_to_cartesian(r, theta, phi):
+    """Convert (r, theta, phi) to (x, y, z)."""
+    r = np.asarray(r, float)
+    theta = np.asarray(theta, float)
+    phi = np.asarray(phi, float)
+    x = r * np.sin(theta) * np.cos(phi)
+    y = r * np.sin(theta) * np.sin(phi)
+    z = r * np.cos(theta)
+    return x, y, z

molbuilder/gui/__init__.py

@@ -0,0 +1,2 @@
+"""Interactive 3D GUI for molecule building and analysis."""
+from molbuilder.gui.app import launch

molbuilder/gui/app.py

@@ -0,0 +1,286 @@
+"""Main tkinter application for the MolBuilder 3D GUI."""
+
+import tkinter as tk
+from tkinter import ttk, messagebox
+
+from molbuilder.gui.canvas3d import MolCanvas3D
+from molbuilder.gui.toolbar import MolToolbar
+from molbuilder.gui.sidebar import MolSidebar
+from molbuilder.gui.dialogs import SmilesDialog, FormulaDialog, file_open_dialog, file_save_dialog
+from molbuilder.gui.event_handler import MolEventHandler
+from molbuilder.molecule.graph import Molecule
+
+
+class MolBuilderApp:
+    """Main MolBuilder GUI application."""
+
+    def __init__(self):
+        self.root = tk.Tk()
+        self.root.title("MolBuilder - Molecular Engineering Tool")
+        self.root.geometry("1200x800")
+        self.root.configure(bg="#1a1a2e")
+
+        self.handler = MolEventHandler()
+        self._build_menu()
+        self._build_ui()
+        self._refresh()
+
+    def _build_menu(self):
+        menubar = tk.Menu(self.root)
+        self.root.config(menu=menubar)
+
+        # File menu
+        file_menu = tk.Menu(menubar, tearoff=0)
+        menubar.add_cascade(label="File", menu=file_menu)
+        file_menu.add_command(label="New", command=self._new)
+        file_menu.add_command(label="Open...", command=self._open)
+        file_menu.add_command(label="Save As...", command=self._save)
+        file_menu.add_separator()
+        file_menu.add_command(label="Exit", command=self.root.quit)
+
+        # Build menu
+        build_menu = tk.Menu(menubar, tearoff=0)
+        menubar.add_cascade(label="Build", menu=build_menu)
+        build_menu.add_command(label="From SMILES...", command=self._from_smiles)
+        build_menu.add_command(label="From Formula (VSEPR)...", command=self._from_formula)
+        build_menu.add_separator()
+        build_menu.add_command(label="Preset: Ethanol", command=lambda: self._preset("CCO", "ethanol"))
+        build_menu.add_command(label="Preset: Aspirin", command=lambda: self._preset("CC(=O)Oc1ccccc1C(=O)O", "aspirin"))
+        build_menu.add_command(label="Preset: Caffeine", command=lambda: self._preset("Cn1c(=O)c2c(ncn2C)n(C)c1=O", "caffeine"))
+        build_menu.add_command(label="Preset: Benzene", command=lambda: self._preset("c1ccccc1", "benzene"))
+        build_menu.add_command(label="Preset: Glucose", command=lambda: self._preset("OC[C@H]1OC(O)[C@H](O)[C@@H](O)[C@@H]1O", "glucose"))
+
+        # Analysis menu
+        analysis_menu = tk.Menu(menubar, tearoff=0)
+        menubar.add_cascade(label="Analysis", menu=analysis_menu)
+        analysis_menu.add_command(label="Detect Functional Groups", command=lambda: self._run_analysis("Functional Groups"))
+        analysis_menu.add_command(label="Bond Analysis", command=lambda: self._run_analysis("Bond Analysis"))
+        analysis_menu.add_command(label="Generate SMILES", command=lambda: self._run_analysis("SMILES"))
+
+    def _build_ui(self):
+        # Toolbar at top
+        self.toolbar = MolToolbar(
+            self.root,
+            on_element_selected=self._on_element,
+            on_bond_selected=self._on_bond,
+            on_action=self._on_action,
+        )
+        self.toolbar.pack(fill="x")
+
+        # Main area: canvas + sidebar
+        main = ttk.PanedWindow(self.root, orient="horizontal")
+        main.pack(fill="both", expand=True)
+
+        canvas_frame = ttk.Frame(main)
+        self.canvas = MolCanvas3D(canvas_frame)
+        main.add(canvas_frame, weight=3)
+
+        self.sidebar = MolSidebar(main, on_analyze=self._run_analysis)
+        main.add(self.sidebar, weight=1)
+
+        # Status bar
+        self.status_var = tk.StringVar(value="Ready")
+        status = ttk.Label(self.root, textvariable=self.status_var, relief="sunken")
+        status.pack(fill="x", side="bottom")
+
+    def _refresh(self):
+        """Re-render molecule and update sidebar."""
+        self.canvas.render(self.handler.mol)
+        self.sidebar.update_info(self.handler.mol)
+
+    def _on_element(self, sym):
+        self.handler.current_element = sym
+        self.status_var.set(f"Element: {sym}")
+
+    def _on_bond(self, order):
+        self.handler.current_bond_order = order
+        labels = {1: "Single", 2: "Double", 3: "Triple"}
+        self.status_var.set(f"Bond: {labels.get(order, '?')}")
+
+    def _on_action(self, action):
+        if action == "Add Atom":
+            self.handler.add_atom_free()
+        elif action == "Add Bond":
+            if not self.handler.add_bond_between_selected():
+                self.status_var.set("Select 2 atoms to bond")
+                return
+        elif action == "Delete":
+            self.handler.delete_selected()
+        elif action == "Add H":
+            self.handler.add_hydrogens()
+        elif action == "Clear":
+            self.handler.clear()
+        self._refresh()
+
+    def _new(self):
+        self.handler.clear()
+        self.handler.mol.name = "untitled"
+        self._refresh()
+
+    def _open(self):
+        path = file_open_dialog(self.root)
+        if not path:
+            return
+        try:
+            ext = path.rsplit(".", 1)[-1].lower()
+            if ext == "xyz":
+                from molbuilder.io.xyz import read_xyz
+                self.handler.mol = read_xyz(path)
+            elif ext in ("mol", "sdf"):
+                from molbuilder.io.mol_sdf import read_mol
+                self.handler.mol = read_mol(path)
+            elif ext == "pdb":
+                from molbuilder.io.pdb import read_pdb
+                self.handler.mol = read_pdb(path)
+            elif ext == "json":
+                from molbuilder.io.json_io import read_json
+                self.handler.mol = read_json(path)
+            else:
+                messagebox.showerror("Error", f"Unsupported format: .{ext}")
+                return
+            self.status_var.set(f"Opened: {path}")
+            self._refresh()
+        except Exception as e:
+            messagebox.showerror("Error", str(e))
+
+    def _save(self):
+        path = file_save_dialog(self.root)
+        if not path:
+            return
+        try:
+            ext = path.rsplit(".", 1)[-1].lower()
+            if ext == "xyz":
+                from molbuilder.io.xyz import write_xyz
+                write_xyz(self.handler.mol, path)
+            elif ext == "mol":
+                from molbuilder.io.mol_sdf import write_mol
+                write_mol(self.handler.mol, path)
+            elif ext == "pdb":
+                from molbuilder.io.pdb import write_pdb
+                write_pdb(self.handler.mol, path)
+            elif ext == "json":
+                from molbuilder.io.json_io import write_json
+                write_json(self.handler.mol, path)
+            elif ext == "smi":
+                from molbuilder.io.smiles_io import write_smiles
+                write_smiles(self.handler.mol, path)
+            else:
+                messagebox.showerror("Error", f"Unsupported format: .{ext}")
+                return
+            self.status_var.set(f"Saved: {path}")
+        except Exception as e:
+            messagebox.showerror("Error", str(e))
+
+    def _from_smiles(self):
+        dlg = SmilesDialog(self.root)
+        if dlg.result:
+            smi, name = dlg.result
+            try:
+                from molbuilder.smiles import parse
+                mol = parse(smi)
+                mol.name = name or smi
+                self.handler.mol = mol
+                self.handler.selected_atoms.clear()
+                self.status_var.set(f"Built from SMILES: {smi}")
+                self._refresh()
+            except Exception as e:
+                messagebox.showerror("SMILES Error", str(e))
+
+    def _from_formula(self):
+        dlg = FormulaDialog(self.root)
+        if dlg.result:
+            formula, charge = dlg.result
+            try:
+                from molbuilder.bonding.vsepr import VSEPRMolecule
+                vsepr = VSEPRMolecule(formula, charge)
+                # Convert VSEPR coords to Molecule
+                coords = vsepr.coordinates
+                mol = Molecule(formula)
+                for sym, pos in coords["atom_positions"]:
+                    if sym is not None and pos is not None:
+                        mol.add_atom(sym, pos)
+                for ai, aj, order in coords["bonds"]:
+                    mol.add_bond(ai, aj, order, rotatable=False)
+                self.handler.mol = mol
+                self.handler.selected_atoms.clear()
+                self.status_var.set(f"Built {formula} via VSEPR")
+                self._refresh()
+            except Exception as e:
+                messagebox.showerror("Formula Error", str(e))
+
+    def _preset(self, smiles, name):
+        try:
+            from molbuilder.smiles import parse
+            mol = parse(smiles)
+            mol.name = name
+            self.handler.mol = mol
+            self.handler.selected_atoms.clear()
+            self.status_var.set(f"Loaded preset: {name}")
+            self._refresh()
+        except Exception as e:
+            messagebox.showerror("Error", str(e))
+
+    def _run_analysis(self, name):
+        mol = self.handler.mol
+        if not mol or len(mol.atoms) == 0:
+            self.sidebar.show_results("No molecule loaded.")
+            return
+
+        try:
+            if name == "Functional Groups":
+                from molbuilder.reactions.functional_group_detect import detect_functional_groups
+                groups = detect_functional_groups(mol)
+                if groups:
+                    lines = [f"Found {len(groups)} functional group(s):\n"]
+                    for g in groups:
+                        lines.append(f"  {g.name} (atom {g.center})")
+                    self.sidebar.show_results("\n".join(lines))
+                else:
+                    self.sidebar.show_results("No functional groups detected.")
+
+            elif name == "Bond Analysis":
+                lines = [f"Bond Analysis: {mol.name}\n"]
+                lines.append(f"{'Bond':<12} {'Order':>5} {'Length':>8}")
+                lines.append("-" * 30)
+                for b in mol.bonds:
+                    sa = mol.atoms[b.atom_i].symbol
+                    sb = mol.atoms[b.atom_j].symbol
+                    d = mol.distance(b.atom_i, b.atom_j)
+                    sym = {1: "-", 2: "=", 3: "#"}.get(b.order, "?")
+                    lines.append(f"{sa}{sym}{sb:<8} {b.order:>5} {d:>7.3f} A")
+                self.sidebar.show_results("\n".join(lines))
+
+            elif name == "SMILES":
+                from molbuilder.smiles.writer import to_smiles
+                smi = to_smiles(mol)
+                self.sidebar.show_results(f"SMILES: {smi}")
+
+            elif name == "Stereochemistry":
+                lines = ["Stereochemistry Analysis:\n"]
+                for i, atom in enumerate(mol.atoms):
+                    if atom.symbol == "H":
+                        continue
+                    nbrs = mol.neighbors(i)
+                    if len(nbrs) == 4:
+                        desc = mol.assign_rs(i)
+                        if desc.name != "NONE":
+                            lines.append(f"  {atom.symbol}[{i}]: {desc.name}")
+                if len(lines) == 1:
+                    lines.append("  No stereocenters found.")
+                self.sidebar.show_results("\n".join(lines))
+
+            else:
+                self.sidebar.show_results(f"Analysis '{name}' not yet implemented.")
+
+        except Exception as e:
+            self.sidebar.show_results(f"Error: {e}")
+
+    def run(self):
+        """Start the application main loop."""
+        self.root.mainloop()
+
+
+def launch():
+    """Launch the MolBuilder GUI."""
+    app = MolBuilderApp()
+    app.run()

molbuilder/gui/canvas3d.py

@@ -0,0 +1,115 @@
+"""Embedded matplotlib 3D canvas for tkinter."""
+
+import numpy as np
+import matplotlib
+matplotlib.use("TkAgg")
+from matplotlib.backends.backend_tkagg import FigureCanvasTkAgg, NavigationToolbar2Tk
+from matplotlib.figure import Figure
+from mpl_toolkits.mplot3d import Axes3D
+
+from molbuilder.core.element_properties import cpk_color, covalent_radius_pm
+from molbuilder.visualization.theme import BG_COLOR, TEXT_COLOR, GRID_COLOR, BOND_COLOR
+
+
+class MolCanvas3D:
+    """3D molecule viewport embedded in a tkinter frame."""
+
+    def __init__(self, parent_frame):
+        self.parent = parent_frame
+        self.fig = Figure(figsize=(7, 6), facecolor=BG_COLOR)
+        self.ax = self.fig.add_subplot(111, projection="3d", facecolor=BG_COLOR)
+
+        self.canvas = FigureCanvasTkAgg(self.fig, master=parent_frame)
+        self.canvas.get_tk_widget().pack(fill="both", expand=True)
+
+        self.toolbar = NavigationToolbar2Tk(self.canvas, parent_frame)
+        self.toolbar.update()
+
+        self._style_axes()
+        self.mol = None
+        self._pick_callback = None
+
+    def _style_axes(self):
+        """Apply dark theme to 3D axes."""
+        for pane in [self.ax.xaxis.pane, self.ax.yaxis.pane, self.ax.zaxis.pane]:
+            pane.set_facecolor(BG_COLOR)
+            pane.set_edgecolor(GRID_COLOR)
+        self.ax.tick_params(colors=TEXT_COLOR, labelsize=7)
+        self.ax.set_xlabel("x (A)", color=TEXT_COLOR, fontsize=8)
+        self.ax.set_ylabel("y (A)", color=TEXT_COLOR, fontsize=8)
+        self.ax.set_zlabel("z (A)", color=TEXT_COLOR, fontsize=8)
+
+    def set_pick_callback(self, callback):
+        """Set callback for atom picking: callback(atom_index)."""
+        self._pick_callback = callback
+
+    def render(self, mol):
+        """Render a Molecule object."""
+        self.mol = mol
+        self.ax.clear()
+        self._style_axes()
+
+        if mol is None or len(mol.atoms) == 0:
+            self.canvas.draw()
+            return
+
+        # Draw bonds
+        for bond in mol.bonds:
+            pa = mol.atoms[bond.atom_i].position
+            pb = mol.atoms[bond.atom_j].position
+            if bond.order == 1:
+                self.ax.plot([pa[0], pb[0]], [pa[1], pb[1]], [pa[2], pb[2]],
+                             color=BOND_COLOR, linewidth=2.0, zorder=3)
+            elif bond.order == 2:
+                mid = (pa + pb) / 2
+                perp = self._perp_offset(pa, pb, 0.06)
+                for s in [1, -1]:
+                    self.ax.plot([pa[0] + s * perp[0], pb[0] + s * perp[0]],
+                                [pa[1] + s * perp[1], pb[1] + s * perp[1]],
+                                [pa[2] + s * perp[2], pb[2] + s * perp[2]],
+                                color=BOND_COLOR, linewidth=1.8, zorder=3)
+            elif bond.order == 3:
+                self.ax.plot([pa[0], pb[0]], [pa[1], pb[1]], [pa[2], pb[2]],
+                             color=BOND_COLOR, linewidth=2.0, zorder=3)
+                perp = self._perp_offset(pa, pb, 0.07)
+                for s in [1, -1]:
+                    self.ax.plot([pa[0] + s * perp[0], pb[0] + s * perp[0]],
+                                [pa[1] + s * perp[1], pb[1] + s * perp[1]],
+                                [pa[2] + s * perp[2], pb[2] + s * perp[2]],
+                                color=BOND_COLOR, linewidth=1.2, zorder=3)
+
+        # Draw atoms
+        for atom in mol.atoms:
+            color = cpk_color(atom.symbol)
+            size = 120 + covalent_radius_pm(atom.symbol) * 0.6
+            self.ax.scatter(*atom.position, c=color, s=size,
+                            edgecolors="white", linewidths=0.3,
+                            alpha=0.92, zorder=5, depthshade=True)
+            self.ax.text(atom.position[0] + 0.06, atom.position[1] + 0.06,
+                         atom.position[2] + 0.06, atom.symbol,
+                         color=TEXT_COLOR, fontsize=8, fontweight="bold", zorder=10)
+
+        # Auto-scale
+        all_pos = np.array([a.position for a in mol.atoms])
+        if len(all_pos) > 0:
+            mx = max(np.max(np.abs(all_pos)) * 1.4, 1.0)
+            self.ax.set_xlim(-mx, mx)
+            self.ax.set_ylim(-mx, mx)
+            self.ax.set_zlim(-mx, mx)
+
+        self.ax.set_title(mol.name or "Molecule", color=TEXT_COLOR, fontsize=11)
+        self.canvas.draw()
+
+    @staticmethod
+    def _perp_offset(pa, pb, mag):
+        """Compute a perpendicular offset vector for drawing multi-bonds."""
+        d = pb - pa
+        n = np.linalg.norm(d)
+        if n < 1e-10:
+            return np.array([mag, 0, 0])
+        d = d / n
+        ref = np.array([1.0, 0, 0])
+        if abs(np.dot(d, ref)) > 0.9:
+            ref = np.array([0, 1.0, 0])
+        p = np.cross(d, ref)
+        return p / np.linalg.norm(p) * mag