CMA-ES (Covariance Matrix Adaptation Evolution Strategy)

import cma

# Main optimization functions
from cma import fmin2, fmin, fmin_con2, fmin_con

# Core classes
from cma import CMAEvolutionStrategy, CMA  # CMA is an alias
from cma import CMAOptions

# Pure Python implementation
from cma import purecma

# Fitness functions and transformations  
from cma import ff  # fitness functions
from cma.fitness_transformations import GlueArguments, ScaleCoordinates

# Boundary and constraint handlers
from cma.boundary_handler import BoundPenalty, BoundTransform, BoundNone, BoundDomainTransform
from cma.constraints_handler import ConstrainedFitnessAL, AugmentedLagrangian

# Logging and analysis
from cma import CMADataLogger, disp, plot, plot_zip

# Optimization tools
from cma.optimization_tools import NoiseHandler

import cma

# Simple function minimization
def objective(x):
    return sum(x**2)

# Method 1: Using fmin2 (recommended)
x_best, es = cma.fmin2(objective, x0=[1, 2, 3], sigma0=0.5)
print(f"Best solution: {x_best}")
print(f"Function value: {es.result.fbest}")

# Method 2: Using the ask-and-tell interface
es = cma.CMAEvolutionStrategy([1, 2, 3], 0.5)
while not es.stop():
    solutions = es.ask()
    fitness_values = [objective(x) for x in solutions]
    es.tell(solutions, fitness_values)
    es.disp()

print(f"Final result: {es.result}")

def fmin2(
    objective_function,
    x0,
    sigma0,
    options=None,
    args=(),
    gradf=None,
    restarts=0,
    restart_from_best=False,
    incpopsize=2,
    eval_initial_x=None,
    parallel_objective=None,
    noise_handler=None,
    noise_change_sigma_exponent=1,
    noise_evaluations_as_reward=False,
    bipop=False,
    callback=None
):
    """
    Main interface function to CMA-ES with optional restarts and noise handling.
    
    Parameters:
    -----------
    objective_function : callable
        Function to minimize. Takes array-like input, returns scalar.
    x0 : array-like
        Initial solution estimate, determines problem dimension.
    sigma0 : float or array-like
        Initial standard deviation for coordinate-wise search steps.
    options : dict, optional
        CMA-ES options. Use CMAOptions() to see available options.
    restarts : int, default 0
        Number of restarts to perform.
    
    Returns:
    --------
    tuple[array, CMAEvolutionStrategy]
        Best solution found and the evolution strategy instance.
    """
    pass

def fmin(
    objective_function,
    x0,
    sigma0,
    options=None,
    args=(),
    **kwargs
):
    """
    Basic functional interface to CMA-ES optimization (older interface).
    
    Parameters:
    -----------
    objective_function : callable
        Function to minimize.
    x0 : array-like
        Initial solution estimate.
    sigma0 : float
        Initial step size.
    options : dict, optional
        CMA-ES options dictionary.
    args : tuple, optional
        Additional arguments passed to objective function.
    
    Returns:
    --------
    tuple[array, float, int, int, CMAEvolutionStrategy]
        xbest, fbest, evals_best, evaluations, es
    """
    pass

def fmin_con2(
    objective_function,
    x0, 
    sigma0,
    g=None,
    h=None,
    options=None,
    **kwargs
):
    """
    Constrained optimization using augmented Lagrangian method.
    
    Parameters:
    -----------
    objective_function : callable
        Objective function to minimize.
    g : callable, optional
        Inequality constraint function g(x) <= 0.
    h : callable, optional  
        Equality constraint function h(x) = 0.
    
    Returns:
    --------
    tuple[array, CMAEvolutionStrategy]
        Best feasible solution and evolution strategy instance.
    """
    pass

def fmin_con(
    objective_function,
    x0,
    sigma0,
    g=None,
    h=None,
    options=None,
    **kwargs
):
    """
    Constrained optimization (older interface to fmin_con2).
    
    Parameters:
    -----------
    objective_function : callable
        Objective function to minimize.
    g : callable, optional
        Inequality constraint function.
    h : callable, optional
        Equality constraint function.
    
    Returns:
    --------
    tuple
        Optimization result.
    """
    pass

