vibeqc.normal_mode_trajectory

vibeqc.normal_mode_trajectory(mol, hessian_result, mode_index, *, amplitude=0.5, n_frames=20)[source]

Generate a list of Molecule frames sampling one vibrational normal mode for animated visualization.

The displacement pattern for atom i in mode p is the standard Wilson-FG normalisation:

Δr_i = (L_{ip} / sqrt(M_i)) · A · sin(2π · t / T)

where L is the mass-weighted normal-mode matrix, M_i the atomic mass (in electron-mass units), A is the amplitude (controlled by amplitude), and t runs through n_frames points over one full vibration period T.

Parameters:

  • mol (vibeqc._vibeqc_core.Molecule) – Reference Molecule (the equilibrium geometry).

  • hessian_result – HessianResult from any of the analytic-Hessian drivers or compute_hessian_fd(). Reads normal_modes, frequencies_cm1, and masses_amu.

  • mode_index (int) – Which mode to animate (0 = lowest, 3N − 1 = highest). Trans/rot zero modes (typically indices 0..5) animate as rigid translations / rotations and are usually not physically interesting; pick a higher index to see a vibration.

  • amplitude (float) – Maximum atomic displacement in bohr along the mode eigenvector. Default 0.5 bohr ≈ 0.26 Å — large enough to be visible in a molecular animation, small enough to stay in the harmonic regime.

  • n_frames (int) – Number of frames per period. Default 20. moltui plays back in a loop, so this controls both temporal resolution and playback speed.

Returns:

n_frames molecules, each with the equilibrium geometry + a sinusoidal displacement along mode p. Pair with write_xyz_trajectory() to drop into moltui:

frames = vq.normal_mode_trajectory(mol, hess, 8)
vq.write_xyz_trajectory("mode-8.xyz", frames)

Return type:

list[Molecule]

Notes

For zero modes (frequencies near 0), the eigenvector L_p still has well-defined norm but the “vibration” is an unphysical rigid translation/rotation. The function still writes a valid trajectory; visual inspection will show a translating / rotating cluster, which is sometimes useful as a sanity check on the Hessian projection.