Running an optimisation

pints.optimise(function, x0, sigma0=None, boundaries=None, transformation=None, method=None)

Finds the parameter values that minimise an ErrorMeasure or maximise a LogPDF.

Parameters:

• function – An pints.ErrorMeasure or a pints.LogPDF that evaluates points in the parameter space.

• x0 – The starting point for searches in the parameter space. This value may be used directly (for example as the initial position of a particle in PSO) or indirectly (for example as the center of a distribution in XNES).

• sigma0 – An optional initial standard deviation around x0, or a parameter representing the “scale” of the parameters. Can be specified either as a scalar value (same value for all dimensions) or as an array with one entry per dimension. Not all methods will use this information.

• boundaries – An optional set of boundaries on the parameter space.

• transformation – An optional pints.Transformation to allow the optimiser to search in a transformed parameter space. If used, points shown or returned to the user will first be detransformed back to the original space.

• method – The class of pints.Optimiser to use for the optimisation. If no method is specified, CMAES is used.

Returns:

• x_best (numpy array) – The best parameter set obtained

• f_best (float) – The corresponding score.

class pints.OptimisationController(function, x0, sigma0=None, boundaries=None, transformation=None, method=None)

Finds the parameter values that minimise an ErrorMeasure or maximise a LogPDF.

Parameters:

• function – An pints.ErrorMeasure or a pints.LogPDF that evaluates points in the parameter space.

• x0 – The starting point for searches in the parameter space. For details, see Optimiser.

• sigma0 – An optional initial standard deviation around x0. For details, see Optimiser.

• boundaries – An optional set of boundaries on the parameter space. For details, see Optimiser.

• transformation – An optional pints.Transformation to allow the optimiser to search in a transformed parameter space. If used, points shown or returned to the user will first be detransformed back to the original space.

• method – The class of pints.Optimiser to use for the optimisation. If no method is specified, CMAES is used.

evaluations()

Returns the number of evaluations performed during the last run, or None if the controller hasn’t ran yet.

f_guessed_tracking()

Returns True if the controller is set to track the optimiser progress using pints.Optimiser.f_guessed() rather than pints.Optimiser.f_best().

See also set_f_guessed_tracking().

function_tolerance()

Returns a tuple (iterations, threshold) specifying the maximum iterations without a significant change in best function evaluation, if this stopping criterion is set, else (None, None).

The entries in the tuple correspond directly to the arguments to set_function_tolerance().

iterations()

Returns the number of iterations performed during the last run, or None if the controller hasn’t ran yet.

max_evaluations()

Returns the maximum number of evaluations if this stopping criterion is set, or None if it is not.

See set_max_evaluations().

max_iterations()

Returns the maximum iterations if this stopping criterion is set, or None if it is not.

See set_max_iterations().

max_unchanged_iterations()

Deprecated alias of function_tolerance().

optimiser()

Returns the underlying optimiser object, allowing detailed configuration.

parallel()

Returns the number of parallel worker processes this routine will be run on, or False if parallelisation is disabled.

parameter_tolerance()

Returns a tuple (iterations, threshold) specifying the maximum iterations without a significant change in best parameters, if this stopping criterion is set, else (None, None).

The entries in the tuple correspond directly to the arguments to set_parameter_tolerance().

run()

Runs the optimisation, returns a tuple (x, f).

