Generator Options

Once created, random number generators can be modified, as needed, using multiple options.

Seed

The seed parameter is a 64-bit integer that initializes the starting state of a pseudorandom number generator. The same seed always produces the same sequence of results. The default seed is different for each generator, see nvplRandSetPseudoRandomGeneratorSeed() for details.

Offset

The offset parameter is used to skip ahead in the sequence. If offset = 100, the first random number generated will be the 100th in the sequence. This allows multiple runs of the same program to continue generating results from the same sequence without overlap. The default offset is zero.

Subsequence

The subsequence parameter is used to skip ahead in subsequence of a pseudorandom number generator. If offset = 10 and subsequence = 100, the first random number generated will be the 10th in the 100th subsequence. The ability to generate multiple subsequences of pseudorandom numbers allows developing parallel random number generation using the single-threaded NVPL RAND library. The default subsequence is zero.

Dimension

The dimension parameter is used to set the number of dimensions to be generated by a quasirandom number generator. When generating results in d dimensions, the size-n output will consist of n / d results from the 1st dimension, followed by n / d results from the 2nd dimension, and so on up to the d-th dimension. Only exact multiples of the dimension size may be generated; otherwise NVPL_RAND_STATUS_LENGTH_NOT_MULTIPLE status is returned. The default number of dimensions is 1.

Increment

The increment parameter is used to set the increment value of a PCG pseudorandom generator. The increment value controls which subsequence is selected to generate random numbers by PCG [4]. Setting the increment parameter for any generators other than PCG will return NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR. The paramer must always be odd; otherwise NVPL_RAND_STATUS_PCG_INCREMENT_NOT_ODD status is returned. See nvplRandSetPCGRandomGeneratorIncrement() for the default increment value.

Order

The order parameter is used to select how the results are ordered in memory. It also has a direct influence on the performance of the generation functions.

Note

NVPL_RAND_RNG_PSEUDO_MT19937 supports only single-threaded random number generation in the current release. Therefore, setting the order parameter for the MT19937 generator returns NVPL_RAND_STATUS_GENERATOR_TYPE_ERROR.

There are four ordering choices for pseudorandom sequences:

  • NVPL_RAND_ORDERING_PSEUDO_DEFAULT,

  • NVPL_RAND_ORDERING_PSEUDO_FAST,

  • NVPL_RAND_ORDERING_STRICT,

  • NVPL_RAND_ORDERING_CURAND_LEGACY.

There is one ordering choice for quasirandom numbers: NVPL_RAND_ORDERING_QUASI_DEFAULT.

The default order for pseudorandom number generators is NVPL_RAND_ORDERING_PSEUDO_DEFAULT, while the default ordering for quasirandom number generators is NVPL_RAND_ORDERING_QUASI_DEFAULT.

Ordering obtained with these parameters is deterministic, and is the same for each run of the program if the same number of threads is used.

  • NVPL_RAND_ORDERING_PSEUDO_DEFAULT order is NVPL_RAND_ORDERING_PSEUDO_FAST for all multi-threaded pseudorandom generators.

  • NVPL_RAND_ORDERING_STRICT order provides good performance and guarantees exactly the same sequence regardless of the number of threads used.

  • NVPL_RAND_ORDERING_STRICT order also provides exactly the same sequence as the one generated with single-threaded NVPL RAND library.

  • Due to variadic number of state changes required to generate one value for Gamma, Beta, Dirichlet, and Poisson distributions, NVPL_RAND_ORDERING_STRICT order does not support these distributions. NVPL_RAND_STATUS_DISTRIBUTION_CONFIGS_ERROR returns if NVPL_RAND_ORDERING_STRICT order is set for generating values of any of the four distributions.

  • NVPL_RAND_ORDERING_PSEUDO_FAST order in general gives the best performance, but the sequence changes if using a different number of threads.

  • NVPL_RAND_ORDERING_CURAND_LEGACY order guarantees exactly the same sequence as the cuRAND results generated with CURAND_ORDERING_PSEUDO_LEGACY order (see CURAND_ORDERING_PSEUDO_LEGACY). But the performance of the NVPL_RAND_ORDERING_CURAND_LEGACY order could be much slower than NVPL_RAND_ORDERING_STRICT or NVPL_RAND_ORDERING_PSEUDO_FAST orders because of the memory access pattern.

  • NVPL_RAND_ORDERING_QUASI_DEFAULT order guarantees exactly the same sequence as the cuRAND results using the same variant of SOBOL quasirandom generator.

