Developer Reference

Contents

vRngGaussianMV

Generates random numbers from multivariate normal distribution.

Syntax

status
=
vsRngGaussianMV
(
method
,
stream
,
n
,
r
,
dimen
,
mstorage
,
a
,
t
);
status
=
vdRngGaussianMV
(
method
,
stream
,
n
,
r
,
dimen
,
mstorage
,
a
,
t
);
Include Files
  • mkl.h
Input Parameters
Name
Type
Description
method
const MKL_INT
Generation method. The specific values are as follows:
VSL_RNG_METHOD_GAUSSIANMV_BOXMULLER
VSL_RNG_METHOD_GAUSSIANMV_BOXMULLER2
VSL_RNG_METHOD_GAUSSIANMV_ICDF
See brief description of the methods
BOXMULLER
,
BOXMULLER2
, and
ICDF
in Table
"Values of
<
method
>
in
method
parameter"
stream
VSLStreamStatePtr
Pointer to the stream state structure
n
const MKL_INT
Number of
d
-dimensional vectors to be generated
dimen
const MKL_INT
Dimension
d
(
d
1)
of output random vectors
mstorage
const MKL_INT
Matrix storage scheme for lower triangular matrix
T
. The routine supports three matrix storage schemes:
  • VSL_MATRIX_STORAGE_FULL
    all
    d
    x
    d
    elements of the matrix
    T
    are passed, however, only the lower triangle part is actually used in the routine.
  • VSL_MATRIX_STORAGE_PACKED
    lower triangle elements of
    T
    are packed by rows into a one-dimensional array.
  • VSL_MATRIX_STORAGE_DIAGONAL
    only diagonal elements of
    T
    are passed.
a
const float*
for
vsRngGaussianMV
const double*
for
vdRngGaussianMV
Mean vector
a
of dimension
d
t
const float*
for
vsRngGaussianMV
const double*
for
vdRngGaussianMV
Elements of the lower triangular matrix passed according to the matrix
T
storage scheme
mstorage
.
Output Parameters
Name
Type
Description
r
float*
for
vsRngGaussianMV
double*
for
vdRngGaussianMV
Array of
n
random vectors of dimension
dimen
Description
The
vRngGaussianMV
function generates random numbers with
d
-variate normal (Gaussian) distribution with mean value
a
and variance-covariance matrix
C
, where
a
R
d
;
C
is a
d
×
d
symmetric positive-definite matrix.
The probability density function is given by:
Equation
where
x
R
d
.
Matrix
C
can be represented as
C
=
TT
T
, where
T
is a lower triangular matrix - Cholesky factor of
C
.
Instead of variance-covariance matrix
C
the generation routines require Cholesky factor of
C
in input. To compute Cholesky factor of matrix
C
, the user may call
Intel® oneAPI Math Kernel Library
LAPACK routines for matrix factorization:
?potrf
or
?pptrf
for
v?RngGaussianMV
/
v?rnggaussianmv
routines (
?
means either
s
or
d
for single and double precision respectively). See Application Notes for more details.
Product and Performance Information
Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.
Notice revision #20201201
Application Notes
Since matrices are stored in Fortran by columns, while in C they are stored by rows, the usage of
Intel® oneAPI Math Kernel Library
factorization routines (assuming Fortran matrices storage) in combination with multivariate normal RNG (assuming C matrix storage) is slightly different in C and Fortran. The following tables help in using these routines in C and Fortran. For further information please refer to the appropriate VS example file.
Using Cholesky Factorization Routines in C
Matrix Storage Scheme
Variance-Covariance Matrix Argument
Factorization Routine
UPLO Parameter in Factorization Routine
Result of Factorization as Input Argument for RNG
VSL_MATRIX_STORAGE_FULL
C
in C two-dimensional array
spotrf
for
vsRngGaussianMV
dpotrf
for
vdRngGaussianMV
‘U’
Lower triangle of
T
. Upper triangle is not used.
VSL_MATRIX_STORAGE_PACKED
Lower triangle of
C
packed by columns into one-dimensional array
spptrf
for
vsRngGaussianMV
dpptrf
for
vdRngGaussianMV
‘L’
Lower triangle of
T
packed by columns into a one-dimensional array.
Return Values
VSL_ERROR_OK
,
VSL_STATUS_OK
Indicates no error, execution is successful.
VSL_ERROR_NULL_PTR
stream
is a
NULL
pointer.
VSL_RNG_ERROR_BAD_STREAM
stream
is not a valid random stream.
VSL_RNG_ERROR_BAD_UPDATE
Callback function for an abstract BRNG returns an invalid number of updated entries in a buffer, that is,
< 0
or
>
nmax
.
VSL_RNG_ERROR_NO_NUMBERS
Callback function for an abstract BRNG returns 0 as the number of updated entries in a buffer.
VSL_RNG_ERROR_QRNG_PERIOD_ELAPSED
Period of the generator has been exceeded.
VSL_RNG_ERROR_NONDETERM_NRETRIES_EXCEEDED
Number of retries to generate a random number by using non-deterministic random number generator exceeds threshold.
VSL_RNG_ERROR_ARS5_NOT_SUPPORTED
ARS-5 random number generator is not supported on the CPU running the application.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.