Using Fixed-Point SCF Models

Read this after the model overview and before the training, evaluation, or calculator pages. The fixed-point model is not just a neural network forward pass: normal evaluation and calculator predictions include a self-consistent field loop. Most practical issues with these models are issues with that loop.

The SCF Loop

At a high level, a fixed-point calculation repeats four steps:

  1. start from an initial density and Fermi level;

  2. compute the electrostatic field features generated by that density;

  3. predict an updated density from the geometry and field features;

  4. mix the update with the previous density and check convergence.

The loop stops when the change in the density is small enough, or when the configured maximum number of SCF steps is reached. If the calculation does not converge, the model still has a last density, but that density should be treated carefully. Energies and forces from a poorly converged SCF state can be noisy or misleading.

Convergence

The main convergence diagnostic is the mean absolute change in the density coefficients between consecutive SCF steps. In calculator results this is reported as convergence_history.

A healthy SCF history usually decreases smoothly, although it does not have to decrease at every step. Common failure modes are:

  • slow convergence: the density changes steadily but remains above the tolerance at the final step;

  • oscillation: the density change bounces between larger and smaller values;

  • divergence: the density change grows, or the total charge becomes unreasonable.

For slow but stable convergence, increase num_scf_steps. For oscillatory or divergent behaviour, reduce mixing_parameter first.

SCF Settings

Most fixed-point SCF behaviour is controlled by a small set of settings:

  • num_scf_steps maximum number of SCF update steps;

  • scf_tolerance convergence threshold for the density change between steps;

  • mixing_parameter fraction of each density update accepted at each step;

  • constant_charge whether the calculation enforces a requested total charge or holds the Fermi level fixed;

  • initial_density how the initial density is chosen in interfaces that expose this option;

  • initial_fermi_level how the initial Fermi level is chosen in interfaces that expose this option;

The option names are similar across training, evaluation, and calculator interfaces, but not every interface accepts every setting directly. Training stages expose the most explicit initial-state controls. The ASE calculator uses local density guesses and data-provided Fermi levels by default, with restart hooks for advanced use.

Number of SCF Steps

num_scf_steps is the maximum number of update steps. It is not a guarantee that all of those steps will be used: the loop can stop early once the tolerance is reached.

Typical settings depend on the workflow:

  • short unrolled training stages often use around 10 steps;

  • evaluation and ASE calculations commonly use many more steps, such as 50 to 100, when a converged density is desired;

  • debugging runs can start with a small number of steps to inspect whether the loop is stable before spending time on longer solves.

If the model reaches the step limit with a small but nonzero density change, more steps may be enough. If the density change is growing, more steps will not fix the calculation.

SCF Tolerance

scf_tolerance sets the density-change threshold used to decide whether the loop has converged. A tighter tolerance gives a more strictly converged density, but may require more SCF steps or reveal instabilities that were hidden by a loose tolerance.

For evaluation and calculator use, start with a tolerance such as 1.0e-5 or 1.0e-6 and inspect the convergence history. During training, especially short unrolled training, the number of steps is often the more important control because the objective may intentionally use a truncated SCF solve.

Mixing Parameter

mixing_parameter controls how much of each new density update is accepted:

\[ \mathbf p_\mathrm{mixed} = \mathbf p_\mathrm{old} + \alpha \left( \mathbf p_\mathrm{new} - \mathbf p_\mathrm{old} \right), \]

where \(\alpha\) is the mixing parameter.

Larger values move faster but are less stable. Smaller values move more slowly but can suppress oscillations. A practical starting range is:

  • 0.2 to 0.3 for robust evaluation or SCF training;

  • lower values if the loop oscillates or diverges;

  • higher values only when the convergence history is smooth and slow.

For the current training recommendation, use about 10 unrolled SCF steps with mixing_parameter: 0.3 after the initial direct fixed-point stage.

Charge And Fermi Level

The fixed-point model can be run in two charge-control modes.

In constant-charge mode, constant_charge: true, the target total charge is an input. The SCF loop adjusts the Fermi-level contribution so that the final density matches that requested charge. This is usually the natural setting for atomistic calculations where the total charge of the cell or molecule is known. It requires a total_charge value.

In constant-Fermi mode, constant_charge: false, the Fermi level is fixed and the total charge is the model’s response to that Fermi level. This is useful for workflows where the Fermi level is the controlled thermodynamic variable. It requires a meaningful Fermi-level input or initial value.

The Fermi level is not just a reported output. It changes the effective potential seen by the update function, so a poor Fermi-level guess can make constant-charge SCF slower or less stable. When reference Fermi levels are available, using them as initial guesses can make training and evaluation much easier.

Initial States

The SCF loop needs an initial density and an initial Fermi level.

For density, the common choices are:

  • local_guess use the field-independent density predicted from the local geometry. This is the most inference-like option and does not require reference multipoles;

  • from_data start from density coefficients supplied in the data. This is useful during training and evaluation when reference multipoles are available, but it is not a production-style initial guess.

For the Fermi level, the common choices are:

  • zero start from zero Fermi-level contribution;

  • from_data start from a Fermi level supplied in the data.

During early training, from_data initial states are often useful because they reduce the difficulty of the SCF problem. For deployment-style evaluation, local_guess and an appropriate Fermi-level initialization are the more honest test of the model.

Force Calculation

use_autograd_forces controls how much of the SCF calculation is kept in the autograd graph when forces are requested. In normal user-facing calculator and evaluation workflows, this is usually left enabled. Turning it off is mainly a performance or debugging choice and should be checked carefully against force accuracy.

Practical Starting Options

A conservative starting point for evaluation or calculator use is:

scf_options:
  num_scf_steps: 100
  scf_tolerance: 1.0e-6
  mixing_parameter: 0.2
  constant_charge: true
  use_autograd_forces: true

The initial-state controls are interface-specific. Training stages use initial_density and initial_fermi_level inside fixed_point_training_options.scf. The ASE calculator currently starts from the local density guess unless a density restart is available, and it reads the Fermi-level input from the atoms data unless a constant-charge Fermi-level restart is available.

For training continuation after direct fixed-point training, you can also try “short-cut” SCF, by using around 10 steps:

fixed_point_training_options:
  mode: unroll_scf
  scf:
    num_scf_steps: 10
    mixing_parameter: 0.3
    constant_charge: true
    initial_density: from_data
    initial_fermi_level: from_data

This is not enough to fully converge the SCF cycle, but sometimes is an efficient way to train.

These values are starting points. The right settings depend on the model, data distribution, boundary conditions, and how difficult the charge response is to learn.

Diagnosing A Difficult SCF Run

When an SCF run fails or gives suspicious results, inspect the convergence history before changing the model.

Useful questions are:

  • Does convergence_history decrease?

  • Does it oscillate?

  • Does the final total charge match the requested total_charge in constant-charge mode?

  • Does reducing mixing_parameter improve stability?

  • Does starting from data fix the problem?

  • Does the same configuration converge with more SCF steps?

If only reference initial states work, the trained fixed-point map may be accurate near the reference density but poor from its own local initial guess. That is a training issue, not just an inference setting.

Restarts

An SCF restart uses a previous converged density, and sometimes a previous Fermi level, as the initial state for a new calculation. This can be useful in principle for closely related structures, such as neighbouring MD steps or a geometry optimization trajectory.

In the current repo, restarts are only implemented in the ASE calculator and should be treated as developer-facing functionality for now. They are not recommended as the default user workflow. A restart can make a weak model look stable by keeping it close to an already converged solution, so debugging and validation should include non-restarted calculations.