13.1. Quick Guide

Before reading this section, please read the general introduction mentioned in General Remarks concerning Post-Hartree-Fock Calculations. This part of the Documentation builds upon it. The current version of PyBEST offers excited-state calculations with a RpCCD (see The pCCD module) reference function using the Equation of Motion (EOM) formalism. The EOM module is explained in greater detail below.

13.1.1. Supported features

The EOM module supports spin-restricted orbitals and the DenseLinalgFactory and CholeskyLinalgFactory.

13.1.2. How to: REOM

This is a short introduction to the REOM module. More information on the input and output structure can be found in the following sections. Similar to the previous modules, we will assume the following names for all PyBEST objects

lf

A LinalgFactory instance (see Preliminaries).

occ_model

An Aufbau occupation model of the AufbauOccModel class

kin

the kinetic energy integrals

ne

the nucleus-electron attraction integrals

eri

the two-electron repulsion integrals

13.1.2.1. RpCCD reference function

This version of PyBEST supports EOM-pCCD calculations with two different excitation operators

  1. electron-pair excited states only (REOMpCCD)

  2. singly and electron-pair excited states (REOMpCCDS)

Complete examples can be found in the following subsections (Example Python scripts).

13.1.2.1.1. EOM-pCCD: Electron-pair excitations

If you use this module, please cite [boguslawski2016a] and [boguslawski2017c].

We assume that you have performed a restricted pCCD calculation (either with or without orbital optimization), whose results are stored in the IOData container pccd_output (see The pCCD module). The code snippet below shows how to perform an REOMpCCD calculation where only electron-pair excitations are described within the EOM formalism. The number of target states is passed through the nroot keyword argument.

# Calculate 3 lowest-lying roots (including ground state)
eom = REOMpCCD(lf, occ_model)
eom_output = eom(kin, ne, eri, pccd_output, nroot=3)

Note

The nroot keyword includes the ground state as the first root.

The results are returned as an IOData container, while all results are saved to the pybest-results/checkpoint_EOMpCCD.h5 file. Specifically, the IOData container contains (amongst others) the following attributes

e_ee

The excitation energies (including the ground state, which equals 0.0)

civ_ee

The CI vector (that is, the eigenvectors) for each state (column) (including the ground states as a first column vector)

t_p

The pair amplitudes of pCCD

The eigenvalues and eigenvectors are stored as numpy arrays, not as instances of the LinalgFactory.

Note

The order of arguments does not matter because PyBEST assigns them in an automatic fashion.

13.1.2.1.2. EOM-pCCD+S: Single and electron-pair excitations

If you use this module, please cite [boguslawski2016a] and [boguslawski2017c].

To include single excitations as well, you can use the REOMpCCDS class, which performs an EOM-pCCD+S calculation. The overall input structure is equivalent to REOMpCCD,

# Calculate 3 lowest-lying roots (including ground state)
eom = REOMpCCDS(lf, occ_model)
eom_output = eom(kin, ne, eri, pccd_output)

The corresponding IOData container (return value) will also contain all singly-excited states in the civ_ee attribute. All results are saved to the pybest-results/checkpoint_EOMpCCD+S.h5 checkpoint file.

Note

The EOM-pCCD+S method is not size-intensive. Thus, the ground state energy eigenvalue will not be 0.0 au. All excitation energies (and hence also total energies) have to be adjusted wrt to the ground state energy shift.

The (rows of the) eigenvectors are sorted as follows: reference (pCCD) state, all singly-excited states, all doubly-excited states.

13.1.2.2. Defining a frozen core

By default, all (occupied and virtual) orbitals are active. If a frozen core has been selected in the pCCD reference calculation, the same orbitals have to be frozen in the chosen EOM flavor. To freeze some (occupied) orbitals, the number of frozen cores has to be specified when an instance of some REOMCC class is created. For instance, if you wish to freeze the first 4 (occupied) orbitals in an EOM-pCCD+S calculation, specify the ncore argument during the initialization of REOMpCCDS class,

# Select 4 frozen core orbital
#-----------------------------
eom = REOMpCCDS(lf, occ_model, ncore=4)
eom_output = eom(kin, ne, eri, pccd_output)

This syntax is working for all EOM modules mentioned above.

13.1.2.3. Restart options

Restart options are not supported yet.