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]}