7. General Remarks concerning Post-Hartree-Fock Calculations

All post-Hartree-Fock modules in PyBEST have a similar input structure. To optimize the wave function of any post-Hartree-Fock method, the corresponding module requires a Hamiltonian and some orbitals (either an AO/MO coefficient matrix or an MO/MO coefficient matrix) including the overlap matrix (for restart purposes) as input arguments. In the following, we will discuss some general aspects on how to perform post-Hartree-Fock calculations in PyBEST. We recommend that all users read the previous sections of the User Documentation to be familiar with the basic input structure and the variable names used throughout the PyBEST Documentation to label Hamiltonians, orbitals, occupation models, etc.

Note

See Defining Basis Sets, Molecular Geometries, and Hamiltonians for how to define the molecular geometry, basis set, or the Hamiltonian.

Note

See Orbitals and Orbital Occupations for how to define orbitals and the occupation models (which also determines the total charge)

Typically, a post-Hartree-Fock calculation requires a Hartree-Fock calculation as initial step (exceptions are, for instance, restarts).

Note

See The Self-Consistent Field Module for how to perform a Hartree-Fock calculation.

PyBEST uses fixed labels/names for the one- and two-electron integrals, orbitals, density matrices, etc., which are summarized in Input/Output Operations: the IOData Container. For reasons of consistency, we recommend not to change those labels/names if you intend to directly manipulate the IOData container. However, if you manipulate data outside the IOData container, you are free to choose names/labels as you want.

7.1. General input structure

To set up a post-Hartree-Fock calculation, you have to perform similar steps as in a simple Hartree-Fock calculation. If some Hamiltonian (see for instance Computing the matrix representation of the Hamiltonian or Model Hamiltonians or FCIDUMP format) and some initial orbitals are present (for instance from a previous Hartree-Fock calculation, see The Hartree-Fock wrapper), a post-Hartree-Fock calculations can be initialized as follows

# Create an instance of a post-Hartree-Fock method (here called PostHF)
posthf = PostHF(lf, occ_model)
# Start the calculation through a function call using the results of
# a previous RHF calculation stored in hf_output
posthf_output = posthf(kin, ne, eri, hf_output)

In the above example, PostHF is some post-Hartree-Fock flavor (see the next sections for more details). The arguments are described in Preliminaries. Thus, the input structure is similar to a Hartree-Fock calculation, except that only the Hamiltonian elements have to be passed explicitly. The orbitals and overlap (and the external energy term) are passed using the IOData container hf_output, which stores the results of a previous wave function calculation like RHF (as in this example).

Note

The IOData container has lowest precedence and (mostly) all wave function information can be overwritten using arguments or keyword arguments. For reasons of robustness, however, we recommend this option only for experienced users. Thus, stick to the IOData container whenever possible.

If external one- and two-electron integrals are read from a file (assuming the FCIDUMP file format), all one-electron integrals are combined to one single term (see FCIDUMP format). Furthermore, both the overlap integrals and the orbitals are stored in the IOData container. The function call of a post-Hartree-Fock method changes then to

# Read external integrals stored in FCIDUMP
ints = IOData.from_file('FCIDUMP')

# Create an instance of a post-Hartree-Fock method (here called PostHF)
posthf = PostHF(lf, occ_model)
# Start the calculation through a function call
posthf_output = posthf(ints.one, ints.two, ints)

Since the FCIDUMP file represents the integrals in an orthonormal basis, the overlap matrix and molecular orbitals that need to be passed to the function call are unity matrices (see also next section).

Note

The Hamiltonian, here labeled as one and two, has to be passed explicitly.

7.2. Post-Hartree-Fock calculations with point charges and embedding potential

For post-Hartree-Fock calculations in presence of external point charges or a static embedding potential, the related integrals calculated before performing the Hartree-Fock calculation need to be added to the relevant Hamiltonian. We assume that you have done an HF calculation as described in Restricted Hartree-Fock with point charges with point charges or as in Restricted Hartree-Fock with static embedding with a static embedding potential.

# Create an instance of a post-Hartree-Fock method (here called PostHF)
posthf = PostHF(lf, occ_model)
# Post HF calculation in presence of external point charges
posthf_output = posthf(kin, ne, eri, pc, hf_output_pc)

