vibe-qcDocumentation

Anharmonic vibrations: n-mode PES, VSCF and VCI

Status: under review (#840). The vibrational Hamiltonian, VSCF, VCI, the molecular and BIPOLE Gamma providers, the symmetry adaptation, the X-H stretch, the matrix-free VCI, molecular anharmonic IR intensities and their validation are on main; the matched CRYSTAL23 ANHARM/ANHAPES/VSCF/VCI comparisons are owed.

vibeqc.vibrational computes anharmonic vibrational levels from a potential energy surface written in mass-weighted normal coordinates. It is one vibrational Hamiltonian with one provider interface: the same code serves analytic model potentials, molecules and periodic cells, and it does not depend on the electronic method that produced the energies. It follows the anharmonic module of CRYSTAL23 (ANHAPES, VSCF, VCI and the one-dimensional ANHARM; Erba et al., J. Chem. Theory Comput. 19, 6891 (2023), DOI 10.1021/acs.jctc.2c00958, section 7, and the CRYSTAL23 manual, sections 8.11 and 8.12).

Coordinates and units

Mode i has the mass-weighted normal coordinate Q_i (atomic units: bohr times the square root of the electron mass) and the harmonic frequency omega_i (Hartree, with hbar = 1). Grids and fits use the dimensionless coordinate x_i = sqrt(omega_i) Q_i; the classical turning point of level n of a harmonic mode is x = sqrt(2n + 1). The vibrational Hamiltonian is

H = sum_i -1/2 d^2/dQ_i^2 + V(Q)

(CRYSTAL23 paper Eq. 80, manual Eq. 8.30): no rotation-vibration coupling and rectilinear normal coordinates. Energies are reported in Hartree and transitions in cm^-1.

The n-mode potential

build_nmode_pes(provider, PESSettings(...)) samples a provider and writes the surface as an explicit n-mode expansion about the reference geometry,

V(Q) = sum_i V_i(Q_i) + sum_(i<j) V_ij(Q_i, Q_j) + sum_(i<j<k) V_ijk(Q_i, Q_j, Q_k),

where each term is the energy at a displacement along its modes minus every lower-order term (a cut expansion). mode_coupling truncates it after one, two (default) or three coupled modes: the 1M, 2M and 3M representations of the CRYSTAL23 paper (Eqs. 85 to 87). Two representations are declared and recorded:

representation="polynomial" (default)

Energies on a grid, fitted by least squares in x. The one-mode grid is x = +-0.5, +-1.0, ..., +-3.0 (one_mode_step, one_mode_points) and the fit has powers 1 to 8 (one_mode_degree; one_mode_degree=6 is the sextic fit of CRYSTAL’s ANHARM, which misses the H2/STO-3G stretch fundamental by 6.4 cm^-1 where the octic fit misses it by 0.09 cm^-1, see below). Two-mode terms use x = +-0.75, +-1.5, +-2.25 on both axes (36 points per pair) and the monomials x_i^a x_j^b with a, b >= 1 and a + b <= 6 (two_mode_degree). Three-mode terms use x = +-0.75, +-1.5 (64 points per triple) and a + b + c <= 6. two_mode_degree=4 and three_mode_degree=4 give the 2M4T and 3M4T force constants of Eqs. 86 and 87; the default is sextic because a quartic coupling fitted over the range the states probe left 15 to 25 cm^-1 of fit error in the stretch fundamentals of water (see the molecular validation below). Every coupling axis value is also a one-mode point, so the subtraction uses sampled energies, not fitted ones. The grid energies, the coefficients, the force constants they imply (pes.force_constants(), the eta of Eqs. 82 to 84) and the rms and largest fit residuals are recorded. The linear coefficient of each one-mode fit measures the residual gradient along the mode, the quadratic one the harmonic consistency (pes_one_mode_curvature_ratio, which is 1 when the sampled curvature equals omega^2).

representation="quadrature"

The terms are evaluated directly at the Gauss-Hermite nodes of the vibrational basis. There is no fit error, at the cost of M K one-mode, C(M,2) K^2 two-mode and C(M,3) K^3 three-mode energies for K nodes per mode. It is meant for one or two modes, or for checking a fit.

With the default polynomial grid the number of energies is 1 + 12 M + 36 C(M,2) (+ 64 C(M,3)) plus 4 one-mode points per mode for the coupling axis values: 13 for one mode, 157 for three modes in 2M, 221 in 3M. estimate_single_points(M, settings) returns it before anything is computed, and a PES above max_single_points (2000) is refused.

Refusals

The vibrational solvers need a surface that is bounded below where the basis probes it. Refused by name (VibrationalRefusal) before any vibrational solve:

  • a non-positive harmonic frequency: the reference is a saddle point along that mode, the barrier of a double well;

  • a one-mode potential with two minima below the reference (a double well; tunnelling between wells is not implemented);

  • a one-mode potential that falls below the reference further than |x| = 0.25 from it, or at the edge of the probed range: the reference is not the minimum along the mode (a lower well, a fit hole or a geometry that is not stationary). A single shallow minimum within |x| <= 0.25 is the shift a residual gradient or a least-squares fit gives a stationary point, and is accepted;

  • an odd one_mode_degree (an odd polynomial is unbounded below). A fit whose highest power has a negative coefficient (for example a bending potential that flattens at large amplitude) is a valid representation where the basis probes it and is accepted with pes_one_mode_asymptotically_bounded = False recorded; once the basis reaches the turnover the previous rule refuses it;

  • a coupled 2M or 3M surface with a hole below the reference on the quadrature grid, into which VSCF and VCI would collapse.

One-mode levels

solve_one_mode(potential, omega, n_basis=24) solves one coordinate in the first n_basis harmonic-oscillator functions of frequency omega. The kinetic matrix is exact for the truncated basis; the potential enters by Gauss-Hermite quadrature on n_quadrature nodes (default n_basis + 4), which is exact for polynomial potentials up to degree 2 n_quadrature - 2 n_basis + 1 (9 by default, so every default fit is integrated exactly). With n_quadrature = n_basis this is the harmonic-oscillator discrete variable representation. The result carries the levels and, as CRYSTAL’s ANHARM does (manual section 8.11), the anharmonicity constant and harmonic frequency from the first two transitions: omega_e x_e = (2 omega_01 - omega_02) / 2 and omega_e = omega_01 + 2 omega_e x_e.

import numpy as np
from vibeqc.vibrational import ModelProvider, PESSettings, build_nmode_pes, solve_one_mode
from vibeqc.constants import HARTREE_TO_CM1

D, we = 0.17, 4400.0 / HARTREE_TO_CM1          # Morse well, unit mass
a = we / np.sqrt(2 * D)
prov = ModelProvider([we], lambda Q: D * (1 - np.exp(-a * Q[..., 0])) ** 2)
pes = build_nmode_pes(prov, PESSettings())     # 13 energies, octic fit
pes.check_admissible(pes.default_bases(30))
lev = solve_one_mode(pes.one[0], we, n_basis=30)
print(lev.fundamental_cm1, lev.omega_e_x_e_cm1)

Validation of the one-mode solver

Measured in tests/test_vibrational_anharmonic.py:

Case

Reference

Result

Quadrature

exact powers of the position operator

matrix elements of x^p exact for p <= 2K - 2N + 1, not beyond

Harmonic

omega (n + 1/2)

1e-12 relative

Pure quartic lambda Q^4

lambda^(1/3) scaling, virial <T> = 2<V>, sinc-DVR

1e-11 relative, 1e-9 relative, 1e-9 Ha; ground state 0.6679862591 Ha at lambda = 1

Morse, 4400 cm^-1, D = 0.17 Ha

exact omega_e (n + 1/2) - omega_e x_e (n + 1/2)^2

six levels within 1e-10 Ha (60 functions); ANHARM relations give omega_e and omega_e x_e back to 1e-6 cm^-1; fundamental error 2.8e-2, 5e-7, 2.5e-11 cm^-1 at 10, 20, 30 functions

Same Morse through the polynomial PES

exact fundamental 4140.56 cm^-1

fit error 0.65 cm^-1 (sextic), 0.005 cm^-1 (octic); the quadrature representation has none

Weak cubic plus quartic anharmonicity

second-order perturbation theory, nu = omega + 2 xi, 16 omega^2 xi = eta_4 - 5 eta_3^2 / (3 omega^2) (Barone, J. Chem. Phys. 122, 014108 (2005), DOI 10.1063/1.1824881, Eqs. 36 and 43)

difference falls 16-fold when the anharmonicity is halved; the fit returns eta_3 and eta_4 to 1e-9

The Morse case also shows why the fit is a separate error: the sextic polynomial over |x| <= 3 misses the fundamental by 0.65 cm^-1, a finer grid over a narrower range (one_mode_step=0.25) by 1.9 cm^-1 because the quadrature then extrapolates the fit.

X-H stretch with only the light atom moving

compute_molecular_xh_stretch(molecule, basis, method, atom=i) and compute_bipole_xh_stretch(system, basis, kmesh, options, atom=i, method=...) are the CRYSTAL ANHARM treatment (manual section 8.11; Tosoni et al., Chem. Phys. Lett. 396, 308 (2004)). Atom i must be hydrogen (deuterium is a mass, see below). Its first neighbour X (for a cell, over the lattice images; a tie between the two closest neighbours, such as the symmetric bridge of bifluoride, is refused) fixes the bond direction, and only i moves along it, every other atom fixed; on BIPOLE the H atom of every cell moves. The energies are computed at CRYSTAL’s seven points d - d0 = -0.2, -0.16, -0.06, 0, 0.16, 0.24, 0.3 Angstrom (XHStretchSettings()), or at 26 points from -0.2 to 0.3 Angstrom (XHStretchSettings.points26(), CRYSTAL’s POINTS26), fitted by a sextic (fit_degree=6; seven points and six coefficients plus the reference are an exact interpolation) and the one-dimensional problem is solved with the shared one-mode solver in the oscillator basis of the fitted harmonic frequency (16 functions; the change against 24 functions is recorded as xh_basis_check_cm1). Fewer than seven points and odd fits are refused, and the one-mode refusals apply (a fit that falls below the reference where the basis probes it, a lower or a double well). The result reports the fundamental omega_01, the first overtone omega_02, omega_e x_e = (2 omega_01 - omega_02) / 2, omega_e = omega_01 + 2 omega_e x_e, the harmonic frequency of the fitted curvature, the fit residuals, the bond force (the linear fit term) and every energy. On BIPOLE the route is held as for the normal-mode provider: the reference’s options, mesh, XC bound and grid, its finite domain and occupations at every point, metals refused, and the displacement range checked against the pair-support radii first.

The manual does not state the mass of the one-dimensional problem. mass_model="reduced" (default) uses mu = m_X m_H / (m_X + m_H), which is exact for a diatomic (its energy depends on the bond length only, so moving H alone samples the same curve); mass_model="light_atom" uses m_H, an H atom against an infinitely heavy neighbour. The manual’s HF molecule example (the level of theory is not stated there) lists 4359.0, 8608.1, 4468.8 and 54.9 cm^-1 for omega_01, omega_02, omega_e and omega_e x_e; RHF/STO-3G here gives 4359.79, 8609.46, 4469.92 and 55.06 cm^-1 with the reduced mass and 4251 cm^-1 for omega_01 with the H mass, so the reduced mass is the reading the example supports (this is not a matched comparison). Isotopes (CRYSTAL’s ISOTOPES) change only the masses: result.with_masses({atom: amu}) solves again with the same energies, and masses_amu= sets them up front.

The bond is an independent oscillator, which is what separates this from the normal-mode treatment: no coupling to other modes, so no Fermi resonance. Measured (tests/test_vibrational_anharmonic.py, tests/test_vibrational_providers.py):

Case

Check

Result

Morse bond, omega_e 4400, omega_e x_e 98.0 cm^-1

seven points, sextic

omega_01 -0.002, omega_02 +0.34, omega_e -0.35, omega_e x_e -0.17 cm^-1 (fit error)

same

26 points, octic fit

omega_01 1.2e-4, omega_02 0.013 cm^-1

same

reduced against light-atom mass, H against D

harmonic frequency exactly as mu^(-1/2); omega_e x_e as 1/mu within 0.2 %

HF RHF/STO-3G

energies against PySCF on the same geometries

1.7e-13 Ha

same

seven points against the one-mode normal-mode treatment (quadrature PES; for a diatomic the bond is the normal coordinate)

omega_01 -0.22, omega_02 +0.78 cm^-1, the seven-point fit error; with 26 points and an octic fit 0.002 cm^-1

same, DF from the same energies

omega_01

3182.89 cm^-1; harmonic ratio sqrt(mu_HF / mu_DF) exactly

HDO RHF/STO-3G

local O-H stretch against the O-H normal mode, VCI@VSCF on the 2M PES (weight 0.97)

4169.42 against 4157.31 cm^-1: the decoupling puts the local stretch 12.1 cm^-1 higher

H2O RHF/STO-3G

local O-H stretch

4169.42 cm^-1, between the symmetric (4016.77) and antisymmetric (4248.76) VCI fundamentals

HF in cubic boxes of 20 and 30 bohr, BIPOLE Gamma

against the molecule

-6.07 and -1.76 cm^-1, as L^-3; extrapolated within 0.1 cm^-1

Not implemented: CRYSTAL’s KEEPSYMM (all symmetry-equivalent X-H bonds stretched in phase), NOGUESS and TEST[ANHA].

VSCF

run_vscf(VibrationalHamiltonian(pes, bases), configuration) makes the energy of one Hartree product of modals stationary (CRYSTAL23 paper Eqs. 93 and 94, manual section 8.12.2). Vibrational modes are distinguishable, so the product needs no antisymmetrisation. With the n-mode surface each mode sees its own one-mode potential plus the average of every coupling term over the modals of the other modes; on the quadrature grids this mean field is the contraction of the coupling tensors with the modal densities. The energy is evaluated directly, so nothing is counted twice. For an excited configuration each modal is followed by maximum overlap with the previous cycle (state-specific VSCF). mixing keeps a fraction of the previous mean field (CRYSTAL’s VSCFMIX, 25 % there, 0 here by default) and tol_ha is the energy convergence (CRYSTAL’s VSCFTOL default is 1e-3 cm^-1, here 1e-10 Ha = 2e-5 cm^-1). vscf_fundamentals returns the ground state and the state-specific VSCF of every fundamental; the fundamental transition of mode i is E(e_i) - E(0).

VibrationalHamiltonian checks the surface first (the refusals above) and holds the one-mode matrices and the coupling values on the quadrature grids; VSCF and VCI share it.

VCI

run_vci(hamiltonian, VCISelection(max_quanta=4, max_excited_modes=None, n_modals=None)) expands every state in Hartree products of modals (Eqs. 95 and 96). The modals are the eigenfunctions of the converged ground-state VSCF operators (VCI@VSCF, the default) or the oscillator functions (modals="harmonic"). The configuration space follows the two CRYSTAL23 truncations (section 7.2.1): at most max_quanta quanta in total (Eq. 97, CRYSTAL’s N_quanta) and at most max_excited_modes modes excited at once (N_modes), plus at most n_modals modals per mode. Configurations are ordered by total quanta and then lexicographically, so a selection is reproducible, and its size is recorded. The Hamiltonian matrix vanishes between configurations that differ in more modes than the PES couples; each nonzero element is a product of one-, two- or three-mode modal integrals. The matrix is diagonalised with the shared eigensolver (vibeqc.solvers.eigensolver.solve_eigenproblem), dense by default and Davidson with solver="davidson"; a dense matrix above 6000 configurations is refused (memory), and solver="sparse" (below) never builds it. VCIResult.fundamentals() assigns to each mode the state with the largest weight on its one-quantum configuration and reports that weight; a weight well below one marks a resonance (Fermi or Darling-Dennison mixing) that only the coupled treatment describes.

Over the full product space VCI is the exact solution of the represented surface in the chosen oscillator basis, whatever the modals. Three separate convergence controls therefore exist: the oscillator basis (n_basis), the quadrature (n_quadrature, exact for polynomial surfaces once it exceeds n_basis by half the polynomial degree) and the configuration space (max_quanta, max_excited_modes, n_modals). The PES range and the truncation mode_coupling are a fourth and fifth, on the surface side.

Matrix-free VCI

run_vci(..., solver="sparse", n_states=k) never builds the VCI matrix. A term of the n-mode surface couples only configurations that agree in every mode outside it, so for each term the configurations are grouped by their quanta outside its modes and labelled by their quanta inside them; within a group the term acts as the small dense matrix of its modal integrals. The product of the Hamiltonian with a block of vectors is then a scatter, one dense multiplication per term and a gather (NModeOperator), at a cost of sum over terms of n_groups d^2 per vector, with d the number of distinct quanta of the term’s modes, instead of N^2. The lowest k roots come from the Davidson path of the shared eigensolver with the analytic diagonal as preconditioner, and every root’s residual is checked after it returns. By default k covers every fundamental: the configurations whose diagonal lies at or below the highest one-quantum diagonal, plus one per mode. The dense cap (max_configurations, 6000) does not apply; the operator tables and the Davidson vectors are estimated first and refused above max_sparse_bytes (2 GB). The configuration list itself is enumerated directly, so its cost is the number of selected configurations. The dense matrix stays the reference.

Validation on coupled oscillators

The reference diagonalises the full model potential on a uniform sinc-DVR product grid (Colbert-Miller kinetic matrix), which shares nothing with the oscillator basis, the quadrature or the n-mode decomposition. Both models are scaled to a molecular energy scale (first mode 3292 cm^-1). Measured in tests/test_vibrational_anharmonic.py:

Model

Check

Result

Two modes, quartic, cubic Q1 Q2^2 and Q1^2 Q2^2 couplings

full product space (400 configurations, 20 functions per mode) against sinc-DVR

1.0e-12 Ha ground state, at most 2.6e-9 Ha over the first eight levels; VSCF and harmonic modals agree to 1e-12 Ha

same

VSCF ground state

4.27 cm^-1 above the exact ground state (vibrational correlation)

same

configuration space, max_quanta = 2, 4, 6, 8, 10 (6 to 66 configurations)

ground-state error 1.9e-5, 7.1e-8, 1.2e-9, 5.4e-11, 1.9e-12 Ha, monotone from above; fundamentals 3463.57 / 2147.92 cm^-1 at 2 quanta, 3459.32 / 2142.08 cm^-1 (exact within 4e-5 cm^-1) at 10

same

oscillator basis, 6, 10, 14, 18 functions

ground-state error 1.4e-6, 5.2e-9, 2.6e-10, 3.3e-12 Ha

same

quadrature at 12 functions

15 and 22 nodes agree to 1e-13 Ha (exact), 12 nodes differ

Three modes with a genuine Q1 Q2 Q3 term

3M PES, full space at 14 functions

at most 3.3e-8 Ha over the first eight levels; the 2M truncation misses them by up to 4.5e-6 Ha

same

Davidson against dense, 91 configurations

lowest four roots within 1e-10 Ha

same, and the three-mode 3M model

matrix-free operator against the dense matrix; sparse against dense roots

the operator applied to the identity is the dense matrix to 1e-15 Ha; roots within 1e-10 Ha at 4, 8 and 12 quanta, and the default roots find the same fundamentals

Eight coupled modes, 2M

sparse against dense at 7 quanta (6435 configurations, above the dense cap, allowed deliberately)

equal to 7e-16 Ha on 12 roots; dense 26 s and about 3.9 GB, sparse 0.8 s and 4 MB of operator tables

same

sparse at 8, 10 and 12 quanta

12870, 43758 and 125962 configurations in 1.6, 5.7 and 18.5 s; the ground state falls monotonically

Electronic-structure providers

A provider turns a vector of normal-coordinate displacements into a total energy. The Cartesian displacement of atom a is u_a = M_a^(-1/2) sum_m L_(a,m) Q_m, with L the orthonormal mass-weighted eigenvectors of the harmonic analysis (Barone 2005, Eq. 1). The providers only displace and evaluate; everything else is the shared vibrational Hamiltonian above.

MolecularNormalModeProvider(molecule, surface, hessian, modes)

The modes of a molecular Hessian (vibeqc.hessian.compute_hessian_fd or any HessianResult) and the energies of a vibeqc.molecular_surface.MolecularSurface, the surface the molecular optimizers and the finite-difference Hessian evaluate (any method it supports). modes counts vibrations from 0 in ascending frequency; translations and rotations (the projected exact zeros) cannot be selected. Imaginary modes and partial Hessians are refused by name, and every SCF must converge.

BipoleGammaNormalModeProvider(system, basis, kmesh, options, frequencies=...)

The Gamma-point modes of vibeqc.bipole_frequencies.compute_bipole_gamma_frequencies on the BIPOLE route (RHF, UHF, RKS, UKS). A displacement at Gamma moves every image of an atom with it. Every displaced SCF runs the reference’s route: the same driver keywords and options, the same full Monkhorst-Pack mesh, the attached-symmetry mode, and for RKS/UKS the XC image closure bound and the XC grid of the reference held (#838, #575); the resolved finite domain of every point is checked equal to the reference’s, and the reference’s domain digest must equal the one the frequencies were computed with. Refused by name before any displaced SCF: the three acoustic translations, imaginary modes, metals (fractional occupations, a varying number of occupied bands, a gap below 1e-3 Ha over the mesh), smeared and Gilat states, the route options the frequency code does not validate (DFT+U, Wigner-Seitz exchange, the historical domain, the legacy gauge), a selection that splits a degenerate set (both providers), and a sampling range that carries an atom-pair image distance across a pair-support radius (BipoleDisplacementDomainError; the band is the largest Cartesian displacement of any atom over the whole grid). A displaced point whose occupations change or whose gap closes stops the sampling. A supercell passed as the cell gives the zone-boundary modes folded onto its Gamma point, as for the harmonic frequencies.

Symmetry: adapted partners and transported points

Both providers apply the nuclear symmetry group of the reference geometry (mode_symmetry="auto", the default; vibeqc.vibrational.symmetry): the molecular point group (operations found at 1e-5 bohr), or, for BIPOLE, the space-group operations at Gamma that map the cell and its k mesh onto themselves, the same group the symmetry-reduced harmonic frequencies use (none for UHF and UKS, whose spin-polarised solution can break it). An operation acts on mass-weighted displacements as D(g), the Cartesian rotation combined with the atom permutation; operations that exchange atoms of different mass (an isotopologue) are dropped. The energy is invariant, E(D(g) u) = E(u), and every degenerate set of the Hessian is an invariant subspace.

Adapted partners

Inside a degenerate set (harmonic frequencies within 0.01 cm^-1) the eigensolver returns an arbitrary basis, and the anharmonic surface along one member depends on it (two arbitrary members of the He fcc LA(X) triplet gave one-mode fundamentals 0.65 cm^-1 apart). The partners are instead the joint eigenvectors of commuting involutions of the group (two-fold axes, mirrors, inversion, half-lattice translations), taken in a fixed order of the operations (two-fold axes before mirrors, operations that move the fewest atoms first, then the x axis first) and kept while they split the set: every involution acts on every partner as +1 or -1. For a cubic triplet these are the x, y, z components; for an E set of C3v or Td one partner is even and one odd under the first mirror. A fixed sign convention (largest component positive) removes the remaining choice, and the frequencies of the set are set to their mean (the spread is recorded). Each adapted partner may then be selected on its own. A set the commuting involutions cannot split into single partners (a complex-pair representation, such as E of C3) gets a reproducible projected Cartesian basis that is not symmetry-adapted, and a selection that splits it stays refused, as does one of a set that is not invariant (a near-degeneracy from Hessian noise).

Transported points

An operation that carries every mode of a grid point onto a signed selected mode, D(g) u_i = s u_j, carries the point onto another point of the same energy. The PES computes one energy per orbit of grid points and copies it to the others (PESSettings(symmetry_reduced_sampling=True), the default); operations that mix partners (a three-fold axis on an E set) relate no two grid points and are not used. The representation, its fits and its number of points (pes_n_single_points) are unchanged; the record adds the computed (pes_n_evaluated_points) and transported (pes_n_transported_points) points and the largest residual of the operations used. mode_symmetry="off" keeps the eigensolver’s vectors and computes every point.

Measured (tests/test_vibrational_anharmonic.py, tests/test_vibrational_providers.py):

Case

Check

Result

Methane spring model, Td

adapted partners after an arbitrary rotation inside each set

the same vectors to 1e-12; all 24 operations permute the T2 partners with signs, 8 the E partners

Water RHF/STO-3G, 2M polynomial PES

reduced against full sampling

113 of 157 energies computed (the B2 stretch is odd under the two-fold axis); transported energies equal the computed ones to 1.7e-12 Ha; fundamentals to 1e-8 cm^-1

He fcc RHF/STO-3G, LA(X) triplet

one adapted partner alone, quadrature PES

558.1344 cm^-1 for each of x, y, z, 11 of 21 energies computed

same

3M polynomial PES, reduced against full sampling

19 of 221 energies computed (202 SCFs saved); VCI@VSCF 563.5777 cm^-1, the three exactly degenerate

Front doors

from vibeqc.vibrational import compute_molecular_anharmonic, VCISelection

res = compute_molecular_anharmonic(mol, "sto-3g", "RHF", scf_options=opts,
                                   vci=VCISelection(max_quanta=6))
print(res.harmonic_cm1, res.vscf_fundamentals_cm1, res.vci_fundamentals_cm1)

compute_molecular_anharmonic(molecule, basis, method, ...) builds the surface (or takes surface=), the Hessian on the same surface (or takes hessian=), samples the PES of the selected modes, runs ground-state and fundamental VSCF and, unless vci=None, VCI@VSCF. compute_bipole_anharmonic(system, basis, kmesh, options, method=..., frequencies=..., modes=...) does the same on the BIPOLE route, computing the Gamma frequencies first when none are given. Both return an AnharmonicResult with the PES, the Hamiltonian, the VSCF states, the VCI result, as_record() (flat provenance) and the harmonic analysis they started from.

run_periodic_job(..., jk_method="bipole", hessian=True, hessian_anharmonic=True) (or a dict with modes, pes_settings, n_basis, n_quadrature, vscf_tol_ha, vscf_mixing, vci, vci_solver, mode_symmetry) runs the anharmonic step after the harmonic frequencies on the same cell, mesh, options and keywords. It writes an “Anharmonic states at Gamma” block to the .out (provider, PES truncation and representation, number of energies, fit residuals, residual gradients, basis and quadrature, VSCF and VCI settings, the table of harmonic, VSCF and VCI fundamentals with their VCI weights, the leading VCI states), the anharmonic_* fields of the .system [run] table, and cites the CRYSTAL23 paper through the anharmonic_pes, vscf and vci routes. It is refused without hessian=True and with phonon_supercell. The QVF does not carry the anharmonic states.

Anharmonic IR intensities

compute_molecular_anharmonic(..., ir_intensities=True) samples the dipole moment (about the reference centre of mass, which the vibrational normal coordinates do not move) at the same points as the energy, so it costs no extra SCF, and represents each Cartesian component with the same n-mode truncation and the same fits or quadrature values as the potential (pes.dipole, a DipoleSurface; a transported point carries the dipole of its representative rotated by the operation, mu(D(g) u) = R_g mu(u)). The dipole is then an n-mode operator like the potential, and the transition moments between VCI states, <Psi_0|mu|Psi_s>, come from the same matrix-free product (vibeqc.vibrational.vci.transition_dipoles). The integrated absorption of 0 -> s is

I = K 2 omega_0s |<Psi_0|mu|Psi_s>|^2,

with K the factor of the harmonic intensities of vibeqc.hessian.ir_intensities (974.864 km/mol per e^2/amu), which it reproduces for a harmonic oscillator with a linear dipole (|<0|mu|1>|^2 = (dmu/dQ)^2 / (2 omega)). Mechanical and electrical anharmonicity are both included, and with them the overtone and combination bands. result.ir holds the transition energies, dipoles and intensities of every computed VCI state, result.ir_fundamental_intensities_km_mol the intensity of the state assigned to each fundamental; the .out block lists them. Refused by name: vci=None (no states), methods whose energy is not an SCF energy (the dipole would need the relaxed correlated density), ECPs, and cells (compute_bipole_anharmonic and run_periodic_job): the Berry-phase polarization of vibeqc.bipole_polarization needs more than one k point along every direction and is not sampled by the Gamma normal-mode PES. Raman intensities are not implemented.

Measured (tests/test_vibrational_anharmonic.py, tests/test_vibrational_providers.py):

Case

Check

Result

Two harmonic modes, dipole d1 Q1 + e Q1^2, d2 Q2

fundamentals; overtones and combination

K d_i^2 and the overtone 2 nu_1 K 2 e^2 / omega_1 to 1e-9 relative (electrical anharmonicity); 2 nu_2 and nu_1 + nu_2 zero

Water RHF/STO-3G, 2M, VCI@VSCF at 6 quanta

fundamentals against the harmonic intensities of the same Hessian

7.01, 39.62, 28.93 against 7.24, 44.28, 29.97 km/mol

same

bend overtone, 4207.98 cm^-1

3.19 km/mol, borrowed from the symmetric stretch through their Fermi mixing

same

dipole against PySCF at a displaced point; transported against computed dipoles

2.2e-9 au; 1.8e-12 au

same

quadrature against polynomial representation

fundamentals within 0.03 km/mol

Validation on electronic surfaces

Three error sources are measured separately. The electronic error is that of the energies themselves (SCF convergence, and for a periodic cell the finite domain and the box or k mesh). The PES error is the truncation nM and the fit, measured against the quadrature representation, which has no fit. The vibrational-basis error is the oscillator basis, the quadrature and the configuration space. Measured in tests/test_vibrational_providers.py:

Case

Check

Result

Water RHF/STO-3G, harmonic 2169.80 / 4139.65 / 4390.68 cm^-1

PES energies against PySCF RHF/STO-3G on the same displaced geometries

equal to 1.3e-13 Ha

same, default 2M polynomial PES (157 energies)

VSCF / VCI@VSCF fundamentals (6 quanta, 84 configurations)

2112.50 / 4067.57 / 4272.89 and 2109.91 / 4016.77 / 4248.76 cm^-1; symmetric stretch weight 0.96 (bend overtone admixture)

same

fit error against the 2M quadrature PES (817 energies)

0.07, 0.67, 1.06 cm^-1 (a quartic coupling fit, CRYSTAL’s 2M4T, left 15 to 25 cm^-1 on the stretches)

same

truncation, 3M against 2M (polynomial; quadrature 3M with 3375 energies)

2111.29 / 4014.33 / 4255.81 cm^-1 (quadrature 2111.40 / 4015.56 / 4254.92): the three-mode terms move the antisymmetric stretch by 7 cm^-1

same

configuration space, 4, 5, 6, 8 quanta

antisymmetric stretch 4250.45, 4249.07, 4248.76, 4248.31 cm^-1

same

oscillator basis, 12 against 16 functions

below 0.01 cm^-1

H2 RHF/STO-3G, stretch, molecular provider

octic fit against quadrature (21 energies)

5292.49 against 5292.40 cm^-1; the sextic fit (CRYSTAL ANHARM form) gives 5298.78, 6.4 cm^-1 off; basis 16 against 24 functions below 0.003 cm^-1

H2 in a cubic box, BIPOLE Gamma provider, quadrature PES

periodic minus molecular fundamental at L = 20, 25, 30, 40 bohr

-6.263, -3.191, -1.842, -0.775 cm^-1, linear in L^-3 (the exchange image term of a neutral molecule grows with the bond length, so it shifts the fundamental five times more than the harmonic frequency, -1.14 cm^-1 at L = 20); extrapolated to L -> infinity +0.01 cm^-1

H2 in a 16 bohr box

quadrature range of 16 functions (0.59 bohr per atom)

refused: it carries the 14.65 bohr image distance across the 15 bohr pair cutoff

He fcc RHF/STO-3G, a = 6 bohr, conventional cell at Gamma (X modes of the primitive cell), cutoff 11.2 bohr

LA(X) triplet, harmonic 551.99 cm^-1 (symmetry-reduced analytic Hessian, 2 SCFs)

with mode_symmetry="off" one raw eigenvector alone is refused: it is an arbitrary member of the degenerate set (two such members gave 558.215 and 558.867 cm^-1)

same

the LA(X) triplet in 3M (221 energies), eigensolver basis (mode_symmetry="off")

VCI@VSCF 563.580, 563.578, 563.580 cm^-1, degenerate to 0.002 cm^-1; 10, 12 and 16 functions agree to 1e-4 cm^-1; 2, 4, 6, 8 quanta 563.619, 563.603, 563.580, 563.580 cm^-1

same

the triplet in 3M on the adapted partners

563.5777 cm^-1, exactly degenerate, from 19 computed energies

same

the adapted z partner alone

558.1344 cm^-1 (quadrature PES), equal to the member along z fixed by the caller (allow_partial_degenerate=True) and to the x and y partners; octic fit 0.0013 cm^-1 above (fit error); the coupling inside the triplet adds 5.4 cm^-1

same

electronic (finite domain): cutoff 10.8 and 11.6 against 11.2 bohr, member along z

-0.0032 and -0.0019 cm^-1

No anharmonic fundamental of water at RHF/STO-3G could be cited from the literature library, so the molecular numbers are checked by independent energies (PySCF), the fit and truncation ladders and the box ladder, not by a published value.

Limits

  • No CRYSTAL23 comparison has been run (CRYSTAL is not available here). A matched comparison needs the same cell, basis, PES truncation and steps; CRYSTAL’s EGH finite-difference scheme (paper Eqs. 88 to 92) is not implemented, so the PES representations differ even at the same nM.

  • Rectilinear normal coordinates without rotation-vibration coupling, as in CRYSTAL23 Eq. 80; large-amplitude torsions, double wells and inversions are refused rather than treated.

  • Symmetry transports a PES point only through operations that map its modes as signed permutations. A selection that splits a degenerate set the group does not fix (no operations, a set that is not invariant, or one the commuting involutions cannot split) is refused by name; include the whole set, or fix a component yourself and pass allow_partial_degenerate=True (which also turns the adaptation off).

  • Anharmonic IR intensities of cells, Raman intensities, finite-temperature anharmonic lattice dynamics and phonon-phonon lifetimes are not implemented.

  • The configuration space is selected by quanta, excited modes and modals per mode only (no energy-based or iterative selection); the sparse solver returns the lowest roots only.