The differences in behavior of the order parameters for each generator type are outlined below:

XORWOW pseudorandom generator

  • NVPL_RAND_ORDERING_PSEUDO_DEFAULT order is same as NVPL_RAND_ORDERING_PSEUDO_FAST.

  • NVPL_RAND_ORDERING_STRICT - All results are generated in a single subsequence. The result at offset n is from position n in the subsequence.

  • NVPL_RAND_ORDERING_PSEUDO_FAST - To generate num_size random numbers using num_threads threads with offset n, each thread tid generates (num_size / num_threads) numbers in subsequence (tid + n) % num_threads.

  • NVPL_RAND_ORDERING_CURAND_LEGACY - The result at offset n is from position \((n \% 4096) * 2^{67} + [ n / 4096]\) in the original XORWOW sequence.

MRG32k3a pseudorandom generator

  • NVPL_RAND_ORDERING_PSEUDO_DEFAULT order is same as NVPL_RAND_ORDERING_PSEUDO_FAST.

  • NVPL_RAND_ORDERING_STRICT - All results are generated in a single subsequence. The result at offset n is from position n in the subsequence.

  • NVPL_RAND_ORDERING_PSEUDO_FAST - To generate num_size random numbers using num_threads threads with offset n, each thread tid generates (num_size / num_threads) numbers in subsequence (tid + n) % num_threads.

  • NVPL_RAND_ORDERING_CURAND_LEGACY - The result at offset n is from position \((n \% 4096) * 2^{76} + [ n / 4096]\) in the original MRG32k3a sequence. Note that the stride between subsequent samples for MRG32k3a is not the same as for XORWOW.

Philox_4x32_10 pseudorandom generator

  • NVPL_RAND_ORDERING_PSEUDO_DEFAULT order is same as NVPL_RAND_ORDERING_PSEUDO_FAST.

  • NVPL_RAND_ORDERING_STRICT - All results are generated in a single subsequence. The result at offset n is from position n in the subsequence.

  • NVPL_RAND_ORDERING_PSEUDO_FAST - To generate num_size random numbers using num_threads threads with offset n, each thread tid generates (num_size / num_threads) numbers in subsequence (tid + n) % num_threads.

  • NVPL_RAND_ORDERING_CURAND_LEGACY - Each thread generates distinct sequences based on different parameter sets for the basic algorithm. There are total 65535 different sequence. Each four values from one sequence are followed by four values from next sequence.

PCG pseudorandom generator

  • NVPL_RAND_ORDERING_PSEUDO_DEFAULT order is same as NVPL_RAND_ORDERING_PSEUDO_FAST.

  • NVPL_RAND_ORDERING_STRICT - All results are generated in a single subsequence. The result at offset n is from position n in the subsequence.

  • NVPL_RAND_ORDERING_PSEUDO_FAST - To generate num_size random numbers using num_threads threads with offset n, each thread tid generates (num_size / num_threads) numbers in subsequence (tid + n) % num_threads.

Note

PCG generator does not support NVPL_RAND_ORDERING_CURAND_LEGACY because the generator is not available in cuRAND.

32- and 64-bit SOBOL and Scrambled SOBOL quasirandom generators

  • NVPL_RAND_ORDERING_QUASI_DEFAULT - When generating n results in d dimensions, the output will consist of n / d results from the 1st Dimension, followed by n / d results from the 2nd dimension, and so on up to the d-th dimension. Only exact multiples of the dimension size may be generated.