scf_utils

The scf_utils module is an abstract module which contains the basics to perform Restricted SCF calculations (the spatial part of the MOs is common for alpha and beta spinorbitals) based on a single-determinant wave function.

This module does not produce any executable and must not do, but instead it contains everything one needs to perform an orbital optimization based on an Fock matrix. The scf_utils module is meant to be included in the NEED of the various single determinant SCF procedures, such as hartree_fock or kohn_sham, where a specific definition of the Fock matrix is given (see hartree_fock fock_matrix_hf.irp.f for an example).

All SCF programs perform the following actions:

1. Compute/Read all the one- and two-electron integrals, and store them in memory

2. Check in the EZFIO database if there is a set of MOs. If there is, it will read them as initial guess. Otherwise, it will create a guess.

3. Perform the SCF iterations based on the definition of the Fock matrix

The main keywords/options are:

• scf_utils thresh_scf

• scf_utils level_shift

At each iteration, the MOs are saved in the EZFIO database. Hence, if the calculation crashes for any unexpected reason, the calculation can be restarted by running again the SCF with the same EZFIO database.

The DIIS algorithm is implemented, as well as the level-shifting method. If the SCF does not converge, try again with a higher value of level_shift.

To start a calculation from scratch, the simplest way is to remove the mo_basis directory from the EZFIO database, and run the SCF again.

EZFIO parameters

max_dim_diis

Maximum size of the DIIS extrapolation procedure

Default: 15

threshold_diis

Threshold on the convergence of the DIIS error vector during a Hartree-Fock calculation. If 0. is chosen, the square root of thresh_scf will be used.

Default: 0.

thresh_scf

Threshold on the convergence of the Hartree Fock energy.

Default: 1.e-10

n_it_scf_max

Maximum number of SCF iterations

Default: 500

level_shift

Energy shift on the virtual MOs to improve SCF convergence

Default: 0.

scf_algorithm

Type of SCF algorithm used. Possible choices are [ Simple | DIIS]

Default: DIIS

mo_guess_type

Initial MO guess. Can be [ Huckel | HCore ]

Default: Huckel

energy

Calculated HF energy

do_mom

If true, this will run a MOM calculation. The overlap will be computed at each step with respect to the initial MOs. After an initial Hartree-Fock calculation, the guess can be created by swapping molecular orbitals through the qp run swap_mos command.

Default: False

frozen_orb_scf

If true, leave untouched all the orbitals defined as core and optimize all the orbitals defined as active with qp_set_mo_class

Default: False

no_oa_or_av_opt

If true, you set to zero all Fock elements between the orbital set to active and all the other orbitals

Default: False

Providers

all_shells_closed

File : scf_utils/scf_density_matrix_ao.irp.f

logical :: all_shells_closed

Needs:

elec_alpha_num

elec_beta_num

Needed by:

fock_matrix_ao

fock_matrix_mo

scf_density_matrix_ao

eigenvalues_fock_matrix_ao

File : scf_utils/diis.irp.f

double precision, allocatable   :: eigenvalues_fock_matrix_ao   (AO_num)
double precision, allocatable   :: eigenvectors_fock_matrix_ao  (AO_num,AO_num)

Eigenvalues and eigenvectors of the Fock matrix over the AO basis

Needs:

ao_num

fock_matrix_ao

s_half_inv

eigenvectors_fock_matrix_ao

File : scf_utils/diis.irp.f

double precision, allocatable   :: eigenvalues_fock_matrix_ao   (AO_num)
double precision, allocatable   :: eigenvectors_fock_matrix_ao  (AO_num,AO_num)

Eigenvalues and eigenvectors of the Fock matrix over the AO basis

Needs:

ao_num

fock_matrix_ao

s_half_inv

eigenvectors_fock_matrix_mo

File : scf_utils/diagonalize_fock.irp.f

double precision, allocatable   :: eigenvectors_fock_matrix_mo  (ao_num,mo_num)

Eigenvectors of the Fock matrix in the MO basis obtained with level shift.

Needs:

ao_num elec_alpha_num elec_beta_num fock_matrix_mo frozen_orb_scf level_shift

list_act list_core list_inact list_virt mo_coef mo_num

n_act_orb n_core_orb n_inact_orb n_virt_orb no_oa_or_av_opt

extrapolate_fock_matrix:

File : scf_utils/roothaan_hall_scf.irp.f

subroutine extrapolate_Fock_matrix(               &
   error_matrix_DIIS,Fock_matrix_DIIS,    &
   Fock_matrix_AO_,size_Fock_matrix_AO,   &
   iteration_SCF,dim_DIIS                 &
   )

Compute the extrapolated Fock matrix using the DIIS procedure

Needs:

ao_num

max_dim_diis

Called by:

roothaan_hall_scf()

Calls:

dgecon()

dgesv()

dgetrf()

fock_matrix_ao

File : scf_utils/fock_matrix.irp.f

