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

key word	:	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

key word	:	calculation.SCF.mixingMode
possible values	:	H, mRho, realRho
default value	:	mRho
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

key word	:	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

key word	:	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

key word	:	calculation.SCF.donatorObject
possible values	:	a file name of a saved cNA_LCAO 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
		cNA_LCAO_object.mat,
		or Hamiltonian.mat, Hamiltonian.xml,
		Hamiltonian.txt,
		or DensityMatrix.mat, DensityMatrix.xml,
		DensityMatrix.txt,
		or DensityFunction.mat, DensityFunction.xml,
		DensityFunction.txt
		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\(\times\)n2\(\times\)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 cNA_LCAO
		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

key word	:	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
		GRPulay, MultiSecant

calculation.SCF.mixRate

key word	:	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

key word	:	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

key word	:	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 between its out- and in- values.
		Note 3b: The displayed value of orbitalCharge or
		gridCharge is the difference between its calculated
		value and the real number of electrons in the system.
		Note 3c: The displayed value of any other built-in
		physical quantity listed above is the difference between
		the values calculated in current and last steps.
an example	:	calculation.SCF.monitoredVariableName = …
		{hMatrix rhoMatrix gridCharge
		…transCoeffs conductance}

calculation.SCF.monitoredVariableCalculator

key word	:	calculation.SCF.monitoredVariableCalculator
possible values	:	cell array of calculators with the same length as that
		of monitoredVariableName.
default value	:	For no spin system, {\([\ ]\), \([\ ]\), \([\ ]\), \([\ ]\), \([\ ]\)};
		For spin system, {\([\ ]\), \([\ ]\), \([\ ]\), \([\ ]\), \([\ ]\), \([\ ]\)};
description	:	The calculator defined in each cell is for
		calculation of the corresponding physical quantity in
		the monitoredVariableName.
		For a physical quantity in the list above
		(see possible values of the monitoredVariableName), the
		corresponding calculator can be left empty such that a
		default calculator will be used.
		A non-empty calculator is defined by a structure with
		two fields of class and parameter where the
		field class clarifies the name of the calculator, and
		the field parameter gives its construction parameter.
		The constructor of the calculator will be called in the
		following manner:
		calculator = constructor([cp])
		where
		[cp] = (the definition structure).parameter
		It is used only if monitoredVariableName is given.
an example	:	calculation.SCF.monitoredVariableCalculator = …
		{\([\ ]\), …
		\([\ ]\), …
		\([\ ]\), …
		struct( …
		class, …
		cMonitoredTransmissionAdaptor, …
		parameter, …
		struct(energyPoints,linspace(-1, 0, 100)) …
		), …
		struct( …
		class, …
		cMonitoredConductanceAdaptor …
		) …
		}

calculation.SCF.convergenceCriteria

key word	:	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, the corresponding physical quantity is not
		used in the convergence judgment.
		It is used only if monitoredVariableName is given.
an example	:	calculation.SCF.convergenceCriteria = …
		{\([\ ]\), \([\ ]\), \([\ ]\), \([\ ]\), 1e-3}