API Reference¶
Defines

NVPL_RAND_VERSION¶
NVPL RAND library version.
Typedefs

typedef enum nvplRandRngType nvplRandRngType_t¶
NVPL RAND generator types.

typedef enum nvplRandDistributionType nvplRandDistributionType_t¶
NVPL RAND distribution types.

typedef struct nvplRandDistributionConfig nvplRandDistributionConfig_t¶
Configuration to describe the properties of a data distribution.

typedef enum nvplRandStatus nvplRandStatus_t¶
NVPL RAND API return status.

typedef enum nvplRandOrdering nvplRandOrdering_t¶
Ordering types of results in memory for multithreaded generators.
Enums

enum nvplRandRngType¶
NVPL RAND generator types.
Values:

enumerator NVPL_RAND_RNG_PSEUDO_DEFAULT¶
Default pseudorandom generator, same as NVPL_RAND_RNG_PSEUDO_XORWOW.

enumerator NVPL_RAND_RNG_PSEUDO_XORWOW¶
XORWOW pseudorandom generator.

enumerator NVPL_RAND_RNG_PSEUDO_MRG32K3A¶
MRG32K3A pseudorandom generator.

enumerator NVPL_RAND_RNG_PSEUDO_MT19937¶
Mersenne Twister MT19937 pseudorandom generator.

enumerator NVPL_RAND_RNG_PSEUDO_PHILOX4_32_10¶
PHILOX4x3210 pseudorandom generator.

enumerator NVPL_RAND_RNG_PSEUDO_PCG¶
PCG pseudorandom generator.

enumerator NVPL_RAND_RNG_QUASI_DEFAULT¶
Default quasirandom generator, same as NVPL_RAND_RNG_QUASI_SOBOL32.

enumerator NVPL_RAND_RNG_QUASI_SOBOL32¶
SOBOL32 quasirandom generator.

enumerator NVPL_RAND_RNG_QUASI_SCRAMBLED_SOBOL32¶
Scrambled SOBOL32 quasirandom generator.

enumerator NVPL_RAND_RNG_QUASI_SOBOL64¶
SOBOL64 quasirandom generator.

enumerator NVPL_RAND_RNG_QUASI_SCRAMBLED_SOBOL64¶
Scrambled SOBOL64 quasirandom generator.

enumerator NVPL_RAND_RNG_PSEUDO_DEFAULT¶

enum nvplRandDistributionType¶
NVPL RAND distribution types.
Values:

enumerator NVPL_RAND_CONTINUOUS_DIST_UNIFORM¶
Uniform distribution with range (0,1].

enumerator NVPL_RAND_CONTINUOUS_DIST_UNIFORM_RANGE¶
Uniform distribution with custom range.

enumerator NVPL_RAND_CONTINUOUS_DIST_NORMAL¶

enumerator NVPL_RAND_CONTINUOUS_DIST_LOGNORMAL¶

enumerator NVPL_RAND_CONTINUOUS_DIST_EXPONENTIAL¶

enumerator NVPL_RAND_CONTINUOUS_DIST_GAMMA¶
Gamma distribution. Only supported by pseudorandom generators.

enumerator NVPL_RAND_CONTINUOUS_DIST_BETA¶
Beta distribution. Only supported by pseudorandom generators.

enumerator NVPL_RAND_CONTINUOUS_DIST_DIRICHLET¶
Dirichlet distribution. Only supported by pseudorandom generators.

enumerator NVPL_RAND_DISCRETE_DIST_POISSON¶

enumerator NVPL_RAND_DISCRETE_DIST_BERNOULLI¶

enumerator NVPL_RAND_DISCRETE_DIST_CATEGORICAL¶

enumerator NVPL_RAND_DISCRETE_DIST_BINOMIAL¶
Binomial distribution. Only supported by pseudorandom generators.

enumerator NVPL_RAND_DISCRETE_DIST_MULTINOMIAL¶
Multinomial distribution. Only supported by pseudorandom generators.

enumerator NVPL_RAND_CONTINUOUS_DIST_UNIFORM¶

enum nvplRandStatus¶
NVPL RAND API return status.
Values:

enumerator NVPL_RAND_STATUS_SUCCESS¶

enumerator NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED¶
Generator not initialized.

