CMA-ES/pycma: derivative-free optimization in Python

Why CMA-ES/pycma targets difficult numerical search

CMA-ES/pycma solves derivative-free numerical optimization problems in Python. The README positions it for continuous and mixed-integer search spaces, especially cases described as non-convex, ill-conditioned, multi-modal, rugged, or noisy. That target is narrower and more technically demanding than ordinary scalar minimization. The package does not require derivatives from the objective function, which makes it applicable when gradients are unavailable, impractical to derive, or unreliable.

The intended audience includes engineers, scientists, researchers, and IPython or Jupyter users. The `pyproject.toml` classifies the package under scientific and engineering software, mathematics, artificial intelligence, education, and general research. Its dependency list is deliberately small: `cma` requires `numpy`. That makes it more plausible to add to an existing Python numerical environment than a package with a larger dependency graph.

The implementation includes several constraint and domain options. Bounds can be supplied through `'bounds' = [lower, upper]` or handled through `cma.BoundDomainTransform`. Linear and nonlinear constraints use the `constraints` argument to `fmin2` or `fmin_con2`. Noise can be addressed with `noise_handler=True` in `fmin2`, while mixed-integer variables use `'integer_variables'=index_list`. These are explicit features listed by the README.

CMA-ES is a randomized algorithm, so evaluation involves search rather than a single deterministic calculation. That makes stochastic settings, termination criteria, and repeated runs relevant to adoption. The README points to a dedicated notebook for the `ask`-and-`tell` interface, which suggests that evaluations can be organized separately from the optimizer's request cycle. It does not document rollback, parallel evaluation, or a distributed execution model.

The cma package structure and optimizer interfaces

The importable package is named `cma`, although the repository is named `CMA-ES/pycma` and the PyPI distribution is `cma`. The source lives in the top-level `cma/` directory. Supporting project files include `pyproject.toml`, packaging configuration, notebooks, and tooling under `tools/`. The README links to API documentation and to four notebooks covering basic use, constraints, `ask`-and-`tell`, and noise handling.

At the API level, the README names `fmin2` and `fmin_con2` as paths for handling linear and nonlinear constraints. It also identifies `cma.CMAEvolutionStrategyResult2` as the result type associated with the package's `fmin2`-style workflows. Release `r4.5.0` adds `runs` to that result type and adds module attributes named `all_stoppings` and `all_best`, which collect information across restarts. These names give implementers concrete places to inspect when they need run-level rather than only final-result information.

The separate `ask`-and-`tell` notebook indicates another integration pattern. In that model, an external evaluator can receive requested candidate solutions and return objective information, rather than requiring all evaluations to be hidden inside a single minimization call. The repository also provides `optimization_tools.EvaluationsIterator` for computing non-discretized ERT values from non-f-targeted data, according to the `r4.5.0` release notes. This is evaluation and analysis support, not evidence of an automatic distributed scheduler.

The source tree includes focused algorithm modules. The release notes specifically mention revisions to step-size implementations in `sigma_adaptation.py`, constraints handling through `AugmentedLagrangian`, transformations, ridge fitness functions, statistical tests, plotting conveniences such as `s.figpolish` and `s.grid`, and `CountWarnings` with `deliver_warnings`. That breadth is relevant during upgrades because the package is more than a single optimizer function.

Installing cma and reaching the documented examples

The README's recommended installation path uses the `cma` package from PyPI. Run this in a system shell to install the latest release:

python -m pip install cma

To upgrade an existing installation to the latest release, the README directs readers to replace `install` with `install -U`:

python -m pip install -U cma

For work against the repository's `development` branch, the documented GitHub installation command is:

pip install git+https://github.com/CMA-ES/pycma.git@development

That route requires `git`. A checkout can also be used in editable mode. After obtaining the repository and changing into its `pycma` folder, run:

pip install -e .

The README warns that moving the `cma` source folder away invalidates this editable installation. It also notes that `pip` may need to be replaced with `python -m pip`, depending on the environment.

A real first use should begin with the repository's `notebooks/notebook-usecases-basics.ipynb`, rather than an undocumented one-line optimization call. The README links to that notebook and to separate notebooks for constraints, `ask`-and-`tell`, and noise, but it does not reproduce their source code. The same limitation applies to the PyPI quick start, which is linked rather than included in the README.

The `pyproject.toml` declares the build backend as `setuptools.build_meta`, with `setuptools >=79` required for the build. Runtime dependency resolution is limited to `numpy`.

Constraints, bounds, integers, and noisy evaluations

