cma.evolution_strategy

Calling Sequences

fmin(objective_function, x0, sigma0)

minimizes objective_function starting at x0 and with standard deviation sigma0 (step-size)

fmin(objective_function, x0, sigma0, options={'ftarget': 1e-5})

minimizes objective_function up to target function value 1e-5, which is typically useful for benchmarking.

fmin(objective_function, x0, sigma0, args=('f',))

minimizes objective_function called with an additional argument 'f'.

fmin(objective_function, x0, sigma0, options={'ftarget':1e-5, 'popsize':40})

uses additional options ftarget and popsize

fmin(objective_function, esobj, None, options={'maxfevals': 1e5})

uses the CMAEvolutionStrategy object instance esobj to optimize objective_function, similar to esobj.optimize().

Arguments

objective_function

called as objective_function(x, *args) to be minimized. x is a one-dimensional numpy.ndarray. See also the parallel_objective argument. objective_function can return numpy.NaN, which is interpreted as outright rejection of solution x and invokes an immediate resampling and (re-)evaluation of a new solution not counting as function evaluation. The attribute variable_annotations is passed into the CMADataLogger.persistent_communication_dict.

x0

list or numpy.ndarray, initial guess of minimum solution before the application of the geno-phenotype transformation according to the transformation option. It can also be a callable that is called (without input argument) before each restart to yield the initial guess such that each restart may start from a different place. Otherwise, x0 can also be a cma.CMAEvolutionStrategy object instance, in that case sigma0 can be None.

sigma0

scalar, initial standard deviation in each coordinate. sigma0 should be about 1/4th of the search domain width (where the optimum is to be expected). The variables in objective_function should be scaled such that they presumably have similar sensitivity. See also ScaleCoordinates.

options

a dictionary with additional options passed to the constructor of class CMAEvolutionStrategy, see cma.CMAOptions () for a list of available options.

args=()

arguments to be used to call the objective_function

gradf=None

gradient of f, where len(gradf(x, *args)) == len(x). gradf is called once in each iteration if gradf is not None.

restarts=0

number of restarts with increasing population size, see also parameter incpopsize. For the time being (this may change in future) restarts can also be a dict where the keys maxrestarts=9 and maxfevals=np.inf are interpreted. An empty dict is interpreted as restarts=0. An IPOP-CMA-ES restart is invoked if restarts > 0 or restarts['maxrestarts'] > 0 and if current_evals < min((restarts['maxfevals'], options['maxfevals'])) and neither the 'ftarget' nor the termination_callback option was triggered; restarts['maxfevals'] does not terminate during the run or restart; to restart from different points (recommended), pass x0 as a callable; see also parameter bipop.

restart_from_best=False

which point to restart from

incpopsize=2

multiplier for increasing the population size popsize before each restart

parallel_objective

an objective function that accepts a list of numpy.ndarray as input and returns a list, which is mostly used instead of objective_function, but for the initial (also initial elitist) and the final evaluations unless not callable(objective_function). If parallel_objective is given, the objective_function (first argument) may be None.

eval_initial_x=None

evaluate initial solution, for None only with elitist option

noise_handler=None

must be True or a cma.NoiseHandler class or instance to invoke noise handling. The latter gives control over the specific settings for the noise handling, see help(cma.NoiseHandler).

noise_change_sigma_exponent=1

exponent for the sigma increment provided by the noise handler for additional noise treatment. 0 means no sigma change.

noise_evaluations_as_kappa=0

instead of applying reevaluations, the "number of evaluations" is (ab)used as scaling factor kappa (experimental).

bipop=False

if bool(bipop) is True, run as BIPOP-CMA-ES; BIPOP is a special restart strategy switching between two population sizings - small (relative to the large population size and with varying initial sigma, the first run is accounted on the "small" budget) and large (progressively increased as in IPOP). This makes the algorithm potentially solve both, functions with many regularly or irregularly arranged local optima (the latter by frequently restarting with small populations). Small populations are (re-)started as long as the cumulated budget_small is smaller than bipop x max(1, budget_large). For the bipop parameter to actually conduct restarts also with the larger population size, select a non-zero number of (IPOP) restarts; the recommended setting is restarts <= 9 and x0 passed as a callable that generates randomized initial solutions. Small-population restarts do not count into the total restart count.

callback=None

callable or list of callables called at the end of each iteration with the current CMAEvolutionStrategy instance as argument.

init_callback=None

callable or list of callables called at the end of initialization of the CMAEvolutionStrategy instance with this instance as argument (like callback). This allows to reassign attributes without a corresponding CMAOption. For example, es.integer_centering = lambda *args: None disables integer centering (which is enabled by default when integer_variables are given in the options) or es.integer_centering = cma.integer_centering.IntCentering(es, correct_bias=False) disables its bias correction.

Optional Arguments

All values in the options dictionary are evaluated if they are of type str, besides verb_filenameprefix, see class CMAOptions for details. The full list is available by calling cma.CMAOptions().

