Scientific diagrams

vaft.diagram draws concepts: topology, coordinate systems, workflows. It does not draw data. The three layers split the work:

A diagram never restates an equation. It calls the formula function, so the picture and the formula reference cannot drift apart.

This page explains the diagrams family by family. The complete list – every builder, every committed SVG and the exact call that draws it – is the generated diagram gallery.

Particle motion and computed animation

The particle-motion guide describes VAFT’s native Lorentz and guiding-center experiments, physical-time animation, stationary mirror wells and synchronized invariant diagnostics. Existing static references retain their default behavior; computed replay accepts an explicit trajectory and time coordinate.

Magnetic island

import vaft

d = vaft.diagram.magnetic_island(
    m=3, n=2, width=0.16, phase=0.0, projection="poloidal",
    r_s=0.55, elongation=1.7, triangularity=0.4,   # D-shaped plasma; defaults give a circle
)
d.tikz       # the LaTeX/TikZ source; needs no TeX installation
# With latex and dvisvgm installed:
# d            -> displays inline in Jupyter (SVG)
# d.save("island.svg")

Projection	Poloidal section at $\phi=0$	Top view $(R,\phi)$	3-D view of the O and X helices

All three views are drawn from one model, and the convention is the same in each:

The top view suppresses $Z$, so crossings of the projected O and X loci there are not reconnection points. The separatrix and $w$ are only visible in the poloidal section.

Animating the island: a phase scan or a rigid rotation

