.. _AcquisitionFunction:


Acquisition function
--------------------


The acquisition function defines the sampling strategy. That is, new samples for the evaluation of the black-box function are  generated by maximizing the acquisition function. The acquisition strategy  itself is defined in the ``objective``. This module allows to configure  additional properties of the acquisition function.

.. _ActiveLearning.acquisition_function.parameter_uncertainties:


parameter_uncertainties (list[dict])
""""""""""""""""""""""""""""""""""""
   Sometimes, one is interested in minima of the  objective function that are preferably insensitive to variations of certain parameters (e.g. if the parameters have large fabrication variances). In this case, one can specify the uncertainties of those parameters, i.e. their standard deviations. When computing the  acquisition function, the regression model of the objective is  averaged over the uncertainty intervals such that very narrow local minima are averaged out whereas broad minima are not affected. 

   Default: ``[]``

   .. admonition:: Example

      The parameters param1 and param3 have a standard  deviation of 0.1 and 0.2, respectively.

      .. code-block:: python

         [{'name': 'param1', 'uncertainty': 0.1},
          {'name': 'param3', 'uncertainty': 0.2}]


   .. note:: Note that the averaging results in additional numerical effort that grows exponentially with the number of uncertain  parameters.

   Each element of the list must be a dict with the following entries:

      .. _ActiveLearning.acquisition_function.name:

      name (str): Name of the parameter. 

         Default: ``'x1'``

      .. _ActiveLearning.acquisition_function.uncertainty:

      uncertainty (float): Standard deviation of the uncertainty. 

         Default: ``0.0``



.. _ActiveLearning.acquisition_function.num_samples:


num_samples (int)
"""""""""""""""""
   If the acquisition function has to be determined by Monte-Carlo integration, this specifies the number of samples to be used. 

   Default: ``10000``

.. _ActiveLearning.acquisition_function.do_MC_integration:


do_MC_integration (bool)
""""""""""""""""""""""""
   The determination of the value of the acquisition function (e.g. expected improvement - EI, probability of improvement - PoI) can be performed by a Monte-Carlo integration based on samples drawn from the posterior distribution of the objectives. If ``do_MC_integration`` if true, this approach is applied for all distributions that cannot be treated analytically (e.g. the output of expression variables). Alternatively to a Monte-Carlo integration, the acquisition functions can be determined analytically based on the empirical mean and variance of the distribution. This approach is more robust if the number of available samples is small, which can be the case when using ensemble surrogates (ensemble neural networks). 

   Default: The parameter is set to true if the number of available samples of all objectives is at least 10000.

.. _ActiveLearning.acquisition_function.smooth_range:


smooth_range (float)
""""""""""""""""""""
   Smooth range of step functions used in Monte Carlo integration used e.g. to estimate the expectation values of a variable :math:`z` to be larger than a threshold :math:`z_0`, i.e.  :math:`\mathbb{E}[ z > z_0 ]`. In order to get a value that has a proper derivative, the step  used in the MC integration must be smooth w.r.t. the sampled value of :math:`z`. The smooth range is multiplied by the bandwidth of the Monte Carlo samples according to Scotts rule of thumb. 

   Default: ``0.2``