# Create an instance of a post-Hartree-Fock method (here called PostHF)
posthf = PostHF(lf, occ_model)
# Post HF calculation in presence of a static embedding potential
posthf_output = posthf(kin, ne, eri, emb, hf_output_emb)

7.3. Defining the orbitals for post-Hartree-Fock calculations

In all post-Hartree-Fock calculations, the molecular orbitals have to be passed as the optimization of the wave function is performed in the molecular orbital basis. The AO/MO transformation is handled internally and the user does not need to transform the integrals explicitly (see The AO/MO Transformation of the Hamiltonian for more information).

Typically, previously optimized Hartree-Fock orbitals are a convenient choice for any post-Hartree-Fock calculation (see The Self-Consistent Field Module). Other choices, however, are also possible. In the following, some examples are listed.

Orbitals from a previous SCF optimization (The Self-Consistent Field Module)

Localized orbitals (Orbital localization)

External orbitals read from file (Reading orbitals from a checkpoint file)

Rotated or swapped orbitals (Rotating orbitals and Swapping orbitals)

Molecular orbitals corresponding to some external Hamiltonian (read from the FCIDUMP format)

In the last case, all integrals are expressed in an orthonormal basis. The corresponding molecular orbitals and overlap matrix that need to be passed to the post-Hartree-Fock method are equivalent to a unitary matrix. They are created when reading in the FCIDUMP file and can be accessed as attributes of the IOData container,

# Read external integrals stored in FCIDUMP
ints = IOData.from_file('FCIDUMP')

# Access the orbitals and overlap matrix as attributes
orb_a = ints.orb_a
olp = ints.olp

Note

Rotating or swapping pairs of orbitals is only recommended if the orbitals are optimized in the post-Hartree-Fock method.

7.4. The return value of a post-Hartree-Fock calculation

All post-Hartree-Fock methods return an instance of the IOData container class (similar to the RHF/UHF modules). Its attributes are the most important results of a calculation and may include the orbitals (including the overlap matrix), N-particle reduced density matrices, total and correlation energies, etc. This attributes are labeled according the IOData standard (see also Input/Output Operations: the IOData Container). In the following, we will mention some examples, assuming posthf_output to be the IOData container.

posthf_output.e_tot:

The total energy (including all external terms)

posthf_output.e_corr:

The total correlation energy

posthf_output.e_corr_s:

The correlation energy corresponding to single excitations

posthf_output.e_corr_d:

The correlation energy corresponding to double excitations

posthf_output.orb_a:

The molecular orbitals used in the post-Hartree-Fock method (they represent a deep copy of the initial orbitals)

posthf_output.olp:

The overlap integrals (stored for restart purposes)

posthf_output.dm_1:

The 1-particle reduced density matrix (dm_1_a/dm_1_b are used solely by the unrestricted SCF module)

posthf_output.dm_2:

The 2-particle reduced density matrix

posthf_output.t_1:

The wave function amplitudes for single excitations

posthf_output.t_p:

The wave function amplitudes for pair excitations

posthf_output.t_2:

The wave function amplitudes for (all) double excitations

posthf_output.l_1:

The \(\lambda\) amplitudes for single (de-)excitations

posthf_output.l_p:

The \(\lambda\) amplitudes for pair (de-)excitations

posthf_output.l_2:

The \(\lambda\) amplitudes for (all) double (de-)excitations

7.5. Checkpoint files of a post-Hartree-Fock calculation

All post-Hartree-Fock methods dump their own checkpoint files to disk. PyBEST stores all restartable files to its own results directory called pybest-results. Those checkpoint files contain the most recent results of the corresponding post-Hartree-Fock method. They can be used for later restarts or post-processing. They are typically named as checkpoint_*someposthf*.h5.

Note

You can change the default result directory on-the-fly when executing a PyBEST script. To update this directory, the filemanager instance of the FileManager class has to be used:

# Change result directory to 'my_results'
filemanger.result_dir = my_results

[do some stuff]

# Change result directory to 'my_new_results'
filemanger.result_dir = my_new_results