Skip to content
Projects

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 A

Classes

NameDescription
BennettPinchThe Bennett pinch.
HarrisSheetThe Harris current sheet B = B₀ tanh(z/L) e_x.
LundquistFieldThe linear force-free field ∇ × B = α B in a cylinder.
SolovevFieldsThe Solov'ev equilibrium on a grid of (R, Z).
TaylorStateThe pinch and reversal parameters of the Taylor state.

Functions

NameDescription
bennett_pinchCompute the Bennett pinch: the isothermal z-pinch with n = n₀/(1 + r²/a²)².
harris_drift_speedCompute the drift speed v = 2 T/(e B₀ L) with which a species carries the Harris current.
harris_sheetCompute the Harris current sheet: a field reversal in pressure balance.
lundquist_fieldCompute the Lundquist field B = B₀ (J₁(α r) e_θ + J₀(α r) e_z): force free with J = α B/μ₀.
solovevCompute the Solov'ev equilibrium of Cerfon and Freidberg: ψ, B and p of a shaped tokamak.
solovev_axisFind the magnetic axis (R_ax, 0) of a Solov'ev equilibrium, where ∇ψ = 0.
solovev_boundaryCompute the "D"-shaped boundary x = 1 + ε cos(τ + α sin τ), y = κ ε sin τ.
solovev_coefficientsCompute the constants cᵢ that give a Solov'ev equilibrium a "D"-shaped boundary.
solovev_safety_factor_axisCompute the safety factor on the magnetic axis, q₀ = F/(R √(Ψ_RR Ψ_ZZ)).
taylor_stateCompute 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

NameTypeDescription
densityfloat or numpy.ndarrayThe density n = n₀/(1 + r²/a²)², in m⁻³.
pressurefloat or numpy.ndarrayThe pressure n k_B (T_e + T_i), in Pa.
b_thetafloat or numpy.ndarrayThe azimuthal field, in T.
current_densityfloat or numpy.ndarrayThe axial current density J_z = μ₀⁻¹ r⁻¹ d(r B_θ)/dr, in A/m².
enclosed_currentfloat or numpy.ndarrayThe current inside r, I r²/(r² + a²), in A.
total_currentfloatThe total current I from the Bennett relation, in A.
line_densityfloatThe number of ions per unit length N = π n₀ a², in m⁻¹.

b_thetaattributeinstance attribute#

b_theta: object

current_densityattributeinstance attribute#

current_density: object

densityattributeinstance attribute#

density: object

enclosed_currentattributeinstance attribute#

enclosed_current: object

line_densityattributeinstance attribute#

line_density: float

pressureattributeinstance attribute#

pressure: object

total_currentattributeinstance attribute#

total_current: float

HarrisSheetclassdataclass#

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

NameTypeDescription
b_xfloat or numpy.ndarrayThe field B_x = B₀ tanh(z/L), in T.
densityfloat or numpy.ndarrayThe density n = n₀ sech²(z/L) + n_b, in m⁻³.
pressurefloat or numpy.ndarrayThe pressure p = n k_B (T_e + T_i), in Pa.
current_densityfloat or numpy.ndarrayThe current density J_y = (B₀/μ₀L) sech²(z/L), in A/m².
vector_potentialfloat or numpy.ndarrayThe vector potential A_y = −B₀ L ln cosh(z/L), in T m.
peak_densityfloatThe sheet density n₀ = B₀²/(2μ₀ e (T_e + T_i)), without the background, in m⁻³.

b_xattributeinstance attribute#

b_x: object

current_densityattributeinstance attribute#

current_density: object

densityattributeinstance attribute#

density: object

peak_densityattributeinstance attribute#

peak_density: float

pressureattributeinstance attribute#

pressure: object

vector_potentialattributeinstance attribute#

vector_potential: object

LundquistFieldclassdataclass#

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

NameTypeDescription
b_thetafloat or numpy.ndarrayThe azimuthal field B₀ J₁(α r), in T.
b_zfloat or numpy.ndarrayThe axial field B₀ J₀(α r), in T.
current_density_thetafloat or numpy.ndarrayThe azimuthal current density α B_θ/μ₀, in A/m².
current_density_zfloat or numpy.ndarrayThe axial current density α B_z/μ₀, in A/m².
pressurefloat or numpy.ndarrayThe pressure, zero (the field is force free).

b_thetaattributeinstance attribute#

b_theta: object

b_zattributeinstance attribute#

b_z: object

current_density_thetaattributeinstance attribute#

current_density_theta: object

current_density_zattributeinstance attribute#

current_density_z: object

pressureattributeinstance attribute#

pressure: object

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

NameTypeDescription
psi_normalizedfloat or numpy.ndarrayThe normalized flux ψ̂ = Ψ/Ψ₀: zero on the boundary, negative inside.
psifloat or numpy.ndarrayThe poloidal flux per radian Ψ, in Wb.
b_rfloat or numpy.ndarrayThe radial field −∂_Z Ψ/R, in T.
b_zfloat or numpy.ndarrayThe vertical field ∂_R Ψ/R, in T.
b_phifloat or numpy.ndarrayThe toroidal field F/R, in T.
pressurefloat or numpy.ndarrayThe pressure, in Pa.
current_density_phifloat or numpy.ndarrayThe toroidal current density −(Ψ₀/μ₀R₀³)(A/x + (1 − A) x) = −Δ*Ψ/(μ₀R), in A/m².

