qimpy.dft.electrons.SCF

class SCF(*, comm, checkpoint_in=(None, ''), n_iterations=50, energy_threshold=1e-08, residual_threshold=1e-07, n_consecutive=2, n_history=10, mix_fraction=0.5, mix_fraction_mag=1.5, q_kerker=0.8, q_metric=0.8, q_kappa=None, n_eig_steps=2, eig_threshold=1e-08, mix_density=True)

Bases: Pulay[FieldH]

Electronic self-consistent field iteration.

Parameters:

  • comm (Comm) –

  • checkpoint_in (CheckpointPath) –

  • n_iterations (int) –

  • energy_threshold (float) –

  • residual_threshold (float) –

  • n_consecutive (int) –

  • n_history (int) –

  • mix_fraction (float) –

  • mix_fraction_mag (float) –

  • q_kerker (float) –

  • q_metric (float) –

  • q_kappa (float | None) –

  • n_eig_steps (int) –

  • eig_threshold (float) –

  • mix_density (bool) –

__init__(*, comm, checkpoint_in=(None, ''), n_iterations=50, energy_threshold=1e-08, residual_threshold=1e-07, n_consecutive=2, n_history=10, mix_fraction=0.5, mix_fraction_mag=1.5, q_kerker=0.8, q_metric=0.8, q_kappa=None, n_eig_steps=2, eig_threshold=1e-08, mix_density=True)

Initialize parameters of self-consistent field iteration (SCF).

Parameters:

  • n_iterations (int) – [Input file] Number of self-consistent field iterations / cycles.

  • energy_threshold (float) – [Input file] Energy convergence threshold in Hartrees. Stop when energy difference between consecutive iterations falls below this threshold.

  • residual_threshold (float) – [Input file] Residual-norm convergence threshold. Stop when the norm of the residual i.e. difference in mixed variable (density / potential) between consecutive iterations falls below this threshold.

  • n_consecutive (int) – [Input file] Number of consecutive iterations each threshold must be satisfied.

  • n_history (int) – [Input file] History size for Pulay mixing. This sets the number of previous residuals and variables to use in the Pulay mixing algorithm. Larger history could improve convergence, while requiring more memory.

  • mix_fraction (float) – [Input file] Fraction of new variable mixed into current variable. Lower values (< 0.5) can improve stability, while higher values (0.5 - 1) attempt more aggressive convergence.

  • mix_fraction_mag (float) – [Input file] Different mix_fraction for magnetization components. More aggressive fractions (> 1) are typically required to converge the magnetization degrees of freedom, because they tend to contribute less to the overall energy of the system (compared to the overall electron density / potential).

  • q_kerker (float) – [Input file] Characteristic wavevector for Kerker mixing.

  • q_metric (float) – [Input file] Characteristic wavevector controlling Pulay metric.

  • q_kappa (float | None) – [Input file] Long-range cutoff wavevector for grand-canonical SCF. If unspecified, set based on Debye screening length.

  • n_eig_steps (int) – [Input file] Number of inner eigenvalue iterations for each SCF cycle.

  • eig_threshold (float) – [Input file] Convergence threshold on eigenvalues in Hartrees. Stop when the maximum change in any eigenvalue between SCF cycles falls below this threshold.

  • mix_density (bool) – [Input file] Whether to mix density or potential. Mix density if True, and potential if False.

  • comm (Comm) –

  • checkpoint_in (CheckpointPath) –

Methods

__init__

Initialize parameters of self-consistent field iteration (SCF).

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.

cycle

Single cycle of the Pulay-mixed self-consistent iteration.

metric

Apply metric to variable/residual.

optimize

Minimize residual using a Pulay-mixing / DIIS algorithm.

precondition

Apply preconditioner to variable/residual.

report

Override to perform optional reporting.

save_checkpoint

Save self and all children in hierarchy to cp_path.

update

Attributes

energy

Current energy components of the system (read-only).

residual

Get the current residual from state of system (read-only).

variable

Get density or potential, depending on mix_density.

mix_fraction_mag

Mix-fraction for magnetization

q_kerker

Kerker-mixing wavevector

q_metric

Wavevector controlling reciprocal-space metric

q_kappa

Debye wavevector (automatic if None)

n_eig_steps

Number of eigenvalue steps per cycle

eig_threshold

Eigenvalue convergence threshold

mix_density

Mix density if True, else mix potential

system

Current system being optimized

K_kerker

Kernel for Kerker mixing (preconditioner)

K_metric

Kernel for metric used in Pulay overlaps

comm

Communicator over which algorithm operates in unison

name

Name of algorithm instance used in reporting eg.

n_iterations

Maximum number of iterations

energy_threshold

Convergence threshold on energy change

residual_threshold

Covergence threshold on residual

n_consecutive

Number of consecutive iterations threshold must be satisfied

n_history

Number of past variables / residuals to retain

mix_fraction

Variable mixing fraction between cycles

extra_thresholds

Names and thresholds for any additional convergence quantities.

child_names

Names of attributes with child objects.
cycle(dEprev)

Single cycle of the Pulay-mixed self-consistent iteration. In each subsequent cycle, Pulay will try to zero the difference between get_variable() before and after the cycle. The implementation should only do the work of computing the updated variable; debug printing and I/O, if any, should occur in report() instead.

Parameters:

dEprev (float) – Energy change at previous cycle, which may be used to adjust accuracy of any inner optimizations

Returns:

Any quantities beyond energy and residual that require convergence checking, corresponding to extra_thresholds.

Return type:

Sequence[float]

metric(v)

Apply metric to variable/residual.

Parameters:

v (FieldH) –

Return type:

FieldH

precondition(v)

Apply preconditioner to variable/residual.

Parameters:

v (FieldH) –

Return type:

FieldH

K_kerker: torch.Tensor

Kernel for Kerker mixing (preconditioner)

K_metric: torch.Tensor

Kernel for metric used in Pulay overlaps

eig_threshold: float

Eigenvalue convergence threshold

property energy: Energy

Current energy components of the system (read-only).

mix_density: bool

Mix density if True, else mix potential

mix_fraction_mag: float

Mix-fraction for magnetization

n_eig_steps: int

Number of eigenvalue steps per cycle

q_kappa: float | None

Debye wavevector (automatic if None)

q_kerker: float

Kerker-mixing wavevector

q_metric: float

Wavevector controlling reciprocal-space metric

system: System

Current system being optimized

property variable: FieldH

Get density or potential, depending on mix_density.