Magnetic fields

To learn about how magnetic fields are configured in SOFT, check out @MagneticField.

Magnetic fields in SOFT come in two flavours: analytical and numerical. The former allows the user to specify common properties of the magnetic field, such as its on-axis strength and major radius, and generates a corresponding magnetic field with circular flux surfaces. The latter takes a numerical representation of a 2D magnetic field as input, and permits more complicated magnetic equilibria.

Analytical magnetic field

The analytical magnetic field in SOFT is defined as

\[B(r,\theta) = \frac{B_0 R_{\rm m}}{R_{\rm m} - r\cos\theta}\left( \frac{r\sigma_I}{q(r)R_{\rm m}} \hat{\boldsymbol{\theta}} + \sigma_B\hat{\boldsymbol{\varphi}} \right).\]

Here, \(r\) denotes minor radius, \(\theta\) denotes poloidal angle, and \(\hat{\boldsymbol{\theta}}\) and \(\hat{\boldsymbol{\varphi}}\) are unit vectors in the poloidal and toroidal directions respectively. The parameters of the magnetic field that must be specified by the user are the on-axis field strength \(B_0\), the major radius \(R_{\rm m}\), the safety factor \(q(r)\) and the toroidal field sign \(\sigma_B\).

The radial profile of the safety factor can take four different forms in SOFT:

\[ \begin{align}\begin{aligned}q_{\rm const}(r) &= q_{a1},\\q_{\rm lin}(r) &= q_{a1} r/r_0 + q_{a2},\\q_{\rm quad}(r) &= q_{a1} (r/r_0)^2 + q_{a2},\\q_{\rm exp}(r) &= e^{q_{a1} r/r_0} + q_{a2},\\q_{\rm curr}(r) &= \frac{q_{a1}}{1 - \frac{2}{n+2}\left(\frac{r}{r_0}\right)^{q_{a2}}},\end{aligned}\end{align} \]

where \(r_0\) is the tokamak minor radius, \(r\) is the minor radius coordinate, ranging between 0 and \(r_0\), and \(q_{a1}\) and \(q_{a2}\) are constants set by the user.

Relation to plasma current (density)

The safety factor denoted \(q_{\rm curr}(r)\) above is the safety factor resulting from a plasma current density of the form

\[\boldsymbol{j} = \sigma_I\hat{\boldsymbol{\varphi}}j(r) = \sigma_I\hat{\boldsymbol{\varphi}} j_0\left[ 1 - \left(\frac{r}{r_0}\right)^{q_{a2}} \right].\]

where \(j_0\) is the central current density. The parameter \(q_{a1}\) is interpreted as the on-axis safety factor, and is related to the central current density through

\[q_{a1} = \frac{2B_0}{\mu_0 j_0 R_{\rm m}}.\]

From this, we can also relate the total plasma current \(I\) the central safety factor \(q_0\equiv q(0)\equiv q_{a1}\):

\[I = \frac{2\pi B_0}{\mu_0 q_0 R_{\rm m}} r_0^2 \left( 1 - \frac{2}{n+2} \right),\]

or conversely

\[q_0 = \frac{2\pi B_0}{\mu_0 R_{\rm m} I} r_0^2 \left( 1 - \frac{2}{n+2} \right),\]

where \(\mu_0\approx 4\pi\times 10^{-7}\,\text{H/m}\) is the vacuum permeability. With \(B_0\), \(\mu_0\), \(R_{\rm m}\) and \(r_0\) in SI units, and the total plasma current in mega-ampere, the central safety factor can be computed from

\[q_0 = \frac{5n}{n+2} \frac{B_0 r_0^2}{R_{\rm m} I}.\]

More information about how to configure an analytical magnetic field can be found at @MagneticField.

Numerical magnetic field

A file defining a numerical magnetic field must contain tables of the radial, vertical and toroidal magnetic field components, as well as wall contours and some meta data. Using this information, SOFT interpolates in the magnetic field data to evaluate its components in arbitrary points of space, and uses the wall contours to block out radiation.

SOFT is able to load three different types of files: HDF5, MAT and SDT. The former two can be generated by a wide range of tools and programming languages, while the latter is a very simple text-based format developed specifically for SOFT and designed to allow exporting data to at text file on systems with limited access to more advanced libraries. Common to all these file formats is that they allow us to store data in variables. SOFT therefore expects any given input file to contain certain variables that provide the information necessary to run a simulation The below table lists the variables that SOFT look for in a magnetic field file.

