qimpy.dft.electrons.Electrons

class Electrons(*, process_grid, lattice, ions, symmetries, checkpoint_in=(None, ''), k_mesh=None, k_path=None, spin_polarized=False, spinorial=False, fillings=None, basis=None, xc=None, fixed_H='', save_wavefunction=True, lcao=None, davidson=None, chefsi=None, scf=None)

Bases: TreeNode

Electronic subsystem

Parameters:
__init__(*, process_grid, lattice, ions, symmetries, checkpoint_in=(None, ''), k_mesh=None, k_path=None, spin_polarized=False, spinorial=False, fillings=None, basis=None, xc=None, fixed_H='', save_wavefunction=True, lcao=None, davidson=None, chefsi=None, scf=None)

Initialize from components and/or dictionary of options.

Parameters:
  • lattice (Lattice) – Lattice (unit cell) to associate with electronic wave functions

  • ions (Ions) – Ionic system interacting with the electrons

  • symmetries (Symmetries) – Symmetries for k-point reduction and density symmetrization

  • k_mesh (dict | Kmesh | None) – [Input file] Uniform k-point mesh for Brillouin-zone integration. Specify only one of k_mesh or k_path.

  • k_path (dict | Kpath | None) – [Input file] Path of k-points through Brillouin zone. (Usually for band structure calculations.) Specify only one of k_mesh or k_path.

  • spin_polarized (bool) – [Input file] Whether system has spin polarization / magnetization. (True if system breaks time reversal symmetry, else False.) Spin polarization is treated explicitly with two sets of orbitals for up and down spins if spinorial = False, and implicitly by each orbital being spinorial if spinorial = True.

  • spinorial (bool) – [Input file] Whether to perform relativistic / spin-orbit calculations. If True, calculations will use 2-component spinorial wavefunctions.

  • fillings (dict | Fillings | None) – [Input file] Electron occupations and charge / magnetization control.

  • basis (dict | Basis | None) – [Input file] Wavefunction basis set (plane waves).

  • xc (dict | XC | None) – [Input file] Exchange-correlation functional.

  • fixed_H (str) – [Input file] Fix Hamiltonian from checkpoint file of this name. This is useful for band structure calculations along high-symmetry k-point paths, or for converging large numners of empty states. Default: don’t fix Hamiltonian i.e. self-consistent calculation.

  • save_wavefunction (bool) – [Input file] Whether to save wavefunction in checkpoint. Saving the wavefunction is useful for full post-processing capability directly from the checkpoint, at the expense of much larger checkpoint file. If False, calculations can still use the converged density / potential to resume calculations, but require an initial non-self-consistent calculation. Default: True.

  • lcao (dict | bool | LCAO | None) – [Input file] Linear combination of atomic orbitals parameters. Set to False to disable and to start with bandwidth-limited random numbers instead. (If starting from a checkpoint with wavefunctions, this option has no effect.)

  • davidson (dict | Davidson | None) – [Input file] Davidson diagonalization of Kohm-Sham Hamiltonian. Specify only one of davidson or chefsi.

  • chefsi (dict | CheFSI | None) – [Input file] CheFSI diagonalization of Kohm-Sham Hamiltonian. Uses the Chebyshev Filter Subspace Iteration (CheFSI) method, which can be advantageous for large number of bands being computed in parallel over a large number of processes. Specify only one of davidson or chefsi.

  • scf (dict | SCF | None) – [Input file] Self-consistent field (SCF) iteration parameters.

  • process_grid (ProcessGrid)

  • checkpoint_in (CheckpointPath)

Return type:

None

Methods

__init__

Initialize from components and/or dictionary of options.

accumulate_geometry_grad

Accumulate geometry gradient contributions of electronic energy.

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.

hamiltonian

Apply electronic Hamiltonian on wavefunction C

initialize_fixed_hamiltonian

Load density/potential from checkpoint for fixed-H calculation

initialize_wavefunctions

Initialize wavefunctions to LCAO / random (if not from checkpoint).

run

Run any actions specified in the input.

save_checkpoint

Save self and all children in hierarchy to cp_path.

update

Update electronic system to current wavefunctions and eigenvalues.

update_density

Update electron density from wavefunctions and fillings.

update_potential

Update density-dependent energy terms and electron potential.