enumerator NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR¶
Generator is wrong type.

enumerator NVPL_RAND_STATUS_DATA_NULLPTR¶
Data ptr is nullptr.

enumerator NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE¶
Length requested is not a multiple of dimension, or not a multiple of two.

enumerator NVPL_RAND_STATUS_PCG_INCREMENT_NOT_ODD¶
Increment requested for PCG is not odd.

enumerator NVPL_RAND_STATUS_OUT_OF_RANGE¶
Argument out of range.

enumerator NVPL_RAND_STATUS_DISTRIBUTION_CONFIGS_ERROR¶
Distribution parameters are not acceptable.

enumerator NVPL_RAND_STATUS_DISTRIBUTION_TYPE_ERROR¶
Distribution type is not supported by the generator.

enumerator NVPL_RAND_STATUS_INTERNAL_ERROR¶
Internal library error.

enumerator NVPL_RAND_STATUS_SUCCESS¶

enum nvplRandOrdering¶
Ordering types of results in memory for multithreaded generators.
Values:

enumerator NVPL_RAND_ORDERING_PSEUDO_DEFAULT¶
Default ordering for pseudorandom results.

enumerator NVPL_RAND_ORDERING_PSEUDO_FAST¶
Nonstrict ordering with good performance but cannot recover offset.

enumerator NVPL_RAND_ORDERING_STRICT¶
Strict ordering generating same sequence as singlethread results.

enumerator NVPL_RAND_ORDERING_CURAND_LEGACY¶
Legacy sequence for pseudorandom, guaranteed to be the same with cuRAND results.

enumerator NVPL_RAND_ORDERING_QUASI_DEFAULT¶
Specific ndimensional ordering for quasirandom results.

enumerator NVPL_RAND_ORDERING_PSEUDO_DEFAULT¶
Functions

nvplRandStatus_t nvplRandCreateGenerator(nvplRandGenerator_t *gen, nvplRandRngType_t rng_type)¶
Create new random number generator of type
rng_type
and returns it in*gen
.Legal values for
rng_type
are:NVPL_RAND_RNG_PSEUDO_DEFAULT
NVPL_RAND_RNG_PSEUDO_XORWOW
NVPL_RAND_RNG_PSEUDO_MRG32K3A
NVPL_RAND_RNG_PSEUDO_MT19937
NVPL_RAND_RNG_PSEUDO_PHILOX4_32_10
NVPL_RAND_RNG_PSEUDO_PCG
NVPL_RAND_RNG_QUASI_DEFAULT
NVPL_RAND_RNG_QUASI_SOBOL32
NVPL_RAND_RNG_QUASI_SCRAMBLED_SOBOL32
NVPL_RAND_RNG_QUASI_SOBOL64
NVPL_RAND_RNG_QUASI_SCRAMBLED_SOBOL64
When
rng_type
is NVPL_RAND_RNG_PSEUDO_DEFAULT, the type chosen is NVPL_RAND_RNG_PSEUDO_XORWOW. Whenrng_type
is NVPL_RAND_RNG_QUASI_DEFAULT, the type chosen is NVPL_RAND_RNG_QUASI_SOBOL32. Parameters:
gen – Pointer to generator
rng_type – Type of generator to create
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was not initialized
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the value for
rng_type
is invalidNVPL_RAND_STATUS_SUCCESS if the generator was generated successfully

nvplRandStatus_t nvplRandDestroyGenerator(nvplRandGenerator_t gen)¶
Destroy an existing generator and free all memory associated with its state.
 Parameters:
gen – Generator to destroy
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_SUCCESS if generator was destroyed successfully

nvplRandStatus_t nvplRandGetVersion(int *version)¶
Return the
version
number of the NVPL RAND library. Parameters:
version – RAND library version
 Returns:
NVPL_RAND_STATUS_SUCCESS if the version number was successfully returned

