cotengra.hyperoptimizers.hyper_es ================================= .. py:module:: cotengra.hyperoptimizers.hyper_es .. autoapi-nested-parse:: Hyper optimization using a steady-state diagonal evolutionary strategy. Attributes ---------- .. autoapisummary:: cotengra.hyperoptimizers.hyper_es._CHI1 Classes ------- .. autoapisummary:: cotengra.hyperoptimizers.hyper_es.SteadyStateES cotengra.hyperoptimizers.hyper_es.ESOptLib Functions --------- .. autoapisummary:: cotengra.hyperoptimizers.hyper_es._reflect Module Contents --------------- .. py:data:: _CHI1 .. py:function:: _reflect(x) Reflect a scalar into [-1, 1]. .. py:class:: SteadyStateES(space, seed=None, population_size='auto', sigma=0.5, sigma_min=0.01, sigma_max=1.0, c_sigma='auto', d_sigma='auto', elite_ratio=0.5, use_mirror=True, inject_best_every='auto', restart_patience='auto', explore_prob=0.05, mean_lr=0.5, exponential_param_power=None) A steady-state diagonal evolutionary strategy (SSES) operating in raw ``[-1, 1]`` parameter space. Unlike a generational ES, this sampler has no synchronization barrier. Every ``ask`` draws from the current distribution immediately, and every ``tell`` updates the distribution state from a sliding window of recent results. Trials can be in-flight in any number and can complete in any order. Step sizes are adapted per dimension using a simplified cumulative step-size adaptation (CSA) rule, giving the optimizer the character of a separable (diagonal) CMA-ES without any matrix operations. :param space: The search space for a single contraction method. :type space: dict[str, dict] :param seed: Random seed. :type seed: None or int, optional :param population_size: Size of the sliding archive window. When ``"auto"`` it is chosen as ``max(8, 4 * ndim)``. :type population_size: int or "auto", optional :param sigma: Initial per-dimension step size in raw ``[-1, 1]`` space. :type sigma: float, optional :param sigma_min: Lower bound for per-dimension step sizes. :type sigma_min: float, optional :param sigma_max: Upper bound for per-dimension step sizes (also the restart value). :type sigma_max: float, optional :param c_sigma: Learning rate for the evolution path. When ``"auto"`` it is set to ``1 / sqrt(ndim)`` (clamped to ``[0.05, 1.0]``). :type c_sigma: float or "auto", optional :param d_sigma: Damping factor for step-size updates. When ``"auto"`` it is set to ``1 + sqrt(ndim)``. :type d_sigma: float or "auto", optional :param elite_ratio: Fraction of the archive used as elites for weighted recombination. :type elite_ratio: float, optional :param use_mirror: If ``True``, every fresh perturbation is paired with its antipodal mirror, halving gradient variance. :type use_mirror: bool, optional :param inject_best_every: Inject the best-so-far point every this many asks. When ``"auto"`` it equals ``population_size``. :type inject_best_every: int or "auto", optional :param restart_patience: Number of tells without improvement before resetting step sizes and re-centering on the best-so-far point. When ``"auto"`` it equals ``5 * population_size``. :type restart_patience: int or "auto", optional :param explore_prob: Probability of issuing a uniform random point instead of the ES-directed point. Maintains global diversity throughout the search and helps escape local minima. Random points still feed into the archive normally. :type explore_prob: float, optional :param mean_lr: Learning rate for the mean update in ``(0, 1]``. Each tell blends the current mean toward the elite weighted mean by this factor: ``mean = (1 - mean_lr) * mean + mean_lr * elite_mean``. Values below ``1.0`` smooth out noise-driven mean drift. Default is ``1.0`` (full update, original behaviour). :type mean_lr: float, optional :param exponential_param_power: Passed through to the shared parameter mapping for ``FLOAT_EXP`` parameters. :type exponential_param_power: float, optional .. py:attribute:: rng .. py:attribute:: params :value: [] .. py:attribute:: ndim .. py:attribute:: population_size :value: 'auto' .. py:attribute:: sigma0 :value: 0.5 .. py:attribute:: sigma_min :value: 0.01 .. py:attribute:: sigma_max :value: 1.0 .. py:attribute:: c_sigma :value: 'auto' .. py:attribute:: d_sigma :value: 'auto' .. py:attribute:: elite_ratio :value: 0.5 .. py:attribute:: use_mirror :value: True .. py:attribute:: explore_prob :value: 0.05 .. py:attribute:: mean_lr :value: 0.5 .. py:attribute:: inject_best_every :value: 'auto' .. py:attribute:: restart_patience :value: 'auto' .. py:attribute:: _weights .. py:attribute:: _mu .. py:attribute:: _mu_eff .. py:method:: _init_state() Initialize or reset the mutable optimizer state. .. py:method:: ask() Return the next candidate point. Draws from the current distribution, optionally using mirrored sampling or best-so-far injection. No synchronization with outstanding trials is required. .. py:method:: tell(trial_number, score) Record a completed trial and update the distribution. Updates the sliding archive, recomputes the weighted mean from elites, adapts per-dimension step sizes via evolution paths, and checks for stalls. .. py:method:: _restart() Reset step sizes and re-center. Alternates between re-centering on the best-so-far point (exploitation restart) and a uniformly random point (exploration restart) to avoid repeated restarts converging to the same local minimum. .. py:class:: ESOptLib Bases: :py:obj:`cotengra.hyperoptimizers.hyper.HyperOptLib` Hyper-optimization using a steady-state diagonal ES. .. py:method:: setup(methods, space, optimizer=None, population_size='auto', sigma=0.5, sigma_min=0.01, sigma_max=1.0, c_sigma='auto', d_sigma='auto', elite_ratio=0.5, use_mirror=True, inject_best_every='auto', restart_patience='auto', explore_prob=0.05, mean_lr=1.0, method_exploration=1.0, method_temperature=1.0, exponential_param_power=None, seed=None, **kwargs) Initialize ES optimizers for each contraction method. :param methods: The contraction methods to optimize over. :type methods: list[str] :param space: The per-method hyperparameter search space. :type space: dict[str, dict[str, dict]] :param optimizer: The parent optimizer. :type optimizer: HyperOptimizer, optional :param population_size: Archive window size for each method-specific ES sampler. :type population_size: int or "auto", optional :param sigma: Initial per-dimension step size. :type sigma: float, optional :param sigma_min: Bounds for per-dimension step sizes. :type sigma_min: float, optional :param sigma_max: Bounds for per-dimension step sizes. :type sigma_max: float, optional :param c_sigma: Evolution path learning rate. :type c_sigma: float or "auto", optional :param d_sigma: Step-size damping factor. :type d_sigma: float or "auto", optional :param elite_ratio: Fraction of the archive used as elites. :type elite_ratio: float, optional :param use_mirror: Enable mirrored sampling. :type use_mirror: bool, optional :param inject_best_every: Best-injection frequency. :type inject_best_every: int or "auto", optional :param restart_patience: Tells without improvement before restart. :type restart_patience: int or "auto", optional :param explore_prob: Probability of issuing a uniform random point on each ask. :type explore_prob: float, optional :param mean_lr: Learning rate for the mean update in ``(0, 1]``. :type mean_lr: float, optional :param method_exploration: Exploration strength for the LCB-based method chooser. :type method_exploration: float, optional :param method_temperature: Noise temperature for the LCB-based method chooser. :type method_temperature: float, optional :param exponential_param_power: Passed to the shared parameter mapping for ``FLOAT_EXP``. :type exponential_param_power: float, optional :param seed: Random seed. :type seed: None or int, optional .. py:method:: get_setting() Choose a contraction method, then request its next setting. .. py:method:: report_result(setting, trial, score) Report a completed trial back to the method chooser and ES.