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