.. _oneapi-mkl-rng-gaussian_mv:

oneapi::mkl::rng::gaussian_mv
=============================


Generates random numbers from multivariate normal distribution.


.. contents::
    :local:
    :depth: 1

Description
***********

The class object is used in the ``oneapi::mkl::rng::generate`` function to provide random numbers with ``d``-variate normal (Gaussian) distribution with mean (``a``) and variance-covariance matrix ``C``, where ``a`` ∈ ``R``\ :sup:`d` ; ``C`` is dxd symmetric positive-definite matrix.


The probability density function is given by:

.. math::

   f_{a, C} (x) =
   \frac{1}{\sqrt{\mathrm{det}(2\pi C)}}
   \exp (- \frac{1}{2} (x-a)^T C^{-1} (x-a))


where ``x∈Rd`` .


Matrix ``C`` can be represented as ``C = TTT``, where ``T`` is a lower triangular matrix - Cholesky factor of ``C``.


API
***


Syntax
------

.. code-block:: cpp


   template<typename RealType = float, layout Layout = layout::packed, typename Method =
   gaussian_mv_method::by_default>
   class gaussian_mv {
   public:
   using method_type = Method;
   using result_type = RealType;
   static constexpr layout layout_type = Layout;
   explicit gaussian_mv(std::uint32_t dimen, std::vector<RealType> mean,
   std::vector<RealType> matrix);
   explicit gaussian_mv(const param_type& pt);
   std::uint32_t dimen() const;
   std::vector<RealType> mean() const;
   std::vector<RealType> matrix() const;
   param_type param() const;
   void param(const param_type& pt);
   };



Devices supported: Host, CPU, and GPU.


Include Files
-------------

- ``oneapi/mkl/rng.hpp``


Template Parameters
-------------------

.. list-table::
   :header-rows: 1

   * - Name
     - Description
   * - ``typename RealType = float``
     - Type of the produced values. The specific values are as follows:

       ``float``

       ``double``

   * - ``layout Layout = layout::packed``
     - Type of the matrix storage. The specific values are as follows:

       ``layout::packed``

       ``layout::full``

       ``layout::diagonal``

       See brief descriptions of the methods in :ref:`distributions-template-parameter-method`.
   * - ``typename Method = oneapi::mkl::rng::gaussian_mv_method::by_default``
     - Generation method. The specific values are as follows:

       ``oneapi::mkl::rng::gaussian_mv_method::box_muller``

       ``oneapi::mkl::rng::gaussian_mv_method::box_muller2``

       ``oneapi::mkl::rng::gaussian_mv_method::icdf``

       See brief descriptions of the methods in :ref:`distributions-template-parameter-method`.


Input Parameters
----------------

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - dimen
     - ``std::uint32_t``
     -  Dimension of output random vectors
   * - mean
     - ``std::vector< RealType> (float, double``
     -  Mean vector a of dimension ``d``.
   * - matrix
     - ``std::vector< RealType> (float, double``
     - Variance-covariance matrix ``C``.