Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

vslNewStreamEx

Creates and initializes a random stream for generators with multiple initial conditions.

Syntax

status = vslNewStreamEx( &stream, brng, n, params );

Include Files

  • mkl.h

Input Parameters

Name

Type

Description

brng

const MKL_INT

Index of the basic generator to initialize the stream. See Table "Values of brng parameter" for specific value.

n

const MKL_INT

Number of initial conditions contained in params

params

const unsigned int

Array of initial conditions necessary for the basic generator brng to initialize the stream. In the case of a quasi-random number generator only the first element in params parameter is used to set the dimension. If the dimension is greater than the dimension that brng can support or is less than 1, then the dimension is assumed to be equal to 1.

Output Parameters

Name

Type

Description

stream

VSLStreamStatePtr*

Stream state descriptor

Description

The vslNewStreamEx function provides an advanced tool to set the initial conditions for a basic generator if its input arguments imply several initialization parameters. Initial values are used to select a particular sequence generated by the basic generator brng. Whenever possible, use vslNewStream, which is analogous to vslNewStreamEx except that it takes only one 32-bit initial condition. In particular, vslNewStreamEx may be used to initialize the state table in Generalized Feedback Shift Register Generators (GFSRs). A more detailed description of this issue can be found in VS Notes.

This function is also used to pass user-defined initialization parameters of quasi-random number generators into the library. See VS Notes for the format for their passing and registration in VS.

NOTE:

This function is not applicable for abstract basic random number generators. Please use vsliNewAbstractStream, vslsNewAbstractStream or vsldNewAbstractStream to utilize integer, single-precision or double-precision external random data respectively.

Product and Performance Information

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

Notice revision #20201201

Return Values

VSL_ERROR_OK, VSL_STATUS_OK

Indicates no error, execution is successful.

VSL_RNG_ERROR_INVALID_BRNG_INDEX

BRNG index is invalid.

VSL_ERROR_MEM_FAILURE

System cannot allocate memory for stream.

VSL_RNG_ERROR_NONDETERMINISTIC_NOT_SUPPORTED

Non-deterministic random number generator is not supported.

VSL_RNG_ERROR_ARS5_NOT_SUPPORTED

ARS-5 random number generator is not supported on the CPU running the application.