# Parameters for calculating SCF

In the self-consistent field (SCF) calculation of DFT, terms that depend on the self-consistent density matrix are calculated iteratively and parameters here are for those calculations.

## calculation.SCF.startingMode

**keyword**: calculation.SCF.startingMode

**possible values**: ‘H’, ‘mRho’, ‘realRho’

**default value**: ‘H’

**description**: The SCF cycle can start from different physical
quantities. If the startingMode is ‘H’, SCF starts from
Hamiltonian; if ‘mRho’, it starts from rho matrix; if
‘realRho’, SCF starts from real space density.

**an example**:

```
calculation.SCF.startingMode = 'H'
```

## calculation.SCF.mixingMode

**keyword**: calculation.SCF.mixingMode

**possible values**: ‘H’, ‘mRho’, ‘realRho’

**default value**: ‘H’

**description**: In the SCF iterations, the mixing value could be any of
Hamiltonian matrix, rho matrix, and real space density.
‘H’ here is for Hamiltonian, ‘mRho’ for rho matrix, and
‘realRho’ for real space density.

**an example**:

```
calculation.SCF.mixingMode = 'H'
```

## calculation.SCF.maximumSteps

**keyword**: calculation.SCF.maximumSteps

**possible values**: an integer

**default value**: 5000

**description**: The maximum steps in the SCF cycle.

**an example**:

```
calculation.SCF.maximumSteps = 20
```

## calculation.SCF.maximumTime

**keyword**: calculation.SCF.maximumTime

**possible values**: a double number

**default value**: inf

**description**: When the computer cpu time is limited for a job, this
parameter gives the maximum (wall) time which can be
used for this SCF calculation. Nanodcal will estimate
the time needed for a SCF cycle, and finish the SCF
calculation automatically before the time limit is
reached.
The unit is hour.

**an example**:

```
calculation.SCF.maximumTime = 48
```

## calculation.SCF.donatorObject

**keyword**: calculation.SCF.donatorObject

**possible values**: a file name of a saved cNanodcal object, Hamiltonian
structure, density matrix structure, or real space
charge density structure

**default value**: [] (empty)

**description**: The value of the starting physical quantity will be
taken from the donatorObject. It can be the saved file
‘NanodcalObject.mat’,
or ‘Hamiltonian.mat’, ‘Hamiltonian.xml’,
or ‘DensityMatrix.mat’, ‘DensityMatrix.xml’,
or ‘DensityFunction.mat’, ‘DensityFunction.xml’,
of another calculation.

If the SCF.startingMode is ‘realRho’, the donatorObject can also be a saved data structure whose name must be ‘data’ and have at least two fields ‘gridRepresentativePoint’ and ‘functionValues’. The value of the field ‘gridRepresentativePoint’ can only be chosen from the three strings ‘lowerCorner’, ‘center’, and ‘upperCorner’. The value of ‘functionValues’ is a cell array, whose length depends the spin type of the system. Each cell contains a n1 x n2 x n3 double matrix where n1, n2 and n3 are grid numbers along the three central cell basis vector directions. For a no-spin system, data.functionValues{1} is the total charge density. For collinear spin system, data.functionValues{1} is spin up charge density, and data.functionValues{2} is spin down. For non-collinear spin system, data.functionValues{1}, data.functionValues{2}, and data.functionValues{3} are spin up, down, up-down charge density, respectively. Note that the term charge density used here is density of the number of electrons which is in atomic unit.

Please note that it is not allowed to use the cNanodcal object as a donator if the object file is in the current directory and the data format of the object is distributed.

**an example**:

```
calculation.SCF.donatorObject = []
```

## calculation.SCF.mixMethod

**keyword**: calculation.SCF.mixMethod

**possible values**: Linear, Quadratic, Broyden, Pulay, GRPulay, MultiSecant

**default value**: Broyden

**description**: With this parameter an user may select a built-in mixer.
If the parameter calculation.SCF.mixer is given, this
parameter will not be used.

**an example**:

```
calculation.SCF.mixMethod = Pulay
```

## calculation.SCF.mixRate

**keyword**: calculation.SCF.mixRate

**possible values**: a small double number

**default value**: 0.1

**description**: A parameter to control the mixing rate with the method
selected by the parameter calculation.SCF.mixMethod.
If the parameter calculation.SCF.mixer is given, or the
parameter calculation.SCF.mixMethod is not given, this
parameter will not be used.

**an example**:

```
calculation.SCF.mixRate = 1e-3
```

## calculation.SCF.mixer

**keyword**: calculation.SCF.mixer

**possible values**: a structure with two fields of ‘class’ and ‘parameter’

