molbuilder 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

molbuilder/dynamics/simulation.py

@@ -0,0 +1,209 @@
+"""MDSimulation orchestrator.
+
+High-level class that wires together ForceField, VelocityVerletIntegrator,
+and Trajectory to run plain or steered molecular dynamics from a Molecule.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from molbuilder.dynamics.forcefield import ForceField, ForceResult
+from molbuilder.dynamics.integrator import (
+    VelocityVerletIntegrator,
+    IntegratorState,
+    BerendsenThermostat,
+)
+from molbuilder.dynamics.trajectory import Trajectory, TrajectoryFrame
+
+if TYPE_CHECKING:
+    from molbuilder.molecule.graph import Molecule
+    from molbuilder.dynamics.mechanisms import ReactionMechanism
+    from molbuilder.dynamics.mechanism_choreography import MechanismChoreographer
+
+
+class MDSimulation:
+    """Molecular dynamics simulation orchestrator.
+
+    Builds a force field from a Molecule, initializes velocities at a
+    target temperature, and runs either plain or mechanism-steered MD,
+    recording every frame for visualization.
+
+    Parameters
+    ----------
+    molecule : Molecule
+        Starting molecular structure.
+    dt_fs : float
+        Integration timestep in femtoseconds.
+    temperature_K : float
+        Target temperature in Kelvin.
+    thermostat : bool
+        Whether to enable Berendsen thermostat.
+    thermostat_tau_fs : float
+        Coupling time for the thermostat.
+    record_interval : int
+        Record a trajectory frame every N steps.
+    """
+
+    def __init__(self, molecule: Molecule,
+                 dt_fs: float = 0.5,
+                 temperature_K: float = 300.0,
+                 thermostat: bool = True,
+                 thermostat_tau_fs: float = 100.0,
+                 record_interval: int = 1):
+        self.molecule = molecule
+        self.dt_fs = dt_fs
+        self.temperature_K = temperature_K
+        self.record_interval = record_interval
+
+        # Build force field
+        self.ff = ForceField.from_molecule(molecule)
+
+        # Set up thermostat
+        thermo = None
+        if thermostat:
+            thermo = BerendsenThermostat(temperature_K, thermostat_tau_fs)
+
+        # Set up integrator
+        self.integrator = VelocityVerletIntegrator(
+            dt_fs=dt_fs,
+            masses=self.ff.params.masses,
+            thermostat=thermo,
+        )
+
+        # Initialize state from molecule positions
+        positions = np.array([a.position for a in molecule.atoms], dtype=float)
+        velocities = self.integrator.initialize_velocities(
+            len(molecule.atoms), temperature_K)
+
+        self.state = IntegratorState(
+            positions=positions,
+            velocities=velocities,
+            time_fs=0.0,
+        )
+
+    def run(self, n_steps: int) -> Trajectory:
+        """Run plain molecular dynamics for n_steps.
+
+        Parameters
+        ----------
+        n_steps : int
+            Number of integration steps.
+
+        Returns
+        -------
+        Trajectory
+            Recorded trajectory with frames at record_interval spacing.
+        """
+        n_atoms = len(self.molecule.atoms)
+        traj = Trajectory(n_atoms)
+
+        def force_fn(pos):
+            return self.ff.compute(pos)
+
+        # Record initial frame
+        result = force_fn(self.state.positions)
+        ke = self.integrator.kinetic_energy(self.state.velocities)
+        traj.add_frame(TrajectoryFrame(
+            time_fs=self.state.time_fs,
+            positions=self.state.positions.copy(),
+            velocities=self.state.velocities.copy(),
+            energy_kinetic=ke,
+            energy_potential=result.energy_total,
+        ))
+
+        for step in range(1, n_steps + 1):
+            self.state = self.integrator.step(self.state, force_fn)
+
+            if step % self.record_interval == 0:
+                result = force_fn(self.state.positions)
+                ke = self.integrator.kinetic_energy(self.state.velocities)
+                traj.add_frame(TrajectoryFrame(
+                    time_fs=self.state.time_fs,
+                    positions=self.state.positions.copy(),
+                    velocities=self.state.velocities.copy(),
+                    energy_kinetic=ke,
+                    energy_potential=result.energy_total,
+                ))
+
+        return traj
+
+    def run_mechanism(self, mechanism: ReactionMechanism,
+                       n_steps_per_stage: int = 200) -> Trajectory:
+        """Run steered MD driven by a reaction mechanism.
+
+        The MechanismChoreographer applies time-varying restraint forces
+        to guide atoms through the mechanism stages, producing smooth
+        bond formation/breaking events.
+
+        Parameters
+        ----------
+        mechanism : ReactionMechanism
+            Reaction mechanism template.
+        n_steps_per_stage : int
+            Number of MD steps per mechanism stage.
+
+        Returns
+        -------
+        Trajectory
+            Recorded trajectory with fractional bond orders.
+        """
+        from molbuilder.dynamics.mechanism_choreography import MechanismChoreographer
+
+        n_atoms = len(self.molecule.atoms)
+        traj = Trajectory(n_atoms)
+        choreographer = MechanismChoreographer(
+            mechanism, self.ff, n_steps_per_stage)
+
+        n_stages = len(mechanism.stages)
+        total_steps = n_stages * n_steps_per_stage
+
+        for stage_idx in range(n_stages):
+            for step_in_stage in range(n_steps_per_stage):
+                progress = step_in_stage / max(1, n_steps_per_stage - 1)
+                global_step = stage_idx * n_steps_per_stage + step_in_stage
+
+                def force_fn(pos, _si=stage_idx, _pr=progress):
+                    ff_result = self.ff.compute(pos)
+                    restraint = choreographer.restraint_forces(
+                        pos, _si, _pr)
+                    ff_result.forces = ff_result.forces + restraint
+                    return ff_result
+
+                self.state = self.integrator.step(self.state, force_fn)
+
+                if global_step % self.record_interval == 0:
+                    result = self.ff.compute(self.state.positions)
+                    ke = self.integrator.kinetic_energy(self.state.velocities)
+                    bond_orders = choreographer.bond_orders_at(
+                        stage_idx, progress)
+                    traj.add_frame(TrajectoryFrame(
+                        time_fs=self.state.time_fs,
+                        positions=self.state.positions.copy(),
+                        velocities=self.state.velocities.copy(),
+                        energy_kinetic=ke,
+                        energy_potential=result.energy_total,
+                        bond_orders=bond_orders,
+                    ))
+
+        return traj
+
+    def get_positions_at_time(self, t_fs: float,
+                               trajectory: Trajectory) -> np.ndarray:
+        """Convenience interpolation of positions from a trajectory.
+
+        Parameters
+        ----------
+        t_fs : float
+            Time in femtoseconds.
+        trajectory : Trajectory
+            A previously recorded trajectory.
+
+        Returns
+        -------
+        ndarray of shape (n_atoms, 3)
+            Interpolated positions.
+        """
+        return trajectory.at_time(t_fs)

molbuilder/dynamics/trajectory.py

@@ -0,0 +1,215 @@
+"""Trajectory storage and sub-femtosecond interpolation.
+
+Stores MD frames and provides CubicSpline interpolation for
+requesting atomic positions at arbitrary time resolution, enabling
+extreme slow-motion visualization of atomic interactions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy.interpolate import CubicSpline
+
+
+@dataclass
+class TrajectoryFrame:
+    """A single snapshot from an MD simulation.
+
+    Attributes
+    ----------
+    time_fs : float
+        Simulation time in femtoseconds.
+    positions : ndarray of shape (n_atoms, 3)
+        Atomic positions in Angstroms.
+    velocities : ndarray of shape (n_atoms, 3) or None
+        Atomic velocities in A/fs (optional).
+    energy_kinetic : float
+        Kinetic energy in kJ/mol.
+    energy_potential : float
+        Potential energy in kJ/mol.
+    bond_orders : dict[tuple[int, int], float] or None
+        Fractional bond orders (for mechanism animations).
+    """
+    time_fs: float
+    positions: np.ndarray
+    velocities: np.ndarray | None = None
+    energy_kinetic: float = 0.0
+    energy_potential: float = 0.0
+    bond_orders: dict[tuple[int, int], float] | None = None
+
+    @property
+    def energy_total(self) -> float:
+        return self.energy_kinetic + self.energy_potential
+
+
+class Trajectory:
+    """Ordered collection of MD frames with CubicSpline interpolation.
+
+    The CubicSpline interpolation is the key to sub-femtosecond slow
+    motion: MD runs at discrete timesteps (e.g. 0.5 fs), but the
+    animation pipeline can request positions at any intermediate time.
+
+    Parameters
+    ----------
+    n_atoms : int
+        Number of atoms (must be consistent across all frames).
+    """
+
+    def __init__(self, n_atoms: int):
+        self.n_atoms = n_atoms
+        self.frames: list[TrajectoryFrame] = []
+        self._spline: CubicSpline | None = None
+        self._spline_dirty = True
+
+    def add_frame(self, frame: TrajectoryFrame):
+        """Append a frame to the trajectory."""
+        self.frames.append(frame)
+        self._spline_dirty = True
+
+    @property
+    def n_frames(self) -> int:
+        return len(self.frames)
+
+    @property
+    def times(self) -> np.ndarray:
+        """Array of frame times in fs."""
+        return np.array([f.time_fs for f in self.frames])
+
+    @property
+    def t_start(self) -> float:
+        """Start time of the trajectory in fs."""
+        if not self.frames:
+            return 0.0
+        return self.frames[0].time_fs
+
+    @property
+    def t_end(self) -> float:
+        """End time of the trajectory in fs."""
+        if not self.frames:
+            return 0.0
+        return self.frames[-1].time_fs
+
+    @property
+    def duration(self) -> float:
+        """Total duration in fs."""
+        return self.t_end - self.t_start
+
+    def _build_spline(self):
+        """Build or rebuild the CubicSpline interpolator."""
+        if len(self.frames) < 2:
+            self._spline = None
+            self._spline_dirty = False
+            return
+
+        times = self.times
+        # Flatten positions to (n_frames, n_atoms*3) for spline
+        pos_flat = np.array([f.positions.ravel() for f in self.frames])
+        self._spline = CubicSpline(times, pos_flat)
+        self._spline_dirty = False
+
+    def at_time(self, t_fs: float) -> np.ndarray:
+        """Interpolate atomic positions at an arbitrary time.
+
+        Parameters
+        ----------
+        t_fs : float
+            Time in femtoseconds.  Clamped to trajectory bounds.
+
+        Returns
+        -------
+        ndarray of shape (n_atoms, 3)
+            Interpolated positions in Angstroms.
+        """
+        if not self.frames:
+            raise ValueError("Trajectory is empty")
+
+        if len(self.frames) == 1:
+            return self.frames[0].positions.copy()
+
+        if self._spline_dirty:
+            self._build_spline()
+
+        t_fs = np.clip(t_fs, self.t_start, self.t_end)
+        flat = self._spline(t_fs)
+        return flat.reshape(self.n_atoms, 3)
+
+    def bond_order_at_time(self, t_fs: float, i: int, j: int) -> float:
+        """Interpolate fractional bond order between atoms i and j.
+
+        Parameters
+        ----------
+        t_fs : float
+            Time in femtoseconds.
+        i, j : int
+            Atom indices.
+
+        Returns
+        -------
+        float
+            Interpolated bond order (0.0 = no bond, 1.0 = single, etc.).
+        """
+        if not self.frames:
+            return 0.0
+
+        key = (min(i, j), max(i, j))
+        times = []
+        orders = []
+
+        for frame in self.frames:
+            if frame.bond_orders is not None and key in frame.bond_orders:
+                times.append(frame.time_fs)
+                orders.append(frame.bond_orders[key])
+
+        if len(times) < 2:
+            if orders:
+                return orders[0]
+            return 0.0
+
+        t_fs = np.clip(t_fs, times[0], times[-1])
+        spline = CubicSpline(np.array(times), np.array(orders))
+        return float(np.clip(spline(t_fs), 0.0, 4.0))
+
+    def energies(self) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Return energy arrays.
+
+        Returns
+        -------
+        times : ndarray
+            Frame times in fs.
+        ke : ndarray
+            Kinetic energies in kJ/mol.
+        pe : ndarray
+            Potential energies in kJ/mol.
+        """
+        times = self.times
+        ke = np.array([f.energy_kinetic for f in self.frames])
+        pe = np.array([f.energy_potential for f in self.frames])
+        return times, ke, pe
+
+    def positions_at_times(self, time_array: np.ndarray) -> np.ndarray:
+        """Interpolate positions at multiple times.
+
+        Parameters
+        ----------
+        time_array : ndarray of shape (n_times,)
+            Times in fs.
+
+        Returns
+        -------
+        ndarray of shape (n_times, n_atoms, 3)
+            Interpolated positions.
+        """
+        if self._spline_dirty:
+            self._build_spline()
+
+        if self._spline is None:
+            if self.frames:
+                pos = self.frames[0].positions
+                return np.tile(pos, (len(time_array), 1, 1))
+            raise ValueError("Trajectory is empty")
+
+        t_clamped = np.clip(time_array, self.t_start, self.t_end)
+        flat = self._spline(t_clamped)  # (n_times, n_atoms*3)
+        return flat.reshape(len(time_array), self.n_atoms, 3)

molbuilder/gui/app.py

@@ -57,6 +57,19 @@ class MolBuilderApp:
         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"))
 
+        # Simulate menu
+        simulate_menu = tk.Menu(menubar, tearoff=0)
+        menubar.add_cascade(label="Simulate", menu=simulate_menu)
+        simulate_menu.add_command(
+            label="MD Vibration...", command=self._sim_md_vibration)
+        simulate_menu.add_command(
+            label="Bond Formation...", command=self._sim_bond_formation)
+        simulate_menu.add_command(
+            label="SN2 Mechanism...", command=self._sim_sn2)
+        simulate_menu.add_separator()
+        simulate_menu.add_command(
+            label="Export Animation...", command=self._sim_export)
+
     def _build_ui(self):
         # Toolbar at top
         self.toolbar = MolToolbar(
@@ -275,6 +288,107 @@ class MolBuilderApp:
         except Exception as e:
             self.sidebar.show_results(f"Error: {e}")
 
+    # ---- Simulate menu commands ----
+
+    def _sim_md_vibration(self):
+        """Launch MD vibration simulation on the current molecule."""
+        mol = self.handler.mol
+        if not mol or len(mol.atoms) == 0:
+            messagebox.showwarning("Simulate", "No molecule loaded.")
+            return
+        try:
+            from molbuilder.visualization.interaction_viz import (
+                visualize_md_trajectory, PlaybackConfig,
+            )
+            self.status_var.set("Running MD simulation...")
+            self.root.update()
+            config = PlaybackConfig(show_electron_density=False)
+            visualize_md_trajectory(mol, n_steps=500, config=config)
+            self.status_var.set("MD simulation complete.")
+        except Exception as e:
+            messagebox.showerror("Simulation Error", str(e))
+
+    def _sim_bond_formation(self):
+        """Visualize bond formation between two selected atoms."""
+        mol = self.handler.mol
+        selected = list(self.handler.selected_atoms)
+        if len(selected) != 2:
+            messagebox.showinfo(
+                "Bond Formation",
+                "Select exactly 2 atoms first, then run this command.")
+            return
+        try:
+            from molbuilder.visualization.interaction_viz import (
+                visualize_bond_formation, PlaybackConfig,
+            )
+            self.status_var.set("Simulating bond formation...")
+            self.root.update()
+            config = PlaybackConfig(show_electron_density=True)
+            visualize_bond_formation(
+                mol, selected[0], selected[1], config=config)
+            self.status_var.set("Bond formation visualization complete.")
+        except Exception as e:
+            messagebox.showerror("Simulation Error", str(e))
+
+    def _sim_sn2(self):
+        """Run an SN2 mechanism demonstration."""
+        try:
+            from molbuilder.visualization.interaction_viz import (
+                visualize_reaction, PlaybackConfig,
+            )
+            from molbuilder.dynamics.mechanisms import sn2_mechanism
+            from molbuilder.molecule.builders import build_ethane
+
+            # Build a simple substrate (methane-like with a "leaving group")
+            mol = build_ethane(60.0)
+            mechanism = sn2_mechanism(
+                substrate_C=0, nucleophile=1, leaving_group=2)
+            self.status_var.set("Running SN2 mechanism...")
+            self.root.update()
+            config = PlaybackConfig(
+                show_electron_density=True,
+                show_electron_flows=True,
+            )
+            visualize_reaction(
+                mol, mechanism,
+                n_steps_per_stage=150, config=config)
+            self.status_var.set("SN2 mechanism visualization complete.")
+        except Exception as e:
+            messagebox.showerror("Simulation Error", str(e))
+
+    def _sim_export(self):
+        """Export the current molecule's MD animation to a file."""
+        mol = self.handler.mol
+        if not mol or len(mol.atoms) == 0:
+            messagebox.showwarning("Export", "No molecule loaded.")
+            return
+        from tkinter import filedialog
+        path = filedialog.asksaveasfilename(
+            parent=self.root,
+            title="Export Animation",
+            filetypes=[("GIF", "*.gif"), ("MP4", "*.mp4")],
+            defaultextension=".gif",
+        )
+        if not path:
+            return
+        try:
+            from molbuilder.visualization.interaction_viz import (
+                visualize_md_trajectory, PlaybackConfig,
+            )
+            self.status_var.set(f"Exporting animation to {path}...")
+            self.root.update()
+            config = PlaybackConfig(
+                export_path=path,
+                show_electron_density=False,
+            )
+            viz = visualize_md_trajectory(
+                mol, n_steps=300, config=config, show=False)
+            viz.export(path)
+            self.status_var.set(f"Exported: {path}")
+            messagebox.showinfo("Export", f"Animation saved to:\n{path}")
+        except Exception as e:
+            messagebox.showerror("Export Error", str(e))
+
     def run(self):
         """Start the application main loop."""
         self.root.mainloop()

molbuilder/visualization/__init__.py

@@ -1 +1,2 @@
-"""Visualization: Bohr models, orbital clouds, molecule rendering."""
+"""Visualization: Bohr models, orbital clouds, molecule rendering,
+and extreme slow-motion atomic interaction animations."""