nvplRandStatus_t nvplRandSetPseudoRandomGeneratorSeed(nvplRandGenerator_t gen, const unsigned long long seed)¶
Set the seed value of the pseudorandom number generator.
All values of seed are valid. Different seeds will produce different sequences. Different seeds will often not be statistically correlated with each other, but some pairs of seed values may generate sequences which are statistically correlated.
The default values
seed
are:0ULL, for NVPL_RAND_RNG_PSEUDO_XORWOW
12345ULL, for NVPL_RAND_RNG_PSEUDO_MRG32K3A
5489ULL, for NVPL_RAND_RNG_PSEUDO_MT19937
0xdeadbeefdeadbeefULL, for NVPL_RAND_RNG_PSEUDO_PHILOX4_32_10
0x853c49e6748fea9bULL, for NVPL_RAND_RNG_PSEUDO_PCG
 Parameters:
gen – Generator to modify
seed – Seed value
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the generator is not a pseudorandom number generator
NVPL_RAND_STATUS_SUCCESS if generator seed was set successfully

nvplRandStatus_t nvplRandSetPCGRandomGeneratorIncrement(nvplRandGenerator_t gen, const unsigned long long inc)¶
Set the increment of the PCG pseudo number generator.
The increment value for PCG must always be odd. The default value of
inc
is 0xda3e39cb94b95bdbULL. Parameters:
gen – Generator to modify
inc – Increment value of PCG, controlling which subsequence is selected
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the generator is not PCG
NVPL_RAND_STATUS_PCG_INCREMENT_NOT_ODD if the increment value is an even number
NVPL_RAND_STATUS_SUCCESS if generator increment value was set successfully

nvplRandStatus_t nvplRandSetGeneratorOffset(nvplRandGenerator_t gen, const unsigned long long offset)¶
Set the absolute offset of the pseudo or quasirandom number generator.
All values of offset are valid. The offset position is absolute, not relative to the current position in the sequence.
For quasirandom generators, the offset is the absolute position in the sequence generated per dimension.
The default values
offset
for all generators are 0ULL. Parameters:
gen – Generator to modify
offset – Absolute offset position
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_SUCCESS if generator offset was set successfully

nvplRandStatus_t nvplRandSetGeneratorSubsequence(nvplRandGenerator_t gen, const unsigned long long seq)¶
Set subsequence number for the pseudo number generator.
Set subsequence, or stream, number for the pseudo number generator to allow explicitly skipping subsequence by users. The ability to generate multiple subsequences of pseudorandom numbers allows developing parallel random number generation using the singlethreaded NVPL RAND library.
The subsequence position is absolute, not relative to the current state’s subsequence.
Supported pseudo random generators: XORWOW, MRG32K3A, PHILOX4_32_10, and PCG.
Except for MRG32K3a, which has the max subsequence number \(2^{51}\), all values of subsequence are valid.
The API is recommended to only be used with a singlethreaded generator.
 Parameters:
gen – Generator to modify
seq – Subsequence number to be set
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the API is not supported for the generator
NVPL_RAND_STATUS_OUT_OF_RANGE if the subsequence number is out of range
NVPL_RAND_STATUS_SUCCESS if generator subsequence was set successfully

nvplRandStatus_t nvplRandSetQuasiRandomGeneratorDimensions(nvplRandGenerator_t gen, const unsigned int num_dims)¶
Set the number of dimensions for the quasirandom number generator.
When generating results in num_dims dimensions, the size n output will consist of n / num_dims results from the 1st dimension, followed by n / num_dims results from the 2nd dimension, and so on up to the last dimension. Only exact multiples of the dimension size may be generated.
Legal values for
num_dims
are 1 to 20000; the default is 1. Parameters:
gen – Generator to modify
num_dims – Number of dimensions
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_OUT_OF_RANGE if num_dimensions is not valid
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the generator is not a quasirandom number generator
NVPL_RAND_STATUS_SUCCESS if the dimension was set successfully

