3. C/C++ API Reference

This chapter describes the hipRAND C and C++ API.

3.1. Device Functions

group hipranddevice

Defines

HIPRAND_PHILOX4x32_DEFAULT_SEED: Default seed for PHILOX4x32 PRNG.

HIPRAND_XORWOW_DEFAULT_SEED: Default seed for XORWOW PRNG.

HIPRAND_MRG32K3A_DEFAULT_SEED: Default seed for MRG32K3A PRNG.

HIPRAND_MTGP32_DEFAULT_SEED: Default seed for MTGP32 PRNG.

HIPRAND_MT19937_DEFAULT_SEED: Default seed for MT19937 PRNG.

Functions

void hiprand_mtgp32_block_copy(hiprandStateMtgp32_t *src, hiprandStateMtgp32_t *dest)

Copy MTGP32 state to another state using block of threads.

Copies a MTGP32 state src to dest using a block of threads efficiently. Example usage would be:

__global__
void generate_kernel(hiprandStateMtgp32_t * states, unsigned int * output, const size_t size)
{
     const unsigned int state_id = hipBlockIdx_x;
     unsigned int index = hipBlockIdx_x * hipBlockDim_x + hipThreadIdx_x;
     unsigned int stride = hipGridDim_x * hipBlockDim_x;

     __shared__ GeneratorState state;
     hiprand_mtgp32_block_copy(&states[state_id], &state);

     while(index < size)
     {
         output[index] = rocrand(&state);
         index += stride;
     }

     hiprand_mtgp32_block_copy(&state, &states[state_id]);
}

Parameters:

src – - Pointer to a state to copy from
dest – - Pointer to a state to copy to

void hiprand_mtgp32_set_params(hiprandStateMtgp32_t *state, mtgp32_kernel_params_t *params)

Changes parameters of a MTGP32 state.

Parameters:

state – - Pointer to a MTGP32 state
params – - Pointer to new parameters

template<class StateType> void hiprand_init(const unsigned long long seed, const unsigned long long subsequence, const unsigned long long offset, StateType *state)

Initializes a PRNG state.

Template Parameters:

StateType – - Pseudorandom number generator state type. StateType type must be one of following types: hiprandStateXORWOW_t, hiprandStatePhilox4_32_10_t, or hiprandStateMRG32k3a_t

Parameters:

seed – - Pseudorandom number generator’s seed
subsequence – - Number of subsequence to skipahead
offset – - Absolute subsequence offset, i.e. how many states from current subsequence should be skipped
state – - Pointer to a state to initialize

void hiprand_init(hiprandDirectionVectors32_t direction_vectors, unsigned int offset, hiprandStateSobol32_t *state)

Initializes a Sobol32 state.

Parameters:

direction_vectors – - Pointer to array of 32 unsigned ints that represent the direction numbers.
offset – - Absolute subsequence offset, i.e. how many states should be skipped.
state – - Pointer to a state to initialize.

void hiprand_init(hiprandDirectionVectors32_t direction_vectors, unsigned int scramble_constant, unsigned int offset, hiprandStateScrambledSobol32_t *state)

Initializes a ScrambledSobol32 state.

Parameters:

direction_vectors – - Pointer to array of 32 unsigned ints that represent the direction numbers.
scramble_constant – - Constant used for scrambling the sequence.
offset – - Absolute subsequence offset, i.e. how many states should be skipped.
state – - Pointer to a state to initialize.

void hiprand_init(hiprandDirectionVectors64_t direction_vectors, unsigned int offset, hiprandStateSobol64_t *state)

Initializes a Sobol64 state.

Parameters:

direction_vectors – - Pointer to array of 64 unsigned long long ints that represent the direction numbers.
offset – - Absolute subsequence offset, i.e. how many states should be skipped.
state – - Pointer to a state to initialize.

void hiprand_init(hiprandDirectionVectors64_t direction_vectors, unsigned long long int scramble_constant, unsigned int offset, hiprandStateScrambledSobol64_t *state)

Initializes a ScrambledSobol64 state.

Parameters:

direction_vectors – - Pointer to array of 64 unsigned long long ints that represent the direction numbers.
scramble_constant – - Constant used for scrambling the sequence.
offset – - Absolute subsequence offset, i.e. how many states should be skipped.
state – - Pointer to a state to initialize.

template<class StateType> void skipahead(unsigned long long n, StateType *state)

Updates RNG state skipping n states ahead.

Template Parameters:

