Parameters for calculating densityOfStates

Parameters here are for calculating the density of states (DOS).

calculation.densityOfStates.method

key word	:	calculation.densityOfStates.method
possible values	:	GreenFunction or WaveFunction
default value	:	WaveFunction for 1D, 2D, and 3D bulk systems,
		GreenFunction for molecule and systems with probes.
description	:	The method used for the calculation of the density of
		states.
an example	:	calculation.densityOfStates.method = GreenFunction

calculation.densityOfStates.isResolved

key word	:	calculation.densityOfStates.isResolved
possible values	:	true or false
default value	:	false
description	:	If true, the density of states (dos) is resolved in
		k-space, instead of integrated over the Brillouin zone.
an example	:	calculation.densityOfStates.isResolved = 0

calculation.densityOfStates.kSpaceGridNumber

key word	:	calculation.densityOfStates.kSpaceGridNumber
possible values	:	3\(\times\)1 integer array
default value	:	the value of calculation.k_spacegrids.number which was
		used in the Hamiltonian calculation, or [1 1 1] if an
		user provided Hamiltonian is used.
description	:	the small k-space grid number in each direction which,
		together with kSpaceGridShift, are used to produce the
		parameter kSpacePoints.
an example	:	calculation.densityOfStates.kSpaceGridNumber = [10 10 10]

calculation.densityOfStates.kSpaceGridShift

key word	:	calculation.densityOfStates.kSpaceGridShift
possible values	:	3\(\times\)1 or 1\(\times\)3 array, [s\(_1\), s\(_2\), s\(_3\)], with each s\(_i\) a
		double number between 0 and 1.
default value	:	if the densityOfStates.kSpaceGridNumber is given, or if an
		user provided Hamiltonian is used, the default value is [0
		0 0], otherwise the default value is the value of
		calculation.k_spacegrids.shift which was used in the
		hamiltonian calculation.
description	:	k-space grid point shift. While all s\(_i\) are set to be 0,
		the Gamma point is always among the k-space grid points
		being generated; otherwise, the k-space grid points will
		be shifted s\(_1\), s\(_2\), and s\(_3\) grid length along their
		grid vector directions, respectively.
an example	:	calculation.densityOfStates.kSpaceGridShift = [1/2 1/2 1/2]

calculation.densityOfStates.kSpacePoints

key word	:	calculation.densityOfStates.kSpacePoints
possible values	:	3\(\times\)n double array
default value	:	defined in the k-point file if the file is given by
		the parameter densityOfStates.kPointFile, or produced by
		the parameters densityOfStates.kSpaceGridNumber and
		densityOfStates.kSpaceGridShift.
description	:	the fractional coordinates of n (transverse) wave vectors
		which are used in the k-space integration, or at which
		the resolved dos is calculated.
an example	:	calculation.densityOfStates.kSpacePoints = [0 0 0]

calculation.densityOfStates.kPointWeights

key word	:	calculation.densityOfStates.kPointWeights
possible values	:	1\(\times\)n double array
default value	:	defined in the k-point file if the corresponding
		parameter densityOfStates.kSpacePoints is using the
		k-values in the same file. Otherwise, equally weighted
		or calculated by nanodcal.
description	:	the weights of k-space points in the k-space
		integration.
an example	:	calculation.densityOfStates.kPointWeights = [1/2 1/3 1/6]

calculation.densityOfStates.kPointFile

key word	:	calculation.densityOfStates.kPointFile
possible values	:	a file name
default value	:	no default value
description	:	the name of a file which contains the coordinates of
		k-space points and their corresponding weights.
		A k-point file with n k-points has (n+1) lines: one line
		of headers and n lines of values of the n k-points.
		The headers are:
		number : the sequential number of the k-point
		k1, k2, k3 : fractional coordinates of the k-point
		divisor : used to modify k1, k2, and k3 so that the
		real fractional coordinates are
		k1/divisor, k2/divisor, k3/divisor
		weight : relative weights of the k-points for
		k-space integration. It is normalized
		so that sum(weight) = 1.
		where the headers number, divisor, and weight are
		optional.
