clinamen2.cmaes package

Submodules

clinamen2.cmaes.cmaes_criteria module

Implementation of the termination criteria as described in

References:

[1] N. Hansen, 2016, arXiv:1604.00772 [cs.LG]

class clinamen2.cmaes.cmaes_criteria.ConditionCovCriterion(parameters, threshold=100000000000000.0)[source]

Bases: Criterion

ConditionCov criterion

Stop if the condition number of the covariance matrix exceeds 1e14.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
threshold (float) – Upper limit for accepted condition number. Default is 1e14.

init()[source]

Initialize the associated NamedTuple.

Return type:: ConditionCovState

met(criterion_state)[source]

Decide if the stopping criterion is met.

Parameters:: criterion_state (ConditionCovState) – The associated NamedTuple representing the current stopping criterion state.
Return type:: bool

update(criterion_state, state, population, loss)[source]

Return an updated associated NamedTuple.

Parameters:

criterion_state (ConditionCovState) – The associated NamedTuple representing the current stopping criterion state.
state (AlgorithmState) – New algorithm state based on which to update the stopping criterion.
population (numpy.typing.ArrayLike) – New population based on which to update the stopping criterion.
loss (numpy.typing.ArrayLike) – New loss values based on which to update the stopping criterion.

Return type:

ConditionCovState

class clinamen2.cmaes.cmaes_criteria.ConditionCovState(cond=None)[source]

Bases: NamedTuple

NamedTuple to keep track of condition number

Parameters:: cond (float) – Condition number of C.

cond: float: Alias for field number 0

class clinamen2.cmaes.cmaes_criteria.EqualFunValuesCriterion(parameters, generation_span=0, atol=1e-15)[source]

Bases: Criterion

EqualFunValues criterion

Stop if the range of the loss within a certain range of generations is close to zero.

Parameters:

parameters (AlgorithmParameters) – The algorithm parameters.
generation_span (int) – Number of generations over which the range of function values is to be taken into account. Default is 10 + ceil(30 dimension / pop_size).
atol (float) – Tolerance for ‘zero’. Default is 1e-15.

init()[source]

Initialize the associated NamedTuple.

Return type:: EqualFunValuesState

met(criterion_state)[source]

Decide if the stopping criterion is met.

Parameters:: criterion_state (EqualFunValuesState) – The associated NamedTuple representing the current stopping criterion state.
Return type:: bool

update(criterion_state, state, population, loss)[source]

Return an updated associated NamedTuple.

Parameters:

criterion_state (EqualFunValuesState) – The associated NamedTuple representing the current stopping criterion state.
state (AlgorithmState) – New algorithm state based on which to update the stopping criterion.
population (numpy.typing.ArrayLike) – New population based on which to update the stopping criterion.
loss (numpy.typing.ArrayLike) – New loss values based on which to update the stopping criterion.

Return type:

EqualFunValuesState

class clinamen2.cmaes.cmaes_criteria.EqualFunValuesState(fun_values=None)[source]

Bases: NamedTuple

NamedTuple to keep track of function value staleness.

Parameters:: fun_values (deque) – Function values of past generations to be taken into account.

fun_values: deque: Alias for field number 0

class clinamen2.cmaes.cmaes_criteria.TolXUpCriterion(parameters, threshold=10000.0, interpolative=False)[source]

Bases: Criterion

TolXUp criterion

Stop if sigma times max(diag(D)) exceeds a threshold when compared to the previous generation.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
threshold (float) – Upper limit for accepted difference. Default is 1e4.
interpolative (bool) – Control how the matrix norm is calculated. True: ‘scipy.linalg.interpolative.estimate_spectral_norm’ False: ‘scipy.linalg.norm’ Default is False. Use True for large matrices.

init()[source]

Initialize the associated NamedTuple.

Return type:: TolXUpState

met(criterion_state)[source]

Decide if the stopping criterion is met.

Parameters:: criterion_state (TolXUpState) – The associated NamedTuple representing the current stopping criterion state.
Return type:: bool

update(criterion_state, state, population, loss)[source]

Return an updated associated NamedTuple.

Parameters:

criterion_state (TolXUpState) – The associated NamedTuple representing the current stopping criterion state.
state (AlgorithmState) – New algorithm state based on which to update the stopping criterion.
population (numpy.typing.ArrayLike) – New population based on which to update the stopping criterion.
loss (numpy.typing.ArrayLike) – New loss values based on which to update the stopping criterion.

