Crate cmaes

An implementation of the CMA-ES optimization algorithm. It is used to minimize or maximize the value of an objective function and performs well on high-dimension, non-linear, non-convex, ill-conditioned, and/or noisy problems.

Overview

There are three main ways to use cmaes:

The quickest and easiest way is to use a convenience function provided in the functions module, such as fmin or fmax:

use cmaes::DVector;

let sphere = |x: &DVector<f64>| x.iter().map(|xi| xi.powi(2)).sum();
let dim = 10;
let solution = cmaes::fmin(sphere, vec![5.0; dim], 1.0);

Further configuration of a run can be performed by creating and building a CMAESOptions and calling CMAES::run or CMAES::run_parallel. This option provides the most flexibility and customization and allows for visualizing runs through data plots (see Plot; requires the plotters feature).

use cmaes::{CMAESOptions, DVector};

let sphere = |x: &DVector<f64>| x.iter().map(|xi| xi.powi(2)).sum();

let dim = 10;
let mut cmaes_state = CMAESOptions::new(vec![1.0; dim], 1.0)
    .fun_target(1e-8)
    .enable_printing(200)
    .max_generations(20000)
    .build(sphere)
    .unwrap();

let results = cmaes_state.run();

For many problems, it is useful to perform multiple independent restarts of the algorithm with varying initial parameters. The restart module implements several automatic restart strategies to this end. To use them, create and build a RestartOptions and call Restarter::run, Restarter::run_parallel, or another run_* method. This option provides greater robustness in solving more complex problems but provides less control over individual runs and cannot produce data plots.

use cmaes::restart::{RestartOptions, RestartStrategy};
use cmaes::DVector;

let sphere = |x: &DVector<f64>| x.iter().map(|xi| xi.powi(2)).sum();

let dim = 10;
let strategy = RestartStrategy::BIPOP(Default::default());
let restarter = RestartOptions::new(dim, -5.0..=5.0, strategy)
    .fun_target(1e-8)
    .enable_printing(true)
    .build()
    .unwrap();

let results = restarter.run_parallel(|| sphere);

Further configuration

CMAESOptions provides many configurable parameters and can be used to tune the algorithm to each particular problem (though this is usually unnecessary beyond changing the initial mean and step size).

The objective_function module provides traits that allow for custom objective function types that store state and parameters.

The CMAES::next method provides finer control over iteration if needed.

Citations

The following contain more detailed information on the algorithms implemented by this library or were referenced in its implementation.

Auger, Anne and Hansen, Nikolaus. “A Restart CMA Evolution Strategy with Increasing Population Size.” 2005 IEEE Congress on Evolutionary Computation, vol. 2, 2005, pp. 1769-1776 Vol. 2, https://doi.org/10.1109/CEC.2005.1554902.

Hansen, Nikolaus. “Benchmarking a BI-Population CMA-ES on the BBOB-2009 Function Testbed.” GECCO (Companion), July 2009, https://doi.org/10.1145/1570256.1570333.

Auger, Anne, and Nikolaus Hansen. Tutorial CMA-ES. 2013, https://doi.org/10.1145/2464576.2483910.

Hansen, Nikolaus, Akimoto, Youhei, and Baudis, Petr. CMA-ES/Pycma on Github. Feb. 2019, https://doi.org/10.5281/zenodo.2559634.

Re-exports

pub use crate::objective_function::ObjectiveFunction;

pub use crate::objective_function::ParallelObjectiveFunction;

pub use crate::options::CMAESOptions;

pub use crate::parameters::Weights;

pub use crate::plotting::PlotOptions;

pub use crate::termination::TerminationReason;

pub use crate::functions::*;

Modules

functions

Convenience functions for easier use of the library.

objective_function

Traits for types that can be used as an objective function, as well as wrapper types that modify the behavior of objective functions.

options

Types related to initializing a CMAES. See CMAESOptions for full documentation.

parameters

Initialization of constant parameters of the algorithm.

plotting

Types for plotting support. See Plot for usage and what is plotted.

restart

Types for automatic restarting of CMA-ES. Useful for solving complex problems and improving the robustness of the algorithm in general.

termination

Algorithm termination handling. See TerminationReason for full documentation.

Structs

CMAES

A type that handles algorithm iteration and printing/plotting of results. Use CMAESOptions to create a CMAES.

Individual

An individual point with its corresponding objective function value.

TerminationData

Data returned when the algorithm terminates.

Enums

Mode

The mode to use when optimizing a function.

Constants

MAX_HISTORY_LENGTH

The maximum number of elements to store in the objective function value histories.

Type Aliases

DVector

A dynamically sized column vector.