3.9 Eigenvalue solver and (fractional) occupation numbers

With an updated Hamiltonian matrix $h_{ij}$ and overlap matrix $s_{ij}$ available at the end of an s.c.f. iteration ( $i, j$ run over all basis functions), or in the post-processing step of the calculation, FHI-aims updates the Kohn-Sham orbitals $l$ (wave function coefficients $c_{jl}$ ) by solving the following eigenvalue problem:

\sum_{j}h_{ij}c_{jl}=\epsilon_{l}\sum_{j}s_{ij}c_{jl}\quad.

(3.38)

In periodic boundary conditions, this eigenvalue problem is solved at every $k$ -point, and $\mathbf{k}$ is implictly included in the eigenstate index $l$ above.

FHI-aims now uses the open-source ELSI infrastructure http://wordpress.elsi-interchange.org – and most often the efficient, massively parallel ELPA eigensolver (http://elpa.mpcdf.mpg.de) – to handle all aspects of this problem.

Since the basis size needed even for meV-converged accuracy in FHI-aims is rather small, and this size determines the dimension of $h_{ij}$ and $s_{ij}$ , the recommended eigenvalue solver(s) in FHI-aims are customized conventional solvers (publicly available as the ELPA library since 2011), employing the same basic algorithms as LAPACK or the parallel ScaLAPACK implementation, but with significant scalability enhancements. Although these solvers scale strictly as $O(N^{3})$ with system size, their application becomes dominant only for systems above $\approx$ 1000 atoms (light elements) or $\approx$ 500 atoms (heavy elements, e.g. Au) in our experience. For large systems, there are alternative methods available through the ELSI library, including the orbital minimization method (libOMM), the pole expansion and selected inversion method (PEXSI), the shift-and-invert parallel spectral transformation eigensolver (SLEPc-SIPs), and the density matrix purification algorithms using sparse matrix linear algebra from the NTPoly library. Note that PEXSI and SLEPc-SIPs are not installed with FHI-aims by default.

The present section describes the available eigensolvers and density matrix solvers and relevant options in FHI-aims, including the determination of a Fermi level and occupation numbers for all orbitals following the process. Keywords starting with a prefix elsi_ are ELSI-specific. The key ideas of using ELSI and its supported solvers are briefly introduced here. For more information, please refer to the ELSI documentation available at http://wordpress.elsi-interchange.org.

FHI-aims also offers the possibility to solve a constrained eigenvalue problem, e.g., in order to restrict the number of spin-up or spin-down electrons in the basis functions of a given set of atoms. Since this functionality is experimental and for experienced users only, it is documented separately in Sec. 3.14.

Finally, we emphasize that the basis set in FHI-aims is non-orthogonal. For all practical production settings, this is not a problem, and in fact taken care of through the overlap matrix $s_{ij}$ in Eq. (3.38) above. It is, however, still possible to generate an overcomplete, nearly ill-conditioned basis set in practical calculations, usually by specific, deliberate user action. The signature of such ill-conditioning are near-zero eigenvalues of $s_{ij}$ (e.g., 10^-5 and below). Possible reasons include: systematically constructed, deliberately overconverged basis sets for non-periodic calculations (not easy); excessively large cutoff radii in dense periodic structures together with very large basis sets (the density of non-zero basis functions per volume element increases as $r_{\text{cut}}^{3}$ ); or, badly integrated, very extended basis functions (diffuse Gaussian basis functions without increasing radial_multiplier appropriately).

FHI-aims does include a number of safeguards against an ill-conditioned overlap matrix, most importantly the basis_threshold keyword that projects out the eigenvectors of the overlap matrix that correspond to its smallest eigenvalues, usually enabling a meaningful calculation anyway. However, to alert every user to the fact that their chosen basis set may be ill-conditioned, the code now stops when it encounters an overlap matrix with too low eigenvalues— unless the keyword override_illconditioning is deliberately set, indicating that the user knows what they are doing and wishes to continue regardless.

Tags for general section of control.in:

Tag: basis_threshold(control.in)

