The hottailgrid and runawaygrid sections of a DREAMSettings object
specify settings for the hot-tail and runaway momentum grids. Both grids are of
the type MomentumGrid, have the same options and grid types. The only
difference between the grids appears in the kernel where the runaway grid has
\(p^{\rm RE}_{1/2}=0\) if the hot-tail grid is disabled, and
\(p^{\rm RE}_{1/2}=p^{\rm HT}_{\rm max}\) if enabled (where
\(p^{\rm HT}_{\rm max}\) is the maximum momentum on the hot-tail grid).
Note
Since DREAM uses the finite-volume method, each momentum grid consists of two shifted momentum grids referred to as the flux and distribution grids.
The flux grid is indexed with half-indices, starting with \(1/2\) which denotes the point on the lower boundary, and ending with \(N+1/2\) or \(\rm max\), denoting the point on the upper boundary. The flux grid is so called because it is where particle fluxes are evaluated.
The points of the distribution grid are situated in between the points of the flux grid. They denote the points in which the distribution function is calculated.
As of this writing, DREAM can only use spherical coordinates (i.e. momentum magnitude \(p\) and cosine of pitch angle \(\xi\)). The code has however been designed with the intention of allowing the use of cylindrical coordinates at some point in the future (i.e. momentum parallel \(p_\parallel\) and perpendicular \(p_\perp\) to the magnetic field).
Todo
Describe the need to explicitly disabled undesired momentum grids.
Todo
Describe the use of the bi-uniform momentum grids.
Todo
Describe the use of the custom momentum grids.
In toroidal geometry, particles with \(|\xi_0| < \sqrt{1-B_{\rm min}/B_{\rm max}}\) will be trapped and bounce back and forth in the magnetic field. Here, \(B_{\rm max}\) is the maximum magnetic field strength experienced along the flux surface/orbit, and \(B_{\rm min}\) is the minimum magnetic field strength, at which point the particle instantaneously has \(\xi = \xi_0\).
To accurately resolve a distribution function in a toroidal magnetic, the set of
points \(\xi_{0,{\rm T}}\) referred to as the trapped-passing
boundary—which separates the particles which are trapped from those that are
passing in momentum space—must be resolved very accurately (i.e. we must place
grid points very close to these points). DREAM provides a particular grid type
for automatically locating the trapped-passing boundary and placing grid points
in appropriate locations. To use this grid, call the method
DREAM.Settings.MomentumGrid.MomentumGrid.setTrappedPassingBoundaryLayerGrid()
on the desired momentum grid.
Since the grid is automatically assembled based on the location of the
trapped-passing boundaries, there are limited options for the user to customize
the grid spacing. The method
DREAM.Settings.MomentumGrid.MomentumGrid.setTrappedPassingBoundaryLayerGrid()
takes four arguments, and typically the user may at least want to specify the
parameter dxiMax to indicate to DREAM the maximum allowed size of each grid
cell. The user can also fine tune the spacing in the fully-trapped and
fully-passing regions separately using the nxiPass and nxiTrap
parameters, which set (half) the number of grid points to place in each of the
two regions. Finally, the parameter boundaryLayerWidth indicates how close
points should be placed to the trapped-passing boundary points
\(\xi_{0,{\rm T}}\) in order to resolve them accurately, and should
generally be a very small number. If the boundary layer width is too large,
the solution can behave weirdly close to the trapped-passing boundary.
Note
The original version of the method
DREAM.Settings.MomentumGrid.MomentumGrid.setTrappedPassingBoundaryLayerGrid()
required the user to manually specify the location of the trapped-passing
boundary at every radius using the xi0Trapped parameter. In more recent
versions, however, the trapped-passing boundary can be automatically
calculated by DREAM during initialization. This is practically always the
desired behaviour, in which case xi0Trapped need not be specified.
ds = DREAMSettings()
...
ds.hottailgrid.setTrappedPassingBoundaryLayerGrid(dxiMax=1e-3, boundaryLayerWidth=1e-4)
DREAM.Settings.MomentumGrid.MomentumGrid(name, enabled=True, ttype=1, np=0, nxi=0, pmax=None)¶__contains__(item)¶__getitem__(index)¶__init__(name, enabled=True, ttype=1, np=0, nxi=0, pmax=None)¶Constructor.
name: Name, indicating what type of grid this is (hot-tail or runaway). enabled: If ‘True’, enables the hot-tail grid in the simulation. ttype: Type of momentum grid (p/xi or ppar/pperp). np: Number of momentum grid points. nxi: Number of pitch grid points. pmax: Maximum momentum on grid.
fromdict(name, data)¶Loads a momentum grid from the specified dictionary.
set(enabled=True, ttype=1, np=100, nxi=1, pmax=None)¶Set all settings for this hot-tail grid.
setBiuniformGrid(psep=None, npsep=None, npsep_frac=None, xisep=None, nxisep=None, nxisep_frac=None, thetasep=None, nthetasep=None, nthetasep_frac=None)¶Set a two-region momentum grid. The lower part (0 < p < psep) has ‘npsep’ number of grid points, while the upper region has ‘np-npsep’ number of grid points. This makes it possible to, for example, have denser grid near the bulk and a coarser grid in the runaway tail. Similarly, the lower part (-1 < xi < xisep) of the pitch grid has ‘nxisep’ number of grid points, etc.
psep (float) – Momentum value separating the two sections.
npsep (int) – Number of grid points on the lower grid section.
npsep_frac (float) – If npsep is None, gives the fraction of grid
points to put in the lower region. Otherwise, not used.
xisep (float) – Pitch value separating the two sections.
nxisep (int) – Number of grid points on the lower grid section.
nxisep_frac (float) – If nxisep is None, gives the fraction of grid
points to put in the lower region. Otherwise not used.
thetasep (float) – Theta value separating the two sections.
nthetasep (int) – Number of grid points on the lower grid section.
nthetasep_frac (float) – If nthetasep is None, gives the fraction of grid
points to put in the lower region. Otherwise not used.
setCustomGrid(p_f=None, xi_f=None)¶Sets p and xi to an arbitrary meshgrid, where the flux grid points of the respective grids are contained in the lists ‘p_f’ and ‘xi_f’. The resolution parameters ‘np’ and ‘nxi’ are overwritten by the sizes of the two input grids.
p_f (float) – Increasing list of momentum flux grid points, with p_f[0]=0.
xi_f (float) – Increasing list of pitch grid points with xi_f[0] = -1 and xi_f[-1] = 1
setEnabled(enabled=True)¶setNp(np)¶setNxi(nxi)¶setPmax(pmax)¶setPmin(pmin)¶Sets the minimum momentum on the kinetic grid. NOTE: This parameter is only observed IF the runaway grid is the only kinetic grid enabled.
setTrappedPassingBoundaryLayerGrid(xi0Trapped=None, dxiMax=2, NxiPass=1, NxiTrap=1, boundaryLayerWidth=0.001)¶Designs a custom pitch grid which places tight grid cells straddling each trapped-passing boundary, so that these singular points are well resolved.
xi0Trapped (float) – List of trapped-passing boundary pitches
(contained in do.grid.xi0TrappedBoundary of an output object).
NEW: To automatically determine the trapped-passing boundary,
leave out this parameter (or set it explicitly to None).
dxiMax (float) – Maximum allowed grid spacing dxi: if this spacing is exceeded after placing points on the trapped-passing boundary, will fill in the gaps by adding one or more grid points (uniformly) in the gaps
NxiPass (int) – Number of grid cells in pitch to be contained between the largest xi0Trapped and xi0=+/-1
NxiTrap (int) – Number of grid cells in pitch to be contained between (+/-) the minimum xi0Trapped and xi0=0
boundaryLayerWidth (float) – Width in pitch of the grid cell containing each trapped-passing boundary, typically << 1
setXiType(ttype)¶Set type of xi grid.
todict(verify=True)¶Returns a Python dictionary containing all settings of this MomentumGrid object.
verifySettings()¶Verify that all (mandatory) settings are set and consistent.
Run with a basic hot-tail grid and no fluid runaways:
from DREAM.DREAMSettings import DREAMSettings
import DREAM.Settings.CollisionHandler as Collisions
ds = DREAMSettings()
...
ds.hottailgrid.set(np=500, nxi=10, pmax=5)
ds.runawaygrid.setEnabled(False)
...