Variables of numerical magnetic field

Variable	Mandatory	Type	Description
mf Bphi	Yes	nz-by-nr matrix	Toroidal field component
mf Br	Yes	nz-by-nr matrix	Radial field component
mf Bz	Yes	nz-by-nr matrix	Vertical field component
mf desc	Yes	String	(Meta) Description of data
mf maxis	Yes	2-vector	Location of magnetic axis
mf name	Yes	String	(Meta) Name of magnetic field data
mf Psi	No	nz-by-nr matrix	Poloidal magnetic flux
mf r	Yes	nr-vector	Radial grid
mf separatrix	Yes [1]	2-by-many vector	Last closed flux surface contour
mf verBphi	No	nr-vector	Verification array for Bphi
mf verBr	No	nr-vector	Verification array for Br
mf verBz	No	nr-vector	Verification array for Bz
mf wall	Yes [1]	2-by-many vector	Tokamak wall contour
mf z	Yes	nz-vector	Vertical grid

Beware that some tools handle data in column-major format, whereas SOFT uses column-major format. You may therefore have to transpose certain data to have the correct shape. The vectors ``verXXX`` can be used to ensure that the magnetic field components have the proper format.

[1]	(1, 2) At least one of the separatrix and wall variables must be present in the file.

Bphi

Br

Bz

Shape:nz-by-nr Mandatory:Yes

Magnetic field components in an \(RZ\) plane. These are given as matrices with \(n_z\)-by-\(n_r\) points (i.e. \(n_z\) rows and \(n_r\) columns), where element \(ij\) corresponds to height \(i\) on the vertical grid mf z and radius \(j\) on the radial grid mf r.

Components are given in units of Tesla.

desc

name

Type:Strings Mandatory:Yes

These variables contain meta information about the magnetic field data. While they must be present in the file, there are not requirements on their format. They should be used to keep track of what datasets magnetic field fiels come from.

maxis

Shape:2-by-1 Mandatory:Yes

Radial and vertical coordinates of the magnetic axis: \((R_{\rm axis}, Z_{\rm axis})\).

Psi

Shape:nz-by-nr Mandatory:No

The poloidal magnetic flux, \(\Psi\), given on the same \(R\)-\(Z\) grid as the magnetic field components. If the magnetic flux is provided, SOFT can evaluate the Jacobian for the guiding-center transformation using an analytical expression instead of numerically (which is forced otherwise).

Numerical evaluation of the Jacobian is associated with instabilities in certain parts of phase space and its accuracy can at most be computed to a relative error equal to the square root of the tolerance used for solving the guiding-center orbit.

r

Shape:nr-by-1 Mandatory:Yes

z

Shape:nz-by-1 Mandatory:Yes

Vectors that define the grid on which the magnetic field components are given. The whole grid must be a valid meshgrid, and this enforced by demanding it to be specified in terms of these grid vectors instead.

The magnetic field components are evaluated on this grid, so that component \(x\) of the magnetic field is

\[B_{ij} = B_x\left( r_j, z_i \right),\]

where \(i\) is the row index and \(j\) is the column index and

separatrix

wall

Shape:2-by-many Mandatory:At least one of separatrix and wall

Contains the contour line for the separatrix/wall. The first row contains the \(R\)-coordinates of the contour and the second row contains the \(Z\)-coordinates.

At least one of these must be provided in the magnetic field file. If only one of them is provided, that contour is used both as wall and separatrix. If both are present, SOFT uses the wall to filter out radiation that comes from behind a wall and verify that particles do not collide with the walls. The separatrix is used to define the normalized minor radius.

verBphi

verBr

verBz

Shape:nr-by-1 vector Mandatory:No

These vectors can be used to verify that the magnetic field components have the correct format. Since Matlab tends to be inconsistent with whether a matrix is stored in row-major or column-major form, these vectors can be used to ensure that SOFT reads the magnetic field components with a radial dependence along the column index, and vertical dependence along the row index.

These vectors may have at most as many elements as the number of columns in the magnetic field matrices. There may be fewer elements.