Usage: basis_threshold threshold
Purpose: Threshold to prevent any accidental ill-conditioning of the basis set.
threshold is a small positive threshold for the eigenvalues of the overlap matrix. Default: 10^-5.

Since NAO basis functions are situated at different atomic centers in a structure, they form a non-orthogonal basis set by construction. Usually, this is not a problem, since the non-orthogonality is naturally accounted for by inserting the overlap matrix $s_{ij}$ into the Kohn-Sham eigenvalue problem, Eq. (3.38). For very large basis sets, this can lead to accidental ill-conditioning (some basis functions may be exactly expressable as linear combinations of some others).

This behavior is detected by directly inverting the overlap matrix, and computing its eigenvalues. If one or more eigenvalues are smaller than threshold, the corresponding eigenvectors are projected out of the basis before solving the Kohn-Sham eigenvalue problem, and the latter is solved after transforming to the reduced eigenbasis-set of the overlap matrix.

Important change: Even when basis_threshold is set, FHI-aims will automatically stop when a near-singular overlap matrix is detected. The user can still override this safeguard by setting the override_illconditioning keyword in control.in explicitly, but we do now do our best to alert the user to this condition.

Tag: elpa_settings(control.in)

Usage: elpa_settings setting
Purpose: Allows to determine the exact algorithm used in the ELPA eigensolver by hand.
setting is a descriptor (string) that selects certain aspects of ELPA. Default: auto

If the parallel ELPA eigensolver is used (see keyword KS_method), a number of choices are made automatically by default. The elpa_settings keyword allows to set some of these aspects by hand. Allowed choices for setting are:

•

auto : The default. ELPA makes all its choices on the fly.
•

one_step_solver : Only the one-step tridiagonalization (and corresponding back transformation) are used. This is usually the slower choice, but not always …
•

two_step_solver : Only the two-step tridiagonalization (and corresponding back transformation) are used. This is usually the faster choice, but not always …

The elpa_settings keyword is particularly useful
(i) if you already know what the faster choice is, and you wish to eliminate the extra test of the slower solver from your calculations, or
(ii) if you suspect that one of the two solvers links to a buggy external(!) library. LAPACK and BLAS implementations (still used in ELPA) come from many vendors, they are often precompiled, and of course they always work—the computer vendor hopes so, after all. We have seen our share of bugs in external libraries (outside the control of FHI-aims), and sometimes, switching the algorithm to change the exact subroutines used can be a helpful backup check.

Tag: empty_states(control.in)

Usage: empty_states number
Purpose: Specifies how many Kohn-Sham states beyond the occupied levels are computed by the eigensolver.
number is the integer number of empty Kohn-Sham states per atom to be computed beyond the occupied levels.

For DFT-LDA/GGA, typically only a small (but non-zero) number of empty states is required to allow a complete determination of the Fermi level.

By default, ( $l$ +1)²+2 states are added for each atom in the structure, where $l$ is the maximum valence angular momentum in the valence of that atom ( $l$ =0 for hydrogen, but $l$ =3 for $f$ -electron atoms and beyond).

For correlated methods including excited states (MP2, RPA, $G W$ , …), all available states should be included. To achieve this, set empty_states to a large number (safely larger than your basis set) or use the calculate_all_eigenstates keyword.

In fact, for SOC calculations (include_spin_orbit), empty_states is set to a large number by default.

Tag: calculate_all_eigenstates(control.in)

Usage: calculate_all_eigenstates
Purpose: Specifies that all possible eigenstates obtainable from the basis set used (after ill-conditioning has been accounted for) should be calculated and stored.

This keyword instructs FHI-aims to calculate and store all possible eigenstates obtainable from the solution of the Kohn-Sham eigenvalue problem. It functions identically to setting the empty_states value to a large number, but makes the input file prettier.

Only users that know exactly what they’re doing should use this option alongside an ill-conditioned basis set. Strange output may occur in this case, which may either be spurious or a symptom of a deeper problem. (This is true of ill-conditioning in general; this keyword only exposes it more openly.)

Tag: fermi_acc(control.in)

