vibe-qcDocumentation

Periodic energy decomposition analysis (pEDA)

Preview

vibeqc.periodic_eda is a preview. Its scope is neutral, insulating fragments; see Scope for the routes it covers.

The periodic energy decomposition analysis of Raupach and Tonner (2015) answers “why does this adsorbate layer bind to this surface” (or one sublattice to another) by splitting the interaction energy of two periodic fragments into physically labelled terms. It is the periodic form of the Ziegler and Rauk / Morokuma scheme that ADF and BAND implement:

dE_int = dE_elstat + dE_Pauli + dE_orb (+ dE_disp)

Term

Meaning

e_elstat

Quasi-classical Coulomb interaction of the two unperturbed fragment charge distributions, nuclei included, in the periodic Ewald gauge of the SCF route.

e_pauli

E[Psi0] - E_A - E_B - dE_elstat, where Psi0 is the determinant of the mutually orthonormalised occupied fragment orbitals (orthonormalised at every k-point). For Kohn-Sham it also holds the exchange-correlation non-additivity of the superposed densities. Always repulsive.

e_orb

E[relaxed] - E[Psi0]: polarisation and charge transfer as the system relaxes to its SCF solution, and electron-pair bond formation between radical fragments.

e_disp

D3(A+B) - D3(A) - D3(B) when dispersion= names a functional.

The terms add up to e_int = E(A+B) - E(A) - E(B) exactly.

With nocv=True (the default) the orbital term is split further by the natural orbitals for chemical valence (ETS-NOCV, Mitoraj, Michalak and Ziegler 2009). At every k-point the deformation density dP(k) = P_relaxed(k) - P_Psi0(k) is diagonalised; each eigenvector pair (psi_-i, psi_i) describes one charge-flow channel, with energy nu_i (F^TS_ii - F^TS_-i-i) from the transition-state Fock matrix F[(P_Psi0 + P_relaxed)/2]. As in pEDA-NOCV the pair of rank i is summed over the k mesh with the k-point weights. Eigenvalues follow the ADF/BAND closed-shell convention (per spin); the pair energies count both spins and add up to e_orb up to the transition-state error, which the summary prints.

Example: CO on MgO(001)

The system of the BAND example PEDANOCV_MgO+CO: a three-layer MgO slab with CO above a Mg site, PBE, at the Gamma point.

import vibeqc as vq
from vibeqc.periodic_eda import EDAFragment, run_peda

ANG = 1.8897259886
mgo = [(12, 0.0, 0.0, 0.0), (12, 1.5026, -1.5026, -2.124), (12, 0.0, 0.0, -4.248),
       (12, 3.0052, 0.0, 0.0), (12, 1.5026, 1.5026, -2.124), (12, 3.0052, 0.0, -4.248),
       (8, 1.5026, -1.5026, 0.002), (8, 0.0, 0.0, -2.124), (8, 1.5026, -1.5026, -4.25),
       (8, 1.5026, 1.5026, 0.002), (8, 3.0052, 0.0, -2.124), (8, 1.5026, 1.5026, -4.25)]
co = [(6, 0.0, 0.0, 2.61), (8, 0.0, 0.0, 3.737)]
atoms = [vq.Atom(z, [x * ANG, y * ANG, w * ANG]) for z, x, y, w in mgo + co]
slab = vq.slab_2d([3.0052 * ANG, -3.0052 * ANG, 0.0],
                  [3.0052 * ANG, 3.0052 * ANG, 0.0], atoms)

opts = vq.PeriodicKSOptions()
opts.functional = "pbe"
result = run_peda(
    slab, vq.BasisSet(slab.unit_cell_molecule(), "def2-svp"),
    [EDAFragment(range(12), "MgO"), EDAFragment([12, 13], "CO")],
    opts, fragment_basis="own",
)
print(result.summary())

Note