**default value**: struct(‘class’, ‘cMixerBroyden’)

**description**: This input parameter defines a plug-in calculator,
where the field ‘class’ clarifies the name of the
calculator, and the field parameter gives its
construction parameter. The constructor of the plug-in
calculator will be called in the following manner:
calculator = constructor([cp])
where
[cp] = calculation.SCF.mixer.parameter

For information about how to replace this plug-in calculator, type “nanodcal -help plug-in” and “nanodcal -api”.

Available mixers built-in nanodcal are cMixerLinear, cMixerQuadratic, cMixerBroyden, cMixerPulay, and cMixerGRPulay. Users can also plug-in their own mixers.

**an example**:

```
calculation.SCF.mixer.class = cMixerPulay
calculation.SCF.mixer.parameter.beta = 1e-3
```

## calculation.SCF.monitoredVariableName

**keyword**: calculation.SCF.monitoredVariableName

**possible values**: cell array of strings. The string in each cell is the
name of a physical quantity, which can either be chosen
from the following built-in name list or defined by the
user.
The built-in physical quantity name list:
‘hMatrix’
‘rhoMatrix’
‘gridCharge’
‘orbitalCharge’
‘totalEnergy’
‘subTotalEnergy’
‘bandEnergy’
‘realSpaceRho’
‘realSpaceVdh’
‘realSpaceVeff’
‘spinPolar’

**default value**: For no spin system, the default value is {‘hMatrix’,
‘rhoMatrix’, ‘bandEnergy’, ‘gridCharge’,
‘orbitalCharge’};
For spin system, the default value is {‘hMatrix’,
‘rhoMatrix’, ‘bandEnergy’, ‘gridCharge’,
‘orbitalCharge’, ‘spinPolar’}.

**description**: Name list of variables to be monitored.

Note 1: If the ‘hMatrix’ and the ‘rhoMatrix’ are missing in the name list, they will be automatically added in. The ‘spinPolar’ will also be automatically added in for spin systems.

Note 2: If there is any user-defined name among the name list, the corresponding calculator must be specified in the calculation.SCF.monitoredVariableCalculator.

Note 3a: The displayed value of ‘hMatrix’, or ‘rhoMatrix’, or ‘realSpaceRho’ which is chosen to be mixing is the difference beween its out- and in- values.

Note 3b: The displayed value of ‘orbitalCharge’ or ‘gridCharge’ is the difference beween its calculated value and the real number of electrons in the system.

Note 3c: The displayed value of ‘spinPolar’ is its calculated value.

Note 3d: The displayed value of any other built-in physical quantity listed above is the difference beween the values calculated in current and last steps.

**an example**:

```
calculation.SCF.monitoredVariableName = ...
{'hMatrix' 'rhoMatrix' 'gridCharge'
...'transCoeffs' 'conductance'}
```

## calculation.SCF.convergenceCriteria

**keyword**: calculation.SCF.convergenceCriteria

**possible values**: cell array of small numbers with the same length as
that of monitoredVariableName.

**default value**: 1e-3, 1e-4, or 1e-5 Hartree for ‘hMatrix’, 1e-3, 1e-4,
or 1e-5 for ‘rhoMatrix’, depending on the value of the
parameter calculation.control.precision.

**description**: The SCF loop will stop when all monitored variables
satisfy this criteria. In the criteria array, if a cell
is empty and the corresponding physical quantity is
‘hMatrix’ or ‘rhoMatrix’, the default value for
‘hMatrix’ or ‘rhoMatrix’ will be used; if a cell is
empty and the corresponding physical quantity is neither
‘hMatrix’ nor ‘rhoMatrix’, the corresponding physical
quantity will not be used in the convergence judgment.

This parameter is used only when monitoredVariableName is given.

**an example**:

```
calculation.SCF.convergenceCriteria = ...
{[], [], [], [], 1e-3}
```

## calculation.densityOfStates.indexProjected

**keyword**: calculation.densityOfStates.indexProjected

**possible values**: cell array of n\(\times\)1 integer array

**default value**: all ells, orbitals, or atoms

**description**: Each cell, which contains a n\(\times\)1 integer array to
represent a set of atoms or orbitals, or ell values of
angular momentum, defines a projector. Density of states
projected on each set of those atoms or orbitals will be
calculated respectively.
This parameter is not used when whatProjected is
None.
Please note that the order of the atoms and orbitals
have been listed in the output file Atoms.txt, which
can be used to identify the orbital or atom index.

**an example**:

```
calculation.densityOfStates.indexProjected = ...
{[1 4 7], [2 5 8], [3 6 9]}
```