Usage: fermi_acc tolerance
Purpose: The precision with which the Fermi level for occupation numbers will be determined.
tolerance : Tolerance parameter for the zero point search of the equation $\sum_{i}f_{\text{occ}}[\epsilon_{F}](\epsilon_{i})-n_{\text{el}}=0$ . Default: 10^-20.

Usually, this tag need not be modified from the default. Within the (standard) Brent’s method search for the Fermi level, tolerance has more than one function. Leave untouched unless problems arise.

Tag: initial_ev_solutions(control.in)

Usage: initial_ev_solutions number
Purpose: Experimental! Number of initial eigenvalue solutions using direct methods before switching on the lopcg-solver. Applies for both LAPACK and ScaLAPACK variants of the solver.
number is a positive integer. Default: 5.

Tag: KS_method(control.in)

Usage: KS_method KS_type
Purpose: Algorithm used to solve the generalized eigenvalue problem Eq. (3.38).
KS_type is a keyword (string) which specifies the update method used for the Kohn-Sham eigenvectors or density matrix in each s.c.f. iteration. Default: serial or parallel, depending on available number of CPUs.

Important change : The naming scheme of the supported options has changed. Notably, the lapack and scalapack keywords are superseded by serial and parallel, respectively. The reason is that lapack and scalapack have indicated other linear algebra than custom (Sca)LAPACK in FHI-aims for a long time. For example, the scalapack option actually employed the ELPA eigenvalue solver, currently called through the ELSI infrastructure. The new naming scheme indicates linear algebra default options that may develop further over time, but these default options will not necessarily be tied to one and the same library going forward.

Available options for the eigensolver, KS_type, are:

•

serial : Default serial eigensolver implementation. Currently the serial eigensolver in ELSI, based on LAPACK and ELPA, will be employed.
•

lapack_fast : Synonymous with serial.
•

lapack_2010 : LAPACK-based, and similar to the divide&conquer based standard solver provided by LAPACK itself.
•

lapack_old : Expert solver provided by standard LAPACK. This is stable and not a bottleneck in most standard situations.
•

lapack : Disabled now.
•

parallel : Default parallel eigensolver implementation. Currently the ELPA eigensolver will be called through the ELSI interface.
•

elsi : Synonymous with parallel.
•

elpa : Synonymous with parallel.
•

elpa_2013 : Same functionality as scalapack_old, however, substantially rewritten for an overall speedup and much improved scalability. See the elpa_settings keyword for some ELPA internals (usually determined automatically, but who knows).
Note that you must set the shell variable OMP_NUM_THREADS=1 prior to running FHI-aims on some platforms. (see Appendix A)
•

scalapack_fast : Synonymous with parallel.
•

scalapack_old : Fully memory-parallel implementation of the eigenvalue solver based on ScaLAPACK itself, scales much worse than our own scalapack_fast.
•

scalapack : Disabled now.
•

svd : Effectively the same as lapack_old.
•

lopcg : Experimental – under development Iterative, locally optimal preconditioned conjugate gradient eigensolver. Potentially useful for very large systems where lapack becomes a bottleneck. However, implementation without any serious testing—contact us if interested.
•

scalapack+lopcg : Experimental – under development. Same as lopcg, but parallel with ScaLAPACK-type memory distribution.

The parallel eigensolvers are only available if ScaLAPACK support has been compiled into the FHI-aims binary—see the Makefile for more information.

In fact, the default parallel eigensolver in FHI-aims is the “ELPA” solver through the ELSI interface, which uses some ScaLAPACK infrastructure but has been rewritten from the ground up for much improved parallel scalability.

Note that a (separate) parallelization over $k$ -points will be performed in periodic systems in any case.

KS_method parallel allows calculations without explicitly collecting the resulting eigenvectors to each thread after the eigensolution is complete. This improves the memory efficiency especially in large-scale / massively parallel situations and is the default where possible. For details, see keyword collect_eigenvectors.