an example	:	calculation.densityOfStates.kPointFile = k-points.dat

calculation.densityOfStates.isIntegrated

key word	:	calculation.densityOfStates.isIntegrated
possible values	:	true or false
default value	:	false
description	:	If true, the density of states (dos) is integrated over
		the given energy range, instead of being expressed as a
		function of energy.
an example	:	calculation.densityOfStates.isIntegrated = 0

calculation.densityOfStates.energyRange

key word	:	calculation.densityOfStates.energyRange
possible values	:	a 2\(\times\)1 double array
default value	:	no default value
description	:	When isIntegrated is true, this parameter defines the
		energy range over which dos is integrated.
		When isIntegrated is false, this parameter is used
		together with numberOfEnergyPoints, to define the
		parameter energyPoints.
		Note that for bulk system its values are measured from
		the Fermi energy, and for system with leads its values
		are measured from the chemical potential of a lead
		that has zero applied voltage.
an example	:	calculation.densityOfStates.energyRange = [-10,10]

calculation.densityOfStates.numberOfEnergyPoints

key word	:	calculation.densityOfStates.numberOfEnergyPoints
possible values	:	an integer number
default value	:	20 when isIntegrated is true and the method is
		GreenFunction, otherwise determined by parameters
		energyRange and energyInterval.
description	:	When isIntegrated is true, this parameter is used to
		perform the integration.
		When isIntegrated is false, this parameter is used
		together with energyRange, to define the parameter
		energyPoints.
an example	:	calculation.densityOfStates.numberOfEnergyPoints = 100

calculation.densityOfStates.energyInterval

key word	:	calculation.densityOfStates.energyInterval
possible values	:	a double number
default value	:	5e-2 eV
description	:	Energy interval used to determine the parameter
		numberOfEnergyPoints.
an example	:	calculation.densityOfStates.energyInterval = 1e-3

calculation.densityOfStates.energyPoints

key word	:	calculation.densityOfStates.energyPoints
possible values	:	n\(\times\)1 double array with n an integer
default value	:	Fermi energy or chemical potentials of all the leads when
		energyRange is not given; otherwise, determined by
		energyRange and numberOfEnergyPoints.
description	:	when isIntegrated is true, this parameter is used
		together with energyPointWeights, to perform the
		energy integration.
		When isIntegrated is false, the density of states
		will be calculated at those energy points.
		Note that for bulk system its values are measured from
		the Fermi energy, and for system with leads its values
		are measured from the chemical potential of a lead
		that has zero bias voltage.
an example	:	calculation.densityOfStates.energyPoints = 0

calculation.densityOfStates.energyPointWeights

key word	:	calculation.densityOfStates.energyPointWeights
possible values	:	double array with the same length of energyPoints.
default value	:	no default value.
description	:	the weights used in the energy space integration.
		The parameter is used when and only when
		isIntegrated is true and the energyPoints is given
		explicitly.
an example	:	calculation.densityOfStates.energyPointWeights = …
		ones(1,101)/3

calculation.densityOfStates.whatProjected

key word	:	calculation.densityOfStates.whatProjected
possible values	:	None, Atom, Orbital, Ell
default value	:	None
description	:	If Atom or Orbital, the dos is projected on the
		given orbitals or atoms. If Ell, the dos is projected
		on orbitals with the given angular momentum. If None,
		not projected.
an example	:	calculation.densityOfStates.whatProjected = Orbital

calculation.densityOfStates.indexProjected

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

calculation.densityOfStates.whatLocalized

key word	:	calculation.densityOfStates.whatLocalized
possible values	:	None, Region, Point
default value	:	None
description	:	If Region, the local dos will be integrated over a
		given real space region. If Point, the local
		dos will be expressed as a function of r. If None, no
		local analysis is performed.
