# plasma_plots.theory.equilibria

*module*

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.

> **Units**
>
> SI units (T, Pa, A/m², m) with temperatures in eV and densities in m⁻³, as in
> [`parameters`][plasma_plots.theory.parameters]. The Solov'ev functions take the flux scale and the
> toroidal field in SI units; its shape parameters are dimensionless. The pressure is p = n k_B
> (T_e + T_i) for a quasi-neutral plasma with n_e = n_i = n.

> **Harris sheet**
>
> B = B₀ tanh(z/L) e_x. Pressure balance p + B²/2μ₀ = const gives p = (B₀²/2μ₀) sech²(z/L) + p_b,
> and ∇ × B gives μ₀ J_y = (B₀/L) sech²(z/L). With A_y = −B₀ L ln cosh(z/L), B = ∇ × A.

> **Bennett pinch**
>
> With n = n₀/(1 + r²/a²)², the equation dp/dr = −J_z B_θ is solved by the enclosed current
> I(r) = I r²/(r² + a²), so B_θ = μ₀ I r / (2π (r² + a²)), and the Bennett relation
> μ₀ I² = 8π N k_B (T_e + T_i) holds for the line density N = π n₀ a².

> **Solov'ev equilibrium**
>
> With x = R/R₀, y = Z/R₀, ψ̂ = Ψ/Ψ₀ (Ψ the poloidal flux per radian, B_R = −∂_Z Ψ/R, B_Z =
> ∂_R Ψ/R, B_φ = F/R) and the Solov'ev profiles μ₀ R₀⁴ p'/Ψ₀² = −(1 − A), R₀² F F'/Ψ₀² = −A, the
> Grad–Shafranov equation Δ*ψ̂ = ψ̂_xx − ψ̂_x/x + ψ̂_yy = A + (1 − A) x² is linear. Its solution is
> ψ̂ = A y²/2 + (1 − A) x⁴/8 + Σᵢ cᵢ ψᵢ with the homogeneous solutions Δ*ψᵢ = 0 of Cerfon and
> Freidberg. The seven constants cᵢ make the up-down symmetric surface ψ̂ = 0 a "D" with inverse
> aspect ratio ε, elongation κ and triangularity δ, by the conditions at the outer and inner
> midplane points and the top point ``(1 − δε, κε)``: ψ̂ = 0 at all of them, ψ̂_x = 0 at the top and
> the curvatures ψ̂_yy = −N ψ̂_x (outer, inner) and ψ̂_xx = −N₃ ψ̂_y (top) of the boundary
> x = 1 + ε cos(τ + α sin τ), y = κ ε sin τ, with α = arcsin δ. The flux is negative inside, the
> pressure p = (1 − A) Ψ₀² (−ψ̂)/(μ₀ R₀⁴) is positive and F² = F₀² + 2A (Ψ₀/R₀)² (−ψ̂), where F₀ is
> the (vacuum) value at the boundary.

> **Force-free fields**
>
> The linear force-free field ∇ × B = α B in a cylinder is B_θ = B₀ J₁(α r), B_z = B₀ J₀(α r)
> (Lundquist). For a cylinder of radius a, the Taylor state, which minimises the magnetic energy
> at fixed helicity, is this field; its pinch parameter is Θ = B_θ(a)/⟨B_z⟩ = α a/2 and its
> reversal parameter F = B_z(a)/⟨B_z⟩ = α a J₀(α a) / (2 J₁(α a)) vanishes at α a = 2.405, the first
> zero of J₀ (Θ = 1.202).

> **References**
>
> H. Harris, "On a plane current sheet in a plasma", Nuovo Cimento 23, 115 (1962).
> 
> W. H. Bennett, "Magnetically self-focussing streams", Phys. Rev. 45, 890 (1934).
> 
> A. J. Cerfon and J. P. Freidberg, ""One size fits all" analytic solutions to the Grad–Shafranov
> equation", Phys. Plasmas 17, 032502 (2010). The paper itself was not available to read; the
> method (profiles, boundary conditions) is as I recall it, and the homogeneous solutions ψ₁ … ψ₇
> are from their restatement in arXiv:2609.15074, table 1. Both are verified here: Δ*ψᵢ = 0,
> the boundary shape, and the force balance are tested numerically.
> 
> J. P. Freidberg, Ideal MHD (Cambridge, 2014), chapters 6 and 9.
> 
> J. B. Taylor, "Relaxation of toroidal plasma and generation of reverse magnetic fields", Phys.
> Rev. Lett. 33, 1139 (1974).