Prior to the solution of Eq. (3.38) using the serial or parallel solvers, the overlap matrix $s_{ij}$ is checked for ill-conditioning (see basis_threshold keyword). For very large basis sets or periodic calculations with many $k$ -points, this criterion may trigger. In that case, the Hamiltonian matrix is transformed to the “safe” set of eigenvectors of $s_{ij}$ , and the transformed eigenvalue problem is solved. If you suspect ill-conditioning to be a problem, it may sometimes be helpful to increase the density of the 3D integration grids in order to minimize any numerical noise in $s_{ij}$ and $h_{ij}$ . That said: In our experience, ill-conditioning is not a problem with accurate basis sets in standard calculations; see Appendix A for some additional comments.

Tag: elsi_method(control.in)

Usage: elsi_method method
Purpose: Determines the usage of eigensolvers or density matrix solvers in ELSI. Must be compatible with the density_update_method keyword (see Sec. 3.6).
method is a keyword (string). Default: ev.

Available options for method are:

•

ev : Use eigensolvers to solve the wave functions explicitly through ELSI. Supported serial solver is LAPACK. Supported parallel solvers are ELPA and SLEPc-SIPs (if compiled in). Compatible with all options of density_update_method.
•

dm : Use density matrix solvers to directly compute the density matrix without explicitly solving the eigenproblem in Eq. (3.38). Note that this will not work with any post-processing that requires the wave functions. Supported solvers are ELPA, libOMM, PEXSI, SLEPc-SIPs, and NTPoly. Only compatible with density_update_method density_matrix.

Tag: elsi_solver(control.in)

Usage: elsi_solver solver
Purpose: Specifies the eigensolver or density matrix solver to use.
solver is a keyword (string). Default: elpa.

Available options for solver are:

•

elpa : Direct, dense eigensolver ELPA (EigensoLvers for Petaflop Applications). Scales as $O(N^{3})$ with respect to system size. Fast for systems of small and medium sizes (up to hundreds of atoms).
•

omm : Density matrix solver libOMM (the Orbital Minimization Method). Scales as $O(N^{3})$ . No support for metallic systems. Not recommended for now.
•

pexsi : Density matrix solver PEXSI (the Pole EXpansion and Selected Inversion method). Scales as $O(N^{2})$ for 3D systems, $O(N^{1.5})$ for 2D systems, and $O(N)$ for 1D systems. Fast when solving a large system with sufficiently many MPI tasks (a thousand or more). PEXSI is not compiled with FHI-aims by default. To use it, either enable the compilation of PEXSI when building FHI-aims wiht CMake, or link FHI-aims against a precompiled ELSI library with PEXSI support.
•

eigenexa : Experimental Direct, dense eigensolver EigenExa. The pentadiagonalization eigensolver eigen_sx in EigenExa can be faster than ELPA when solving the full eigenspectrum. Requires an externally compiled EigenExa library. No support for complex-valued problems. Therefore, in periodic calculations the number of $k$ -points in any direction cannot be greater than 2.
•

sips : Experimental Sparse eigensolver SLEPc-SIPs (the Shift-and-Invert Parallel spectral transformation method). Requires externally compiled SLEPc and PETSc libraries. Not recommended for now. No support for complex-valued problems. Therefore, in periodic calculations the number of $k$ -points in any direction cannot be greater than 2.
•

ntpoly : Density matrix purification algorithms implemented in the NTPoly library. For sufficiently large systems, scales as $O(N)$ . Only competitive for thousands of atoms.
•

magma : Experimental GPU-accelerated direct, dense eigensolvers in MAGMA. Drop-in enhancement to the eigensolvers in LAPACK. Requires an externally compiled MAGMA library.

Tag: elsi_elpa_solver(control.in)

Usage: elsi_elpa_solver solver
Purpose: Specifies the eigensolver used in ELPA.
method is an integer. Default: 2.

Available options for solver are:

•

1 : One-stage tridiagonalization eigensolver.
•

2 : Two-stage tridiagonalization eigensolver.

Tag: elsi_elpa_n_single(control.in)

Usage: elsi_elpa_n_single n_single
Purpose: Specifies the number of s.c.f. steps in which the eigenproblems Eq. (3.38) are solved using single precision ELPA solvers.
n_single is an integer. Default: 0.

