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 isx = +-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=6is the sextic fit of CRYSTAL’sANHARM, 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 usex = +-0.75, +-1.5, +-2.25on both axes (36 points per pair) and the monomialsx_i^a x_j^bwitha, b >= 1anda + b <= 6(two_mode_degree). Three-mode terms usex = +-0.75, +-1.5(64 points per triple) anda + b + c <= 6.two_mode_degree=4andthree_mode_degree=4give 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(), theetaof 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 equalsomega^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 Kone-mode,C(M,2) K^2two-mode andC(M,3) K^3three-mode energies forKnodes 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.25from 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.25is 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 withpes_one_mode_asymptotically_bounded = Falserecorded; 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 |
Harmonic |
|
1e-12 relative |
Pure quartic |
|
1e-11 relative, 1e-9 relative, 1e-9 Ha; ground state 0.6679862591 Ha at |
Morse, 4400 cm^-1, |
exact |
six levels within 1e-10 Ha (60 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, |
difference falls 16-fold when the anharmonicity is halved; the fit returns |
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, |
seven points, sextic |
|
same |
26 points, octic fit |
|
same |
reduced against light-atom mass, H against D |
harmonic frequency exactly as |
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) |
|
same, DF from the same energies |
|
3182.89 cm^-1; harmonic ratio |
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 |
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 |
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, |
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 |
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_fdor anyHessianResult) and the energies of avibeqc.molecular_surface.MolecularSurface, the surface the molecular optimizers and the finite-difference Hessian evaluate (any method it supports).modescounts 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_frequencieson 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
xaxis first) and kept while they split the set: every involution acts on every partner as+1or-1. For a cubic triplet these are thex,y,zcomponents; for anEset ofC3vorTdone 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 asEofC3) 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 anEset) 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, |
adapted partners after an arbitrary rotation inside each set |
the same vectors to 1e-12; all 24 operations permute the |
Water RHF/STO-3G, 2M polynomial PES |
reduced against full sampling |
113 of 157 energies computed (the |
He fcc RHF/STO-3G, LA(X) triplet |
one adapted partner alone, quadrature PES |
558.1344 cm^-1 for each of |
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 |
fundamentals; overtones and combination |
|
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 |
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 |
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 |
same |
the LA(X) triplet in 3M (221 energies), eigensolver basis ( |
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 |
558.1344 cm^-1 (quadrature PES), equal to the member along z fixed by the caller ( |
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.