radialgrid

The radial grid module handles the specification of the spatial grid used in the DREAM simulation. DREAM currently provides three different types of radial grids: cylindrical, analytic toroidal, and numeric toroidal.

General settings

While the radial grids described below provide significantly different geometries, they all share some common settings which must be given.

Radial grid specification

The location and size of the computational cells in which quantities are evaluated can be specified in two different ways. Either, the total length of radial grid can be given, along with the number of cells on that grid (assuming a uniform cell size), or the location cell boundaries can be given explicitly.

1. Grid size and resolution

If a uniform radial grid is desired, this grid specification is recommended. For this grid, the user must specify the total length of the radial grid a (i.e. the plasma minor radius), as well as the number of computational cells nr to divide the plasma into.

ds = DREAMSettings()
...
ds.radialgrid.setMinorRadius(0.5)
ds.radialgrid.setNr(100)

(It is also possible to specify the value of the innermost radius used, r0, although this is not recommended).

2. Arbitrary grid

If a non-uniform radial grid is desired, the boundaries of the computational cells can be specified. Note that it is the boundaries that are to be specified, in contrast to the cell centres implicitly specified above. From the specified vector, the three parameters specified above can be derived:

• Innermost cell boundary r0: taken as the first element of the given vector.

• Plasma minor radius a: taken as the last element of the given vector.

• Number of grid cells nr: taken as the length of the specified vector, minus one.

Below we give an example of how a non-uniform radial grid could be specified. Note that only the call to DREAM.Settings.RadialGrid.RadialGrid.setCustomGridPoints() is strictly necessary.

import numpy as np

ds = DREAMSettings()
...
# Plasma minor radius
a   = 0.5
# Level of grid non-uniformity
q   = 2
# Number of radial grid cells
nr  = 100

r_f  = np.linspace(0, a**q, nr+1)**(1/q)
r_f *= a/r_f[-1]   # correct for roundoff

ds.radialgrid.setCustomGridPoints(r_f)

Tokamak wall radius

The location of the tokamak wall relative to the magnetic axis is given using the parameter b. This parameter influences the boundary condition used when solving for the electric field.

ds = DREAMSettings()
...
ds.radialgrid.setWallRadius(wall_radius=0.65)

Cylindrical grid

The cylindrical radial grid mode asumes cylindrical geometry in the simulation. This is mathematically equivalent to taking the \(R_0/a\to\infty\) limit in toroidal geometry, where \(R_0\) is the tokamak major radius and \(a\) the plasma minor radius.

The cylindrical grid mode only requires the specification of one additional parameter to the parameters of the radial grid described above in General settings. The required parameter is the magnetic field strength B0, which must be given in SI units (Tesla).

Note

Due to the cylindrical geometry, the magnetic field strength specified is the magnetic field everywhere. If you would like to simulate a specific tokamak in this mode, however, you should set B0 to the toroidal magnetic field strength on the magnetic axis. The infinite-aspect ratio assumption made in cylindrical geometry means that model is only valid sufficiently close to the magnetic axis of a tokamak.

ds = DREAMSettings()
...
ds.radialgrid.setMinorRadius(0.5)    # Plasma minor radius
ds.radialgrid.setWallRadius(0.65)    # Tokamak wall minor radius
ds.radialgrid.setNr(100)             # Number of grid cells
ds.radialgrid.setB0(3.2)             # Magnetic field strength

Analytic toroidal grid

Note

When using toroidal geometry, it is important to adjust the \(\xi\) grids for \(f_{\rm hot}\) and/or \(f_{\rm re}\) (if used) so that the trapped/passing boundaries are sufficiently resovled.

Details about how to do this can be found at Trapped/passing boundary.

DREAM implements an analytic five-parameter toroidal magnetic field. The model includes the three shaping parameters illustrated in the figure below, namely elongation \(\kappa(r)\), triangularity \(\delta(r)\) and Shafranov shift \(\Delta(r)\), which together determine the location and shape of the flux surfaces. In addition to the shaping parameters, the analytic magnetic field also needs information about the toroidal magnetic field function \(G(r) = RB_\varphi\) and the poloidal flux function \(\psi_{\rm p}\).