With def2-SVP this example does not run on the current slab Ewald route: the Gamma slab Hartree cache refuses its fixed z grid as under-resolved for the tight Mg core functions, and the (2, 2, 1) slab k-mesh cache would need several hundred GiB (vibe-qc#1260). Minimal-basis slabs pass both caches, e.g. water on a 2x2 h-BN layer with STO-3G.

run_peda runs three SCF calculations (the complete system and each fragment) unless their results are passed in with complex_result= and fragment_results=, then evaluates every state of the decomposition.

Electron-sharing bonds: open-shell fragments

A covalent bond between an adsorbate and a surface is usually analysed with two radical fragments whose unpaired electrons pair up in the bond. Give each fragment its multiplicity and flip the spin of one of them with spin=-1, so that the frozen state holds the unpaired electron of one fragment as alpha and that of the other as beta:

fragments = [
    EDAFragment(surface_atoms, "surface", multiplicity=2),
    EDAFragment(adsorbate_atoms, "adsorbate", multiplicity=2, spin=-1),
]
result = run_peda(system, basis, fragments, opts, kpoints=(3, 3, 1))

Open-shell fragments make the decomposition spin-unrestricted (UKS): the fragments run UKS, the frozen state is built per spin, and the NOCV pairs are listed per spin. The fragments’ alpha and beta electron counts (after the flip) must add up to those of the complete system, whose multiplicity is that of system; a mismatch is refused with a message. For opposite-spin radicals e_pauli can be negative: there is no Pauli repulsion between the two unpaired electrons, and the exchange-correlation non-additivity of the spin-flipped superposition can outweigh the closed-shell repulsion. unrestricted=True forces the UKS decomposition for closed-shell fragments too; it then reproduces the restricted terms.

Fragment orbital populations

run_peda also reports how many electrons each frontier orbital of a fragment holds in the relaxed system: the k-weighted projection occupation c^H S P S c of the fragment orbitals from fo_window (default 3) below to fo_window above the fragment’s Fermi level, per spin. The summary prints them next to the fragment’s own occupation (2 or 0 for a restricted fragment), and result.extra["fragment_orbital_populations"] holds the values. For CO on a surface, for example, a 5sigma population below 2 and a 2pi* population above 0 measure donation and back-donation. Set fo_window=0 to skip them.

QVF result files

run_peda(..., qvf="stem") (or write_peda_qvf(stem, result, system, basis) afterwards) writes stem.qvf for vibe-viewer and other QVF readers:

Section

Content

structure

the cell and atoms of the complete system

energy_decomposition (peda_decomposition)

the decomposition as QVF spec § 5.16 defines it: scheme ziegler-rauk, variant peda; the terms interaction, electrostatic, pauli, orbital (and dispersion with D3) in hartree per cell, with the sum rule that they add up to the interaction; the two fragments (atoms, multiplicity, spin_flip, basis own or supersystem, energy); the ETS-NOCV table (per-spin eigenvalues, per-k eigenvalues and weighted per-k energies, the all-pair total and the listing threshold); the k-points (fractional reciprocal coordinates) with their weights and mesh. The fragment orbital populations are kept under x_vibeqc_fragment_orbital_populations.

volume.difference

pEDA orbital relaxation, rho(A+B) - rho(Psi0) (role orbital_relaxation); pEDA interaction density, rho(A+B) - rho(A) - rho(B) (role interaction); and the deformation densities of the first n_nocv (default 4) NOCV pairs, summed over the k mesh (role orbital_pair, linked both ways with the pair’s density_ref)

citations

BibTeX of the method references

The volumes are sampled on one cell with spacing_bohr (default 0.3 bohr); for a slab the box spans the atoms plus padding_bohr (default 6 bohr) along the surface normal. Each deformation density integrates to zero, and positive values mark charge gained. volumes=False writes the archive without grids.

Archives written before the merge into vibe-qc main carried the decomposition as the noncritical vendor section x_vibeqc.peda. vibe-qc no longer writes it; such archives still validate, and readers list the section as a vendor section.

Plotting NOCV deformation densities

write_nocv_cube writes the deformation density of one NOCV pair (or the sum of several), summed over the k mesh, as a cube file for vibe-viewer or any cube viewer. Positive values are charge gained, negative values charge depleted. For a slab the box spans the atoms plus padding_bohr along the surface normal.

from vibeqc.periodic_eda import write_nocv_cube

write_nocv_cube("nocv1.cube", result, result.nocv[0], slab, basis)
write_nocv_cube("nocv2+3.cube", result, result.nocv[1:3], slab, basis)

How the energies are evaluated

All energies of the decomposition come from one evaluator built from the complete system: one set of lattice options, one Ewald split and one exchange-correlation grid. Between the complete system and a fragment only the nuclear-attraction matrix and the nuclear repulsion change. A fragment’s energy is therefore re-evaluated on the complete system’s grid instead of being taken from its own SCF, whose grid has no centres on the other fragment. result.extra["scf_energies"] keeps the energies the SCF runs reported; the difference is the integration-grid effect.

Before decomposing, run_peda re-evaluates the converged density of the complete system and compares it with that SCF’s energy (result.extra["reevaluation_mismatch"]). A mismatch above check_tol (default 1e-6 Hartree) stops the analysis, because it means the evaluator does not reproduce the SCF route’s settings.

Fragment basis

fragment_basis

Fragments are computed in

Basis-set superposition error

"own" (default)

their own atoms’ basis functions

contained in e_orb, as in ADF and BAND

"full"

the complete basis, on Z = 0 ghost centres

removed (counterpoise); e_int is less attractive

Use "own" to compare with ADF or BAND pEDA, and "full" for a counterpoise-corrected interaction energy.

Scope

Supported

Gamma point

dim = 2 slabs (SLAB_EWALD_2D) and dim = 3 crystals (EWALD_3D); RKS/UKS with any functional the Gamma Ewald drivers accept, and closed-shell RHF

k mesh

kpoints=(n1, n2, 1) on dim = 2 slabs, full Monkhorst-Pack mesh, semilocal (LDA/GGA/meta-GGA) RKS/UKS

Fragments

two, neutral, insulating (integer occupations at every k-point), closed or open shell

Dispersion

D3-BJ through dispersion="<functional>"

With k-dependent integer occupations (a band crossing the Fermi level on the mesh), ETS-NOCV needs the relaxed system and the frozen state to hold the same number of occupied orbitals at every k-point. Otherwise the deformation density moves charge between k-points and has no NOCV pairs: run_peda then warns, skips the pairs and records the reason in result.extra["nocv_skipped"]; the energy terms are unaffected.

Refused, with a message naming the reason:

  • charged fragments: the neutralising background terms of two charged periodic fragments do not cancel, so the electrostatic interaction is not uniquely defined;

  • metallic systems (fractional occupations);

  • open-shell RHF (use Kohn-Sham, which runs UKS);

  • exact exchange on a slab k mesh, which the SCF route itself refuses; use a semilocal functional or a Gamma supercell;

  • RHF on a k mesh.

Note

With exact exchange at the Gamma point (RHF or a hybrid) on a tight cell, the Gamma exchange build is not self-adjoint, so the route’s Fock matrix is not exactly the gradient of its energy. The pEDA terms are unaffected (they are differences of energies), but the NOCV transition-state sum then misses e_orb by more than the usual third-order error.

The Gamma-point and k-mesh routes are separate SCF routes and do not agree to numerical precision on the same cell sampling (a 2x2 supercell at Gamma and a (2, 2, 1) mesh differ by about 0.5 kcal/mol per cell in total energy for a small H2 bilayer), so compare decompositions within one route.

Validation

Molecular limit. A water dimer (the geometry of the bond analysis guide, RHF/6-31G, fragments on ghost centres) placed in a slab cell of growing lateral size, against the molecular LMO-EDA of vibeqc.eda.eda_lmo (kcal/mol):

Cell

elstat

Pauli

orb

int

12 A

-9.592

5.501

-1.792

-5.883

18 A

-9.841

5.498

-1.858

-6.201

24 A

-9.906

5.497

-1.875

-6.283

molecular

-9.954

5.497 (exch + rep)

-1.888 (pol)

-6.346

The Pauli term matches at every size; elstat and orb approach the molecular values as 1/L^3, the decay of the dipole interaction with the periodic images (0.36 kcal/mol at 12 A times (12/18)^3 predicts the 0.11 kcal/mol left at 18 A).

Internal consistency (test suite): the terms add up to e_int to machine precision, the re-evaluated energy of the complete system matches its SCF energy to 1e-10 Hartree on the Gamma and k-mesh routes, NOCV eigenvalues pair to machine precision, an unrestricted decomposition of a closed-shell partition reproduces the restricted one, and a NOCV deformation density integrates to zero charge.

References

  • M. Raupach and R. Tonner, J. Chem. Phys. 142, 194105 (2015), doi:10.1063/1.4919943 (pEDA and pEDA-NOCV).

  • T. Ziegler and A. Rauk, Theor. Chim. Acta 46, 1 (1977), doi:10.1007/BF02401406.

  • K. Morokuma, J. Chem. Phys. 55, 1236 (1971), doi:10.1063/1.1676210.

  • M. P. Mitoraj, A. Michalak and T. Ziegler, J. Chem. Theory Comput. 5, 962 (2009), doi:10.1021/ct800503d (ETS-NOCV).

  • A. Michalak, M. Mitoraj and T. Ziegler, J. Phys. Chem. A 112, 1933 (2008), doi:10.1021/jp075460u (NOCV).

result.citations lists the citation keys of these references.