hf

Hartree-Fock theory.

In the global context this command runs a Hartree-Fock energy calculation on a system specified through the structure subcommand; in other contexts it can be used to specify details of a HF calculation.

For example, Hartree-Fock on the water molecule can be run using:

hf(
  structure(molecule = water)
  ao = 'cc-pVDZ'
)

This command can appear in the global context.

Subcommands

Options

ansatz

SCF wavefunction ansatz.

The type is string
The default is default
The value must be one of:
- default - default ansatz for given number of electrons
- r - spin-restricted closed-shell ansatz
- u - spin-unrestricted open-shell ansatz
- ro - spin-restricted open-shell ansatz. By default, the Davidson coupling scheme is used. See rohf_scheme for different choices of the coupling schemes.
- cu -
  constrained spin-unrestricted open-shell ansatz of Tsuchimochi and Scuseria.
  
  This ansatz gives the same total energy and wavefunction as the restricted open-shell ansatz ro, but exhibits more robust SCF convergence and gives physically meaningful orbital energies, i.e. satisfying Koopmans' theorem, and the aufbau principle.
  
  Another difference between this ansatz and the ro ansatz is that it yields two different sets of spin orbitals, where as the ro ansatz gives only one set of orbitals for the alpha and beta spins.
  
  However, one can obtain the ro orbitals from the cu wavefunction by setting ro_orbitals_from_cu to true. For example:
```
hf(
  structure( formula = OH bond_length = 1.0 angstrom )
  ao = 'Def2-SVP'
  ansatz = cu
  ro_orbitals_from_cu = true
)
```

ao

Atomic-orbital basis set name. No constraint is implied by the parser, but the basis set file must exist (in the directory basis within the data directory).

Adding pre- or post-fix of (s) will limit the maximum angular momentum to s-functions. (sp) limits to s- and p-functions, and this works up to (spdfghi). The complete set of functions must be present i.e. (s[p[d[f[g[h[i]]]]]]).

Note: the input value must match exactly the name of the basis set file in the basis directory.

This option is mandatory.

The type is string-lowered
There is no default value.

ao_custom

Provide custom basis set for particular elements

The type is {string-lowered}
There is no default value.

ao_threshold

Threshold applied to prescreen AO shell pairs based on radial overlap estimate.

The type is real
The default is 1e-12
The value must be nonnegative

charge

Total molecular charge. No constraint is imposed, but clearly the value has to be such that for a given molecule the number of electrons is nonnegative, and that the number of electrons does not exceed the number that can be described with the given atomic-orbital basis. Note that non-integer values are possible as well.

This option is deprecated. Please use the charge option inside structure instead.

This option is deprecated.

The type is real
There is no default value.

check_fock_norm

Check the norm of the Fock matrix against the numerical derivative of the energy before starting SCF. Only for debugging purposes.

The type is bool
The default is false

coulomb_factor

Factor for electronic Coulomb energy. By and large this should never be changed.

The type is real
The default is 1.0

coulomb_method

Method for computing the Coulomb contribution to Fock matrix and energy.

The type is string
The default is incore_df
The value must be one of:
- incore_df -
  Use conventional incore density-fitting to compute the Coulomb contribution to Fock matrix and energy.
  
  This algorithm is fast but has a memory requirement of about \(8 * N_\text{ao}^2 * N_\text{df}\) Bytes, where \(N_\text{ao}\) and \(N_\text{df}\) are the number of AO and density-fitting basis functions, respectively. Therefore, it may not work for calculations on very large systems or with very large basis; in these cases, use coulomb_method = direct_df instead.
- direct_df -
  Use integral-direct density-fitting to compute the Coulomb contribution to Fock matrix and energy.
  
  This algorithm has minimal memory requirement but is generally slower than the incore_df method. Use it when coulomb_method = incore_df does not work.
  
  This method also indicates use of integral screening (see schwarz_threshold) and incremental Fock build (see incremental_fock).
