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 multi-threaded 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¶: PHILOX-4x32-10 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.

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¶: Normal distribution.

enumerator NVPL_RAND_CONTINUOUS_DIST_LOGNORMAL¶: Log-normal distribution.

enumerator NVPL_RAND_CONTINUOUS_DIST_EXPONENTIAL¶: Exponential distribution.

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¶: Poisson distribution.

enumerator NVPL_RAND_DISCRETE_DIST_BERNOULLI¶: Bernoulli distribution.

enumerator NVPL_RAND_DISCRETE_DIST_CATEGORICAL¶: Categorical distribution.

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.

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.

enum nvplRandOrdering¶

Ordering types of results in memory for multi-threaded generators.

Values:

enumerator NVPL_RAND_ORDERING_PSEUDO_DEFAULT¶: Default ordering for pseudorandom results.

enumerator NVPL_RAND_ORDERING_PSEUDO_FAST¶: Non-strict ordering with good performance but cannot recover offset.

enumerator NVPL_RAND_ORDERING_STRICT¶: Strict ordering generating same sequence as single-thread 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 n-dimensional ordering for quasirandom results.

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. When rng_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 invalid
NVPL_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 pseudo-random 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 single-threaded 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 single-threaded 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 32-bit pseudo or quasirandom numbers with XORWOW, MRG32K3A, MT19937, PHILOX4_32_10, PCG, SOBOL32, and Scrambled SOBOL32 generators.

Use gen to generate num 32-bit results into the memory at outputPtr. The memory must have been previously allocated and be large enough to hold all the results.

Results are 32-bit values with every bit random.

Parameters:

gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of random 32-bit 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 64-bit pseudo or quasirandom numbers with PCG, SOBOL64, and Scrambled SOBOL64 generators.

Use gen to generate num 64-bit results into the memory at outputPtr. The memory must have been previously allocated and be large enough to hold all the results.

Results are 64-bit values with every bit random.

Parameters:

gen – Generator to use
outputPtr – Pointer to the memory to store generated results
num – Number of random 64-bit 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 64-bit 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 generate num float results into the memory at outputPtr. 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 generate num float results into the memory at outputPtr. 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 generate num float results into the memory at outputPtr. 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 and end, excluding start and including end.

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 generate num float results into the memory at outputPtr. 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 and end, excluding start and including end.

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 generate num float results into the memory at outputPtr. 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 deviation stddev.

Normally distributed results are generated from pseudorandom generators with a Box-Muller 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 generate num float results into the memory at outputPtr. 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 deviation stddev.

Normally distributed results are generated from pseudorandom generators (except Mersenne Twister MT19937) with a Box-Muller 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 generate num float results into the memory at outputPtr. The memory must have been previously allocated and be large enough to hold all the results.

Results are FP32 random values with user-specified distribution config.

Normally distributed results are generated from pseudorandom generators (except Mersenne Twister MT19937) with a Box-Muller 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 multi-variate 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 generate num double results into the memory at outputPtr. The memory must have been previously allocated and be large enough to hold all the results.

Results are FP64 random values with user-specified 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 multi-variate 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 generate num integer results into the memory at outputPtr. The memory must have been previously allocated and be large enough to hold all the results.

Results are 32-bit random integer values with user-specified 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 multi-variate 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 be nthreads, 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 is NVPL_RAND_RNG_PSEUDO_DEFAULT, the type chosen is NVPL_RAND_RNG_PSEUDO_XORWOW. When rng_type is NVPL_RAND_RNG_QUASI_DEFAULT, the type chosen is NVPL_RAND_RNG_QUASI_SOBOL32.

The API can only be used when linking to the multi-threaded 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 invalid
NVPL_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 multi-threaded 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 invalid
NVPL_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 multi-threaded 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