Attributes

n_densities

Number of electron density / magnetization components in n.

need_full_projectors

Whether full-basis projectors are necessary.

comm

Overall electronic communicator (k-points and bands/basis)

kpoints

Set of kpoints (mesh or path)

spin_polarized

Whether calculation is spin-polarized

spinorial

Whether calculation is relativistic / spinorial

n_spins

Number of spin channels

n_spinor

Number of spinor components

w_spin

Spin weight (degeneracy factor)

fillings

Occupation factor / smearing scheme

basis

Plane-wave basis for wavefunctions

xc

Exchange-correlation functional

diagonalize

Hamiltonian diagonalization method

scf

Self-consistent field method

C

Electronic wavefunctions

fixed_H

If given, fix Hamiltonian to checkpoint file of this name

save_wavefunction

Whether to save wavefunction in checkpoint

lcao

If present, use LCAO initialization

eig

Electronic orbital eigenvalues

deig_max

Estimate of accuracy of current eig

n_tilde

Electron density (and magnetization, if spin_polarized)

tau_tilde

KE density (only for meta-GGAs)

child_names

Names of attributes with child objects.

variant_name

Version of children having variants (if any)

accumulate_geometry_grad(system)

Accumulate geometry gradient contributions of electronic energy. Each contribution is accumulated to a grad attribute, only if the corresponding requires_grad is enabled. Force contributions are accumulated to system.ions.positions.grad. Stress contributions are accumulated to system.lattice.grad. Gradients with respect to ionic scalar fields are accumulated to system.ions.Vloc_tilde.grad and system.ions.n_core_tilde.grad.

Parameters:

system (System)

Return type:

None

hamiltonian(C)

Apply electronic Hamiltonian on wavefunction C

Parameters:
Return type:

Wavefunction

initialize_fixed_hamiltonian(system)

Load density/potential from checkpoint for fixed-H calculation

Parameters:

system (System)

Return type:

None

initialize_wavefunctions(system)

Initialize wavefunctions to LCAO / random (if not from checkpoint). (This needs to happen after ions have been updated in order to get atomic orbitals, which in turn depends on electrons.__init__ being completed; hence this is outside the __init__.)

Parameters:

system (System)

Return type:

None

run(system)

Run any actions specified in the input.

Parameters:

system (System)

Return type:

None

update(system, requires_grad=True)

Update electronic system to current wavefunctions and eigenvalues. This updates occupations, density, potential and electronic energy. If requires_grad is False, only compute the energy (skip the potentials).

Parameters:
  • system (System)

  • requires_grad (bool)

Return type:

None

update_density(system)

Update electron density from wavefunctions and fillings. Result is in system grid in reciprocal space.

Parameters:

system (System)

Return type:

None

update_potential(system, requires_grad=True)

Update density-dependent energy terms and electron potential. If requires_grad is False, only compute the energy (skip the potentials).

Parameters:
  • system (System)

  • requires_grad (bool)

Return type:

None

C: Wavefunction

Electronic wavefunctions

basis: Basis

Plane-wave basis for wavefunctions

comm: Comm

Overall electronic communicator (k-points and bands/basis)

deig_max: float

Estimate of accuracy of current eig

diagonalize: Davidson

Hamiltonian diagonalization method

eig: Tensor

Electronic orbital eigenvalues

fillings: Fillings

Occupation factor / smearing scheme

fixed_H: str

If given, fix Hamiltonian to checkpoint file of this name

kpoints: Kpoints

Set of kpoints (mesh or path)

lcao: LCAO | None

If present, use LCAO initialization

property n_densities: int

Number of electron density / magnetization components in n.

n_spinor: int

Number of spinor components

n_spins: int

Number of spin channels

n_tilde: FieldH

Electron density (and magnetization, if spin_polarized)

property need_full_projectors: bool

Whether full-basis projectors are necessary.

save_wavefunction: bool

Whether to save wavefunction in checkpoint

scf: SCF

Self-consistent field method

spin_polarized: bool

Whether calculation is spin-polarized

spinorial: bool

Whether calculation is relativistic / spinorial

tau_tilde: FieldH

KE density (only for meta-GGAs)

w_spin: float

Spin weight (degeneracy factor)

xc: XC

Exchange-correlation functional