Fillings input documentation

Initialize occupation factor (smearing) scheme.

Used to initialize class qimpy.electrons.Fillings.

YAML template:

charge: 0.0          # Net charge of electrons + ions in e units.
smearing: gauss      # Smearing method for setting electron occupations.
sigma: 0.002         # Width of the smearing function in Hartrees.
kT: null             # Specify temperature instead of sigma for Fermi smearing.
mu: nan              # Electron chemical potential in Hartrees.
mu-constrain: no     # Whether to hold chemical potential fixed to mu.
B: 0.0               # External magnetic field (only for spin-polarized modes).
M: 0.0               # Total magnetization (only for spin-polarized modes).
M-constrain: no      # Whether to hold magnetization fixed to M.
n-bands: null        # Specify number of bands or scheme to determine it.
n-bands-extra: null  # Number of extra bands retained by diagonalizers.

Parameters:

charge

Type: float, Default: 0.0

Net charge of electrons + ions in e units. This determines n_electrons = ions.Z_tot - charge.

smearing

Type: string, Default: gauss

Smearing method for setting electron occupations. Here ‘gauss’, ‘fermi’, ‘cold’, ‘mp1’ select Gaussian, Fermi-Dirac, Cold and first order Methfessel-Paxton (MP1) smearing respectively. Use no (or null) to disable smearing and keep the electron occupations fixed at their initial values.

sigma

Type: float, Default: 0.002

Width of the smearing function in Hartrees. This sets Gaussian width \(\sigma\) in the Gaussian, Cold and M-P schemes, and \(2k_BT\) in the Fermi-Dirac scheme. Overridden if kT is specified.

kT

Type: float or null, Default: null

Specify temperature instead of sigma for Fermi smearing. This directly sets \(k_BT\) in Hartrees and corresponds to \(\sigma/2\) for the other Gaussian-based smearing schemes. Overrides sigma if specified.

mu

Type: float, Default: nan

Electron chemical potential in Hartrees. This serves as an initial guess (rarely needed) if mu_constrain is no, and otherwise, it is the required value to hold \(\mu\) fixed at.

mu-constrain

Type: bool, Default: no

Whether to hold chemical potential fixed to mu. If yes, perform grand-canonical electronic DFT. Note that this only takes effect when smearing is not null.

B

Type: float or list of float, Default: 0.0

External magnetic field (only for spin-polarized modes). Must be scalar for non-spinorial and 3-vector for spinorial modes. If M_constrain is yes, then this is only an initial guess as the magnetic field then becomes a Legendre multiplier to constrain M.

M

Type: float or list of float, Default: 0.0

Total magnetization (only for spin-polarized modes). Must be scalar for non-spinorial and 3-vector for spinorial modes. This magnetization is assigned to the initial occupations and it may change when smearing is present depending on M_constrain.

M-constrain

Type: bool, Default: no

Whether to hold magnetization fixed to M. This only matters when smearing is not null.

n-bands

Type: int or string or null, Default: null

Specify number of bands or scheme to determine it.

atomic: set to the number of atomic orbitals.
x<scale>: scale relative to the minimum number of bands to accommodate electrons (‘x1.5’ implies 1.5 x n_bands_min).
An integer explicitly sets the number of bands.

n-bands-extra

Type: int or string or null, Default: null

Number of extra bands retained by diagonalizers. This is necessary to converge any degenerate subspaces straddling n_bands. May be specified as:

x<scale>: scale relative to n_bands
An integer explicitly sets the number of extra bands