double precision, allocatable   :: fock_matrix_ao       (ao_num,ao_num)

Fock matrix in AO basis set

Needs:

all_shells_closed ao_num fock_matrix_ao_alpha

fock_matrix_mo frozen_orb_scf level_shift

mo_num s_mo_coef

Needed by:

eigenvalues_fock_matrix_ao

fps_spf_matrix_ao

fock_matrix_diag_mo

File : scf_utils/fock_matrix.irp.f

double precision, allocatable   :: fock_matrix_mo       (mo_num,mo_num)
double precision, allocatable   :: fock_matrix_diag_mo  (mo_num)

Fock matrix on the MO basis. For open shells, the ROHF Fock Matrix is

|  Rcc  |  F^b  |  Fcv  |
|-----------------------|
|  F^b  |  Roo  |  F^a  |
|-----------------------|
|  Fcv  |  F^a  |  Rvv  |

C: Core, O: Open, V: Virtual

Rcc = Acc Fcc^a + Bcc Fcc^b Roo = Aoo Foo^a + Boo Foo^b Rvv = Avv Fvv^a + Bvv Fvv^b Fcv = (F^a + F^b)/2

F^a: Fock matrix alpha (MO), F^b: Fock matrix beta (MO) A,B: Coupling parameters

J. Chem. Phys. 133, 141102 (2010), https://doi.org/10.1063/1.3503173 Coupling parameters from J. Chem. Phys. 125, 204110 (2006); https://doi.org/10.1063/1.2393223.

cc oo vv

A -0.5 0.5 1.5 B 1.5 0.5 -0.5

Needs:

all_shells_closed elec_alpha_num elec_beta_num fock_matrix_mo_alpha fock_matrix_mo_beta frozen_orb_scf

list_act list_core list_inact list_virt mo_num

n_act_orb n_core_orb n_inact_orb n_virt_orb no_oa_or_av_opt

Needed by:

eigenvectors_fock_matrix_mo

fock_matrix_ao

fock_matrix_mo

File : scf_utils/fock_matrix.irp.f

double precision, allocatable   :: fock_matrix_mo       (mo_num,mo_num)
double precision, allocatable   :: fock_matrix_diag_mo  (mo_num)

Fock matrix on the MO basis. For open shells, the ROHF Fock Matrix is

|  Rcc  |  F^b  |  Fcv  |
|-----------------------|
|  F^b  |  Roo  |  F^a  |
|-----------------------|
|  Fcv  |  F^a  |  Rvv  |

C: Core, O: Open, V: Virtual

Rcc = Acc Fcc^a + Bcc Fcc^b Roo = Aoo Foo^a + Boo Foo^b Rvv = Avv Fvv^a + Bvv Fvv^b Fcv = (F^a + F^b)/2

F^a: Fock matrix alpha (MO), F^b: Fock matrix beta (MO) A,B: Coupling parameters

J. Chem. Phys. 133, 141102 (2010), https://doi.org/10.1063/1.3503173 Coupling parameters from J. Chem. Phys. 125, 204110 (2006); https://doi.org/10.1063/1.2393223.

cc oo vv

A -0.5 0.5 1.5 B 1.5 0.5 -0.5

Needs:

all_shells_closed elec_alpha_num elec_beta_num fock_matrix_mo_alpha fock_matrix_mo_beta frozen_orb_scf

list_act list_core list_inact list_virt mo_num

n_act_orb n_core_orb n_inact_orb n_virt_orb no_oa_or_av_opt

Needed by:

eigenvectors_fock_matrix_mo

fock_matrix_ao

fock_matrix_mo_alpha

File : scf_utils/fock_matrix.irp.f

double precision, allocatable   :: fock_matrix_mo_alpha (mo_num,mo_num)

Fock matrix on the MO basis

Needs:

ao_num fock_matrix_ao_alpha

mo_coef

mo_num

Needed by:

fock_matrix_mo

fock_matrix_mo_beta

File : scf_utils/fock_matrix.irp.f

double precision, allocatable   :: fock_matrix_mo_beta  (mo_num,mo_num)

Fock matrix on the MO basis

Needs:

ao_num fock_matrix_ao_alpha

mo_coef

mo_num

Needed by:

fock_matrix_mo

fps_spf_matrix_ao

File : scf_utils/diis.irp.f

double precision, allocatable   :: fps_spf_matrix_ao    (AO_num,AO_num)

Commutator FPS - SPF

Needs:

ao_num ao_overlap

fock_matrix_ao

scf_density_matrix_ao

Needed by:

fps_spf_matrix_mo

fps_spf_matrix_mo

File : scf_utils/diis.irp.f

double precision, allocatable   :: fps_spf_matrix_mo    (mo_num,mo_num)

Commutator FPS - SPF in MO basis

Needs:

ao_num fps_spf_matrix_ao

mo_coef

mo_num

scf_density_matrix_ao

File : scf_utils/scf_density_matrix_ao.irp.f