The package treats problem constraints as first-class options rather than requiring every caller to encode them into the objective. For variable bounds, the README gives both an `'bounds' = [lower, upper]` option and `cma.BoundDomainTransform`. Linear and nonlinear constraints are passed through the `constraints` argument to `fmin2` or `fmin_con2`. The release history says `AugmentedLagrangian` constraints handling received a major revision and initialization fix in `r4.5.0`, so callers should pay particular attention to that area when validating an upgrade.

Noise support is exposed through `noise_handler=True` for `fmin2`. The existence of a dedicated noise notebook is useful because a noisy objective changes how observed quality relates to the underlying search process. However, the README does not state a default noise model, tolerance policy, or universal configuration for stochastic evaluators. It would therefore be unsafe to promise that one setting handles every noise pattern.

For mixed-integer problems, `'integer_variables'=index_list` identifies integer coordinates. This is coordinate-based mixed-integer support, not a general declaration of an arbitrary discrete combinatorial encoding. Pycma is not the right fit when the only legal values come from large arbitrary sets, unless the application develops an appropriate encoding outside what the repository documents.

The package also exposes analysis and presentation controls. Release `r4.5.0` reports improved ridge fitness functions, low-effective-dimension functions and transformations, and plotting conveniences. Those additions can help inspect behavior on specially shaped landscapes, but they do not mean that every optimization result is interpretable automatically. Users still need a meaningful objective scale, documented parameter bounds, and an evaluation budget.

Version changes and the maintenance review burden

The repository is not archived, and its last push was on 2026-10-14. Three recent releases are listed: `r4.5.0` on 2026-09-13, `r4.4.4` on 2026-02-25, and `r4.4.3` on 2026-02-24. These dates support recent development activity. They do not establish that every optimizer path has equal test coverage or that an upgrade will preserve a particular result.

The scope of `r4.5.0` is broad enough to warrant validation. It changes console overwrite behavior through `verb_disp_overwrite`, introduces run and restart information, revises step-size implementations, changes default TPA step-size adaptation for dimensions at or above `cma.evolution_strategy.TPA_dimension = 300`, improves constraints handling, and adds several analysis and plotting facilities. A team upgrading from an earlier release should compare its own objective, dimensions, termination settings, and output parsing against these changes.

The `r4.4.4` entry records a fix associated with issue 343. The `r4.4.3` entry changes step-size damping for CSA and TPA and introduces `'TPA_dampfac'` parallel to `'CSA_dampfac'`. The release notes themselves state mixed effects across the cited `bbob-f24` and `bbob-f23` cases. That is a useful warning against assuming every numerical change improves every benchmark.

Licensing metadata needs direct inspection. The repository classification says `LICENSE` is a custom licence that GitHub cannot classify, while `pyproject.toml` declares `license = "BSD-3-Clause"` and includes `license-files = ["LICENSE"]`. This review cannot resolve that mismatch without reading the actual file, which is not included. Organizations should verify the repository's `LICENSE` and package metadata before redistribution or integration; this is a compliance check, not legal advice.

Where CMA-ES differs from gradient and discrete optimizers

Another alternative is a discrete optimizer for a search space whose variables are inherently categorical rather than mixed numeric and integer. pycma's documented integer-variable mechanism identifies integer coordinates in a continuous search formulation. It does not advertise native support for arbitrary categorical domains, combinatorial permutations, or a graph-constrained search space. Such a problem would require an encoding or a tool designed around the domain's discrete constraints.

pycma's differentiator is not simply the CMA-ES name. The package exposes practical handlers for bounds, nonlinear constraints, noise, and integer coordinates, plus notebooks and result objects for experimentation. Its trade-off is that a stochastic, derivative-free process can consume many objective evaluations, and the README does not promise a global optimum. Search behavior depends on the objective, parameterization, dimensions, budget, and stopping policy.

Editorial conclusion

Adopt CMA-ES/pycma when you have a derivative-free, potentially non-convex optimization problem and need explicit support for bounds, nonlinear constraints, noise, or integer variables. Do not choose it as a default for a smooth objective with an efficient gradient method available, or for a discrete-only search space outside the documented mixed-integer support. Check the objective definition, constraint return convention, stopping controls, and the exact `LICENSE` file before incorporating it into a product, because the project metadata names BSD-3-Clause while the repository classification describes the `LICENSE` file as a custom licence that GitHub cannot classify.

Frequently asked questions

Official sources

1. CMA-ES/pycma on GitHub
2. Issues
3. README
4. Releases