- direct_4idx -
  Use integral-direct approach to compute the 4-index electron repulsion integrals (ERIs).
  
  Currently, this algorithm is very slow, and is recommended to be used only for testing purposes (on small systems with small basis).

coulomb_metric

Algorithm regarding the storage and use of Coulomb-metric integrals in density fitting.

The type is string
The default is Cholesky
The value must be one of:
- Cholesky - Use Cholesky decomposition of the two-index Coulomb DF integrals and forward/backward substitution to compute DF Coulomb matrix and energy. This is the default algorithm.
- linear solver - Solve the linear system equations for DF Coulomb every SCF step.
- inverse - Use pre-computed (pseudo-)inverse of the two-index DF integrals to compute DF Coulomb. This becomes numerically unstable when system or density-fitting basis is large, so use with caution.
- inverse sqrt - Use pre-computed inverse square-root of the two-index DF integrals to compute DF Coulomb. This requres pre-transformation of 3-index DF integrals.

df

Density fitting basis name. This basis is used to fit products of the form \( |ij) \) where \( i \) and \( j \) are occupied molecular orbitals.

Note: the input value must match exactly the name of the basis set file in the basis directory.

The type is string-lowered
There is no default value.

df_custom

Provide custom density fitting basis set for particular elements

The type is {string-lowered}
There is no default value.

diagonalize_l_z

Switch whether for degenerate orbitals the l_z operator shall be diagonalized in order to obtain a unique set of orbitals. This is for example useful for linear molecules. If your calculation is on a single atom, use diagonalize_l_z_atom.

The type is bool
The default is false

diagonalize_l_z_atom

See diagonalize_l_z; in case of a single atom, this switch is used instead of diagonalize_l_z. For single atoms the default is to make use of the option.

The type is bool
The default is true

diis

Method of DIIS.

The type is string-lowered
The default is adiis+cdiis
The value must be one of:
- none - DIIS is not used.
- cdiis - This is the original DIIS algorithm by P. Pulay. P. Pulay, Chem. Phys. Lett. 73, 393 (1980).
- ediis - Energy-based DIIS which minimizes the Hartree-Fock energy functional. Kudin, Scuseria and Cances, J. Chem. Phys. 116, 8255 (2002).
- adiis - DIIS based on the augmented Roothaan--Hall energy. X. Hu and W. Yang, J. Chem. Phys. 132, 054109 (2010).
- ediis+cdiis - Combination of these two algorithms; see diis_switch_threshold_grad
- adiis+cdiis - Combination of these two algorithms; see diis_switch_threshold_grad

diis_max

Maximum number of vectors for DIIS.

The type is int
The default is 10
The value must be nonnegative

diis_shift

Diagonal shift for regularization of DIIS.

The type is real
The default is 0
The value must be nonnegative

diis_switch_threshold_grad

In DIIS modes ADIIS+CDIIS and EDIIS+CDIIS the algorithm is switched to CDIIS if the gradient falls below this threshold.

The type is real
The default is 1e-1
The value must be nonnegative

dispersion

Add dispersion correction to energy

The type is string
There is no default value.
The value must be one of:
- none - No dispersion correction
- D3 - Use Grimme D3 zero damping dispersion correction

energy_threshold

SCF convergence threshold using the absolute value of the energy difference between iterations.

The type is real
The default is 1e-6
The value must be nonnegative

exchange_factor

Factor for exact exchange. The default value is 1.0 for Hartree-Fock, 0.0 for Hartree theory, and whatever the appropriate factor is for hybrid exchange-correlation functionals. This option is overridden for range separated hybrid functionals.

The type is real
There is no default value.

exchange_method

Method for computing the exact exchange contribution to Fock matrix and energy.

The type is string
The default is pre_transformed_df
The value must be one of:
- incore_df -
  Use conventional incore density-fitting to compute the exchange contribution to Fock matrix and energy.
  
  This algorithm is fast but has a memory requirement of about \(8 * N_\text{ao}^2 * N_\text{df}\) Bytes, where \(N_\text{ao}\) and \(N_\text{df}\) are the number of AO and density-fitting basis functions, respectively. Therefore, it may not work for calculations on very large systems or with very large basis; in these cases, use coulomb_method = direct_df instead.
