# ConvergenceScan¶

The ConvergenceScan class provides a simple way of quickly generating parameter scans, particularly in the resolution parameters. A ConvergenceScan object holds a reference to a baseline DREAMSettings object, as well as a list of input and output parameters. Each input and output parameter has a name associate with it, as well as a function which modifies a given DREAMSettings object (input) or extracts data from a DREAMOutput object (output).

Once the ConvergenceScan has been successfully executed, the result can be conveniently plotted using the ConvergenceScanPlot class.

The most basic use case is illustrated by the following example (although far more complicated things can be achieved with the class):

import DREAM
# ... or
# from DREAM.ConvergenceScan import ConvergenceScan
# ... and use as just "ConvergenceScan()"

# First, create a DREAMSettings object as you normally would...
ds = DREAM.DREAMSettings()

# set up ds...
...

# Create convergence scan
cs = DREAM.ConvergenceScan(settings=ds,
inparams=['nt', 'hottail.np', 'hottail.nxi'],
outparams=['other.fluid.runawayRate'])

# Run convergence scan
cs.run()

# Save results to file
cs.save('convergence.h5')


Note

DREAM path

In order for the convergence scan to find DREAM, you must first properly set up your environment before using the ConvergenceScan object. Primarily, the environment variable DREAMPATH variable should be defined and point to the DREAM source directory. You can read more about how to do this on the page runiface.

## Input/output parameter by name¶

Input and output parameters can be specified by name. Except for a few special parameters, the name is the full name, including parent class names in the owning DREAMSettings/DREAMOutput object. For example, to vary the radial grid resolution, which is accessed in the DREAMSettings object using DREAMSettings.radialgrid.nr, one would generally specify the name of the parameter as radialgrid.nr, that is, everything after the the DREAMSettings.. The same applies to DREAMOutput, so that the name eqsys.I_p would access the final plasma current.

Parameters can be added either when the ConvergenceScan object is created, or afterwards (or both):

ds = DREAMSettings()
...

cs = ConvergenceScan(ds, inparams=['nt'], outparams=['other.fluid.runawayRate'])


### Aliases for input parameters¶

Some input parameters are special and have aliases which allow for easier access. These are listed in the table below:

Full name

Alias

Description

hottailgrid.pgrid.np

hottailgrid.np

Momentum resolution on hottail grid.

hottailgrid.xigrid.nxi

hottailgrid.nxi

Pitch resolution on hottail grid.

hottailgrid.pgrid.np and hottailgrid.xigrid.nxi

hottail

Momentum AND pitch resolution on hottail grid (adds two input parameters).

radialgrid.nr

nr

timestep.nt

nt

Time resolution.

runawaygrid.pgrid.np

runawaygrid.np

Momentum resolution on runaway grid.

runawaygrid.xigrid.nxi

runawaygrid.nxi

Pitch resolution on runaway grid.

runawaygrid.pgrid.np and runawaygrid.xigrid.nxi

runaway

Momentum AND pitch resolution on runaway grid.

### Special notes on output parameters¶

Output parameter data is accessed by index, meaning that any UnknownQuantity or OtherQuantity may be used as the output parameter. When the output parameter is given by name, the code will access only the very last element of the data. This means that, for

• ScalarQuantity’s (such as I_p), the final value is used.

• FluidQuantity’s (such as E_field), the final value at the outermost radius is used.

• KineticQuantity’s (such as f_hot), the final value at the outermost radius in $$\xi=1$$ and $$p=p_{\rm max}$$ is used.

When specifying output parameters by name, the very last element of the parameter data will generally be accessed.

## Input parameter custom function¶

Sometimes the parameter to scan is more complicated to set than just increasing/decreasing it by a constant float value. In this case, one can instead define a custom function which modifies the settings object in a successive fashion. The function can only be provided via a call to addScanParameter() and must thus be added after the ConvergenceScan object has been constructed.

The addScanParameter() should be called in the following way:

cs.addScanParameter(name='inparam', f=customFunction, baselineValue=baseval)


These are the required parameters; the other parameters can also be specified if desired.

The name of the parameter is essentially arbitrary. It is only used by the ConvergenceScan object to identify the baseline value if the baselineValue parameter is not specified. If this is the case, the baseline value is taken from the variable in the previously given DREAMSettings object which has the given name.

The custom function customFunction() should have the following signature:

customInputFunction(index, settings, baseline)
Parameters
• index (int) – Index of simulation to set up (0 means the baseline case; negative values are possible)

• settings (DREAMSettings) – Settings object to modify. On input, this object is a copy of the baseline settings object specified when constructing the ConvergenceScan object.

• baseline – Baseline value for this parameter.

Returns

Tuple consisting of the modified settings object and a float representing the value set.

Note

Lambda expressions

