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
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 one scalar per band from cp_path into v.
save_checkpoint
Save self and all children in hierarchy to cp_path.
Update fillings f and chemical potential mu, if needed.
Write v containing one scalar per band to cp_path.
Attributes
electrons
Number of electrons
Minimum number of bands to accomodate n_electrons
Number of bands to calculate
Number of extra bands during diagonalization
Smearing method name
Gaussian width (\(2k_BT\) for Fermi)
Electron chemical potential
Whether to constrain chemical potential
Magnetic field (vector in spinorial mode)
Total magnetization (vector in spinorial mode)
Whether to constrain magnetization
Electronic occupations
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:
cp_path (CheckpointPath) –
v (Tensor) –
- 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:
cp_path (CheckpointPath) –
v (Tensor) –
- 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