Tag: elsi_elpa_gpu(control.in)

Usage: elsi_elpa_gpu gpu
Purpose: Switches on the usage of GPU (CUDA) acceleration in ELPA.
gpu is an integer. Default: 0.

Tag: elsi_omm_n_elpa(control.in)

Usage: elsi_omm_n_elpa n_elpa
Purpose: When using libOMM, specifies the number of s.c.f. steps in which the eigenproblems Eq. (3.38) are solved explicitly using ELPA. As an iterative solver, libOMM’s performance heavily depends on the quality of the initial guess. By default, random numbers are used as inital guess. The eigensolution computed by ELPA proves to be a better choice.
n_elpa is an integer. Default: 6.

Tag: elsi_omm_flavor(control.in)

Usage: elsi_omm_flavor flavor
Purpose: Specifies the flavor of libOMM to be used.
flavor is an integer. Default: 0.

Available options for flavor are:

•

0 : Directly minimizes the OMM energy functional without transforming the generalized eigenproblem to the standard form before minimization. This is usually faster than flaver 2 if using several ELPA steps before switching to libOMM.
•

2 : Before OMM minimization, first transforms the generalized eigenproblem to the standard form using the Cholesky decomposition of the overlap matrix.

Tag: elsi_omm_tol(control.in)

Usage: elsi_omm_tol tolerance
Purpose: Specifies the convergence criterion of the OMM energy functional minimization.
tolerance is a small positive real number. Default: 10^-12.

Tag: elsi_pexsi_np_symbo(control.in)

Usage: elsi_pexsi_np_symbo np_symbo
Purpose: Specifies the number of MPI tasks assigned for the symbolic factorization step in PEXSI.
np_symbo is a positive integer. Default: 1.

Parallel symbolic factorization with more than 1 MPI task is not always stable, hence the default. Increasing np_symbo might accelerate the symbolic factorization, however might also cause a segfault. Note that the symbolic factorization step needs to be performed only once per s.c.f. cycle. Unless facing a memory bottleneck, using the default value is recommended.

Tag: elsi_eigenexa_method(control.in)

Usage: elsi_eigenexa_method method
Purpose: Specifies the eigensolver used in EigenExa.
method is an integer. Default: 2.

Available options for solver are:

•

1 : One-stage tridiagonalization eigensolver.
•

2 : One-stage pentadiagonalization eigensolver.

Tag: elsi_sips_n_slice(control.in)

Usage: elsi_sips_n_slice n_slice
Purpose: Specifies the number of slices used in SLEPc-SIPs. Note that the total number of MPI tasks must be a multiple of the number of slices. In practice, setting n_slice to be equal to the number of nodes seems to work well. The default value should always work, but by no means leads to the best performance.
type is a positive integer. Default: 1.

Tag: elsi_sips_n_elpa(control.in)

Usage: elsi_sips_n_elpa n_elpa
Purpose: Specifies the number of s.c.f. steps to be solved with ELPA. The performance of SIPs relies on a decent knowledge on the eigenvalue distribution, which is key to an efficient spectrum slicing. This can be calculated by ELPA in the first n_elpa s.c.f. steps.
type is an integer. Default: 0.

Tag: elsi_ntpoly_method(control.in)

Usage: elsi_ntpoly_method method
Purpose: Specifies the purification algorithm used in NTPoly.
method is an integer. Default: 2.

Available options for method are:

•

0 : Canonical purification.
•

1 : Trace-correcting purification.
•

2 : 4th order trace-resetting purification.
•

3 : Generalized canonical purification.

Tag: elsi_ntpoly_tol(control.in)

Usage: elsi_ntpoly_tol tolerance
Purpose: Specifies the convergence criterion of the density matrix purification.
tolerance is a small positive real number. Default: 10^-4.

Tag: elsi_ntpoly_filter(control.in)

Usage: elsi_ntpoly_filter threshold
Purpose: Specifies the threshold smaller than which the matrix elements will be discarded in the process of density matrix purification.
tolerance is a small positive real number. Default: 10^-8.