>>> import cma
>>> cma.CMAOptions()  #doctest: +ELLIPSIS
{...

Subsets of options can be displayed, for example like cma.CMAOptions('tol'), or cma.CMAOptions('bound'), see also class CMAOptions.

Return

Return the list provided in CMAEvolutionStrategy.result appended with termination conditions, an OOOptimizer and a BaseDataLogger:

res = es.result + (es.stop(), es, logger)

where

• res[0] (xopt) -- best evaluated solution
• res[1] (fopt) -- respective function value
• res[2] (evalsopt) -- respective number of function evaluations
• res[3] (evals) -- number of overall conducted objective function evaluations
• res[4] (iterations) -- number of overall conducted iterations
• res[5] (xmean) -- mean of the final sample distribution
• res[6] (stds) -- effective stds of the final sample distribution
• res[-3] (stop) -- termination condition(s) in a dictionary
• res[-2] (cmaes) -- class CMAEvolutionStrategy instance
• res[-1] (logger) -- class CMADataLogger instance

Details

This function is an interface to the class CMAEvolutionStrategy. The latter class should be used when full control over the iteration loop of the optimizer is desired.

Examples

The following example calls fmin optimizing the Rosenbrock function in 10-D with initial solution 0.1 and initial step-size 0.5. The options are specified for the usage with the doctest module.

>>> import cma
>>> # cma.CMAOptions()  # returns all possible options
>>> options = {'CMA_diagonal':100, 'seed':1234, 'verb_time':0}
>>>
>>> res = cma.fmin(cma.ff.rosen, [0.1] * 10, 0.3, options)  #doctest: +ELLIPSIS
(5_w,10)-aCMA-ES (mu_w=3.2,w_1=45%) in dimension 10 (seed=1234...)
   Covariance matrix is diagonal for 100 iterations (1/ccov=26...
Iterat #Fevals   function value  axis ratio  sigma ...
    1     10 ...
termination on tolfun=1e-11 ...
final/bestever f-value = ...
>>> assert res[1] < 1e-12  # f-value of best found solution
>>> assert res[2] < 8000  # evaluations

The above call is pretty much equivalent with the slightly more verbose call:

res = cma.CMAEvolutionStrategy([0.1] * 10, 0.3,
            options=options).optimize(cma.ff.rosen).result

where optimize returns a CMAEvolutionStrategy instance. The following example calls fmin optimizing the Rastrigin function in 3-D with random initial solution in [-2,2], initial step-size 0.5 and the BIPOP restart strategy (that progressively increases population). The options are specified for the usage with the doctest module.

>>> import cma
>>> # cma.CMAOptions()  # returns all possible options
>>> options = {'seed':12345, 'verb_time':0, 'ftarget': 1e-8}
>>>
>>> res = cma.fmin(cma.ff.rastrigin, lambda : 2. * np.random.rand(3) - 1, 0.5,
...                options, restarts=9, bipop=True)  #doctest: +ELLIPSIS
(3_w,7)-aCMA-ES (mu_w=2.3,w_1=58%) in dimension 3 (seed=12345...

In either case, the method:

cma.plot();

(based on matplotlib.pyplot) produces a plot of the run and, if necessary:

cma.s.figshow()

shows the plot in a window. Finally:

cma.s.figsave('myfirstrun')  # figsave from matplotlib.pyplot

will save the figure in a png.

We can use the gradient like

>>> import cma
>>> res = cma.fmin(cma.ff.rosen, np.zeros(10), 0.1,
...             options = {'ftarget':1e-8,},
...             gradf=cma.ff.grad_rosen,
...         )  #doctest: +ELLIPSIS
(5_w,...
>>> assert cma.ff.rosen(res[0]) < 1e-8
>>> assert res[2] < 3600  # 1% are > 3300
>>> assert res[3] < 3600  # 1% are > 3300

If solution can only be comparatively ranked, either use CMAEvolutionStrategy directly or the objective accepts a list of solutions as input:

>>> def parallel_sphere(X): return [cma.ff.sphere(x) for x in X]
>>> x, es = cma.fmin2(None, 3 * [0], 0.1, {'verbose': -9},
...                   parallel_objective=parallel_sphere)
>>> assert es.result[1] < 1e-9

Example code

>>> import cma
>>> x, es = cma.fmin_lq_surr(cma.ff.rosen, 2 * [0], 0.1,
...                          {'verbose':-9,  # verbosity for doctesting
...                           'ftarget':1e-2, 'seed':11})
>>> assert 'ftarget' in es.stop(), (es.stop(), es.result_pretty())
>>> assert es.result.evaluations < 90, es.result.evaluations  # can be 137 depending on seed

Details

lq-CMA-ES builds a linear or quadratic (global) model as a surrogate to try to circumvent evaluations of the objective function, see link below.

This function calls fmin2 with a surrogate as parallel_objective argument. The model is kept the same for each restart. Use fmin_lq_surr2 if this is not desirable.

kwargs['callback'] is modified by appending a callable that injects model.xopt. This can be prevented by passing callback=False or adding False as an element of the callback list (see also cma.fmin).

parallel_objective is assigned to a surrogate model instance of cma.fitness_models.SurrogatePopulation.

es.countevals is updated from the evaluations attribute of the constructed surrogate to count only "true" evaluations.

See https://cma-es.github.io/lq-cma for references and details about the algorithm.

Example code

>>> import cma
>>> x, es = cma.fmin_lq_surr2(cma.ff.rosen, 2 * [0], 0.1,
...                           {'verbose':-9,  # verbosity for doctesting
...                            'ftarget':1e-2, 'seed':3})
>>> assert 'ftarget' in es.stop(), (es.stop(), es.result_pretty())
>>> assert es.result.evaluations < 90, es.result.evaluations  # can be >130? depending on seed
>>> assert es.countiter < 60, es.countiter

Details

lq-CMA-ES builds a linear or quadratic (global) model as a surrogate to circumvent evaluations of the objective function, see link below.

This code uses the ask-and-tell interface to CMA-ES via the class CMAEvolutionStrategy to the options dict is passed.

To pass additional arguments to the objective function use functools.partial.

not_evaluated must return True if a value indicates (by convention of cma.fitness_models.SurrogatePopulation.EvaluationManager.fvalues) a missing "true" evaluation of the objective_function.

See https://cma-es.github.io/lq-cma for references and details about the algorithm.