Return type:

TolXUpState

class clinamen2.cmaes.cmaes_criteria.TolXUpState(compare_to=None, latest_diff=None)[source]

Bases: NamedTuple

NamedTuple to keep track of function value staleness.

Parameters:

compare_to (float) – Previous value of tolxup saved for comparison.
latest_diff (float) – Latest calculated absolute difference in tolxup values.

compare_to: float: Alias for field number 0

latest_diff: float: Alias for field number 1

clinamen2.cmaes.params_and_state module

The core Cholesky CMA-ES implementation.

References

[1] O. Krause, D. R. Arbonès, C. Igel, “CMA-ES with Optimal Covariance Update and Storage Complexity”, part of [2], 2016.

[2] D. Lee, M. Sugiyama, U. Luxburg, I. Guyon, R. Garnett, “Advances in Neural Information Processing Systems 29, 2016.

class clinamen2.cmaes.params_and_state.AlgorithmParameters(dimension, initial_step_size, random_seed, pop_size, mu, weights, c_sigma, d_sigma, c_m, c_c, c_1, c_mu)[source]

Bases: object

Class for keeping track of the initial, immutable parameters of a run.

You are unlikely to need to manually instantiate this class. Use init_default_algorithm_parameters instead, which provides a simpler interface covering common use cases and uses recommended defaults wherever possible. Directly instantiating this class offers more flexibility, but deviating from the literature recommendations for parameter defaults without good reason is not encouraged.

Basic checks on parameters are performed upon direct instantiation, but no defaults are used. Every single parameter is therefore required.

See References for more information on individual parameters.

Parameters:

dimension (int) – The dimensionality of the problem.
initial_step_size (float) – Global step size at the beginning of a run.
random_seed (int) – Random seed to start the run with.
pop_size (int) – The size of the “population”, i.e., of each sample of random deviates.
mu (int) – Parent number, equal to the number of positive weights. In the standard flavor of CMA-ES (with no negative weights), it is the mu best-ranked individuals that contribute to the update of the normal distribution.
weights (numpy.typing.ArrayLike) – The pop_size weights used in the algorithm.
c_sigma (float) – The learning rate for the conjugate evolution path used for step-size control. It must lie in (0, 1).
d_sigma (float) – The damping term, which must be positive.
c_m (float) – The learning rate for updating the mean. Generally 1, usually <= 1.
c_c (float) – The learning rate for the evolution path used in the cumulation procedure. It must lie in [0, 1].
c_1 (float) – The learning rate for the rank-1 update of the covariance matrix. It must lie in [0, 1 - c_mu].
c_mu (float) – The learning rate for the rank-mu update of the covariance matrix. It must lie in [0, 1 - c_1].

c_1: float

c_c: float

c_m: float

c_mu: float

c_sigma: float

d_sigma: float

dimension: int

initial_step_size: float

mu: int

pop_size: int

random_seed: int

weights: numpy.typing.ArrayLike

class clinamen2.cmaes.params_and_state.AlgorithmState(random_state, mean, cholesky_factor, step_size, generation, p_sigma, p_c)[source]

Bases: object

Class for keeping track of the state of the run.

Includes the CMA-ES data (e.g. mean) and keeps track of the random state.

Parameters:

random_state (dict) – Dictionary representing the state of the random generator numpy.random.default_rng().
mean (numpy.typing.ArrayLike) – Mean of the Gaussian.
cholesky_factor (numpy.typing.ArrayLike) – Cholesky factor of the covariance matrix.
step_size (float) – Global standard deviation of the Gaussian.
generation (int) – The generation number.
p_sigma (numpy.typing.ArrayLike) – Evolution path of step size.
p_c (numpy.typing.ArrayLike) – Evolution path of the covariance.

cholesky_factor: numpy.typing.ArrayLike

generation: int

mean: numpy.typing.ArrayLike

p_c: numpy.typing.ArrayLike

p_sigma: numpy.typing.ArrayLike

random_state: dict

step_size: float

clinamen2.cmaes.params_and_state.calculate_new_mean(parameters, original_state, population)[source]

Calculates the new mean of the distribution.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
original_state (AlgorithmState) – State of the previous CMA step.
population (numpy.typing.ArrayLike) – Individuals of the current generation.