Tag: elsi_magma_solver(control.in)

Usage: elsi_magma_solver solver
Purpose: Specifies the eigensolver used in MAGMA.
method is an integer. Default: 1.

Available options for solver are:

•

1 : One-stage tridiagonalization eigensolver.
•

2 : Two-stage tridiagonalization eigensolver.

Tag: elsi_build_dm_method(control.in)

Usage: elsi_build_dm_method method
Purpose: Specifies which method is used in ELSI to build the density matrix from eigenvectors.
method is a keyword (string). Default: auto.

Available options for method are:

•

auto : ELSI will automatically determine the best choice to build the density matrix, dependent on the calculation conditions (e.g. occupations of density matrix), whether ELPA is available, and whether CPU or GPU is used (see the options below for more details on which method is chosen by ELSI, and please also consult the ELSI manual).
•

elpa_at_a : ELPA $\mathbf{A}^{T}\mathbf{A}$ optimized routine. This is the best choice on CPU and GPU. Available in the ELSI internally shipped ELPA 2020 version. It will also be available in the latest ELPA 2025.06.002 version, if externally compiled and linked to FHI-aims via ELSI.
•

elpa_at_b : ELPA $\mathbf{A}^{T}\mathbf{B}$ generic routine to perform the $\mathbf{A}^{T}\mathbf{A}$ operation. Available in all versions of ELPA. Not as fast as elpa_at_a. Fallback on GPU if elpa_at_a is not available.
•

elpa_pxgemm : ELPA PXGEMM - an experimental ELPA matrix multiply routine, only available in ELPA versions $\geq$ 2025.01.001. Currently not as fast as elpa_at_a or elpa_at_b on CPU or GPU. If selected and the method is not available, will attempt to fall back to elpa_at_a.
•

rank_update : Rank Update - a rank-k update with the ScaLAPACK pdsyrk routine. Second fastest on CPU behind elpa_at_a. Fallback if elpa_at_a is not available on CPU. Fallback on CPU and GPU if ELPA is not available.
•

pdgemm : PDGEMM - ScaLAPACK matrix multiply routine. Only used if there are negative factors (negative occupations) for a real density matrix. Very slow, not recommended otherwise.

Note: this keyword will only work with ELSI versions 2.12.0 and above.

Tag: frozen_core_scf(control.in)

Usage: frozen_core_scf boolean
Purpose: Enables the frozen core approximation to reduce the dimension of the Kohn-Sham eigenproblem.
boolean is either .true. or .false.. Default: .false.

This functionality can lead to significantly improved runtimes of the self-consistent field cycle for large systems containing heavy elements, for which the eigenvalue solver dominates the runtime.

A complete description of the implemented method can be found in reference [325]. Please cite this reference if the functionality is used successfully.

The frozen_core_scf keyword must be combined with the frozen_core_scf_cutoff keyword in order to be effective.

Atomic basis functions whose eigenvalue is lower than frozen_core_scf_cutoff will be treated as core states. Useful for systems consisting of heavy elements. This keyword applies only to the solution of the Kohn-Sham eigenproblem. It does not imply a frozen core treatment anywhere else.

See also frozen_core and frozen_core_postscf, which are not the same functionality and which control the use of frozen core approximations in other parts of the code.

Tag: frozen_core_scf_cutoff(control.in)

Usage: frozen_core_scf_cutoff cutoff
Purpose: Determines the number of core states when the frozen core approximation is enabled by frozen_core_scf. Atomic basis functions whose eigenvalue is lower than cutoff (eV) will be treated as core states.
cutoff is a negative number. Default: -13605.5 (eV, which is about -500 Ha)

We recommend a default cutoff of $-$ 200 eV (conservative) for effective use. More aggressive values (e.g., $-$ 100 eV) are possible, especially for smaller systems.

Conversely, if too shallow orbitals are included in the frozen core (e.g., cutoff $-$ 50 eV or even more shallow), the s.c.f. convergence of larger systems may be negatively affected. We suggest to proceed with caution here.