The use of lambda functions is often appropriate when passing functions to addScanParameter() and can provide more compact code (see, for example, https://docs.python.org/3/tutorial/controlflow.html#lambda-expressions).

The function is supposed to modify the parameter settings, which is a copy of the DREAMSettings object given to the ConvergenceScan when constructed, and return the modified settings object along with a numerical value representing the assigned setting (even if the value is not numerical itself; then it could for example be index). An example implementation is:

def _CS_getiNt(index: int, settings: DREAMSettings, baseline):
# Calculate new value to set
val = max(1,int(np.round(baseline * np.float_power(2, index))))
# Modify settings object
settings.timestep.setNt(val)
# Return modified object and new parameter value
return settings.val


### Simulation indices¶

The index parameter accepted by the custom function indicates the stage of the convergence scan to set up. Indices work such that 0 correspond to the baseline case, while positive values indicate “higher resolution” and negative values indicate “lower resolution” (of course, users are welcome to reinterpret the distinction between positive and negative indices however they desire). The scanner expects the function to modify the object in a deterministic way so that a call with a specific index always results in the same settings being applied. In general, the baseline case is only run once, instead of once for each scan parameter.

By default, the starting index is -1, which is then gradually increased until the upper index limit is reach, which is set to 1 (inclusive) by default.

## Output parameter custom function¶

As with complicated input parameters, more complicated output parameters can also be accessed via a custom function. The custom function has to be added separately via the addOutputParameter() function in the following way:

cs.addOutputParameter(name='outparam', f=customFunction)


Optionally, a relative tolerance used for the continuous convergence scan mode can also be provided, but is not required.

If a custom function is provided, the name of the output parameter is only used when communicating with the user and has no internal significance.

The custom function should have the signature

customOutputFunction(do: DREAMOutput)
Parameters

do (DREAMOutput) – Output object to extract parameter value from.

Returns

The value of the output parameter.

Return type

float

Note

Lambda expressions

The use of lambda functions is often appropriate when passing functions to addOutputParameter() and can provide more compact code (see, for example, https://docs.python.org/3/tutorial/controlflow.html#lambda-expressions).

The purpose of the function is to process the given DREAMOutput object in order to obtain the value of the output parameter resulting from the simulation. The returned value must be a float, although the actual value returned generally is of little or no interest to the ConvergenceScan object (it could for example be a binary value, varying discretely between 0 and 1). The only time the ConvergenceScan object makes a decision based on the value of the parameter is when scanUntilConvergence is set to True for an input parameter.

An example implementation of the custom output parameter function is the following:

def customFunction(do: DREAMOutput) -> float:
# Calculate kinetic energy carried by hot electrons
Wk = do.eqsys.f_hot.kineticEnergy()[-1,:]
# Turn into a FluidQuantity
Wk = DREAM.Output.FluidQuantity('Wk', Wk, do.grid, do)

return Wk.integral(t=-1)


## Scanning until convergence¶

If you would like to find the point of convergence without manually tweaking the scan, you can set the parameter scanUntilConvergence=True when calling addScanParameter(). This will cause the ConvergenceScan to increase the simulation index by one until the output parameters vary by less than the relative tolerance specified for each output parameter.

Warning

Note that there is a maximum number of permitted iterations in the ConvergenceScan object, called NMAX. It defaults to 10, meaning that if convergence has not been reached on the tenth iteration (corresponding to index 8 with the default starting index -1), then the scan will stop with an error.

## Class documentation¶

class DREAM.ConvergenceScan(settings, inparams=None, outparams=None, scanUntilConvergence=False, verbose=True)

Bases: object

__init__(settings, inparams=None, outparams=None, scanUntilConvergence=False, verbose=True)

Creates a new ConvergenceScan object with ‘settings’ representing the settings for the baseline scenario.

Parameters
• settings (DREAMSettings) – Baseline DREAMSettings object to base all convergence runs on.

• inparams (list) – Either a string (or a list of strings), specifying the set(s) of parameters to scan, or None, which sets no parameters (and they must then be explicitly set using addScanParameter() later).

• outparams (list) – Either a string (or a list of strings), specifying the set(s) of parameters to measure for convergence. Alternatively, None clears all output parameters (which must then be explicitly set using addOutputParameter() later).

• scanUntilConvergence (bool) – If True, does not limit the number of runs to do and updates the value of each parameter until the output parameter changes less than the given tolerance.

• verbose (bool) – If True, prints progress message to stdout when running.

addOutputParameter(name: str, f=None, reltol=0.01)

Adds an output parameter to check convergence for.

Parameters
• name (str) – Name of output parameter (used as an identifier, but does not have to correspond to the parameter’s actual name in DREAM).

• f (function) – A function which, given a DREAMOutput object, returns a single float value corresponding to this output parameter.

• reltol (float) – Relative tolerance to demand if ‘scanUntilConvergence’ is True for any of the scan parameters.

addScanParameter(name: str, f=None, baselineValue=None, scanUntilConvergence=False, nvalues=3, startindex=- 1)

Adds an input parameter to scan in.

Parameters
• name (str) – Name of parameter (used as an identifier, but does not have to correspond to the parameter’s actual name in DREAM).

• f (function) – A function which, given an index, a DREAMSettings object and a baseline value, updates the scan parameter in the settings object. The index can take both positive and negative values, with 0 corresponding to the baseline value (negative values thus correspond to lower resolution while positive values correspond to higher resolution). The function should return a tuple consisting of the modified settings object (which may be the same as the input object) and the value representing the changes made to the DREAMSettings object (for identification purposes in plots).

• baselineValue – Baseline value of the parameter (for passing on to f).

• scanUntilConvergence (bool) – If True, does not limit the number of runs to do and updates the value of each parameter until the output parameter changes less than the given tolerance.

• nvalues (int) – Number of values to scan over. Ignored if scanUntilConvergence = True.

• startindex (int) – First index to run from. Default: -1 (so that runs are -1, 0, 1, …, nvalues-2)

getOutputParameters()

Get a dictionary containing details about the output parameters used in the scan.

Returns

A dict which specifies the settings for the output parameters to consider as measures of convergence.

Return type

dict

run()

Run the convergence scan.

save(filename)

Saves this convergence scan to an HDF5 file.

Parameters

filename (str) – Name of file to save scan results to.

setVerbose(verbose=True)

If verbose is True, the scan will print progress messages to stdout when running.

Parameters

verbose (bool) – Value to set verbosity to.

todict()

Converts the results of this scan to a dictionary object which can easily be saved to file.