OpenFUSIONToolkit.TokaMaker.eqdsk Namespace Reference

Detailed Description

GEQDSK (g-file) and Osborne p-file (kinetic profile) readers and writers.

Reads standard GEQDSK equilibrium files and computes flux-surface-averaged quantities, and reads/writes Osborne p-files for kinetic profiles. Adapted from OMFIT omfit_eqdsk / omfit_osborne with no OMFIT runtime dependency.

Dependencies: numpy, scipy, contourpy (ships with matplotlib).

Authors

Daniel Burgess

Date

April 2026

Classes
class	GEQDSKEquilibrium
	GEQDSK equilibrium with flux-surface-averaged quantities. More...
class	PFile
	Interface for Osborne p-file kinetic profiles. More...

Functions
	_cocos_params (cocos_index)
	Return COCOS sign/exponent parameters for a given COCOS index.
	_crop_at_xpoint (seg, R0, Z0)
	Crop an open separatrix contour at the X-point to produce a closed LCFS.
	_detect_xpoint_angle (R, Z, R0, Z0)
	Detect the X-point angle on a separatrix contour.
	_flux_geometry (R, Z)
	Compute geometric properties of a single flux-surface contour.
	_read_geqdsk (filename)
	Parse a GEQDSK (g-file) into a plain dict.
	_read_pfile (filename)
	Parse an Osborne p-file into an OrderedDict.
	_resample_contour (R, Z, npts=257, periodic=True)
	Resample a closed contour to npts equally-spaced-in-arc-length points.
	_resample_contour_theta (R, Z, R0, Z0, npts=257, theta_xpt=None)
	Resample a closed contour to npts equally-spaced-in-angle points.
	_select_main_contour (segments, R0, Z0, sigma_RpZ, sigma_rhotp)
	Select the main closed contour encircling the magnetic axis.
	_trace_contours (R, Z, PSI, levels)
	Extract contour lines of \(\psi\) at given levels using contourpy.
	_write_fortran_block (stream, values)
	Write values in standard GEQDSK format (5 per line, 16 chars each).
	_write_geqdsk_to_stream (g, stream)
	Serialise a raw g-file dict g to an open text stream.
	_write_pfile (profiles, filename)
	Write an OrderedDict of profiles to an Osborne p-file.
	read_geqdsk (filename, cocos=1, nlevels=None, resample="theta", extrapolate_edge=True)
	Read a GEQDSK file and return a GEQDSKEquilibrium object.
	read_pfile (filename)
	Read an Osborne p-file and return a PFile object.
	write_geqdsk (g, filename)
	Write a raw g-file dict to filename.

Variables
float	_NT_TO_KPA = 1.602176634e-19 * 1e20
	_PFILE_HEADER_RE
	PFILE_DESCRIPTIONS
	PFILE_UNITS

Function Documentation

_cocos_params()

_cocos_params ( cocos_index )

protected

Return COCOS sign/exponent parameters for a given COCOS index.

Parameters

cocos_index

COCOS convention index (1-8 or 11-18)

Returns

Dict with keys: sigma_Bp, sigma_RpZ, sigma_rhotp, exp_Bp

_crop_at_xpoint()

_crop_at_xpoint ( seg, R0, Z0 )

protected

Crop an open separatrix contour at the X-point to produce a closed LCFS.

Parameters

seg	(N,2) open contour segment with columns (R, Z)
R0	Magnetic axis R [m]
Z0	Magnetic axis Z [m]

Returns

(M,2) closed contour (first point == last point)

_detect_xpoint_angle()

_detect_xpoint_angle ( R, Z, R0, Z0 )

protected

Detect the X-point angle on a separatrix contour.

Finds the location of the sharpest bend (minimum cosine of angle between adjacent tangent vectors) and returns \(\theta = \mathrm{atan2}(Z-Z_0, R-R_0)\) at that point.

Parameters

R	1-D array of separatrix R coordinates (nearly closed)
Z	1-D array of separatrix Z coordinates (nearly closed)
R0	Magnetic axis R [m]
Z0	Magnetic axis Z [m]

Returns

Poloidal angle \(\theta\) of the X-point, or None if detection fails

_flux_geometry()

_flux_geometry ( R, Z )

protected

Compute geometric properties of a single flux-surface contour.

Parameters

R	1-D array of contour R coordinates (closed: first == last, or nearly so)
Z	1-D array of contour Z coordinates (closed: first == last, or nearly so)

Returns

Dict with keys R (geometric center), Z, a (minor radius), kappa, kapu, kapl, delta, delu, dell, perimeter, surfArea, eps

_read_geqdsk()

_read_geqdsk ( filename )

protected

Parse a GEQDSK (g-file) into a plain dict.

Parameters

filename

Path to the g-file

Returns

Dict whose keys match the standard GEQDSK field names (NW, NH, RDIM, ..., FPOL, PRES, FFPRIM, PPRIME, PSIRZ, QPSI, RBBBS, ZBBBS, etc.)

_read_pfile()

_read_pfile ( filename )

protected

Parse an Osborne p-file into an OrderedDict.

Parameters

filename

Path to the p-file

