geqdsk#

G-EQDSK files describe Grad-Shafranov tokamak plasma equilibria. These may be generated via a Grad-Shafranov solver, or by fitting to experimental measurements. Tools that make use of G-EQDSK files include, but are not limited to:

EFIT
FreeGS
SCENE
TRANSP

G-EQDSK files begin with a header line containing the following information:

A comment 48 characters in length. This normally includes information such as the software used to generate the file, the date of creation, a shot number, and the time frame within the shot. Unfortunately, the format of this line is not rigorously defined, so each code will tend to define it differently. FreeQDSK currently assumes a FreeGS-style comment, but this may be expanded to other comment styles in a future update.
A mysterious integer of unknown purpose, with a width of 4 characters.
The number of points in the R direction, expressed as an integer with a width of four characters.
The number of points in the Z direction, expressed as an integer with a width of four characters.

The Fortran format for the header can be expressed (a48,3i4). This is followed by 4 lines of floats describing a tokamak plasma equilibrium. Each line contains 5 floats, following the Fortran format (5e16.9). These floats are:

rdim	zdim	rcentr	rleft	zmid
rmagx	zmagx	simagx	sibdry	bcentr
cpasma	simagx		rmagx
zmagx		sibdry

The blank spaces are ignored, and are usually set to zero. Note that rmagx, zmagx, simagx, and sibdry are duplicated. The meaning of these floats are:

rdim	Width of computational domain in R direction, float [meter]
zdim	Height of computational domain in Z direction, float [meter]
rcentr	Reference value of R, float [meter]
rleft	R at left (inner) boundary, float [meter]
zmid	Z at middle of domain, float [meter]
rmagx	R at magnetic axis (0-point), float [meter]
zmagx	Z at magnetic axis (0-point), float [meter]
simagx	Poloidal flux \(\psi\) at magnetic axis, float [weber / radian]
sibdry	Poloidal flux \(\psi\) at plasma boundary, float [weber / radian]
bcentr	Vacuum toroidal magnetic field at rcentr, float [tesla]
cpasma	Plasma current, float [ampere]

This is then followed by a series of grids:

fpol	Poloidal current function \(F(\psi)=RB_t\), 1D array [meter * tesla]
pres	Plasma pressure \(p(\psi)\), 1D array [pascal]
ffprime	\(FF'(\psi)=RB_t\), 1D array [meter*2 tesla*2 radian / weber]
pprime	\(p'(\psi)\), 1D array [pascal * radian / weber]
psi	Poloidal flux \(\psi\), 2D array [weber / radian]
qpsi	Safety factor \(q(\psi)\), 1D array [dimensionless]

The 1D arrays are expressed on a linearly spaced \(\psi\) grid which may be generated using numpy.linspace(simagx, sibdry, nx). The 2D \(\psi\) grid is instead expressed on a linearly spaced grid extending the range [rleft, rleft + rdim] in the R direction and [zmid - zdim/2, zmid + zdim/2] in the Z direction. Each grid is printed over multiple lines using the Fortran format (5e16.9), with the final line containing some blank spaces if the total grid size is not a multiple of 5. Note that the psi grid is expressed in a flattened state using Fortran ordering, meaning it increments in the columns direction first, then in rows.

The G-EQDSK file then gives information on the plasma boundary and the surrounding limiter contour. The next line gives the dimensions of these grids in the format (2i5):

nbdry	Number of points in the boundary grid, int
nlim	Number of points in the limiter grid, int

Finally, the boundary and limiter grids are specified as lists of (R, Z) coordinates, again using the format (5e16.9):

rbdry	R of boundary points, 1D array [meter]
zbdry	Z of boundary points, 1D array [meter]
rlim	R of limiter points, 1D array [meter]
zlim	Z of limiter points, 1D array [meter]

Note that these grids are interleaved, so are expressed as:

`rbdry[0]`	`zbdry[0]`	`rbdry[1]`	`zbdry[1]`	`rbdry[2]`
`zbdry[2]`	`rbdry[3]`	`zbdry[3]`	`rbdry[4]`	`rbdry[4]`
…	…	…	…	…

SPDX-License-Identifier: MIT

geqdsk.read(cocos=1, header_fmt=None, data_fmt=None, bdry_lim_fmt=None)#

Read a G-EQDSK formatted equilibrium file. The format is specified here.

Parameters:

fh (TextIO) – File handle to read from. Should be opened in a text read mode, i.e. open(filename, "r").
cocos (int (default: 1)) – COordinate COnventionS. This feature is not fully handled yet, and only determines whether psi is divided by \(2\pi\) or not. If cocos >= 10, \(\psi\) is divided by \(2\pi\), and otherwise it is left unchanged. See Sauter et al, 2013.
header_fmt (Optional[str] (default: None)) – Fortran IO format for G-EQDSK header line. If not provided, uses (a48,3i4), corresponding to a comment, a dummy int, nx, and ny.
data_fmt (Optional[str] (default: None)) – Fortran IO format for G-EQDSK data. If not provided, uses (5e16.9).
bdr_lim_fmt – Fortran IO format specifying the lengths of the boundary/limiter grids. If not provided, defaults to (2i5)

Warns:

UserWarning – If any of the entries that are duplicated in the file do not match. These include ‘rmagx’, ‘zmagx’, ‘simagx’ and ‘sibdry’. The value returned will be the last found.

Return type:

Dict[str, Union[int, float, ndarray]]

geqdsk.write(fh, label=None, shot=0, time=0, header_fmt=None, data_fmt=None, bdry_lim_fmt=None)#

Write a G-EQDSK equilibrium file, given a dictionary of data.

Parameters:

data (Dict[str, Union[float, int, _SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) – G-EQDSK data to write. See the ‘Notes’ section below for info.
fh (TextIO) – File handle to write to. Should be opened in a text write mode, i.e. open(filename, "w").
label (Optional[str] (default: None)) – Text label to put in the file. Defaults to ‘FREEGS’ if not provided.
shot (int (default: 0)) – Shot number to put in the file.
time (int (default: 0)) – Time in milliseconds to put in the file.
header_fmt (Optional[str] (default: None)) – Fortran IO format for G-EQDSK header line. If not provided, uses (a48,3i4), corresponding to a comment, a dummy int, nx, and ny.
data_fmt (Optional[str] (default: None)) – Fortran IO format for G-EQDSK data. If not provided, uses (5e16.9).
bdry_lim_fmt (Optional[str] (default: None)) – Fortran IO format specifying the lengths of the boundary/limiter grids. If not provided, defaults to (2i5).

Raises:

KeyError – If required information is missing from data.
ValueError – If the provided arrays have incorrect dimensions, or if the data provided is of the wrong type.

Notes

Return type:: None

ffprime and pprime may be excluded from data, in which case they will be filled with zeros. Similarly, rbdry, zbdry, rlim and zlim may be excluded, in which case they aren’t added to the end of the file. If nbdry and nlim are excluded, they are inferred from rbdry and rlim, and are set to zero if these aren’t found. Similarly, if nx or ny are excluded, they are inferred from psi, which should have the shape (nx, ny).

geqdsk

Contents

geqdsk#