tako.vibration Settings

Page type: Reference · Generated from src/script/takoScriptDocs.ts · Verified 2026-07-11T00:00:00.000Z

On this page

tako.vibration

This page is generated from code-owned Doxygen-style metadata in src/script/takoScriptDocs.ts. Update that file first, then regenerate this page so runtime capability descriptions, docs, and agent guidance stay aligned.

tako.vibration

Runs molecular finite-difference vibrational analysis and optional IR/Raman spectra.

Signature: await tako.vibration(structure, { calculator, properties, vibrationDisplacementAngstrom, vibrationNfree, spectroscopy })

Theory

Molecular vibrations are computed from finite differences of forces around a stationary geometry. The mass-weighted Hessian gives normal-mode frequencies and displacement vectors.
IR intensity comes from dipole derivative estimates, while Raman intensity comes from polarizability derivative estimates where the calculator supports them. These are approximate model-dependent spectra.
A geometry with large residual forces can produce misleading low-frequency or imaginary modes. Optimize before vibration analysis unless intentionally probing an unstable structure.

Usage Notes

Use vibration for finite molecules. For periodic crystals, use tako.phonon instead.
Use vibrationNfree: 4 for a more expensive finite-difference stencil when numerical stability matters.
Request only the spectroscopy channels needed for the report to avoid extra derivative work.

Settings

Setting	Type	Default	Values	Validation	Description
`calculator`	calculator			Required for calculator-backed operations; validate the operation, structure element coverage, and requested properties before execution	Calculator object from `tako.calculator.gxtb(...)`, `gfn2(...)`, `mlip(...)`, or `dft(...)`. It controls the level of theory, charge/spin where supported, runtime assets, property availability, and the synchronous supported-element list used by TakoScript and the UI.
`properties`	properties	`level-dependent normalization; MLIP: ['energy', 'forces']; GFN2: ['energy', 'forces', 'charges', 'dos', 'pdos']`	`energy`, `forces`, `stress`, `dos`, `pdos`, `charges`, `electronDensity`, `chargeDensity`, `nci`, `molden`, `wfn`, `hdf5`, `orbitals`, `spinDensity`, `esp`, `densityDerivatives`, `fukui`, `elf`	Unknown names are removed and energy/forces are reinserted. Vibration response channels are selected with spectroscopy; normalized electronic property names do not create single-point post-processing.	Shared calculator property request retained in calculation settings. This setting does not request IR/Raman and charges, DOS/PDOS, density, NCI, or WFN are not returned by the vibration operation.
`vibrationDisplacementAngstrom`	number	`0.01`			Finite-difference displacement in A. Too small amplifies force noise; too large samples anharmonic curvature.
`vibrationNfree`	enum	`2`	`2`, `4`		Finite-difference stencil. `2` is cheaper central difference; `4` uses more force evaluations for a higher-order estimate.
`spectroscopy`	array	`['frequencies', 'infrared', 'raman']`	`frequencies`, `infrared`, `raman`		Requested vibrational outputs. `frequencies` gives modes, `infrared` adds IR intensities, and `raman` adds Raman activity where supported.
`thermoTemperatureK`	number	`298.15`			Evaluation temperature for the thermochemistry payload (ideal-gas G/H/S for molecules, harmonic U/S/F for periodic structures).
`thermoPressurePa`	number	`100000`			Ideal-gas reference pressure in Pa (1 bar) for the translational entropy and G.
`thermoSymmetryNumber`	number	`1`			Rotational symmetry number σ for the ideal-gas rotational entropy (e.g. H2O 2, NH3 3, benzene 12).

Example

const molecule = await tako.input("input/water.extxyz");
const calculator = tako.calculator.gfn2({ dispersion: "d4" });
const result = await tako.vibration(molecule, {
  calculator,
  vibrationDisplacementAngstrom: 0.01,
  vibrationNfree: 2,
  spectroscopy: ["frequencies", "infrared"],
});
await tako.output("output/vibrations.json", result);

Result

Returned vibration object with mode frequencies, Cartesian displacement vectors, harmonic zero-point energy, and optional GFN2 IR/Raman response payloads. Interface workspace artifacts are derived outside this returned object.

