plasma_plots.theory.equilibria
Exact MHD equilibria to verify MHD codes: the Harris current sheet, the Bennett pinch, the Solov’ev tokamak equilibrium (Cerfon–Freidberg construction), and linear force-free (Lundquist) fields with the Taylor state.
Every equilibrium satisfies the force balance ∇p = J × B with μ₀J = ∇ × B and ∇ · B = 0. The
tests check this by finite differences, which is the check to run on a code’s own initial state
too. Profiles take the coordinates first, f(z, ...), so that a field of the returned result
(or a lambda around the function) can be passed as the reference= of plasma-plots’ profile
plots. Everything is plain numpy and vectorized.
Examples
The Harris-sheet peak density needed to balance a 10 mT field at T_e + T_i = 10 eV, and the Bennett current of a 1e20 m⁻³ pinch of radius 1 mm at 100 eV (T_e + T_i):
>>> print(f"{harris_sheet(0.0, 0.01, 1.0, 5.0, 5.0).density:.4e}")2.4834e+19>>> print(f"{bennett_pinch(0.0, 1e20, 1e-3, 50.0, 50.0).total_current:.1f} A")317.3 AClasses
| Name | Description |
|---|---|
BennettPinch | The Bennett pinch. |
HarrisSheet | The Harris current sheet B = B₀ tanh(z/L) e_x. |
LundquistField | The linear force-free field ∇ × B = α B in a cylinder. |
SolovevFields | The Solov'ev equilibrium on a grid of (R, Z). |
TaylorState | The pinch and reversal parameters of the Taylor state. |
Functions
| Name | Description |
|---|---|
bennett_pinch | Compute the Bennett pinch: the isothermal z-pinch with n = n₀/(1 + r²/a²)². |
harris_drift_speed | Compute the drift speed v = 2 T/(e B₀ L) with which a species carries the Harris current. |
harris_sheet | Compute the Harris current sheet: a field reversal in pressure balance. |
lundquist_field | Compute the Lundquist field B = B₀ (J₁(α r) e_θ + J₀(α r) e_z): force free with J = α B/μ₀. |
solovev | Compute the Solov'ev equilibrium of Cerfon and Freidberg: ψ, B and p of a shaped tokamak. |
solovev_axis | Find the magnetic axis (R_ax, 0) of a Solov'ev equilibrium, where ∇ψ = 0. |
solovev_boundary | Compute the "D"-shaped boundary x = 1 + ε cos(τ + α sin τ), y = κ ε sin τ. |
solovev_coefficients | Compute the constants cᵢ that give a Solov'ev equilibrium a "D"-shaped boundary. |
solovev_safety_factor_axis | Compute the safety factor on the magnetic axis, q₀ = F/(R √(Ψ_RR Ψ_ZZ)). |
taylor_state | Compute the pinch parameter Θ and reversal parameter F of the Taylor state of α a. |
BennettPinchclassdataclass#
class BennettPinch(density: object, pressure: object, b_theta: object, current_density: object, enclosed_current: object, total_current: float, line_density: float)The Bennett pinch.
Attributes
| Name | Type | Description |
|---|---|---|
density | float or numpy.ndarray | The density n = n₀/(1 + r²/a²)², in m⁻³. |
pressure | float or numpy.ndarray | The pressure n k_B (T_e + T_i), in Pa. |
b_theta | float or numpy.ndarray | The azimuthal field, in T. |
current_density | float or numpy.ndarray | The axial current density J_z = μ₀⁻¹ r⁻¹ d(r B_θ)/dr, in A/m². |
enclosed_current | float or numpy.ndarray | The current inside r, I r²/(r² + a²), in A. |
total_current | float | The total current I from the Bennett relation, in A. |
line_density | float | The number of ions per unit length N = π n₀ a², in m⁻¹. |
b_thetaattributeinstance attribute#
b_theta: objectcurrent_densityattributeinstance attribute#
current_density: objectdensityattributeinstance attribute#
density: objectenclosed_currentattributeinstance attribute#
enclosed_current: objectline_densityattributeinstance attribute#
line_density: floatpressureattributeinstance attribute#
pressure: objecttotal_currentattributeinstance attribute#
total_current: floatHarrisSheetclassdataclass#
class HarrisSheet(b_x: object, density: object, pressure: object, current_density: object, vector_potential: object, peak_density: float)The Harris current sheet B = B₀ tanh(z/L) e_x.
Attributes
| Name | Type | Description |
|---|---|---|
b_x | float or numpy.ndarray | The field B_x = B₀ tanh(z/L), in T. |
density | float or numpy.ndarray | The density n = n₀ sech²(z/L) + n_b, in m⁻³. |
pressure | float or numpy.ndarray | The pressure p = n k_B (T_e + T_i), in Pa. |
current_density | float or numpy.ndarray | The current density J_y = (B₀/μ₀L) sech²(z/L), in A/m². |
vector_potential | float or numpy.ndarray | The vector potential A_y = −B₀ L ln cosh(z/L), in T m. |
peak_density | float | The sheet density n₀ = B₀²/(2μ₀ e (T_e + T_i)), without the background, in m⁻³. |
b_xattributeinstance attribute#
b_x: objectcurrent_densityattributeinstance attribute#
current_density: objectdensityattributeinstance attribute#
density: objectpeak_densityattributeinstance attribute#
peak_density: floatpressureattributeinstance attribute#
pressure: objectvector_potentialattributeinstance attribute#
vector_potential: objectLundquistFieldclassdataclass#
class LundquistField(b_theta: object, b_z: object, current_density_theta: object, current_density_z: object, pressure: object)The linear force-free field ∇ × B = α B in a cylinder.
Attributes
| Name | Type | Description |
|---|---|---|
b_theta | float or numpy.ndarray | The azimuthal field B₀ J₁(α r), in T. |
b_z | float or numpy.ndarray | The axial field B₀ J₀(α r), in T. |
current_density_theta | float or numpy.ndarray | The azimuthal current density α B_θ/μ₀, in A/m². |
current_density_z | float or numpy.ndarray | The axial current density α B_z/μ₀, in A/m². |
pressure | float or numpy.ndarray | The pressure, zero (the field is force free). |
SolovevFieldsclassdataclass#
class SolovevFields(psi_normalized: object, psi: object, b_r: object, b_z: object, b_phi: object, pressure: object, current_density_phi: object)The Solov’ev equilibrium on a grid of (R, Z).
Attributes
| Name | Type | Description |
|---|---|---|
psi_normalized | float or numpy.ndarray | The normalized flux ψ̂ = Ψ/Ψ₀: zero on the boundary, negative inside. |
psi | float or numpy.ndarray | The poloidal flux per radian Ψ, in Wb. |
b_r | float or numpy.ndarray | The radial field −∂_Z Ψ/R, in T. |
b_z | float or numpy.ndarray | The vertical field ∂_R Ψ/R, in T. |
b_phi | float or numpy.ndarray | The toroidal field F/R, in T. |
pressure | float or numpy.ndarray | The pressure, in Pa. |
current_density_phi | float or numpy.ndarray | The toroidal current density −(Ψ₀/μ₀R₀³)(A/x + (1 − A) x) = −Δ*Ψ/(μ₀R), in A/m². |
b_phiattributeinstance attribute#
b_phi: objectb_rattributeinstance attribute#
b_r: objectb_zattributeinstance attribute#
b_z: objectcurrent_density_phiattributeinstance attribute#
current_density_phi: objectpressureattributeinstance attribute#
pressure: objectpsiattributeinstance attribute#
psi: objectpsi_normalizedattributeinstance attribute#
psi_normalized: objectTaylorStateclassdataclass#
class TaylorState(pinch: object, reversal: object)The pinch and reversal parameters of the Taylor state.
Attributes
| Name | Type | Description |
|---|---|---|
pinch | float or numpy.ndarray | Θ = B_θ(a)/⟨B_z⟩ = α a/2. |
reversal | float or numpy.ndarray | F = B_z(a)/⟨B_z⟩ = α a J₀(α a)/(2 J₁(α a)). |
bennett_pinchfunction#
def bennett_pinch(r, density0, radius, temperature_electron, temperature_ion)Compute the Bennett pinch: the isothermal z-pinch with n = n₀/(1 + r²/a²)².
The current is fixed by the Bennett relation μ₀ I² = 8π N k_B (T_e + T_i) with the line density N = π n₀ a²: then dp/dr = −J_z B_θ holds at every r, with B_θ = μ₀ I r/(2π (r² + a²)) and J_z = I a²/(π (r² + a²)²).
Parameters
Returns
BennettPinch- Density, pressure, B_θ, current density and the currents.
Raises
ValueError- If
density0,radiusor the temperatures are not positive.
Examples
The current and the edge field of a 1e20 m⁻³, 1 mm pinch at T_e + T_i = 100 eV:
>>> p = bennett_pinch(1e-3, 1e20, 1e-3, 50.0, 50.0)>>> print(f"{p.total_current:.1f} A, B_theta(a) = {p.b_theta:.4e} T")317.3 A, B_theta(a) = 3.1728e-02 Tharris_drift_speedfunction#
def harris_drift_speed(temperature, b0, thickness)Compute the drift speed v = 2 T/(e B₀ L) with which a species carries the Harris current.
With the species drifting along y at u_s, the current J_y = n₀ e (u_i + |u_e|) sech² equals the field’s B₀ sech²/(μ₀ L) when u_s = 2 T_s/(e B₀ L) (T_s in eV; the Harris distribution), given n₀ (T_e + T_i) = B₀²/2μ₀.
Parameters
Returns
float or numpy.ndarray- The drift speed in m/s.
Examples
>>> print(f"{harris_drift_speed(5.0, 0.01, 1.0):.4e} m/s")1.0000e+03 m/sharris_sheetfunction#
def harris_sheet(z, b0, thickness, temperature_electron, temperature_ion, background_density=0.0)Compute the Harris current sheet: a field reversal in pressure balance.
The field B_x = B₀ tanh(z/L) reverses across the sheet, the density n = n₀ sech²(z/L) + n_b peaks where it vanishes, and p + B²/2μ₀ is uniform when n₀ k_B (T_e + T_i) = B₀²/2μ₀ (the uniform background adds a uniform pressure). The current is μ₀ J_y = ∂_z B_x and the vector potential A_y = −B₀ L ln cosh(z/L) has B_x = −∂_z A_y.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
z | float or array_like | required | The coordinate across the sheet, in m. |
b0 | float | required | The asymptotic field B₀, in T. |
thickness | float | required | The half thickness L, in m. |
temperature_electron | float | required | The electron temperature, in eV. |
temperature_ion | float | required | The ion temperature, in eV. |
background_density | float | 0.0 | The uniform background density n_b, in m⁻³. Default: 0.0. |
Returns
HarrisSheet- The field, density, pressure, current density and vector potential.
Raises
ValueError- If
thicknessor the temperatures are not positive, or the background density is negative.
Examples
The total pressure p + B²/2μ₀ is the same everywhere:
>>> import numpy as np>>> s = harris_sheet(np.array([0.0, 0.5, 3.0]), 0.01, 1.0, 5.0, 5.0, 1e17)>>> total = s.pressure + s.b_x**2 / (2 * 1.25663706212e-06)>>> bool(np.ptp(total) < 1e-9 * total[0])Truelundquist_fieldfunction#
def lundquist_field(r, alpha, b0=1.0)Compute the Lundquist field B = B₀ (J₁(α r) e_θ + J₀(α r) e_z): force free with J = α B/μ₀.
Parameters
Returns
LundquistField- B_θ, B_z, the current density and the (zero) pressure.
Examples
The field vanishes in B_z at the first zero of J₀, r = 2.405/α:
>>> f = lundquist_field(2.404825557695773, 1.0)>>> abs(float(f.b_z)) < 1e-12, round(float(f.b_theta), 6)(True, 0.519147)solovevfunction#
def solovev(r, z, r0, epsilon, kappa, delta, a_param, psi0, b0)Compute the Solov’ev equilibrium of Cerfon and Freidberg: ψ, B and p of a shaped tokamak.
The Grad–Shafranov solution ψ̂ = A y²/2 + (1 − A) x⁴/8 + Σ cᵢ ψᵢ, x = R/R₀, y = Z/R₀, with
the constants from solovev_coefficients(); B_R = −∂_Z Ψ/R, B_Z = ∂_R Ψ/R,
B_φ = F/R with F² = F₀² + 2A (Ψ₀/R₀)² (−ψ̂) and F₀ = R₀ B₀, and the pressure
p = (1 − A) Ψ₀² (−ψ̂)/(μ₀ R₀⁴). The pressure vanishes on the boundary and the points outside
it (ψ̂ > 0) are not part of the plasma: there ψ̂ and the fields continue analytically but p
is negative, so mask them with psi_normalized < 0.
Parameters
| Name | Type | Description |
|---|---|---|
r | float or array_like | The major radius R, in m. |
z | float or array_like | The height Z, in m. |
r0 | float | The reference major radius R₀, in m. |
epsilon | float | The inverse aspect ratio ε. |
kappa | float | The elongation κ. |
delta | float | The triangularity δ. |
a_param | float | The constant A of the profiles: A = 0 is pressure-driven, A = 1 force-free. |
psi0 | float | The flux scale Ψ₀ in Wb (its sign sets the direction of the poloidal field). |
b0 | float | The vacuum toroidal field at R₀, in T: F₀ = R₀ B₀ is F on the boundary. |
Returns
SolovevFields- ψ̂, Ψ, B_R, B_Z, B_φ, the pressure and the toroidal current density.
Raises
ValueError- If the shape parameters are out of range (see
solovev_coefficients()), orr0≤ 0.
Examples
The flux vanishes on the boundary and is negative on the axis:
>>> s = solovev(1.3, 0.0, 1.0, 0.3, 1.5, 0.2, 0.1, 0.1, 1.0)>>> abs(float(s.psi_normalized)) < 1e-12True>>> s = solovev(1.0, 0.0, 1.0, 0.3, 1.5, 0.2, 0.1, 0.1, 1.0)>>> float(s.psi_normalized) < 0 and float(s.pressure) > 0Truesolovev_axisfunction#
def solovev_axis(epsilon, kappa, delta, a_param, r0=1.0)Find the magnetic axis (R_ax, 0) of a Solov’ev equilibrium, where ∇ψ = 0.
Newton’s method on ψ̂_x(x, 0) = 0, starting at the geometric centre x = 1 (by up-down symmetry the axis is on the midplane).
Parameters
Returns
float- The major radius of the axis, in the units of
r0.
Raises
RuntimeError- If Newton’s method does not converge.
Examples
The axis is shifted outward of the geometric centre 1:
>>> print(f"{solovev_axis(0.32, 1.7, 0.33, -0.155):.4f}")1.0513solovev_boundaryfunction#
def solovev_boundary(epsilon, kappa, delta, tau=None, r0=1.0)Compute the “D”-shaped boundary x = 1 + ε cos(τ + α sin τ), y = κ ε sin τ.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
epsilon | float | required | The inverse aspect ratio ε. |
kappa | float | required | The elongation κ. |
delta | float | required | The triangularity δ, with α = arcsin δ. |
tau | array_like | None | The angles τ. Default: 129 points on [0, 2π]. |
r0 | float | 1.0 | The major radius R₀ that scales R = R₀ x and Z = R₀ y. Default: 1.0. |
Returns
tuple of numpy.ndarray- The boundary points (R, Z).
Examples
The outer, top and inner points for ε = 0.3, κ = 1.5, δ = 0.2:
>>> r, z = solovev_boundary(0.3, 1.5, 0.2, [0.0, np.pi / 2, np.pi])>>> r.round(4), (z + 0.0).round(4)(array([1.3 , 0.94, 0.7 ]), array([0. , 0.45, 0. ]))solovev_coefficientsfunction#
def solovev_coefficients(epsilon, kappa, delta, a_param)Compute the constants cᵢ that give a Solov’ev equilibrium a “D”-shaped boundary.
Solves the 7 × 7 linear system of Cerfon and Freidberg for the up-down symmetric case: ψ̂ vanishes at the outer midplane point (1 + ε, 0), the inner one (1 − ε, 0) and the top point (1 − δε, κε), ψ̂_x vanishes at the top point, and the curvatures of the surface ψ̂ = 0 at the three points match those of x = 1 + ε cos(τ + α sin τ), y = κε sin τ with α = arcsin δ (ψ̂_yy = −N₁ ψ̂_x at the outer point, ψ̂_yy = −N₂ ψ̂_x at the inner one, ψ̂_xx = −N₃ ψ̂_y at the top, with N₁ = −(1 + α)²/(εκ²), N₂ = (1 − α)²/(εκ²), N₃ = −κ/(ε cos²α) and α = arcsin δ).
Parameters
Returns
numpy.ndarray- The seven coefficients c₁ … c₇ of ψ̂ = A y²/2 + (1 − A) x⁴/8 + Σ cᵢ ψᵢ.
Raises
ValueError- If
epsilonis not in (0, 1),kappa≤ 0 ordeltais not in (−1, 1).
Examples
The seven constants of an ITER-like shape:
>>> c = solovev_coefficients(0.32, 1.7, 0.33, -0.155)>>> c.shape(7,)solovev_safety_factor_axisfunction#
def solovev_safety_factor_axis(epsilon, kappa, delta, a_param, psi0, r0, b0)Compute the safety factor on the magnetic axis, q₀ = F/(R √(Ψ_RR Ψ_ZZ)).
Near the axis the flux surfaces are ellipses of area dA = 2π dΨ/√(Ψ_RR Ψ_ZZ), and q = (1/2π) ∮ F dl/(R² B_p) = (F/2πR) dA/dΨ, evaluated at R = R_ax.
Parameters
| Name | Type | Description |
|---|---|---|
epsilon | float | The inverse aspect ratio ε. |
kappa | float | The elongation κ. |
delta | float | The triangularity δ. |
a_param | float | The constant A of the profiles. |
psi0 | float | The flux scale Ψ₀, in Wb (only its magnitude matters). |
r0 | float | The reference major radius R₀, in m. |
b0 | float | The vacuum toroidal field at R₀, in T. |
Returns
float- q₀ (positive).
Examples
>>> print(... f"{solovev_safety_factor_axis(0.32, 1.7, 0.33, -0.155, 0.1, 1.0, 1.0):.4f}"... )18.8074taylor_statefunction#
def taylor_state(alpha_a)Compute the pinch parameter Θ and reversal parameter F of the Taylor state of α a.
Taylor’s relaxed state in a cylinder of radius a is the Lundquist field with ⟨B_z⟩ = 2B₀ J₁(αa)/(αa), so Θ = αa/2 and F = αa J₀(αa)/(2 J₁(αa)). The field reverses at the wall (F < 0) for αa > 2.405, the first zero of J₀, i.e. Θ > 1.202.
Parameters
| Name | Type | Description |
|---|---|---|
alpha_a | float or array_like | The product of the force-free constant and the wall radius, α a (not a zero of J₁). |
Returns
TaylorState- The pinch and reversal parameters.
Examples
Reversal sets in at Θ = 1.2024:
>>> s = taylor_state(2.404825557695773)>>> round(float(s.pinch), 4), abs(float(s.reversal)) < 1e-12(1.2024, True)