class documentation

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.


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.


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

Instantiate CMAES object instance using xstart and sigma.


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.

def ask(self):

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

print some iteration info to stdout

def stop(self):

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

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


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 =


C =


counteval: int =


fitvals =


ftarget =


logger =


maxfevals =


params =


pc =


ps =


randn =


sigma =


xmean =


result =

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