**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):

```pycon
>>> 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
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L1-L1)

## plasma_plots.theory.equilibria.BennettPinch

*class* · *dataclass*

```python
class BennettPinch
```

The Bennett pinch.

**Attributes**

- `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⁻¹.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L262-L290)

### plasma_plots.theory.equilibria.BennettPinch.b_theta

*attribute* · *instance attribute*

```python
b_theta: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L286-L286)

### plasma_plots.theory.equilibria.BennettPinch.current_density

*attribute* · *instance attribute*

```python
current_density: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L287-L287)

### plasma_plots.theory.equilibria.BennettPinch.density

*attribute* · *instance attribute*

```python
density: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L284-L284)

### plasma_plots.theory.equilibria.BennettPinch.enclosed_current

*attribute* · *instance attribute*

```python
enclosed_current: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L288-L288)

### plasma_plots.theory.equilibria.BennettPinch.line_density

*attribute* · *instance attribute*

```python
line_density: float
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L290-L290)

### plasma_plots.theory.equilibria.BennettPinch.pressure

*attribute* · *instance attribute*

```python
pressure: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L285-L285)

### plasma_plots.theory.equilibria.BennettPinch.total_current

*attribute* · *instance attribute*

```python
total_current: float
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L289-L289)

## plasma_plots.theory.equilibria.HarrisSheet

*class* · *dataclass*

```python
class HarrisSheet
```

The Harris current sheet B = B₀ tanh(z/L) e_x.

**Attributes**

- `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⁻³.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L118-L143)

### plasma_plots.theory.equilibria.HarrisSheet.b_x

*attribute* · *instance attribute*

```python
b_x: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L138-L138)

### plasma_plots.theory.equilibria.HarrisSheet.current_density

*attribute* · *instance attribute*

```python
current_density: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L141-L141)

### plasma_plots.theory.equilibria.HarrisSheet.density

*attribute* · *instance attribute*

```python
density: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L139-L139)

### plasma_plots.theory.equilibria.HarrisSheet.peak_density

*attribute* · *instance attribute*

```python
peak_density: float
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L143-L143)

### plasma_plots.theory.equilibria.HarrisSheet.pressure

*attribute* · *instance attribute*

```python
pressure: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L140-L140)

### plasma_plots.theory.equilibria.HarrisSheet.vector_potential

*attribute* · *instance attribute*

```python
vector_potential: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L142-L142)

## plasma_plots.theory.equilibria.LundquistField

*class* · *dataclass*

```python
class LundquistField
```

The linear force-free field ∇ × B = α B in a cylinder.

**Attributes**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L782-L804)

### plasma_plots.theory.equilibria.LundquistField.b_theta

*attribute* · *instance attribute*

```python
b_theta: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L800-L800)

### plasma_plots.theory.equilibria.LundquistField.b_z

*attribute* · *instance attribute*

```python
b_z: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L801-L801)

### plasma_plots.theory.equilibria.LundquistField.current_density_theta

*attribute* · *instance attribute*

```python
current_density_theta: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L802-L802)

### plasma_plots.theory.equilibria.LundquistField.current_density_z

*attribute* · *instance attribute*

```python
current_density_z: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L803-L803)

### plasma_plots.theory.equilibria.LundquistField.pressure

*attribute* · *instance attribute*

```python
pressure: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L804-L804)

## plasma_plots.theory.equilibria.SolovevFields

*class* · *dataclass*

```python
class SolovevFields
```

The Solov'ev equilibrium on a grid of (R, Z).

**Attributes**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L553-L581)

### plasma_plots.theory.equilibria.SolovevFields.b_phi

*attribute* · *instance attribute*

```python
b_phi: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L579-L579)

### plasma_plots.theory.equilibria.SolovevFields.b_r

*attribute* · *instance attribute*

```python
b_r: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L577-L577)

### plasma_plots.theory.equilibria.SolovevFields.b_z

*attribute* · *instance attribute*

```python
b_z: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L578-L578)

