Outputs
This page explains the output file formats for equilibrium solutions computed by DESC.
ASCII
The text output are ASCII files with the naming convention
output.FILE_NAME
. All of the necessary variables to fully define an
equilibrium solution are output in the following order: grid parameters,
fixed-boundary shape, pressure and rotational transform profiles, flux
surface shapes, and the boundary function \(\lambda\). An example
output file is included for reference at the end of this document. All
integers are printed with a total width of 3 characters, and all
floating point numbers are printed in exponential notation with a total
width of 16 characters including 8 digits after the decimal points.
Grid Parameters
The first two lines of the output file specify some global parameters: next four lines contain the following information in order:
NFP
(integer): number of field periodsPsi
(float): total toroidal magnetic flux through the last closed flux surface, \(\psi_a\), in Webers
Fixed-Boundary Shape
The target shape of the plasma boundary is output for reference in the
section of the output file with the heading Nbdry
. This gives the number
of boundary terms, followed by the coefficients. This is the fixed-boundary
input that was used to compute the equilibrium, but the
last closed flux surface generally does not match this desired shape
exactly. The shape of the boundary surface is given as a double Fourier
series of the form:
The Fourier coefficients \(R^{b}_{mn}\) and \(Z^{b}_{mn}\) are
given by the output variables bR
and bZ
, respectively. The
poloidal and toroidal mode numbers \(m\) and \(n\) that identify
each coefficient are given by the variables m
and n
on the same
line of the output file as bR
and bZ
. When stellarator symmetry
is enforced, only the \(R^{b}_{mn}\) with \(mn > 0\) and the
\(Z^{b}_{mn}\) with \(mn < 0\) are nonzero. Coefficients with
\(mn = 0\) are nonzero for \(R^{b}_{mn}\) if one of the mode
numbers is positive, and nonzero for \(Z^{b}_{mn}\) if one of the
mode numbers is negative. The boundary surface given in the example is
equivalent to (using Ptolemy’s identities):
Pressure & Rotational Transform Profiles
The pressure and rotational transform profiles that were used to compute
the equilibrium are also output for reference in the section of the
output file with the heading Nprof
, which also gives the number of profile
coefficients. These are given as a power series in the flux surface label
\(\rho \equiv \sqrt{\psi / \psi_a}\) as follows:
The coefficients \(p_{l}\) and \(\iota_{l}\) are given by the
output variables cP
and cI
, respectively. The radial order
\(l\) that identifies each coefficient is given by the variable
l
on the same line of the output file as cP
and cI
. The
profiles given in the example are:
Flux Surface Shapes
The shapes of the flux surfaces are the solution to the equilibrium defined by the fixed-boundary and profile inputs. They are given by a Fourier-Zernike basis set with “fringe” indexing of the form:
where \(L = |m|, |m|+2, |m|+4, \ldots, 2 M\). \(\mathcal{F}^{n}(\zeta)\) is the toroidal Fourier series defined as
\(\mathcal{Z}^{m}_{l}(\rho,\vartheta)\) are the Zernike polynomials defined on the unit disc \(0\leq\rho\leq1\), \(\vartheta\in[0,2\pi)\) as
with the radial function
The Fourier-Zernike coefficients \(R_{mn}\) and \(Z_{mn}\) are
given by the variables cR
and cZ
, respectively, in the section
of the output file with the heading NRZ
(which gives the total number
of values). The indices \(l\), \(m\), and \(n\) that identify
each coefficient are given by the variables l
, m
, and n
on
the same line of the output file as cR
and cZ
.
When stellarator symmetry is enforced,
only the \(R_{mn}\) with \(mn > 0\) and the \(Z_{mn}\) with
\(mn < 0\) are nonzero. Coefficients with \(mn = 0\) are nonzero
for \(R_{mn}\) if one of the mode numbers is positive, and nonzero
for \(Z_{mn}\) if one of the mode numbers is negative. Lines 45-46
of the example output file give the terms
The magnetic field is computed in the straight field-line coordinate system \((\rho,\vartheta,\zeta)\) by
The covariant basis vectors are defined as
and the Jacobian of the coordinate system is \(\sqrt{g} = {\mathbf e}_{\rho}\cdot{\mathbf e}_{\vartheta}\times{\mathbf e}_{\zeta}\). The partial derivatives of \(R(\rho,\vartheta,\zeta)\) and \(Z(\rho,\vartheta,\zeta)\) are known analytically from the basis functions. The components of the magnetic field in the toroidal coordinate system \((R,\phi,Z)\) can be easily computed as \(B_i = \mathbf{B} \cdot \mathbf{e}_i\) with \({\mathbf e}_{R}= [1, 0, 0]^T\), \({\mathbf e}_{\phi}= [0, 1, 0]^T\), and \({\mathbf e}_{Z}= [0, 0, 1]^T\).
Boundary Function \(\lambda\)
The straight field-line angle \(\zeta\) is equivalent to the toroidal angle by definition: \(\zeta = \phi\). The function \(\lambda(\theta,\phi)\) relates the straight field-line angle \(\vartheta\) to the poloidal angle used to define the boundary surface \(\theta\) through the equation \(\vartheta = \theta + \lambda(\theta,\phi)\). It is used internally to enforce the boundary condition at the last closed flux surface, and is output for reference. The function is given as a doubles Fourier series of the form:
where \(\mathcal{G}^{m}_{n}(\theta,\phi)\) was defined above for the
boundary shape. The Fourier coefficients \(\lambda_{mn}\) are
given by the variable cL
in the section of the output file with the
heading NL
(which gives the number of \(\lambda\) coefficients).
Their output format follows the same convention as
the boundary coefficients bR
and bZ
. When stellarator symmetry
is enforced, only the coefficients with \(mn < 0\) are nonzero.
Coefficients with \(mn = 0\) are nonzero if one of the mode numbers
is negative.
Example Output File
NFP = 3
Psi = 1.00000000E+00
Nbdry = 7
m: 0 n: 0 bR = 1.00000000E+01 bZ = 0.00000000E+00
m: 1 n: 0 bR = -1.00000000E+00 bZ = 0.00000000E+00
m: -1 n: 0 bR = 0.00000000E+00 bZ = 1.00000000E+00
m: 1 n: 1 bR = -3.00000000E-01 bZ = 0.00000000E+00
m: -1 n: -1 bR = -3.00000000E-01 bZ = 0.00000000E+00
m: -1 n: 1 bR = 0.00000000E+00 bZ = -3.00000000E-01
m: 1 n: -1 bR = 0.00000000E+00 bZ = 3.00000000E-01
Nprof = 5
l: 0 cP = 3.40000000E+03 cI = 5.00000000E-01
l: 1 cP = 0.00000000E+00 cI = 0.00000000E+00
l: 2 cP = -6.80000000E+03 cI = 1.50000000E+00
l: 3 cP = 0.00000000E+00 cI = 0.00000000E+00
l: 4 cP = 3.40000000E+03 cI = 0.00000000E+00
NRZ = 27
l: 0 m: 0 n: -1 cR = 0.00000000E+00 cZ = -2.90511418E-03
l: 0 m: 0 n: 0 cR = 9.98274712E+00 cZ = 0.00000000E+00
l: 0 m: 0 n: 1 cR = -2.90180674E-03 cZ = 0.00000000E+00
l: 1 m: -1 n: -1 cR = 2.28896490E-01 cZ = 0.00000000E+00
l: 1 m: -1 n: 0 cR = 0.00000000E+00 cZ = 9.48092222E-01
l: 1 m: -1 n: 1 cR = 0.00000000E+00 cZ = -2.27403979E-01
l: 2 m: 0 n: -1 cR = 0.00000000E+00 cZ = -2.41707137E-02
l: 2 m: 0 n: 0 cR = -1.36531448E-01 cZ = 0.00000000E+00
l: 2 m: 0 n: 1 cR = -2.41387024E-02 cZ = 0.00000000E+00
l: 1 m: 1 n: -1 cR = 0.00000000E+00 cZ = 2.24346193E-01
l: 1 m: 1 n: 0 cR = 9.25944834E-01 cZ = 0.00000000E+00
l: 1 m: 1 n: 1 cR = 2.25843613E-01 cZ = 0.00000000E+00
l: 2 m: -2 n: -1 cR = 3.34519544E-02 cZ = 0.00000000E+00
l: 2 m: -2 n: 0 cR = 0.00000000E+00 cZ = 1.58172393E-01
l: 2 m: -2 n: 1 cR = 0.00000000E+00 cZ = -5.03483447E-02
l: 3 m: -1 n: -1 cR = 4.81316537E-02 cZ = 0.00000000E+00
l: 3 m: -1 n: 0 cR = 0.00000000E+00 cZ = 3.38024112E-02
l: 3 m: -1 n: 1 cR = 0.00000000E+00 cZ = -4.74860303E-02
l: 4 m: 0 n: -1 cR = 0.00000000E+00 cZ = 2.08609498E-02
l: 4 m: 0 n: 0 cR = 1.33345992E-01 cZ = 0.00000000E+00
l: 4 m: 0 n: 1 cR = 2.07783052E-02 cZ = 0.00000000E+00
l: 3 m: 1 n: -1 cR = 0.00000000E+00 cZ = 5.20291455E-02
l: 3 m: 1 n: 0 cR = 7.29416666E-02 cZ = 0.00000000E+00
l: 3 m: 1 n: 1 cR = 5.26674681E-02 cZ = 0.00000000E+00
l: 2 m: 2 n: -1 cR = 0.00000000E+00 cZ = 5.01543691E-02
l: 2 m: 2 n: 0 cR = 1.56388795E-01 cZ = 0.00000000E+00
l: 2 m: 2 n: 1 cR = 3.32590868E-02 cZ = 0.00000000E+00
NL = 12
m: -2 n: -1 cL = -0.00000000E+00
m: -2 n: 0 cL = 9.55435813E-03
m: -2 n: 1 cL = 2.53333116E-02
m: -1 n: -1 cL = -0.00000000E+00
m: -1 n: 0 cL = 9.91996517E-02
m: -1 n: 1 cL = -1.17417875E-02
m: 0 n: -1 cL = 1.75103748E-04
m: 0 n: 0 cL = -0.00000000E+00
m: 0 n: 1 cL = -0.00000000E+00
m: 1 n: -1 cL = 1.16506641E-02
m: 1 n: 0 cL = -0.00000000E+00
m: 1 n: 1 cL = -0.00000000E+00
HDF5
By default, DESC saves to the hdf5 self-describing binary format [1], [2]
(“.h5” file extension). The file contains all information necessary to reconstruct
the python object that was saved. The file structure will depend slightly upon which
object was saved (all objects in DESC have a save
method), but generally all
objects will contain the following fields:
__class__
: name of the python class of the object__version__
: which version of DESC created the file
Other fields in the hdf5 file will depend on the type of object, with each attribute
of the python object being stored as a data field in the hdf5 file (specifically,
all attributes listed in a classes _io_attrs_
property). These may be nested
objects, such as an EquilibriaFamily that has the attribute _equilibria
which is
a list containing the individual equilibria in the family, and is then indexed by
number, for example ../_equilibria/0
, or an Equilibrium which contains objects
for the pressure and iota profiles and spectral bases for R, Z and \(\lambda\).
In general, all names in the hdf5 file will mirror the python attributes, but with a
leading underscore. For example, eq.R_lmn
will be stored as ../_R_lmn
.
Below are some examples of common data items and where to find them within a saved Equilibrium:
Spectral coefficients for R, Z, \(\lambda\):
/_R_lmn
/_Z_lmn
/_L_lmn
Mode numbers corresponding to spectral coefficients:
/_R_basis/_modes
/_Z_basis/_modes
/_L_basis/_modes
Profile coefficients:
/_pressure/_params
/_iota/_params
Number of field periods:
/_NFP
Total toroidal flux:
/_Psi
Boundary Fourier coefficients:
/_surface/_R_lmn
/_surface/_Z_lmn
Boundary mode numbers:
/_surface/_R_basis/_modes
/_surface/_Z_basis/_modes
A saved hdf5 file can be loaded with desc.io.load
, and it will return a
reconstruction of the object(s) saved within. Some data may not be saved (fields not
in _io_attrs_
), generally things that require large amounts of memory but are
trivially recomputable (i.e., transform matrices).
DESC also has the option of saving to python’s standard binary format, known as
pickle
[3] (“.pkl” file extension). The internal structure of this is somewhat
more complicated than hdf5 and is meant only for saving and loading data between
python environments.
The developers strive to maintain backwards and forwards compatibility with saved data, so that equilibria computed in an older version of the code can be loaded in a newer version and vice versa, but we make no guarantees at this time.