cotengra.experimental.hyper_de
==============================

.. py:module:: cotengra.experimental.hyper_de

.. autoapi-nested-parse::

   Hyper optimization using a pure Python differential evolution strategy.



Classes
-------

.. autoapisummary::

   cotengra.experimental.hyper_de.HyperDESampler
   cotengra.experimental.hyper_de.DEOptLib


Module Contents
---------------

.. py:class:: HyperDESampler(space, seed=None, population_size='auto', mutation=0.8, crossover=0.7, mutation_decay=1.0, mutation_min=0.1, mutation_max=1.5, exponential_param_power=None)

   A lightweight differential evolution optimizer operating in raw
   ``[-1, 1]`` parameter space.

   Each generation maintains a population of candidate vectors. New trial
   vectors are created using ``DE/rand/1/bin`` mutation and binomial
   crossover, then kept only if they improve on their parent.

   :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: The population size. When ``"auto"`` it is chosen based on the mapped
                           parameter dimension.
   :type population_size: int or "auto", optional
   :param mutation: The differential weight (F) applied to the difference vector.
   :type mutation: float, optional
   :param crossover: The crossover probability (CR) for binomial crossover.
   :type crossover: float, optional
   :param mutation_decay: Multiplicative decay applied to ``mutation`` after each completed
                          generation.
   :type mutation_decay: float, optional
   :param mutation_min: Lower bound for ``mutation``.
   :type mutation_min: float, optional
   :param mutation_max: Upper bound for ``mutation``.
   :type mutation_max: 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


   .. py:attribute:: ndim


   .. py:attribute:: population_size
      :value: 'auto'



   .. py:attribute:: mutation
      :value: 0.8



   .. py:attribute:: crossover
      :value: 0.7



   .. py:attribute:: mutation_decay
      :value: 1.0



   .. py:attribute:: mutation_min
      :value: 0.1



   .. py:attribute:: mutation_max
      :value: 1.5



   .. py:attribute:: _population


   .. py:attribute:: _scores


   .. py:attribute:: _trial_counter
      :value: 0



   .. py:attribute:: _target_index
      :value: 0



   .. py:attribute:: _generation
      :value: None



   .. py:attribute:: _trial_map


   .. py:method:: _mutate(target_idx)

      Create a trial vector via DE/rand/1/bin.



   .. py:method:: _sample_generation()

      Prepare trial vectors for all population members.



   .. py:method:: _extend_generation(target_idx=None)

      Append one more trial to the current generation.



   .. py:method:: ask()

      Return the next candidate from the current generation.

      If all prepared candidates have been issued, grow the generation
      by one more sample.



   .. py:method:: tell(trial_number, score)

      Record a completed trial and perform selection if the
      generation is complete.

      For each trial vector, if it scores better than (or equal to) its
      target parent, it replaces the parent in the population.



.. py:class:: DEOptLib

   Bases: :py:obj:`cotengra.experimental.hyper.HyperOptLib`


   Hyper-optimization using differential evolution.


   .. py:method:: setup(methods, space, optimizer=None, population_size='auto', mutation=0.8, crossover=0.7, mutation_decay=1.0, mutation_min=0.1, mutation_max=1.5, method_exploration=1.0, method_temperature=1.0, exponential_param_power=None, seed=None, **kwargs)

      Initialize DE 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. Used to size the initial population
                        large enough for parallel pre-dispatch.
      :type optimizer: HyperOptimizer, optional
      :param population_size: The population size for each method-specific DE sampler.
      :type population_size: int or "auto", optional
      :param mutation: Differential weight (F).
      :type mutation: float, optional
      :param crossover: Crossover probability (CR).
      :type crossover: float, optional
      :param mutation_decay: Parameters controlling mutation scale over generations.
      :type mutation_decay: float, optional
      :param mutation_min: Parameters controlling mutation scale over generations.
      :type mutation_min: float, optional
      :param mutation_max: Parameters controlling mutation scale over generations.
      :type mutation_max: 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 DE.