Self-consistent ion-structure feedback

Warning

The AA \(\leftrightarrow\) QOZ/HNC feedback implementation is experimental and not a production workflow. The production default is 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:

  1. forms the ionic background seen by each average atom from the current \(g_{ij}(r)\);

  2. estimates an ion–electron correlation potential;

  3. 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;

  4. reconstructs the pseudoatoms and solves QOZ/HNC again;

  5. 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, making Eq. (19) auditable.

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"]

Keep is_result as the comparison reference. The experimental API fails closed by default when the outer iteration is unconverged. Set require_converged=False only to inspect an explicitly labelled best-effort diagnostic; the portable production state writer rejects such a result.

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.

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.