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:

• process_grid (ProcessGrid) –

• lattice (Lattice) –

• ions (Ions) –

• symmetries (Symmetries) –

• checkpoint_in (CheckpointPath) –

• k_mesh (Optional[Union[dict, Kmesh]]) –

• k_path (Optional[Union[dict, Kpath]]) –

• spin_polarized (bool) –

• spinorial (bool) –

• fillings (Fillings) –

• basis (Basis) –

• xc (XC) –

• fixed_H (str) –

• save_wavefunction (bool) –

• lcao (LCAO | None) –

• davidson (Optional[Union[dict, Davidson]]) –

• chefsi (Optional[Union[dict, CheFSI]]) –

• scf (SCF) –

__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.

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:

• self (Electrons) –

• C (Wavefunction) –

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