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.
Page overview
While the radial grids described below provide significantly different geometries, they all share some common settings which must be given.
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.
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).
If a nonuniform 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 nonuniform 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 nonuniformity
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)
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)
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 infiniteaspect 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
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 fiveparameter 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}\).
Flux surfaces are parametrized in this model as
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
The parameters that can be specified to the analytic magnetic field are:
Parameter 
Name in interface 
Description 

\(\Delta(r)\) 

Shafranov shift. 
\(\delta(r)\) 

Triangularity. 
\(G(r)/R_0\) 

Toroidal magnetic field function. 
\(\kappa(r)\) 

Elongation. 
\(\psi_{\rm p}/R_0\) 

Poloidal flux function. 
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 = 4e7 * 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=1e3)
ds.runawaygrid.setTrappedPassingBoundaryLayerGrid(dxiMax=1e3)
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.
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, GradShafranov 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.
Magnetic field data can be stored in a number of different ways. DREAM supports the following file formats for magnetic fields:
LUKE is a bounceaveraged 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 


N/A 
String describing the equilibrium data. 

(1,) 
Major radius coordinate of magnetic axis, \(R_{\rm p} = R_0\). 

(1,) 
Vertical position of magnetic axis, \(Z_{\rm p} = Z_0\). 

(\(n_\psi\),) 
Poloidal flux grid; normalized by the aspect ratio, i.e. \(\texttt{psi_apRp} = \psi_{\rm p} / (R_0/a)\). 

(\(n_\theta\),) 
Poloidal angle grid; defined as \(\texttt{theta} = \mathrm{arctan2}(ZZ_0, RR_0) = \mathrm{arctan2}(\texttt{pty}, \texttt{ptx})\). 

(\(n_\theta, n_\psi\)) 
Mapping from \((\psi_{\rm p}, \theta)\) to the radial coordinate \(RR_0\). 

(\(n_\theta, n_\psi\)) 
Mapping from \((\psi_{\rm p}, \theta)\) to the vertical coordinate \(ZZ_0\). 

(\(n_\theta, n_\psi\)) 
Radial component of the magnetic field, \(B_r(\psi_{\rm p}, \theta)\). 

(\(n_\theta, n_\psi\)) 
Vertical component of the magnetic field, \(B_z(\psi_{\rm p}, \theta)\). 

(\(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.
The magnetic field strength has exactly one maximum and one minimum, per flux surface (no negative triangularity)
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
DREAM.Settings.RadialGrid.
RadialGrid
(ttype=1)¶Bases: DREAM.Settings.Equations.PrescribedScalarParameter.PrescribedScalarParameter
__init__
(ttype=1)¶Constructor.
fromdict
(data)¶Load settings from the given dictionary.
setB0
(B0)¶(Cylindrical) Set the onaxis 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.
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.
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.
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.
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 timerateofchange 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 onaxis magnetic field strength and dB0/dt denotes the absolute timerateofchange of B0.
dB0dt_B0 – Normalized timerateofchange of the onaxis magnetic field strength.
t – Time vector corresponding to the given timerateofchange.
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.
shapeparam (str) – Name of shape parameter to verify settings for.
visualize
(*args, ax=None, show=None, **kwargs)¶Visualize the current magnetic field.
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.