Quick start

Google Colab

Run the aluminium workflow in a browser, with the same four figure groups and colours as Al: complete electronic-to-ionic workflow. The Colab default is Al at \(8.1\,\mathrm{g\,cm^{-3}}\) and \(T_e=T_i=1\,\mathrm{eV}\):

Single-species aluminium

Run the single-species workflow from the repository root:

$ poetry run python examples/single_species_workflow.py

The default state is Al at \(8.1\,\mathrm{g\,cm^{-3}}\) and \(T_e=T_i=15\,\mathrm{eV}\). The input block controls the state and output. The script plots the electronic density, effective potential, \(g_{ii}(r)\), \(S_{ii}(k)\), and \(V_{ii}\)/\(V_{ei}\) in real and reciprocal space. The pair-potential panels use symmetric logarithmic axes to display both signs over their full range.

To reproduce the four figure groups in the Al gallery and Colab instead, including the bound-orbital panels and Rayleigh weight, run:

poetry run python docs/examples/plot_al_full_workflow.py

That example uses \(T_e=T_i=1\,\mathrm{eV}\) at the same density.

For a strongly coupled one-component ion fluid, the optional Rosenfeld–Ashcroft closure is selected in the same configuration:

config = PlasmaWorkflowConfig(
    elements=["Al"],
    temperature_ev=5.0,
    ion_temperature_ev=5.0,
    rho_g_cc=8.1,
    hnc_bridge_model="rosenfeld_ashcroft",
)

This runs variational modified HNC and reports the self-consistent hard-sphere packing fraction as result["ion"]["vmhnc_eta"]. The implementation uses the bridge-universality ansatz of Rosenfeld and Ashcroft [1979], the exact Percus–Yevick hard-sphere reference of Wertheim [1963], Thiele [1963], and the variational criterion written explicitly by Faussurier [2004]. This is not IEMHNC: IEMHNC maps a simulation-derived OCP bridge onto a Yukawa one-component plasma (YOCP) along an isomorph [Iyetomi et al., 1992, Tolias and Lucco Castello, 2019], whereas VMHNC determines a hard-sphere packing fraction variationally. Plain HNC is the default. VMHNC currently supports single-component systems only.

Mixtures

Run the mixture workflow:

$ poetry run python examples/mixture_workflow.py

Runtime output

The default report shows the state definition, Wigner–Seitz radius, d_n and d_v during SCF, the converged chemical potential, bound-level tables, and elapsed time. Set debug=True in otter.PlasmaWorkflowConfig for charge, continuum, tail-matching, mixer, and timing diagnostics. Set show_progress=False for quiet runs.

Access and export results

The workflow returns electronic and ionic results in separate dictionaries:

result = solve_plasma_workflow(config)
for entry in result["electronic"]["species"]:
    aa = entry["result"]
    print(entry["element"], aa["zbar_partition"], aa["zstar"])
ion = result["ion"]

k = ion["k"]
q_k = ion["q_k"][0]
f_k = ion["f_k"][0]
G_k = ion["G_ee_k"]
v_ie_k = ion["v_ie_k"][0]
g_ii = ion["gij_r"][0, 0]
s_ii = ion["sij_k"][0, 0]

The electronic loop applies to any number of species. The ionic quantities above are for aluminium. Field definitions, array dimensions and version compatibility are documented in Workflow results and portable NPZ files.

Set save_state_npz=True in otter.PlasmaWorkflowConfig to save a portable .npz archive. Array names, shapes, units, interaction channels, and the standalone save/load API are documented in Workflow results and portable NPZ files.

Runtime and cached electronic structure

Quantum continuum calculations can be slow near pressure ionization. The function otter.continue_plasma_workflow_from_electronic_result() can reuse a validated electronic result while changing QOZ/HNC controls.

Assess charge closure, SCF convergence, HNC residuals and model applicability before using the results. See Scientific benchmarks for validation cases.

Consistent PNG and PDF figures

save_figure writes PNG and PDF files from the same Matplotlib figure:

import matplotlib.pyplot as plt
from otter.plotting import save_figure, set_style

set_style("docs", palette="nature")
fig, ax = plt.subplots()
ax.plot(ionic["k"], ionic["sij_k"][0, 0])
ax.set(xlabel=r"$k$ [Bohr$^{-1}$]", ylabel=r"$S_{ii}(k)$")

paths = save_figure(fig, "outputs/al_sii")
print(paths["png"], paths["pdf"])
plt.show()