C/C++ API reference

C/C++ API reference#

This document describes the hipRAND APIs available in C and C++.

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.

Typedefs

typedef struct hiprandStateXORWOW hiprandStateXORWOW_t#: XORWOW PRNG state type.

typedef hiprandStateXORWOW_t hipRandState_t#

Deprecated alias of hiprandStateXORWOW_t.

Deprecated:: Please use hiprandStateXORWOW_t directly.

typedef struct hiprandStatePhilox4_32_10 hiprandStatePhilox4_32_10_t#: PHILOX PRNG state type.

typedef struct hiprandStateMRG32k3a hiprandStateMRG32k3a_t#: MRG32k3a PRNG state type.

typedef struct hiprandStateMtgp32 hiprandStateMtgp32_t#: MTGP32 PRNG state type.

typedef struct hiprandStateScrambledSobol32 hiprandStateScrambledSobol32_t#: Scrambled SOBOL32 QRNG state type.

typedef struct hiprandStateScrambledSobol64 hiprandStateScrambledSobol64_t#: Scrambled SOBOL64 QRNG state type.

typedef struct hiprandStateSobol32 hiprandStateSobol32_t#: SOBOL32 QRNG state type.

typedef struct hiprandStateSobol64 hiprandStateSobol64_t#: SOBOL64 QRNG state type.

typedef mtgp32_params mtgp32_kernel_params_t#: Opaque MTGP32 PRNG state parameters in the device format.

typedef struct mtgp32_params_fast mtgp32_params_fast_t#: Opaque MTGP32 PRNG state parameters in the host format.

typedef mtgp32_fast_params mtgp32_fast_param_t#

Deprecated alias of mtgp32_params_fast_t.

Deprecated:: please use mtgp32_params_fast_t directly.

typedef unsigned int hiprandDirectionVectors32_t[32]#: Convenience typedef for Sobol 32 direction vector array.

typedef unsigned long long hiprandDirectionVectors64_t[64]#: Convenience typedef for Sobol 64 direction vector array.

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.

Note

MTGP32 must be initialized from the host using hiprandMakeMTGP32KernelState().

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 \times 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 \times 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 quasi-random 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.