Formula reference

vaft.formula is documented from a single source of truth: every public function carries a standardized docstring (summary, definition, units, convention, assumptions, validity, limitations, numerical notes, references), and these pages are generated from those docstrings by python -m vaft.formula.catalog. Nothing here is written by hand, so the site and vaft.formula.describe("<name>") always agree.

import vaft.formula as F

print(F.describe("greenwald_density"))          # one formula, rendered
F.search("Sauter")                              # every formula whose text mentions it
F.list_formulas(category="stability")           # imports only that submodule

The discovery layer is loaded on first use only; import vaft.formula.stability never touches it.

Categories

Conventions that change the number

Every function whose result depends on a sign, normalisation, COCOS or unit choice carries a Convention section and is marked convention-sensitive on its page; empirical fits open their Validity section with Empirical fit. and name the dataset or publication. The recurring traps:

• Poloidal flux, Wb versus Wb/rad. The equilibrium helpers default to flux per radian (COCOS 1-8, EFIT g-files, VFIT); the IMAS Data Dictionary and the Green’s functions use full weber (COCOS 11-18). poloidal_field_factor(cocos) carries both the $2\pi$ and the orientation sign; vaft.data.eqdsk.ods_psi_to_wb_per_radian_factor settles which family an ODS holds.
• Engineering units. The confinement scalings, $n_G$, $\beta_N$ and the Verdoolaege dimensionless parameters are defined in MA, MW, $10^{19}$ m$^{-3}$ and percent; each page states what is converted internally and what is not.
• Several definitions of one quantity. Three $\nu_$ and three $\rho_$ definitions coexist (tracked in #353); each page names its own.

Constants

Every physics submodule of vaft.formula takes its constants from here so that a value is changed in one place. The electromagnetic and particle constants are CODATA 2018 recommended values [1] (MU0 keeps the pre-2019 exact definition $4\pi\times10^{-7}$, which differs from the 2018 measured value by $5\times10^{-10}$ relative); E_ALPHA is the D-T alpha birth energy [2]. SIGMA_V_COEF, SPITZER_RESISTIVITY_COEF and COLLISIONALITY_COEF are fitted prefactors whose meaning is defined by the single function that uses each of them, documented there.

The private _SCALING_COEFS table holds the engineering-unit confinement scalings (ITER89P, IPB98(y,2), the two NSTX 2006 fits and the Kurskiev 2022 ST fit). Each entry carries its prefactor, exponents, target density definition, source reference and unit-convention notes; the table is read by vaft.formula.equilibrium.confinement_time_from_engineering_parameters, which documents the conventions and cites every entry.

Utils

Utility functions for plasma physics calculations. — 9 functions.

• calculate_peaking_factor — Peaking factor, central value over volume average.
• calculate_poloidal_flux (convention) — Poloidal flux per radian from a line integral of $RB_\theta$.
• calculate_toroidal_flux (convention) — Toroidal flux as a sum of $B_\varphi$ over area elements.
• calculate_volume_weighted_average — Volume-weighted average of a sampled profile.
• fit_profile — Fit a 1-D profile with a selectable model and evaluate it on a grid.
• gradient — Derivative $dy/dx$ on a sampled 1-D profile.
• make_fit_function — Build a 1-D parametric model $f(x; c_0, c_1, \dots)$ for profile fitting.
• normalize_profile — Linear normalisation of a profile between its axis and boundary values.
• trapz_integral — Definite integral $\int y\,dx$ by the trapezoidal rule.

Equilibrium

Plasma equilibrium, current, energy, and geometry calculations. — 96 functions.

• alpha_heating_power_from_n_D_n_T_T_keV_V (empirical) — D-T alpha heating power with the rough $\langle\sigma v\rangle \propto T^2$ fit.
• approximated_diamagnetism_from_B_pa_B_tv_R0_delta_phi (convention) — Diamagnetic parameter from the vacuum toroidal field and flux change.
• aspect_ratio_from_a_R — Aspect ratio $A = R/a = 1/\varepsilon$.
• auxiliary_heating_power — Split auxiliary power into heating and current-drive parts.
• beta_normal_from_beta_tor — Normalized beta (Troyon) from toroidal beta, minor radius, field and current.
• beta_poloidal_from_circumference (convention) — Poloidal beta in the EFIT/OMFIT convention, normalized by the LCFS circumference.
• beta_poloidal_from_pressure_integral (convention) — Poloidal beta in the IMAS definition, from the pressure volume integral.
• beta_t_from_n_T_B (convention) — Toroidal beta from density, temperature and field.
• beta_toroidal_from_p_B0 — Toroidal beta from the volume-averaged pressure and the vacuum field.
• bootstrap_current_fraction (empirical) — Heuristic bootstrap-current fraction $f_{BS}$.
• bremsstrahlung_power_density_from_T_e_p_Z_eff (convention) — Bremsstrahlung power density in the pressure form.
• bremsstrahlung_power_density_from_Z_eff_n_e_T_e (convention) — Maxwellian free-free (bremsstrahlung) power density from first principles.
• bremsstrahlung_radiation_power_from_z_eff_n_e_t_e (convention) — Bremsstrahlung power density, NRL engineering form.
• calc_inverse_aspect_ratio — Inverse aspect ratio $\varepsilon = a/R_{geo}$ with input validation.
• check_kadomtsev_constraint — Whether engineering exponents satisfy the Kadomtsev constraint within a tolerance.
• confinement_factor_ITER89P — Confinement enhancement factor $H_{89}$ relative to ITER89P.
• confinement_time_from_P_loss_W_th (convention) — Energy confinement time as stored energy over loss power.
• confinement_time_from_engineering_parameters (empirical) (convention) — Thermal energy confinement time from an engineering-parameter scaling law.
• coulomb_logarithm_from_n_T (convention) — Coulomb logarithm $\ln\Lambda$ for electron collisions above 10 eV.
• current_density_from_B (convention) — Toroidal current density from the radial derivative of a poloidal field.
• current_density_from_psi (convention) — Radial-derivative current-density estimate from a poloidal flux cut.
• current_drive_efficiency (empirical) — Heuristic lower-hybrid current-drive efficiency $\eta_{CD}$.
• current_limit_from_beta — Current figure obtained by substituting $\beta_N$ for $q$ in the cylindrical relation.
• current_limit_from_q — Plasma current at a prescribed edge safety factor, cylindrical approximation.
• cyclotron_synchrotron_power_density_scaling_from_n_e_B_t_T_e — Classical electron-cyclotron emission power density, no reabsorption.
• cylindrical_safety_factor_from_R_B_epsilon_I_f_kappa_delta (convention) — Cylindrical safety factor with a shape function.
• dimensionless_scaling_coeffs_from_engineering_scaling_coeffs — Dimensionless scaling indices $(\mu_\rho, \mu_\beta, \mu_\nu)$ from engineering exponents.
• eK_from_K — Elongation parameter $e_K$ of the virial relations.
• ec_heating_power_from_I_ec_V_ec — Electron-cyclotron launched power $P_{ec} = I_{ec}V_{ec}$.
• elongation_from_RZ_boundary (convention) — Boundary elongation $\kappa$ from the extremal points of a contour.
• exact_volume_from_RZ_contour (convention) — Plasma volume from a closed $(R, Z)$ contour by Green’s theorem.
• heating_power_from_p_ohm_p_aux — Total heating power $P_{heat} = P_{ohm} + P_{aux}$.
• inductive_voltage_from_dW_magdt_I_p — Inductive voltage from the rate of change of magnetic energy.
• inverse_aspect_ratio_from_a_R — Inverse aspect ratio $\varepsilon = a/R$.
• kadomtsev_constraint_from_engineering_exponents — Residual of the Kadomtsev high-beta constraint on engineering exponents.
• kinetic_energy_from_beta_p_B_pa_V_p (convention) — Thermal energy from poloidal beta, $W_K = \tfrac{3}{2}\,\beta_p B_{pa}^2 V_p/(2\mu_0)$.
• kink_safety_factor (convention) — Kink safety factor $q_*$ with the Freidberg beta and current limits.
• li_3_from_Bp2_volume_integral — Internal inductance in the IMAS li_3 definition, from the poloidal-field energy.
• line_to_volume_avg_density — Volume-averaged density from a line average with a fixed profile factor.
• loop_voltage_from_total_flux (convention) — Surface loop voltage from the time series of boundary flux.
• loss_power_from_p_heat_dWdt_p_rad (convention) — Loss power $P_{loss} = P_{heat} - dW/dt - P_{rad}$.
• magnetic_energy_from_li_B_pa_V_p (convention) — Poloidal magnetic energy from the internal inductance, $W_M = l_i B_{pa}^2 V_p/(2\mu_0)$.
• nbi_heating_power_from_I_nbi_V_nbi — Neutral-beam injected power $P_{nbi} = I_{nbi}V_{nbi}$.
• normalize_psi — Deprecated: use psi_normalised.
• normalized_collisionality_from_a_n_q_epsilon_T (convention) — Collisionality scaling form $\nu_* \propto a\,n\,q/(\varepsilon^{5/2}T^2)$.
• normalized_collisionality_from_nu_ii_T_i_M_i_R_a_q (convention) — Ion collisionality $\nu_*$ from a collision frequency.
• normalized_larmor_radius_from_M_T_a_Bt (convention) — Normalised ion gyroradius $\rho_* = \rho_i/a$ in SI inputs.
• normalized_plasma_current (convention) — Normalised plasma current $I_N = I_p/(a B_t)$ in MA/(m T).
• nu_star_from_n_T_B_R_epsilon_kappa_I (convention) — Normalised collisionality $\nu_*$ in the Verdoolaege engineering form.
• ohmic_heating_power_from_I_p_V_res (convention) — Ohmic heating power $P_{ohm} = I_pV_{res}$.
• omega_i_tau_E_from_B_tau_E_M (convention) — Ion-cyclotron-normalised confinement time $\Omega_i\tau_E$.
• peaking_factor — Profile peaking factor, central value over volume average.
• phi_from_Bphi (convention) — Toroidal flux $\Phi$ through a poloidal cross-section.
• poloidal_field_factor (convention) — Sauter Eq. 20 prefactor $k = \sigma_{R\varphi Z}\,\sigma_{B_p}/(2\pi)^{e_{B_p}}$.
• psi_from_RBtheta (convention) — Poloidal flux $\psi$ from a line integral of $R B_\theta$ across flux surfaces.
• psi_normalised (convention) — Normalised poloidal flux $\psi_N$.
• q_cyl_from_B_R_epsilon_kappa_I (convention) — Cylindrical safety factor in the Verdoolaege convention.
• q_from_phi (convention) — Safety factor $q$ as the flux derivative $d\Phi/d\psi$.
• q_from_rhoN (convention) — Safety factor from the toroidal-flux label $\rho_N(\psi_N)$.
• radial_magnetic_field_from_psi (convention) — Radial magnetic field $B_R$ from the poloidal flux map.
• rhoN_from_phi (convention) — Normalised toroidal-flux radius $\rho_N$.
• rhoN_from_qpsiN (convention) — Normalised toroidal-flux radius from the $q$ profile.
• rho_star_from_M_T_B_R_epsilon (convention) — Normalised ion gyroradius $\rho_*$ in the Verdoolaege engineering form.
• rho_tor_from_phi (convention) —

  Dimensional toroidal-flux radius $\rho_{tor} = \sqrt{

  \Phi

  /(\pi

  B_0

  )}$.

• shear_from_r_q (convention) — Magnetic shear $s$ of the safety-factor profile.
• spitzer_resistivity_from_T_e_Z_eff_ln_Lambda (convention) — Spitzer parallel resistivity $\eta_\parallel$.
• stored_energy_from_beta_V (convention) — Stored energy from toroidal beta, $W = \beta B_0^2 V/(2\mu_0)$.
• stored_energy_from_p_V (convention) — Stored energy as pressure times volume, $W = pV$.
• surface_poloidal_flux_from_psi_boundary (convention) — Total poloidal flux at the plasma surface, $\Phi_{surface} = 2\pi\psi_b$.
• toroidal_flux_from_q_psi (convention) — Cumulative toroidal flux $\Phi(\psi)$ from the $q$ profile on a full-weber grid.
• triangularity_from_RZ_boundary (convention) — Boundary triangularity $\delta$ from the midplane intersection.
• verify_kadomtsev_constraint — Reconstruct the Kadomtsev constraint value from dimensionless indices.
• vertical_magnetic_field_from_psi (convention) — Vertical magnetic field $B_Z$ from the poloidal flux map.
• virial_D0_boundary_from_bp_li_eK (convention) — Boundary Shafranov shift $D_0(b)$ from $\beta_p$, $l_i$ and elongation.
• virial_S1_approx (convention) — Leading-order value of the first Shafranov integral, $S_1 = 2$.
• virial_S2_approx_from_D0_a_R0 (convention) — Analytic approximation of the second Shafranov integral for an elongated boundary.
• virial_S3_approx_from_eK_d (convention) — Analytic approximation of the third Shafranov integral for an elongated boundary.
• virial_beta_p_from_S_alpha_mu (convention) — Poloidal beta from the Shafranov integrals, low-aspect-ratio closure.
• virial_beta_p_from_S_li — Poloidal beta from $S_1$, $S_2$ and a known internal inductance.
• virial_beta_p_from_volume (convention) — Poloidal beta from a volume integral of pressure.
• virial_beta_p_lao_from_S_mu_rt — Poloidal beta, Lao large-aspect-ratio virial closure.
• virial_beta_p_li_from_S_alpha_mu_rt — Lao closure bundle: $\beta_p$, $l_i$ and $\beta_{p,d}$ in one call.
• virial_beta_pd_from_S_mu_rt — Diamagnetic poloidal beta $\beta_{p,d}$ from $S_1$, $S_2$ and $\mu_i$.
• virial_bongard_from_S_alpha_mu — Low-aspect-ratio virial closure (Bongard 2016): $\beta_p$ and $l_i$.
• virial_bp_li_lihat_from_S123 — Solve the three virial relations for $\beta_p$, $l_i$ and $\hat l_i$.
• virial_kinetic_energy — Bulk kinetic energy of a sampled flow, $W_{kin} = \tfrac{1}{2}\sum n m v^2\,V$.
• virial_lao_from_S_alpha_mu_rt — Large-aspect-ratio virial closure (Lao 1985): $\beta_p$ and $l_i$.
• virial_li_from_S_alpha_mu (convention) — Internal inductance from the Shafranov integrals, low-aspect-ratio closure.
• virial_li_from_S_alpha_rt — Internal inductance, Lao large-aspect-ratio virial closure.
• virial_li_from_volume (convention) — Internal inductance from a volume integral of $B_p^2$.
• virial_magnetic_energy — Magnetic energy of a sampled field, $W_{mag} = \sum B^2\,V/(2\mu_0)$.
• virial_muihat_from_Bt_R0_dphi (convention) — Diamagnetic parameter $\hat\mu_i$ from the measured diamagnetic flux.
• virial_stability_criterion — Virial-ratio margin against the heuristic threshold $r_v = 0.5$.
• virial_theorem — Total energy and virial ratio of magnetic, kinetic and thermal contributions.
• virial_thermal_energy (convention) — Thermal energy of a sampled plasma, $W_{th} = \tfrac{3}{2}\sum n T\,V$.
• volume_from_RZ_boundary — Plasma volume from a boundary polygon, mean-radius approximation.

Stability

Plasma stability, operational limits, and transport calculations. — 19 functions.

• ballooning_alpha_from_p_B_R (convention) — Normalised pressure gradient of the $s$-$\alpha$ ballooning model, without $q^2$.
• ballooning_stability_criterion (empirical) — Distance from the first ballooning stability boundary $\alpha_{crit} \approx 0.6\,s$.
• beta_N_from_beta_a_B0_Ip (convention) — Normalised beta evaluated literally as $\beta\,a\,B_0/I_p$.
• beta_pol_from_beta_tor — Poloidal beta from toroidal beta, $\beta_p = \beta_t\,q_{95}^2$.
• beta_stability_boundary (empirical) — Heuristic beta margin against $\beta_{N,crit} = 0.028\,q_{95}$.
• beta_tor_from_beta_pol — Toroidal beta from poloidal beta, $\beta_t = \beta_p/q_{95}^2$.
• c_s_from_Te_Ti_mi (convention) — Isothermal ion sound speed $c_s = \sqrt{(T_e + T_i)/m_i}$.
• collisionality_from_n_T_B_R (convention) — Electron collisionality figure $6.921\times10^{-18}\,n_e R_0/(T_e^2 B_t)$.
• empirical_li_qa (empirical) — Surveyed $(q_a, l_i)$ operating points from the JET disruption study.
• greenwald_density (empirical) (convention) — Greenwald density limit $n_G$.
• greenwald_fraction (convention) — Greenwald fraction $f_G = n_e/n_G$.
• kink_stability_criterion (empirical) — Heuristic kink margin against $\beta_{N,crit} = 2.8\,q_{95}$.
• li_from_qa_empirical (empirical) — Internal inductance at a given $q_a$ by interpolating the JET survey points.
• plasma_stability_margins (convention) — Beta, $q_{95}$ and density margins in one call.
• power_limit_from_beta — Energy-like figure $\beta_N B_0^2 V/(2\mu_0)$ labelled a power limit.
• power_limit_from_q — Expression $2\pi R_0 I_p/(\mu_0 q_{95})$ labelled a power limit.
• rhostar_from_Te_a_Bt (convention) — Electron gyroradius figure $\sqrt{T_e}\,a/B_t$ (as implemented).
• sawtooth_stability_criterion (empirical) — Heuristic sawtooth margin against $\beta_{p,crit} = 0.3\,(1 - q_0)$.
• v_alfven_from_B_n_mi — Alfven speed $v_A = B/\sqrt{\mu_0 n m_i}$.

Green

Green’s function calculations for plasma physics. — 16 functions.

• calculate_distance — Euclidean distance between $(r_1, z_1)$ and $(r_2, z_2)$ in the poloidal plane.
• complete_elliptic_integral_e (convention) — Complete elliptic integral of the second kind $E(m)$.
• complete_elliptic_integral_k (convention) — Complete elliptic integral of the first kind $K(m)$.
• elliptic_integral — Polynomial approximations of $K$ and $E$ for a ring source and observer points.
• green_br_bz (convention) — Field of a unit-current ring, $(B_r, B_z)$ at observer points (legacy elliptic path).
• green_br_bz_exact (convention) — $(B_r, B_z)$ per unit ring current, exact elliptic integrals, broadcasting.
• green_psi_exact (convention) — Poloidal flux per unit ring current, exact elliptic integrals.
• green_r (convention) — Poloidal flux per unit ring current at observer points (legacy elliptic path).
• greens_function_2d (convention) — Axisymmetric kernel $\sqrt{RR_0}\,K(m)$ between a field point and a ring source.
• greens_function_3d — Toroidal-angle-resolved variant of the $\sqrt{RR_0}\,K(m)$ kernel.
• greens_function_exact (convention) — Exact free-space axisymmetric Green’s function and its derivatives.
• greens_integral_2d — Line integral along $R$ of the 2-D kernel times a source density.
• greens_integral_3d — Line integral along $R$ of the 3-D kernel times a source density.
• mutual_inductance — Mutual inductance between two rectangular-cross-section ring coils.
• self_inductance — Self-inductance of a rectangular-cross-section ring coil.
• trapz_integral — Trapezoidal integral $\int y\,dx$, local copy for the Green kernels.

Atomic

Atomic equilibrium and line-radiation formulae backed by OPEN-ADAS ADF11. — 3 functions.

• fractional_abundances (convention) — Ionisation-equilibrium (coronal) fractional abundances from ACD and SCD tables.
• interpolate_adf11 (convention) — Interpolate every charge-state block of an ADF11 table at given $(n_e, T_e)$.
• line_cooling_coefficient (convention) — Equilibrium line-radiation cooling coefficient $L_{line}(n_e, T_e)$ of a species.

Statistics

Pure statistical kernels for residual and convergence diagnostics (issue #186). — 22 functions.

• bias_standard_error — Standard error of the mean of $n$ unit-variance samples, $1/\sqrt{n}$.
• chi_squared — Chi-square, $\sum_i (r_i/\sigma_i)^2$ over the finite terms.
• dynamic_range — Sample range, $\max - \min$ over the finite entries.
• fractional_rms_improvement — Fractional RMS improvement, $1 - \mathrm{RMS}(r)/\mathrm{RMS}(r_0)$.
• lag1_autocorrelation — Lag-1 autocorrelation of the finite entries, in the order given.
• linear_trend — Least-squares slope of $y$ against $x$, in units of $y$ per unit $x$.
• log10_decay_rate — Least-squares slope of $\log_{10}x$ against iteration index over the tail.
• median_absolute_deviation —

  Median absolute deviation, $\mathrm{median}(

  x - \mathrm{median}(x)

  )$.

• monotonic_fraction — Fraction of consecutive steps in which the sequence decreased.
• noise_band — Mean and population standard deviation of a reference (effect-free) sample.
• normalized_residual — Residuals in units of the fitted uncertainty, $z = r\,w/k$.
• outlier_fraction —

  Fraction of finite entries with $

  x_i

  > \mathrm{level}$.

• pearson_correlation — Pearson correlation of two series over their pairwise-finite samples.
• percentile_scale — A high percentile of |x| over the finite entries, an amplitude scale one anomalous sample cannot set.
• reduced_chi_squared — Reduced chi-square, $\chi^2/\nu$ per degree of freedom.
• relative_spread —

  Relative spread, $(\max - \min)/\max

  x

  $ over the finite entries.

• residual_bias — Mean of the finite entries, the systematic offset of a residual sample.
• rms — Root mean square, $\sqrt{\mathrm{mean}(x_i^2)}$, over the finite entries.
• robust_z_scores — Deviation from the median in robust sigma units, sample by sample.
• runs_test_z — Wald-Wolfowitz runs-test z-score for the sign sequence of a sample.
• sigma_threshold_crossing — First time outside the reference window where the signal leaves its noise band.
• sigma_unit_factor — Recover the units-of-fit factor $k$ from a fit’s own per-channel chi-square.

Magnetics

Magnetic-probe geometry shared by every forward model. — 2 functions.

• probe_axis — Direction cosines (c_R, c_Z) of a poloidal-field probe’s sensitive axis.
• project_poloidal_field — The component of (B_R, B_Z) a probe oriented at poloidal_angle reads.

Refreshing this snapshot

From a checkout of the develop branch, run:

python -m vaft.formula.catalog --output /path/to/vaft-gh/_data/formula_catalog.yml

The snapshot records the SHA-256 of every vaft/formula/*.py source file; documentation validation compares them when VAFT_REGISTRY_SOURCE points to the corresponding source checkout. The same text is available offline as vaft.formula.describe("<name>"), vaft.formula.search("<text>") and vaft.formula.list_formulas(category="<category>").