ModularCMAES
No description available
Install / Use
/learn @IOHprofiler/ModularCMAESREADME
The Modular CMA-ES is a Python and C++ package that provides a modular implementation of the Covariance Matrix Adaptation Evolution Strategy (CMA-ES) algorithm. This package allows you to create various algorithmic variants of CMA-ES by enabling or disabling different modules, offering flexibility and customization in evolutionary optimization. In addition to the CMA-ES, the library includes an implementation of the Matrix Adaptation Evolution Strategy (MA-ES) algorithm, which has similar emprical performance on most problems, but signifanctly lower runtime. All modules implemented are compatible with both the CMA-ES and MA-ES.
This implementation is based on the algorithm introduced in the paper "Evolving the Structure of Evolution Strategies. (2016)" by Sander van Rijn et. al. If you would like to cite this work in your research, please cite the paper: "Tuning as a Means of Assessing the Benefits of New Ideas in Interplay with Existing Algorithmic Modules (2021)" by Jacob de Nobel, Diederick Vermetten, Hao Wang, Carola Doerr and Thomas Bäck.
This README provides a high level overview of the implemented modules, and provides some usage examples for both the Python-only and the C++-based versions of the framework.
Table of Contents
Installation <a name="installation"></a>
You can install the Modular CMA-ES package using pip.
Python Installation
pip install modcma
Installation from source
If you want to work on a development version of the library, you should follow the following steps. A C++ compiler is required, and the following is valid for g++ (v11.1.0):
-
Clone the repository:
git clone git@github.com:IOHprofiler/ModularCMAES.git cd ModularCMAES -
Install dependencies (in a virtual environment)
python3 -m venv env source ./env/bin/activate pip install -r requirements.txt -
Compile the library, we can optionally install the package globally:
python setup.py installor install in develop mode, which is recommended if one would like to actively develop the library:
python setup.py develop -
Ensure all functionality works as expected by running the unittests:
python -m unittest discover
Usage <a name="usage"></a>
Note:
The C++ backend is the primary and recommended interface for ModularCMAES.
The pure Python implementation remains available for reference and educational purposes,
but is no longer actively developed and may not include all new module options or performance improvements.
C++ Backend <a name="c-backend"></a>
For performance, completeness, and modularity, the C++ backend is the recommended interface for ModularCMAES. It exposes all available modules and options through a direct Python binding.
High Level interface <a name="high-level-interface"></a>
In addition to the fully specified method described below, we can run an optimization via a friendly fmin interface:
x0 = [0, 1, 2, 3] # Location to start the search from
sigma0 = 0.234 # Initial estimate of the stepsize, try 0.3 * (ub - lb) if you're unsure
budget = 100 # Total number of function evaluations
xopt, fopt, evals, cma = c_maes.fmin(
func, x0, sigma0, budget,
# We can specify modules and setting values as keyword arguments
active=True,
target=10.0,
cc=0.8
matrix_adaptation='NONE'
)
Note that the func, x0, sigma0 and budget arguments are required. Modules and settings can be specified via keyword arguments by they corresponding names in the Modules and Settings objects. Module options, such as matrix_adaptation in the above example, can be specified by their name as str.
Low Level interface <a name="low-level-interface"></a>
To run an optimization, first create a Modules object specifying which modules and options to enable. Then construct a Settings object (which defines problem dimension and strategy parameters), and pass it through a Parameters object to the optimizer:
from modcma import c_maes
# Instantiate module configuration
modules = c_maes.parameters.Modules()
modules.active = True
modules.matrix_adaptation = c_maes.parameters.MatrixAdaptationType.MATRIX
# Create Settings and Parameters objects
settings = c_maes.parameters.Settings(dim=10, modules=modules, sigma0=2.5)
parameters = c_maes.Parameters(settings)
# Instantiate the optimizer
cma = c_maes.ModularCMAES(parameters)
# Define objective function
def func(x):
return sum(x**2)
# Run the optimization
cma.run(func)
The API provides fine-grained control over the optimization process. Instead of calling run, you can explicitly step through the algorithm:
while not cma.break_conditions():
cma.step(func)
Or execute the internal components of each iteration separately:
while not cma.break_conditions():
cma.mutate(func)
cma.select()
cma.recombine()
cma.adapt()
This modularity allows experimentation with specific parts of the evolution strategy, such as custom selection, recombination, or adaptation routines.
Tuning <a name="tuning"></a>
To facilitate automated hyperparameter tuning, ModularCMAES now provides functionality to create and manipulate configuration spaces directly compatible with popular optimization and AutoML tools, such as SMAC, BOHB. This functionality allows users to systematically explore both algorithmic module combinations and numerical hyperparameters (e.g., population size, learning rates, damping coefficients).
Configuration Space Generation
The configuration space is automatically derived from the available modules and tunable parameters via the function:
from modcma.cmaescpp import get_configspace
Usage:
from modcma.cmaescpp import get_configspace
# Create a configuration space for a 10-dimensional problem
cs = get_configspace(dim=10)
This function returns a ConfigSpace.ConfigurationSpace object containing:
- Categorical parameters for all available modules (e.g., mirrored sampling, restart strategy, bound correction).
- Numeric parameters for key internal strategy settings such as
lambda0,mu0,sigma0,cs,cc,cmu,c1, anddamps. - A built-in constraint ensuring
mu0 ≤ lambda0. - Optionally, the configuration space can include only module-level options by setting
add_popsize=False, add_sigma=False, add_learning_rates=False.
Example:
# Get only the module configuration space (no numeric parameters)
cs_modules = get_configspace(add_popsize=False, add_sigma=False, add_learning_rates=False)
Creating Settings from a Configuration
Once a configuration has been selected—either manually or from a tuner—the library provides a simple interface to construct a corresponding Settings object:
from modcma.cmaescpp import settings_from_config
from ConfigSpace import Configuration
# Sample or load a configuration
config = cs.sample_configuration()
# Or for defaults
default = cs.default_configuration()
# The config can be edited
config['sampler'] = 'HALTON'
# Convert the configuration to a Settings object
# Note that keyword arguments like lb in the next example, can be passed to settings like so
settings = settings_from_config(dim=10, config=config, lb=np.ones(10))
The resulting Settings object can then be passed directly to the C++ backend:
from modcma impor
