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.

Example Usage:

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

Alternatively use the setProcedure:

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:: int, 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:: int, default: 1

updatePlotFreq#

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

Type:: int, 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:: int, default: 10000

maxIterations#

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

Type:: int, default: 1000

populationSize#

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

Type:: int, 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:: int, default: 500

nLive#

[NS] The number of points to sample.

Type:: int, default: 150

nMCMC#

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

Type:: int, 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 number of samples in the initial population for each chain.

Type:: int, default: 20000

nChains#

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

Type:: int, 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.

Usage:

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

Usage:

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

sendStopEvent()#

Sends the stop event via IPC file.

Usage:

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

setProcedure(procedure, varargin)#

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

Example Usage:

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.