Field	Type	Unit	Availability	Description
`kind`	”vibration”		Every successful result	Runtime result discriminator.
`level_of_theory`	string		Every successful result	Normalized calculator level used for every displacement.
`engine`	”gfn2” \| “mlip”		Every successful result	Calculator engine family.
`vibrations`	object		Every successful result	Normal-mode result from the force finite-difference pass.
`vibrations.frequencies_cm_inv`	number[]	cm^-1	Every successful result	Signed real frequency list; imaginary components are represented as negative numbers.
`vibrations.frequency_components`	{ real: number, imaginary: number }[]	cm^-1	Every successful result	Real and imaginary frequency components without collapsing the sign convention.
`vibrations.energies_hartree`	{ real: number, imaginary: number }[]	Hartree	Every successful result	Complex harmonic quantum energy associated with each mode.
`vibrations.zero_point_energy_hartree`	number	Hartree	Every successful result	Harmonic zero-point energy returned by the vibration backend.
`vibrations.zero_point_energy_ev`	number	eV	Every successful result	The same harmonic zero-point energy converted to electronvolts.
`vibrations.modes`	number[mode][atom][3]		Every successful result	Cartesian displacement vectors M^-1/2 e derived from the normalized mass-weighted eigenvectors, in input atom order; fixed atoms have zero vectors.
`thermochemistry`	object		When the thermochemistry post-processing succeeds (molecular: ideal-gas G/H/S; periodic: harmonic U/S/F)	Free thermochemistry computed from the vibrational modes at the configured temperature, pressure, and symmetry number, including a 50–1000 K sweep.
`thermochemistry.model`	string		With thermochemistry	’idealGas’ for molecules, ‘harmonic’ for periodic structures.
`thermochemistry.temperature_k`	number	K	With thermochemistry	Evaluation temperature for the headline values.
`thermochemistry.zero_point_energy_ev`	number	eV	With thermochemistry	Harmonic zero-point energy.
`thermochemistry.internal_energy_ev`	number	eV	With thermochemistry	Internal energy U(T) including the electronic energy.
`thermochemistry.enthalpy_ev`	number	eV	Ideal-gas model	Enthalpy H(T) = U + kB·T.
`thermochemistry.entropy_j_per_mol_k`	number	J·mol⁻¹·K⁻¹	With thermochemistry	Entropy S(T); ideal gas includes translation, rotation, vibration, and electronic spin terms at the configured pressure.
`thermochemistry.gibbs_energy_ev`	number	eV	Ideal-gas model	Gibbs free energy G(T, P) = H − T·S.
`thermochemistry.helmholtz_energy_ev`	number	eV	Harmonic model	Helmholtz free energy F(T) = U − T·S.
`thermochemistry.imaginary_modes`	integer		With thermochemistry	Number of imaginary modes ignored in the sums; nonzero means the geometry is not a clean minimum.
`thermochemistry.sweep`	object		With thermochemistry	temperatures_k plus gibbs_energy_ev (ideal gas) or helmholtz_energy_ev (harmonic) and entropy_j_per_mol_k arrays over 50–1000 K.
`infrared`	object		Only when IR was requested and a GFN2 response calculation returned it	Infrared finite-difference response payload; omitted for MLIP.
`infrared.vibrations`	vibration object		With infrared payload	Mode data computed during the dipole-response finite-difference pass.
`infrared.intensities_au`	number[]	(D/Å)^2 amu^-1	With infrared payload	Per-mode ASE-convention infrared intensities. The field name is a historical alias and does not mean the stored values remain in raw atomic units.
`infrared.static_dipole_au`	number	e a0	With infrared payload	Norm of the undisplaced molecular dipole vector in atomic units.
`infrared.max_force_hartree_per_bohr`	number	Hartree Bohr^-1	With infrared payload	Maximum force diagnostic at the undisplaced response geometry.
`raman`	object		Only when Raman was requested and a GFN2 response calculation returned it	Finite-field polarizability-response payload; omitted for MLIP.
`raman.vibrations`	vibration object		With Raman payload	Mode data computed during the polarizability-response finite-difference pass.
`raman.activities`	number[]	Å^4 amu^-1	With Raman payload	Per-mode Placzek Raman activities using zero weight for the antisymmetric anisotropy term.
`raman.absolute_intensities`	number[]	Å^4 amu^-1	With Raman payload	Current runtime alias of the same zero-antisymmetric-weight Raman activities; it is not a temperature- or laser-dependent experimental intensity.
`raman.invariants`	{ alpha2: number, gamma2: number, delta2: number }[]	raw atomic-unit squared derivative invariant	With Raman payload	Per-mode isotropic, symmetric-anisotropic, and antisymmetric polarizability-derivative invariants before the activity conversion.
`raman.invariants[].alpha2`	number	raw atomic-unit squared derivative invariant	With Raman payload	Squared isotropic mode-polarizability derivative before conversion.
`raman.invariants[].gamma2`	number	raw atomic-unit squared derivative invariant	With Raman payload	Squared symmetric-anisotropic mode-polarizability derivative before conversion.
`raman.invariants[].delta2`	number	raw atomic-unit squared derivative invariant	With Raman payload	Squared antisymmetric mode-polarizability derivative before conversion; the current activity arrays assign it zero weight.

Errors and Promise Behavior

Rejects if the normalized structure or calculator input cannot be evaluated for the required displaced geometries.
Fails when a displaced force, dipole, or polarizability evaluation fails; partial response data is not promoted to a successful result.
IR and Raman requested with an MLIP are logged and omitted rather than returned as zero-valued spectra.