- pre_transformed_df -
  Use the pre-transformed density-fitting integrals to compute the exact exchange contribution to Fock matrix and energy.
  
  This algorithm is faster than incore_df when SCF converges slowly (ca. with more than 10 SCF steps), and the speepup increases with the number of SCF steps; but is slower when SCF converges within a few steps.
  
  This algorithm has the same memory requirement as incore_df.
- occupied_df -
  Use the occ-RI-K algorithm (incore version) to compute the exact exchange contribution to Fock matrix and energy.
  
  This algorithm is ~ 2 times faster than incore_df for normal calculations (e.g. with double-zeta AO basis), and the speedup increases when larger basis is used.
  
  See this paper for a detailed description of the algorithm.
  
  This algorithm has the same memory requirement as incore_df.
- semi_numeric - Use semi-numeric approach to compute the exact exchange contribution to Fock matrix and energy.
- direct_4idx -
  Use integral-direct approach to compute the 4-index electron repulsion integrals (ERIs).
  
  Currently, this algorithm is very slow, and is recommended to be used only for testing purposes (on small systems with small basis).

final_threshold

Final threshold for pre-screening integrals during direct SCF. A shell block of integrals are computed only when the product of the integral estimate (based on Cauchy-Schwarz inequality) and the largest density matrix element within the shell block is larger than this threshold. This is applied to later stage of SCF iterations.

The type is real
The default is 1e-12
The value must be nonnegative

fock_damping

Amount of previous Fock matrix to use in Fock damping. The new Fock matrix for iteration \( n \): \( F_{n} = (1-\alpha) F_{n} + \alpha F_{n-1} \) where \( \alpha \) is the fock_damping_factor.

The type is real
The default is 0.7

fock_damping

Amount of previous Fock matrix to use in Fock damping. The new Fock matrix for iteration \( n \): \( F_{n} = (1-\alpha) F_{n} + \alpha F_{n-1} \) where \( \alpha \) is the fock_damping_factor.

The type is real
The default is 0.7

fock_damping_gradient_threshold

If this keyword is specified, Fock matrix extrapolation is initially performed using a damping (see fock_damping). When the largest element of the absolute orbital gradient drops below fock_damping_gradient_threshold, DIIS will be used. If this keyword is absent, DIIS is used straight away.

The type is real
There is no default value.

fock_damping_gradient_threshold

If this keyword is specified, Fock matrix extrapolation is initially performed using a damping (see fock_damping). When the largest element of the absolute orbital gradient drops below fock_damping_gradient_threshold, DIIS will be used. If this keyword is absent, DIIS is used straight away.

The type is real
There is no default value.

frozen_grid

Use the frozen-grid approximation when calculating geometrical derivatives.

The type is bool
The default is false

guess

Initial guess for the SCF wavefunction.

The type is string
The default is SAD
The value must be one of:
- SAD - Superposition of Atomic Densities (SAD).
- H0 - Using eigenvectors of the core Hamiltonian as the initial guess. This is equivalent to setting the initial density to zero.

incremental_fock

Whether to use incremental Fock build for computing the Coulomb and exact exchange contributions to Fock matrix and energy.

By default, this is turned on for integral direct algorithms and off for in-core algorithms. Explicitly setting this option will override the default behaviour.

The type is bool
There is no default value.

initial_threshold

Initial threshold for pre-screening integrals during direct SCF. A shell block of integrals are computed only when the product of the integral estimate (based on Cauchy-Schwarz inequality) and the largest density matrix element within the shell block is larger than this threshold. Only effective when incremental_fock is on. This is applied to earlier stage of SCF iterations. The threshold will be tightened to final_threshold when switching_threshold is satisfied.

The type is real
The default is 1e-9
The value must be nonnegative

level_shift

Turn on level shifting to improve SCF convergence. Raises the energy of virtual orbitals by level shifting value. Whether to remove the level shift at the end is controlled by option remove_level_shift.

