**SCFCalculateDipole**
*Section*: SCF
*Type*: logical

This variable controls whether the dipole is calculated at the
end of a self-consistent iteration. For finite systems the
default is yes. For periodic systems the default is no, unless
an electric field is being applied in a periodic direction.
The single-point Berry`s phase approximation is used for
periodic directions. Ref:
E Yaschenko, L Fu, L Resca, and R Resta, *Phys. Rev. B* **58**, 1222-1229 (1998).

**SCFCalculateForces**
*Section*: SCF
*Type*: logical

This variable controls whether the forces on the ions are
calculated at the end of a self-consistent iteration. The
default is yes, unless the system only has user-defined
species.

**SCFCalculatePartialCharges**
*Section*: SCF
*Type*: logical
*Default*: no

(Experimental) This variable controls whether partial charges
are calculated at the end of a self-consistent iteration.

**SCFCalculateStress**
*Section*: SCF
*Type*: logical

This variable controls whether the stress on the lattice is
calculated at the end of a self-consistent iteration. The
default is no.

**SCFinLCAO**
*Section*: SCF
*Type*: logical
*Default*: no

Performs the SCF cycle with the calculation restricted to the LCAO subspace.
This may be useful for systems with convergence problems (first do a
calculation within the LCAO subspace, then restart from that point for
an unrestricted calculation).

**ConvAbsDens**
*Section*: SCF::Convergence
*Type*: float
*Default*: 0.0

Absolute convergence of the density:

\(\varepsilon = \int {\rm d}^3r \left| \rho^{out}(\bf r) -\rho^{inp}(\bf r) \right|\).

A zero value (the default) means do not use this criterion.

If this criterion is used, the SCF loop will only stop once it is
fulfilled for two consecutive iterations.

**ConvAbsEv**
*Section*: SCF::Convergence
*Type*: float
*Default*: 0.0

Absolute convergence of the sum of the eigenvalues:

\( \varepsilon = \left| \sum_{j=1}^{N_{occ}} \varepsilon_j^{out} -
\sum_{j=1}^{N_{occ}} \varepsilon_j^{inp} \right| \)

A zero value (the default) means do not use this criterion.

If this criterion is used, the SCF loop will only stop once it is
fulfilled for two consecutive iterations.

**ConvEigenError**
*Section*: SCF::Convergence
*Type*: logical
*Default*: false

If true, the calculation will not be considered converged unless all states have
individual errors less than `EigensolverTolerance`.

If this criterion is used, the SCF loop will only stop once it is
fulfilled for two consecutive iterations.

**ConvEnergy**
*Section*: SCF::Convergence
*Type*: float
*Default*: 0.0

Stop the SCF when the magnitude of change in energy during at
one SCF iteration is smaller than this value.

**ConvRelDens**
*Section*: SCF::Convergence
*Type*: float
*Default*: 1e-6

Relative convergence of the density:

\(\varepsilon = \frac{1}{N} \mathrm{ConvAbsDens}\).

*N* is the total number of electrons in the problem. A
zero value means do not use this criterion.

If you reduce this value, you should also reduce
`EigensolverTolerance` to a value of roughly 1/10 of
`ConvRelDens` to avoid convergence problems.

If this criterion is used, the SCF loop will only stop once it is
fulfilled for two consecutive iterations.

**ConvRelEv**
*Section*: SCF::Convergence
*Type*: float
*Default*: 0.0

Relative convergence of the sum of the eigenvalues:

\(\varepsilon = \frac{ \left| \sum_{j=1}^{N_{occ}} ( \varepsilon_j^{out} - \varepsilon_j^{inp} ) \right|}
{\left| \sum_{j=1}^{N_{occ}} \varepsilon_j^{out} \right|} \)

**MaximumIter**
*Section*: SCF::Convergence
*Type*: integer
*Default*: 200

Maximum number of SCF iterations. The code will stop even if convergence
has not been achieved. -1 means unlimited.
0 means just do LCAO (or read from restart), compute the eigenvalues and energy,
and stop, without updating the wavefunctions or density.

If convergence criteria are set, the SCF loop will only stop once the criteria
are fulfilled for two consecutive iterations.

Note that this variable is also used in the section Calculation Modes::Unoccupied States,
where it denotes the maximum number of calls of the eigensolver. In this context, the
default value is 50.

**MaximumIterBerry**
*Section*: SCF::Convergence
*Type*: integer
*Default*: 10

Maximum number of iterations for the Berry potential, within each SCF iteration.
Only applies if a `StaticElectricField` is applied in a periodic direction.
The code will move on to the next SCF iteration even if convergence
has not been achieved. -1 means unlimited.

**CGAdditionalTerms**
*Section*: SCF::Eigensolver
*Type*: logical
*Default*: no

Used by the cg solver only.
Add additional terms during the line minimization, see PTA92, eq. 5.31ff.
These terms can improve convergence for some systems, but they are quite costly.
If you experience convergence problems, you might try out this option.
This feature is still experimental.

**CGDirection**
*Section*: SCF::Eigensolver
*Type*: integer

Used by the cg solver only.
The conjugate direction is updated using a certain coefficient to the previous
direction. This coeffiction can be computed in different ways. The default is
to use Fletcher-Reeves (FR), an alternative is Polak-Ribiere (PR).
*Options*:

**fletcher**: The coefficient for Fletcher-Reeves consists of the current norm of the steepest descent vector divided by that of the previous iteration.**polak**: For the Polak-Ribiere scheme, a product of the current with the previous steepest descent vector is subtracted in the nominator.

**CGEnergyChangeThreshold**
*Section*: SCF::Eigensolver
*Type*: float
*Default*: 0.1

Used by the cg solver only.
For each band, the CG iterations are stopped when the change in energy is smaller than the
change in the first iteration multiplied by this factor. This limits the number of CG
iterations for each band, while still showing good convergence for the SCF cycle. The criterion
is discussed in Sec. V.B.6 of Payne et al. (1992), Rev. Mod. Phys. 64, 4.
The default value is 0.1, which is usually a good choice for LDA and GGA potentials. If you
are solving the OEP equation, you might want to set this value to 1e-3 or smaller. In general,
smaller values might help if you experience convergence problems.

**CGOrthogonalizeAll**
*Section*: SCF::Eigensolver
*Type*: logical
*Default*: no

Used by the cg solver only.
During the cg iterations, the current band can be orthogonalized
against all other bands or only against the lower bands. Orthogonalizing
against all other bands can improve convergence properties, whereas
orthogonalizing against lower bands needs less operations.

**Eigensolver**
*Section*: SCF::Eigensolver
*Type*: integer

Which eigensolver to use to obtain the lowest eigenvalues and
eigenfunctions of the Kohn-Sham Hamiltonian. The default is
conjugate gradients (`cg`), except that when parallelization in states is
enabled, the default is `rmmdiis`.
*Options*:

**rmmdiis**: Residual minimization scheme, direct inversion in the iterative subspace eigensolver, based on the implementation of Kresse and Furthmüller [*Phys. Rev. B***54**, 11169 (1996)]. This eigensolver requires almost no orthogonalization so it can be considerably faster than the other options for large systems. To improve its performance a large number of`ExtraStates`are required (around 10-20% of the number of occupied states). Note: with`unocc`, you will need to stop the calculation by hand, since the highest states will probably never converge. Usage with more than one block of states per node is experimental, unfortunately.**plan**: Preconditioned Lanczos scheme. Ref: Y. Saad, A. Stathopoulos, J. Chelikowsky, K. Wu and S. Ogut, "Solution of Large Eigenvalue Problems in Electronic Structure Calculations",*BIT***36**, 1 (1996).**cg**: Conjugate-gradients algorithm.**cg_new**: An alternative conjugate-gradients eigensolver, faster for larger systems but less mature. Ref: Jiang et al.,*Phys. Rev. B***68**, 165337 (2003)**evolution**: (Experimental) Propagation in imaginary time.

**EigensolverImaginaryTime**
*Section*: SCF::Eigensolver
*Type*: float
*Default*: 0.1

The imaginary-time step that is used in the imaginary-time evolution
method (`Eigensolver = evolution`) to obtain the lowest eigenvalues/eigenvectors.
It must satisfy `EigensolverImaginaryTime > 0`.
Increasing this value can make the propagation faster, but could lead to unstable propagations.

**EigensolverMaxIter**
*Section*: SCF::Eigensolver
*Type*: integer

Determines the maximum number of iterations that the
eigensolver will perform if the desired tolerance is not
achieved. The default is 25 iterations for all eigensolvers
except for `rmdiis`, which performs only 5 iterations.
Increasing this value for `rmdiis` increases the convergence speed,
at the cost of an increased memory footprint.
In the case of imaginary time propatation, this variable is not used.

**EigensolverMinimizationIter**
*Section*: SCF::Eigensolver
*Type*: integer
*Default*: 5

During the first iterations, the RMMDIIS eigensolver requires
some steepest-descent minimizations to improve
convergence. This variable determines the number of those
minimizations.

**EigensolverSkipKpoints**
*Section*: SCF::Eigensolver
*Type*: logical

Only solve Hamiltonian for k-points with zero weight

**EigensolverTolerance**
*Section*: SCF::Eigensolver
*Type*: float

This is the tolerance for the eigenvectors. The default is 1e-7.

**Preconditioner**
*Section*: SCF::Eigensolver
*Type*: integer

Which preconditioner to use in order to solve the Kohn-Sham
equations or the linear-response equations. The default is
pre_filter, except for curvilinear coordinates, where no
preconditioner is applied by default.
*Options*:

**no**: Do not apply preconditioner.**pre_filter**: Filter preconditioner.**pre_jacobi**: Jacobi preconditioner. Only the local part of the pseudopotential is used. Not very helpful.**pre_poisson**: Uses the full Laplacian as preconditioner. The inverse is calculated through the solution of the Poisson equation. This is, of course, very slow.**pre_multigrid**: Multigrid preconditioner.

**PreconditionerFilterFactor**
*Section*: SCF::Eigensolver
*Type*: float

This variable controls how much filter preconditioner is
applied. A value of 1.0 means no preconditioning, 0.5 is the
standard.

The default is 0.5, except for periodic systems where the
default is 0.6.

If you observe that the first eigenvectors are not converging
properly, especially for periodic systems, you should
increment this value.

The allowed range for this parameter is between 0.5 and 1.0.
For other values, the SCF may converge to wrong results.

**PreconditionerIterationsMiddle**
*Section*: SCF::Eigensolver
*Type*: integer

This variable is the number of smoothing iterations on the coarsest grid for the multigrid
preconditioner. The default is 1.

**PreconditionerIterationsPost**
*Section*: SCF::Eigensolver
*Type*: integer

This variable is the number of post-smoothing iterations for the multigrid
preconditioner. The default is 2.

**PreconditionerIterationsPre**
*Section*: SCF::Eigensolver
*Type*: integer

This variable is the number of pre-smoothing iterations for the multigrid
preconditioner. The default is 1.

**StatesOrthogonalization**
*Section*: SCF::Eigensolver
*Type*: integer

The full orthogonalization method used by some
eigensolvers. The default is `cholesky_serial`, except with state
parallelization, the default is `cholesky_parallel`.
*Options*:

**cholesky_serial**: Cholesky decomposition implemented using BLAS/LAPACK. Can be used with domain parallelization but not state parallelization.**cholesky_parallel**: Cholesky decomposition implemented using ScaLAPACK. Compatible with states parallelization.**cgs**: Classical Gram-Schmidt (CGS) orthogonalization. Can be used with domain parallelization but not state parallelization. The algorithm is defined in Giraud et al., Computers and Mathematics with Applications 50, 1069 (2005).**mgs**: Modified Gram-Schmidt (MGS) orthogonalization. Can be used with domain parallelization but not state parallelization. The algorithm is defined in Giraud et al., Computers and Mathematics with Applications 50, 1069 (2005).**drcgs**: Classical Gram-Schmidt orthogonalization with double-step reorthogonalization. Can be used with domain parallelization but not state parallelization. The algorithm is taken from Giraud et al., Computers and Mathematics with Applications 50, 1069 (2005). According to this reference, this is much more precise than CGS or MGS algorithms. The MGS version seems not to improve much the stability and would require more communications over the domains.

**SubspaceDiagonalization**
*Section*: SCF::Eigensolver
*Type*: integer
*Default*: standard

Selects the method to perform subspace diagonalization. The
default is `standard`, unless states parallelization is used,
when the default is `scalapack`.
Note that this variable is not parsed in the case of the evolution eigensolver.
*Options*:

**none**: No subspace diagonalization. WARNING: this will generally give incorrect results.**standard**: The standard routine. Can be used with domain parallelization but not state parallelization.**scalapack**: State-parallelized version using ScaLAPACK. (Requires that Octopus was compiled with ScaLAPACK support.)

**AtomsMagnetDirection**
*Section*: SCF::LCAO
*Type*: block

This option is only used when `GuessMagnetDensity` is
set to `user_defined`. It provides a direction for the
magnetization vector of each atom when building the guess
density. In order to do that, the user should specify the
coordinates of a vector that has the desired direction and
norm. Note that it is necessary to maintain the ordering in
which the species were defined in the coordinates
specifications.

For spin-polarized calculations, the vectors should have only
one component; for non-collinear-spin calculations, they
should have three components. If the norm of the vector is greater
than the number of valence electrons in the atom, it will be rescaled
to this number, which is the maximum possible magnetization.

**GuessMagnetDensity**
*Section*: SCF::LCAO
*Type*: integer
*Default*: ferromagnetic

The guess density for the SCF cycle is just the sum of all the atomic densities.
When performing spin-polarized or non-collinear-spin calculations this option sets
the guess magnetization density.

For anti-ferromagnetic configurations, the `user_defined` option should be used.

Note that if the `paramagnetic` option is used, the final ground state will also be
paramagnetic, but the same is not true for the other options.
*Options*:

**paramagnetic**: Magnetization density is zero.**ferromagnetic**: Magnetization density is the sum of the atomic magnetization densities.**random**: Each atomic magnetization density is randomly rotated.**user_defined**: The atomic magnetization densities are rotated so that the magnetization vector has the same direction as a vector provided by the user. In this case, the`AtomsMagnetDirection`block has to be set.

**LCAOAlternative**
*Section*: SCF::LCAO
*Type*: logical
*Default*: false

If this variable is set, the LCAO procedure will use an
alternative (and experimental) implementation. It is faster for
large systems and parallel in states. It is not working for spinors, however.

**LCAOComplexYlms**
*Section*: SCF::LCAO
*Type*: logical
*Default*: false

If set to true, and using complex states, complex spherical harmonics will be used, *i.e.*
with \(e^{\pm i m \phi}\).
If false, real spherical harmonics with \(\sin(m \phi)\) or \(\cos(m \phi)\) are used.
This variable will make it more likely to get states that are eigenvectors of the \(L_z\)
operator, with a definite angular momentum.

**LCAODiagTol**
*Section*: SCF::LCAO
*Type*: float
*Default*: 1e-10

Only applies if `LCAOAlternative = true`.
The tolerance for the diagonalization of the LCAO Hamiltonian.

**LCAODimension**
*Section*: SCF::LCAO
*Type*: integer

(Only applies if `LCAOAlternative = no`.)
Before starting the SCF cycle, an initial LCAO calculation can be performed
in order to obtain reasonable initial guesses for spin-orbitals and densities.
For this purpose, the code calculates a number of atomic orbitals.
The number available for a species described by a pseudopotential is all the
orbitals up the maximum angular momentum in the pseudopotential, minus any orbitals that
are found to be unbound. For non-pseudopotential species, the number is equal to
twice the valence charge.
The default dimension for the LCAO basis
set will be the sum of all these numbers, or twice the number of required orbitals
for the full calculation, whichever is less.

This dimension however can be changed by making use of this
variable. Note that `LCAODimension` cannot be smaller than the
number of orbitals needed in the full calculation -- if
`LCAODimension` is smaller, it will be silently increased to meet
this requirement. In the same way, if `LCAODimension` is larger
than the available number of atomic orbitals, it will be
reduced. If you want to use the largest possible number, set
`LCAODimension` to a negative number.

**LCAOExtraOrbitals**
*Section*: SCF::LCAO
*Type*: logical
*Default*: false

Only applies if `LCAOAlternative = true`, and all species are pseudopotentials.
(experimental) If this variable is set to yes, the LCAO
procedure will add an extra set of numerical orbitals (by
using the derivative of the radial part of the original
orbitals). Note that this corresponds roughly to adding orbitals
with higher principal quantum numbers, but the same angular momentum.
This option may cause problems for unoccupied states since you may miss
some lower-lying states which correspond to higher angular momenta instead
of higher principal quantum number.

**LCAOKeepOrbitals**
*Section*: SCF::LCAO
*Type*: logical
*Default*: yes

Only applies if `LCAOAlternative = true`.
If set to yes (the default) Octopus keeps atomic orbitals in
memory during the LCAO procedure. If set to no, the orbitals
are generated each time that they are needed, increasing
computational time but saving memory.

When set to yes, Octopus prints the amount of memory per node
that is required to store the orbitals.

**LCAOMaximumOrbitalRadius**
*Section*: SCF::LCAO
*Type*: float
*Default*: 20.0 a.u.

The LCAO procedure will ignore orbitals that have an
extent greater that this value.

**LCAOScaleFactor**
*Section*: SCF::LCAO
*Type*: float
*Default*: 1.0

The coordinates of the atomic orbitals used by the LCAO
procedure will be rescaled by the value of this variable. 1.0 means no rescaling.

**LCAOStart**
*Section*: SCF::LCAO
*Type*: integer

Before starting a SCF calculation, `Octopus` can perform
a linear combination of atomic orbitals (LCAO) calculation.
These can provide `Octopus` with a good set
of initial wavefunctions and with a new guess for the density.
(Up to the current version, only a minimal basis set is used.)
The default is `lcao_states` if at least one species representing an atom is present.
The default is `lcao_none` if all species are `species_user_defined`,
`species_charge_density`, `species_from_file`, or `species_jellium_slab`.

The initial guess densities for LCAO are taken from the atomic orbitals for pseudopotential species;
from the natural charge density for `species_charge_density`, `species_point`,
`species_jellium`, and `species_jellium_slab`;
or uniform for `species_full_delta`, `species_full_gaussian`,
`species_user_defined`, or `species_from_file`.
Pseudopotential species use the pseudo-wavefunctions as orbitals, full-potential atomic species
(`species_full_delta` and `species_full_gaussian`) use hydrogenic wavefunctions, and
others use harmonic-oscillator wavefunctions.

Note: Some pseudopotential files (CPI, FHI for example) do not
contain full information about the orbitals. In this case,
Octopus generates the starting density from the normalized
square root of the local potential. If no orbitals are
available at all from the pseudopotential files, Octopus will
not be able to perform an LCAO and the initial states will be
randomized.

*Options*:

**lcao_none**: Do not perform a LCAO calculation before the SCF cycle. Instead use random wavefunctions.**lcao_states**: Do a LCAO calculation before the SCF cycle and use the resulting wavefunctions as initial wavefunctions without changing the guess density. This will speed up the convergence of the eigensolver during the first SCF iterations.**lcao_full**: Do a LCAO calculation before the SCF cycle and use the LCAO wavefunctions to build a new guess density and a new KS potential. Using the LCAO density as a new guess density may improve the convergence, but can also slow it down or yield wrong results (especially for spin-polarized calculations).

**MixField**
*Section*: SCF::Mixing
*Type*: integer

Selects what should be mixed during the SCF cycle. Note that
currently the exact-exchange part of hybrid functionals is not
mixed at all, which would require wavefunction-mixing, not yet
implemented. This may lead to instabilities in the SCF cycle,
so starting from a converged LDA/GGA calculation is recommended
for hybrid functionals. The default depends on the `TheoryLevel`
and the exchange-correlation potential used.
*Options*:

**none**: No mixing is done. This is the default for independent particles.**potential**: The Kohn-Sham potential is mixed. This is the default for other cases.**density**: Mix the density.**states**: (Experimental) Mix the states. In this case, the mixing is always linear.

**MixInterval**
*Section*: SCF::Mixing
*Type*: integer
*Default*: 1

When this variable is set to a value different than 1 (the
default) a combined mixing scheme will be used, with MixInterval
- 1 steps of linear mixing followed by 1 step of the selected
mixing. For the moment this variable only works with DIIS mixing.

**MixNumberSteps**
*Section*: SCF::Mixing
*Type*: integer
*Default*: 4

In the Broyden and Bowler_Gillan schemes, the new input density or potential is constructed
from the values of the densities/potentials of a given number of previous iterations.
This number is set by this variable. Must be greater than 1.

**Mixing**
*Section*: SCF::Mixing
*Type*: float
*Default*: 0.3

The linear, Broyden and DIIS scheme depend on a "mixing parameter", set by this variable.
Must be 0 < `Mixing` <= 1.

**MixingPreconditioner**
*Section*: SCF::Mixing
*Type*: logical
*Default*: false

(Experimental) If set to yes, Octopus will use a preconditioner
for the mixing operator.
This preconditioner is disabled for systems with dimension other than 3.

**MixingResidual**
*Section*: SCF::Mixing
*Type*: float
*Default*: 0.05

In the DIIS mixing it is benefitial to include a bit of
residual into the mixing. This parameter controls this amount.

**MixingRestart**
*Section*: SCF::Mixing
*Type*: integer
*Default*: 20

In the Broyden and Bowler_Gillan schemes, the mixing is restarted after
the number of iterations given by this variable.
Set this to zero to disable restarting the mixing.

**MixingScheme**
*Section*: SCF::Mixing
*Type*: integer
*Default*: broyden

The scheme used to produce, at each iteration in the self-consistent cycle
that attempts to solve the Kohn-Sham equations, the input density from the value
of the input and output densities of previous iterations.
*Options*:

**linear**: Simple linear mixing.**bowler_gillan**: The Guaranteed-reduction modification of the Pulay scheme by Bowler and Gillan [D. R. Bowler and M. J. Gillan,*Chem. Phys. Lett.***325**, 473 (2000)].**broyden**: Broyden scheme [C. G Broyden,*Math. Comp.***19**, 577 (1965); D. D. Johnson,*Phys. Rev. B***38**, 12807 (1988)]. The scheme is slightly adapted, see the comments in the code. For complex functions (e.g. Sternheimer with`EMEta`> 0), we use the generalization with a complex dot product.**diis**: Direct inversion in the iterative subspace (diis) scheme [P. Pulay,*Chem. Phys. Lett.*,**73**, 393 (1980)] as described in [G. Kresse, and J. Hurthmueller,*Phys. Rev. B***54**, 11169 (1996)].

**RDMBasis**
*Section*: SCF::RDMFT
*Type*: logical
*Default*: yes

If true, all the energy terms and corresponding derivatives involved in RDMFT will
not be calculated on the grid but on the basis of the initial orbitals

**RDMConvEner**
*Section*: SCF::RDMFT
*Type*: float
*Default*: 1e-6 Ha

Convergence criterion for stopping the overall minimization of the energy with
respect to occupation numbers and the orbitals. The minimization of the
energy stops when the total energy difference between two subsequent
minimizations of the energy with respect to the occupation numbers and the
orbitals is smaller than this criterion. It is also used to exit the orbital minimization.

**RDMHartreeFock**
*Section*: SCF::RDMFT
*Type*: logical
*Default*: no

If true, the code simulates a HF calculation, by omitting the occ.num. optimization
can be used for test reasons

**RDMTolerance**
*Section*: SCF::RDMFT
*Type*: float
*Default*: 1e-7 Ha

Convergence criterion for stopping the occupation numbers minimization. Minimization is
stopped when all derivatives of the energy wrt. each occupation number
are smaller than this criterion. The bisection for finding the correct mu that is needed
for the occupation number minimization also stops according to this criterion.

**RDMToleranceFO**
*Section*: SCF::RDMFT
*Type*: float
*Default*: 1e-4 Ha

Convergence criterion for stopping the diagonalization of the Fock matrix in the Piris method.
Orbital minimization is stopped when all off-diagonal ellements of the Fock matrix
are smaller than this criterion.