The returned x and f correspond to either the best f seen during the optimisation, or to the best guessed f, depending on the setting for set_f_guessed_tracking(). See :meth:Optimiser.f_guessed()` for details.

An optional callback function can be passed in that will be called at the end of every iteration. The callback should take the arguments (iteration, optimiser), where iteration is the iteration count (an integer) and optimiser is the optimiser object.

set_callback(cb=None)

Allows a “callback” function to be passed in that will be called at the end of every iteration.

This can be used for e.g. visualising optimiser progress.

Example:

def cb(opt):
    plot(opt.xbest())

opt.set_callback(cb)

set_f_guessed_tracking(use_f_guessed=False)

Sets the method used to track the optimiser progress to pints.Optimiser.f_guessed() or pints.Optimiser.f_best() (default).

The tracked f (and/or x) value is used to evaluate stopping criteria, and is the one returned from run().

set_function_tolerance(iterations=200, threshold=1e-11)

Adds a stopping criterion so that the routine halts if the objective function does not change by more than threshold for the given number of iterations.

This criterion is enabled by default. To disable it, use set_function_tolerance(None).

Note that this can be used to implement an absolute “ftol” stopping criteria, by calling set_function_tolerance(1, ftol).

set_log_interval(iters=20, warm_up=3)

Changes the frequency with which messages are logged.

Parameters:

• interval – A log message will be shown every iters iterations.

• warm_up – A log message will be shown every iteration, for the first warm_up iterations.

set_log_to_file(filename=None, csv=False)

Enables logging to file when a filename is passed in, disables it if filename is False or None.

The argument csv can be set to True to write the file in comma separated value (CSV) format. By default, the file contents will be similar to the output on screen.

set_log_to_screen(enabled)

Enables or disables logging to screen.

set_max_evaluations(evaluations=None)

Adds a stopping criterion so that the routine halts after the given number of function evaluations.

This criterion is disabled by default. To enable, pass in any positive integer. To disable again, use set_max_evaluations(None).

set_max_iterations(iterations=10000)

Adds a stopping criterion so that the routine halts after the given number of iterations.

This criterion is enabled by default. To disable it, use set_max_iterations(None).

set_max_unchanged_iterations(iterations=200, threshold=1e-11)

Deprecated alias of function_tolerance().

set_parallel(parallel=False)

Enables/disables parallel evaluation.

If parallel=True, the method will run using a number of worker processes equal to the detected cpu core count. The number of workers can be set explicitly by setting parallel to an integer greater than 0. Parallelisation can be disabled by setting parallel to 0 or False.

set_parameter_tolerance(iterations=200, threshold=1e-11)

Adds a stopping criterion so that the routine halts if the position in parameter space does not change by more threshold for the given number of iterations.

Thresholds can be defined per parameter, or a single scalar value can be passed in. The position is deemed to have changed if np.any(np.abs(x_new - x_sig) >= threshold), where x_sig is either the starting position, or the last position for which the criterion was met.

This criterion is disabled by default. Once enabled, it can be disabled again by calling set_parameter_tolerance(None).

Note that this can be used to implement an absolute “xtol” stopping criteria, by calling set_parameter_tolerance(1, xtol).

set_threshold(threshold)

Adds a stopping criterion causing the routine to stop once the objective function is less than the given threshold (when minimising, or more when maximising).

This criterion is disabled by default, but can be enabled by calling this method with a valid threshold. To disable it, use set_treshold(None).

threshold()

Returns the threshold stopping criterion, or None if no threshold stopping criterion is set. See set_threshold().

time()

Returns the time needed for the last run, in seconds, or None if the controller hasn’t run yet.

class pints.Optimisation(function, x0, sigma0=None, boundaries=None, transformation=None, method=None)

Deprecated alias for OptimisationController.

evaluations()

Returns the number of evaluations performed during the last run, or None if the controller hasn’t ran yet.

f_guessed_tracking()

Returns True if the controller is set to track the optimiser progress using pints.Optimiser.f_guessed() rather than pints.Optimiser.f_best().

See also set_f_guessed_tracking().

function_tolerance()

Returns a tuple (iterations, threshold) specifying the maximum iterations without a significant change in best function evaluation, if this stopping criterion is set, else (None, None).

The entries in the tuple correspond directly to the arguments to set_function_tolerance().

iterations()

Returns the number of iterations performed during the last run, or None if the controller hasn’t ran yet.

max_evaluations()

Returns the maximum number of evaluations if this stopping criterion is set, or None if it is not.

See set_max_evaluations().

max_iterations()

Returns the maximum iterations if this stopping criterion is set, or None if it is not.

See set_max_iterations().

max_unchanged_iterations()

Deprecated alias of function_tolerance().

optimiser()

Returns the underlying optimiser object, allowing detailed configuration.

parallel()

Returns the number of parallel worker processes this routine will be run on, or False if parallelisation is disabled.

parameter_tolerance()

Returns a tuple (iterations, threshold) specifying the maximum iterations without a significant change in best parameters, if this stopping criterion is set, else (None, None).

The entries in the tuple correspond directly to the arguments to set_parameter_tolerance().

run()

Runs the optimisation, returns a tuple (x, f).

The returned x and f correspond to either the best f seen during the optimisation, or to the best guessed f, depending on the setting for set_f_guessed_tracking(). See :meth:Optimiser.f_guessed()` for details.