The type is real
The default is 0
The value must be nonnegative

load

Name of assigned result (containing orbitals) to start the SCF from.

The type is string
There is no default value.

max_incremental_fock_steps

Maximum number of steps of incremental Fock build before a full Fock build.

The type is int
The default is 20
The value must be positive

max_iter

Maximum number of SCF iterations.

The type is int
The default is 128
The value must be nonnegative

mom

Switch whether the maximum overlap method (MOM) will be used. This strategy improves convergence of non-aufbau occupations. CAUTION: Once mom is activated, the occupation numbers are fixed. A calculation with, for example, temperature may not work as intended in combination with mom.

The type is bool
The default is false

mom_activation_threshold

If MOM is used, an initial occupation first needs to be established before it can be kept. If this threshold is set to a non-zero value, MOM will be switched on once the electronic gradient falls below this threshold, keeping the occupation obtained at that iteration. The special value 0 indicates that MOM keeps the initial occupation (from the first cycle).

The type is real
The default is 0.0

multiplicity

Spin multiplicity \(2S + 1\) - only valid for integer-electron calculations. For non-integer-electron number, or for higher multiplcities, use the spin option.

By default entos selects the lowest available spin multiplicity.

The type is string
There is no default value.
The value must be one of:
- singlet - 2S + 1 = 1; S = 0
- doublet - 2S + 1 = 2; S = 1/2
- triplet - 2S + 1 = 3; S = 1
- quartet - 2S + 1 = 4; S = 3/2
- quintet - 2S + 1 = 5; S = 2
- sextet - 2S + 1 = 6; S = 5/2

name

Specify the name of a set of results.

This option is deprecated.

The type is string
There is no default value.

no_fail

If set to true, the program will continue its execution even if the SCF does not converge. This is useful for frozen-orbital calculations.

The type is bool
The default is false

no_symmetry_breaking

In case of a unrestricted singlet calculation, in the first cycle half of the electron(s) in the alpha HOMO is shifted to the LUMO, unless this flag is set to true or the SCF starts from previous orbitals.

The type is bool
The default is false

number_type

Number type for orbitals and operators, whether real or complex.

The type is string
The default is real
The value must be one of:
- real - Use real numbers for orbital coefficents and fock matrices.
- complex - Use complex numbers for orbitals coefficents and fock matrices.

orbital_grad_threshold

SCF convergence threshold using the infinity norm of the orbital gradient.

The type is real
The default is 1e-5
The value must be nonnegative

orthogonalization

Method to orthogonalize the atomic orbital basis. Note that in case of a nearly linearly dependent basis (see overlap_threshold) the canonical algorithm is used irrespective of this option.

The type is string-lowered
The default is symmetric
The value must be one of:
- symmetric - Symmetric orthogonalization of the AO basis. Uses the symmetric inverse square root of the overlap matrix for the orthogonalization.
- canonical - Canonical orthogonalization of the AO basis.
- cholesky - Orthogonalization through Cholesky decomposition of the overlap matrix.

overlap_threshold

Threshold for throwing away the smallest eigenvalues of the overlap matrix. This is a safety measure for calculations with near-linearly dependent basis sets. Usually, the default value should be fine.

The type is real
The default is 1e-7
The value must be nonnegative

print_level

Print level.

The type is int
There is no default value.
The value must be one of:
- -2 - No output
- -1 - Minimum output
- 0 - Output that doesn't scale with system size
- 1 - Output that scales linearly with system size
- 2 - (Debugging) output that scales quadratically with system size
- 3 - (Debugging) output that scales cubically with system size

pseudo_diagonalization

Whether to use pseudo-diagonalization instead of full diagonalization of the Fock matrix. Recommended for calculations on very large systems or with a very large basis.

The type is bool
The default is false

radial_threshold

Threshold for radial density cutoff, used in screening in the evaluation of exchange-correlation functionals.

The type is real
The default is 1e-6

remove_level_shift

