.. _SpaceDistribution1:


Space distribution
------------------


Probability distribution of design and environment parameters defined by distribution functions and constraints. The definition of the parameter distribution can have several effects:  

* In a call to the method ``get_statistics`` of the driver interface     the value of interest is averaged over samples drawn from the     space distribution.  

* In a call to the method ``run_mcmc`` of the driver interface     the space distribution acts as a prior distribution.  

* In a call to the method ``get_sobol_indices`` of the driver interface     the space distribution acts as a weighting factor for determining     expectation values.  

* In an :ref:`ActiveLearning` driver, one can access the value of the     log-probability density (up to an additive constant) by the name     ``'log_prob'`` in any expression, e.g. in     :ref:`ExpressionVariable`,     :ref:`LinearCombinationVariable`.

.. _BayesianOptimization.parameter_distribution.include_study_constraints:


include_study_constraints (bool)
""""""""""""""""""""""""""""""""
   If true, the constraints defined when creating the study are included in the distribution. 

   Default: ``false``

.. _BayesianOptimization.parameter_distribution.distributions:


distributions (cell{struct})
""""""""""""""""""""""""""""
   List of distributions for all or a subset of design and environment parameters. If not specified, the distributions are uniform over the specified domains. 

   Default: ``{}``

   .. admonition:: Example

      A multivariate normal distribution over two parameters ``'x1'``, ``'x2'`` and a uniform distribution over a third parameter ``'x3'``.

      .. code-block:: matlab

         {struct('type', "mvn", 'parameters', {"x1","x2"}, 'mean', {0.0,0.0}, 'covariance', {{1.0,0.4},...
          {0.4,2.0}}),...
          struct('type', "uniform", 'parameter', "x2", 'domain', {-2.0,2.0})}

   Each element of the list must be a struct. The struct entry ``type`` specifies the type of the element. The remaining entries  specify its properties. In the following, all possible  list element types are described:

      **Uniform distribution** (type ``"uniform"``): Uniform distribution in a specific domain.      
      
      See :ref:`uniform configuration <Uniform2>` for details.

      **Normal distribution** (type ``"normal"``): Normal distribution of specified mean and standard deviation.      
      
      See :ref:`normal configuration <Normal2>` for details.

      **Gamma distribution** (type ``"gamma"``): Gamma distribution defined by rate and shape parameter.      
      
      See :ref:`gamma configuration <Gamma2>` for details.

      **Distribution over discrete values** (type ``"discrete"``): Distribution over discrete values of a discrete or categorial parameter.      
      
      See :ref:`discrete configuration <DiscreteProbabilities2>` for details.

      **Multivariate normal distribution** (type ``"mvn"``): Multivariate normal defined my mean vector and covariance matrix.      
      
      See :ref:`mvn configuration <MultivariateNormal2>` for details.

.. toctree::
   :maxdepth: 100 
   :hidden:
   
   Uniform2
   Normal2
   Gamma2
   DiscreteProbabilities2
   MultivariateNormal2



.. _BayesianOptimization.parameter_distribution.constraints:


constraints (cell{struct})
""""""""""""""""""""""""""
   List of constraints on parameters. 

   Default: ``{}``

   .. admonition:: Example

      Constrain probability distribution to values :math:`\sqrt{x_1^2 + x_2^2} \leq 3`.

      .. code-block:: matlab

         {struct('name', "x1_constraint", 'expression', "sqrt(x1^2 + x2^2) <= 3")}

   Each element of the list must be a struct. In the following, the list elements are described:

   Inequality constraint on design end environment parameters.   
   
   See :ref:`constraint configuration <SpaceConstraint1>` for details.

.. toctree::
   :maxdepth: 100 
   :hidden:
   
   SpaceConstraint1