0
# CMA-ES (Covariance Matrix Adaptation Evolution Strategy)
1
2
CMA-ES is a stochastic optimizer for robust non-linear non-convex derivative- and function-value-free numerical optimization. It searches for a minimizer of an objective function f, requiring only a passably reliable ranking of candidate solutions in each iteration.
3
4
## Package Information
5
6
- **Package Name**: cma
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install cma`
10
- **Version:** 4.3.0
11
- **Python Compatibility:** 3.8 to 3.13 (intended to be compatible with Python >= 2.7)
12
- **Dependencies:** numpy (required for full functionality), matplotlib (optional, for plotting)
13
- **License:** BSD 3-clause
14
15
## Core Imports
16
17
```python { .api }
18
import cma
19
20
# Main optimization functions
21
from cma import fmin2, fmin, fmin_con2, fmin_con
22
23
# Core classes
24
from cma import CMAEvolutionStrategy, CMA # CMA is an alias
25
from cma import CMAOptions
26
27
# Pure Python implementation
28
from cma import purecma
29
30
# Fitness functions and transformations
31
from cma import ff # fitness functions
32
from cma.fitness_transformations import GlueArguments, ScaleCoordinates
33
34
# Boundary and constraint handlers
35
from cma.boundary_handler import BoundPenalty, BoundTransform, BoundNone, BoundDomainTransform
36
from cma.constraints_handler import ConstrainedFitnessAL, AugmentedLagrangian
37
38
# Logging and analysis
39
from cma import CMADataLogger, disp, plot, plot_zip
40
41
# Optimization tools
42
from cma.optimization_tools import NoiseHandler
43
```
44
45
## Basic Usage
46
47
### Quick Start - Function Minimization
48
49
```python { .api }
50
import cma
51
52
# Simple function minimization
53
def objective(x):
54
return sum(x**2)
55
56
# Method 1: Using fmin2 (recommended)
57
x_best, es = cma.fmin2(objective, x0=[1, 2, 3], sigma0=0.5)
58
print(f"Best solution: {x_best}")
59
print(f"Function value: {es.result.fbest}")
60
61
# Method 2: Using the ask-and-tell interface
62
es = cma.CMAEvolutionStrategy([1, 2, 3], 0.5)
63
while not es.stop():
64
solutions = es.ask()
65
fitness_values = [objective(x) for x in solutions]
66
es.tell(solutions, fitness_values)
67
es.disp()
68
69
print(f"Final result: {es.result}")
70
```
71
72
### Function Signatures - Core Functions
73
74
```python { .api }
75
def fmin2(
76
objective_function,
77
x0,
78
sigma0,
79
options=None,
80
args=(),
81
gradf=None,
82
restarts=0,
83
restart_from_best=False,
84
incpopsize=2,
85
eval_initial_x=None,
86
parallel_objective=None,
87
noise_handler=None,
88
noise_change_sigma_exponent=1,
89
noise_evaluations_as_reward=False,
90
bipop=False,
91
callback=None
92
):
93
"""
94
Main interface function to CMA-ES with optional restarts and noise handling.
95
96
Parameters:
97
-----------
98
objective_function : callable
99
Function to minimize. Takes array-like input, returns scalar.
100
x0 : array-like
101
Initial solution estimate, determines problem dimension.
102
sigma0 : float or array-like
103
Initial standard deviation for coordinate-wise search steps.
104
options : dict, optional
105
CMA-ES options. Use CMAOptions() to see available options.
106
restarts : int, default 0
107
Number of restarts to perform.
108
109
Returns:
110
--------
111
tuple[array, CMAEvolutionStrategy]
112
Best solution found and the evolution strategy instance.
113
"""
114
pass
115
116
def fmin(
117
objective_function,
118
x0,
119
sigma0,
120
options=None,
121
args=(),
122
**kwargs
123
):
124
"""
125
Basic functional interface to CMA-ES optimization (older interface).
126
127
Parameters:
128
-----------
129
objective_function : callable
130
Function to minimize.
131
x0 : array-like
132
Initial solution estimate.
133
sigma0 : float
134
Initial step size.
135
options : dict, optional
136
CMA-ES options dictionary.
137
args : tuple, optional
138
Additional arguments passed to objective function.
139
140
Returns:
141
--------
142
tuple[array, float, int, int, CMAEvolutionStrategy]
143
xbest, fbest, evals_best, evaluations, es
144
"""
145
pass
146
147
def fmin_con2(
148
objective_function,
149
x0,
150
sigma0,
151
g=None,
152
h=None,
153
options=None,
154
**kwargs
155
):
156
"""
157
Constrained optimization using augmented Lagrangian method.
158
159
Parameters:
160
-----------
161
objective_function : callable
162
Objective function to minimize.
163
g : callable, optional
164
Inequality constraint function g(x) <= 0.
165
h : callable, optional
166
Equality constraint function h(x) = 0.
167
168
Returns:
169
--------
170
tuple[array, CMAEvolutionStrategy]
171
Best feasible solution and evolution strategy instance.
172
"""
173
pass
174
175
def fmin_con(
176
objective_function,
177
x0,
178
sigma0,
179
g=None,
180
h=None,
181
options=None,
182
**kwargs
183
):
184
"""
185
Constrained optimization (older interface to fmin_con2).
186
187
Parameters:
188
-----------
189
objective_function : callable
190
Objective function to minimize.
191
g : callable, optional
192
Inequality constraint function.
193
h : callable, optional
194
Equality constraint function.
195
196
Returns:
197
--------
198
tuple
199
Optimization result.
200
"""
201
pass
202
203
class CMAEvolutionStrategy:
204
"""
205
CMA-ES stochastic optimizer class with ask-and-tell interface.
206
"""
207
208
def __init__(self, x0, sigma0, inopts=None):
209
"""
210
Initialize CMA-ES optimizer.
211
212
Parameters:
213
-----------
214
x0 : array-like
215
Initial solution, defines problem dimension N.
216
sigma0 : float or array-like
217
Initial step size(s).
218
inopts : dict, optional
219
Options dictionary, see CMAOptions().
220
"""
221
pass
222
223
def ask(self, number=None, xmean=None, gradf=None, args=()):
224
"""
225
Sample new candidate solutions.
226
227
Parameters:
228
-----------
229
number : int, optional
230
Number of solutions to return (default: popsize).
231
232
Returns:
233
--------
234
list[array]
235
List of candidate solutions.
236
"""
237
pass
238
239
def tell(self, arx, fitnesses, check_points=True, copy=False):
240
"""
241
Update strategy parameters based on function evaluations.
242
243
Parameters:
244
-----------
245
arx : list[array]
246
List of candidate solutions.
247
fitnesses : array-like
248
Corresponding fitness values (to be minimized).
249
"""
250
pass
251
252
def stop(self):
253
"""
254
Check termination criteria.
255
256
Returns:
257
--------
258
dict or False
259
Termination conditions dictionary if stopped, False otherwise.
260
"""
261
pass
262
263
def optimize(self, objective_function, iterations=None, args=(), **kwargs):
264
"""
265
Convenience method to run complete optimization.
266
267
Parameters:
268
-----------
269
objective_function : callable
270
Function to optimize.
271
iterations : int, optional
272
Maximum number of iterations.
273
274
Returns:
275
--------
276
CMAEvolutionStrategy
277
Self (for method chaining).
278
"""
279
pass
280
281
def disp(self, modulo=None):
282
"""
283
Display current state and progress information.
284
285
Parameters:
286
-----------
287
modulo : int, optional
288
Display every modulo iterations (default based on verbosity).
289
"""
290
pass
291
292
def inject(self, solutions, force=False):
293
"""
294
Inject solutions into current population.
295
296
Parameters:
297
-----------
298
solutions : list[array]
299
Solutions to inject.
300
force : bool
301
Force injection even if population is full.
302
"""
303
pass
304
305
@property
306
def sigma(self):
307
"""float: Current overall step size."""
308
pass
309
310
@property
311
def mean(self):
312
"""array: Current distribution mean."""
313
pass
314
315
@property
316
def countiter(self):
317
"""int: Current iteration count."""
318
pass
319
320
@property
321
def countevals(self):
322
"""int: Current evaluation count."""
323
pass
324
325
@property
326
def result(self):
327
"""
328
Optimization result.
329
330
Returns:
331
--------
332
CMAEvolutionStrategyResult
333
Named tuple with fields: xbest, fbest, evals_best, evaluations,
334
iterations, xfavorite, stds, stop.
335
"""
336
pass
337
338
class CMAOptions(dict):
339
"""
340
Dictionary of available CMA-ES options with defaults and documentation.
341
"""
342
343
def __init__(self, s='', **kwargs):
344
"""
345
Create options dictionary.
346
347
Parameters:
348
-----------
349
s : str, optional
350
Search term to filter options by keyword, value, or description.
351
"""
352
pass
353
354
class CMAEvolutionStrategyResult:
355
"""
356
Named tuple-like result object containing optimization results.
357
"""
358
359
@property
360
def xbest(self):
361
"""array: Best evaluated solution."""
362
pass
363
364
@property
365
def fbest(self):
366
"""float: Function value of best solution."""
367
pass
368
369
@property
370
def evals_best(self):
371
"""int: Evaluation count when best solution was found."""
372
pass
373
374
@property
375
def evaluations(self):
376
"""int: Total number of function evaluations."""
377
pass
378
379
@property
380
def iterations(self):
381
"""int: Number of iterations performed."""
382
pass
383
384
@property
385
def xfavorite(self):
386
"""array: Favorite solution (distribution mean)."""
387
pass
388
389
@property
390
def stds(self):
391
"""array: Standard deviations in each coordinate."""
392
pass
393
394
@property
395
def stop(self):
396
"""dict: Termination criteria that were met."""
397
pass
398
```
399
400
## Capabilities
401
402
### [Core Optimization](./core-optimization.md)
403
404
Essential optimization functions and the main CMAEvolutionStrategy class for general-purpose optimization problems.
405
406
**Key Functions:**
407
- `fmin2()` - Main interface with restarts and noise handling
408
- `fmin()` - Basic interface function
409
- `CMAEvolutionStrategy` - Ask-and-tell interface for fine control
410
- `CMA` - Alias for CMAEvolutionStrategy
411
412
**Usage Example:**
413
```python { .api }
414
# Quick optimization
415
x, es = cma.fmin2(cma.ff.sphere, [0, 0, 0], 0.5)
416
417
# Ask-and-tell interface
418
es = cma.CMAEvolutionStrategy([0, 0, 0], 0.5)
419
while not es.stop():
420
X = es.ask()
421
es.tell(X, [cma.ff.sphere(x) for x in X])
422
```
423
424
### [Advanced Optimization](./advanced-optimization.md)
425
426
Specialized optimization techniques including surrogate models and pure Python implementation.
427
428
**Key Functions:**
429
- `fmin_lq_surr2()` - Linear-quadratic surrogate model optimization
430
- `purecma.fmin()` - Pure Python implementation (no numpy dependency)
431
- `NoiseHandler` - Handling of noisy objective functions
432
433
**Usage Example:**
434
```python { .api }
435
# Surrogate model optimization for expensive functions
436
x, es = cma.fmin_lq_surr2(expensive_function, x0, sigma0,
437
options={'maxfevals': 1000})
438
439
# Pure Python implementation
440
import cma.purecma
441
x, es = cma.purecma.fmin(objective, x0, sigma0)
442
```
443
444
### [Configuration and Options](./configuration.md)
445
446
Comprehensive option management and parameter tuning for CMA-ES behavior.
447
448
**Key Classes:**
449
- `CMAOptions` - Option management and defaults
450
- Parameter categories: termination, population, adaptation, bounds
451
452
**Usage Example:**
453
```python { .api }
454
# Explore options
455
opts = cma.CMAOptions() # All options
456
tol_opts = cma.CMAOptions('tol') # Tolerance options
457
458
# Custom configuration
459
options = {'popsize': 50, 'maxiter': 1000, 'tolfun': 1e-12}
460
es = cma.CMAEvolutionStrategy(x0, sigma0, options)
461
```
462
463
### [Constraints and Boundaries](./constraints-boundaries.md)
464
465
Handling of box constraints, boundary conditions, and general constraints.
466
467
**Key Classes:**
468
- `BoundTransform`, `BoundPenalty` - Box constraint handling
469
- `AugmentedLagrangian` - General constraint handling
470
- `fmin_con2()` - Constrained optimization interface
471
472
**Usage Example:**
473
```python { .api }
474
# Box-constrained optimization
475
bounds = [[-5, -5], [5, 5]] # lower, upper bounds
476
x, es = cma.fmin2(objective, x0, sigma0,
477
options={'bounds': bounds})
478
479
# General constraints
480
def constraint(x):
481
return [x[0]**2 + x[1]**2 - 1] # g(x) <= 0
482
483
x, es = cma.fmin_con2(objective, x0, sigma0, g=constraint)
484
```
485
486
### [Samplers and Adaptation](./samplers-adaptation.md)
487
488
Advanced sampling methods and step-size adaptation techniques for specialized optimization scenarios.
489
490
**Key Classes:**
491
- `GaussFullSampler`, `GaussStandardSampler` - Gaussian sampling methods
492
- `CMAAdaptSigmaCSA`, `CMAAdaptSigmaTPA` - Step-size adaptation
493
- `RecombinationWeights` - Parent selection weighting
494
495
**Usage Example:**
496
```python { .api }
497
# Custom sampling configuration
498
from cma.sampler import GaussFullSampler
499
options = {'CMA_sampler': GaussFullSampler}
500
es = cma.CMAEvolutionStrategy([0, 0, 0], 0.5, options)
501
502
# Monitor step-size adaptation
503
while not es.stop():
504
X = es.ask()
505
es.tell(X, [objective(x) for x in X])
506
print(f"Step-size: {es.sigma:.6f}")
507
```
508
509
### [Fitness Functions and Testing](./fitness-functions.md)
510
511
Test functions, benchmarks, and fitness transformations for algorithm testing and validation.
512
513
**Key Modules:**
514
- `ff` - Collection of test functions (sphere, rosenbrock, etc.)
515
- `GlueArguments`, `ScaleCoordinates` - Fitness transformations
516
- BBOB benchmark functions
517
518
**Usage Example:**
519
```python { .api }
520
# Test functions
521
import cma.ff
522
x, es = cma.fmin2(cma.ff.rosen, 5 * [0.1], 0.5)
523
524
# Scaled coordinates
525
from cma.fitness_transformations import ScaleCoordinates
526
scaled_func = ScaleCoordinates([1, 10, 100])(cma.ff.sphere)
527
x, es = cma.fmin2(scaled_func, [1, 1, 1], 0.5)
528
```
529
530
### [Logging and Analysis](./logging-analysis.md)
531
532
Data collection, visualization, and analysis tools for understanding optimization behavior.
533
534
**Key Functions:**
535
- `CMADataLogger` - Comprehensive data logging
536
- `plot()`, `disp()` - Visualization and display functions
537
- Performance analysis tools
538
539
**Usage Example:**
540
```python { .api }
541
# Logging during optimization
542
es = cma.CMAEvolutionStrategy(x0, sigma0, {'verb_disp': 1})
543
logger = cma.CMADataLogger()
544
logger.register(es)
545
546
while not es.stop():
547
X = es.ask()
548
es.tell(X, [objective(x) for x in X])
549
logger.add(es) # Log current state
550
551
# Plotting results
552
logger.plot()
553
cma.plot() # Plot from default data files
554
```
555
556
## Testing
557
558
```python { .api }
559
# Run comprehensive tests
560
import cma.test
561
cma.test.main()
562
563
# From command line
564
# python -m cma.test
565
```
566
567
## References
568
569
- **Source Code:** https://github.com/CMA-ES/pycma
570
- **Algorithm:** Hansen, N. (2006). The CMA Evolution Strategy: A Comparing Review
571
- **Tutorials:** Available notebooks at https://github.com/CMA-ES/pycma/tree/development/notebooks