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 aLogPDF
.- Parameters:
function – An
pints.ErrorMeasure
or apints.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 inXNES
).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)[source]¶
Finds the parameter values that minimise an
ErrorMeasure
or maximise aLogPDF
.- Parameters:
function – An
pints.ErrorMeasure
or apints.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 inXNES
).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.
- f_guessed_tracking()[source]¶
Returns
True
if the controller is set to track the optimiser progress usingpints.Optimiser.f_guessed()
rather thanpints.Optimiser.f_best()
.See also
set_f_guessed_tracking()
.
- iterations()[source]¶
Returns the number of iterations performed during the last run, or
None
if the controller hasn’t ran yet.
- max_evaluations()[source]¶
Returns the maximum number of evaluations if this stopping criteria is set, or
None
if it is not. Seeset_max_evaluations()
.
- max_iterations()[source]¶
Returns the maximum iterations if this stopping criterion is set, or
None
if it is not. Seeset_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.The entries in the tuple correspond directly to the arguments to
set_max_unchanged_iterations()
.
- 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
(x_best, f_best)
.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)
, whereiteration
is the iteration count (an integer) andoptimiser
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_f_guessed_tracking(use_f_guessed=False)[source]¶
Sets the method used to track the optimiser progress to
pints.Optimiser.f_guessed()
orpints.Optimiser.f_best()
(default).The tracked
f
value is used to evaluate stopping criteria.
- 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
isFalse
orNone
.The argument
csv
can be set toTrue
to write the file in comma separated value (CSV) format. By default, the file contents will be similar to the output on screen.
- set_max_evaluations(evaluations=None)[source]¶
Adds a stopping criterion, allowing the routine to halt after the given number of
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)[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 ofiterations
.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 settingparallel
to an integer greater than 0. Parallelisation can be disabled by settingparallel
to0
orFalse
.
- 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, useset_treshold(None)
.
- threshold()[source]¶
Returns the threshold stopping criterion, or
None
if no threshold stopping criterion is set. Seeset_threshold()
.
- 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.
- f_guessed_tracking()¶
Returns
True
if the controller is set to track the optimiser progress usingpints.Optimiser.f_guessed()
rather thanpints.Optimiser.f_best()
.See also
set_f_guessed_tracking()
.
- 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 criteria is set, or
None
if it is not. Seeset_max_evaluations()
.
- max_iterations()¶
Returns the maximum iterations if this stopping criterion is set, or
None
if it is not. Seeset_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.The entries in the tuple correspond directly to the arguments to
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
(x_best, f_best)
.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)
, whereiteration
is the iteration count (an integer) andoptimiser
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()
orpints.Optimiser.f_best()
(default).The tracked
f
value is used to evaluate stopping criteria.
- 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
isFalse
orNone
.The argument
csv
can be set toTrue
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, allowing the routine to halt after the given number of
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, 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 ofiterations
.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 settingparallel
to an integer greater than 0. Parallelisation can be disabled by settingparallel
to0
orFalse
.
- 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, useset_treshold(None)
.
- threshold()¶
Returns the threshold stopping criterion, or
None
if no threshold stopping criterion is set. Seeset_threshold()
.
- time()¶
Returns the time needed for the last run, in seconds, or
None
if the controller hasn’t run yet.