Developer Reference for Intel® oneAPI Math Kernel Library - C

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.