double precision, allocatable   :: scf_density_matrix_ao        (ao_num,ao_num)

Sum of \(\alpha\) and \(\beta\) density matrices

Needs:

all_shells_closed ao_num

scf_density_matrix_ao_alpha

scf_density_matrix_ao_beta

Needed by:

ao_two_e_integral_alpha_chol

fps_spf_matrix_ao

scf_density_matrix_ao_alpha

File : scf_utils/scf_density_matrix_ao.irp.f

double precision, allocatable   :: scf_density_matrix_ao_alpha  (ao_num,ao_num)

\(C.C^t\) over \(\alpha\) MOs

Needs:

ao_num

elec_alpha_num

mo_coef

Needed by:

ao_two_e_integral_alpha ao_two_e_integral_alpha_chol hf_energy

hf_kinetic_energy mcscf_fock_alpha_ao

scf_density_matrix_ao scf_energy

scf_density_matrix_ao_beta

File : scf_utils/scf_density_matrix_ao.irp.f

double precision, allocatable   :: scf_density_matrix_ao_beta   (ao_num,ao_num)

\(C.C^t\) over \(\beta\) MOs

Needs:

ao_num

elec_beta_num

mo_coef

Needed by:

ao_two_e_integral_alpha ao_two_e_integral_alpha_chol hf_energy

hf_kinetic_energy mcscf_fock_alpha_ao

scf_density_matrix_ao scf_energy

scf_energy

File : scf_utils/fock_matrix.irp.f

double precision        :: scf_energy

Hartree-Fock energy

Needs:

ao_num ao_one_e_integrals extra_e_contrib_density

fock_matrix_ao_alpha nuclear_repulsion

scf_density_matrix_ao_alpha scf_density_matrix_ao_beta

threshold_diis_nonzero

File : scf_utils/diis.irp.f

double precision        :: threshold_diis_nonzero

If threshold_DIIS is zero, choose sqrt(thresh_scf)

Needs:

thresh_scf

threshold_diis

Subroutines / functions

damping_scf:

File : scf_utils/damping_scf.irp.f

subroutine damping_SCF

Needs:

ao_num eigenvectors_fock_matrix_mo fock_matrix_ao fock_matrix_mo

frozen_orb_scf mo_coef mo_label n_it_scf_max

scf_density_matrix_ao_alpha scf_density_matrix_ao_beta scf_energy thresh_scf

Calls:

ezfio_set_hartree_fock_energy() initialize_mo_coef_begin_iteration() mo_as_eigvectors_of_mo_matrix()

reorder_core_orb() save_mos()

write_double() write_time()

Touches:

scf_density_matrix_ao_alpha

scf_density_matrix_ao_beta

mo_coef

huckel_guess:

File : scf_utils/huckel.irp.f

subroutine huckel_guess

Build the MOs using the extended Huckel model

Needs:

ao_num ao_one_e_integrals ao_overlap

ao_two_e_integral_alpha eigenvectors_fock_matrix_mo fock_matrix_ao_alpha

fock_matrix_ao_alpha mo_coef mo_num

Called by:

create_guess()

Calls:

orthonormalize_mos()

restore_symmetry()

save_mos()

Touches:

fock_matrix_ao_alpha

fock_matrix_ao_alpha

mo_coef

reorder_mo_max_overlap:

File : scf_utils/reorder_mo_max_overlap.irp.f

subroutine reorder_mo_max_overlap

routines that compute the projection of each MO of the current mo_coef on the space spanned by the occupied orbitals of mo_coef_begin_iteration

Needs:

ao_num ao_overlap elec_alpha_num

elec_beta_num mo_coef

mo_coef_begin_iteration mo_num

Called by:

roothaan_hall_scf()

Calls:

dgemm()

dsort()

roothaan_hall_scf:

File : scf_utils/roothaan_hall_scf.irp.f

subroutine Roothaan_Hall_SCF

Roothaan-Hall algorithm for SCF Hartree-Fock calculation

Needs:

ao_md5 ao_num do_mom eigenvectors_fock_matrix_mo fock_matrix_ao fock_matrix_ao_alpha fock_matrix_ao_alpha fock_matrix_mo

fps_spf_matrix_ao fps_spf_matrix_mo frozen_orb_scf json_int_fmt json_unit level_shift max_dim_diis mo_coef

mo_label mo_num mo_occ n_it_scf_max scf_algorithm scf_energy thresh_scf threshold_diis_nonzero

Called by:

run()

Calls:

dgemm() extrapolate_fock_matrix() initialize_mo_coef_begin_iteration() lock_io() mo_as_eigvectors_of_mo_matrix()

orthonormalize_mos() pivoted_cholesky() reorder_core_orb() reorder_mo_max_overlap() restore_symmetry()

save_mos() sleep() unlock_io() write_double() write_time()

Touches:

fock_matrix_ao_alpha fock_matrix_ao_alpha

mo_coef level_shift

mo_coef