### plasma_plots.theory.equilibria.SolovevFields.current_density_phi

*attribute* · *instance attribute*

```python
current_density_phi: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L581-L581)

### plasma_plots.theory.equilibria.SolovevFields.pressure

*attribute* · *instance attribute*

```python
pressure: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L580-L580)

### plasma_plots.theory.equilibria.SolovevFields.psi

*attribute* · *instance attribute*

```python
psi: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L576-L576)

### plasma_plots.theory.equilibria.SolovevFields.psi_normalized

*attribute* · *instance attribute*

```python
psi_normalized: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L575-L575)

## plasma_plots.theory.equilibria.TaylorState

*class* · *dataclass*

```python
class TaylorState
```

The pinch and reversal parameters of the Taylor state.

**Attributes**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L848-L861)

### plasma_plots.theory.equilibria.TaylorState.pinch

*attribute* · *instance attribute*

```python
pinch: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L860-L860)

### plasma_plots.theory.equilibria.TaylorState.reversal

*attribute* · *instance attribute*

```python
reversal: object
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L861-L861)

## plasma_plots.theory.equilibria.bennett_pinch

*function*

```python
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**

- `r` (`float or array_like`) — The radius, in m.
- `density0` (`float`) — The density n₀ on the axis, in m⁻³.
- `radius` (`float`) — The scale radius a, in m.
- `temperature_electron` (`float`) — The electron temperature, in eV.
- `temperature_ion` (`float`) — The 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.

> **References**
>
> W. H. Bennett, "Magnetically self-focussing streams", Phys. Rev. 45, 890 (1934).
> 
> J. P. Freidberg, Ideal MHD (Cambridge, 2014), section 6.2.

**Examples**

The current and the edge field of a 1e20 m⁻³, 1 mm pinch at T_e + T_i = 100 eV:

```pycon
>>> 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
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L293-L358)

## plasma_plots.theory.equilibria.harris_drift_speed

*function*

```python
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**

- `temperature` (`float or array_like`) — The temperature of the species, in eV.
- `b0` (`float`) — The asymptotic field B₀, in T.
- `thickness` (`float`) — The half thickness L, in m.

**Returns**

- (`float or numpy.ndarray`) — The drift speed in m/s.

> **References**
>
> H. Harris, "On a plane current sheet in a plasma", Nuovo Cimento 23, 115 (1962).

**Examples**

```pycon
>>> print(f"{harris_drift_speed(5.0, 0.01, 1.0):.4e} m/s")
1.0000e+03 m/s
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L227-L256)

## plasma_plots.theory.equilibria.harris_sheet

*function*

```python
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**

- `z` (`float or array_like`) — The coordinate across the sheet, in m.
- `b0` (`float`) — The asymptotic field B₀, in T.
- `thickness` (`float`) — The half thickness L, in m.
- `temperature_electron` (`float`) — The electron temperature, in eV.
- `temperature_ion` (`float`) — The ion temperature, in eV.
- `background_density` (`float`) (default: `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 ``thickness`` or the temperatures are not positive, or the background density is
negative.

> **See Also**
>
> [`harris_drift_speed()`][plasma_plots.theory.equilibria.harris_drift_speed] : The drifts that carry the current.

> **References**
>
> H. Harris, "On a plane current sheet in a plasma", Nuovo Cimento 23, 115 (1962).

**Examples**

The total pressure p + B²/2μ₀ is the same everywhere:

```pycon
>>> 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
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L152-L224)

## plasma_plots.theory.equilibria.lundquist_field

*function*

```python
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**

- `r` (`float or array_like`) — The radius, in m.
- `alpha` (`float`) — The force-free constant α in ∇ × B = α B, in 1/m.
- `b0` (`float`) (default: `1.0`) — The axial field on the axis, in T. Default: ``1.0``.

**Returns**

- (`LundquistField`) — B_θ, B_z, the current density and the (zero) pressure.

> **References**
>
> S. Lundquist, "Magneto-hydrostatic fields", Ark. Fys. 2, 361 (1950).

**Examples**

The field vanishes in B_z at the first zero of J₀, r = 2.405/α:

```pycon
>>> f = lundquist_field(2.404825557695773, 1.0)
>>> abs(float(f.b_z)) < 1e-12, round(float(f.b_theta), 6)
(True, 0.519147)
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L807-L845)

## plasma_plots.theory.equilibria.solovev

*function*

```python
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()`][plasma_plots.theory.equilibria.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**

- `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()`][plasma_plots.theory.equilibria.solovev_coefficients]), or ``r0``
≤ 0.

> **See Also**
>
> [`solovev_axis()`][plasma_plots.theory.equilibria.solovev_axis] : The magnetic axis.
> [`solovev_safety_factor_axis()`][plasma_plots.theory.equilibria.solovev_safety_factor_axis] : q on the axis.

> **References**
>
> A. J. Cerfon and J. P. Freidberg, Phys. Plasmas 17, 032502 (2010).
> 
> L. S. Solov'ev, "The theory of hydromagnetic stability of toroidal plasma configurations",
> Sov. Phys. JETP 26, 400 (1968).

**Examples**

The flux vanishes on the boundary and is negative on the axis:

```pycon
>>> 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
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L584-L675)

## plasma_plots.theory.equilibria.solovev_axis

*function*

```python
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**

- `epsilon` (`float`) — The inverse aspect ratio ε.
- `kappa` (`float`) — The elongation κ.
- `delta` (`float`) — The triangularity δ.
- `a_param` (`float`) — The constant A of the profiles.
- `r0` (`float`) (default: `1.0`) — The 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.

> **References**
>
> A. J. Cerfon and J. P. Freidberg, Phys. Plasmas 17, 032502 (2010).

**Examples**

The axis is shifted outward of the geometric centre 1:

```pycon
>>> print(f"{solovev_axis(0.32, 1.7, 0.33, -0.155):.4f}")
1.0513
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L678-L727)

## plasma_plots.theory.equilibria.solovev_boundary

*function*

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

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

**Parameters**

- `epsilon` (`float`) — The inverse aspect ratio ε.
- `kappa` (`float`) — The elongation κ.
- `delta` (`float`) — The triangularity δ, with α = arcsin δ.
- `tau` (`array_like`) (default: `None`) — The angles τ. Default: 129 points on [0, 2π].
- `r0` (`float`) (default: `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).

> **References**
>
> A. J. Cerfon and J. P. Freidberg, Phys. Plasmas 17, 032502 (2010).

**Examples**

The outer, top and inner points for ε = 0.3, κ = 1.5, δ = 0.2:

```pycon
>>> 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.  ]))
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L509-L550)

## plasma_plots.theory.equilibria.solovev_coefficients

*function*

```python
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**

- `epsilon` (`float`) — The inverse aspect ratio ε = a/R₀, in (0, 1).
- `kappa` (`float`) — The elongation κ > 0.
- `delta` (`float`) — The triangularity δ, in (−1, 1).
- `a_param` (`float`) — The 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).

> **See Also**
>
> [`solovev()`][plasma_plots.theory.equilibria.solovev] : The fields.

> **References**
>
> A. J. Cerfon and J. P. Freidberg, Phys. Plasmas 17, 032502 (2010).

**Examples**

The seven constants of an ITER-like shape:

```pycon
>>> c = solovev_coefficients(0.32, 1.7, 0.33, -0.155)
>>> c.shape
(7,)
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L429-L506)

## plasma_plots.theory.equilibria.solovev_safety_factor_axis

*function*

```python
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**

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

> **References**
>
> J. P. Freidberg, Ideal MHD (Cambridge, 2014), section 6.7.

**Examples**

```pycon
>>> print(
...     f"{solovev_safety_factor_axis(0.32, 1.7, 0.33, -0.155, 0.1, 1.0, 1.0):.4f}"
... )
18.8074
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L730-L776)

## plasma_plots.theory.equilibria.taylor_state

*function*

```python
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**

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

> **References**
>
> J. B. Taylor, Phys. Rev. Lett. 33, 1139 (1974).

**Examples**

Reversal sets in at Θ = 1.2024:

```pycon
>>> s = taylor_state(2.404825557695773)
>>> round(float(s.pinch), 4), abs(float(s.reversal)) < 1e-12
(1.2024, True)
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/theory/equilibria.py#L864-L896)