The same call draws the island over a trajectory of its phase when it is asked to with animation=True (issues #1049, #1053). It returns the animation result that plot_*(..., animation=True) returns. An array argument never animates by itself.

import numpy as np
import vaft

# A helical-phase scan: one frame per phi_0, the same model as the static call.
scan = vaft.diagram.magnetic_island(m=2, n=1, phase=np.linspace(0, 2 * np.pi, 120), animation=True, fps=30)
scan.save("island.mp4")          # or .webm (both need vaft[video]) or .gif (needs nothing)

# A rigid rotation at f = 5 kHz: phi_0(t) = phi_0 + 2*pi*f*(t - t_0), from phase= at the first time.
rotation = vaft.diagram.magnetic_island(
    m=2, n=1, time=np.linspace(0, 2e-3, 120), rotation_frequency=5e3, animation=True,
)
rotation.metadata["driver"]      # name "time", unit "s", and every frame's time

• Exactly one trajectory. A trajectory is either phase as an array (driver phase [rad]) or time with rotation_frequency (driver time [s]).
  • A phase array combined with time is refused, because it is ambiguous.
  • So is a single phase with animation=True, which is a static diagram.
• Units and direction. rotation_frequency is a frequency $f$ in Hz. The synthetic island of #886 (vaft.process.magnetic_island.MagneticIslandSpec) takes the angular frequency $\omega = 2\pi f$ in rad/s. A positive $f$ moves the O-points towards $+\theta^$ on a section. At fixed $\theta^$, it moves them towards $-\phi$, which is clockwise seen from above.
• Physics, not pictures. Every state is the static diagram at that phase, with the same O/X topology, width and shaping. The rotation is the phase relation evaluated at each time; the drawing is never rotated as an image.
• Presentation only. fps or duration set only how fast the frames are shown, never the rotation rate. Each frame’s phase or time is kept in metadata and in the .json sidecar of save().
• A preview of the canonical figure. The frames are a Matplotlib drawing of each state’s scene (the template’s colours and line styles, with labels through mathtext). The canonical static figure remains the SVG above.

Stability and operational-space diagrams

Textbook 2-D charts: two axes, the boundaries that divide the plane, and one label per region. A boundary that physics defines is computed by vaft.formula. Only the peeling–ballooning boundary, which has no closed form, is a schematic, and the figure says so.

vaft.diagram.peeling_ballooning()
vaft.diagram.s_alpha_ballooning(s_max=1.5, alpha_max=3.5)
vaft.diagram.hugill(elongation=1.0)                       # no size parameter: R, a, B cancel
vaft.diagram.hugill_st(elongation=1.8)                   # spherical-tokamak q_cyl (Sykes et al. 2000, MAST)
vaft.diagram.troyon(aspect_ratio=3.0, elongation=1.7)      # Troyon stability reference ~2.76, experimental levels dashed
vaft.diagram.li_qa(reference="wesson_1989")                # JET empirical l_i-q_psi space
vaft.diagram.li_qa(reference="cheng_1987")                 # theoretical MHD-stable l_i-q(a) domain

These charts show the boundaries of an operating space. Each one reads its lines from vaft.formula.boundaries through a canonical projection (#1425), and a population of measured or modelled states goes on the same projection with vaft.plot.operational_space.operational_space_population(table, "hugill"). Table columns are named by quantity identity (murakami_parameter, inverse_cylindrical_q, normalized_beta, …) with units in table.attrs["units"]. A boundary is drawn only when both plotted columns are exactly the projection’s quantities in its units: a q95 column never carries a $q_\psi$ or $q_\mathrm{cyl}$ boundary. Projections: hugill, troyon, beta_n_li, q95_li, greenwald_fraction_power, li_qa_wesson, li_qa_cheng, beta_n_li1 (Strait’s $\beta_N = 4\,l_i(1)$ envelope), and the #1691 beta-normalisation views volume_beta_in, beta_n_normalizations (with a $y = x$ guide), aspect_ratio_beta_n, aspect_ratio_volume_beta_n; list_projections() gives the full set. See #944 and #636.

Dimensionless similarity spaces

The limit diagrams above ask whether a state crosses a boundary. A similarity space asks where a state sits relative to other machines and to reactor designs, and which extrapolation separates them. In $\nu_$–$\rho_$, $\rho_$ is the size / finite-gyroradius direction ($1/\rho_$ is roughly the number of ion gyroradii across the minor radius) and $\nu_$ the collisionality direction ($1/\nu_$ is roughly the number of trapped-ion bounce orbits before a collision). $\beta_N$–$\rho_$ splits MHD-normalised pressure from machine scale. $\Omega_{ci}\tau_{E,\mathrm{th}}$–$\rho_$ splits confinement time, counted in gyro-orbits, from size. All three come from the ARC physics-basis comparison (Hillesheim et al., J. Plasma Phys. 92 (2026) E69, Fig. 6). They are zero-dimensional and draw no boundary by default (Luce, Petty and Cordey, PPCF 50 (2008) 043001, explain why these coordinates separate transport mechanisms).

The $\rho_$ and $\nu_$ axes follow the ITPA confinement-database convention, Verdoolaege et al., Nucl. Fusion 61 (2021) 076006, Eqs. (1a) and (1c), which Hillesheim et al. use. $n$ and $T$ are volume averages with $T_e = T_i$. The functions that evaluate them are rho_star_from_M_T_B_R_epsilon, nu_star_from_n_T_B_R_epsilon_kappa_I and omega_i_tau_E_from_B_tau_E_M in vaft.formula.equilibrium. VAFT has other $\nu_$ and $\rho_$ definitions (issue 353): Sauter’s local $\nu_$, pedestal $\nu^_e$, edge and separatrix collisionalities. Each is a different quantity, so it cannot be drawn on these axes. A missing input leaves the state unassessed: it is counted per group, in a warning and in the legend, and is never estimated. Each projection carries its meaning as metadata:

from vaft.diagram import _op_space
from vaft.plot.dimensionless_space import dimensionless_similarity

print(_op_space.get_projection("rho_star_nu_star").interpretation.describe())
fig, ax = dimensionless_similarity(table, "rho_star_nu_star", group="machine")   # ARC V3A overlaid
ax.vaft_exclusions.summary()

The only built-in reference point is ARC V3A ($\beta_N = 1.8$, $\rho_* = 0.0017$, $\nu_* = 0.031$, $\Omega_{ci}\tau_{E,\mathrm{th}} = 4.1\times10^8$), the values Hillesheim et al. state in Sec. 4. Their SPARC, ITER and EU-DEMO points appear only as plotted markers, so they are not digitised. Pass such points as reference_table= with a source column. See #1624.

Reduced stability diagnostics

What each analytic or reduced criterion is, and what it proves, is on Reduced stability diagnostics (#1635).

vaft.diagram.stability_diagnostic_taxonomy()
vaft.diagram.interchange_criteria()

Single-particle motion

Gyration and guiding-centre drifts, drawn in the island family’s style and 3-D camera. Every orbit is integrated from the Lorentz force by vaft.formula.boris_orbit, and every drift arrow is the drift formula of vaft.formula.particle. The tests require the integrated guiding centre to move at the formula’s velocity, so the figure cannot show a drift that the orbit does not make.

vaft.diagram.exb_drift(mass_ratio=4.0)
vaft.diagram.curvature_drift()
vaft.diagram.magnetization_current()
vaft.diagram.toroidal_drift(aspect_ratio=2.2)

Every view shows the relevant equations in a box. They are read from the $$…$$ definition in each formula’s docstring, so the figure shows exactly what the formula documents and implements. There is no second copy of any equation.

Each has further projections of the same computed orbits, chosen with projection=:

The units are normalised ($|q| = 1$, $m_e = 1$, fields of order one). The ion-to-electron mass ratio is reduced (4 by default) so that both orbits are visible; the figures state this.

Tearing physics

The ideas upstream of an island, one concept per diagram, so each can be used on its own in a page, notebook or slide. None takes an equilibrium, shot or solver output: the curves are schematic.

vaft.diagram.rational_surface(m=2, n=1)
vaft.diagram.delta_prime(sign="positive")   # "positive", "zero" or "negative"
vaft.diagram.tearing_layer_matching()

The index drawn here is the definition, not a stability result: no outer equation is solved. Solver values of $\Delta’$ (RDCON, STRIDE) belong to vaft.plot, and they are not the RDCON $D_R$ or the Modified Rutherford terms. The object these lead to is magnetic_island.

3-D perturbation harmonics

How a linear 3-D perturbation is written as complex Fourier harmonics, and what the complex numbers mean. Each diagram is one concept and needs no equilibrium, shot or GPEC output.

vaft.diagram.normal_field_component()
vaft.diagram.complex_harmonic(amplitude=1.0, phase=1.05)
vaft.diagram.toroidal_harmonic_phase(n=1)
vaft.diagram.harmonic_real_space_projection(m=2, n=1, phase=1.05)
vaft.diagram.complex_field_superposition(case="screening")   # "amplification", "phase_shift"

The phase convention is helical_phase’s $\xi = m\theta - n\phi$, with both mode numbers positive and the helicity in the minus sign. vaft.code.gpec stores each complex quantity as a real/imaginary pair (i = 0 real, i = 1 imaginary) and rebuilds it as real + 1j * imag, deciding no convention. For GPEC’s spectral outputs that pair is the $(b_R, b_I)$ of complex_harmonic, and it becomes a field only through the real-space reconstruction. Two sources differ:

• the *_fun quantities (b_n_fun, xi_n_fun) are already real-space in $\theta$, and GPEC writes them as $(\mathrm{Re}, -h\,\mathrm{Im})$ with its helicity $h$;
• vaft.process.toroidal_mode_decomposition returns the conjugate, $\hat b = 2\,\overline{C_n}$.

helical_harmonic’s Convention section states both. Amplitudes, phases and responses in these figures are schematic.

Collision processes

A classification of the interactions in a fusion plasma, built from the concept-diagram primitives. Coulomb collisions between charged particles relax the distribution. Atomic processes change charge states and bound electrons. Nuclear reactions change nuclei.

vaft.diagram.collision_processes()

The diagram contains no numbers except the D–T alpha energy, which is vaft.formula.constants.E_ALPHA. Collision frequencies, the Coulomb logarithm and collisionality regimes are left to formula-backed diagrams (#1111).

Geometric approximations

How slab, cylindrical and toroidal models relate, keeping geometry and ordering on separate axes. The physics is in vaft.formula.geometry. Geometric approximations explains each representation.

vaft.diagram.geometry_ordering_map()
vaft.diagram.field_line_geometry(geometry="toroidal")   # "cylindrical", "slab"
vaft.diagram.mode_number_mapping(m=2, n=1)
vaft.diagram.mhd_mode_geometry_map()

Asymptotic orderings

The scale separations a reduced model assumes, evaluated rather than assumed. The kernels are in vaft.formula.ordering, and Asymptotic orderings (#1627) explains them. Which diagrams the scale-to-model chain needs, and which are still planned, is Characteristic scales and orderings, “Diagram contracts”.

vaft.diagram.timescale_hierarchy()
vaft.diagram.spatial_scale_orderings()
vaft.diagram.ordering_contract_map()
vaft.diagram.adapter_contract_map()

Plasma-model guide

Figures for the plasma-model guide (#1739). Every node is read from the formalism records: a node lists the adapter:mode ids of vaft.validation.model_contracts.ADAPTER_MODES whose record matches it, and codes not in VAFT (vaft.diagram.EXTERNAL_CODES) are hollow and labelled so. Four edge kinds are used: asymptotic reduction (solid), model coupling (double-headed), software dependency (dotted) and surrogate ancestry (dashed). No direction is a fidelity axis.

vaft.diagram.plasma_model_reduction_map()
vaft.diagram.formalism_axes_map()
vaft.diagram.solver_placement_map()
vaft.diagram.kinetic_mhd_coupling()
vaft.diagram.reduced_model_ancestry()

Reduced representations

How formulas compress plasma information, from fields to profiles to scalars and from dimensional to dimensionless quantities, is classified on Reduced representations (#1626). The figures are built from the formulas’ Reduction docstring sections and the relation metadata in vaft.formula._taxonomy.

vaft.diagram.reduced_representation_hierarchy()
vaft.diagram.reduced_representation_hierarchy_compact()
vaft.diagram.reduction_graph(family="current_q")   # "pressure_energy", "kinetic_profiles", "dimensionless_similarity"

Tokamak geometry and flux coordinates

The parent geometry that the cylindrical and slab reductions start from. Surfaces are miller_surface, the shift is shafranov_shift_from_r_a_R0_beta_p_li, the field is vacuum_toroidal_field, and $\theta^*$ is straight_field_line_angle.

vaft.diagram.tokamak_torus(projection="3d")        # "poloidal"
vaft.diagram.flux_surfaces(shape="circular")       # "shifted"
vaft.diagram.shaping_family()
vaft.diagram.hfs_lfs_field()
vaft.diagram.safety_factor_winding(q=3)
vaft.diagram.flux_coordinates()
vaft.diagram.poloidal_angle_comparison()
vaft.diagram.unwrapped_flux_surface(q=2.5)
vaft.diagram.field_line_pitch(q=1.0)

The field line on a torus, its cylindrical and slab reductions, and the geometry/ordering map are in the geometric-approximations section above. The toroidal → cylindrical → slab bridge is geometry_ordering_map together with field_line_geometry.

Toroidicity and TF ripple

From the $1/R$ mirror to ripple-induced fast-particle transport. The formulas are in vaft.formula.ripple, and each one names its diagram under See Also. $B_\phi \propto 1/R$ itself is hfs_lfs_field, in the tokamak-geometry section.

vaft.diagram.trapped_and_passing_orbits()
vaft.diagram.toroidal_field_ripple(n_tf=16)
vaft.diagram.ripple_well_formation()
vaft.diagram.stochastic_ripple_orbit()

These are regime indicators, not a loss calculation. Orbit following (ASCOT, NUBEAM) is the quantitative check. Low-$n$ error fields, NTV and locking are separate topics.

Guiding-centre invariants and toroidal symmetry

This is the global view of the orbit physics that curvature_drift and toroidal_drift show locally. The grad-B and curvature drifts say why a guiding centre moves at each instant. Conservation of $P_\phi$ constrains the whole orbit in an axisymmetric field. These are the same physics seen two ways, not competing explanations.

vaft.diagram.guiding_center_invariants()
vaft.diagram.canonical_toroidal_momentum(phase=0.45)
vaft.diagram.toroidal_symmetry_breaking()

Conventions.

• $P_\phi = mRv_\phi + qRA_\phi$ (canonical_toroidal_momentum) uses physical components and the IMAS $\phi$.
• The guiding-centre form uses $\psi = RA_\phi$ in Wb per radian, largest on the axis for a current along $+\phi$. psi_per_radian_from_cocos converts a stored flux: $-\psi/2\pi$ for COCOS 11 (IMAS DD3) and $+\psi/2\pi$ for COCOS 17 (DD4). Used as stored, the flux has the wrong sign or a $2\pi$ error.
• $J_\parallel$ is documented but deliberately not a numerical helper: its bounce interval and orientation depend on the orbit.
• The drift of one orbit’s $P_\phi$ is not NTV. Torque and transport are #1111’s, and need the kinetic response of the whole distribution.

Straight-field-line coordinates

Straight field lines are a condition, not a coordinate system. The freedom the condition leaves is what PEST, Boozer, Hamada and equal-arc fix in different ways. All four are members of one generalised family, $\mathcal{J} \propto R^{p_R}/(B_p^{p_{Bp}}B^{p_B})$ (vaft.formula.generalized_straight_field_line_angle, as in DCON/GPEC). The unwrapped picture of a straight field line is unwrapped_flux_surface. Clebsch, field-aligned and ballooning coordinates are #1075’s.

vaft.diagram.sfl_coordinate_grids()
vaft.diagram.sfl_coordinate_taxonomy()
vaft.diagram.sfl_fourier_convergence()

• Same equilibrium, different grids. All four panels of sfl_coordinate_grids share one equilibrium: $R_0/a = 1.7$, $\kappa = 2$, $\delta = 0.45$. The surfaces are identical and only the angle changes. A test checks this.
• Different Fourier costs. In sfl_fourier_convergence, one outboard-localised, axisymmetric perturbation needs anywhere from 9 to 26 poloidal harmonics, depending on the angle it is expanded in. Moved inboard, the ranking reverses: which angle is compact depends on where the structure sits. For $n \ne 0$, the toroidal shift $\nu$ of every angle except PEST couples harmonics further. The figure leaves that out.
• Only PEST keeps $\phi$. Keeping the geometric $\phi$ forces $\mathcal{J} \propto R^2$, so every other member has $\zeta = \phi + \nu$.
• Boozer ≈ PEST here. The two nearly coincide at this $B_p \ll B_\phi$, where $B^2 \propto R^{-2}$.
• COCOS is not a coordinate choice. It fixes signs and orientations across every node of the taxonomy, independently of which angle is chosen.

Toroidal shift, action angles, validity, and COCOS

Every straight-field-line angle except PEST needs its own toroidal angle $\zeta = \phi + \nu$. vaft.formula.equilibrium.sfl_toroidal_angle_shift gives the shift as $\nu = q(\theta_\mathrm{sfl} - \theta_\mathrm{PEST})$, which follows from $d\phi = q\,d\theta_\mathrm{PEST}$ and $d\zeta = q\,d\theta_\mathrm{sfl}$ along a field line. For a toroidal mode number $n \neq 0$, a mode aligned with the nearest rational surface $q = m_0/n$, read at fixed $\zeta$, has in every angle the $n = 0$ spectrum moved to $m \approx m_0$ with its width unchanged. sfl_fourier_convergence(n=2) shows this: the shift $\nu$ is what keeps such a mode compact. A structure fixed in the geometric $\phi$ is instead moved by the angle-dependent $\nu$, and stays unshifted only in PEST (spectra_with_toroidal_mode).

• field_line_action_angle follows one field line over a poloidal turn. Against the geometric angles $(\phi, \vartheta)$ it bends; against $(\zeta, \theta_\mathrm{PEST})$ it is the straight line of slope $1/q$. Nested surfaces make the field-line flow integrable, so SFL coordinates are its action-angle variables; the action is the toroidal flux, and the poloidal flux is the Hamiltonian. Canonical SFL coordinates, which also give the guiding-centre Hamiltonian its canonical form, stay a branch of sfl_coordinate_taxonomy; no transformation is implemented here.
• sfl_coordinate_validity computes $|q|$ toward the last closed surface. On a limited Solov’ev equilibrium it settles; on a single-null one it grows as $-\ln(1 - \psi_N)$, because $B_p \to 0$ at the X-point and $\theta^*$ degenerates there. Islands and stochastic fields have no global surfaces at all (see magnetic_island and stochastic_layer).
• coordinates_vs_cocos draws the coordinate choice and the COCOS convention as orthogonal axes: every combination is valid, and a coordinate system is not a COCOS convention.

DCON and GPEC use the generalized family (PEST, Boozer, Hamada, equal-arc, and $J \propto R^{p_R}/(B_p^{p_{B_p}} B^{p_B})$). An input or output handled in VAFT should therefore keep four things together: the coordinate type, its powers, the Fourier convention $e^{i(m\theta - n\zeta)}$, and where the mapping came from. Two analyses in different SFL coordinates describe the same equilibrium with different harmonic content. DCON output already keeps jac_type and the powers (vaft.code.gpec).

vaft.diagram.sfl_fourier_convergence(n=2)
vaft.diagram.field_line_action_angle()
vaft.diagram.sfl_coordinate_validity()
vaft.diagram.coordinates_vs_cocos()

Clebsch labels and the ballooning representation

These figures go from straight-field-line coordinates to the local, field-aligned and ballooning descriptions that high-$n$ stability and turbulence models use. The formulas are field_line_label, s_alpha_curvature_drive and s_alpha_ballooning_solution in vaft.formula.stability, on the circular $s$–$\alpha$ model.

vaft.diagram.clebsch_field_line_label(q=2.5)
vaft.diagram.ballooning_curvature_drive()
vaft.diagram.ballooning_newcomb_test()
vaft.diagram.ballooning_harmonic_envelope(n=20)
vaft.diagram.ballooning_workflow()

The straight-field-line coordinates they start from are in the section above (sfl_coordinate_taxonomy). The resulting $(s, \alpha)$ stability diagram is s_alpha_ballooning.

Field-aligned basis, flux tube, shear, and the ballooning eigenfunction

• field_aligned_basis unrolls one flux surface. Its field lines are the lines of constant $\alpha = \phi - q\theta$. With $x = \psi$, $y = \alpha$ and $z = \theta$, two coordinates are constant along $\mathbf B$, so $\mathbf B\cdot\nabla = (\mathbf B\cdot\nabla z)\,\partial_z$.
• flux_tube_patch goes from a flux surface to one field line, then to its thin neighbourhood, then to the local $(x, y, z)$ box used by flux-tube gyrokinetic codes and by the sheared slab.
• magnetic_shear_field_aligned follows a mode along the line. With $k_x = k_y\hat s\theta$ (ballooning_radial_wavenumber at $\alpha = 0$, the $\Lambda$ of the $s$-$\alpha$ model), its phase fronts rotate: the sheared slab’s $k_x(z) = k_{x0} + k_y\hat s z$, seen in the tokamak. The binormal period stays fixed, so the spacing across the fronts shrinks as $1/\sqrt{1+\hat s^2\theta^2}$; that growth of $k_\perp$ is the $(1+\Lambda^2)$ of line bending and inertia.

• ballooning_eigenfunction solves the $s$-$\alpha$ equation with inertia on the extended angle (s_alpha_ballooning_eigenmode). An unstable surface has a mode peaked at the outboard midplane (bad curvature) that decays within a few transits; a stable surface has only the continuum.

• ballooning_transit_map ties the extended angle to the cross-section: one poloidal circle per transit $k$, under $\theta = 2\pi k$, its outboard point (bad curvature) labelled with $F(2\pi k)$. The same point, revisited on every transit, carries less of the mode each time.
• ballooning_boundary_conditions puts the two ways of closing the field line side by side. The ballooning representation requires decay on the covering space, $F \to 0$ as $|\theta| \to \infty$. A flux tube joins its ends after one poloidal turn, and because $k_x = k_y\hat s\theta$ the rejoined end has a shifted $k_x$: twist and shift, named and not derived.
• field_aligned_xpoint_limitation draws lines of constant straight-field-line angle $\theta^$ ($d\theta^/dl \propto 1/(R^2B_p)$) on the diverted toy equilibrium of the Grad–Shafranov diagrams. They are evenly spread in the core and crowd into the X-point near the separatrix, where $B_p \to 0$ and $q \propto \oint dl/(R^2B_p)$ diverges; outside it the lines are open and X-point-adapted coordinates take over. See also sfl_coordinate_validity (#1074).

vaft.diagram.field_aligned_basis(q=2.5)
vaft.diagram.flux_tube_patch()
vaft.diagram.magnetic_shear_field_aligned(shear=1.0)
vaft.diagram.ballooning_eigenfunction()
vaft.diagram.ballooning_transit_map(transits=2)
vaft.diagram.ballooning_boundary_conditions(shear=1.0)
vaft.diagram.field_aligned_xpoint_limitation(n_theta=24)

Ballooning formulations

How the reduced $s$–$\alpha$ equation follows from the general ballooning equation, and how DCON’s $C_A$ and GPEC.jl’s ballooning $\Delta’$ relate to it, is on Ballooning formulations (#1637).

vaft.diagram.ballooning_formulation_hierarchy()

Slab resonant layers: tearing and twisting parity

How a global harmonic becomes a local layer response. The mapping $(m, n) \to (k_y, k_z)$ and $q = m/n \Leftrightarrow k_\parallel = 0$ is mode_number_mapping. The flux is vaft.formula.slab_perturbed_flux; its tearing form is the island pendulum of magnetic_island.

vaft.diagram.slab_parity(parity="tearing")   # "twisting"
vaft.diagram.slab_parity_comparison()
vaft.diagram.poloidal_harmonic_coupling(m=3)
vaft.diagram.resonant_layer_matching()

Cylindrical geometry: profiles, mode shapes and matching

The screw-pinch picture between the torus and the slab. The profile is Wesson’s peaked current $j \propto (1 - x^2)^\nu$, given by peaked_current_safety_factor together with cylindrical_poloidal_field (Ampère). The screw-pinch field line is field_line_geometry("cylindrical"), and the cylinder-versus-torus harmonic contrast is poloidal_harmonic_coupling.

vaft.diagram.current_to_q_profile(nu=1.0, q_a=3.5)
vaft.diagram.cylindrical_rational_surfaces(n=1)
vaft.diagram.cylindrical_mode_morphology()
vaft.diagram.internal_external_kink()
vaft.diagram.plasma_vacuum_wall(m=2)
vaft.diagram.cylindrical_tearing_outer(m=2, n=1)

From the cylinder to the slab: mode_number_mapping expands $k_\parallel(r)$ about $r_s$ into the local slab of local_slab_from_cylinder, and resonant_layer_matching couples several such layers. The screw-pinch field line itself is field_line_geometry("cylindrical"), and the cylinder-vs-torus harmonic picture (independent $m$ vs toroidally coupled $m, m\pm1$) is poloidal_harmonic_coupling.

Current-profile and q topology

What the shape of the current does to the poloidal field, the internal inductance and the safety factor, and how the shape of $q$ decides how many rational surfaces one $m/n$ has (#1604). All four diagrams use one reduced model: a straight cylinder whose current is peaked ($j \propto (1 - x^2)^2$), broad ($1 - x^4$) or hollow / off-axis ($(0.1 + x^2)(1 - x^2)^{3/2}$), each normalized to the same $I_p$. The chain is cylindrical_enclosed_current, cylindrical_poloidal_field (Ampère), cylindrical_safety_factor_from_r_B, cylindrical_poloidal_flux (for $\psi_N$), cylindrical_internal_inductance and shear_from_r_q. The crossings come from vaft.process.equilibrium.find_rational_surfaces, the routine that finds them on a reconstructed $q$. These are concept figures, not equilibria and not stability results.

vaft.diagram.current_profile_shapes()
vaft.diagram.q_profile_topologies()
vaft.diagram.q_profile_landmarks(profile="monotonic")         # or "reversed_shear"
vaft.diagram.rational_surface_topology(profile="reversed_shear", m=2, n=1)

These diagrams sit upstream of the others. current_to_q_profile keeps the analytic peaked family $j \propto (1 - x^2)^\nu$ and cylindrical_rational_surfaces the monotonic surfaces of one $n$ (#1072). rational_surface keeps the single-crossing definition, and delta_prime and tearing_layer_matching follow it (#1039). The $l_i$–$q$ diagrams of li_qa (#1603) are operating spaces: one scalar $l_i$ against one scalar edge $q$, from the literature. They are not plots of a current profile. The data-side counterparts are vaft.plot.equilibrium_profile_j_tor and equilibrium_profile_q (#1505).

Current diffusion and current drive

How the current-density and safety-factor profiles above form in time (#1605). Both diagrams evolve one reduced model: the enclosed current $I(\rho, t)$ of a straight cylinder under cylindrical_current_diffusion_rate (Faraday, Ampère and Ohm’s law with a non-inductive source $j_\mathrm{ni}$), integrated implicitly. The resistivity is a fixed Spitzer $\eta(\rho)$ (spitzer_resistivity_from_T_e_Z_eff_ln_Lambda) on a hot-core, cold-edge $T_e(\rho)$, and time is in units of the core resistive_diffusion_time $\tau_R = \mu_0 a^2/\eta(0)$. The profiles are representative, not universal: there is no transport, bootstrap current or toroidal geometry.

vaft.diagram.current_diffusion()
vaft.diagram.current_drive_profiles(deposition="off_axis")   # or "on_axis"

Field configurations, reconnection and MHD waves

The canonical slab configurations, the topology of reconnection, and the linear ideal-MHD waves. All are drawn in the slab frame of vaft.formula.geometry: $x$ is the sheet normal (radial), $y$ the reconnecting (binormal) direction, and $z$ the current and guide-field direction. The geometry itself (slab, sheared slab, cylinder, torus) belongs to Geometric approximations. The formulas are harris_sheet_field, harris_sheet_current_density and x_point_flux in geometry, and shear_alfven_frequency and magnetosonic_phase_speeds in stability.

vaft.diagram.slab_field_configuration(kind="sheared")   # "uniform", "reversed", "guide"
vaft.diagram.current_sheet(guide_field=False)
vaft.diagram.harris_sheet()
vaft.diagram.x_point()
vaft.diagram.magnetic_reconnection()
vaft.diagram.island_formation()
vaft.diagram.shear_alfven_wave()
vaft.diagram.fast_magnetosonic_wave()
vaft.diagram.mhd_wave_family()

From these to the tokamak: the current sheet and the island lead to the tearing layer (slab_parity), then to the cylindrical and toroidal tearing mode (delta_prime, resonant_layer_matching). Here $q(r_s) = m/n$ globally is $k_\parallel = 0$ locally (mode_number_mapping). The uniform-slab shear Alfvén wave leads to the Alfvén continuum, where $v_A(r)$ and $k_\parallel(r)$ vary. Toroidal coupling (poloidal_harmonic_coupling) then opens the gaps of the TAE and EAE. Those are not computed here.

The Grad–Shafranov problem: regions, boundaries and problem classes

The axisymmetric field is $\mathbf B = R^{-1}\nabla\psi\times\hat{\boldsymbol\phi} + F(\psi)R^{-1}\hat{\boldsymbol\phi}$, with $\psi$ the poloidal flux per radian and $F = RB_\phi$ the poloidal-current function. Its components are radial_magnetic_field_from_psi and vertical_magnetic_field_from_psi (COCOS-aware); in vacuum $F$ is constant, and $B_\phi = F/R$ is vacuum_toroidal_field. One flux function $\psi(R, Z)$ is solved across the plasma, vacuum and coil regions, each with its own source. vaft.formula.grad_shafranov_source gives the Ampère form $\Delta^*\psi = -\mu_0RJ_\phi$, which holds in every region. toroidal_current_density_from_p_prime_ff_prime gives the plasma current that force balance allows, $J_\phi = Rp’ + FF’/(\mu_0R)$. On a grid, the operator is vaft.process.equilibrium.grad_shafranov_operator. The flux maps are a toy: prescribed ring currents and three coils superposed through green_psi_exact. The topology (axis, X-point, limiter contact, LCFS) is then found from the total flux, as a free-boundary code finds it. A production solver would also make the plasma current consistent with $p’$ and $FF’$.

vaft.diagram.grad_shafranov_domain_decomposition()
vaft.diagram.fixed_vs_free_boundary_equilibrium()
vaft.diagram.limiter_and_diverted_topologies()
vaft.diagram.equilibrium_problem_taxonomy()
vaft.diagram.poloidal_flux_source_decomposition()

Equilibrium-aware phenomena: kink displacement and sawtooth

This layer sits between the reference diagrams and result plotting. The geometry comes from an equilibrium (any vaft.data.equilibrium.EquilibriumData); the physical state is a prescribed, documented model. The default equilibrium is the exact Solov’ev (Cerfon–Freidberg) equilibrium of vaft.process.equilibrium.solovev_example with $A = 0$, where $q$ rises from about 0.8 to 3. Surfaces, normals and the PEST angle $\theta^$ come from straight_field_line_map, and $q(\rho)$ from calculate_q_profile_from_psi, with $\rho = \sqrt{\psi_N}$. The mode phase uses $\theta^$. The drawing uses the real $(R, Z)$ surfaces.

vaft.diagram.kink_mode(equilibrium=None, m=1, n=1, amplitude=0.06, radial_profile="internal")
vaft.diagram.kink_mode(m=2, n=1, radial_profile="global", harmonics={2: 1.0, 3: 0.3})
vaft.diagram.sawtooth(stage="precursor")   # "reconnection", "post_crash"

Two reduced Hamiltonian models extend the vocabulary of magnetic_island to several resonances, and to the X-point.

vaft.diagram.stochastic_layer(regime="touching")   # "isolated", "overlapping"; or overlap=, perturbations=
vaft.diagram.separatrix_lobes(perturbation=0.02, m=8, n=4)       # or separatrix_lobes(equilibrium, ...)

In stochastic_layer, $x = \psi_N$ stands in for the toroidal-flux action, so $\epsilon$ is a model amplitude and area in the section is not flux. separatrix_lobes takes any lower-single-null EquilibriumData: the X-point must be a saddle of the flux on the boundary value, below the axis, and the window scales with the minor radius; a limited equilibrium is refused. Neither diagram is a GPEC, MARS or vacuum-field trace: those belong to result plotting.

The mixing radius comes from vaft.formula.kadomtsev_mixing_radius: the 1/1 helical flux $\psi_* \propto \int r(1/q - 1)\,dr$ returns to its axis value there. It equals $\sqrt2\,r_1$ when $1/q - 1$ is parabolic. Complete (Kadomtsev) reconnection is the $f \to 1$ limit, not a claim about every crash.

MARFE

marfe puts a prescribed radiation condensation on the edge of an equilibrium and shows the condition that makes it.

• On the high-field side (localization="hfs", the usual location) the band straddles the last closed surface. It is about 30° wide poloidally and 0.1$a$ deep, as Lipschultz (1987) reports.
• Next to the X-point ("xpoint", Greenwald 2002 p. R35) the band is drawn on the closed side with the same sizes, which are borrowed, not measured there.
• Its $T_e$ is below about 10 eV (Greenwald p. R34), and it is toroidally symmetric: a ring.

The right panel is Drake’s (1987) constant-pressure criterion in dimensionless form, computed from vaft.formula.sol.radiative_condensation_growth_rate. For $k_\parallel > 0$ the boundary is $k_\parallel^2\kappa_\parallel T/L = 2 - \partial\ln L/\partial\ln T$, so condensation does not need a falling radiation curve. On the $k_\parallel = 0$ axis only the constant-density flute limit (radiative_thermal_instability_growth_rate) applies, and it is unstable where $L$ falls with $T$.

The band is prescribed, not solved, and no cooling curve or density-limit formula is built in; MARFE onset and density-limit semantics belong to #1068. The API names its sizes poloidal_width_deg and radial_fraction; the issue’s "prescribed" localization is not implemented.

vaft.diagram.marfe(localization="hfs")      # or "xpoint"; poloidal_width_deg=30, radial_fraction=0.1

Divertor heat-flux footprint

divertor_heat_footprint maps an Eich target profile onto a diverted equilibrium. The geometry comes from the equilibrium itself: the X-point is the zero of $\nabla\psi$ next to the lowest boundary point, the strike point is where the separatrix leg crosses a horizontal target, and the total flux expansion $f_x = (\partial\psi/\partial R)\mathrm{OMP} / (\partial\psi/\partial s)\mathrm{target}$ is evaluated on the flux, not assumed. The profile is vaft.formula.sol.eich_target_heat_flux_profile with that $f_x$. $\lambda_q$ (at the outer midplane) and $S$ (at the target) are illustrative inputs: this is a schematic, and measured IR profiles belong in vaft.plot. The SOL surfaces one, two and three $\lambda_q$ outside the separatrix at the midplane fan out to about $k\lambda_q f_x$ on the target. The equilibrium must be lower single null, with an X-point on its boundary flux and legs that reach the target inside the limiter; anything else is refused rather than drawn.

vaft.diagram.divertor_heat_footprint(lambda_q=0.004, spreading=0.0015, target="outer")

Disruption physics: quench sequence, runaways and energy paths

The chain from loss of confinement to a runaway plateau, each link a relation in the new vaft.formula.disruption category or an existing one:

• thermal_quench_temperature, current_quench_current and inductive_parallel_electric_field;
• connor_hastie_critical_field, dreicer_field, runaway_critical_momentum and relativistic_collision_time;
• dreicer_generation_rate, avalanche_growth_rate, avalanche_efolds_from_current_drop and runaway_current_from_density;
• the Spitzer resistivity, and the startup plasma resistance, inductance and L/R time.

Detecting a disruption in data stays in vaft.process.transients. Simulating one belongs to kinetic or integrated codes.

vaft.diagram.disruption_timeline()
vaft.diagram.disruption_causal_chain()
vaft.diagram.runaway_generation()
vaft.diagram.disruption_energy_pathways()

Vertical displacement events: hot and cold VDE, halo currents

A hot VDE moves a still-hot plasma into the wall, and the scraping can trigger the thermal quench. A cold VDE follows the quench, as the decaying current loses its centred vertical equilibrium. Wall contact then drives halo currents through the scrape-off layer and the wall. The model-neutral reference quantities are in the new vaft.formula.vde category:

• vertical_velocity and vde_growth_rate (a local $d\ln\lvert\Delta Z\rvert/dt$);
• thin_wall_time and wall_mode_decay_time;
• halo_current_fraction and toroidal_peaking_factor.

A wall element’s $L/R$ is lr_time_from_L_R. The named reduced VDE models (edge-current loss, filament-plus-wall, analytic halo) are not chosen yet. The disruption chain these diagrams couple to is vaft.formula.disruption.

vaft.diagram.hot_vde_sequence()
vaft.diagram.cold_vde_bifurcation()
vaft.diagram.plasma_wall_halo_current()
vaft.diagram.vde_timescales()

Plasma-wall interaction

The plasma-wall vocabulary: one impact and its outcomes, reflection (particle versus energy), physical sputtering, recycling versus retention, and particle versus energy balance. This is level 0 of the issue’s enrichment, semantics only. No reflection or sputtering coefficient, yield or threshold is drawn unless it is computed by a vaft.formula.pwi relation from inputs the caller supplies:

• binary_collision_energy_transfer_factor, the exact elastic kinematics;
• mean_reflected_energy_fraction, which is $R_E/R_N$;
• recycling_coefficient;
• sputtering_threshold_bohdansky, a named empirical fit that needs the surface binding energy.

Projectile and target species go through vaft.data.atomic and are drawn apart: projectile blue, target dark. Each diagram’s model names the IMAS paths of the quantities it shows, under wall.global_quantities.neutral[:]: the recycling particle and energy coefficients, the fluxes from the plasma and from the wall, the wall inventory, and the per-incident-species sputtering coefficients. IMAS’s recycling energy coefficient covers all recycling channels, so it is not the prompt-reflection $R_E$. The canonical sputtering figure uses $E_s = 8.68$ eV, the sublimation energy of W, as a stated input.

vaft.diagram.plasma_wall_interaction_processes(projectile="D", target="W")
vaft.diagram.plasma_wall_interaction_reflection()
vaft.diagram.plasma_wall_interaction_sputtering(surface_binding_energy=8.68)   # threshold only if E_s given
vaft.diagram.plasma_wall_interaction_recycling()
vaft.diagram.plasma_wall_interaction_energy_partition()
vaft.diagram.plasma_wall_interaction_reflection_energy()
vaft.diagram.plasma_wall_interaction_angle_dependence()
vaft.diagram.plasma_wall_interaction_sputtering_threshold(surface_binding_energy=8.68)   # E_th only if E_s given
vaft.diagram.plasma_wall_interaction_particle_balance()
vaft.diagram.plasma_wall_interaction_surface_response()

Spectroscopy and ionization

Concept diagrams in the vocabulary of vaft.data.atomic and vaft.data.spectroscopy. parse_emission_term and parse_line_label are the same parsers emission= uses in vaft.plot, so a term that selects a trace selects the same diagram. Metadata is progressive, and nothing is fabricated:

• level 0 is the semantic identity (stage, charge, element);
• level 1 is what the data declare (the wavelength in an IMAS processed_line label such as OI_7770);
• hydrogenic lines add Bohr-model levels and Rydberg vacuum wavelengths with the isotope’s reduced mass (hydrogenic_energy_level and hydrogenic_transition_wavelength in vaft.formula.atomic). For one-electron systems this model is the authoritative source; each model records it under source;
• many-electron levels and photon emissivities would need OPEN-ADAS ADF04 and ADF15. Those are extension points and are not loaded; ADF11 stays in vaft.formula.atomic.

vaft.diagram.spectroscopy_ionization_stages("C III")   # "C2+", "carbon", "CIII_1909" too
vaft.diagram.spectroscopy_transitions("H-alpha")        # "OI_7770": declared wavelength only
vaft.diagram.spectroscopy_energy_levels("D-alpha")
vaft.diagram.spectroscopy_spectrum()                    # the labels VEST's spectrometer declares

Neutral beam injection: lifecycle and reduced attenuation

A small, machine-independent NBI layer. It is not NUBEAM, ASCOT5 or BEAMS3D, and it never replaces vaft.code.nubeam.

• Formulas (vaft.formula.nbi): beam_particle_rate_from_power_energy (per energy component, in eV), neutral_beam_optical_depth, neutral_survival_fraction_from_optical_depth, beam_birth_probability_density (a density along the path, not a volumetric deposition), shine_through_fraction, and injected_toroidal_angular_momentum_rate. The last is the ideal rate carried in, not the torque on the plasma.
• Process (vaft.process.nbi.neutral_beam_attenuation_along_path): composes these along a prescribed 1-D path and adds the particle and power bookkeeping. Births are counted per path cell as $S_i - S_{i+1}$, so $\sum_i + f_\mathrm{shine} = 1$ and $P_\mathrm{birth} + P_\mathrm{shine} = P_\mathrm{injected}$ hold exactly on any grid. The “power birth profile” is where neutrals become fast ions, not where the plasma is heated. The process module’s docstring tabulates what this layer answers and what needs a full solver; related work is #265 (VEST NBI description), #592 (NUBEAM → IMAS), #1064 and #1092 (scales, orbits).

The attenuation coefficient $\alpha = \sum_j n_j\sigma_j$ is always an input; no beam-stopping data are built in. Orbits, trapped and passing fast ions, and $P_\phi$ are the particle-motion diagrams’, and are not redrawn here.

vaft.diagram.nbi_particle_lifecycle()      # shine-through / prompt loss / delayed loss kept apart
vaft.diagram.nbi_neutral_attenuation()     # S(s), b(s), births and f_shine from vaft.formula.nbi

Iteration behaviour, branch bifurcation and branch selection

Non-convergence can arise from true branch structure or from numerical cycling. A solver that does not converge has not necessarily found an unphysical solution, and these diagrams separate the cases. They are generic concept diagrams for EFIT convergence, grid, weighting and continuation studies. No shot, residual or grid comparison is shown or implied, and none of them claims that a physical bifurcation exists in VEST equilibria.

Every curve is computed:

• the iteration panels come from the logistic map $x_{k+1} = rx_k(1 - x_k)$ at $r = 2.8$, $3.2$ and $3.5$, and from an expanding linear map;
• the branch diagram is the saddle-node normal form $\dot x = \lambda + x - x^3$;
• the basins are its exact relaxation at $\lambda = 0$.

The bifurcation is drawn once. The basin diagram is the same model at one control parameter, not a second bifurcation figure.

vaft.diagram.iteration_behavior()       # fixed point, divergence, 2-cycle, period-4 limit cycle
vaft.diagram.branch_bifurcation()       # stable (solid) / unstable (dashed), folds, jumps, hysteresis
vaft.diagram.basin_of_attraction()      # initial condition selects branch A or B
vaft.diagram.grid_induced_two_cycle()   # each re-solve lands nearer the other node: a one-cell hop
vaft.diagram.branch_selection()         # the last two side by side under one caption

Cold-plasma waves: dispersion, cutoffs, resonances and the CMA diagram

Each diagram is drawn from the cold-plasma equations in vaft.formula.waves:

• plasma_frequency;
• stix_parameters, giving $R, L, S, D, P$ with the signed cyclotron frequency, so $\Omega_e < 0$, and dielectric_tensor;
• cold_plasma_refractive_index_squared, the two roots of $An^4 - Bn^2 + C = 0$, in a cancellation-free form that keeps the finite root at a resonance cone;
• perpendicular_refractive_index_squared, giving $n_O^2 = P$ and $n_X^2 = RL/S$;

• cma_coordinates, giving $X = \omega_{pe}^2/\omega^2$ and $Y =

  \Omega_e

  /\omega$;

• propagation_regime, which classifies propagating, evanescent, cutoff and resonance.

Boundaries are zeros or poles of the Stix parameters, located by bracketing the formulas; no closed form is typed into a drawing. The $\pm$ roots are algebraic branches, not mode names, so O/X and R/L are named only where the mode is tracked: at $\theta = \pi/2$ and $\theta = 0$. Electrons only, ions immobile: the electron-cyclotron range. Warm-plasma effects, damping, ray tracing and full-wave solutions are out of scope.

import math

vaft.diagram.o_mode_cutoff()                                  # n_O^2 = P, cutoff at omega_pe
vaft.diagram.x_mode_dispersion(omega_pe_over_omega_ce=1.2)    # L, R cutoffs; upper-hybrid resonance
vaft.diagram.cma_diagram()                                    # P, R, L, S = 0 and Y = 1 in (X, Y)
vaft.diagram.profile_propagation()                            # layers along an example midplane
vaft.diagram.profile_propagation(theta=math.radians(60))      # oblique: both roots, A = 0 resonances
vaft.diagram.wave_dispersion_omega_k(omega_pe_over_omega_ce=1.2)  # branches in the omega-k plane
vaft.diagram.refractive_index_vs_X(Y=0.5)                     # rising density at fixed field
vaft.diagram.refractive_index_vs_Y(X=0.5)                     # rising field at fixed density

Every view takes theta, from $5^\circ$ to $\pi/2$ (below that, parallel propagation is the picture). At $\theta = \pi/2$ the branches are named O (blue) and X (red). At any other angle both roots of cold_plasma_refractive_index_squared are drawn in one colour, because the algebraic $\pm$ branches swap at the cyclotron layer, and the resonance moves from $S = 0$ to the cone $A = S\sin^2\theta + P\cos^2\theta = 0$, which is marked.

Neoclassical and NTV collisionality regimes

Two different regime families that share the word “collisionality”. Axisymmetric neoclassical transport orders the collision frequency against the transit and bounce frequencies. Neoclassical toroidal viscosity (NTV) in broken symmetry orders it against the bounce-averaged precession $\omega_d = \omega_E + \omega_B$:

Coulomb collisions -> transit / bounce motion -> nu_hat = qR nu/v -> banana / plateau / Pfirsch-Schlueter
3-D delta B + precession omega_d -> 1/nu / nu-sqrt(nu) / superbanana-plateau / nu -> NTV torque

The axis of the first diagram is $\hat\nu = qR_0\nu/v$ (collisions_per_transit), not a $\nu_$. VAFT’s several $\nu_$ conventions (issue 353) share the symbol but not the value. The boundaries $\hat\nu = \epsilon^{3/2}$ and $1$ come from neoclassical_regime_boundaries. The orbit scales behind them are transit_frequency, deeply_trapped_bounce_frequency, trapped_particle_effective_collision_frequency and banana_width in vaft.formula.neoclassical.

vaft.formula.ntv holds the exact, convention-bearing relations:

• ntv_precession_frequency, whose zero is the superbanana-plateau resonance. $\omega_E$ is the $E\times B$ frequency omega_exb, never the toroidal rotation, and both $\omega_E$ and $\omega_B$ are measured along the plasma current;
• nonambipolar_torque_density, the torque on the plasma: the $\mathbf J\times\mathbf B$ of the return current that cancels the non-ambipolar flux. Ion loss in a co-current plasma drives counter-current rotation.

The size of the flux needs a drift-kinetic code (vaft.code), and Shaing’s connected formula is not implemented, so the NTV regime diagram shows slopes only.

vaft.diagram.neoclassical_collisionality(epsilon=0.1)
vaft.diagram.ntv_collisionality()
vaft.diagram.ntv_precession_regimes(omega_magnetic=1.0)

Canonical transport concepts

Three concept figures for the transport reference relations in vaft.formula.transport:

• how a diffusivity is defined;
• how gradients drive fluxes;
• how the classical, Bohm and gyro-Bohm reference scales relate.

They explain definitions. None predicts the transport of a plasma.

radial motion -> mean-square displacement (late slope)  -> D
              -> velocity autocorrelation (area)         -> D
gradient -> diffusive term + convective term -> flux   (one flux does not fix D and V)

random_walk_diffusion draws one exponentially correlated velocity three ways, with a fixed seed:

• sample trajectories;
• the mean-square displacement, which is ballistic at first and diffusive later;
• the autocorrelation.

Both definitions, diffusivity_from_mean_square_displacement on the late slope and diffusivity_from_velocity_autocorrelation on the area, give $D = \langle v_r^2\rangle\tau_c$.

transport_flux_gradient keeps the diffusive and convective terms apart for particles, heat and toroidal momentum (per unit volume in $v_\phi$). The momentum flux’s residual stress is a third term, neither diffusive nor convective. Its inset shows the inverse problem: one $\Gamma$ at one $\partial_r n$ is the line $V = (\Gamma + D\,\partial_r n)/n$, checked against particle_flux_from_D_grad_n_V_n.

transport_reference_scales sorts the scales by role:

• collisional: classical and neoclassical;
• empirical reference: Bohm;
• turbulence normalisation: gyro-Bohm.

It draws no magnitude axis, because their sizes are not universally ordered. The banana, plateau and Pfirsch–Schlüter regimes are neoclassical_collisionality above. It states its $\hat\nu$ convention, and since #1112 it shades a transition range, a factor of 3 either side of each boundary, rather than drawing exact lines.

vaft.diagram.random_walk_diffusion()
vaft.diagram.transport_flux_gradient()
vaft.diagram.transport_reference_scales()

Wall conditioning

Baking, glow-discharge cleaning and boronization, each drawn as a transition of the wall state $S^{(0)}\mathrm{wall} \to S^{(1)}\mathrm{wall}$ (WALL_STATE_CHANGE in the module), not only as “cleaning”. The diagrams are reduced and semantic, and share one vessel with an inlet port, a pump port and a wall-surface primitive:

• baking is thermal desorption only: no glow, anode, ion bombardment or coating;
• the glow discharges share one apparatus template: gas feed, glow, anode, the wall as cathode, and ions accelerated across the cathode sheath onto the whole wall. H$_2$/D$_2$ is reactive cleaning, with volatile O/C products that match the feed isotope. He is ion-induced release of retained H/D, drawn with its own arrow style;
• boronization names a “B-containing precursor” unless one is passed, and leaves a B-rich layer.

Species are examples. No temperature, precursor, pressure or thickness is built in. A temperature (in K or °C) or a thickness is drawn only when the caller passes it together with its source. The sequence ends in plasma operation; how the conditioned wall responds then is the plasma-wall interaction section.

vaft.diagram.wall_conditioning_baking()        # temperature=, temperature_unit="K"|"degC", temperature_source=
vaft.diagram.wall_conditioning_gdc("D2")       # "H2", "D2" or "He"
vaft.diagram.wall_conditioning_boronization(precursor="B$_2$H$_6$")
vaft.diagram.wall_conditioning_sequence(("baking", "D2_gdc", "He_gdc", "boronization"))

Canonical turbulence concepts

Six concept figures built on the fluctuation-driven transport definitions in vaft.formula.turbulence. Geometry is slab: $x$ radial (outward), $y$ binormal, $\mathbf B = B\hat z$. They explain mechanisms; none is a turbulence model, a stability classifier or a transport prediction.

gradient -> omega_* -> drive and kinetic response -> gamma (if > 0) -> n~, phi~ -> v_E -> flux <n~ v_r>
  flux -> profile relaxation (slow, transport time scale)
turbulence -> Reynolds stress -> d_r R != 0 -> zonal flow -> E x B shear --| turbulence (fast, at fixed gradients)

Two feedbacks are kept apart. Profile feedback is slow: the flux changes the gradients on the transport time scale, which is set by the particle and energy balance. Flow feedback is fast: zonal flows saturate the turbulence at fixed gradients, as in a flux-tube simulation.

• drift_wave_transport_cycle draws that loop. A gradient is a possible free-energy source; whether a mode grows is decided by the instability drive and kinetic response, and $\omega_*$ is a frequency scale, not $\gamma$. Each step names its definition:
  • $\omega_* = \mathbf k\cdot\mathbf v_*$;
  • $\mathbf v_E = \mathbf B\times\nabla\phi/B^2$ (it calls particle.exb_drift_velocity);
  • $\Gamma = \langle\tilde n\tilde v_r\rangle$.
• cross_phase_transport shows one mode at $\theta_{n\phi} = 0, \pm\pi/2$. Each flux comes from coherent_particle_flux_from_amplitudes_phase and is checked against a direct average of $\tilde n\,\tilde v_x$. The convention ($\theta_{n\phi} = \alpha_\phi - \alpha_n$, real cosine fields, $x$ up, $y$ right, $\mathbf B$ into the page) is in the model and on the figure. It covers one Fourier component, and a zero particle flux does not imply a zero heat flux. Changing every convention consistently changes the intermediate signs, not the physical flux.
• mixing_length_saturation: growth $\gamma$ against an estimated decorrelation rate $k_\perp\tilde v$. Balancing them at $\tilde v = \gamma/k_\perp$ gives the phenomenological scaling mixing_length_diffusivity_from_gamma_k_perp. It is not a predictive saturation rule:
  • one mode’s $E\times B$ velocity does not advect its own potential ($\tilde{\mathbf v}_E\cdot\nabla\tilde\phi = 0$);
  • saturation therefore needs coupling between modes (zonal flows, stable modes, spectral transfer);
  • quasilinear models need a separate saturation rule (Staebler, Bourdelle, Citrin and Waltz, Nucl. Fusion 64 (2024) 103001);
  • $D_\mathrm{ML}$ is not $D_n$ or $\chi$ of any channel.
• exb_shear_decorrelation: a round eddy, and the same eddy after the shear map $y \to y + St\,x$.
  • The cut through its centre at fixed $y$ shrinks by $\sqrt{1 + (St)^2}$, while its total radial extent is unchanged. This is geometry, not the statistical correlation length; measured $E_r$ and shearing-rate profiles are plots.
  • The decorrelation is a separate, following step: $k_x(t) = k_x(0) - Sk_yt$ (Biglari, Diamond and Terry, Phys. Fluids B 2 (1990) 1).
  • $\gamma_E$ above $\gamma_\mathrm{lin}$ is a rule of thumb, not a universal threshold.
• zonal_flow_feedback: the self-regulation loop with the Reynolds-stress and zonal-flow-drive definitions:
  • only the stress divergence $\partial_rR_{r\theta} \neq 0$ drives the flow;
  • the shear changes the turbulence through mode coupling and decorrelation, which often but not always suppresses it;
  • the damping $\mu$ is a stated choice, and no coefficient model is assumed;
  • the slab has constant density, and a tokamak adds curvature, GAMs, collisional damping and Maxwell stress.

  The loop follows Diamond et al., Plasma Phys. Control. Fusion 47 (2005) R35.

• turbulence_scale_hierarchy: representative perpendicular scales $1/k_\perp$ against the lengths of the spatial_scale_orderings state:
  • ITG/TEM at $k_\perp\rho_i \sim 0.1$–$1$;
  • ETG at $k_\perp\rho_e \sim 0.1$–$1$;
  • a dashed TEM extension to $k_\perp\rho_s \sim 5$.

  The conventions:

  • the bands are conventions, not thresholds;
  • the state is illustrative hydrogen, not a VEST measurement;
  • it uses $v_t = \sqrt{T/m}$, and deuterium makes $\rho_i$ and $\rho_s$ larger by $\sqrt2$;
  • the axis length is $1/k_\perp$, not the wavelength;
  • the ITG/TEM and ETG bands are in $k_\perp\rho_i$ and $k_\perp\rho_e$;
  • only the TEM extension uses the literature’s $k_y\rho_s$, taken as $k_\perp$ with $k_x = 0$, and it is one regime’s example, not a bound.

vaft.diagram.drift_wave_transport_cycle()
vaft.diagram.cross_phase_transport()
vaft.diagram.mixing_length_saturation()
vaft.diagram.exb_shear_decorrelation(shear=1.6)
vaft.diagram.zonal_flow_feedback()
vaft.diagram.turbulence_scale_hierarchy()

SOL blobs and filaments

A blob is a localized positive density (pressure) perturbation in the scrape-off layer, and a hole is a negative one. The filament is the field-aligned structure whose perpendicular cross-section is the blob.

How a blob moves:

• curvature and $\nabla B$ drift ions and electrons apart;
• the density monopole becomes a charge dipole, $+$ above and $-$ below;
• the dipole’s $E$ field drives an $E\times B$ drift outward on the low-field side, down $\nabla B$ (a hole moves inward).

How fast it moves depends on where the polarization current closes:

• along the field to the sheaths (sheath-connected, $v \propto \delta^{-2}$);
• across the field by ion inertia (inertial or resistive-ballooning, $v \propto \delta^{1/2}$);
• with resistivity and X-point fanning, in between.

vaft.formula.sol holds the prescribed filament state blob_density_perturbation (a blob, or a hole below the background), the reference size $\delta_* = \rho_s^{4/5}L_\parallel^{2/5}/R^{1/5}$, the reference velocity $v_$, the collisionality $\Lambda$, both limits, the interpolation, and the four regime scalings. All follow D’Ippolito, Myra and Zweben (2011), with a Gaussian of radius $\delta$. The $O(1)$ prefactors in Krasheninnikov (2001) and Theiler et al. (2011) belong to their own size definitions. The NSTX parameters of Myra et al. (2006) give $\hat a \approx 1.3$, as in their Fig. 1, and $v_ \approx 3$ km/s from their symbolic Eq. (3); their text quotes $v_* \sim 2$ km/s. Cold ions throughout: $c_s = (T_e/m_i)^{1/2}$.

vaft.diagram.blob_polarization()        # the mechanism: dipole, E, E x B; perturbation="hole" reverses it
vaft.diagram.blob_current_closure(regime="sheath")   # or "inertial": where the current closes
vaft.diagram.blob_velocity_scaling()    # v/v* against delta/delta*: both limits and Eq. (9)
vaft.diagram.blob_regimes(epsilon_x=0.1)  # Lambda against Theta = delta_hat^{5/2}: RB, RX, C_i, C_s

The VAFT framework: pillars, research cycle, managed pipeline, provenance

These diagrams describe what VAFT is and how scientific data moves through it (#1090). They work at the level of scientific capabilities, not deployment: no storage backend, endpoint, path or module name appears in them, and a test enforces this. The README uses the four pillars, the research cycle and the managed pipeline.

vaft.diagram.vaft_four_pillars()
vaft.diagram.fusion_science_knowledge_lifecycle()
vaft.diagram.scientific_workflow()
vaft.diagram.interoperability_layers()
vaft.diagram.scientific_provenance_chain()
vaft.diagram.plasma_state_provenance()
vaft.diagram.scientific_infrastructure_principles()
vaft.diagram.machine_agnostic_architecture()
vaft.diagram.experiment_modeling_theory_data_network()   # "point_to_point", "common_model", "equilibrium"
vaft.diagram.integrated_scientific_framework()           # domain=None or "equilibrium"
vaft.diagram.human_ai_interface()
vaft.diagram.machine_research_archive()

The four pillars, the research cycle, the managed pipeline and the human-AI interface carry semantic pictograms (#2101, #2109), one symbol per concept:

The symbols name a kind of activity or component only. They do not mark anything as implemented or validated, and the labels stay authoritative.

The interoperability figures read as one progression, from data interoperability through scientific integration to infrastructure and implementation. The four nodes of the network and framework figures are research modes, not physics domains; Research domains sets out how the two classifications cross:

1. pairwise interfaces, experiment_modeling_theory_data_network("point_to_point");
2. a shared scientific representation, experiment_modeling_theory_data_network("common_model");
3. an integrated scientific framework, integrated_scientific_framework(), and its equilibrium example, integrated_scientific_framework(domain="equilibrium");
4. the broader research infrastructure, experimental_research_infrastructure() (#1636);
5. the managed workflow, scientific_workflow();
6. the VEST implementation, vest_data_platform().

The pillar names are the four README sections. The diagrams are built from the concept primitives in vaft.diagram._concept: box, connector, band, and database, a drum drawn as polylines. They use the concept … and connector … styles of the template.

Research infrastructure: four levels of integration, the community and ownership

Why VAFT is built the way it is, in four levels (#1641, #1636, #1638, #1640). Each level is a pair of figures from one builder: organization="fragmented" draws the problem and organization="integrated" the architecture that answers it. The pair grammar is shared:

• the fragmented figure draws research paths as dashed silos, joined only by red, dashed ad-hoc links (level 3 is one chain of steps instead, with the evidence each step loses beneath it);
• the integrated figure draws the same entities around the shared layer that replaces those links;
• both carry the level tag at the top left and numbered notes at the bottom, set as columns of text. The fragmented figure lists what goes wrong, each in plain words with its technical term and, where there is one, a reference: ^n plain words (technical term) [reference]. The integrated figure lists what answers each one, under the same number;
• the numbers are cited like footnotes, as a grey superscript after the text they belong to. In the figure they mark where a symptom arises and which part of the architecture answers it, and they run in the order the problem figure cites them.

vaft.diagram.scientific_representation("fragmented")             # level 1, #1641
vaft.diagram.scientific_representation()                         # "integrated" is the default
vaft.diagram.experimental_research_infrastructure("fragmented")  # level 2, #1636
vaft.diagram.scientific_credibility("fragmented")                # level 3, #1638
vaft.diagram.research_modality_architecture("fragmented")        # level 4, #1640
vaft.diagram.fusion_research_ecosystem()                         # #1643, "full" or "presentation"
vaft.diagram.scientific_ownership_architecture()                 # #1645

Read in order, the figures make one argument. A Common Data Model answers the representation problem (experiment_modeling_theory_data_network). It is not enough on its own: a research infrastructure also needs a FAIR repository and a research framework. Reproducibility is not enough either: a result also needs traceable justification. The same science must then serve every researcher, interface and environment. The managed pipeline is scientific_workflow, and the VEST implementation is vest_data_platform.

The figures keep several distinctions visible, and the tests check them:

• HDF5 is a serialization format, not the scientific model. The level-1 figure shows it only as one encoding beside NetCDF, MATLAB files and native outputs, and names no storage service;
• provenance is not validity, numerical verification is not physical applicability, and a surrogate’s training domain is checked apart from its physics model;
• GUI, CLI and MCP are interfaces, never part of the core;
• external solvers keep their own platform limits.

fusion_research_ecosystem asks a different question: who does fusion research, what they do, and which shared scientific states connect it (#1643). The "full" figure shows research roles a person may combine, with graduate researchers and learners across every activity. Planning leads to a planned shot and a planned simulation run. Experiment and simulation are parallel, epistemically distinct producers. Comparison, validation and synthesis yield qualified states and feed new questions back to planning. Knowledge is preserved and transferred, and the states serve generic research contexts; only the reference implementation, VEST, is named. The "presentation" figure is a one-slide projection of the same model, with shared scientific states feeding experimental planning and operation, physics interpretation and discovery, and modelling, prediction and validation. Curved arrows show exchange between neighbouring uses; they do not prescribe a fixed sequence. A test checks that its roles, verbs, states and uses map back to the detailed figure’s roles, activities and states.

scientific_ownership_architecture shows where scientific logic lives as research software matures (#1645). Research groups Studies by membership, not by execution order, and neither executes anything. A workflow or notebook composes computation and matures reusable logic out of itself. Data and the database, and Formula, Process, Code and learned models, produce results and evidence. Validation interprets that evidence, and an optional use policy decides what a workflow does about it. The Actor contract is an optional overlay, off every edge. The graduation rule promotes matured logic by meaning. Computational layers is the zoomed view of the computation band, and Scientific architecture uses this figure as VAFT’s normative architecture.

Related issues: #1090 (the concept family), #1550 (the VEST workflow), #497 (placement of canonical visuals), #248, #252, #1505, #1626-#1629 (provenance, contracts and applicability), #1077, #1165, #1170, #1639, #1642, #669 (ownership, Study, Research, learned models), #1174, #1086, #188, #1423, #1002, #1012, #1013, #1016 (interfaces and runtimes).

References for the terminology in the level-3 and community figures:

• R. Fischer and A. Dinklage, Integrated data analysis of fusion diagnostics by means of the Bayesian probability theory, Rev. Sci. Instrum. 75, 4237 (2004): data inconsistency, parametric entanglement, diagnostic interdependencies, complex error propagation.
• P. W. Terry et al., Validation in fusion research: towards guidelines and best practices, Phys. Plasmas 15, 062503 (2008): qualification, fortuitous agreement, primacy hierarchy.
• M. Greenwald, Verification and validation for magnetic fusion, Phys. Plasmas 17, 058101 (2010).
• W3C, PROV-DM: the PROV data model, W3C Recommendation (2013).
• M. D. Wilkinson et al., The FAIR guiding principles for scientific data management and stewardship, Sci. Data 3, 160018 (2016).
• D. Lin et al., The TRUST principles for digital repositories, Sci. Data 7, 144 (2020).
• F. Imbeaux et al., Design and first applications of the ITER integrated modelling & analysis suite, Nucl. Fusion 55, 123006 (2015).
• ITER Organization, ITER Research Plan within the Staged Approach, ITR-18-03 (2018).
• ITER Physics Basis, Nucl. Fusion 39, 2137 (1999); Progress in the ITER Physics Basis, Nucl. Fusion 47, S1 (2007).

Both infrastructure figures mark each source with the same semantic pictogram (#2109): DAQ signals → signal, machine database → database, diagnostic files → file, machine geometry → tokamak, operation & maintenance records → history, calibration & configuration → parameters. Only the integrated figure has the last one as a source, because the fragmented figure keeps calibration as private copies.

The four concept figures embedded in the README and guides carry a few semantic pictograms (#2113), placed where they help a reader tell kinds of things apart and left out elsewhere:

A symbol never claims that a capability is implemented or a product is validated. The upstream versus VAFT ownership brackets, the execution routes and the mapping step keep their labels.

The content is the data at the top of each section of vaft.diagram._research_concepts (INFRA_*, CREDIBILITY_*, MODALITY_*, REPRESENTATION_*, ECOSYSTEM_*, PRESENTATION_*, OWNERSHIP_*), so a figure is changed by editing data.

The VEST data platform

The VEST data platform as a database-centred scientific workflow (#1550), laid out as a cross about the database. The VEST machine, a CAD render packaged with vaft.diagram and embedded in the SVG, sits outside the platform server and feeds experimental data processing (the render). A per-shot directory is the hub: reconstruction and physics inference (above) and simulation (right) read from it and write back to it. Users reach it from below, and the whole runs on Windows, macOS and Linux, locally or on an HPC cluster. The content is declared in vaft.diagram._platform (EXPERIMENTAL_PROCESSING, DATABASE_LAYOUT, RECONSTRUCTION, DERIVED_PHYSICS, SIMULATION, ACCESS, EXECUTION_*), so the figure is updated by editing data. The database technology appears once, as a muted caption under its title (DATABASE_TECHNOLOGY: IMAS · HDF5 · HSDS); no other backend or workflow-engine names are drawn.

vaft.diagram.vest_data_platform()           # the reference architecture view
vaft.diagram.vest_data_platform_overview()  # five stages, for papers and slides

Integrated modeling: knowledge basis, realization, abstraction

A single “analytic / numerical / empirical / data-driven” list mixes three independent questions. These diagrams keep them apart (#1085):

• Knowledge basis: where does the model’s knowledge come from, from first-principles to data-driven?
• Computational realization: how is the model evaluated, from analytical to fully numerical?
• Physical abstraction: at what description level is the system represented, from particle orbits to static equilibrium?

The diagrams then combine the three axes into one space and connect models by typed couplings. They show location and character, not ranking: neither end of an axis is better.

vaft.diagram.knowledge_basis()
vaft.diagram.computational_realization()
vaft.diagram.physical_abstraction()
vaft.diagram.integrated_modeling_space()                 # "fusion", "tearing"
vaft.diagram.integrated_modeling_process()

Semi-empirical is a knowledge basis: a physical form with fitted coefficients. Semi-analytical is a computational realization: an asymptotic expansion, a Green-function reduction or a quadrature of a closed form. The words look alike but belong to different axes.

Positions are semantic, not layout. Models with the same knowledge basis share an x and are separated in y. A learned model is not a realization rung. A surrogate takes the y of the model it emulates and is linked to it; a model that emulates nothing, such as a classifier, sits at the rung of its evaluation.

The "fusion" overlay places familiar codes, from Solov’ev, EFIT and CHEASE to TGLF, TRANSP and ASCOT5, with an empirical confinement scaling, a neural-operator surrogate of TGLF and an event classifier. These placements are illustrative, not a classification:

• EFIT is an inverse model: it solves the Grad–Shafranov equation numerically inside a fit to measurements.
• TRANSP is mainly used interpretively, so it is also an inverse model.
• DCON integrates the Newcomb ODE, which is a reduced numerical method.
• TGLF is gyro-Landau-fluid approximating gyrokinetics, with a saturation rule fitted to nonlinear gyrokinetic runs, so it sits at semi-empirical/closure. The "tearing" variant follows one phenomenon from an island picture in the explanatory layer, through the Rutherford equation, to a nonlinear resistive-MHD simulation.

The coupling types are data flow, closure, parameter inference/calibration, surrogate replacement, residual correction, validation/benchmarking, feedback/control and iterative coupling. A coupling is a label on an edge. The data-driven model’s three uses are alternatives: a closure inside the forward model, or a surrogate replacement of it, or a residual correction of its prediction (the hybrid mode). Validation compares the prediction with the processed measurement, and control acts on the experiment.

The vocabulary and the example placements are data in vaft.diagram._modeling_schema: the axis stations, ModelDescriptor, ModelCoupling and the coupling types. They are kept apart from the drawing so that documentation and provenance tooling can reuse them. They are not a stable public API yet.

Spatial vocabulary: coordinates, geometry, meshes, mappings and topology

Concept-oriented schematics of the spatial ideas VAFT works with, organised by the concept rather than by a code: a structured grid or a logical mapping is drawn as the numerical idea several equilibrium, transport and MHD codes share. They need no shot data; vaft.plot draws a particular equilibrium, mesh or field. vaft.diagram._spatial.SPATIAL_FAMILIES files every builder below by family.

vaft.diagram.tokamak_top_view(cocos=11)
vaft.diagram.cocos_orientation(11)                 # one panel
vaft.diagram.cocos_orientation(range(1, 9))        # one panel per index, one scale
vaft.diagram.machine_and_equilibrium_geometry()
vaft.diagram.structured_rz_grid(n_r=13, n_z=21)
vaft.diagram.geometry_to_mesh()
vaft.diagram.logical_to_physical_mapping()
vaft.diagram.physical_to_flux_mapping()

Conventions shared by every figure: $R$ to the right and $Z$ up in the poloidal plane; $\odot$ out of and $\otimes$ into the page; the magnetic axis is a filled blue dot, an X-point a cross; the LCFS a black line, the separatrix blue; the computational boundary dashed; the machine (vessel, limiter, coils) in black outline, faint where it is shown only for reference; regions shaded plasma blue, vacuum green, conductor grey; measurements red (outboard) and orange (inboard). The machine and the flux are the toy free-boundary model of the Grad–Shafranov diagrams, not any device. The sense of $\theta$ differs on purpose: the cocos_orientation panels draw it as the index fixes it (COCOS 11, $\sigma_{R\phi Z} = +1$ and $\sigma_{\rho\theta\phi} = +1$ with $\phi$ into the page, puts $\theta$ clockwise in the $(R, Z)$ plane as drawn), while the torus, mesh and mapping figures (tokamak_torus, logical_to_physical_mapping, sfl_coordinate_grids) are convention-free sketches that use the mathematical angle, counter-clockwise from the outboard midplane.

Physics workflows: derivation, inference and solver coupling

The level-2 view below the platform overview (#1585). Each figure is drawn from one declarative WorkflowSpec (vaft.diagram._workflow); the same record produces the figure and the table under it, and the tests require every API and equation it names to exist on this tree. The figures follow the current implementation: where VAFT does not yet implement the physically complete step, or has no IMAS mapping, the node carries a red IMAS mapping TODO and the workflow lists its follow-up TODOs instead of drawing an unsupported capability. Node style says how a quantity was obtained:

Each legend entry draws the kind’s semantic pictogram inside its colour swatch (#2114), followed by its label. The swatch and label stay authoritative, and the symbol never encodes implementation status: a computation symbol on solver / model does not mean the solver runs, and standardized does not mean a product passed validation. The symbols appear only in the legend, not inside the nodes. Node-level icons were compared on magnetic_efit, kinetic_efit, plasma_parameter_inference, tokamaker_coupling and tglf_cgyro_local_transport: they crowded the bold titles and equations (Measurement constraints, the side inputs) and repeated what the node’s style already says, so they were not adopted.

Inputs and outputs carry their representative variables under the label, and standardized nodes their IMAS path. A step’s equation is drawn inside it: the vaft.formula catalog definition (formula_equation) where one exists, otherwise a relation restating the expression the named API implements.

vaft.diagram.plasma_parameter_inference()
vaft.diagram.romero_transformer_balance()
vaft.diagram.resistive_zeff_inference()
vaft.diagram.magnetic_efit()
vaft.diagram.kinetic_efit()
vaft.diagram.analytic_mhd_equilibrium()
vaft.diagram.chease_coupling()
vaft.diagram.tokamaker_coupling()
vaft.diagram.dcon_rdcon_stability()
vaft.diagram.gpec_plasma_response()
vaft.diagram.flare_field_line_topology()
vaft.diagram.neo_neoclassical()
vaft.diagram.tglf_cgyro_local_transport()
vaft.diagram.parameter_inference_overview()
vaft.diagram.parameter_inference_dependency_graph()
vaft.diagram.eddy_current_model()
vaft.diagram.kinetic_profile_fitting()
vaft.diagram.transport_hierarchy()
vaft.diagram.neoclassical_model_comparison()
vaft.diagram.machine_model_history()
vaft.diagram.signal_processing()
vaft.diagram.quality_validation()
vaft.diagram.fault_anomaly_detection()
vaft.diagram.shot_classification()
vaft.diagram.event_detection()
vaft.diagram.vacuum_field_proxies()
vaft.diagram.derived_mhd_parameters()
vaft.diagram.synthetic_diagnostics()
vaft.diagram.coordinate_cocos_conversions()
vaft.diagram.power_balance_confinement()

Architecture coverage: every science box of the platform figure

Each science box of the platform figure (vest_data_platform, #1550) maps to the workflow diagrams that draw it, or to a tracked gap. The table is generated from vaft.diagram._architecture_coverage, which reads the boxes from vaft.diagram._platform; a test keeps it equal to the figure and requires every named diagram to exist.

Plasma parameter inference: ion temperature and species

Measured electron profiles and the equilibrium resolved into an ion temperature, a species mix and the local quantities transport codes read. Each ion-temperature branch is kept apart, and the resolved state is held in memory (ResolvedTransportState), not written back to IMAS.

Follow-up TODOs (implementation or IMAS mapping):

• The resolved state (T_i choice, n_H, n_I) is not written back to core_profiles.
• Normalized gradients and the GACODE collision rate are computed inside the TGLF input projection, not as vaft.formula definitions.

Plasma resistance from Romero’s transformer balance

The reconstructed boundary flux, plasma current and internal inductance close Romero’s voltage balance; what the inductive part does not explain is the resistive voltage, from which the plasma resistance follows.

Follow-up TODOs (implementation or IMAS mapping):

• psi_C is formed as psi_B + L_i I_p from li_3; the current-weighted integral (transformer.current_weighted_flux_from_psi_j_dS) exists but is not used here.
• No IMAS storage for V_B, V_I, V_R or R_p (e.g. summary.global_quantities.v_loop).

Resistively equivalent effective charge

One scalar Zeff over a time window: the effective charge a chosen parallel-conductivity model needs to reproduce the plasma resistance observed through Romero’s balance. It is a model-inferred, resistively equivalent value, not a measured or radially resolved Zeff(rho).

Follow-up TODOs (implementation or IMAS mapping):

• The observed resistance carries no propagated uncertainty (smoothing ‘none’ by default); the Zeff uncertainty is the fit’s sqrt(J/(n-1)/sum w (dV/dZ)^2).
• No IMAS mapping for the scalar resistive Zeff.

Magnetic equilibrium reconstruction (EFIT)

A free-boundary Grad-Shafranov inverse problem: magnetic measurements with their uncertainties, modelled vessel currents and the machine’s Green-function tables constrain a low-order p’ and FF’ basis. EFIT fits; it does not forward-solve.

Follow-up TODOs (implementation or IMAS mapping):

• Vessel currents are modelled from a circuit driven by measured PF currents and I_p filaments, not fitted (IFITVS=0 by default); no flux loop constrains them.
• Measurement weighting is diagonal; no covariance enters EFIT.
• Native k/g/a/m files are recorded only by path and hash under equilibrium.code.parameters.

Kinetically constrained equilibrium reconstruction

The magnetic constraints plus a kinetic pressure profile: Thomson T_e, n_e and a measured or ratio-assumed T_i give pressure points with propagated uncertainty, placed in real space so EFIT maps them to psi on its own solution.

Follow-up TODOs (implementation or IMAS mapping):

• Pressure assumes one ion species with n_i = n_e: no impurity dilution or Zeff enters p_kin.
• The pressure points and the Ip scale run_kinetic_efit settles on are not stored in IMAS (manifest only); the work directory with the k-file is deleted.
• Single pass against the magnetic equilibrium: no kinetic <-> equilibrium iteration.

Analytic MHD equilibrium models

Two uses of closed-form Grad-Shafranov solutions. Forward generation builds an equilibrium from shape parameters and a profile class; fitting projects a reconstructed equilibrium onto a Solov’ev basis and reports how well it is represented.

Follow-up TODOs (implementation or IMAS mapping):

• No direct ODS writer: forward results reach IMAS through EquilibriumData -> GEQDSK -> to_omas.
• Fit results (SolovevFit) are not written to IMAS.

Fixed-boundary equilibrium refinement (CHEASE)

A reconstructed boundary and profiles re-solved at fixed boundary; the COCOS transform into and out of CHEASE is explicit.

Free-boundary equilibrium (TokaMaker)

Machine geometry, measured coil currents and power-law profile shapes solved at free boundary on a finite-element mesh; the plasma boundary is part of the solution.

Ideal and resistive MHD stability (DCON / RDCON)

An equilibrium tested for ideal stability (DCON energy principle) and for tearing (RDCON matching at the rational surfaces); the solver-native energies and Delta-prime come before any verdict.

Follow-up TODOs (implementation or IMAS mapping):

• energy_perturbed carries the DCON-normalised total delta W, not joules; the plasma/vacuum split and the full Delta-prime matrices stay native.
• Wall position, qlow and delta_mlow/high come from the packaged templates, not from VAFT options.

Ideal plasma response to 3-D fields (GPEC)

An applied non-axisymmetric coil field and the plasma’s ideal response to it: coil geometry is machine data, the excitation is prescribed, and the total, plasma and resonant fields are kept apart.

Follow-up TODOs (implementation or IMAS mapping):

• GPEC returns total and plasma fields; the vacuum part (total minus plasma) is not computed by any mapping.
• No frequency, rotation or kinetic response inputs: the response is ideal and static.
• Energies go to code.parameters; resonant quantities and cylindrical fields are not mapped.

Magnetic field-line topology (FLARE)

Field lines traced through the axisymmetric background plus the 3-D perturbation: Poincare maps, connection lengths and strike-point footprints are the native products; a heat load needs an explicit model, here a relative proxy.

Follow-up TODOs (implementation or IMAS mapping):

• Wall/target geometry and tracing settings live in the user’s FLARE control file, not in VAFT.
• No island width or stochasticity metric is computed from FLARE output (GPEC’s Chirikov K is the only one in VAFT).
• The heat load is a relative proxy; no parallel-transport or q_perp model is implemented.

Neoclassical transport: closed-form fits and drift-kinetic solution

The same resolved local state through the Sauter and Redl fits and the drift-kinetic solver NEO, so the two can be compared at one state.

Local turbulent transport: quasilinear and gyrokinetic

One local gyrokinetic state projected into TGLF (quasilinear) and CGYRO (local delta-f, linear or nonlinear); their outputs are different physical objects and are kept apart.

Follow-up TODOs (implementation or IMAS mapping):

• Rotation and ExB shear are zero in both projections (TGLF VEXB_SHEAR, CGYRO GAMMA_E, MACH): their derivation from data is not implemented (#553).
• Squareness zeta enters as 0 (VEST equilibria carry no squareness); Z_EFF is not written to input.cgyro by design: CGYRO recomputes it from the species list (Z_EFF_METHOD=2).
• No implemented local-gyrokinetic validity criterion (rho*): compare_with_oracle checks only the input translation against CGYRO’s own projection.
• gyrokinetics_local_from_tglf and gyrokinetics_local_from_cgyro write gyrokinetics_local, but no pipeline stage stores that IDS: turbulent_transport owns core_transport only, and one occurrence per flux surface awaits the #1128/#1129 occurrence model (#2020).

Plasma parameter inference: completing the kinetic profiles

Where inference sits: diagnostics and the equilibrium give reconstructed but incomplete kinetic profiles; explicit assumptions and the closures VAFT implements complete them, and every completed quantity keeps its origin on the way to simulation.

References:

1. L. L. Lao et al., Nucl. Fusion 25 (1985) 1611
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 4.25
3. J. A. Romero and JET-EFDA contributors, Nucl. Fusion 50 (2010) 115002
4. L. Spitzer and R. Harm, Phys. Rev. 89 (1953) 977
5. O. Sauter, C. Angioni and Y. R. Lin-Liu, Phys. Plasmas 6 (1999) 2834; 9 (2002) 5140 (erratum)
6. A. Redl et al., Phys. Plasmas 28 (2021) 022502

Follow-up TODOs (implementation or IMAS mapping):

• Atomic-model-constrained Z_eff(rho) (transient charge states projected through the resistive closure) is on develop as resolve_radial_composition(normalization=’resistive_closure’) (#1565, #1566, PR #1659); this diagram still draws the scalar resistive closure only.
• Rotation, E_r and the ExB shear are not inferred: downstream codes receive gamma_E = 0 as an explicit assumption (#553).
• Provenance is recorded per quantity where it exists (core_profiles origin=…; method=… records for composition, the T_i result’s origin/method fields); there is no single runtime provenance object, by design (#1601 is documentation-first).

Inferred quantities depend on inferred quantities

Provenance propagates: a composition assumption fixes the ion densities, which set the pressure-partition T_i, whose gradients reach the gyrokinetic input beside an assumed zero ExB shear. Every link below the measurements carries the assumptions above it.

References:

1. L. L. Lao et al., Nucl. Fusion 25 (1985) 1611
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 4.25

Follow-up TODOs (implementation or IMAS mapping):

• E_r, rotation and gamma_E are not inferred from data (#553): gamma_E = 0 enters the gyrokinetic input as an assumption, and force balance is future scope.

Vessel eddy currents: a circuit driven by the coils and the plasma

The passive structure is a set of resistive loops driven by the changing PF and plasma currents. VAFT solves that circuit forward from rest – it does not fit the vessel currents to the magnetics – and checks the result against the pre-plasma flux loops and probes.

Follow-up TODOs (implementation or IMAS mapping):

• Vessel currents are a forward model, not fitted to the magnetics; EFIT then treats them as known (IFITVS=0).
• The plasma filaments are placed by the caller, not taken from the equilibrium.
• The circuit is constant in time and starts from zero current; the 50 us substep is coarser than the 40 us diagnostics grid (#425).
• A missing PF channel (PF5 48644-48760, PF6 48534-48537) leaves NaN currents and the stage refuses to run.

Kinetic profile fitting: point measurements to profiles

Thomson and charge-exchange points are placed on flux surfaces by the equilibrium and fitted to smooth profiles with declared fitting choices; each fitted profile keeps its origin record.

Follow-up TODOs (implementation or IMAS mapping):

• Thomson and charge exchange are fitted separately and combined only in core_profiles; there is no joint multi-diagnostic fit.
• The kinetic-profile evidence framework (#1204) is not yet referenced by the fit records.

Transport hierarchy: classical, neoclassical, turbulent

One resolved local state and five independently computed routes; none feeds another. ‘Always available’ means the route needs no external code, not that its physics applies everywhere. Each route with a writer lands in its own core_transport.model entry, found by its identifier.index and code name – the array position k is assigned at write time.

References:

1. S. I. Braginskii, Rev. Plasma Phys. 1 (1965) 205
2. O. Sauter, C. Angioni and Y. R. Lin-Liu, Phys. Plasmas 6 (1999) 2834; 9 (2002) 5140 (erratum)
3. A. Redl et al., Phys. Plasmas 28 (2021) 022502
4. E. A. Belli and J. Candy, Plasma Phys. Control. Fusion 50 (2008) 095010
5. E. A. Belli and J. Candy, Plasma Phys. Control. Fusion 54 (2012) 015015
6. G. M. Staebler, J. E. Kinsey and R. E. Waltz, Phys. Plasmas 14 (2007) 055909
7. J. Candy, E. A. Belli and R. V. Bravenec, J. Comput. Phys. 324 (2016) 73

Follow-up TODOs (implementation or IMAS mapping):

• The closed-form Sauter/Redl results have no core_transport writer (and carry no particle or heat flux to write); they are returned, not stored.
• Classical transport uses a private identifier.index (-1): the data dictionary has no classical entry. The Braginskii forms assume a strongly magnetized plasma, and ln Lambda is flagged invalid below 10 eV.
• core_transport.model[k]: k is the array position the writer finds or appends (matching identifier.index and code.name); it is not the identifier.index.
• A nonlinear CGYRO run writes no fluxes without a saturation window: choosing it is the caller’s judgement.
• The TGLF-NN surrogate (vaft.code.gacode.tglf.surrogate) refuses VEST inputs as out of domain and has no IMAS writer.

Sauter / Redl against NEO at one state

One shared source state, two independently prepared input paths, and an end-to-end comparison against NEO as the numerical reference – not as ground truth. The bootstrap current is compared in one definition, /B0 with the vacuum B0 and its sign, on one grid; a plasma mismatch is refused, while differences in grid construction, trapped fraction and collisionality between the two input paths remain part of the gap.

References:

1. O. Sauter, C. Angioni and Y. R. Lin-Liu, Phys. Plasmas 6 (1999) 2834; 9 (2002) 5140 (erratum)
2. A. Redl et al., Phys. Plasmas 28 (2021) 022502
3. E. A. Belli and J. Candy, Plasma Phys. Control. Fusion 50 (2008) 095010
4. E. A. Belli and J. Candy, Plasma Phys. Control. Fusion 54 (2012) 015015

Follow-up TODOs (implementation or IMAS mapping):

• End-to-end, not like-for-like: the two input paths differ in grid construction, trapped fraction and collisionality definition, so part of any gap is the input path. The like-for-like check against NEO’s own Sauter/Redl columns (agreement to 1e-7) is a test, not a product.
• A stored NEO profile on a different rho_tor_norm grid is refused, not interpolated; a run whose Z_eff or n_i/n_e differs is refused when the solver’s values are passed.
• Without NEO there is no reference and no comparison; the closed-form results are not written to IMAS.

Machine model and shot history: one shot number selects the machine

The shot number is the only key. It selects the machine era (PF and wall geometry), each diagnostic’s revision (wiring, gains, baseline windows) and the shot-log record; the static machine description is built once per era and the processing era is reported per diagnostic.

Follow-up TODOs (implementation or IMAS mapping):

• The VEST COCOS index is not resolved yet (vaft.machine_mapping.conventions.equilibrium_orientation_is_resolved); the discharge sign contract stands in for it.
• The shot-log mapper writes pulse_schedule when called (vaft shotlog CLI) but build_diagnostics_ods does not call it.
• Wall and limiter history is the era table only; there is no per-component calibration lineage.
• There is no single shot-to-machine object: era, revisions and provenance are separate lookups.
• The static description is built per era, not per shot: PF, passive structure and coupling at the era’s reference shot, magnetics and TF as the un-gated inventory. Per-shot wiring and revisions apply when the diagnostics IDS is built.

Signal processing: raw digitizer records to a diagnostic IDS

A representative chain, in the order the magnetic probes use it: anti-alias low-pass on the native grid, calibration, time integration of the inductive voltage, a linear baseline over the era’s leading samples, then interpolation onto the analysis grid. Other diagnostics reorder or skip steps.

Follow-up TODOs (implementation or IMAS mapping):

• The order is per diagnostic: PF coils subtract a baseline mean, filter, scale and align; H-alpha shifts in time and resamples with an anti-aliased resampler; flux loops integrate per radian.
• There is no drift-correction stage separate from the baseline fit, and no cross-DAQ synchronization module: each mapper applies its own time shift and interpolation.
• Integration is inline in each mapper; vaft.process has no shared integration helper.
• Thomson scattering and the interferometer read post-processed files, so this chain does not apply to them.

Quality and validation: measurements against references to evidence

Three separate kinds of evidence: per-sample source validity (written to the IDS validity nodes), agreement with the vacuum model before the plasma (a report), and equilibrium fit quality turned into a slice class. Model disagreement never sets a channel’s validity.

Follow-up TODOs (implementation or IMAS mapping):

• Only source validity reaches IMAS; model-agreement and fit-quality metrics are returned as dicts and tables in the stage manifests.
• Flux-loop agreement with the vacuum model is report-only by default; only source validity can reject a loop.
• The vacuum check covers the pre-plasma window only; there is no plasma-phase synthetic magnetics check outside the EFIT residuals.

Fault and anomaly evidence: diagnostic-specific checks

There is no single anomaly model: each diagnostic has its own checks. Magnetics separate hard faults from soft flags and honour the recorded fault list; the Rogowski coil has a square-wave test; clipped PF, diamagnetic and TF records are repaired over the clipped interval; H-alpha channels are screened before they time the plasma.

Follow-up TODOs (implementation or IMAS mapping):

• No general anomaly model runs in the pipeline: vaft.process.ml provides the framework (PCA autoencoder, k-NN, one-class SVM) but no trained model ships with the package.
• The spectrometer and barometry fault registry (known_diagnostic_faults) has no pipeline consumer.
• Missing raw data marks the component unavailable or partial; it is not a per-channel fault flag.

Shot classification: rules over derived features

A shot class is a rule applied to derived features – the plasma window, the gauge-pressure response, the peak current – under stated thresholds, and it records which rule decided. It is not a measurement. A separate pre-run check classifies DAQ completeness, and equilibrium slices get a phase label from their own rule.

Follow-up TODOs (implementation or IMAS mapping):

• The four-way physics class of #57 is not implemented; the class is Plasma, BD failure or Vacuum.
• There are no disruption labels and no label-provenance store; vaft.process.ml datasets take targets from the caller.
• Events passed to the slice classifier (VDE, IRE, disruption) are caller annotations, not detections.

Event detection: onsets and windows from a robust baseline

Each waveform gets a robust baseline and spread from its quiet reference, a threshold that is the larger of a fraction of the peak and a number of robust sigmas, and an active window that must stay above it. The plasma window is then confirmed across signals: H-alpha light against the plasma current. Coil onsets anchor the loop-voltage time base.

Follow-up TODOs (implementation or IMAS mapping):

• Breakdown time is the plasma-window start; there is no separate breakdown detector.
• There is no flat-top detector (only the post-hoc slice phase) and no IRE, sawtooth or disruption detector.
• current_quench and current_spike (vaft.process.transients) measure a quench or spike in a given window; nothing in the pipeline calls them, and they do not label it an IRE or a disruption.

Vacuum fields and startup proxies: coils and vessel, no plasma

The field of the PF coils and the vessel currents alone, evaluated from geometric Green’s functions on a grid or at a point, and the breakdown proxies read from it. Everything is returned to the caller; nothing is written to an IDS except the vessel currents the evaluators solve when the ODS has none.

Follow-up TODOs (implementation or IMAS mapping):

• No vacuum field, map, proxy or breakdown margin is written to an IDS: every evaluator returns a dict, and the startup summary is a dict too.
• compute_vacuum_field_map and compute_startup_proxies_ods solve the vessel currents and store them in the caller’s pf_passive when it has no time base; startup_summary avoids that by evaluating on a private copy.
• Only vacuum sources contribute (coils and vessel, no plasma); above roughly 10 kA of plasma current the map no longer describes the machine.
• The loop voltage is a model quantity from the coil and vessel flux; it is to be compared with the measured flux-loop voltage, not substituted for it.
• No empirical threshold is applied to the Lloyd figure of merit, and the startup summary does not report it: the summary counts the null area and the Lloyd margin on the 2-D map itself.
• The point proxies come from their own point response (compute_point_response_matrices_ods), not from the grid map; the two agree to about 1e-7 relative.

Derived MHD parameters: global quantities of an equilibrium

Global quantities computed from a reconstructed equilibrium. The DD-defined betas, l_i3 and W_MHD are written to equilibrium.global_quantities; the descriptor set and the edge-q proxies are returned with their derivation records. Two poloidal betas exist on purpose: the DD leaf and the circumference form EFIT reports.

Follow-up TODOs (implementation or IMAS mapping):

• beta_pol holds the DD definition; EFIT normalizes by the LCFS-circumference field instead and differs by 26% on the packaged reference (#318). derive_global_descriptors reports the boundary-average form as beta_p_boundary_average; the DD leaf is not matched to OMFIT.
• equilibrium.vacuum_toroidal_field.r0 is corrupt on the VEST database and b0 drifts within a shot (#325); R_0 is replaced by tf.r0, loudly, and b0 is used as stored.
• beta_tor with the stored b0 does not reproduce the OMFIT reference (ratio 1.041); the reference field is unidentified (#238).
• li_3 is the ITER/Jackson third definition: the DD documents no formula for it.
• energy_mhd is (3/2) int p dV of the reconstructed pressure: a reconstruction-derived energy, not a kinetic measurement.
• The global descriptors and the edge-q proxies are returned, not written to equilibrium or summary.
• edge_q_estimate’s equilibrium source takes R_0 B_0 from the stored vacuum_toroidal_field.r0 * b0, not from resolve_reference_major_radius; the magnetics source takes it from tf.

Synthetic diagnostics: predicted signals from a modelled state

A synthetic diagnostic predicts what an instrument would record from a modelled or reconstructed state. VAFT has three: vacuum magnetics from the coil and vessel currents, the equilibrium’s diamagnetic flux, and soft-X-ray chords through a prescribed island. Assumption-completed kinetic profiles (generate_synthetic_kinetic_profiles) are a synthetic state, not a diagnostic, and are not drawn here.

Follow-up TODOs (implementation or IMAS mapping):

• There is no synthetic Thomson, interferometer, visible-camera or bolometer model: those measurements cannot be compared with a prediction of the reconstructed state.
• The vacuum magnetics are returned with their measured counterparts and written nowhere; EFIT’s own fitted magnetics (equilibrium constraints.*.reconstructed) are the solver’s native output, not a VAFT forward model.
• The vacuum forward model has no plasma current: it predicts the magnetics only before breakdown or in plasma-free windows.
• The SXR model is forward only: a rigidly rotating island of fixed width, pencil-beam chords, no filter, etendue or noise; it is comparable with a measurement only up to a per-channel calibration, and is not written to soft_x_rays.

Coordinates and COCOS: one transform per layer

Two COCOS transforms, at two layers: the ODS is normalized in place to weber (COCOS 1-8 and per-radian files become 11; a declared 11-18 is left as it is), and an in-memory equilibrium record is converted to any target COCOS. The ODS coordinate writers resolve the flux storage of each slice themselves (as_equilibrium), so they also run on an unnormalized ODS; the record-level radii and angle are COCOS-independent and returned.

Follow-up TODOs (implementation or IMAS mapping):

• The ODS writer of the 2-D flux-surface grid uses a geometric approximation (the boundary scaled by sqrt(psi_N) about the axis, the geometric angle) for every requested convention, yet labels it grid_type 11; the true PEST angle exists only in memory (vaft.process.equilibrium.straight_field_line_map).
• equilibrium_psi_to_weber leaves equilibrium.time_slice[:].constraints untouched: VAFT copies them from the DD-conformant magnetics and pf_active IDSs.
• rho_tor integrates q from the axis, so EFIT’s often outlying q[0] moves rho_tor_norm by up to about 0.04 on the innermost surfaces; packaged samples older than #192 still hold the sqrt(psi_N) proxy.

Power balance and confinement: experimental and modelled

Two power balances answer different questions. The experimental Ohmic chain splits the measured loop voltage with l_i3 and takes the stored energy of the equilibrium; the modelled budget uses Spitzer heating and modelled radiation. Neither writes to the summary IDS; the experimental chain is tabulated in the database summary sheet.