{"id":4479,"library":"cma","title":"CMA-ES (pycma) for Numerical Optimization","description":"CMA-ES (pycma) is a Python implementation of the Covariance Matrix Adaptation Evolution Strategy, a robust randomized derivative-free numerical optimization algorithm. It is designed for challenging non-convex, ill-conditioned, multi-modal, rugged, and noisy problems in continuous and mixed-integer search spaces. The library is currently at version 4.4.4 and maintains an active release cadence with regular improvements and bug fixes.","status":"active","version":"4.4.4","language":"en","source_language":"en","source_url":"https://github.com/CMA-ES/pycma.git","tags":["optimization","CMA-ES","evolutionary algorithms","numerical optimization","derivative-free optimization"],"install":[{"cmd":"pip install cma","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for the main `cma.CMAEvolutionStrategy` implementation for array processing. The `cma.purecma` submodule can function without it but is slower.","package":"numpy","optional":false},{"reason":"Highly recommended for plotting optimization progress and results.","package":"matplotlib","optional":true}],"imports":[{"note":"`cma.fmin2` is the recommended functional interface for running a complete minimization with additional options like restarts and noise handling. The older `cma.fmin` had a different return signature.","wrong":"cma.fmin() (older interface)","symbol":"fmin2","correct":"import cma\ncma.fmin2(...)"},{"note":"For an 'ask-and-tell' interface, providing more control over the iteration loop. `cma.fmin2` returns an instance of this class.","symbol":"CMAEvolutionStrategy","correct":"import cma\nes = cma.CMAEvolutionStrategy(...)\nes.ask()\nes.tell(...)"}],"quickstart":{"code":"import cma\nimport numpy as np\n\ndef rosenbrock(x):\n    \"\"\"The Rosenbrock function for demonstration.\"\"\"\n    return sum(\n        100.0 * (x[i + 1] - x[i]**2)**2 + (1 - x[i])**2\n        for i in range(len(x) - 1)\n    )\n\n# Define initial solution and initial step-size (sigma)\n# For a 10-dimensional problem, starting near the origin.\ninitial_solution = 10 * [0.1]  # [0.1, 0.1, ..., 0.1]\ninitial_sigma = 0.5\n\n# Run the CMA-ES optimization using fmin2\n# fmin2 returns (x_best, CMAEvolutionStrategy_instance)\nx_best, es = cma.fmin2(\n    rosenbrock,\n    initial_solution,\n    initial_sigma,\n    options={'maxfevals': 10000, 'verb_log': 0} # Limit evaluations, suppress logging for quick run\n)\n\nprint(f\"Optimization finished after {es.result.evaluations} evaluations.\")\nprint(f\"Best solution found: {np.round(x_best, 4)}\")\nprint(f\"Objective value at best solution: {es.result.fbest}\")\n\n# Detailed results can be accessed via es.result or es.result_pretty()\n# print(es.result_pretty())\n","lang":"python","description":"This quickstart optimizes the 10-dimensional Rosenbrock function using `cma.fmin2`, starting from an initial solution of all 0.1s and an initial step-size (sigma) of 0.5. It demonstrates how to define an objective function and call the primary optimization interface."},"warnings":[{"fix":"Use `cma.fmin2()` and access results via the returned `CMAEvolutionStrategy` instance (e.g., `es.result.xbest`, `es.result.fbest`).","message":"The return signature of `cma.fmin` changed significantly. Prior to version 2.4.2, `cma.fmin` returned a 10-tuple. Since version 2.4.2, `cma.fmin2` (the recommended interface) returns a `(x_best, es)` tuple, where `es` is a `CMAEvolutionStrategy` instance containing all detailed results in `es.result`. Update old code to use `fmin2` and access results through the `es` object.","severity":"breaking","affected_versions":"<= 2.4.1 (fmin) vs >= 2.4.2 (fmin2)"},{"fix":"Switch to using `cma.BoundDomainTransform` for consistent boundary handling.","message":"The `cma.constraints_handling.BoundTransform` class was deprecated/temporarily missing in version 4.1.0. While re-added in 4.4.2 for compatibility, the recommended and stable way to handle bound constraints is `cma.BoundDomainTransform`.","severity":"breaking","affected_versions":"4.1.0 - 4.4.1"},{"fix":"Ensure the optimization problem has a dimensionality greater than one. For 1D optimization, consider other algorithms.","message":"The library explicitly states that optimization in 1-D is not supported and will raise a `ValueError`. CMA-ES is typically designed for higher-dimensional problems.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `cma` version 4.4.2 or later to ensure compatibility with recent `matplotlib` versions.","message":"Older versions of `pycma` (prior to 4.4.2) experienced plotting issues when used with `matplotlib > 3.8.0`. These compatibility problems have been addressed in recent releases.","severity":"gotcha","affected_versions":"< 4.4.2"},{"fix":"For performance-critical applications, always ensure `numpy` is installed and use the main `cma` module (e.g., `cma.fmin2`, `cma.CMAEvolutionStrategy`). `cma.purecma` is better suited for educational purposes or environments where `numpy` cannot be installed.","message":"The `cma.purecma` submodule, while having minimal dependencies (no `numpy` requirement), is significantly slower than the main `cma` implementation, which heavily relies on `numpy` for performance.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}