StateType – - Random number generator state type. StateType type must be one of following types: hiprandStateXORWOW_t, hiprandStatePhilox4_32_10_t, hiprandStateMRG32k3a_t, hiprandStateSobol32_t, hiprandStateScrambledSobol32_t, hiprandStateSobol64_t, or hiprandStateScrambledSobol64_t.

Parameters:

n – - Number of states to skipahead
state – - Pointer to a state to modify

template<class StateType> void skipahead_sequence(unsigned long long n, StateType *state)

Updates PRNG state skipping n sequences ahead.

 PRNG     | Sequence size [Number of elements]

———-— | ———-— XORWOW | 2^67 Philox | 4 * 2^64 MRG32k3a | 2^67

Template Parameters:

StateType – - Random number generator state type. StateType type must be one of following types: hiprandStateXORWOW_t, hiprandStatePhilox4_32_10_t, or hiprandStateMRG32k3a_t

Parameters:

n – - Number of subsequences to skipahead
state – - Pointer to a state to update

template<class StateType> void skipahead_subsequence(unsigned long long n, StateType *state)

Updates PRNG state skipping n subsequences ahead.

 PRNG     | Subsequence size [Number of elements]

———-— | ———-— XORWOW | 2^67 Philox | 4 * 2^64 MRG32k3a | 2^127

Template Parameters:

StateType – - Random number generator state type. StateType type must be one of following types: hiprandStateXORWOW_t, hiprandStatePhilox4_32_10_t, or hiprandStateMRG32k3a_t

Parameters:

n – - Number of subsequences to skipahead
state – - Pointer to a state to update

template<class StateType> unsigned int hiprand(StateType *state)

Generates uniformly distributed random unsigned int from [0; 2^32 - 1] range.

Template Parameters:: StateType – - Random number generator state type. StateType type must be one of following types: hiprandStateXORWOW_t, hiprandStatePhilox4_32_10_t, hiprandStateMRG32k3a_t, hiprandStateMtgp32_t, hiprandStateSobol32_t, hiprandStateScrambledSobol32_t.
Parameters:: state – - Pointer to a RNG state to use
Returns:: Uniformly distributed random 32-bit unsigned int

uint4 hiprand4(hiprandStatePhilox4_32_10_t *state)

Generates four uniformly distributed random unsigned ints from [0; 2^32 - 1] range.

Parameters:: state – - Pointer to a Philox state to use
Returns:: Four uniformly distributed random 32-bit unsigned ints as uint4

template<class StateType> unsigned long long int hiprand_long_long(StateType *state)

Generates uniformly distributed random unsigned long long int from [0; 2^64 - 1] range.

Template Parameters:: StateType – - Random number generator state type. StateType type must be one of the following types: hiprandStateSobol64_t or hiprandStateScrambledSobol64_t.
Parameters:: state – - Pointer to a RNG state to use
Returns:: Uniformly distributed random 64-bit unsigned long long int

template<class StateType> float hiprand_uniform(StateType *state)

Generates uniformly distributed random float value from (0; 1] range.

Template Parameters:: StateType – - Random number generator state type.
Parameters:: state – - Pointer to a RNG state to use
Returns:: Uniformly distributed random float value

float4 hiprand_uniform4(hiprandStatePhilox4_32_10_t *state)

Generates four uniformly distributed random float value from (0; 1] range.

Parameters:: state – - Pointer to a Philox state to use
Returns:: Four uniformly distributed random float values as float4

template<class StateType> double hiprand_uniform_double(StateType *state)

Generates uniformly distributed random double value from (0; 1] range.

Note: When state is of type: hiprandStateMRG32k3a_t, hiprandStateMtgp32_t, hiprandStateSobol32_t, or hiprandStateScrambledSobol32_t then the returned double value is generated using only 32 random bits (one unsigned int value). In case of the Sobol types, this is done to guarantee the quasirandom properties.

Template Parameters:: StateType – - Random number generator state type.
Parameters:: state – - Pointer to a RNG state to use
Returns:: Uniformly distributed random double value

double2 hiprand_uniform2_double(hiprandStatePhilox4_32_10_t *state)

Generates two uniformly distributed random double values from (0; 1] range.

Parameters:: state – - Pointer to a Philox state to use
Returns:: Two uniformly distributed random double values as double2

double4 hiprand_uniform4_double(hiprandStatePhilox4_32_10_t *state)

Generates four uniformly distributed random double values from (0; 1] range.

Parameters:: state – - Pointer to a Philox state to use
Returns:: Four uniformly distributed random double values as double4

template<class StateType> float hiprand_normal(StateType *state)

Generates normally distributed random float value.