an example	:	calculation.densityOfStates.whatLocalized = Region

calculation.densityOfStates.regionPosition

key word	:	calculation.densityOfStates.regionPosition
possible values	:	a 3\(\times\)1 double array
default value	:	no default value
description	:	When whatLocalized is Region, this parameter and
		regionVectors define a real space region over which
		local dos is integrated. When whatLocalized is
		Point and realSpacePoints is not given, this
		parameter, regionVectors and regionGridNumber
		will define the parameter realSpacePoints. When
		whatLocalized is None, this parameter is not used.
an example	:	calculation.densityOfStates.regionPosition = [1,1,1]

calculation.densityOfStates.regionVectors

key word	:	calculation.densityOfStates.regionVectors
possible values	:	a 3\(\times\)3 double array
default value	:	no default value
description	:	When whatLocalized is Region, this parameter and
		regionPosition define a real space region over which
		local dos is integrated, where the columns of
		regionVectors are the three basis vectors of the region.
		When whatLocalized is Point and realSpacePoints
		is not given, this parameter, regionPosition, and
		regionGridNumber will define the parameter
		realSpacePoints. When whatLocalized is None, this
		parameter is not used.
an example	:	calculation.densityOfStates.regionVectors = eye(3)*0.3

calculation.densityOfStates.regionGridNumber

key word	:	calculation.densityOfStates.regionGridNumber
possible values	:	3\(\times\)1 integer vector
default value	:	no default value
description	:	the small grid number in each direction. It is used
		to divide the region defined by regionPosition and
		regionVectors to a number of small grids for
		integration over the region. When whatLocalized is
		Point and realSpacePoints is not given, this
		parameter, regionPosition, and regionVectors define
		the parameter realSpacePoints.
an example	:	calculation.densityOfStates.regionGridNumber = [4 4 4]

calculation.densityOfStates.realSpacePoints

key word	:	calculation.densityOfStates.realSpacePoints
possible values	:	3\(\times\)n double array with n an integer
default value	:	determined by regionPosition, regionVectors, and
		regionGridNumber
description	:	the real space points at which the local density of states
		is calculated. When whatLocalized is None or
		Region, this parameter is not used.
an example	:	calculation.densityOfStates.realSpacePoints = [0 0 0]

calculation.densityOfStates.eta

key word	:	calculation.densityOfStates.eta
possible values	:	a small double number
default value	:	5e-2 eV
description	:	The Lorentz broadening width used to smooth the dos when
		the GreenFunction method is used.
		Note that the unit used is defined by input parameter
		calculation.control.energyUnit, and default unit is eV.
an example	:	calculation.densityOfStates.eta = 1e-2

calculation.densityOfStates.plot

key word	:	calculation.densityOfStates.plot
possible values	:	true or false
default value	:	false
description	:	If true, a plot will be given after the calculation.
an example	:	calculation.densityOfStates.plot = true

calculation.densityOfStates.broadening

key word	:	calculation.densityOfStates.broadening
possible values	:	0, 1, 2
default value	:	1
description	:	The calculated density of states as a function of energy
		may not look smooth enough and it normally needs to do
		the gaussian broadening to make it looks more smooth.
		If it is 0, do not do the broadening.
		If it is 1, do the broadening by using a gaussian
		function as the broadening function, where the standard
		deviation parameter of the gaussian function is defined
		through the input parameter broadeningWidth.
		If it is 2, re-do the broadening (with a different
		broadening width) on the density of states which has
		already been calculated before.
an example	:	calculation.densityOfStates.broadening = 2

calculation.densityOfStates.broadeningWidth

key word	:	calculation.densityOfStates.broadeningWidth
possible values	:	a small double number
default value	:	2
description	:	The half width at half maximum (HWHM) of the broadening
		function, in the unit of the minimum interval between
		the energy points. For a gaussian function with a
		standard deviation SD, the HWHM is sqrt(2ln2)*SD,
an example	:	calculation.densityOfStates.broadeningWidth = 4