Skip to content

emft

Embedded mean-field theory.

This command runs an EMFT calculation, in which a system is partitioned into two subsystems, with one active subsystem typically treated at a higher level of mean-field theory and the other subsystem treated at a lower level of mean-field theory. See J. Chem. Theory Comput. 2015, 11, 568−580 for a detailed description of the method.

The active subsystem is specified using active; the higher level of theory is specified by a dft subcommand, and the lower level of theory is specified by another dft subcommand. The higher level method subcommand should be specified first, followed by the lower level method subcommand.

For cases where a hybrid DFT is used for the higher-level of theory and a pure DFT is used for the lower-level of theory, there are three different ways to treat the HF exact exchange: EX0, EX1 and EX2, which can be specified via exchange_scheme. See J. Chem. Theory Comput. 2017, 13, 1605−1615 for a detailed description of different schemes for treating exact exchange.

The subsystems are divided by partitioning the density matrix in some one-particle basis. This is specified using option partitioning. The default partitioning is the AO basis partitioning, which partitions the density matrix according to the AO basis functions that belong to the atoms in each subsystem. Another partitioning is the block-orthogonalized (BO) partitioning, in which the AO basis functions for the two subsystems are block orthogonalized and the resulting basis functions are used for partitioning the density matrix. See J. Chem. Theory Comput. 2017, 13, 1605−1615 for a detailed description of different partitionings.

For example, a DC-EMFT calculation on methanol, with the hydroxyl group treated at B3LYP/6-31G* level of theory and the methyl group treated at PBE/STO-3G level of theory, might be run using: 

emft(
  structure( molecule = methanol )
  active = [1:2]
  dft(
    xc = B3LYP
    ao = '6-31G*'
  )
  dft(
    xc = PBE
    ao = 'STO-3G'
  )
)

We note that the level_shift option should not be added to the dft subcommands.

This command can appear in the global context.

Subcommands

Options

active

Specify the active (i.e. high-level) subsystem by providing a list of indices for those atoms that belong to the high-level region. The atoms in the molecule are indexed from 1.

This option is mandatory.

  • The type is [int]
  • There is no default value.
  • The value must be positive
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
)

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
diis

Method of DIIS.

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
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_scheme

Specify the scheme for treating HF exact exchange.

For cases where a hybrid DFT is used for the higher-level of theory and a pure DFT is used for the lower-level of theory, there are three different ways to treat the HF exact exchange: EX0, EX1 and EX2. See J. Chem. Theory Comput. 2017, 13, 1605−1615 for a detailed description of different schemes for treating exact exchange.

  • The type is string
  • The default is EX0
  • The value must be one of:
    • EX0 - The EX0 scheme
    • EX1 - The EX1 scheme
    • EX2 - The EX2 scheme
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.
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.
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_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 shall be used. This strategy improves convergence of non-aufbau occupations.

  • The type is bool
  • The default is false
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
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_analysis

Analyze the atomic contribution to each molecular orbital.

  • The type is bool
  • The default is false
  • The value must be one of:
    • true - Do analyze the atomic contribution to each MO.
    • false - Do not analyze the atomic contribution to each MO.
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
pairwise_potential

Specify the pairwise potential.

  • The type is string
  • There is no default value.
partition_type

Specify the type of system partitioning.

The subsystems are constructed by partitioning the density matrix in a one-particle basis. The default partitioning is density-corrected block-orthogonalized partitioning ('dc'). In this method, the AO basis functions for the two subsystems are block orthogonalized and the resulting basis functions are used for partitioning the density matrix. The energy is then evaluated in the original AO basis.

See J. Chem. Theory Comput. 2017, 13, 1605−1615 for a detailed description of different partitioning strategies.

  • The type is string
  • The default is dc
  • The value must be one of:
    • ao - Partition the system and evaluate the energy using the AO basis set.
    • bo - Partition the system and evaluate the energy using the block-orthogonalized basis set.
    • dc - Partition the system using the block-orthogonalized basis set, and evaluate the energy in the AO basis set.
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
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.

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
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.
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