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