nvplRandStatus_t nvplRandGenerate(nvplRandGenerator_t gen, unsigned int *outputPtr, const size_t num)¶
Generate 32bit pseudo or quasirandom numbers with XORWOW, MRG32K3A, MT19937, PHILOX4_32_10, PCG, SOBOL32, and Scrambled SOBOL32 generators.
Use
gen
to generatenum
32bit results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are 32bit values with every bit random.
 Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of random 32bit values to generate
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the generator type does not match the data type
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE if the number of output samples is not a multiple of the quasirandom dimension
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateLongLong(nvplRandGenerator_t gen, unsigned long long *outputPtr, const size_t num)¶
Generate 64bit pseudo or quasirandom numbers with PCG, SOBOL64, and Scrambled SOBOL64 generators.
Use
gen
to generatenum
64bit results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are 64bit values with every bit random.
 Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of random 64bit values to generate
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the generator type is not a 64bit generator
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE if the number of output samples is not a multiple of the quasirandom dimension
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateUniform(nvplRandGenerator_t gen, float *outputPtr, const size_t num)¶
Generate uniformly distributed floats.
Use
gen
to generatenum
float results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are FP32 uniformly distributed random values between between 0 and 1, excluding 0 and including 1.
 Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of floats to generate
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE if the number of output samples is not a multiple of the quasirandom dimension
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateUniformDouble(nvplRandGenerator_t gen, double *outputPtr, const size_t num)¶
Generate uniformly distributed doubles.
Use
generator
to generatenum
float results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are FP64 uniformly distributed random values between 0 and 1, excluding 0 and including 1.
 Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of doubles to generate
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE if the number of output samples is not a multiple of the quasirandom dimension
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateUniformRange(nvplRandGenerator_t gen, float *outputPtr, const size_t num, const float start, const float end)¶
Generate uniformly distributed floats with custom range.
Use
gen
to generatenum
float results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are FP32 uniformly distributed random values between
start
andend
, excludingstart
and includingend
. Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of floats to generate
start – Start of the interval
end – End of the interval
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE if the number of output samples is not a multiple of the quasirandom dimension
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateUniformRangeDouble(nvplRandGenerator_t gen, double *outputPtr, const size_t num, const double start, const double end)¶
Generate uniformly distributed doubles with custom range.
Use
gen
to generatenum
float results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are FP64 uniformly distributed random values between
start
andend
, excludingstart
and includingend
. Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of doubles to generate
start – Start of the interval
end – End of the interval
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE if the number of output samples is not a multiple of the quasirandom dimension
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateNormal(nvplRandGenerator_t gen, float *outputPtr, const size_t num, const float mean, const float stddev)¶
Generate normally distributed floats.
Use
gen
to generatenum
float results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are FP32 normally distributed random values with mean
mean
and standard deviationstddev
.Normally distributed results are generated from pseudorandom generators with a BoxMuller transform. Quasirandom generators use an inverse cumulative distribution function (ICDF) to preserve dimensionality.
 Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of floats to generate
