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.

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)

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

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 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).

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:

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()

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.
• No TGLF to gyrokinetics_local mapping.

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

Using the committed assets

The reference SVGs live in docs/assets/diagrams/ and are the artifacts to embed anywhere:

• Documentation pages: ![island]({{ '/assets/diagrams/magnetic_island_poloidal.svg' | relative_url }}).
• The README, notebooks and slides: link or copy the SVG. It is self-contained, with glyphs stored as paths and no external fonts or images.

They do not ship in the wheel. An installed package builds any diagram from its packaged TikZ template.

Regenerating and checking

python -m vaft.diagram.build            # re-render diagrams whose TikZ source changed
python -m vaft.diagram.build --check    # verify the committed assets; needs no TeX

Each SVG carries its own build record: one comment line after the XML declaration holding the call, the SHA-256 of the generated TikZ document it was rendered from, and the SHA-256 of the SVG without that line. Because the record lives in the diagram’s own file, two pull requests that change different diagrams share no generated file and do not conflict (#1750). --check rebuilds the TikZ in pure Python and fails in five cases: an asset is stale, an asset was edited by hand, an asset is missing, an asset has no record, or an asset is orphaned. CI runs it on every pull request. Freshness is judged on the source and not on SVG bytes, because two dvisvgm releases write different but equally correct SVG for the same picture. Rendering needs latex and dvisvgm, which TeX Live and MacTeX provide. The generated .tex, PDF, PNG and LaTeX by-products are never committed.