Running an optimisation

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

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. Can be specified either as a scalar value (one standard deviation for all coordinates) 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:

  • xbest (numpy array) – The best parameter set obtained
  • fbest (float) – The corresponding score.

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

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. Can be specified either as a scalar value (one standard deviation for all coordinates) 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.
evaluations()[source]

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

iterations()[source]

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

max_iterations()[source]

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

max_unchanged_iterations()[source]

Returns a tuple (iterations, threshold) specifying a maximum unchanged iterations stopping criterion, or (None, None) if no such criterion is set. See set_max_unchanged_iterations().

optimiser()[source]

Returns the underlying optimiser object, allowing detailed configuration.

parallel()[source]

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

run()[source]

Runs the optimisation, returns a tuple (xbest, fbest).

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)[source]

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_log_interval(iters=20, warm_up=3)[source]

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)[source]

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)[source]

Enables or disables logging to screen.

set_max_iterations(iterations=10000)[source]

Adds a stopping criterion, allowing the routine to halt 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)[source]

Adds a stopping criterion, allowing the routine to halt if the objective function doesn’t change by more than threshold for the given number of iterations.

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

set_parallel(parallel=False)[source]

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_threshold(threshold)[source]

Adds a stopping criterion, allowing the routine to halt once the objective function goes below a set threshold.

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()[source]

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

time()[source]

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)[source]

Deprecated alias for OptimisationController.

evaluations()

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

iterations()

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

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

Returns a tuple (iterations, threshold) specifying a maximum unchanged iterations stopping criterion, or (None, None) if no such criterion is set. See set_max_unchanged_iterations().

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.

run()

Runs the optimisation, returns a tuple (xbest, fbest).

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_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_iterations(iterations=10000)

Adds a stopping criterion, allowing the routine to halt 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)

Adds a stopping criterion, allowing the routine to halt if the objective function doesn’t change by more than threshold for the given number of iterations.

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

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_threshold(threshold)

Adds a stopping criterion, allowing the routine to halt once the objective function goes below a set threshold.

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.