mean – Mean of normal distribution
stddev – Standard deviation of normal distribution
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE if the number of output samples is not a multiple of the quasirandom dimension, or is not a multiple of two for pseudorandom generators
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateNormalDouble(nvplRandGenerator_t gen, double *outputPtr, const size_t num, const double mean, const double stddev)¶
Generate normally distributed doubles.
Use
gen
to generatenum
float results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are FP64 normally distributed random values with mean
mean
and standard deviationstddev
.Normally distributed results are generated from pseudorandom generators (except Mersenne Twister MT19937) with a BoxMuller transform, so require
num
be to be even. Quasirandom generators and Mersenne Twister MT19937 use an inverse cumulative distribution function (ICDF) to preserve dimensionality. Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of doubles to generate
mean – Mean of normal distribution
stddev – Standard deviation of normal distribution
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE if the number of output samples is not a multiple of the quasirandom dimension, or is not a multiple of two for pseudorandom generators
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateDistribution(nvplRandGenerator_t gen, float *outputPtr, const nvplRandDistributionConfig_t config, const size_t num)¶
Generate floats based on specified continuous distribution.
Use
gen
to generatenum
float results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are FP32 random values with userspecified distribution
config
.Normally distributed results are generated from pseudorandom generators (except Mersenne Twister MT19937) with a BoxMuller transform, so require
num
be to be even. Quasirandom generators and Mersenne Twister MT19937 use an inverse cumulative distribution function (ICDF) to preserve dimensionality. Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store the results
config – Configurations of the distribution
num – Number of floats to generate. For multivariate distributions, e.g., Dirichlet, ( num *
config.nk
) number of floats are generated.
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_DISTRIBUTION_TYPE_ERROR if the distribution type is not supported
NVPL_RAND_STATUS_DISTRIBUTION_CONFIGS_ERROR if the distribution config is incorrectly set, or does not support certain ordering. Note that Gamma, Beta, and Dirichlet distributions do not support NVPL_RAND_ORDERING_STRICT order
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateDistributionDouble(nvplRandGenerator_t gen, double *outputPtr, const nvplRandDistributionConfig_t config, const size_t num)¶
Generate doubles based on specified continuous distribution.
Use
gen
to generatenum
double results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are FP64 random values with userspecified distribution
config
. Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store the results
config – Configurations of the distribution
num – Number of floats to generate. For multivariate distributions, e.g., Dirichlet, ( num *
config.nk
) number of doubles are generated.
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_DISTRIBUTION_TYPE_ERROR if the distribution type is not supported
NVPL_RAND_STATUS_DISTRIBUTION_CONFIGS_ERROR if the distribution config is incorrectly set, or does not support certain ordering. Note that Gamma, Beta, and Dirichlet distributions do not support NVPL_RAND_ORDERING_STRICT order
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandGenerateDistributionDiscrete(nvplRandGenerator_t gen, unsigned int *outputPtr, const nvplRandDistributionConfig_t distConfig, const size_t num)¶
Generate unsigned integers based on specified discrete distribution.
Use
gen
to generatenum
integer results into the memory atoutputPtr
. The memory must have been previously allocated and be large enough to hold all the results.Results are 32bit random integer values with userspecified distribution
config
. Parameters:
gen – Generator to use
outputPtr – Pointer to the memory to store the results
distConfig – Configurations of the distribution
num – Number of unsigned integers to generate. For multivariate distributions, e.g., multinomial, ( num *
config.nk
) number of unsigned integers are generated.
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was never created
NVPL_RAND_STATUS_DATA_NULLPTR if outputPtr is nullptr
NVPL_RAND_STATUS_DISTRIBUTION_TYPE_ERROR if the distribution type is not supported
NVPL_RAND_STATUS_DISTRIBUTION_CONFIGS_ERROR if the distribution config is incorrectly set, or does not support certain ordering. Note that Poison distribution does not support NVPL_RAND_ORDERING_STRICT order
NVPL_RAND_STATUS_SUCCESS if the results were generated successfully

nvplRandStatus_t nvplRandMTCreateGenerator(nvplRandGenerator_t *gen, nvplRandRngType_t rng_type, const unsigned int nthreads)¶
Create a new random number generator of type
rng_type
, set the number of threads to benthreads
, and returns it in*gen
.Legal values for
rng_type
are:NVPL_RAND_RNG_PSEUDO_DEFAULT
NVPL_RAND_RNG_PSEUDO_XORWOW
NVPL_RAND_RNG_PSEUDO_MRG32K3A
NVPL_RAND_RNG_PSEUDO_PHILOX4_32_10
NVPL_RAND_RNG_PSEUDO_PCG
NVPL_RAND_RNG_QUASI_DEFAULT
NVPL_RAND_RNG_QUASI_SOBOL32
NVPL_RAND_RNG_QUASI_SCRAMBLED_SOBOL32
NVPL_RAND_RNG_QUASI_SOBOL64
NVPL_RAND_RNG_QUASI_SCRAMBLED_SOBOL64
When
rng_type
isNVPL_RAND_RNG_PSEUDO_DEFAULT
, the type chosen isNVPL_RAND_RNG_PSEUDO_XORWOW
. Whenrng_type
is NVPL_RAND_RNG_QUASI_DEFAULT, the type chosen isNVPL_RAND_RNG_QUASI_SOBOL32
.The API can only be used when linking to the multithreaded NVPL RAND library.
 Parameters:
gen – Pointer to generator
rng_type – Type of generator to create
nthreads – Number of threads used to generate random numbers
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was not initialized
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the value for
rng_type
is invalidNVPL_RAND_STATUS_SUCCESS if the generator was generated successfully

nvplRandStatus_t nvplRandMTCreateGeneratorDefault(nvplRandGenerator_t *gen, nvplRandRngType_t rng_type)¶
Create a new random number generator of type
rng_type
, set the number of threads to be the value of std::thread::hardware_concurrency(), and returns it in*gen
.The API can only be used when linking to the multithreaded NVPL RAND library.
 Parameters:
gen – Pointer to generator
rng_type – Type of generator to create
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was not initialized
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the value for
rng_type
is invalidNVPL_RAND_STATUS_SUCCESS if the generator was generated successfully

