pyuncertainnumber.opt.ga
========================

.. py:module:: pyuncertainnumber.opt.ga


Classes
-------

.. autoapisummary::

   pyuncertainnumber.opt.ga.GA


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

.. py:class:: GA(f: callable, task: str, dimension: int, varbound)

   Genetic Algorithm class

   :param f: the target function to be optimised, should have a single argument
   :type f: callable
   :param task: either 'minimisation' or 'maximisation'
   :type task: str
   :param dimension: the dimension of the design space, i.e. the number of parameters
   :type dimension: int
   :param varbound: the bounds for the design space, e.g. 'np.array([[-2, 10]])'
   :type varbound: np.ndarry

   .. rubric:: Example

   >>> import numpy as np
   >>> from pyuncertainnumber.opt.ga import GA
   >>> def black_box_function(x):
   ...     return np.exp(-(x - 2)**2) + np.exp(-(x - 6)**2 / 10) + 1 / (x**2 + 1)
   >>> ga = GA(f=black_box_function, task='maximisation', dimension=1, varbound=np.array([[-2, 10]]))
   >>> ga.run()  # the progress bar will be shown as side effect
   >>> print(ga.optimal)  # get the optimal parameters and target value

   .. admonition:: Implementation

       The range of the design space is defined by `varbound`, which is a 2D numpy array with shape (n, 2), where n is the number of parameters.
       This is a different signature compared to the Bayesian Optimisation class, which uses a dictionary for bounds.
       For consistency, it is recommended to use the class `EpistemicDomain.to_varbound()` to automatically take care of the format of the bounds.

       example:
           >>> from pyuncertainnumber import pba, EpistemicDomain
           >>> ed = EpistemicDomain(pba.I(-5, 5), pba.I(-5, 5))
           >>> ga = GA(
           ...     f=foo,
           ...     task='maximisation',
           ...     dimension=2,
           ...     varbound=ed.to_GA_varBounds()  # the trick
           ... )

   .. seealso::

       :class:`pyuncertainnumber.propagation.epistemic_uncertainty.helper.EpistemicDomain`: the utility tool for setting up the epistemic domain.


   .. py:attribute:: f


   .. py:attribute:: task


   .. py:attribute:: dimension


   .. py:attribute:: varbound


   .. py:method:: setup()

      Objective direction setup



   .. py:method:: get_results()

      display the results of the optimization



   .. py:method:: run(algorithm_param=None, **kwargs)

      run the genetic algorithm

      :param algorithm_param: the parameters for the genetic algorithm; if None, the default parameters will be used.
      :type algorithm_param: dict
      :param convergence_curve: whether to return the convergence curve, default is True
      :type convergence_curve: Boolean
      :param progress_bar: whether to show the progress bar, default is True
      :type progress_bar: Boolean



   .. py:property:: optimal


   .. py:property:: optimal_xc

      return the design variable that gives the optimal function value


   .. py:property:: optimal_target

      return the optimal target value