Formula reference: equilibrium

This page is generated from the docstrings of vaft/formula/equilibrium.py: 96 public functions. The category overview and notation come from the module docstring; every entry below is what vaft.formula.describe("equilibrium.<name>") prints. Back to the formula reference index.

Overview

This module provides functions for calculating various plasma equilibrium parameters including poloidal flux, toroidal flux, safety factor, current, energy, and geometry.

Functions

• alpha_heating_power_from_n_D_n_T_T_keV_V — 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 — 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 — Poloidal beta in the EFIT/OMFIT convention, normalized by the LCFS circumference.
• beta_poloidal_from_pressure_integral — Poloidal beta in the IMAS definition, from the pressure volume integral.
• beta_t_from_n_T_B — 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 — Heuristic bootstrap-current fraction $f_{BS}$.
• bremsstrahlung_power_density_from_T_e_p_Z_eff — Bremsstrahlung power density in the pressure form.
• bremsstrahlung_power_density_from_Z_eff_n_e_T_e — Maxwellian free-free (bremsstrahlung) power density from first principles.
• bremsstrahlung_radiation_power_from_z_eff_n_e_t_e — 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 — Energy confinement time as stored energy over loss power.
• confinement_time_from_engineering_parameters — Thermal energy confinement time from an engineering-parameter scaling law.
• coulomb_logarithm_from_n_T — Coulomb logarithm $\ln\Lambda$ for electron collisions above 10 eV.
• current_density_from_B — Toroidal current density from the radial derivative of a poloidal field.
• current_density_from_psi — Radial-derivative current-density estimate from a poloidal flux cut.
• current_drive_efficiency — 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 — 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 — Boundary elongation $\kappa$ from the extremal points of a contour.
• exact_volume_from_RZ_contour — 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 — Thermal energy from poloidal beta, $W_K = \tfrac{3}{2}\,\beta_p B_{pa}^2 V_p/(2\mu_0)$.
• kink_safety_factor — 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 — Surface loop voltage from the time series of boundary flux.
• loss_power_from_p_heat_dWdt_p_rad — Loss power $P_{loss} = P_{heat} - dW/dt - P_{rad}$.
• magnetic_energy_from_li_B_pa_V_p — 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 — 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 — Ion collisionality $\nu_*$ from a collision frequency.
• normalized_larmor_radius_from_M_T_a_Bt — Normalised ion gyroradius $\rho_* = \rho_i/a$ in SI inputs.
• normalized_plasma_current — Normalised plasma current $I_N = I_p/(a B_t)$ in MA/(m T).
• nu_star_from_n_T_B_R_epsilon_kappa_I — Normalised collisionality $\nu_*$ in the Verdoolaege engineering form.
• ohmic_heating_power_from_I_p_V_res — Ohmic heating power $P_{ohm} = I_pV_{res}$.
• omega_i_tau_E_from_B_tau_E_M — Ion-cyclotron-normalised confinement time $\Omega_i\tau_E$.
• peaking_factor — Profile peaking factor, central value over volume average.
• phi_from_Bphi — Toroidal flux $\Phi$ through a poloidal cross-section.
• poloidal_field_factor — Sauter Eq. 20 prefactor $k = \sigma_{R\varphi Z}\,\sigma_{B_p}/(2\pi)^{e_{B_p}}$.
• psi_from_RBtheta — Poloidal flux $\psi$ from a line integral of $R B_\theta$ across flux surfaces.
• psi_normalised — Normalised poloidal flux $\psi_N$.
• q_cyl_from_B_R_epsilon_kappa_I — Cylindrical safety factor in the Verdoolaege convention.
• q_from_phi — Safety factor $q$ as the flux derivative $d\Phi/d\psi$.
• q_from_rhoN — Safety factor from the toroidal-flux label $\rho_N(\psi_N)$.
• radial_magnetic_field_from_psi — Radial magnetic field $B_R$ from the poloidal flux map.
• rhoN_from_phi — Normalised toroidal-flux radius $\rho_N$.
• rhoN_from_qpsiN — Normalised toroidal-flux radius from the $q$ profile.
• rho_star_from_M_T_B_R_epsilon — Normalised ion gyroradius $\rho_*$ in the Verdoolaege engineering form.
• rho_tor_from_phi —

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

  \Phi

  /(\pi

  B_0

  )}$.

• shear_from_r_q — Magnetic shear $s$ of the safety-factor profile.
• spitzer_resistivity_from_T_e_Z_eff_ln_Lambda — Spitzer parallel resistivity $\eta_\parallel$.
• stored_energy_from_beta_V — Stored energy from toroidal beta, $W = \beta B_0^2 V/(2\mu_0)$.
• stored_energy_from_p_V — Stored energy as pressure times volume, $W = pV$.
• surface_poloidal_flux_from_psi_boundary — Total poloidal flux at the plasma surface, $\Phi_{surface} = 2\pi\psi_b$.
• toroidal_flux_from_q_psi — Cumulative toroidal flux $\Phi(\psi)$ from the $q$ profile on a full-weber grid.
• triangularity_from_RZ_boundary — Boundary triangularity $\delta$ from the midplane intersection.
• verify_kadomtsev_constraint — Reconstruct the Kadomtsev constraint value from dimensionless indices.
• vertical_magnetic_field_from_psi — Vertical magnetic field $B_Z$ from the poloidal flux map.
• virial_D0_boundary_from_bp_li_eK — Boundary Shafranov shift $D_0(b)$ from $\beta_p$, $l_i$ and elongation.
• virial_S1_approx — Leading-order value of the first Shafranov integral, $S_1 = 2$.
• virial_S2_approx_from_D0_a_R0 — Analytic approximation of the second Shafranov integral for an elongated boundary.
• virial_S3_approx_from_eK_d — Analytic approximation of the third Shafranov integral for an elongated boundary.
• virial_beta_p_from_S_alpha_mu — 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 — 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 — 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 — 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 — 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 — 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.

alpha_heating_power_from_n_D_n_T_T_keV_V

alpha_heating_power_from_n_D_n_T_T_keV_V(n_D_1e19, n_T_1e19, T_keV, V_m3) — aliases alpha_heating_power

Empirical fit.

D-T alpha heating power with the rough $\langle\sigma v\rangle \propto T^2$ fit.

Assumptions.

Flat profiles (the product of densities is taken at one temperature over the whole volume); all alpha energy deposited in the plasma.

Validity.

Empirical fit. The quadratic $\langle\sigma v\rangle$ is Wesson’s interpolation of the D-T reactivity, accurate to ~10 % for $10 < T < 20$ keV [1]; outside that window use the Bosch-Hale parametrisation [2].

Limitations.

Irrelevant for a deuterium-only device such as VEST; kept for power-balance completeness. Tracked in #360 (Bosch-Hale replacement).

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 1.3.
2. H.-S. Bosch and G. M. Hale, Nucl. Fusion 32 (1992) 611, Table VII.

approximated_diamagnetism_from_B_pa_B_tv_R0_delta_phi

approximated_diamagnetism_from_B_pa_B_tv_R0_delta_phi(B_pa, B_tv, R0, delta_phi, V_p)

Convention-sensitive.

Diamagnetic parameter from the vacuum toroidal field and flux change.

Convention.

Numerically identical to virial_muihat_from_Bt_R0_dphi; kept under the name used by the VFIT-era analysis. Same sign caveat on delta_phi.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 2.

aspect_ratio_from_a_R

aspect_ratio_from_a_R(a, R)

Aspect ratio $A = R/a = 1/\varepsilon$.

Notes.

Not to be confused with the elongation $\kappa$.

auxiliary_heating_power

auxiliary_heating_power(P_aux, eta_CD)

Split auxiliary power into heating and current-drive parts.

Limitations.

A bookkeeping split with the same unsourced normalisation as eta_CD; the two parts always sum to P_aux.

beta_normal_from_beta_tor

beta_normal_from_beta_tor(beta_tor, a, B0, Ip)

Normalized beta (Troyon) from toroidal beta, minor radius, field and current.

References.

1. F. Troyon et al., Plasma Phys. Control. Fusion 26 (1984) 209.
2. IMAS Data Dictionary, equilibrium.time_slice[:].global_quantities.beta_normal.

beta_poloidal_from_circumference

beta_poloidal_from_circumference(p_average, Ip, length_pol)

Convention-sensitive.

Poloidal beta in the EFIT/OMFIT convention, normalized by the LCFS circumference.

Convention.