Definition of the three shaping parameters in the analytic toroidal magnetic field model in DREAM. The three parameters are \(\kappa(r)\) (elongation), \(\delta(r)\) (triangularity), and \(\Delta(r)\) (Shafranov shift). The elongation is the scale factor determining the length of the major axis of the ellipse; the triangularity determines horizontal shift of the top-most point of the flux surface; the Shafranov shift is the shift from the magnetic axis of the center of a flux surface.

Flux surfaces are parametrized in this model as

\[\begin{split}\boldsymbol{x} &= R\hat{R} + z\hat{z},\\ R &= R_0 + \Delta(r) + r\cos\left[\theta + \delta(r)\sin\theta\right],\\ z &= r\kappa(r)\sin\theta,\\ \hat{R} &= \cos\varphi\hat{x} + \sin\varphi\hat{y}\end{split}\]

where \(R_0\) is the tokamak major radius, \(r\) is the minor radius coordinate, \(\theta\) is the poloidal angle, and \(\varphi\) is the toroidal angle. Further, the magnetic field vector is defined according to

\[\boldsymbol{B}(r,\theta) = G(r)\nabla\varphi + \frac{1}{2\pi}\nabla\varphi\times\nabla\psi(r).\]

The parameters that can be specified to the analytic magnetic field are:

Parameter	Name in interface	Description
\(\Delta(r)\)	Delta	Shafranov shift.
\(\delta(r)\)	delta	Triangularity.
\(G(r)/R_0\)	GOverR0	Toroidal magnetic field function.
\(\kappa(r)\)	kappa	Elongation.
\(\psi_{\rm p}/R_0\)	psi	Poloidal flux function.

Example

The following illustrates how an analytic toroidal magnetic field could be specified in DREAM:

import DREAM.Settings.RadialGrid as RGrid
import numpy as np

ds = DREAMSettings()
...
# Basic tokamak parameters
a  = 0.22
R0 = 0.68
B0 = 5.0

# Set up input radial grids
rDelta = np.linspace(0, a, 20)
rdelta = np.linspace(0, a, 20)
rkappa = np.linspace(0, a, 20)
rpsi   = np.linspace(0, a, 20)

# Set shaping parameters
Delta = np.linspace(0, 0.1*a, rDelta.size)   # Shafranov shift
delta = np.linspace(0, 0.2, rdelta.size)     # Triangularity
kappa = np.linspace(1, 1.5, rkappa.size)     # Elongation

# Toroidal field function
GOverR0 = B0       # = R*Bphi/R0

# Poloidal flux
mu0 = 4e-7 * np.pi       # Permeability of free space
IpRef = 200e3            # Reference plasma current which generates poloidal field
psi = -mu0 * IpRef * (1-(rpsi/a)**2) * a

ds.radialgrid.setType(RGrid.TYPE_ANALYTIC_TOROIDAL)
ds.radialgrid.setShaping(psi=psi, rpsi=rpsi, GOverR0=GOverR0, kappa=kappa,
    rkappa=rkappa, Delta=Delta, rDelta=rDelta, delta=delta, rdelta=rdelta)
ds.radialgrid.setWallRadius(a*1.1)
ds.radialgrid.setMajorRadius(R0)

# Numerics parameters
ds.radialgrid.setMinorRadius(a)
ds.radialgrid.setNr(100)

# If kinetic grids are enabled, you should also do...
ds.hottailgrid.setTrappedPassingBoundaryLayerGrid(dxiMax=1e-3)
ds.runawaygrid.setTrappedPassingBoundaryLayerGrid(dxiMax=1e-3)

Note

While this example gives all shape parameters explicitly, and most of them as functions of radius, it is only required to specify the toroidal field function \(G(r)\) and the poloidal flux function \(\psi_{\rm p}(r)\). Also, parameters can also be given as constants, in which case the corresponding radial grid parameter is not necessary and the parameter is assumed to take the prescribed value at all radii.

Numeric toroidal grid

Note

When using toroidal geometry, it is important to adjust the \(\xi\) grids for \(f_{\rm hot}\) and/or \(f_{\rm re}\) (if used) so that the trapped/passing boundaries are sufficiently resovled.

