SOL Box Model

Reduced-physics 0D model of the tokamak Scrape-Off Layer (SOL). Given core power and particle fluxes plus magnetic geometry, it returns upstream (outer midplane, OMP) and divertor target plasma conditions.

Based on Zhang et al. (2023) [1] and Goldston (2012) [2].

Installation

We recommend using uv to run this code.

git clone git@github.com:Next-Step-Fusion/sol-box-model.git
cd sol_box_model
uv sync
uv pip install -e .

Quick Start

For standalone run:

uv run run_standalone.py

For run from given equilibrium:

uv run run_from_equilibrium.py

For run of benchmark notebook use python kernel from .venv

Geometry Utilities (src/utils.py)

Two functions compute the geometry inputs for BoxModel directly from a magnetic equilibrium:

sol_width_heuristic_drift

Computes the SOL heat-flux decay length from the Goldston Heuristic Drift model [2]:

Parameter	Units	Description
P_sol	W	Total power entering the SOL
kappa	—	Plasma elongation
R0	m	Major radius
a0	m	Minor radius
Ip	A	Plasma current
Bt0	T	On-axis toroidal field
Zeff	—	Effective ion charge
A	amu	Ion mass number
Z	—	Ion charge number

Returns sol_width [m] (= 2 λ_q).

sol_geometry_from_equilibrium

Traces the SOL flux surface from the equilibrium ψ(R,Z) grid and returns geometry parameters for BoxModel:

Parameter	Units	Description
sol_width	m	SOL width (from sol_width_heuristic_drift or manually set)
R, Z	m	1D equilibrium grid coordinates
psi	Wb	2D total poloidal flux on the (R,Z) grid
psi_axis	Wb	Total poloidal flux at the magnetic axis
psi_sep	Wb	Total poloidal flux at the separatrix
limiter	m	(N,2) array of first-wall (R,Z) coordinates
magnetic_axis	m	(R,Z) position of the magnetic axis
x1_point	m	(R,Z) position of the primary X-point
x2_point	m	(R,Z) position of the secondary X-point
toroidal_field	T	On-axis toroidal field Bt0
major_radius	m	Major radius R0

Returns (R_sep_omp, L_par, f_R, extras).

Input Parameters Reference

Electron Channel

Parameter	Units	Description
epower_in	W	Power carried by electrons into the SOL
eflux_in	particles/s	Electron particle flux into the SOL
epower_loss_factor	—	Volumetric power loss fraction (0 = no loss, 1 = all power lost)

Ion Channel

Parameter	Units	Description
Ai	amu	Ion mass number
Zi	—	Ion charge number
ipower_in	W	Ion power into the SOL
iflux_in	particles/s	Ion particle flux into the SOL
ipower_loss_factor	—	Ion volumetric power loss fraction (0 = no loss, 1 = all power lost)

Single-Fluid Quantities

Parameter	Units	Description
recycling	—	Recycling coefficient R ∈ [0, 1). Set transmission rate γ_particles = 1 − R
momentum_loss_factor	—	Momentum transmission (1 = no loss, < 1 = losses).
conduction_loss_fraction	—	Conduction fraction (1 = full conduction, < 1 = losses).

Geometry

Parameter	Units	Description
sol_width	m	Radial SOL width at the OMP
R_sep_omp	m	Major radius of the separatrix at the OMP
L_par	m	Parallel connection length from OMP to target
f_R	—	Flux expansion factor (> 1)

Output Parameters

After calling BoxModel.solve():

Attribute	Units	Description
Te_omp	eV	Electron temperature at OMP
Ti_omp	eV	Ion temperature at OMP
ne_omp	m⁻³	Electron density at OMP
ni_omp	m⁻³	Ion density at OMP
Te_div	eV	Electron temperature at divertor target
Ti_div	eV	Ion temperature at divertor target
ne_div	m⁻³	Electron density at divertor target
ni_div	m⁻³	Ion density at divertor target

Reference:

[1] X. Zhang, F. M. Poli, E. D. Emdee & M. Podestà, "Reduced physics model of the tokamak Scrape-Off-Layer for pulse design," Nucl. Mater. Energy 34, 101354 (2023). https://doi.org/10.1016/j.nme.2022.101354

[2] R. J. Goldston, "Heuristic drift-based model of the power scrape-off width in low-gas-puff H-mode tokamaks," Nucl. Fusion 52, 013009 (2012). https://doi.org/10.1088/0029-5515/52/1/013009