vibrational_analysis

Numerical routines and file writers for vibrational analysis.

Summary

Classes:

VibrationalAnalysisResult

Result container for a vibrational analysis.

Functions:

`calculate`	Calculate wavenumbers, force constants, reduced masses and normal modes.
`calculate_from_system`	Calculate vibrational data from an AtomicSystem and Hessian.
`center_to_com`	Translate coordinates to the center of mass.
`force_constant`	Calculate force constants in mdyn A^-1.
`hessian_sign_factor`	Resolve a Hessian sign setting into a numeric factor.
`inertia_tensor`	Calculate the inertia tensor.
`infrared_intensity`	Calculate infrared intensities in km mol^-1.
`internal_coordinates`	Calculate normal modes from a mass-weighted Hessian.
`internal_subspace`	Calculate the internal-coordinate subspace.
`mass_weighted_hessian`	Symmetrize and mass-weight a Hessian.
`masses_matrix`	Create the mass-scaling matrix sqrt(m_i * m_j).
`mode_displacement`	Scale a mode for display.
`read_hessian_file`	Read a plain square Hessian matrix.
`reduced_mass`	Calculate reduced masses from normal-mode normalization factors.
`rotational_modes`	Calculate normalized rotational modes.
`select_mode_indices`	Select mode indices from a user-facing one-based mode selection.
`signed_sqrt`	Calculate a sign-preserving square root.
`symmetrize_addition`	Symmetrize a matrix by averaging it with its transpose.
`transformation_matrix`	Calculate the external-mode transformation matrix.
`translational_modes`	Calculate normalized translational modes.
`wavenumber`	Convert Hessian eigenvalues to wavenumbers.
`write_calculate_output`	Write the tabular vibrational analysis output.
`write_extxyz_modes`	Write selected normal modes to one extended XYZ file.
`write_normal_modes`	Write normal modes in matrix form.
`write_xyz_modes`	Write one sinusoidal XYZ trajectory per selected normal mode.

Reference

class VibrationalAnalysisResult( wavenumbers: ndarray, force_constants: ndarray, reduced_masses: ndarray, normal_modes: ndarray, intensities: ndarray | None = None, )[source]

Bases: object

Result container for a vibrational analysis.

force_constants: ndarray

intensities: ndarray | None = None

normal_modes: ndarray

reduced_masses: ndarray

wavenumbers: ndarray

calculate( atom_masses: ndarray, atom_coords: ndarray, hessian: ndarray, atom_charges: ndarray | None = None, unit: str = 'kcal', hessian_sign: str | float = 'auto', ) → VibrationalAnalysisResult[source]

Calculate wavenumbers, force constants, reduced masses and normal modes.

Parameters:

atom_masses (np.ndarray) – Atomic masses in amu.
atom_coords (np.ndarray) – Atomic coordinates with shape (n_atoms, 3).
hessian (np.ndarray) – Cartesian Hessian with shape (3 * n_atoms, 3 * n_atoms).
atom_charges (np.ndarray | None, optional) – Atomic charges used to calculate IR intensities, by default None.
unit (str, optional) – Hessian energy unit. Supported values are kcal, hartree and ev, by default kcal.
hessian_sign (str | float, optional) – Hessian sign convention. Supported values are auto, positive, negative, 1 and -1, by default auto.

calculate_from_system( system: AtomicSystem, hessian: ndarray, unit: str = 'kcal', hessian_sign: str | float = 'auto', atom_charges: ndarray | None = None, ) → VibrationalAnalysisResult[source]: Calculate vibrational data from an AtomicSystem and Hessian.

center_to_com( atom_coords: ndarray, atom_masses: ndarray, ) → ndarray[source]: Translate coordinates to the center of mass.

force_constant( omega: ndarray, reduced_masses: ndarray, ) → ndarray[source]: Calculate force constants in mdyn A^-1.

hessian_sign_factor( atom_coords: ndarray, atom_masses: ndarray, hessian: ndarray, hessian_sign: str | float, ) → float[source]: Resolve a Hessian sign setting into a numeric factor.

inertia_tensor( atom_coords: ndarray, atom_masses: ndarray, ) → ndarray[source]: Calculate the inertia tensor.

infrared_intensity( normal_modes: ndarray, atom_charges: ndarray, reduced_masses: ndarray, ) → ndarray[source]: Calculate infrared intensities in km mol^-1.

internal_coordinates( atom_coords: ndarray, atom_masses: ndarray, hessian_mw: ndarray, ) → tuple[ndarray, ndarray, ndarray][source]: Calculate normal modes from a mass-weighted Hessian.

internal_subspace( atom_coords: ndarray, atom_masses: ndarray, ) → ndarray[source]: Calculate the internal-coordinate subspace.

mass_weighted_hessian( hessian: ndarray, atom_masses: ndarray, sign: float = 1.0, ) → ndarray[source]: Symmetrize and mass-weight a Hessian.

masses_matrix( atom_masses: ndarray, ) → ndarray[source]: Create the mass-scaling matrix sqrt(m_i * m_j).

mode_displacement( mode: ndarray, wavenumber_value: float, amplitude: float = 0.25, temperature: float | None = None, threshold: float = 1e-08, ) → ndarray[source]: Scale a mode for display.

read_hessian_file(filename: str) → ndarray[source]

Read a plain square Hessian matrix.

Parameters:: filename (str) – The Hessian file.
Returns:: The square Hessian matrix.
Return type:: np.ndarray

reduced_mass( normalization: ndarray, ) → ndarray[source]: Calculate reduced masses from normal-mode normalization factors.

rotational_modes( atom_coords: ndarray, atom_masses: ndarray, ) → ndarray[source]: Calculate normalized rotational modes.

select_mode_indices( wavenumbers: ndarray, modes: str | list[int] | None = 'all', threshold: float = 1e-08, ) → list[int][source]: Select mode indices from a user-facing one-based mode selection.

signed_sqrt( values: ndarray, ) → ndarray[source]: Calculate a sign-preserving square root.

symmetrize_addition( hessian: ndarray, ) → ndarray[source]: Symmetrize a matrix by averaging it with its transpose.

transformation_matrix( atom_coords: ndarray, atom_masses: ndarray, ) → ndarray[source]: Calculate the external-mode transformation matrix.

translational_modes( atom_masses: ndarray, ) → ndarray[source]: Calculate normalized translational modes.

wavenumber( eigenvalues: ndarray, unit: str = 'kcal', ) → tuple[ndarray, ndarray][source]: Convert Hessian eigenvalues to wavenumbers.

write_calculate_output( result: VibrationalAnalysisResult, filename: str | None = None, ) → None[source]: Write the tabular vibrational analysis output.

write_extxyz_modes( normal_modes: ndarray, atom_coords: ndarray, atom_names: list[str], filename: str = 'modes.xyz', wavenumbers: ndarray | None = None, intensities: ndarray | None = None, modes: str | list[int] | None = 'all', threshold: float = 1e-08, ) → None[source]: Write selected normal modes to one extended XYZ file.

write_normal_modes( normal_modes: ndarray, filename: str | None = None, ) → None[source]: Write normal modes in matrix form.

write_xyz_modes( normal_modes: ndarray, atom_coords: ndarray, atom_names: list[str], filename: str = 'modes', amplitude: float = 0.25, step: float | None = None, *, wavenumbers: ndarray | None = None, modes: str | list[int] | None = 'all', n_frames: int | None = None, temperature: float | None = None, threshold: float = 1e-08, ) → None[source]: Write one sinusoidal XYZ trajectory per selected normal mode.