Details about how to do this can be found at Trapped/passing boundary.

DREAM allows numerical magnetic fields obtained from, for example, Grad-Shafranov solvers such as EFIT or LIUQE, to be used to specify the geometry in simulations. Numerically specified magnetic fields are not subject to the symmetry constraints of the Analytic toroidal grid, but still relies on the assumption that each flux surface has exactly one minimum and one maximum in the magnetic field strength.

Internally, DREAM uses information about the magnetic field and geometry of a number of flux surfaces. The information is represented internally by the following parameters:

• \(R_0, Z_0\): major radius and vertical position of magnetic axis.

• \(\psi_{\rm p}, \theta\): Poloidal flux and poloidal angle coordinates for flux surfaces.

• \(R(\psi_{\rm p},\theta), Z(\psi_{\rm p},\theta)\): mapping of flux surfaces from poloidal flux/angle to cylindrical coordinates.

• \(B_\varphi(\psi_{\rm p},\theta), B_r(\psi_{\rm p},\theta), B_z(\psi_{\rm p},\theta)\): Magnetic field components.

From this information, DREAM derives and calculates the various bounce and flux surface averages used for a simulation. Note however that this data is only used internally, and can (in principle) be loaded from files of various formats.

File formats

Magnetic field data can be stored in a number of different ways. DREAM supports the following file formats for magnetic fields:

LUKE

LUKE is a bounce-averaged Fokker–Planck solver developed by Y. Peysson and J. Decker, and written in Matlab. While there is no official standard for the magnetic equilibrium files used by LUKE, a de facto standard has evolved which is used in most cases.

Note

LUKE magnetic equilibrium data is usually stored in a Matlab .mat file. For DREAM to be able to read the file, it must be stored as a version 7.3 Matlab file. DREAM can also read regular HDF5 files.

A LUKE magnetic equilibrium file contains a structure named equil which in turn contains the actual data for the equilibrium. The following fields should be present in the file:

Field	Shape	Description
id	N/A	String describing the equilibrium data.
Rp	(1,)	Major radius coordinate of magnetic axis, \(R_{\rm p} = R_0\).
Zp	(1,)	Vertical position of magnetic axis, \(Z_{\rm p} = Z_0\).
psi_apRp	(\(n_\psi\),)	Poloidal flux grid; normalized by the aspect ratio, i.e. \(\texttt{psi_apRp} = \psi_{\rm p} / (R_0/a)\).
theta	(\(n_\theta\),)	Poloidal angle grid; defined as \(\texttt{theta} = \mathrm{arctan2}(Z-Z_0, R-R_0) = \mathrm{arctan2}(\texttt{pty}, \texttt{ptx})\).
ptx	(\(n_\theta, n_\psi\))	Mapping from \((\psi_{\rm p}, \theta)\) to the radial coordinate \(R-R_0\).
pty	(\(n_\theta, n_\psi\))	Mapping from \((\psi_{\rm p}, \theta)\) to the vertical coordinate \(Z-Z_0\).
ptBx	(\(n_\theta, n_\psi\))	Radial component of the magnetic field, \(B_r(\psi_{\rm p}, \theta)\).
ptBy	(\(n_\theta, n_\psi\))	Vertical component of the magnetic field, \(B_z(\psi_{\rm p}, \theta)\).
ptBPHI	(\(n_\theta, n_\psi\))	Toroidal component of the magnetic field, \(B_\varphi(\psi_{\rm p}, \theta)\).

Note

LUKE magnetic equilibrium data files can also contain a cell array of equil structs, corresponding to equilibria at different times. DREAM does not currently support time evolving magnetic fields and will not be able to read such files at all.

Assumptions for toroidal magnetic fields

• The magnetic field strength has exactly one maximum and one minimum, per flux surface (no negative triangularity)

Magnetic ripple

Some settings related to the effect of the magnetic ripple are made on the radial grid. For details about how to enable effects of the ripple, please see

• DistributionFunction

Class documentation

class DREAM.Settings.RadialGrid.RadialGrid(ttype=1)