b_phiattributeinstance attribute#

b_phi: object

b_rattributeinstance attribute#

b_r: object

b_zattributeinstance attribute#

b_z: object

current_density_phiattributeinstance attribute#

current_density_phi: object

pressureattributeinstance attribute#

pressure: object

psiattributeinstance attribute#

psi: object

psi_normalizedattributeinstance attribute#

psi_normalized: object

TaylorStateclassdataclass#

class TaylorState(pinch: object, reversal: object)

The pinch and reversal parameters of the Taylor state.

Attributes

NameTypeDescription
pinchfloat or numpy.ndarrayΘ = B_θ(a)/⟨B_z⟩ = α a/2.
reversalfloat or numpy.ndarrayF = B_z(a)/⟨B_z⟩ = α a J₀(α a)/(2 J₁(α a)).

pinchattributeinstance attribute#

pinch: object

reversalattributeinstance attribute#

reversal: object

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

NameTypeDescription
rfloat or array_likeThe radius, in m.
density0floatThe density n₀ on the axis, in m⁻³.
radiusfloatThe scale radius a, in m.
temperature_electronfloatThe electron temperature, in eV.
temperature_ionfloatThe ion temperature, in eV.

Returns

BennettPinch
Density, pressure, B_θ, current density and the currents.

Raises

ValueError
If density0, radius or 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 T

harris_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

NameTypeDescription
temperaturefloat or array_likeThe temperature of the species, in eV.
b0floatThe asymptotic field B₀, in T.
thicknessfloatThe half thickness L, in m.

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/s

harris_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

NameTypeDefaultDescription
zfloat or array_likerequiredThe coordinate across the sheet, in m.
b0floatrequiredThe asymptotic field B₀, in T.
thicknessfloatrequiredThe half thickness L, in m.
temperature_electronfloatrequiredThe electron temperature, in eV.
temperature_ionfloatrequiredThe ion temperature, in eV.
background_densityfloat0.0The uniform background density n_b, in m⁻³. Default: 0.0.

Returns

HarrisSheet
The field, density, pressure, current density and vector potential.

Raises

ValueError
If thickness or 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])
True

lundquist_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

NameTypeDefaultDescription
rfloat or array_likerequiredThe radius, in m.
alphafloatrequiredThe force-free constant α in ∇ × B = α B, in 1/m.
b0float1.0The axial field on the axis, in T. Default: 1.0.

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

NameTypeDescription
rfloat or array_likeThe major radius R, in m.
zfloat or array_likeThe height Z, in m.
r0floatThe reference major radius R₀, in m.
epsilonfloatThe inverse aspect ratio ε.
kappafloatThe elongation κ.
deltafloatThe triangularity δ.
a_paramfloatThe constant A of the profiles: A = 0 is pressure-driven, A = 1 force-free.
psi0floatThe flux scale Ψ₀ in Wb (its sign sets the direction of the poloidal field).
b0floatThe 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()), or r0 ≤ 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-12
True
>>> 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) > 0
True

solovev_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

NameTypeDefaultDescription
epsilonfloatrequiredThe inverse aspect ratio ε.
kappafloatrequiredThe elongation κ.
deltafloatrequiredThe triangularity δ.
a_paramfloatrequiredThe constant A of the profiles.
r0float1.0The reference major radius R₀. Default: 1.0.

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

solovev_boundaryfunction#

def solovev_boundary(epsilon, kappa, delta, tau=None, r0=1.0)

Compute the “D”-shaped boundary x = 1 + ε cos(τ + α sin τ), y = κ ε sin τ.

Parameters

NameTypeDefaultDescription
epsilonfloatrequiredThe inverse aspect ratio ε.
kappafloatrequiredThe elongation κ.
deltafloatrequiredThe triangularity δ, with α = arcsin δ.
tauarray_likeNoneThe angles τ. Default: 129 points on [0, 2π].
r0float1.0The 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

NameTypeDescription
epsilonfloatThe inverse aspect ratio ε = a/R₀, in (0, 1).
kappafloatThe elongation κ > 0.
deltafloatThe triangularity δ, in (−1, 1).
a_paramfloatThe constant A of the Solov’ev profiles: A = 0 is pressure-driven, A = 1 force-free.

Returns

numpy.ndarray
The seven coefficients c₁ … c₇ of ψ̂ = A y²/2 + (1 − A) x⁴/8 + Σ cᵢ ψᵢ.

Raises

ValueError
If epsilon is not in (0, 1), kappa ≤ 0 or delta is 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

NameTypeDescription
epsilonfloatThe inverse aspect ratio ε.
kappafloatThe elongation κ.
deltafloatThe triangularity δ.
a_paramfloatThe constant A of the profiles.
psi0floatThe flux scale Ψ₀, in Wb (only its magnitude matters).
r0floatThe reference major radius R₀, in m.
b0floatThe 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.8074

taylor_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

NameTypeDescription
alpha_afloat or array_likeThe 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)