nvplRandStatus_t nvplRandMTSetGeneratorOrdering(nvplRandGenerator_t gen, nvplRandOrdering_t order)¶
Set the ordering of results of the pseudo or quasirandom number generator.
Legal values of
order
for pseudorandom generators are:NVPL_RAND_ORDERING_PSEUDO_DEFAULT
NVPL_RAND_ORDERING_PSEUDO_FAST
NVPL_RAND_ORDERING_STRICT
NVPL_RAND_ORDERING_CURAND_LEGACY
Legal values of
order
for quasirandom generators are:NVPL_RAND_ORDERING_QUASI_DEFAULT
The API can only be used when linking to the multithreaded NVPL RAND library.
 Parameters:
gen – Generator to modify
order – Ordering of results
 Returns:
NVPL_RAND_STATUS_GENERATOR_NOT_INITIALIZED if the generator was not initialized
NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR if the generator does not support the ordering type
NVPL_RAND_STATUS_SUCCESS if the generator ordering was set successfully

struct nvplRandDistributionConfig¶
Configuration to describe the properties of a data distribution.
Public Members

nvplRandDistributionType_t dist¶
Distribution type.

double a¶
For each of the distribution type, the double value
a
is:NVPL_RAND_CONTINUOUS_DIST_UNIFORM: not used
NVPL_RAND_CONTINUOUS_DIST_UNIFORM_RANGE : start value of the range (start, end]
NVPL_RAND_CONTINUOUS_DIST_NORMAL : mean of the normal distribution
NVPL_RAND_CONTINUOUS_DIST_LOGNORMAL : mean of the associated normal distribution
NVPL_RAND_CONTINUOUS_DIST_EXPONENTIAL : location parameter of exponential distribution, \( \lambda \)
NVPL_RAND_CONTINUOUS_DIST_GAMMA : shape parameter, \( \alpha > 0 \)
NVPL_RAND_CONTINUOUS_DIST_BETA : shape parameter, \( \alpha > 0 \)
NVPL_RAND_CONTINUOUS_DIST_DIRICHLET: not used
NVPL_RAND_DISCRETE_DIST_POISSON : rate parameter, \( \lambda > 0 \)
NVPL_RAND_DISCRETE_DIST_BERNOULLI : rate parameter, \( 1 >= \lambda >= 0 \)
NVPL_RAND_DISCRETE_DIST_CATEGORICAL : not used
NVPL_RAND_DISCRETE_DIST_BINOMIAL : rate parameter, \( 1 >= \lambda >= 0 \)

double b¶
For each of the distribution type, the double value
b
needs to be defined only for the following distributions:NVPL_RAND_CONTINUOUS_DIST_UNIFORM_RANGE : end value of the range (start, end]
NVPL_RAND_CONTINUOUS_DIST_NORMAL : stddev of normal distribution
NVPL_RAND_CONTINUOUS_DIST_LOGNORMAL : stddev of associated normal distribution
NVPL_RAND_CONTINUOUS_DIST_GAMMA : scale parameter, \( \beta > 0 \)
NVPL_RAND_CONTINUOUS_DIST_BETA : shape parameter, \( \beta > 0 \)

double *p_array¶
The double array
p_array
needs to be defined only for the following distributions:NVPL_RAND_CONTINUOUS_DIST_DIRICHLET: shape parameter arrays of size k, all > 0
NVPL_RAND_DISCRETE_DIST_CATEGORICAL: probability arrays, all >= 0

unsigned int nk¶
The unsigned integer value
nk
needs to be defined only for the following distributions:NVPL_RAND_CONTINUOUS_DIST_DIRICHLET: size of the shape parameters
NVPL_RAND_DISCRETE_DIST_CATEGORICAL: size of the probability parameters, >1 (if =1, use Bernoulli)
NVPL_RAND_DISCRETE_DIST_BINOMIAL : size of Bernoulli trials, >1 (if =1, use Bernoulli)
NVPL_RAND_DISCRETE_DIST_MULTINOMIAL : size of the probability parameters, >1

unsigned int nt¶
The unsigned integer value
nt
needs to be defined only for the following distribution:NVPL_RAND_DISCRETE_DIST_MULTINOMIAL : size of the Bernoulli trials >1

nvplRandDistributionType_t dist¶