class CMAEvolutionStrategy:
    """
    CMA-ES stochastic optimizer class with ask-and-tell interface.
    """
    
    def __init__(self, x0, sigma0, inopts=None):
        """
        Initialize CMA-ES optimizer.
        
        Parameters:
        -----------
        x0 : array-like
            Initial solution, defines problem dimension N.
        sigma0 : float or array-like
            Initial step size(s).
        inopts : dict, optional
            Options dictionary, see CMAOptions().
        """
        pass
    
    def ask(self, number=None, xmean=None, gradf=None, args=()):
        """
        Sample new candidate solutions.
        
        Parameters:
        -----------
        number : int, optional
            Number of solutions to return (default: popsize).
            
        Returns:
        --------
        list[array]
            List of candidate solutions.
        """
        pass
    
    def tell(self, arx, fitnesses, check_points=True, copy=False):
        """
        Update strategy parameters based on function evaluations.
        
        Parameters:
        -----------
        arx : list[array]
            List of candidate solutions.
        fitnesses : array-like
            Corresponding fitness values (to be minimized).
        """
        pass
    
    def stop(self):
        """
        Check termination criteria.
        
        Returns:
        --------
        dict or False
            Termination conditions dictionary if stopped, False otherwise.
        """
        pass
    
    def optimize(self, objective_function, iterations=None, args=(), **kwargs):
        """
        Convenience method to run complete optimization.
        
        Parameters:
        -----------
        objective_function : callable
            Function to optimize.
        iterations : int, optional
            Maximum number of iterations.
            
        Returns:
        --------
        CMAEvolutionStrategy
            Self (for method chaining).
        """
        pass
    
    def disp(self, modulo=None):
        """
        Display current state and progress information.
        
        Parameters:
        -----------
        modulo : int, optional
            Display every modulo iterations (default based on verbosity).
        """
        pass
    
    def inject(self, solutions, force=False):
        """
        Inject solutions into current population.
        
        Parameters:
        -----------
        solutions : list[array]
            Solutions to inject.
        force : bool
            Force injection even if population is full.
        """
        pass
    
    @property
    def sigma(self):
        """float: Current overall step size."""
        pass
    
    @property 
    def mean(self):
        """array: Current distribution mean."""
        pass
    
    @property
    def countiter(self):
        """int: Current iteration count."""
        pass
    
    @property
    def countevals(self):
        """int: Current evaluation count.""" 
        pass
    
    @property
    def result(self):
        """
        Optimization result.
        
        Returns:
        --------
        CMAEvolutionStrategyResult
            Named tuple with fields: xbest, fbest, evals_best, evaluations, 
            iterations, xfavorite, stds, stop.
        """
        pass

class CMAOptions(dict):
    """
    Dictionary of available CMA-ES options with defaults and documentation.
    """
    
    def __init__(self, s='', **kwargs):
        """
        Create options dictionary.
        
        Parameters:
        -----------
        s : str, optional
            Search term to filter options by keyword, value, or description.
        """
        pass

class CMAEvolutionStrategyResult:
    """
    Named tuple-like result object containing optimization results.
    """
    
    @property
    def xbest(self): 
        """array: Best evaluated solution."""
        pass
    
    @property
    def fbest(self): 
        """float: Function value of best solution."""
        pass
    
    @property
    def evals_best(self): 
        """int: Evaluation count when best solution was found."""
        pass
    
    @property
    def evaluations(self): 
        """int: Total number of function evaluations."""
        pass
    
    @property
    def iterations(self): 
        """int: Number of iterations performed."""
        pass
    
    @property
    def xfavorite(self): 
        """array: Favorite solution (distribution mean)."""
        pass
    
    @property
    def stds(self): 
        """array: Standard deviations in each coordinate."""
        pass
    
    @property
    def stop(self): 
        """dict: Termination criteria that were met."""
        pass

# Quick optimization
x, es = cma.fmin2(cma.ff.sphere, [0, 0, 0], 0.5)

# Ask-and-tell interface
es = cma.CMAEvolutionStrategy([0, 0, 0], 0.5)
while not es.stop():
    X = es.ask()
    es.tell(X, [cma.ff.sphere(x) for x in X])

# Surrogate model optimization for expensive functions
x, es = cma.fmin_lq_surr2(expensive_function, x0, sigma0, 
                          options={'maxfevals': 1000})

# Pure Python implementation
import cma.purecma
x, es = cma.purecma.fmin(objective, x0, sigma0)

# Explore options
opts = cma.CMAOptions()  # All options
tol_opts = cma.CMAOptions('tol')  # Tolerance options

# Custom configuration
options = {'popsize': 50, 'maxiter': 1000, 'tolfun': 1e-12}
es = cma.CMAEvolutionStrategy(x0, sigma0, options)

# Box-constrained optimization
bounds = [[-5, -5], [5, 5]]  # lower, upper bounds
x, es = cma.fmin2(objective, x0, sigma0, 
                  options={'bounds': bounds})

# General constraints
def constraint(x):
    return [x[0]**2 + x[1]**2 - 1]  # g(x) <= 0

x, es = cma.fmin_con2(objective, x0, sigma0, g=constraint)

# Custom sampling configuration
from cma.sampler import GaussFullSampler
options = {'CMA_sampler': GaussFullSampler}
es = cma.CMAEvolutionStrategy([0, 0, 0], 0.5, options)

# Monitor step-size adaptation  
while not es.stop():
    X = es.ask()
    es.tell(X, [objective(x) for x in X])
    print(f"Step-size: {es.sigma:.6f}")

# Test functions
import cma.ff
x, es = cma.fmin2(cma.ff.rosen, 5 * [0.1], 0.5)

# Scaled coordinates
from cma.fitness_transformations import ScaleCoordinates
scaled_func = ScaleCoordinates([1, 10, 100])(cma.ff.sphere)
x, es = cma.fmin2(scaled_func, [1, 1, 1], 0.5)

# Logging during optimization
es = cma.CMAEvolutionStrategy(x0, sigma0, {'verb_disp': 1})
logger = cma.CMADataLogger()
logger.register(es)

while not es.stop():
    X = es.ask()
    es.tell(X, [objective(x) for x in X])
    logger.add(es)  # Log current state

# Plotting results
logger.plot()
cma.plot()  # Plot from default data files

# Run comprehensive tests
import cma.test
cma.test.main()

# From command line
# python -m cma.test