Self-consistent ion-structure feedback

Warning

AA \(\leftrightarrow\) QOZ/HNC feedback is experimental. The default workflow uses the ion-sphere (IS) construction.

The module otter.experimental.sc_feedback implements an outer iteration inspired by the self-consistent construction of Starrett and Saumon [2014]. Starting from a completed IS calculation, it:

forms the ionic background seen by each average atom from the current \(g_{ij}(r)\);
estimates an ion–electron correlation potential;
reruns the selected full/external average atom (Kohn–Sham or Thomas–Fermi) at the fixed IS chemical potential and, for mixtures, fixed IS volume partition;
reconstructs the pseudoatoms and solves QOZ/HNC again;
repeats until both \(g_{ij}\) and the correlation potential satisfy their requested tolerances.

For a mixture, the central species receives the charge-weighted sum of all pair channels, not only its diagonal \(g_{ii}\). This multicomponent extension is especially provisional: the published mixture calculations in Starrett et al. [2014] used the IS approximation.

Implemented single-component coupling

For one component the implementation follows Sec. 2.4 of Starrett and Saumon [2014] directly. The QOZ/HNC result replaces the ion-sphere step in the source of the full and external potentials, Eqs. (4) and (7), and the same additive correlation potential enters both maps:

\[V_{\mathrm{Ie}}^{\mathrm C}(r) =-\frac{n_{\mathrm I}^{0}}{\beta} \int \widetilde C_{\mathrm{Ie}}( |\mathbf r-\mathbf r'|, n_{\mathrm e}^{0}) [g_{\mathrm{II}}(r')-1]\,d\mathbf r'.\]

This is Eq. (19); the density rescaling of \(\widetilde C_{\mathrm{Ie}}\) is Eq. (20). The field-free density \(n_{\mathrm e}^{0}\) is evaluated at the chemical potential of the preceding IS solve. In particular, an SC electronic step does not reimpose the ion-sphere neutrality condition (3). The TF backend also disables its analytic sharp-step Hartree shortcut when a tabulated \(g_{\mathrm{II}}\) is supplied, so the feedback is not silently replaced by the IS source.

The electronic payload retains g_ii_background, v_corr_full and v_corr_ext on its radial grid. The final sc_feedback metadata also retains the mixed correlation potential and grid used by the last outer iteration, for comparison with Eq. (19).

Minimal diagnostic use

from otter import PlasmaWorkflowConfig, solve_plasma_workflow
from otter.experimental import (
    SCFeedbackConfig,
    solve_sc_feedback_workflow,
)

config = PlasmaWorkflowConfig(
    elements=["C"],
    temperature_ev=20.0,
    ion_temperature_ev=20.0,
    rho_g_cc=3.7,
)

is_result = solve_plasma_workflow(config)
sc_result = solve_sc_feedback_workflow(
    config,
    is_result,
    feedback_cfg=SCFeedbackConfig(
        max_outer=10,
        g_tol=5.0e-4,
        v_corr_tol=5.0e-4,
        v_corr_mix=0.35,
        require_converged=True,
    ),
)

history = sc_result["sc_feedback"]["history"]

is_result provides the comparison reference. An unconverged outer iteration raises an error by default. require_converged=False returns the unconverged result for diagnosis; the portable state writer rejects it.

Numerical convergence and inner accuracy

Orbital (QM) SC steps default to bound_zero_tail_refine=True. This matches shallow bound orbitals to the decaying exterior solution as feedback moves levels near the continuum edge, avoiding finite-box normalization jumps. The matching search window and threshold acceptance checks remain unchanged. Ordinary IS/full+external defaults and the TF path are unaffected. An explicit aa_overrides={"bound_zero_tail_refine": False} opts out; a corresponding species_overrides entry takes precedence for that species. SC does not modify the caller’s configuration or its initial IS result.

An individually converged AA calculation need not be accurate enough for an outer feedback loop. In particular, a small full-density change can coexist with a larger change in the pseudoatom screening response. Otter therefore uses the ordinary QM full-SCF tolerances early in SC feedback, then tightens them when the outer residual enters the final decade of the requested accuracy, or after three updates without improvement. The tighter precision is retained for subsequent outer iterations and must be used before accepting a QM SC solution.

SCFeedbackConfig.inner_full_tol_scale defaults to 0.01. On refinement, the full-SCF map, density and potential tolerances are capped at that fraction of their ordinary AA defaults. Stricter user tolerances are preserved. None disables this safeguard for numerical diagnosis. This control does not change ordinary IS calculations, TF, external-SCF tolerances, energy quadrature, B3 settings, or shallow-state resolution criteria. These numerical controls are implementation choices, not prescriptions from the cited papers.

Potential convergence requires the unmixed fixed-point residual evaluated on the current output:

\[R_V = \max_r\left| \mathcal{C}[g^{\rm out}, n_{\rm scr}^{\rm out}](r) - V_{\rm corr}^{\rm in}(r)\right|,\]

where \(\mathcal{C}\) denotes the implemented correlation-potential map above. max_v_corr_residual_ha records this residual; the historical max_v_corr_change_ha still records the mixed update. Both must pass v_corr_tol, along with the existing g_tol test. Reducing the mixing coefficient cannot by itself make the true residual pass.

SCFeedbackConvergenceError remains a subclass of RuntimeError and retains the unconverged last workflow in exception.result, including the complete sc_feedback.history. It can also be transported from a process worker. Such output is diagnostic only. A resolved electronic threshold classification is separate from convergence of this outer feedback loop.

Scope and limitations

Both the orbital Kohn–Sham and Thomas–Fermi electronic backends implement the single-component coupling above. TF has no discrete bound-orbital table.
bound_occ_mode="fd" is required by the Kohn–Sham path; it is not a TF parameter.
The IS chemical potential and mixture volume partition remain fixed during the outer iteration.
Convergence of the two numerical differences does not establish uniqueness or improved physical accuracy.
Pressure-ionization thresholds can still make the inner AA solve discontinuous or expensive.
The mixture generalization needs independent literature and simulation validation before production use.

The returned sc_feedback metadata records tolerances, mixing, fixed chemical potential, volume weights, per-iteration changes, and convergence. These fields should accompany every reported comparison.

API

`SCFeedbackConfig`([max_outer, g_tol, ...])	Numerical controls for the outer SC AA <-> QOZ/HNC iteration.
`SCFeedbackConvergenceError`(message, result)	Failed outer solve with an explicitly unconverged diagnostic result.
`solve_sc_feedback_workflow`(workflow_cfg, ...)	Continue one converged IS workflow to an SC AA <-> QOZ/HNC solution.
`mixture_ionic_background_profiles`(gij_r, ...)	Return the effective ionic background profile seen by every AA species.
`estimate_mixture_correlation_potentials`(*, ...)	Estimate the per-species `V_Ie^C(r)` correlation potentials.