Return type:

numpy.typing.ArrayLike

Returns:

The new mean of the distribution.

clinamen2.cmaes.params_and_state.create_init_algorithm_state(parameters)[source]

Create function that initializes an AlgorithmState.

Parameters:: parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
Return type:: Callable
Returns:: A function for initializing an AlgorithmState.

clinamen2.cmaes.params_and_state.create_resample_and_evaluate(sample_individuals, evaluate_batch, evaluate_single, input_pipeline_batch=<function <lambda>>, input_pipeline_single=<function <lambda>>)[source]

Create function that samples a population and evaluates its loss.

Samples that are rejected, i.e., they come with an exception are resampled.

Parameters:

sample_individuals (Callable) – Function that samples a number of individuals from a state.
evaluate_batch (Callable) – Function that returns a tuple containing the loss of a batch of individuals and additional information in a dictionary (at least exception if applicable).
evaluate_single (Callable) – Function that returns a tuple containing the loss of an individual and additional information in a dictionary (at least exception if applicable).
input_pipeline_batch (Callable) – Transform dof such that evaluate_loss can handle the data. Default is identity.
input_pipeline_single (Callable) – Transform dof such that evaluate_loss can handle the data. Default is identity.

Return type:

Callable

Returns:

A function to sample (with resampling) and evaluate a population from a state.

clinamen2.cmaes.params_and_state.create_sample_and_evaluate(sample_individuals, evaluate_loss, input_pipeline=<function <lambda>>)[source]

Create function that samples a population and evaluates its loss.

Parameters:

sample_individuals (Callable) – Function that samples a number of individuals from a state.
evaluate_loss (Callable) – Function that returns the loss of one individual or a population of individuals.
input_pipeline (Callable) – Transform dof such that evaluate_loss can handle the data. Default is identity.

Return type:

Callable

Returns:

A function to sample and evaluate a population from a state.

clinamen2.cmaes.params_and_state.create_sample_and_run(sample_individuals, runner)[source]

Create function that samples a population and evaluates its loss.

Utilizes an instance of Runner. With resampling for failures.

Parameters:

sample_individuals (Callable) – Function that samples a number of individuals from a state.
runner (Runner) – Function that submits all individuals to a Runner and pops the results.

Return type:

Callable

Returns:

A function to sample and evaluate a population from a state.

clinamen2.cmaes.params_and_state.create_sample_and_sequential_evaluate(sample_individuals, evaluate_loss, input_pipeline=<function <lambda>>)[source]

Create function that samples a population and evaluates its loss.

Parameters:

sample_individuals (Callable) – Function that samples a number of individuals from a state.
evaluate_loss (Callable) – Function that returns the loss of one individual or a population of individuals.
input_pipeline (Callable) – Transform dof such that evaluate_loss can handle the data. Default is identity.

Return type:

Callable

Returns:

A function to sample and evaluate a population from a state.

clinamen2.cmaes.params_and_state.create_sample_from_state(parameters)[source]

Create function that samples a population.

Parameters:: parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
Return type:: Callable
Returns:: A function to sample invididuals from a state.

clinamen2.cmaes.params_and_state.create_update_algorithm_state(parameters)[source]

Create function that creates an updated AlgorithmState.

Parameters:: parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
Return type:: Callable
Returns:: A function for getting an updated AlgorithmState.

clinamen2.cmaes.params_and_state.init_default_algorithm_parameters(dimension, pop_size=None, alpha_cov=2.0, initial_step_size=1.0, random_seed=0)[source]

Initialize CMA-ES parameters to recommended defaults wherever possible.

This function is the recommended way of instantiating an AlgorithmParameters object. It exposes only a minimal set of options to the user and computes all other parameters from these using literature defaults. The only strictly required argument is the dimension.

Weights for ranks > mu are initialized to zero, i.e., no negative weights as in Ref. [1] are used.

Parameters:

dimension (int) – The dimensionality of the problem, i.e., number of degrees of freedom.
pop_size (Optional[int]) – The number of samples drawn from the Gaussian at each generation. If not given, it is calculated from the dimension according to pop_size = 4 + floor(3 * log(dimension)). Using smaller values than this default is not recommended.
alpha_cov (float) – A parameter that enters into the calculation of defaults for the learning rates used in covariance matrix update.
initial_step_size (float) – Global step size at the beginning of a run.
random_seed (int) – Random seed to start the run with.