Not the IMAS DD’s beta_pol, and not an estimate of it: this normalizes the volume-averaged pressure by the poloidal field implied by the LCFS circumference rather than by R_0 mu_0 Ip^2. The two differ by the geometric factor R_0 L_pol^2 / (2 V) – 26% on the packaged kineticEfit reference, where this form reproduces the stored value to 0.1% and the DD form does not. It exists so the database summary can keep reporting what OMFIT reported; global_quantities.beta_pol stays DD-normative (see beta_poloidal_from_pressure_integral and issue #318, which owns the sensitivity study of the two).

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh, A. G. Kellman and W. Pfeiffer, Nucl. Fusion 25 (1985) 1611 (EFIT definitions).

beta_poloidal_from_pressure_integral

beta_poloidal_from_pressure_integral(pressure_integral, R0, Ip)

Convention-sensitive.

Poloidal beta in the IMAS definition, from the pressure volume integral.

Convention.

This is the DD-normative beta_pol, normalized by R_0 mu_0 Ip^2. The EFIT/OMFIT circumference form is a different definition; see beta_poloidal_from_circumference.

References.

1. IMAS Data Dictionary, equilibrium.time_slice[:].global_quantities.beta_pol.
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Ch. 3, Equilibrium (definition of beta).

beta_t_from_n_T_B

beta_t_from_n_T_B(n_m3, T_eV, B_t_T, output='percent') — aliases calc_beta_t

Convention-sensitive.

Toroidal beta from density, temperature and field.

Raises.

ValueError For non-finite or non-positive input, or an unknown output.

Convention.

$8.05\times10^{-23} = 100\times2\mu_0\times2e$: the total pressure is taken as $2n_eT$ (equal electron and ion temperatures, $n_i = n_e$), and the default output is a percentage. Verdoolaege’s ITER example is reproduced by construction.

References.

1. G. Verdoolaege et al., Nucl. Fusion 61 (2021) 076006, Sec. 2.
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.5.

beta_toroidal_from_p_B0

beta_toroidal_from_p_B0(p_average, B0)

Toroidal beta from the volume-averaged pressure and the vacuum field.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Ch. 3, Equilibrium (definition of beta).
2. IMAS Data Dictionary, equilibrium.time_slice[:].global_quantities.beta_tor.

bootstrap_current_fraction

bootstrap_current_fraction(n_e, T_e_keV, R0, a, q_95)

Empirical fit.

Heuristic bootstrap-current fraction $f_{BS}$.

Physical interpretation.

Neoclassical bootstrap current scales as $\epsilon^{1/2}\beta_p$; the inner expression is a crude $\beta_p$ estimate from an $n T$ pressure and the cylindrical $q$-$I_p$ relation, and the outer square root is a fit.

Validity.

Empirical fit. Labelled “ITER scaling for bootstrap current” in the original VAFT source without a publication or unit system for the coefficients 0.3 and 0.4. The physics it approximates is the $\sqrt{\epsilon}\,\beta_p$ scaling of Peeters [1] and Wesson [2].

Limitations.

Unsourced coefficients and unstated density unit; the $\beta_p$ estimate ignores profile shape and the ion pressure. Tracked in #361.

References.

1. A. G. Peeters, Plasma Phys. Control. Fusion 42 (2000) B231, Sec. 2.
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 4.9 (bootstrap current).

bremsstrahlung_power_density_from_T_e_p_Z_eff

bremsstrahlung_power_density_from_T_e_p_Z_eff(T_e, p, Z_eff=2.0)

Convention-sensitive.

Bremsstrahlung power density in the pressure form.

which is the NRL $P_{br} = 1.69\times10^{-38}\,Z_{\mathrm{eff}}n_e^2\sqrt{T_e}$ rewritten with $n_e = p/(2T)$ (equal electron and ion pressure).

Convention.

Pressure is converted to bar ($10^5$ Pa) and temperature to keV internally; the prefactor 0.052 MW/m^3 follows exactly from the NRL coefficient and $p = 2n_eT$, so a pressure that already includes fast ions or unequal $T_i$ overestimates $n_e$.

Assumptions.

Maxwellian electrons, Gaunt factor 1, $n_i = n_e$ and $T_i = T_e$; no recombination or line radiation.

References.

1. NRL Plasma Formulary (2019), p. 58 (bremsstrahlung).
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Ch. 4 (radiation losses).

bremsstrahlung_power_density_from_Z_eff_n_e_T_e

bremsstrahlung_power_density_from_Z_eff_n_e_T_e(n_e_m3, T_e_eV, Z_eff=2.0)

Convention-sensitive.

Maxwellian free-free (bremsstrahlung) power density from first principles.

Convention.

The prefactor evaluates to $4.2\times10^{-29}$ W m^3 J^-1/2, equal to the NRL $1.69\times10^{-38}\,n_e^2\sqrt{T_{\mathrm{eV}}}$ used by bremsstrahlung_radiation_power_from_z_eff_n_e_t_e; the two agree to 1 %.

Assumptions.

Maxwellian, non-relativistic electrons; Gaunt factor 1; $Z_{\mathrm{eff}}$ absorbs $\sum_Z Z^2 n_Z / n_e$.

Validity.

$T_e \ll m_ec^2$; relativistic corrections exceed 10 % above ~50 keV.

References.

1. G. B. Rybicki and A. P. Lightman, Radiative Processes in Astrophysics, Wiley (1979), Eq. (5.15b).
2. I. H. Hutchinson, Principles of Plasma Diagnostics, 2nd ed., Cambridge University Press (2002), Sec. 5.3.

bremsstrahlung_radiation_power_from_z_eff_n_e_t_e

bremsstrahlung_radiation_power_from_z_eff_n_e_t_e(Z_eff, n_e, T_e_eV)

Convention-sensitive.

Bremsstrahlung power density, NRL engineering form.

Convention.

The NRL Formulary $1.69\times10^{-32}\,n_e T_e^{1/2}\sum Z^2n_Z$ W/cm^3 with cm^-3 densities, converted to SI, and $\sum Z^2 n_Z = Z_{\mathrm{eff}}n_e$.

Assumptions.

Maxwellian electrons, Gaunt factor 1.

References.

1. NRL Plasma Formulary (2019), p. 58.

calc_inverse_aspect_ratio

calc_inverse_aspect_ratio(a_m, R_geo_m)

Inverse aspect ratio $\varepsilon = a/R_{geo}$ with input validation.

Raises.

ValueError For non-finite or non-positive input.

See Also.

inverse_aspect_ratio_from_a_R : the unvalidated form.

check_kadomtsev_constraint

check_kadomtsev_constraint(alpha_I, alpha_B, alpha_P, alpha_n, alpha_R, tol=1e-06)

Whether engineering exponents satisfy the Kadomtsev constraint within a tolerance.

with $\alpha_K$ from kadomtsev_constraint_from_engineering_exponents.

Limitations.

The default tolerance is far tighter than any published fit satisfies (ITER89P misses by 0.15); pass a physically motivated tol. verify_kadomtsev_constraint evaluates a different expression from the dimensionless indices; the two are tracked in #351.

References.

1. B. B. Kadomtsev, Sov. J. Plasma Phys. 1 (1975) 295.

confinement_factor_ITER89P

confinement_factor_ITER89P(tau_E_exp, tau_E_ITER89P)

Confinement enhancement factor $H_{89}$ relative to ITER89P.

References.

1. P. N. Yushmanov et al., Nucl. Fusion 30 (1990) 1999.

confinement_time_from_P_loss_W_th

confinement_time_from_P_loss_W_th(P_loss, W_th)

Convention-sensitive.

Energy confinement time as stored energy over loss power.

Convention.

Thermal energy over loss power ($P_{heat} - dW/dt$, with or without radiation subtracted depending on the database); the ITER definition of $\tau_{E,th}$ needs $P_{loss}$ from loss_power_from_p_heat_dWdt_p_rad.

References.

1. ITER Physics Expert Groups, Nucl. Fusion 39 (1999) 2175, Ch. 2, Sec. 3.

confinement_time_from_engineering_parameters

confinement_time_from_engineering_parameters(I_p, B_t, P_loss, n_e, M, R, epsilon, kappa, scaling='ITER89P', input_density_definition='line_avg', line_to_volume_factor=None)

Empirical fit. Convention-sensitive.

Thermal energy confinement time from an engineering-parameter scaling law.

with the product running only over the variables the selected scaling declares, in the engineering units MA, T, MW, $10^{19}$ m^-3, amu and m.

Raises.

ValueError Unknown scaling, non-positive input, or a density-definition mismatch without line_to_volume_factor.

Convention.

Strict SI in; the SI-to-engineering conversions ($\times10^{-6}$ for current and power, $\times10^{-19}$ for density) happen inside, so pre-scaled inputs are wrong by orders of magnitude. Every prefactor $C$ is tied to that unit convention: the NSTX fits were converted from the papers’ SI-like form, and the density definition each scaling expects is declared in _SCALING_COEFS. Variables a scaling does not use are neither range-checked nor raised to any power.

Validity.

Empirical fit. Multi-machine regressions of the ITER L-mode (ITER89P [1]) and ELMy H-mode (IPB98(y,2) [2]) databases, the NSTX H- and L-mode fits of Kaye [3], and the spherical-tokamak multi-machine H-mode fit of Kurskiev [4]; each is valid over its database’s parameter range and the ST fits are the only ones that include low-aspect-ratio data.

Limitations.

Extrapolation to VEST (small size, low field) lies outside every database range except in part the ST fit; the Kurskiev regression’s absorbed-power dependence is mapped onto P_loss as supplied.

References.

1. P. N. Yushmanov et al., Nucl. Fusion 30 (1990) 1999 (ITER89P).
2. ITER Physics Expert Groups, Nucl. Fusion 39 (1999) 2175, Ch. 2, Eq. (20) (IPB98(y,2)).
3. S. M. Kaye et al., Nucl. Fusion 46 (2006) 848, Table 2.
4. G. S. Kurskiev et al., Nucl. Fusion 62 (2022) 016011.

coulomb_logarithm_from_n_T

coulomb_logarithm_from_n_T(n_m3, T_eV) — aliases coulomb_logarithm

Convention-sensitive.

Coulomb logarithm $\ln\Lambda$ for electron collisions above 10 eV.

Raises.

ValueError For non-finite or non-positive input.

Convention.

The NRL Formulary electron-electron/electron-ion form $24 - \ln(n_e^{1/2} T_e^{-1})$ with $n_e$ in cm^-3, converted to m^-3 ($24 + \ln 10^3 = 30.9$); also the convention of the Verdoolaege confinement-database analysis.

Validity.

$T_e > 10$ eV; below that the NRL low-temperature branch applies.

References.

1. NRL Plasma Formulary (2019), p. 34 (Coulomb logarithm).
2. G. Verdoolaege et al., Nucl. Fusion 61 (2021) 076006, Sec. 2.

current_density_from_B

current_density_from_B(B, R)

Convention-sensitive.

Toroidal current density from the radial derivative of a poloidal field.

the slab form of Ampere’s law $\mu_0 j_\varphi = \partial B_Z/\partial R - \partial B_R/\partial Z$ with the second term dropped.

Convention.

Sign follows the COCOS $\sigma_{B_p}$ of the supplied component: with the midplane $B_Z$ of a standard equilibrium the result has the sign of the plasma current. The $\partial B_R/\partial Z$ contribution is neglected, so the answer is exact only on the midplane of an up-down symmetric equilibrium.

Numerical notes.

numpy.gradient along the single supplied axis (second-order interior, first-order ends); pass a 1-D slice, not a 2-D map.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.1 (Ampere’s law in the tokamak).

current_density_from_psi

current_density_from_psi(psi, R)

Convention-sensitive.

Radial-derivative current-density estimate from a poloidal flux cut.

Convention.

Hard-codes the historical $k=-1$ (weber-per-radian, COCOS 2/3/6/7) prefactor inline instead of going through poloidal_field_factor, so unlike the $B_R$/$B_Z$ helpers it cannot be told the COCOS. Tracked in #355.

Limitations.

$-(1/R)\,d\psi/dR$ is $B_Z$, so this expression is $B_Z/\mu_0$: a current per unit length [A/m], not the toroidal current density $j_\varphi = -\Delta^*\psi /(\mu_0 R)$ [A/m^2], which needs second derivatives. Kept unchanged for compatibility; use profiles_2d.j_tor or current_density_from_B with $B_Z$ for a density. Tracked in #355.

Numerical notes.

numpy.gradient along the single supplied axis; pass a 1-D slice.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.3 (Grad-Shafranov equation, $\mu_0 R j_\varphi = -\Delta^*\psi$).

current_drive_efficiency

current_drive_efficiency(n_e, T_e_keV, Z_eff=1.0)

Empirical fit.

Heuristic lower-hybrid current-drive efficiency $\eta_{CD}$.

Physical interpretation.

Lower-hybrid current drive becomes more efficient at higher temperature and lower $Z_{\mathrm{eff}}$ because the wave-driven fast electrons slow down on a hotter, cleaner background; the density factor here is unusual (the standard figure of merit $\eta = n_e I_{CD} R / P$ divides by density).

Validity.

Empirical fit. Labelled “ITER scaling for lower hybrid current drive” in the original VAFT source; no publication, dataset or unit system for the coefficient 0.3 was recorded, so the number is a placeholder. The theory of the efficiency and its $T_e/Z_{\mathrm{eff}}$ dependence is Fisch [1].

Limitations.

Unsourced coefficient and unstated density unit; treat the result as qualitative. Tracked in #361.

References.

1. N. J. Fisch, Rev. Mod. Phys. 59 (1987) 175, Sec. VI (lower-hybrid current-drive efficiency).

current_limit_from_beta

current_limit_from_beta(beta_N, a, B0)

Current figure obtained by substituting $\beta_N$ for $q$ in the cylindrical relation.

Limitations.

Dimensionally the cylindrical-$q$ formula with $\beta_N$ in the place of $q$; no derivation or source records what this is meant to bound, and the result depends on the units chosen for $\beta_N$. Kept for compatibility; prefer vaft.formula.stability.beta_N_from_beta_a_B0_Ip and the Troyon limit. Tracked in #362.

References.

1. F. Troyon et al., Plasma Phys. Control. Fusion 26 (1984) 209 (the $\beta_N$ limit this appears to invert).

current_limit_from_q

current_limit_from_q(q_95, a, B0)

Plasma current at a prescribed edge safety factor, cylindrical approximation.

the inversion of $q_{cyl} = 2\pi a^2 B_0/(\mu_0 R\,I_p)\times R/R$ for a circular cross-section written per unit major radius.

Assumptions.

Circular, large-aspect-ratio cylinder with $q_{95}$ standing in for the cylindrical $q_a$.

Limitations.

As written the expression lacks the $1/R$ of the cylindrical safety factor $q = 2\pi a^2 B_0/(\mu_0 R I_p)$ and therefore returns $I_p R$ [A m], not a current; divide by $R$ for amperes. Elongation is ignored. Tracked in #362.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.4 (cylindrical safety factor).

cyclotron_synchrotron_power_density_scaling_from_n_e_B_t_T_e

cyclotron_synchrotron_power_density_scaling_from_n_e_B_t_T_e(n_e_m3, B_t_T, T_e_eV)

Classical electron-cyclotron emission power density, no reabsorption.

Physical interpretation.

Total single-particle cyclotron radiation of a non-relativistic Maxwellian; the plasma is optically thick at the low harmonics, so the net loss is a small fraction of this, set by wall reflectivity and $\beta$ (Trubnikov).

Validity.

Non-relativistic electrons; an upper bound on the loss, intended as a start-up loss-channel estimate rather than a radiation-transport result.

Limitations.

Ignores reabsorption and wall reflection, which reduce the net loss by one to two orders of magnitude in a tokamak.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Ch. 4 (cyclotron radiation).
2. B. A. Trubnikov, in Reviews of Plasma Physics, Vol. 7, Consultants Bureau (1979), p. 345.

cylindrical_safety_factor_from_R_B_epsilon_I_f_kappa_delta

cylindrical_safety_factor_from_R_B_epsilon_I_f_kappa_delta(R, B, epsilon, I, f_kappa_delta)

Convention-sensitive.

Cylindrical safety factor with a shape function.

Convention.

$2\pi/\mu_0 = 5\times10^6$, so with SI current this is the ITER Physics Basis $q_{cyl}$ once $f = 1/\kappa$; the shape function is left to the caller because the ITER-89P and IPB98 databases used different $\kappa$ definitions. Unlike the flux-derivative $q$ it never changes sign.

References.

1. ITER Physics Expert Groups, Nucl. Fusion 39 (1999) 2175, Ch. 2, Sec. 3 (definition of $q_{cyl}$).
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.4.

dimensionless_scaling_coeffs_from_engineering_scaling_coeffs

dimensionless_scaling_coeffs_from_engineering_scaling_coeffs(a_I, a_B, a_P, a_n, a_M, a_R, a_eps, a_kappa)

Dimensionless scaling indices $(\mu_\rho, \mu_\beta, \mu_\nu)$ from engineering exponents.

with, for $\alpha_L = \alpha_R + \alpha_I$, $\alpha_B^* = \alpha_B + \alpha_I$ and $D = 1 + \alpha_P$,

Assumptions.

Constant safety factor, $I_p \propto a^2B/R$, so current is absorbed into the size and field indices; temperature eliminated through $P = W/\tau_E$.

Limitations.

Returns None instead of a tuple when $1 + \alpha_P$ vanishes (tracked in #352); indices are rounded to three decimals.

References.

1. T. C. Luce, C. C. Petty and J. G. Cordey, Plasma Phys. Control. Fusion 50 (2008) 043001, Sec. 3 (engineering to dimensionless exponent transformation).
2. B. B. Kadomtsev, Sov. J. Plasma Phys. 1 (1975) 295.

eK_from_K

eK_from_K(K)

Elongation parameter $e_K$ of the virial relations.

Physical interpretation.

The ellipticity measure in which the Martynov-Pustovitov virial approximations are linear.

References.

1. A. A. Martynov and V. D. Pustovitov, Phys. Plasmas 31 (2024), “Virial relations for elongated plasmas in tokamaks”, definition preceding Eq. (21).

ec_heating_power_from_I_ec_V_ec

ec_heating_power_from_I_ec_V_ec(I_ec, V_ec)

Electron-cyclotron launched power $P_{ec} = I_{ec}V_{ec}$.

Limitations.

Gyrotron electrical power, not RF power (efficiency ~30-50 %) and not the power absorbed by the plasma.

elongation_from_RZ_boundary

elongation_from_RZ_boundary(R, Z)

Convention-sensitive.

Boundary elongation $\kappa$ from the extremal points of a contour.

Convention.

The IMAS boundary.elongation definition (half-height over half-width of the bounding box), not an area-based or flux-surface-averaged elongation.

Limitations.

A single-point or degenerate contour divides by zero; no validation.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.1.
2. IMAS Data Dictionary, equilibrium.time_slice[:].boundary.elongation.

exact_volume_from_RZ_contour

exact_volume_from_RZ_contour(R, Z)

Convention-sensitive.

Plasma volume from a closed $(R, Z)$ contour by Green’s theorem.

exact for the solid of revolution swept by a closed poloidal contour, with no mean-radius approximation.

Convention.

Orientation-agnostic: the sign of the contour integral follows the traversal direction and the magnitude is returned. The contour is closed automatically when its first and last points differ.

Limitations.

Unlike volume_from_RZ_boundary, which factors the integral as $2\pi A_{\mathrm{poly}}\bar R$ with $\bar R = \mathrm{mean}(R)$, this evaluates the contour integral itself. On VEST flux surfaces the two differ by up to ~6 % at the plasma edge, where the $\bar R$ factorisation is weakest. Use this one whenever the volume is a reported quantity rather than an intermediate.

Numerical notes.

Trapezoidal rule on $R^2$ between successive vertices, second-order in the vertex spacing.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.1.

heating_power_from_p_ohm_p_aux

heating_power_from_p_ohm_p_aux(P_ohm, P_aux)

Total heating power $P_{heat} = P_{ohm} + P_{aux}$.

inductive_voltage_from_dW_magdt_I_p

inductive_voltage_from_dW_magdt_I_p(dW_magdt, I_p)

Inductive voltage from the rate of change of magnetic energy.

Assumptions.

Exact for $W = \tfrac{1}{2}LI^2$ with constant $L$; when the inductance changes (current-profile evolution) the full inductive voltage is $d(LI)/dt$ and this expression captures only part of it.

inverse_aspect_ratio_from_a_R

inverse_aspect_ratio_from_a_R(a, R)

Inverse aspect ratio $\varepsilon = a/R$.

See Also.

calc_inverse_aspect_ratio : the same ratio with positivity validation.

kadomtsev_constraint_from_engineering_exponents

kadomtsev_constraint_from_engineering_exponents(alpha_I, alpha_B, alpha_P, alpha_n, alpha_R)

Residual of the Kadomtsev high-beta constraint on engineering exponents.

for $\tau_E \propto I^{\alpha_I}B^{\alpha_B}P^{\alpha_P}n^{\alpha_n}R^{\alpha_R}$; $\alpha_K = 0$ when the scaling is expressible in the three dimensionless parameters $\rho_$, $\beta$, $\nu_$ alone.

Raises.

ValueError For non-finite input.

Physical interpretation.

Dimensional analysis of the Vlasov-Maxwell system: only three of the engineering variables are independent once $\rho_$, $\beta$ and $\nu_$ are fixed at constant geometry. ITER89P gives $\alpha_K = -0.15$ and IPB98(y,2) gives $-0.01$.

References.

1. B. B. Kadomtsev, Sov. J. Plasma Phys. 1 (1975) 295.
2. ITER Physics Expert Groups, Nucl. Fusion 39 (1999) 2175, Ch. 2, Sec. 6.2 (Kadomtsev constraint).
3. G. Verdoolaege et al., Nucl. Fusion 61 (2021) 076006.

kinetic_energy_from_beta_p_B_pa_V_p

kinetic_energy_from_beta_p_B_pa_V_p(beta_p, B_pa, V_p)

Convention-sensitive.

Thermal energy from poloidal beta, $W_K = \tfrac{3}{2}\,\beta_p B_{pa}^2 V_p/(2\mu_0)$.

Convention.

$B_{pa}$ is the poloidal field averaged over the boundary contour of length $L_p$, the EFIT/Lao normalisation of $\beta_p$; the $3/2$ converts $pV$ to the ideal-gas thermal energy.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 2 (definitions of $\beta_p$ and $B_{pa}$).

kink_safety_factor

kink_safety_factor(R, a, kappa, Ip, Bt, type_)

Convention-sensitive.

Kink safety factor $q_*$ with the Freidberg beta and current limits.

with $g = 1$ ('circular'), $g = 1 + \tfrac{4}{\pi^2}(\kappa^2-1)$ ('conventional') or $g = \tfrac{1}{2}(1+\kappa^2)$ ('ST'), plus the matching Troyon-type $\beta$ limits and the current at $q_{\mathrm{kink}} = q_{\min}$.

Convention.

$\beta$ limits are fractions, not percent, and are given in Freidberg’s $\epsilon$-scaled form ($\beta_{\max} = 0.072\,\tfrac{1+\kappa^2}{2}\, \epsilon$ for the ST branch, $\pi^2\kappa\epsilon/16q^2$ for the conventional one). $\mu_0$ is hard-coded as $4\pi\times10^{-7}$.

Validity.

Freidberg’s reduced-MHD estimates for external kink and pressure-driven limits; order-of-magnitude design numbers, not a stability code result.

References.

1. J. P. Freidberg, Plasma Physics and Fusion Energy, Cambridge University Press (2007), Ch. 13, Eq. (13.158) and the surrounding kink and Troyon limit discussion.
2. F. Troyon et al., Plasma Phys. Control. Fusion 26 (1984) 209.

li_3_from_Bp2_volume_integral

li_3_from_Bp2_volume_integral(Bp2_dV, Ip, R0)

Internal inductance in the IMAS li_3 definition, from the poloidal-field energy.

The same quantity OMFIT reports as li_(3)_IMAS.

References.

1. IMAS Data Dictionary, equilibrium.time_slice[:].global_quantities.li_3.
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Ch. 3, Equilibrium (internal inductance).

line_to_volume_avg_density

line_to_volume_avg_density(n_line_m3, factor=0.88)

Volume-averaged density from a line average with a fixed profile factor.

Raises.

ValueError For non-finite or non-positive input.

Assumptions.

A moderately peaked density profile; 0.88 is the ITPA workflow value for H-mode-like profiles and is not a measurement.

References.

1. G. Verdoolaege et al., Nucl. Fusion 61 (2021) 076006, Sec. 2.

loop_voltage_from_total_flux

loop_voltage_from_total_flux(time_slice, psi_boundary)

Convention-sensitive.

Surface loop voltage from the time series of boundary flux.

Convention.

Assumes psi_boundary per radian, as surface_poloidal_flux_from_psi_boundary does; a full-weber IMAS flux gives a voltage $2\pi$ too large. The sign is that of $d\psi_b/dt$ in the supplied COCOS, so a discharge with positive current and the usual $\sigma_{B_p}$ shows negative $V_{loop}$ during ramp-up. Tracked in #354.

Physical interpretation.

Sum of resistive and inductive voltage at the last closed flux surface, the quantity a flux loop on the boundary would read.

Numerical notes.

numpy.gradient in time (second-order interior, first-order ends); noisy $\psi_b$ reconstructions need smoothing first.

References.

1. S. Ejima et al., Nucl. Fusion 22 (1982) 1313, Sec. 2.

loss_power_from_p_heat_dWdt_p_rad

loss_power_from_p_heat_dWdt_p_rad(P_heat, dWdt, p_rad)

Convention-sensitive.

Loss power $P_{loss} = P_{heat} - dW/dt - P_{rad}$.

Convention.

With p_rad = 0 this is the ITER-database $P_L$ that the confinement scalings are fitted to (radiation counted as a loss); with the core radiation subtracted it is the conducted-plus-convected loss to the boundary. Use the same choice as the scaling being compared against.

References.

1. ITER Physics Expert Groups, Nucl. Fusion 39 (1999) 2175, Ch. 2, Sec. 3.

magnetic_energy_from_li_B_pa_V_p

magnetic_energy_from_li_B_pa_V_p(li, B_pa, V_p)

Convention-sensitive.

Poloidal magnetic energy from the internal inductance, $W_M = l_i B_{pa}^2 V_p/(2\mu_0)$.

Convention.

The Lao/EFIT $l_i$ (volume average of $B_p^2$ over $B_{pa}^2$), which is neither the IMAS $l_{i,3}$ nor the large-aspect-ratio $l_i = \langle B_p^2 \rangle/B_p(a)^2$; each differs by its normalising field.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 2.

nbi_heating_power_from_I_nbi_V_nbi

nbi_heating_power_from_I_nbi_V_nbi(I_nbi, V_nbi)

Neutral-beam injected power $P_{nbi} = I_{nbi}V_{nbi}$.

Limitations.

Injected, not absorbed: neutralisation efficiency, duct losses and shine-through are not subtracted.

normalize_psi

normalize_psi(*args, **kw)

Deprecated.

Deprecated: use psi_normalised.

Kept for backwards compatibility; emits a DeprecationWarning and forwards every argument unchanged.

See Also.

psi_normalised

normalized_collisionality_from_a_n_q_epsilon_T

normalized_collisionality_from_a_n_q_epsilon_T(a, n, q, epsilon, T_eV, C=1.0)

Convention-sensitive.

Collisionality scaling form $\nu_* \propto a\,n\,q/(\varepsilon^{5/2}T^2)$.

which is the Sauter form $\nu_* = 6.921\times10^{-18}\,qRn\ln\Lambda/ (T^2\varepsilon^{3/2})$ with $R = a/\varepsilon$ and $C = 6.921\times10^{-18} \ln\Lambda$ (electrons; times $Z^4$ for ions).

Raises.

ValueError For non-positive epsilon or T_eV.

Convention.

With C=1 the number is not $\nu_*$ but proportional to it; supply $C = 6.921\times10^{-18}\ln\Lambda$ (with $n$ in m^-3 and $T$ in eV) for Sauter’s electron collisionality. Tracked with the other two definitions in #353.

References.

1. O. Sauter, C. Angioni and Y. R. Lin-Liu, Phys. Plasmas 6 (1999) 2834, Eq. (18b).

normalized_collisionality_from_nu_ii_T_i_M_i_R_a_q

normalized_collisionality_from_nu_ii_T_i_M_i_R_a_q(nu_ii, T_i_eV, M_i, R, a, q)

Convention-sensitive.

Ion collisionality $\nu_*$ from a collision frequency.

the ratio of the effective detrapping frequency to the bounce frequency, with $v_{th,i} = \sqrt{eT_i/M_i}$.

Convention.

Thermal speed $\sqrt{T/m}$ (no factor 2) and the collision frequency supplied by the caller; with Sauter’s $\nu_{ii}$ this is Sauter Eq. (18b) without its numeric prefactor. Two other $\nu_*$ definitions live in this package (normalized_collisionality_from_a_n_q_epsilon_T and nu_star_from_n_T_B_R_epsilon_kappa_I); tracked in #353.

Physical interpretation.

$\nu_* \ll 1$ is the banana (collisionless) regime, $\nu_* \gg \varepsilon^{-3/2}$ the Pfirsch-Schluter regime.

References.

1. O. Sauter, C. Angioni and Y. R. Lin-Liu, Phys. Plasmas 6 (1999) 2834, Eq. (18b).
2. F. L. Hinton and R. D. Hazeltine, Rev. Mod. Phys. 48 (1976) 239, Sec. IV (collisionality regimes).

normalized_larmor_radius_from_M_T_a_Bt

normalized_larmor_radius_from_M_T_a_Bt(M, T, a, Bt)

Convention-sensitive.

Normalised ion gyroradius $\rho_* = \rho_i/a$ in SI inputs.

with $v_{th} = \sqrt{2T_i/m_i}$ and $T_i$ in eV.

Convention.

Thermal speed $\sqrt{2T/m}$ and the toroidal field, normalised by the minor radius: the ITER Physics Basis definition. Differs from rho_star_from_M_T_B_R_epsilon (mass in amu, normalised by $R\varepsilon$ with a rounded prefactor) only in input units, and from vaft.formula.stability.rhostar_from_Te_a_Bt in substance; the three definitions are tracked in #353.

References.

1. ITER Physics Expert Groups, Nucl. Fusion 39 (1999) 2175, Ch. 2, Sec. 6 (dimensionless parameters).

normalized_plasma_current

normalized_plasma_current(Ip, R, a, Bt)

Convention-sensitive.

Normalised plasma current $I_N = I_p/(a B_t)$ in MA/(m T).

Convention.

SI current in, engineering-unit ratio out: the same $I_N$ that normalises $\beta_N = \beta_t[\%]/I_N$ and that the ST beta-limit literature plots against.

References.

1. J. E. Menard et al., Phys. Plasmas 23 (2016) 072508, https://doi.org/10.1063/1.4959808, Sec. II.
2. F. Troyon et al., Plasma Phys. Control. Fusion 26 (1984) 209.

nu_star_from_n_T_B_R_epsilon_kappa_I

nu_star_from_n_T_B_R_epsilon_kappa_I(n_m3, T_eV, B_t_T, R_geo_m, epsilon, kappa_a, I_p_A, ln_lambda=None) — aliases calc_nu_star

Convention-sensitive.

Normalised collisionality $\nu_*$ in the Verdoolaege engineering form.

Raises.

ValueError For non-finite or non-positive input.

Convention.

Sauter’s $\nu_* = 6.921\times10^{-18}\,qRn\ln\Lambda/(T^2\varepsilon^{3/2})$ with $q = q_{cyl}$ substituted gives $3.46\times10^{-11}$ in front; the $5\times10^{-11}$ used here is Verdoolaege’s database convention and is 1.45 times larger, so values are comparable only within one convention. Tracked with the other $\nu_*$ definitions in #353.

References.

1. G. Verdoolaege et al., Nucl. Fusion 61 (2021) 076006, Sec. 2.
2. O. Sauter, C. Angioni and Y. R. Lin-Liu, Phys. Plasmas 6 (1999) 2834, Eq. (18b).

ohmic_heating_power_from_I_p_V_res

ohmic_heating_power_from_I_p_V_res(I_p, V_res)

Convention-sensitive.

Ohmic heating power $P_{ohm} = I_pV_{res}$.

Convention.

With the surface loop voltage in place of $V_{res}$ the product also counts the inductive power $L\,dI_p/dt$ and the change of internal inductance, so it is a resistive-heating estimate only when $dI_p/dt \approx 0$.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 5.1 (ohmic heating).

omega_i_tau_E_from_B_tau_E_M

omega_i_tau_E_from_B_tau_E_M(B_t_T, tau_E_s, M_eff_amu, Z_i=1.0) — aliases calc_omega_i_tau_E

Convention-sensitive.

Ion-cyclotron-normalised confinement time $\Omega_i\tau_E$.

Raises.

ValueError For non-finite or non-positive input.

Convention.

Exact SI angular cyclotron frequency with the proton mass and elementary charge from vaft.formula.constants; not a fitted prefactor. The dependent variable of dimensionless confinement scalings.

References.

1. G. Verdoolaege et al., Nucl. Fusion 61 (2021) 076006, Sec. 2.
2. ITER Physics Expert Groups, Nucl. Fusion 39 (1999) 2175, Ch. 2, Sec. 6.

peaking_factor

peaking_factor(central, volume_avg)

Profile peaking factor, central value over volume average.

Limitations.

No guard against a zero volume average. Tracked in #357.

See Also.

vaft.formula.utils.calculate_peaking_factor

phi_from_Bphi

phi_from_Bphi(B_phi, dA)

Convention-sensitive.

Toroidal flux $\Phi$ through a poloidal cross-section.

Convention.

Full weber, never per radian: toroidal flux carries no $2\pi$ ambiguity. The sign is that of $B_\varphi$, i.e. $\sigma_{B_\varphi}$ of the COCOS in use (COCOS 1-8 and 11-18 differ only in the poloidal flux).

Assumptions.

dA are true area elements of the cross-section bounded by the flux surface of interest; the routine does not construct them.

Numerical notes.

A Riemann sum, not a quadrature rule: accuracy is first order in the cell size of the caller’s grid.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.4 (toroidal flux and the safety factor).

poloidal_field_factor

poloidal_field_factor(cocos, *, psi_per_radian=None)

Convention-sensitive.

Sauter Eq. 20 prefactor $k = \sigma_{R\varphi Z}\,\sigma_{B_p}/(2\pi)^{e_{B_p}}$.

The factor carries both the $2\pi$ normalisation and the orientation sign, so applying only the former leaves the field inverted for half the conventions.

Convention.

cocos=None keeps the weber-per-radian, $k=-1$ behaviour that the rest of this module assumed before conventions were explicit: the COCOS 2/3/6/7 form. Pass an index to get any other; it is resolved through vaft.data.cocos.cocos_spec, the single source of truth for the COCOS model in VAFT. The two halves are established by different evidence, so they can be known separately: psi_per_radian supplies the $2\pi$ half on its own for a caller that settled the storage family without pinning the index (an ODS whose flux scale is unambiguous while clockwise_phi leaves the index open). It is consulted only when cocos is None, where the orientation still falls back to $-1$; an index carries both halves and wins outright.

See Also.

vaft.data.eqdsk.ods_psi_to_wb_per_radian_factor

References.

1. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Eq. (20) and Table I.

psi_from_RBtheta

psi_from_RBtheta(R, B_theta, l, psi_axis=0.0)

Convention-sensitive.

Poloidal flux $\psi$ from a line integral of $R B_\theta$ across flux surfaces.

along a path $l$ that crosses the flux surfaces (the outboard midplane, say), where $B_\theta$ is the poloidal field component normal to the path. This is the inverse of $B_p = |\nabla\psi|/R$, so the result is the flux per radian.

Convention.

Returns flux per radian, $\psi = \int R B_\theta\,dl$, the COCOS 1-8 storage of an EFIT g-file or of VFIT. Multiply by $2\pi$ for the IMAS Data Dictionary’s full-weber equilibrium.*.psi (COCOS 11-18). The sign follows the sign of B_theta and the direction of l; nothing is re-oriented.

Assumptions.

Axisymmetry, and that B_theta is the component perpendicular to the path so that $R B_\theta\,dl$ is exactly $d\psi$.

Numerical notes.

Trapezoidal rule (numpy.trapezoid) on the supplied samples; the result is returned only at the sample points and is second-order accurate in the spacing of l.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.2 (flux functions).
2. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Sec. 2 and Table I (per-radian versus full-weber flux).

psi_normalised

psi_normalised(psi, psi_axis, psi_boundary)

Convention-sensitive.

Normalised poloidal flux $\psi_N$.

Convention.

Independent of the $2\pi$ storage convention and of the COCOS sign, because both cancel in the ratio, provided all three inputs share one convention. Equals the IMAS profiles_1d.psi_norm label.

Limitations.

Divides by psi_boundary - psi_axis without a guard; a degenerate equilibrium with equal axis and boundary flux returns inf/nan. Tracked in #357.

See Also.

vaft.formula.utils.normalize_profile

q_cyl_from_B_R_epsilon_kappa_I

q_cyl_from_B_R_epsilon_kappa_I(B_t_T, R_geo_m, epsilon, kappa_a, I_p_A) — aliases calc_q_cyl

Convention-sensitive.

Cylindrical safety factor in the Verdoolaege convention.

Raises.

ValueError For non-finite or non-positive input.

Convention.

cylindrical_safety_factor_from_R_B_epsilon_I_f_kappa_delta with $f = 1/\kappa_a$ and $2\pi/\mu_0 = 5\times10^6$; $\kappa_a$ is the area elongation $S/(\pi a^2)$ of the confinement databases, not the boundary elongation.

References.

1. G. Verdoolaege et al., Nucl. Fusion 61 (2021) 076006, Sec. 2.
2. ITER Physics Expert Groups, Nucl. Fusion 39 (1999) 2175, Ch. 2, Sec. 3.

q_from_phi

q_from_phi(psi, phi)

Convention-sensitive.

Safety factor $q$ as the flux derivative $d\Phi/d\psi$.

Convention.

Sauter and Medvedev define $q = \sigma_{\rho\theta\varphi}\sigma_{B_p} (2\pi)^{-e_{B_p}}\,d\Phi/d\psi$. This routine applies neither sign nor $2\pi$: it is exact for psi in Wb/rad (COCOS 1-8, $e_{B_p}=0$) up to the orientation sign, and returns $2\pi q$ when psi is the IMAS full-weber flux. Convert with vaft.data.eqdsk.ods_psi_to_wb_per_radian_factor first, or take profiles_1d.q from the equilibrium directly. Tracked in #354.

Numerical notes.

numpy.gradient: second-order central differences in the interior, first-order one-sided at the two ends, noise-amplifying; needs at least two samples and a strictly monotonic psi.

References.

1. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Eq. (17) and Table I.
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.4.

q_from_rhoN

q_from_rhoN(psiN, rhoN, C=1.0)

Convention-sensitive.

Safety factor from the toroidal-flux label $\rho_N(\psi_N)$.

follows from $\Phi = \Phi_b\rho_N^2$ and $q = d\Phi/d\psi$.

Convention.

With C=1 the result is $q$ up to the constant $2\Phi_b/(\psi_b-\psi_a)$ and is only proportional to the true profile. Supply C from the equilibrium (with $\psi$ per radian, or $2\pi$ smaller with full-weber $\psi$) for absolute values; the orientation sign is not applied.

Numerical notes.

numpy.gradient of rhoN against psiN (second-order interior, first-order ends); the on-axis value is dominated by the one-sided difference and by $\rho_N\to0$.

References.

1. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Eq. (17).
2. F. L. Hinton and R. D. Hazeltine, Rev. Mod. Phys. 48 (1976) 239, Sec. II.B.

radial_magnetic_field_from_psi

radial_magnetic_field_from_psi(psi, R, Z, cocos=None)

Convention-sensitive.

Radial magnetic field $B_R$ from the poloidal flux map.

with $k$ from poloidal_field_factor (Sauter Eq. 20).

Convention.

cocos=None assumes psi in Wb/rad with $\sigma_{B_p}\sigma_{R\varphi Z} =-1$ (COCOS 2/3/6/7). A full-weber map (IMAS Data Dictionary, vaft.formula.green.green_psi_exact) passed without cocos overestimates $|B_R|$ by $2\pi$; convert with vaft.data.eqdsk.ods_psi_to_wb_per_radian_factor or pass the index.

Assumptions.

Axisymmetry. The derivative is taken along the first axis of psi against Z, so the map must be indexed [Z] or [Z, R]; a [R, Z]-ordered 2-D array differentiates along the wrong axis.

Numerical notes.

numpy.gradient (second-order interior, first-order one-sided ends).

References.

1. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Eq. (20) and Table I.

rhoN_from_phi

rhoN_from_phi(phi, phi_boundary)

Convention-sensitive.

Normalised toroidal-flux radius $\rho_N$.

Convention.

This is the IMAS rho_tor_norm label (the square root of normalised toroidal flux), not the poloidal-flux label $\sqrt{\psi_N}$ nor a geometric minor radius. phi and phi_boundary must carry the same sign; a COCOS-sign mismatch between them produces nan from the square root.

Physical interpretation.

$\rho_N$ is the minor radius of the circular cylinder that would enclose the same toroidal flux at the same $B_0$, scaled to the boundary value.

References.

1. F. L. Hinton and R. D. Hazeltine, Rev. Mod. Phys. 48 (1976) 239, Sec. II.B (flux-surface coordinates).
2. IMAS Data Dictionary, equilibrium.time_slice[:].profiles_1d.rho_tor_norm.

rhoN_from_qpsiN

rhoN_from_qpsiN(psiN, qpsiN)

Convention-sensitive.

Normalised toroidal-flux radius from the $q$ profile.

which is $\sqrt{\Phi/\Phi_b}$ since $d\Phi = q\,d\psi$ and the constants cancel in the ratio.

Convention.

Independent of the $\psi$ unit and of the COCOS sign as long as qpsiN does not change sign; a signed $q$ (COCOS with $\sigma_{\rho\theta\varphi}=-1$) must be passed as $|q|$ or the square root returns nan.

Assumptions.

psiN starts at the magnetic axis; the integral is taken from the first sample, so a profile that starts inside the plasma is mis-normalised.

Numerical notes.

Cumulative trapezoidal integral rebuilt from scratch at every sample ($O(N^2)$; tracked in #357); the denominator is not guarded against zero.

References.

1. F. L. Hinton and R. D. Hazeltine, Rev. Mod. Phys. 48 (1976) 239, Sec. II.B.

rho_star_from_M_T_B_R_epsilon

rho_star_from_M_T_B_R_epsilon(M_eff_amu, T_eV, B_t_T, R_geo_m, epsilon) — aliases calc_rho_star

Convention-sensitive.

Normalised ion gyroradius $\rho_*$ in the Verdoolaege engineering form.

Raises.

ValueError For non-finite or non-positive input.

Convention.

$1.44\times10^{-4} = \sqrt{2m_p/e}$, i.e. $\rho_i = \sqrt{2m_iT}/(eB)$ normalised by $a = R_{geo}\varepsilon$: the same physics as normalized_larmor_radius_from_M_T_a_Bt in database units. Tracked with the other $\rho_*$ definitions in #353.

References.

1. G. Verdoolaege et al., Nucl. Fusion 61 (2021) 076006, Sec. 2.

rho_tor_from_phi

rho_tor_from_phi(phi, B0)

Convention-sensitive.

Convention.

The IMAS rho_tor coordinate: the minor radius of the circle that would carry the same toroidal flux in a uniform field $B_0$, with $B_0 =$ vacuum_toroidal_field.b0 at r0. Absolute values are taken, so the result is independent of the COCOS signs of $\Phi$ and $B_0$; divide by the boundary value for rhoN_from_phi’s rho_tor_norm.

Physical interpretation.

A length-like flux label that reduces to the geometric minor radius for a circular, large-aspect-ratio plasma with uniform $B_0$.

References.

1. IMAS Data Dictionary, equilibrium.time_slice[:].profiles_1d.rho_tor.
2. F. L. Hinton and R. D. Hazeltine, Rev. Mod. Phys. 48 (1976) 239, Sec. II.B.

shear_from_r_q

shear_from_r_q(r, q) — aliases magnetic_shear

Convention-sensitive.

Magnetic shear $s$ of the safety-factor profile.

Convention.

The logarithmic derivative $d\ln q/d\ln r$, the definition used in the $s$-$\alpha$ ballooning diagram; any monotonic radius label gives the same number up to the choice of $r$ (minor radius versus $\rho_N$ differ in the Shafranov-shifted region). Sign is that of $dq/dr$, which is independent of COCOS.

Physical interpretation.

Rate at which field-line pitch changes across surfaces; positive shear stabilises ballooning modes at low $\alpha$ and localises resonant perturbations.

Numerical notes.

numpy.gradient (second-order interior, first-order ends), then division by q and multiplication by r: the axis value is exactly 0 when r starts at 0 and undefined where $q$ crosses zero.

References.

1. J. W. Connor, R. J. Hastie and J. B. Taylor, Phys. Rev. Lett. 40 (1978) 396, definition of $s$.
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 6.13.

spitzer_resistivity_from_T_e_Z_eff_ln_Lambda

spitzer_resistivity_from_T_e_Z_eff_ln_Lambda(T_e, Z_eff=2.0, ln_Lambda=17.0)

Convention-sensitive.

Spitzer parallel resistivity $\eta_\parallel$.

Convention.

The NRL Formulary value $\eta_\parallel = 1.65\times10^{-9}\,Z\ln\Lambda\, T_{\mathrm{keV}}^{-3/2}\ \Omega$ m rewritten for $T_e$ in eV; the $Z_{\mathrm{eff}}$ factor is applied linearly (the Spitzer-Harm $Z$-dependence is weaker than linear for $Z>1$).

Assumptions.

Classical collisional plasma, no neoclassical trapped-particle correction.

Validity.

Core tokamak plasmas well above the ionisation stage; the defaults $Z_{\mathrm{eff}}=2$ and $\ln\Lambda=17$ are typical rather than derived, use coulomb_logarithm_from_n_T for a self-consistent value.

Limitations.

Neoclassical resistivity in a spherical tokamak exceeds this by the trapped-fraction factor (up to ~2 at VEST aspect ratio).

References.

1. NRL Plasma Formulary (2019), p. 29 (Spitzer resistivity).
2. L. Spitzer and R. Harm, Phys. Rev. 89 (1953) 977.
3. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 2.16 (resistivity).

stored_energy_from_beta_V

stored_energy_from_beta_V(beta, B0, V)

Convention-sensitive.

Stored energy from toroidal beta, $W = \beta B_0^2 V/(2\mu_0)$.

Convention.

Uses the fraction form of $\beta_t$; a percentage input is 100 times too large. As for stored_energy_from_p_V, the result is $\langle p\rangle V$, so the thermal energy is 1.5 times it.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.5 (definition of beta).

stored_energy_from_p_V

stored_energy_from_p_V(p, V)

Convention-sensitive.

Stored energy as pressure times volume, $W = pV$.

Convention.

$pV$ is the magnetic-like energy normalisation; the thermal energy of an ideal gas is $W_{th} = \tfrac{3}{2}\int p\,dV$, so multiply by 1.5 for the IMAS energy_thermal convention.

Assumptions.

p is the volume average (or the profile is flat) when V is the total volume.

surface_poloidal_flux_from_psi_boundary

surface_poloidal_flux_from_psi_boundary(psi_boundary)

Convention-sensitive.

Total poloidal flux at the plasma surface, $\Phi_{surface} = 2\pi\psi_b$.

Convention.

Converts a per-radian boundary flux (COCOS 1-8, EFIT g-file, VFIT) to the full flux that flux-consumption bookkeeping uses. An IMAS full-weber global_quantities.psi_boundary (COCOS 11-18) must not be passed: the result would be $2\pi$ too large. Tracked in #354.

Physical interpretation.

The poloidal flux linked by the plasma boundary, whose time derivative is the surface loop voltage in the Ejima flux-consumption balance.

References.

1. S. Ejima et al., Nucl. Fusion 22 (1982) 1313, Sec. 2.
2. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Table I.

toroidal_flux_from_q_psi

toroidal_flux_from_q_psi(q, psi_wb)

Convention-sensitive.

Cumulative toroidal flux $\Phi(\psi)$ from the $q$ profile on a full-weber grid.

Convention.

psi_wb is the IMAS Data Dictionary flux (COCOS 11-18). No $2\pi$ appears because $d\Phi/d\psi_{rad} = 2\pi q$ and $\psi_{wb} = 2\pi \psi_{rad}$ cancel; pass 2*np.pi*psi_rad for an EFIT or VFIT per-radian profile (vaft.data.eqdsk.ods_psi_to_wb_per_radian_factor settles which family an ODS holds). The orientation sign of $q$ and $\psi$ is not applied: a COCOS with $\sigma_{\rho\theta\varphi} = -1$ gives a negative $\Phi$.

Numerical notes.

Cumulative trapezoidal rule (scipy.integrate.cumulative_trapezoid via vaft.compat.cumtrapz_compat); second order in the grid spacing, and the result is the running integral, so its first element is zero.

References.

1. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Eq. (17) and Table I.
2. IMAS Data Dictionary, equilibrium.time_slice[:].profiles_1d.phi.

triangularity_from_RZ_boundary

triangularity_from_RZ_boundary(R, Z, R0)

Convention-sensitive.

Boundary triangularity $\delta$ from the midplane intersection.

Convention.

Uses the single boundary point closest to $Z=0$, so the result is a property of the midplane crossing chosen by argmin, not the standard $\delta = (R_0 - R_{Z_{\max}})/a$ evaluated at the top and bottom extremities (IMAS triangularity_upper/lower). Positive means the crossing lies inboard of R0.

Limitations.

Whether the inboard or outboard midplane point is picked depends on which is nearer $Z=0$ in the sampling, so the sign is not stable; prefer the IMAS-style extremity definition for reported values. Tracked in #365.

References.

1. IMAS Data Dictionary, equilibrium.time_slice[:].boundary.triangularity.
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.1.

verify_kadomtsev_constraint

verify_kadomtsev_constraint(mu_rho, mu_beta, mu_nu, a_P)

Reconstruct the Kadomtsev constraint value from dimensionless indices.

which should return 5 when the dimensionless mapping of dimensionless_scaling_coeffs_from_engineering_scaling_coeffs preserves the identity $\alpha_L + 2\alpha_n + \alpha_B^* - 3\alpha_P = 5$.

Limitations.

Evaluates a different expression from check_kadomtsev_constraint (which uses the engineering exponents directly) and the two need not agree; tracked in #351.

References.

1. B. B. Kadomtsev, Sov. J. Plasma Phys. 1 (1975) 295.
2. T. C. Luce, C. C. Petty and J. G. Cordey, Plasma Phys. Control. Fusion 50 (2008) 043001.

vertical_magnetic_field_from_psi

vertical_magnetic_field_from_psi(psi, R, Z, cocos=None)

Convention-sensitive.

Vertical magnetic field $B_Z$ from the poloidal flux map.

with $k$ from poloidal_field_factor (Sauter Eq. 20).

Convention.

cocos=None assumes psi in Wb/rad with $\sigma_{B_p}\sigma_{R\varphi Z} =-1$ (COCOS 2/3/6/7). A full-weber map (IMAS Data Dictionary, vaft.formula.green.green_psi_exact) passed without cocos overestimates $|B_Z|$ by $2\pi$; convert with vaft.data.eqdsk.ods_psi_to_wb_per_radian_factor or pass the index.

Assumptions.

Axisymmetry. The derivative is taken along the first axis of psi against R, so the map must be indexed [R] or [R, Z].

Numerical notes.

numpy.gradient (second-order interior, first-order one-sided ends).

References.

1. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Eq. (20) and Table I.

virial_D0_boundary_from_bp_li_eK

virial_D0_boundary_from_bp_li_eK(beta_p, li_int, eK, b_minor, R_plasma)

Convention-sensitive.

Boundary Shafranov shift $D_0(b)$ from $\beta_p$, $l_i$ and elongation.

Convention.

Negative sign convention of Martynov and Pustovitov: the magnetic axis moves outboard, so $D_0 < 0$ for positive $\beta_p + l_i/2$.

Validity.

First order in $b/R$; elongation through $e_K$ only.

References.

1. A. A. Martynov and V. D. Pustovitov, Phys. Plasmas 31 (2024), “Virial relations for elongated plasmas in tokamaks”, Eq. (37).

virial_S1_approx

virial_S1_approx()

Convention-sensitive.

Leading-order value of the first Shafranov integral, $S_1 = 2$.

Convention.

Lao/EFIT normalisation of the surface integrals by $B_{pa}$ and the plasma volume, in which $S_1\to2$ for a circular, unshifted, large-aspect-ratio boundary.

Validity.

Valid to first order in inverse aspect ratio, Shafranov shift $D_0$ and triangularity; a placeholder when the surface integral itself is unavailable.

References.

1. A. A. Martynov and V. D. Pustovitov, Phys. Plasmas 31 (2024), “Virial relations for elongated plasmas in tokamaks”, Sec. III.
2. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421.

virial_S2_approx_from_D0_a_R0

virial_S2_approx_from_D0_a_R0(eK, D0, a_minor, R0)

Convention-sensitive.

Analytic approximation of the second Shafranov integral for an elongated boundary.

Convention.

Lao/EFIT normalisation of the surface integrals; $D_0$ as defined by Martynov and Pustovitov (shift over minor radius).

Validity.

First order in $a/R_0$ and in the shift; elongation enters only through $e_K$.

References.

1. A. A. Martynov and V. D. Pustovitov, Phys. Plasmas 31 (2024), “Virial relations for elongated plasmas in tokamaks”, Eq. (21).

virial_S3_approx_from_eK_d

virial_S3_approx_from_eK_d(eK, d_param)

Convention-sensitive.

Analytic approximation of the third Shafranov integral for an elongated boundary.

Convention.

Lao/EFIT normalisation of the surface integrals.

Validity.

First order in the shape parameters.

References.

1. A. A. Martynov and V. D. Pustovitov, Phys. Plasmas 31 (2024), “Virial relations for elongated plasmas in tokamaks”, Eq. (22).

virial_beta_p_from_S_alpha_mu

virial_beta_p_from_S_alpha_mu(S1, S2, S3, alpha, mui_hat)

Convention-sensitive.

Poloidal beta from the Shafranov integrals, low-aspect-ratio closure.

Convention.

$S_1$-$S_3$ and $\hat\mu_i$ in the Lao/EFIT normalisation by $B_{pa}$ (virial_beta_p_from_volume). The closure retains the diamagnetic term, so it holds at low aspect ratio where the Lao form does not.

References.

1. M. W. Bongard et al., Phys. Plasmas 23 (2016), low-aspect-ratio virial closure (journal page not recorded in the VAFT source).
2. V. D. Shafranov, Plasma Phys. 13 (1971) 757.

virial_beta_p_from_S_li

virial_beta_p_from_S_li(S1, S2, li)

Poloidal beta from $S_1$, $S_2$ and a known internal inductance.

Physical interpretation.

Solves the first virial relation $S_1 + S_2 = 3\beta_p + l_i - \hat l_i$ for $\beta_p$ after dropping $\hat l_i$ and rescaling, giving the classic “$\beta_p + l_i/2$ from magnetics” separation when $l_i$ is known independently.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 3.

virial_beta_p_from_volume

virial_beta_p_from_volume(p, dV, B_pa, Omega, mu0=None)

Convention-sensitive.

Poloidal beta from a volume integral of pressure.

Convention.

The EFIT/Lao definition normalised by $B_{pa} = \mu_0 I_p/L_p$ with $L_p$ the boundary contour length, as used by the virial closures below. Other codes normalise by $B_p$ at the boundary or by $\mu_0 I_p/(2\pi a)$; the values differ by shape-dependent factors.

Numerical notes.

Plain weighted sum over the supplied cells.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 2.
2. V. D. Shafranov, Plasma Phys. 13 (1971) 757.

virial_beta_p_lao_from_S_mu_rt

virial_beta_p_lao_from_S_mu_rt(S1, S2, mui, RT_over_R0)

Poloidal beta, Lao large-aspect-ratio virial closure.

Validity.

Large aspect ratio; at VEST aspect ratio the neglected $\epsilon$ terms reach tens of percent, which is why the Bongard closure exists.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 3.

virial_beta_p_li_from_S_alpha_mu_rt

virial_beta_p_li_from_S_alpha_mu_rt(S1, S2, S3, alpha, mui, RT_over_R0, eps=1e-12)

Lao closure bundle: $\beta_p$, $l_i$ and $\beta_{p,d}$ in one call.

Evaluates virial_beta_p_lao_from_S_mu_rt, virial_li_from_S_alpha_rt and virial_beta_pd_from_S_mu_rt on the same inputs.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 3.

virial_beta_pd_from_S_mu_rt

virial_beta_pd_from_S_mu_rt(S1, S2, mui, RT_over_R0)

Diamagnetic poloidal beta $\beta_{p,d}$ from $S_1$, $S_2$ and $\mu_i$.

Validity.

Large aspect ratio (Lao closure).

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 3.

virial_bongard_from_S_alpha_mu

virial_bongard_from_S_alpha_mu(S1, S2, S3, alpha, mui)

Low-aspect-ratio virial closure (Bongard 2016): $\beta_p$ and $l_i$.

Evaluates virial_beta_p_from_S_alpha_mu and virial_li_from_S_alpha_mu.

References.

1. M. W. Bongard et al., Phys. Plasmas 23 (2016), low-aspect-ratio virial closure (journal page not recorded in the VAFT source).

virial_bp_li_lihat_from_S123

virial_bp_li_lihat_from_S123(S1, S2, S3, a_param, RT_over_R0)

Solve the three virial relations for $\beta_p$, $l_i$ and $\hat l_i$.

Numerical notes.

Direct solve of the 3x3 linear system with numpy.linalg.solve; singular when $\alpha = 1/3$ (rows become dependent).

References.

1. A. A. Martynov and V. D. Pustovitov, Phys. Plasmas 31 (2024), “Virial relations for elongated plasmas in tokamaks”, Eqs. (1)-(3).
2. V. D. Shafranov, Plasma Phys. 13 (1971) 757.

virial_kinetic_energy

virial_kinetic_energy(n, v, m, V)

Bulk kinetic energy of a sampled flow, $W_{kin} = \tfrac{1}{2}\sum n m v^2\,V$.

Assumptions.

Equal-volume samples (V is the cell volume); the flow is a bulk velocity, not a thermal speed.

References.

1. V. D. Shafranov, in Reviews of Plasma Physics, Vol. 2, Consultants Bureau (1966), p. 103.

virial_lao_from_S_alpha_mu_rt

virial_lao_from_S_alpha_mu_rt(S1, S2, S3, alpha, mui, RT_over_R0, eps=1e-12)

Large-aspect-ratio virial closure (Lao 1985): $\beta_p$ and $l_i$.

Evaluates virial_beta_p_lao_from_S_mu_rt and virial_li_from_S_alpha_rt.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 3.

virial_li_from_S_alpha_mu

virial_li_from_S_alpha_mu(S1, S2, S3, alpha, mui_hat)

Convention-sensitive.

Internal inductance from the Shafranov integrals, low-aspect-ratio closure.

Convention.

Companion of virial_beta_p_from_S_alpha_mu, same normalisation.

Limitations.

Ill-conditioned as $\alpha\to2/3$; no guard.

References.

1. M. W. Bongard et al., Phys. Plasmas 23 (2016), low-aspect-ratio virial closure (journal page not recorded in the VAFT source).

virial_li_from_S_alpha_rt

virial_li_from_S_alpha_rt(S1, S2, S3, alpha, RT_over_R0, eps=1e-12)

Internal inductance, Lao large-aspect-ratio virial closure.

Raises.

ValueError When alpha is within eps of 1 (the closure is singular there).

Validity.

Large aspect ratio, as virial_beta_p_lao_from_S_mu_rt.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 3.

virial_li_from_volume

virial_li_from_volume(B_p, dV, B_pa, Omega)

Convention-sensitive.

Internal inductance from a volume integral of $B_p^2$.

Convention.

Lao/EFIT normalisation by $B_{pa}$; not the IMAS $l_{i,3}$ (normalised by $(\mu_0 I_p)^2 R_0/2$) nor the cylindrical $l_i$.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 2.

virial_magnetic_energy

virial_magnetic_energy(B, V)

Magnetic energy of a sampled field, $W_{mag} = \sum B^2\,V/(2\mu_0)$.

Assumptions.

Equal-volume samples: V multiplies the plain sum, so it is the cell volume, not the total. Pass V_total / B.size for a uniform grid.

Numerical notes.

A Riemann sum, first order in the cell size.

References.

1. V. D. Shafranov, in Reviews of Plasma Physics, Vol. 2, Consultants Bureau (1966), p. 103 (virial theorem for a confined plasma).

virial_muihat_from_Bt_R0_dphi

virial_muihat_from_Bt_R0_dphi(B_t, R0, dphi, B_pa, Omega)

Convention-sensitive.

Diamagnetic parameter $\hat\mu_i$ from the measured diamagnetic flux.

Convention.

Sign follows dphi: a paramagnetic (low-$\beta_p$) plasma increases the toroidal flux and gives $\hat\mu_i > 0$ in the sign convention of the diamagnetic loop; check the loop’s polarity before comparing with a virial closure. $\Delta\phi$ is a full-weber toroidal flux.

Assumptions.

Large-aspect-ratio expansion of the toroidal-field energy term, $B_t R_0$ constant over the cross-section.

References.

1. L. L. Lao, H. St. John, R. D. Stambaugh and W. Pfeiffer, Nucl. Fusion 25 (1985) 1421, Sec. 2 ($\mu_i$ definition).
2. V. D. Shafranov, Plasma Phys. 13 (1971) 757.

virial_stability_criterion

virial_stability_criterion(W_mag, W_kin, W_th)

Virial-ratio margin against the heuristic threshold $r_v = 0.5$.

Limitations.

The threshold 0.5 is labelled “theoretical value for stability” in the original VAFT source but no derivation or reference for it was recorded; the scalar virial theorem constrains equilibrium, not stability. Treat the margin as a bookkeeping diagnostic. Tracked in #366.

References.

1. V. D. Shafranov, in Reviews of Plasma Physics, Vol. 2, Consultants Bureau (1966), p. 103.

virial_theorem

virial_theorem(W_mag, W_kin, W_th)

Total energy and virial ratio of magnetic, kinetic and thermal contributions.

Physical interpretation.

The scalar virial theorem forbids a plasma confined by its own fields alone: a positive-definite $W_{\mathrm{mag}}$ must be balanced by external (coil) fields, and the ratio measures how far the material energy is from that balance.

References.

1. V. D. Shafranov, in Reviews of Plasma Physics, Vol. 2, Consultants Bureau (1966), p. 103.
2. J. P. Freidberg, Ideal MHD, Cambridge University Press (2014), Sec. 3.6 (virial theorem).

virial_thermal_energy

virial_thermal_energy(n, T, V)

Convention-sensitive.

Thermal energy of a sampled plasma, $W_{th} = \tfrac{3}{2}\sum n T\,V$.

Convention.

T must be in joules ($k_B T$); a temperature in eV needs the factor QE. One species only: sum electron and ion calls for the total.

Assumptions.

Equal-volume samples (V is the cell volume); three degrees of freedom.

References.

1. V. D. Shafranov, in Reviews of Plasma Physics, Vol. 2, Consultants Bureau (1966), p. 103.

volume_from_RZ_boundary

volume_from_RZ_boundary(R, Z)

Plasma volume from a boundary polygon, mean-radius approximation.

Assumptions.

$\bar R$ is the arithmetic mean of the vertex radii, not the area centroid demanded by Pappus’ theorem; exact only for a boundary symmetric about $\bar R$.

Limitations.

On VEST flux surfaces the mean-radius factorisation differs from the exact contour integral by up to ~6 % at the edge; use exact_volume_from_RZ_contour for a reported volume.

Numerical notes.

Shoelace formula for the polygon area (exact for straight edges); the polygon is implicitly closed by numpy.roll.

References.

1. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.1 (plasma volume of a toroidal cross-section).

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