cotengra.hyperoptimizers._param_mapping
=======================================

.. py:module:: cotengra.hyperoptimizers._param_mapping

.. autoapi-nested-parse::

   Shared parameter mapping utilities for hyper-optimization backends.

   Provides classes for mapping heterogeneous parameter types (float, int,
   string, bool) to and from a uniform [-1, 1] optimization space, plus an
   LCB-based method selector.



Classes
-------

.. autoapisummary::

   cotengra.hyperoptimizers._param_mapping.LCBOptimizer
   cotengra.hyperoptimizers._param_mapping.Param
   cotengra.hyperoptimizers._param_mapping.ParamFloat
   cotengra.hyperoptimizers._param_mapping.ParamFloatExp
   cotengra.hyperoptimizers._param_mapping.ParamInt
   cotengra.hyperoptimizers._param_mapping.ParamString
   cotengra.hyperoptimizers._param_mapping.ParamBool


Functions
---------

.. autoapisummary::

   cotengra.hyperoptimizers._param_mapping.build_params
   cotengra.hyperoptimizers._param_mapping.convert_raw
   cotengra.hyperoptimizers._param_mapping.num_params
   cotengra.hyperoptimizers._param_mapping.generate_lhs_points


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

.. py:class:: LCBOptimizer(options, exploration=1.0, temperature=1.0, seed=None)

   Lower Confidence Bound Optimizer.

   This optimizer selects the option with the lowest lower confidence bound.


   .. py:attribute:: options


   .. py:attribute:: index


   .. py:attribute:: nopt


   .. py:attribute:: counts


   .. py:attribute:: values


   .. py:attribute:: total
      :value: 0



   .. py:attribute:: exploration
      :value: 1.0



   .. py:attribute:: temperature
      :value: 1.0



   .. py:attribute:: rng


   .. py:method:: ask()

      Suggest an option based on the lower confidence bound.



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


.. py:class:: Param(name)

   A basic parameter class for mapping various types of parameters to
   and from uniform optimization space of [-1, 1].


   .. py:attribute:: name


   .. py:attribute:: size
      :value: 1



   .. py:method:: get_raw_bounds()
      :abstractmethod:



   .. py:method:: convert_raw(vi)
      :abstractmethod:



.. py:class:: ParamFloat(min, max, **kwargs)

   Bases: :py:obj:`Param`


   A basic parameter class for mapping various types of parameters to
   and from uniform optimization space of [-1, 1].


   .. py:attribute:: min


   .. py:attribute:: max


   .. py:method:: convert_raw(x)


.. py:class:: ParamFloatExp(min, max, power=0.5, **kwargs)

   Bases: :py:obj:`ParamFloat`


   An exponentially distributed (i.e. uniform in logspace) parameter.


   .. py:attribute:: power
      :value: 0.5



   .. py:method:: convert_raw(x)


.. py:class:: ParamInt(min, max, **kwargs)

   Bases: :py:obj:`Param`


   A basic parameter class for mapping various types of parameters to
   and from uniform optimization space of [-1, 1].


   .. py:attribute:: min


   .. py:attribute:: max


   .. py:method:: convert_raw(x)


.. py:class:: ParamString(options, name)

   Bases: :py:obj:`Param`


   A basic parameter class for mapping various types of parameters to
   and from uniform optimization space of [-1, 1].


   .. py:attribute:: options


   .. py:attribute:: size


   .. py:attribute:: name


   .. py:method:: convert_raw(x)


.. py:class:: ParamBool(name)

   Bases: :py:obj:`Param`


   A basic parameter class for mapping various types of parameters to
   and from uniform optimization space of [-1, 1].


   .. py:attribute:: size
      :value: 2



   .. py:attribute:: name


   .. py:method:: convert_raw(x)


.. py:function:: build_params(space, exponential_param_power=None)

   Build a list of ``Param`` objects from a search space dict.

   :param space: The search space for a single method.
   :type space: dict[str, dict]
   :param exponential_param_power: Power parameter for ``ParamFloatExp``.
   :type exponential_param_power: float, optional

   :returns: **params**
   :rtype: list[Param]


.. py:function:: convert_raw(params, x)

   Convert a raw vector from [-1, 1] space into named parameters.

   :param params: The parameter definitions.
   :type params: list[Param]
   :param x: The raw vector.
   :type x: array_like

   :returns: **named_params**
   :rtype: dict[str, any]


.. py:function:: num_params(params)

   Return the total number of raw dimensions for a list of params.


.. py:function:: generate_lhs_points(ndim, n, rng)

   Generate ``n`` Latin Hypercube Sampled points in ``[-1, 1]^ndim``.

   Each dimension is divided into ``n`` equal strata and exactly one
   sample is drawn uniformly within each stratum. The stratum-to-sample
   assignment is independently permuted per dimension, ensuring good
   marginal coverage with no external dependencies.

   :param ndim: Number of raw dimensions.
   :type ndim: int
   :param n: Number of points to generate.
   :type n: int
   :param rng: Random number generator instance.
   :type rng: random.Random

   :returns: **points** -- ``n`` points, each a list of ``ndim`` floats in ``[-1, 1]``.
   :rtype: list[list[float]]