Return type:

AlgorithmParameters

Returns:

An initialized AlgorithmParameters object.

clinamen2.cmaes.params_and_state.rank_one_update(A, beta, v)[source]

Perform the rank-one update of the Cholesky factor as described in [1].

Parameters:

A (numpy.typing.ArrayLike) – Cholesky factor of the covariance matrix.
beta (float) – Pre-factor (expected: learning rate * weight).
v (numpy.typing.ArrayLike) – Centered individual.

Return type:

numpy.typing.ArrayLike

Returns:

Cholesky factor A’ of (C + beta*v*v.T).

clinamen2.cmaes.termination_criterion module

Classes and functions implementing the CMA-ES termination criteria.

class clinamen2.cmaes.termination_criterion.CriteriaAnd(parameters, criteria)[source]

Bases: CriteriaCombination

Class that combines criteria that all have to be fulfilled.

Evaluates multiple criteria (instances of Criterion). All have to meet their respective parameters for the CriterionAnd to be met.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
criteria (Sequence) – Sequence of criteria to be combined.

met(criterion_state)[source]

Parameters:: criterion_state (CriteriaCombinationState) – NamedTuple containing tuple of criteria states.
Return type:: bool
Returns:: True if all criteria are fulfilled, False if any is not.

clinamen2.cmaes.termination_criterion.CriteriaAndState: alias of CriteriaCombinationState

class clinamen2.cmaes.termination_criterion.CriteriaCombination(parameters, criteria)[source]

Bases: Criterion, ABC

Abstract class that combines criteria.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
criteria (Sequence) – Sequence of criteria to be combined.

init()[source]

Initialize the associated CriterionState instances.

Return type:: Sequence

abstract met(criterion_state)[source]

Parameters:: criterion_state (CriteriaCombinationState) – NamedTuple containing tuple of criteria states.
Return type:: bool
Returns:: True if criteria combination is fulfilled, False otherwise.

update(criterion_state, state, population, loss)[source]

Function to update and return the criteria

Parameters:

criterion_state (CriteriaCombinationState) – NamedTuple containing tuple of criteria states.
state (AlgorithmState) – Current state of the evolution.
population (numpy.typing.ArrayLike) – Current generation of individuals.
loss (numpy.typing.ArrayLike) – Loss of each of the current individuals.

Return type:

CriteriaCombinationState

Returns:

NamedTuple with tuple of the updated states of the criteria.

class clinamen2.cmaes.termination_criterion.CriteriaCombinationState(criteria_states)[source]

Bases: NamedTuple

NamedTuple to keep track of a tuple of criterion states.

Parameters:: criteria_states (tuple) – Tuple containing criteria states.

criteria_states: tuple: Alias for field number 0

class clinamen2.cmaes.termination_criterion.CriteriaOr(parameters, criteria)[source]

Bases: CriteriaCombination

Class that combines criteria were one has to be fulfilled.

Evaluates multiple criteria (instances of Criterion). Any one has to meet their respective parameters for the CriterionOr to be met.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
criteria (Sequence) – Sequence of criteria to be combined.

met(criterion_state)[source]

Parameters:: criterion_state (CriteriaCombinationState) – NamedTuple containing tuple of criteria states.
Return type:: bool
Returns:: True if any criteria is fulfilled, False if none are.

clinamen2.cmaes.termination_criterion.CriteriaOrState: alias of CriteriaCombinationState

class clinamen2.cmaes.termination_criterion.Criterion(parameters)[source]

Bases: ABC

Abstract base class for termination criteria.

Parameters:: parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.

abstract init()[source]

Initialize the associated state.

Return type:: NamedTuple
Returns:: The initial state of the Criterion.

abstract met(criterion_state)[source]

Parameters:: criterion_state (NamedTuple) – State of criterion to base decision on.
Return type:: bool
Returns:: True if the Criterion is fulfilled, False if not.

abstract update(criterion_state, state, population, loss)[source]

Function to update and return the Criterion

Parameters:

criterion_state (NamedTuple) – Current state of the Criterion.
state (AlgorithmState) – Current state of the evolution.
population (numpy.typing.ArrayLike) – Current generation of individuals.
loss (numpy.typing.ArrayLike) – Loss of each of the current individuals.