Bases: DREAM.Settings.Equations.PrescribedScalarParameter.PrescribedScalarParameter

__init__(ttype=1)

Constructor.

fromdict(data)

Load settings from the given dictionary.

getMajorRadius()

setB0(B0)

(Cylindrical) Set the on-axis magnetic field strength.

setCustomGridPoints(r_f)

(Cylindrical, Analytic toroidal) Set an arbitrary custom grid point distribution on the radial flux grid (i.e. the locations of the cell edges). This overrides the grid resolution ‘nr’, which will be taken as the number of cells described by the prescribed grid points.

Parameters

r_f (float) – List of radial flux grid points

setInnerRadius(r0)

(Cylindrical, Analytic toroidal) Set the innermost radial point to simulate.

setMajorRadius(R0)

(Analytic toroidal) Set the tokamak major radius.

setMinorRadius(a)

(Cylindrical, Analytic toroidal) Set the plasma minor radius.

setNr(nr)

(Cylindrical, Analytic toroidal) Set the number of radial grid points to use.

setNtheta(ntheta)

(Analytic toroidal and numerical) Set the number of grid points to use for the poloidal grid on which bounce averages are calculated.

setNumerical(filename, format=1)

Sets the numerical magnetic field to use for the simulation.

Parameters

• filename (str) – Name of file containing magnetic field data.

• format (int) – Format of the magnetic field data in the given file.

setRipple(m, n, dB_B, ncoils=0, deltacoils=0, r=[0], t=[0])

Enable the ripple pitch scattering term.

Parameters

• m (list) – Poloidal mode numbers of magnetic perturbation(s).

• n (list) – Toroidal mode numbers of magnetic perturbation(s).

• dB_B – Magnetic perturbations (shape: nModes x nt x nr).

• ncoils (int) – Number of toroidal field coils.

• deltacoils (float) – Distance between toroidal field coils.

• r – Radial grid on which the magnetic perturbations are given.

• t – Time grid on which the magnetic perturbations are given.

setShapeParameter(name, data, r=0.0)

(Analytic toroidal) Set a specific magnetic field shape parameter.

setShaping(psi, GOverR0, rpsi=0.0, rG=0.0, Delta=0.0, rDelta=0.0, delta=0.0, rdelta=0.0, kappa=1.0, rkappa=0.0)

(Analytic toroidal) Set the plasma shape parameters to use with the magnetic field.

Parameters

• GOverR0 – Toroidal magnetic field component, R*Bphi, normalized by R0.

• rG – Radial grid for GOverR0.

• psi – Reference poloidal flux, normalized by R0.

• rpsi – Radial grid for psi.

• Delta – Shafranov shift.

• rDelta – Radial grid for Shafranov shift.

• delta – Triangularity.

• rdelta – Radial grid for triangularity.

• kappa – Elongation.

• rkappa – Radial grid for elongation.

setTimeVaryingB(dB0dt_B0, t=0)

Set the time-rate-of-change of the magnetic field strength (for the approximate time varying B compression force operator). Note that the specified parameter should be (1/B0)*(dB0/dt), where B0 is the on-axis magnetic field strength and dB0/dt denotes the absolute time-rate-of-change of B0.

Parameters

• dB0dt_B0 – Normalized time-rate-of-change of the on-axis magnetic field strength.

• t – Time vector corresponding to the given time-rate-of-change.

setType(ttype)

Set the type of radial grid to use.

setWallRadius(wall_radius)

(Cylindrical, Analytic toroidal) Set the minor radius of the wall

todict(verify=True)

Returns the settings in this object as a Python dictionary.

verifySettings()

Verfiy that the RadialGrid settings are consistent.

verifySettingsShapeParameter(shapeparam)

Verify the settings of the named shape parameter.

Parameters

shapeparam (str) – Name of shape parameter to verify settings for.

visualize(*args, ax=None, show=None, **kwargs)

Visualize the current magnetic field.

Parameters

• nr (int) – Number of flux surfaces to show.

• ntheta (int) – Number of poloidal angles per flux surface.

visualize_analytic(nr=10, ntheta=40, ax=None, show=None, **kwargs)

Visualize an analytic toroidal magnetic field.