An optional callback function can be passed in that will be called at the end of every iteration. The callback should take the arguments (iteration, optimiser), where iteration is the iteration count (an integer) and optimiser is the optimiser object.

set_callback(cb=None)

Allows a “callback” function to be passed in that will be called at the end of every iteration.

This can be used for e.g. visualising optimiser progress.

Example:

def cb(opt):
    plot(opt.xbest())

opt.set_callback(cb)

set_f_guessed_tracking(use_f_guessed=False)

Sets the method used to track the optimiser progress to pints.Optimiser.f_guessed() or pints.Optimiser.f_best() (default).

The tracked f (and/or x) value is used to evaluate stopping criteria, and is the one returned from run().

set_function_tolerance(iterations=200, threshold=1e-11)

Adds a stopping criterion so that the routine halts if the objective function does not change by more than threshold for the given number of iterations.

This criterion is enabled by default. To disable it, use set_function_tolerance(None).

Note that this can be used to implement an absolute “ftol” stopping criteria, by calling set_function_tolerance(1, ftol).

set_log_interval(iters=20, warm_up=3)

Changes the frequency with which messages are logged.

Parameters:

• interval – A log message will be shown every iters iterations.

• warm_up – A log message will be shown every iteration, for the first warm_up iterations.

set_log_to_file(filename=None, csv=False)

Enables logging to file when a filename is passed in, disables it if filename is False or None.

The argument csv can be set to True to write the file in comma separated value (CSV) format. By default, the file contents will be similar to the output on screen.

set_log_to_screen(enabled)

Enables or disables logging to screen.

set_max_evaluations(evaluations=None)

Adds a stopping criterion so that the routine halts after the given number of function evaluations.

This criterion is disabled by default. To enable, pass in any positive integer. To disable again, use set_max_evaluations(None).

set_max_iterations(iterations=10000)

Adds a stopping criterion so that the routine halts after the given number of iterations.

This criterion is enabled by default. To disable it, use set_max_iterations(None).

set_max_unchanged_iterations(iterations=200, threshold=1e-11)

Deprecated alias of function_tolerance().

set_parallel(parallel=False)

Enables/disables parallel evaluation.

If parallel=True, the method will run using a number of worker processes equal to the detected cpu core count. The number of workers can be set explicitly by setting parallel to an integer greater than 0. Parallelisation can be disabled by setting parallel to 0 or False.

set_parameter_tolerance(iterations=200, threshold=1e-11)

Adds a stopping criterion so that the routine halts if the position in parameter space does not change by more threshold for the given number of iterations.

Thresholds can be defined per parameter, or a single scalar value can be passed in. The position is deemed to have changed if np.any(np.abs(x_new - x_sig) >= threshold), where x_sig is either the starting position, or the last position for which the criterion was met.

This criterion is disabled by default. Once enabled, it can be disabled again by calling set_parameter_tolerance(None).

Note that this can be used to implement an absolute “xtol” stopping criteria, by calling set_parameter_tolerance(1, xtol).

set_threshold(threshold)

Adds a stopping criterion causing the routine to stop once the objective function is less than the given threshold (when minimising, or more when maximising).

This criterion is disabled by default, but can be enabled by calling this method with a valid threshold. To disable it, use set_treshold(None).

threshold()

Returns the threshold stopping criterion, or None if no threshold stopping criterion is set. See set_threshold().

time()

Returns the time needed for the last run, in seconds, or None if the controller hasn’t run yet.