qimpy.dft.electrons.Fillings

class Fillings(*, ions, electrons, checkpoint_in=(None, ''), charge=0.0, smearing='gauss', sigma=0.002, kT=None, mu=nan, mu_constrain=False, B=0.0, M=0.0, M_constrain=False, n_bands=Default(atomic), n_bands_extra=Default(x0.1))

Bases: TreeNode

Electron occupation factors (smearing)

Parameters:

  • ions (Ions) –

  • electrons (Electrons) –

  • checkpoint_in (CheckpointPath) –

  • charge (float) –

  • smearing (str | None) –

  • sigma (float | None) –

  • kT (Optional[float]) –

  • mu (float) –

  • mu_constrain (bool) –

  • B (Tensor) –

  • M (Tensor) –

  • M_constrain (bool) –

  • n_bands (int) –

  • n_bands_extra (int) –

__init__(*, ions, electrons, checkpoint_in=(None, ''), charge=0.0, smearing='gauss', sigma=0.002, kT=None, mu=nan, mu_constrain=False, B=0.0, M=0.0, M_constrain=False, n_bands=Default(atomic), n_bands_extra=Default(x0.1))

Initialize occupation factor (smearing) scheme.

Parameters:

  • charge (float) – [Input file] Net charge of electrons + ions in e units. This determines n_electrons = ions.Z_tot - charge.

  • smearing ({'gauss', 'fermi', 'cold', 'mp1', False}, default: 'gauss') – [Input file] 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 False (or None) to disable smearing and keep the electron occupations fixed at their initial values.

  • sigma (float) – [Input file] 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 (float | None) – [Input file] 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 (float) – [Input file] Electron chemical potential in Hartrees. This serves as an initial guess (rarely needed) if mu_constrain is False, and otherwise, it is the required value to hold \(\mu\) fixed at.

  • mu_constrain (bool) – [Input file] Whether to hold chemical potential fixed to mu. If True, perform grand-canonical electronic DFT. Note that this only takes effect when smearing is not None.

  • B (float | Sequence[float]) – [Input file] External magnetic field (only for spin-polarized modes). Must be scalar for non-spinorial and 3-vector for spinorial modes. If M_constrain is True, then this is only an initial guess as the magnetic field then becomes a Legendre multiplier to constrain M.

  • M (float | Sequence[float]) – [Input file] 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 (bool) – [Input file] Whether to hold magnetization fixed to M. This only matters when smearing is not None.

  • n_bands ({'atomic', 'x<scale>', int}) –

    [Input file] 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 ({'x<scale>', int}) –

    [Input file] 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

  • ions (Ions) –

  • electrons (Electrons) –

  • checkpoint_in (CheckpointPath) –

Return type:

None

Methods

__init__

Initialize occupation factor (smearing) scheme.

add_child

Construct child object self.`attr_name` of type cls.

add_child_one_of

Invoke add_child on one of several child options in args.

read_band_scalars

Read one scalar per band from cp_path into v.

save_checkpoint

Save self and all children in hierarchy to cp_path.

update

Update fillings f and chemical potential mu, if needed.

write_band_scalars

Write v containing one scalar per band to cp_path.

Attributes

electrons

n_electrons

Number of electrons

n_bands_min

Minimum number of bands to accomodate n_electrons

n_bands

Number of bands to calculate

n_bands_extra

Number of extra bands during diagonalization

smearing

Smearing method name

sigma

Gaussian width (\(2k_BT\) for Fermi)

mu

Electron chemical potential

mu_constrain

Whether to constrain chemical potential

B

Magnetic field (vector in spinorial mode)

M

Total magnetization (vector in spinorial mode)

M_constrain

Whether to constrain magnetization

f

Electronic occupations

f_eig

Derivative of f with electronic eigenvalues

child_names

Names of attributes with child objects.
read_band_scalars(cp_path, v)

Read one scalar per band from cp_path into v. Returns number of bands read, which may be <= self.n_bands. This is useful for reading fillings, eigenvalues etc.

Parameters:
Return type:

int

update(energy)

Update fillings f and chemical potential mu, if needed. Set corresponding energy components in energy.

Parameters:

energy (Energy) –

Return type:

None

write_band_scalars(cp_path, v)

Write v containing one scalar per band to cp_path. This is useful for writing fillings, eigenvalues etc.

Parameters:
Return type:

None

B: Tensor

Magnetic field (vector in spinorial mode)

M: Tensor

Total magnetization (vector in spinorial mode)

M_constrain: bool

Whether to constrain magnetization

f: Tensor

Electronic occupations

f_eig: Tensor

Derivative of f with electronic eigenvalues

mu: float

Electron chemical potential

mu_constrain: bool

Whether to constrain chemical potential

n_bands: int

Number of bands to calculate

n_bands_extra: int

Number of extra bands during diagonalization

n_bands_min: int

Minimum number of bands to accomodate n_electrons

n_electrons: float

Number of electrons

sigma: float | None

Gaussian width (\(2k_BT\) for Fermi)

smearing: str | None

Smearing method name