Controls Class

class API.controlsClass

controlsClass determines how RAT works. It allows the user to interact with the software, by choosing how to parallelise, whether to calculate the SLD during a fit, how many iterations an algorithm should do and more.

There are 5 different procedures available for calculations in RAT. They are:

• Calculate

• Simplex

• Differential Evolution (DE)

• Nested Sampler (NS)

• DREAM

Each procedure has their own unique set of options so the relevant procedure is listed in square brackets before the options description.

Examples

>>> controls = controlsClass();
>>> controls.procedure = procedures.Dream;
>>> controls.nSamples = 6000;
>>> controls.nChains = 10;
>>> controls.parallel = parallelOptions.Contrasts;

Alternatively use the setProcedure method

>>> controls = controlsClass();
>>> controls.setProcedure('dream', 'nSamples', 6000, 'nChains', 10, 'parallel', 'contrasts');

parallel

How the calculation should be parallelised (This uses the Parallel Computing Toolbox). Can be ‘single’, ‘contrasts’ or ‘points’.

Type:

parallelOptions, default: parallelOptions.Single

procedure

Which procedure RAT should execute. Can be ‘calculate’, ‘simplex’, ‘de’, ‘ns’, or ‘dream’.

Type:

procedures, default: procedures.Calculate

calcSldDuringFit

Whether SLD will be calculated during fit (for live plotting etc.)

Type:

logical, default: false

resampleMinAngle

The upper threshold on the angle between three sampled points for resampling, in units of radians over pi.

Type:

float, default: 0.9

resampleNPoints

The number of initial points to use for resampling.

Type:

whole number, default: 50

display

How much RAT should print to the terminal. Can be ‘off’, ‘iter’, ‘notify’, or ‘final’.

Type:

displayOptions, default: displayOptions.Iter

updateFreq

[SIMPLEX, DE] Number of iterations between printing progress updates to the terminal.

Type:

whole number, default: 1

updatePlotFreq

[SIMPLEX, DE] Number of iterations between updates to live plots.

Type:

whole number, default: 20

xTolerance

[SIMPLEX] The termination tolerance for step size.

Type:

float, default: 1e-6

funcTolerance

[SIMPLEX] The termination tolerance for change in chi-squared.

Type:

float, default: 1e-6

maxFuncEvals

[SIMPLEX] The maximum number of function evaluations before the algorithm terminates.

Type:

whole number, default: 10000

maxIterations

[SIMPLEX] The maximum number of iterations before the algorithm terminates.

Type:

whole number, default: 1000

populationSize

[DE] The number of candidate solutions that exist at any time.

Type:

whole number, default: 20

fWeight

[DE] The step size for how different mutations are to their parents.

Type:

float, default: 0.5

crossoverProbability

[DE] The probability of exchange of parameters between individuals at any iteration.

Type:

float, default: 0.8

strategy

[DE] The algorithm used to generate new candidates.

Type:

searchStrategy, default: searchStrategy.RandomWithPerVectorDither

targetValue

[DE] The value of chi-squared at which the algorithm will terminate.

Type:

float, default: 1

numGenerations

[DE] The maximum number of iterations before the algorithm terminates.

Type:

whole number, default: 500

nLive

[NS] The number of points to sample.

Type:

whole number, default: 150

nMCMC

[NS] If non-zero, an MCMC process with nMCMC chains will be used instead of MultiNest.

Type:

whole number, default: 0

propScale

[NS] A scaling factor for the ellipsoid generated by MultiNest.

Type:

float, default: 0.1

nsTolerance

[NS] The tolerance threshold for when the algorithm should terminate.

Type:

float, default: 0.1

nSamples

[DREAM] The total number of function evaluations (number of algorithm generations times number of chains).

Type:

whole number, default: 20000

nChains

[DREAM] The number of Markov chains to use in the algorithm.

Type:

whole number, default: 10

jumpProbability

[DREAM] The probability range for the size of jumps in sampling. Larger values mean more variable jumps.

Type:

float, default: 0.5

pUnitGamma

[DREAM] The probability that the scaling-down factor of jumps will be ignored and a larger jump will be taken.

Type:

float, default: 0.2

boundHandling

[DREAM] How steps past the space boundaries should be handled. Can be ‘off’, ‘reflect’, ‘bound’, or ‘fold’.

Type:

boundHandlingOptions, default: boundHandlingOptions.Reflect

adaptPCR

[DREAM] Whether the crossover probability for differential evolution should be adapted during the run.

Type:

logical, default: true

getIPCFilePath()

Returns the path of the IPC file.

Examples

>>> controls = controlsClass();
>>> path = controls.getIPCFilePath();

Returns:

path – path of the IPC file.

Return type:

char array

initialiseIPC()

Creates and initialises the inter-process communication file

Examples

>>> controls = controlsClass();
>>> controls.initialiseIPC();

sendStopEvent()

Sends the stop event via IPC file.

Examples

>>> controls = controlsClass();
>>> controls.sendStopEvent();

setProcedure(procedure, varargin)

Sets the properties of the controls object based on the selected procedures

Examples

>>> controls = controlsClass();
>>> controls.setProcedure('simplex', 'xTolerance', 1e-6, 'funcTolerance', 1e-6,'maxFuncEvals', 1000);
>>> controls.setProcedure('dream');  % This will use default DREAM options
>>> controls.setProcedure('ns', 'nLive', 150,'nMCMC', 0, 'propScale', 0.1, 'nsTolerance', 0.1);

Parameters:

• procedure (str or procedures) – Which procedure RAT should execute. Can be ‘calculate’, ‘simplex’, ‘de’, ‘ns’, or ‘dream’.

• varargin – keyword/value pairs of the available options for the specified procedure.