Remove level shift from final orbitals.

The type is bool
The default is true

ro_orbitals_from_cu

Whether to constuct ROHF/ROKS orbitals and orbital energies from a converged CUHF/CUKS wavefunction.

The type is bool
The default is true

rohf_scheme

The coupling scheme for constructing the ROHF effective Fock matrix. Note that different choices give the same SCF total energy, but they give different sets of orbitals and orbital energies. See Plakhutin, Gorelik, and Breslavskaya, J. Chem. Phys. 125, 204110 (2006) for a comprehensive discussion on different coupling schemes.

The type is string-lowered
The default is davidson
The value must be one of:
- mcweeny_diercksen - Use the couping scheme of McWeeny and Diercksen. See McWeeny and Diercksen, J. Chem. Phys. 49, 4852 (1968)
- davidson - Use the couping scheme of Davidson. See Davidson, Chem. Phys. Lett. 21, 565 (1973)

schwarz_threshold

Threshold applied to Cauchy-Schwarz integral screening.

The type is real
The default is 1e-10
The value must be nonnegative

scramble_complex

Add noise to the imaginary part of the guess density while keeping it hermitian. This option is only used if number_type = complex.

The type is bool
The default is true

scramble_complex_density_only

Scramble only the initial density (leaving the orbitals unchanged) in complex orbital calculations. Use scramble_complex to scramble the density and orbitals.

The change in the guess density implies a change in the guess orbitals and/or occupation numbers which are needed for orbital-dependent potentials. To obtain the adapted orbitals and occupations, the density must be diagonalized, which may be expensive. Usually, most parts of the potential are calculated directly from the density and scrambling in these parts is sufficient to break the symmetry. Thus, one may be able to achieve symmetry-breaking even when the orbitals and occupations are left unchanged.

The type is bool
The default is false

scramble_parameter

The amount of noise that is added to the imaginary part of the guess density. This option is only relevant if scramble_complex is true.

The type is real
The default is 1e-5

sparse_density_fitting

Whether to use the sparse form of the density fitting integrals for in-core density fitting. The sparsity can be controlled with ao_threshold.

The type is bool
The default is false

spin

For spin-unrestricted calculations: spin is \(2S\), where S is the total spin angular momentum

Notice that the value of this option need not be an integer. See the documentation on spin_z for an explanation.

By default entos selects the lowest available spin multiplicity.

The type is real
There is no default value.
The value must be nonnegative

spin_z

For spin-unrestricted calculations, \(2m_s\), the number of alpha-spin electrons minus the number of beta-spin electrons.

If omitted, spin_z defaults to be the same as the total spin angular momentum.

Notice that the value of this option need not be an integer, and need not be the same as the value of spin. See this paper for an explanation of noninteger charge.

The thinking is similar to thinking about non-integer charge. A fractional-charge (fc) density matrix is a mixed state of the density matrices of two Slater determinants (each with integer charge)

\[ \rho_\text{fc}(N+1/2) = \rho(N)/2 + \rho(N+1)/2 . \]

A fractional-spin (fs) density matrix is a mixed state of two density matrices with different numbers of alpha and beta electrons

\[ \rho_\text{fs}(S=S, m_s=0) = \rho(N_\alpha = N_\text{el}/2 + S, N_\beta = N_\text{el}/2 - S )/2 + \rho(N_\alpha = N_\text{el}/2 - S, N_\beta = N_\text{el}/2 + S )/2 . \]

The type is real
There is no default value.

switching_threshold

This threshold controls switching between initial_threshold and final_threshold during an integral-direct SCF calculation. It is applied to the root-mean-square of the change in density matrix elements between two consecutive SCF iterations.

The type is real
The default is 1e-4
The value must be nonnegative

temperature

Specify the temperature for the electrons and perform the SCF calculation in the canonical-ensemble. Convergence is often poor with the default convergence settings, and using the original Pulay DIIS method is recommended (see diis option).

The type is quantity
The default is 0 kelvin

hf

Subcommands

Options

Sierra

Resources