Returns

OrderedDict keyed by profile name ("ne", "te", ...). Each value is a dict with keys "psinorm", "data", "derivative", "units", and "deriv_label". The special key "N Z A" (if present) maps to a dict with "N", "Z", "A" arrays.

_resample_contour()

_resample_contour ( R, Z, npts = 257, periodic = True )

protected

Resample a closed contour to npts equally-spaced-in-arc-length points.

Parameters

R	1-D array of contour R coordinates (nearly closed: first \(\approx\) last)
Z	1-D array of contour Z coordinates (nearly closed: first \(\approx\) last)
npts	Number of output points (including the repeated closing point)
periodic	If True (default), use a periodic cubic spline. Set to False for the separatrix surface where the X-point cusp produces a derivative discontinuity.

Returns

Tuple (R_new, Z_new) of 1-D arrays of length npts

_resample_contour_theta()

_resample_contour_theta ( R, Z, R0, Z0, npts = 257, theta_xpt = None )

protected

Resample a closed contour to npts equally-spaced-in-angle points.

Fits periodic cubic splines \(R(\theta)\) and \(Z(\theta)\) where \(\theta = \mathrm{atan2}(Z-Z_0, R-R_0)\), sorted starting from the X-point angle.

Parameters

R	1-D array of contour R coordinates (nearly closed)
Z	1-D array of contour Z coordinates (nearly closed)
R0	Magnetic axis R [m]
Z0	Magnetic axis Z [m]
npts	Number of output points (including the repeated closing point)
theta_xpt	Pre-computed X-point angle; if None, detected from this contour

Returns

Tuple (R_new, Z_new) of 1-D arrays of length npts

_select_main_contour()

_select_main_contour ( segments, R0, Z0, sigma_RpZ, sigma_rhotp )

protected

Select the main closed contour encircling the magnetic axis.

Uses the winding / angular-coverage criterion: the contour whose double integral of angle vs. arc-fraction has the largest amplitude is most likely the one that wraps around the axis.

Parameters

segments	List of (N,2) candidate contour segments at a single \(\psi\) level
R0	Magnetic axis R [m]
Z0	Magnetic axis Z [m]
sigma_RpZ	COCOS right-handedness sign
sigma_rhotp	COCOS \(\theta_{\mathrm{pol}}\cdot\phi_{\mathrm{tor}}\) sign

Returns

(N,2) ndarray of the selected contour with correct orientation, or None

_trace_contours()

_trace_contours ( R, Z, PSI, levels )

protected

Extract contour lines of \(\psi\) at given levels using contourpy.

Parameters

R	1-D array of R grid coordinates [m]
Z	1-D array of Z grid coordinates [m]
PSI	2-D array (len(Z) x len(R)) of poloidal flux on the grid [Wb]
levels	1-D array of \(\psi\) values at which to extract contours

Returns

List (one per level) of lists of (N,2) arrays of (R,Z) points

_write_fortran_block()

_write_fortran_block ( stream, values )

protected

Write values in standard GEQDSK format (5 per line, 16 chars each).

Parameters

stream	Open text stream to write to
values	1-D sequence of floats to serialise

_write_geqdsk_to_stream()

_write_geqdsk_to_stream ( g, stream )

protected

Serialise a raw g-file dict g to an open text stream.

Parameters

g	Raw g-file dict (as produced by _read_geqdsk)
stream	Open text stream to write to

_write_pfile()

_write_pfile ( profiles, filename )

protected

Write an OrderedDict of profiles to an Osborne p-file.

Parameters

profiles	OrderedDict with the same structure as returned by _read_pfile
filename	Output path for the p-file

read_geqdsk()

read_geqdsk	(		filename,
			cocos = 1,
			nlevels = None,
			resample = "theta",
			extrapolate_edge = True )

Read a GEQDSK file and return a GEQDSKEquilibrium object.

Parameters

filename	Path to the g-file
cocos	COCOS convention index (default 1)
nlevels	Number of \(\hat{\psi}\) levels for flux-surface analysis
resample	Contour resampling method ("theta" or "arc_length")
extrapolate_edge	If True (default), extrapolate \(p'\) and \(FF'\) at the separatrix when the g-file has them forced to zero

Returns

GEQDSKEquilibrium instance

read_pfile()

read_pfile

(

filename

)

Read an Osborne p-file and return a PFile object.

Parameters

filename

Path to the p-file

Returns

PFile instance

write_geqdsk()

write_geqdsk	(		g,
			filename )

Write a raw g-file dict to filename.

Parameters

g	Raw g-file dict (as produced by _read_geqdsk)
filename	Output path for the g-file

Variable Documentation

_NT_TO_KPA

float _NT_TO_KPA = 1.602176634e-19 * 1e20

protected

_PFILE_HEADER_RE

_PFILE_HEADER_RE

protected

Initial value:

=  re.compile(
    r"^(\d+)\s+(\S+)\s+(\S+)\‍(([^)]*)\‍)\s+(.*?)\s*$"
)

PFILE_DESCRIPTIONS

PFILE_DESCRIPTIONS

PFILE_UNITS

PFILE_UNITS