Tag: frozen_core_scf_core_correction(control.in)

Usage: frozen_core_scf_core_correction boolean
Purpose: Provides better accuracy for the frozen core states when the frozen core approximation is enabled by frozen_core_scf.
boolean is either .true. or .false.. Default: .true.

Tag: frozen_core_scf_valence_correction(control.in)

Usage: frozen_core_scf_valence_correction boolean
Purpose: Provides better accuracy for the unfrozen valence states when the frozen core approximation is enabled by frozen_core_scf.
boolean is either .true. or .false.. Default: .true.

Tag: lopcg_adaptive_tolerance(control.in)

Usage: lopcg_adaptive_tolerance flag
Purpose: Experimental! Allows the lopcg-algorithm to dynamically adjusts its convergence tolerance as $\max{\{0.01\,|\delta n|,\hbox{\keyword{lopcg\_tolerance}}\}}$ where $\delta n$ is the change in the electron density as recorded in the self-consistency cycles.
flag is a logical expression. Default: .false.

Tag: lopcg_block_size(control.in)

Usage: lopcg_block_size number
Purpose: Experimental! The maximal size of a block in lopcg-iteration.
number is a positive integer. Default: 1.

Tag: lopcg_auto_blocksize(control.in)

Usage: lopcg_auto_blocksize flag
Purpose: Experimental! Selects if the lopcg algorithm tries to find automatically a better blocksize than the maximal one by grouping close eigenvalues together.
flag is a logical expression. Default: .false.

Tag: lopcg_preconditioner(control.in)

Usage: lopcg_preconditioner type
Purpose: Experimental! For KS_method lopcg, specifies the preconditioner used.
type is a string, either diagonal (diagonal preconditioning matrix) or ovlp_inverse (use inverse of the overlap matrix for preconditioning).

Tag: lopcg_start_tolerance(control.in)

Usage: lopcg_start_tolerance tolerance
Purpose: Experimental! Sets the tolerance for starting the lopcg-solver using the change in the sum of eigenvalues as a criterion. The lopcg-solver is activated as set in initial_ev_solutions latest, but lopcg_start_tolerance may trigger it earlier.
tolerance is a double precision real. Default: 0.0

Tag: lopcg_tolerance(control.in)

Usage: lopcg_tolerance tolerance
Purpose: Experimental! Sets the convergence tolerance for the lopcg-solver.
tolerance is a double precision real. Default: 10^-6.

Tag: max_lopcg_iterations(control.in)

Usage: max_lopcg_iterations number
Purpose: Experimental! Sets the maximal number of iterations for one block in the the lopcg-solver.
number is an integer. Default: 100.

Tag: mu_determination_method(control.in)

Usage: mu_determination_method type
Purpose: Specifies the algorithm used to search for the Fermi level.
type is a descriptor (string) which specifies the desired algorithm to determine the Fermi level. Default: bisection

Available options are:

•

bisection : Standard bisection algorithm. Usually robust to reach an accuracy of 10^-13 in terms of electron count. If a desired accuracy cannot be reached by the bisection iteration, e.g., due to the limit of the machine precision, the remaining error (very small) will be arbitrarily cancelled out. Not compatible with the integer occupation_type.
•

zeroin : Standard Brent’s method. Not compatible with the cubic or the cold occupation_type.

Tag: max_zeroin(control.in)

Usage: max_zeroin number
Purpose: Number of iterations allowed in Brent’s method to find the Fermi level.
number is an integer number. Default: 200.

Usually, this tag need not be modified from the default. This limits the number of allowed iterations for the (standard) Brent’s method search for the Femi level. Leave untouched unless problems arise. Note that changing the values given for occupation_type or empty_states may be the true fixes if the search for a Fermi level really ever fails.

Tag: occupation_acc(control.in)

Usage: occupation_acc tolerance
Purpose: Accuracy with which the sum of calculated occupation numbers for a given Fermi level reproduces the actual number of electrons in the system.
tolerance is a small positive real number. Default: 10^-13.

