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).


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.

Momentum coordinates

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).


Describe the need to explicitly disabled undesired momentum grids.


Describe the use of the bi-uniform momentum grids.


Describe the use of the custom momentum grids.

Trapped/passing boundary

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.


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)

Object documentation

class DREAM.Settings.MomentumGrid.MomentumGrid(name, enabled=True, ttype=1, np=0, nxi=0, pmax=None)
__init__(name, enabled=True, ttype=1, np=0, nxi=0, pmax=None)


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

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


Set type of xi grid.


Returns a Python dictionary containing all settings of this MomentumGrid object.


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)