class documentation

`class CMAES(OOOptimizer):`

View In Hierarchy

class for non-linear non-convex numerical minimization with CMA-ES.

The class implements the interface define in `OOOptimizer`, namely the methods `__init__`, `ask`, `tell`, `stop`, `disp` and property `result`.

## Examples

The Jupyter notebook or IPython are the favorite environments to execute these examples, both in %pylab mode. All examples minimize the function `elli`, output is not shown.

First we need to import the module we want to use. We import `purecma` from `cma` as (aliased to) pcma:

```from cma import purecma as pcma
```

The shortest example uses the inherited method `OOOptimizer.optimize`:

```es = pcma.CMAES(8 * [0.1], 0.5).optimize(pcma.ff.elli)
```

See method `CMAES.__init__` for a documentation of the input parameters to `CMAES`. We might have a look at the result:

```print(es.result[0])  # best solution and
print(es.result[1])  # its function value
```

`result` is a property of `CMAES`. In order to display more exciting output, we may use the `CMAESDataLogger` instance in the `logger` attribute of `CMAES`:

```es.logger.plot()  # if matplotlib is available
```

Virtually the same example can be written with an explicit loop instead of using `optimize`, see also `fmin`. This gives insight into the `CMAES` class interface and entire control over the iteration loop:

```pcma.fmin??  # print source, works in jupyter/ipython only
es = pcma.CMAES(9 * [0.5], 0.3)  # calls CMAES.__init__()

# this loop resembles the method optimize
while not es.stop():  # iterate
X = es.ask()      # get candidate solutions
f = [pcma.ff.elli(x) for x in X]  # evaluate solutions
es.tell(X, f)     # do all the real work
es.disp(20)       # display info every 20th iteration
es.logger.add(es) # log another "data line"

# final output
print('termination by', es.stop())
print('best f-value =', es.result[1])
print('best solution =', es.result[0])

print('potentially better solution xmean =', es.result[5])
print("let's check f(xmean) = ", pcma.ff.elli(es.result[5]))
es.logger.plot()  # if matplotlib is available
```

A very similar example which may also save the logged data within the loop is the implementation of function `fmin`.

## Details

Most of the work is done in the method `tell`. The property `result` contains more useful output.

 See Also `fmin`, `OOOptimizer.optimize`
 Method `__init__` Instantiate `CMAES` object instance using `xstart` and `sigma`. Method `ask` sample lambda candidate solutions Method `disp` `print` some iteration info to `stdout` Method `stop` return satisfied termination conditions in a dictionary, Method `tell` update the evolution paths and the distribution parameters m, sigma, and C within CMA-ES. Instance Variable `best` Undocumented Instance Variable `C` Undocumented Instance Variable `counteval` Undocumented Instance Variable `fitvals` Undocumented Instance Variable `ftarget` Undocumented Instance Variable `logger` Undocumented Instance Variable `maxfevals` Undocumented Instance Variable `params` Undocumented Instance Variable `pc` Undocumented Instance Variable `ps` Undocumented Instance Variable `randn` Undocumented Instance Variable `sigma` Undocumented Instance Variable `xmean` Undocumented Property `result` the `tuple` (xbest, f(xbest), evaluations_xbest, evaluations, iterations, xmean, stds)

Inherited from `OOOptimizer`:

 Method `initialize` (re-)set to the initial state Method `optimize` find minimizer of objective_fct. Instance Variable `countiter` Undocumented Instance Variable `more_mandatory_args` Undocumented Instance Variable `optional_kwargs` Undocumented Instance Variable `xcurrent` Undocumented Instance Variable `xstart` Undocumented Method `_force_final_logging` try force the logger to log NOW Method `_prepare_callback_list` return a list of callbacks including self.logger.add.
def __init__(self, xstart, sigma, popsize=CMAESParameters.default_popsize, ftarget=None, maxfevals='100 * popsize + 150 * (N + 3)**2 * popsize**0.5', randn=random_normalvariate):
overrides `cma.interfaces.OOOptimizer.__init__`

Instantiate `CMAES` object instance using `xstart` and `sigma`.

## Parameters

`xstart`: `list`
of numbers (like [3, 2, 1.2]), initial solution vector
`sigma`: `float`
initial step-size (standard deviation in each coordinate)
`popsize`: `int` or `str`
population size, number of candidate samples per iteration
`maxfevals`: `int` or `str`
maximal number of function evaluations, a string is evaluated with N as search space dimension
`ftarget`: `float`
target function value
`randn`: `callable`
normal random number generator, by default `random.normalvariate`

Details: this method initializes the dynamic state variables and creates a `CMAESParameters` instance for static parameters.

overrides `cma.interfaces.OOOptimizer.ask`

sample lambda candidate solutions

distributed according to:

```m + sigma * Normal(0,C) = m + sigma * B * D * Normal(0,I)
= m + B * D * sigma * Normal(0,I)
```

and return a `list` of the sampled "vectors".

def disp(self, verb_modulo=1):
overrides `cma.interfaces.OOOptimizer.disp`

`print` some iteration info to `stdout`

def stop(self):
overrides `cma.interfaces.OOOptimizer.stop`

return satisfied termination conditions in a dictionary,

generally speaking like {'termination_reason':value, ...}, for example {'tolfun':1e-12}, or the empty `dict` {}.

def tell(self, arx, fitvals):
overrides `cma.interfaces.OOOptimizer.tell`

update the evolution paths and the distribution parameters m, sigma, and C within CMA-ES.

## Parameters

`arx`: `list` of "row vectors"
a list of candidate solution vectors, presumably from calling `ask`. arx[k][i] is the i-th element of solution vector k.
`fitvals`: `list`
the corresponding objective function values, to be minimised
best =

Undocumented

C =

Undocumented

counteval: `int` =

Undocumented

fitvals =

Undocumented

ftarget =

Undocumented

logger =

Undocumented

maxfevals =

Undocumented

params =

Undocumented

pc =

Undocumented

ps =

Undocumented

randn =

Undocumented

sigma =

Undocumented

xmean =

Undocumented

@property
result =
overrides `cma.interfaces.OOOptimizer.result`

the `tuple` (xbest, f(xbest), evaluations_xbest, evaluations, iterations, xmean, stds)