Usually, this tag need not be modified from the default. Determines the target accuracy for the Fermi level (calculated vs. actual number of electrons in the system). Note that changing the values given for occupation_type or empty_states may be the true fixes if the search for a Fermi level really ever fails.

Tag: occupation_type(control.in)

Usage: occupation_type type width [order]
Purpose: Determines the broadening scheme used to find the Fermi level and occupy the Kohn-Sham eigenstates.
type is a string which determines the desired broadening function. Default: gaussian
width specifies the width of the broadening function [in eV]. Default: 0.01 eV.
order is an integer, and only required to specify the order of type methfessel-paxton.

Based on the eigenvalues $\epsilon_{l}$ of each s.c.f. iteration, the selected occupation_type determines the Fermi level $\epsilon_{F}$ and occupies all Kohn-Sham states with fractional occupation numbers $f_{l}(\epsilon_{F})$ for the following electron density update. Detailed discussions can be found in Ref. [36] or other standard literature [176]. We only briefly list the available options for the occupation type here:

•

gaussian : Gaussian broadening function [98]

$f_{l}=0.5\cdot[1-\erf(\frac{\epsilon_{l}-\epsilon_{F}}{\mathtt{width}})]$
•

methfessel-paxton : Generalized Gaussian-type distribution functions of Methfessel and Paxton (see Ref. [220] for details). In practice, any order beyond 1 is not recommended, and is not supported if bisection is chosen for the keyword mu_determination_method.
•

fermi : Formally correct finite-temperature broadening scheme [219]

$f_{l}=\frac{1}{1+\exp[(\epsilon_{l}-\epsilon_{F})/\mathtt{width}]}$

However, to be useful in practice, width must take on values significantly greater than $k T$ at room temperature, and therefore mostly loses its physical meaning. In practice, fermi broadening seems to lead to faster-increasing total energy inaccuracies than gaussian broadening, which is why the latter is preferred in FHI-aims.
•

integer : Forces the occupation numbers to be integers.
•

cubic : Experimental Cubic polynomial broadening.
•

cold : Cold smearing technique proposed by Marzari and Vanderbilt [213]

$f_{i}=0.5\left[\mathrm{erf}\left(x_{i}-\frac{1}{\sqrt{2}}\right)+\sqrt{\frac{2% }{\pi}}\exp\left(-\left[x-\frac{1}{\sqrt{2}}\right]^{2}\right)+1\right]$

with $x_{i}=\frac{\epsilon_{F}-\epsilon_{i}}{\mathtt{width}}$ .

For metallic systems / systems with small HOMO-LUMO gap, the availability of an occupation scheme with finite width (e.g., 0.1 eV) is critical to guarantee the stable convergence of the s.c.f. cycle. Especially for metallic systems, FHI-aims outputs an extrapolated total energy, which estimates the total energy for zero broadening based on the entropy of the electron gas [176, 104, 310]. This extrapolated total energy must only be used for metallic systems, not, e.g., for atoms with a decidedly discrete density of states.

For non-metallic systems / systems with appreciable HOMO-LUMO gap, the broadening width must be finite in order to guarantee the existence of a formal Fermi level, but not so large as to lead to any actual fractional occupation numbers. In our experience, the default width of 0.01 eV performs well for this purpose.

Tag: override_illconditioning(control.in)

Usage: override_illconditioning flag
Purpose: Allows to override a built-in stop and run with a nearly singular overlap matrix.
flag is a logical flag, either .true. or .false. Default: .true.

If the overlap matrix $s_{ij}$ has an eigenvalue below basis_threshold or below 10^-5 (whichever is larger), FHI-aims will stop and warn the user of a potentially ill-conditioned basis set. Usually this situation can still be resolved by setting an appropriate value of basis_threshold, but anyone relying on this functionality should first check whether their “ill-conditioning” condition is not also due to another, inadvertent choice, such as an insufficient integration grid for very extended functions, or an excessively large cutoff radius in dense periodic systems (is it really necessary?).

In other words: By all means, override if you wish, but check first whether all computational settings are actually intentional and appropriate.