Return type:

NamedTuple

Returns:

The updated state of the Criterion.

class clinamen2.cmaes.termination_criterion.StaleLossCriterion(parameters, threshold, generations)[source]

Bases: Criterion

Class that implements a termination criterion of the CMA-ES.

Takes the loss trajectory into account. If the loss is stale for a given number of generations, the criterion is met.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
threshold (float) – Difference up to which two different loss values are considered equal.
generations (int) – Number of generations for which the loss has to be stale for the criterion to be met.

init()[source]

Initialize the associated CriterionState.

Use base CriterionState and set counter to zero.

Return type:: StaleLossState

met(criterion_state)[source]

Parameters:: criterion_state (StaleLossState) – State of criterion to base decision on.
Return type:: bool
Returns:: True if the Criterion is fulfilled, False if not.

update(criterion_state, state, population, loss)[source]

Function to update and return the Criterion

Parameters:

criterion_state (StaleLossState) – Current state of the Criterion.
state (AlgorithmState) – Current state of the evolution.
population (numpy.typing.ArrayLike) – Current generation of individuals.
loss (numpy.typing.ArrayLike) – Loss of each of the current individuals.

Return type:

StaleLossState

Returns:

The updated state of the Criterion.

class clinamen2.cmaes.termination_criterion.StaleLossState(counter=0, compare_to=None)[source]

Bases: NamedTuple

NamedTuple to keep track of the state of a criterion.

Parameters:

counter (int) – A variable to keep track of relevant steps.
compare_to (float) – A reference value to compare to.

compare_to: float: Alias for field number 1

counter: int: Alias for field number 0

class clinamen2.cmaes.termination_criterion.StaleStdCriterion(parameters, threshold, generations)[source]

Bases: Criterion

Class that implements a termination criterion of the CMA-ES.

Takes the standard deviation within generations into account. If the std is below a threshold for a given number of generations, the criterion is met.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
threshold (float) – Threshold value for std to fall below.
generations (int) – Number of generations for which std needs to remain below threshold for the criterion to be met.

init()[source]

Initialize the associated CriterionState.

Use base CriterionState and set counter to zero.

Return type:: StaleLossState

met(criterion_state)[source]

Parameters:: criterion_state (StaleLossState) – State of criterion to base decision on.
Return type:: bool
Returns:: True if the Criterion is fulfilled, False if not.

update(criterion_state, state, population, loss)[source]

Function to update and return the Criterion

Parameters:

criterion_state (StaleLossState) – Current state of the Criterion.
state (AlgorithmState) – Current state of the evolution.
population (numpy.typing.ArrayLike) – Current generation of individuals.
loss (numpy.typing.ArrayLike) – Loss of each of the current individuals.

Return type:

StaleLossState

Returns:

The updated state of the Criterion.

clinamen2.cmaes.termination_criterion.StaleStdState: alias of StaleLossState

class clinamen2.cmaes.termination_criterion.StaleStepCriterion(parameters, threshold, generations)[source]

Bases: Criterion

Class that implements a termination criterion of the CMA-ES.

Takes the step size trajectory into account. If the step size is stale for a given number of generations, the criterion is met.

Parameters:

parameters (AlgorithmParameters) – Initial, immutable parameters of the CMA-ES run.
threshold (float) – Difference up to which two different step sizes are considered equal.
generations (int) – Number of generations for which the step size needs to be stale for the criterion to be met.

init()[source]

Initialize the associated CriterionState.

Use base CriterionState and set counter to zero.

Return type:: StaleLossState

met(criterion_state)[source]

Parameters:: criterion_state (StaleLossState) – State of criterion to base decision on.
Return type:: bool
Returns:: True if the Criterion is fulfilled, False if not.

update(criterion_state, state, population, loss)[source]

Function to update and return the Criterion

Parameters:

criterion_state (StaleLossState) – Current state of the Criterion.
state (AlgorithmState) – Current state of the evolution.
population (numpy.typing.ArrayLike) – Current generation of individuals.
loss (numpy.typing.ArrayLike) – Loss of each of the current individuals.

Return type:

StaleLossState

Returns:

The updated state of the Criterion.

clinamen2.cmaes.termination_criterion.StaleStepState: alias of StaleLossState

Module contents

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.