rocRAND host API

rocRAND host API#

API library: rocRAND host API
Macros | Typedefs | Enumerations | Functions
rocRAND host API

Macros

#define ROCRAND_DEFAULT_MAX_BLOCK_SIZE   256
 The default maximum number of threads per block.
 

Typedefs

typedef enum rocrand_status rocrand_status
 rocRAND function call status type
 
typedef enum rocrand_rng_type rocrand_rng_type
 rocRAND generator type
 
typedef enum rocrand_ordering rocrand_ordering
 rocRAND generator ordering
 
typedef enum rocrand_direction_vector_set rocrand_direction_vector_set
 rocRAND vector set
 

Enumerations

enum  rocrand_status {
  ROCRAND_STATUS_SUCCESS = 0 , ROCRAND_STATUS_VERSION_MISMATCH = 100 , ROCRAND_STATUS_NOT_CREATED = 101 , ROCRAND_STATUS_ALLOCATION_FAILED = 102 ,
  ROCRAND_STATUS_TYPE_ERROR = 103 , ROCRAND_STATUS_OUT_OF_RANGE = 104 , ROCRAND_STATUS_LENGTH_NOT_MULTIPLE = 105 , ROCRAND_STATUS_DOUBLE_PRECISION_REQUIRED = 106 ,
  ROCRAND_STATUS_LAUNCH_FAILURE = 107 , ROCRAND_STATUS_INTERNAL_ERROR = 108
}
 rocRAND function call status type More...
 
enum  rocrand_rng_type {
  ROCRAND_RNG_PSEUDO_DEFAULT = 400 , ROCRAND_RNG_PSEUDO_XORWOW = 401 , ROCRAND_RNG_PSEUDO_MRG32K3A = 402 , ROCRAND_RNG_PSEUDO_MTGP32 = 403 ,
  ROCRAND_RNG_PSEUDO_PHILOX4_32_10 = 404 , ROCRAND_RNG_PSEUDO_MRG31K3P = 405 , ROCRAND_RNG_PSEUDO_LFSR113 = 406 , ROCRAND_RNG_PSEUDO_MT19937 = 407 ,
  ROCRAND_RNG_PSEUDO_THREEFRY2_32_20 = 408 , ROCRAND_RNG_PSEUDO_THREEFRY2_64_20 = 409 , ROCRAND_RNG_PSEUDO_THREEFRY4_32_20 = 410 , ROCRAND_RNG_PSEUDO_THREEFRY4_64_20 = 411 ,
  ROCRAND_RNG_QUASI_DEFAULT = 500 , ROCRAND_RNG_QUASI_SOBOL32 = 501 , ROCRAND_RNG_QUASI_SCRAMBLED_SOBOL32 = 502 , ROCRAND_RNG_QUASI_SOBOL64 = 504 ,
  ROCRAND_RNG_QUASI_SCRAMBLED_SOBOL64 = 505
}
 rocRAND generator type More...
 
enum  rocrand_ordering {
  ROCRAND_ORDERING_PSEUDO_BEST = 100 , ROCRAND_ORDERING_PSEUDO_DEFAULT = 101 , ROCRAND_ORDERING_PSEUDO_SEEDED = 102 , ROCRAND_ORDERING_PSEUDO_LEGACY = 103 ,
  ROCRAND_ORDERING_PSEUDO_DYNAMIC = 104 , ROCRAND_ORDERING_QUASI_DEFAULT = 201
}
 rocRAND generator ordering More...
 
enum  rocrand_direction_vector_set { ROCRAND_DIRECTION_VECTORS_32_JOEKUO6 = 101 , ROCRAND_SCRAMBLED_DIRECTION_VECTORS_32_JOEKUO6 = 102 , ROCRAND_DIRECTION_VECTORS_64_JOEKUO6 = 103 , ROCRAND_SCRAMBLED_DIRECTION_VECTORS_64_JOEKUO6 = 104 }
 rocRAND vector set
 

Functions

rocrand_status ROCRANDAPI rocrand_create_generator (rocrand_generator *generator, rocrand_rng_type rng_type)
 Creates a new random number generator. More...
 
rocrand_status ROCRANDAPI rocrand_create_generator_host (rocrand_generator *generator, rocrand_rng_type rng_type)
 Creates a new host random number generator. More...
 
rocrand_status ROCRANDAPI rocrand_create_generator_host_blocking (rocrand_generator *generator, rocrand_rng_type rng_type)
 Creates a new host random number generator, similar to rocrand_create_generator_host. The exception is that, instead of enqueuing the host function in the stream, execution happens synchronously with respect to the calling thread and the stream is ignored.
 
rocrand_status ROCRANDAPI rocrand_destroy_generator (rocrand_generator generator)
 Destroys random number generator. More...
 
rocrand_status ROCRANDAPI rocrand_generate (rocrand_generator generator, unsigned int *output_data, size_t n)
 Generates uniformly distributed 32-bit unsigned integers. More...
 
rocrand_status ROCRANDAPI rocrand_generate_long_long (rocrand_generator generator, unsigned long long int *output_data, size_t n)
 Generates uniformly distributed 64-bit unsigned integers. More...
 
rocrand_status ROCRANDAPI rocrand_generate_char (rocrand_generator generator, unsigned char *output_data, size_t n)
 Generates uniformly distributed 8-bit unsigned integers. More...
 
rocrand_status ROCRANDAPI rocrand_generate_short (rocrand_generator generator, unsigned short *output_data, size_t n)
 Generates uniformly distributed 16-bit unsigned integers. More...
 
rocrand_status ROCRANDAPI rocrand_generate_uniform (rocrand_generator generator, float *output_data, size_t n)
 Generates uniformly distributed float values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_uniform_double (rocrand_generator generator, double *output_data, size_t n)
 Generates uniformly distributed double-precision floating-point values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_uniform_half (rocrand_generator generator, half *output_data, size_t n)
 Generates uniformly distributed half-precision floating-point values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_normal (rocrand_generator generator, float *output_data, size_t n, float mean, float stddev)
 Generates normally distributed float values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_normal_double (rocrand_generator generator, double *output_data, size_t n, double mean, double stddev)
 Generates normally distributed double values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_normal_half (rocrand_generator generator, half *output_data, size_t n, half mean, half stddev)
 Generates normally distributed half values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_log_normal (rocrand_generator generator, float *output_data, size_t n, float mean, float stddev)
 Generates log-normally distributed float values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_log_normal_double (rocrand_generator generator, double *output_data, size_t n, double mean, double stddev)
 Generates log-normally distributed double values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_log_normal_half (rocrand_generator generator, half *output_data, size_t n, half mean, half stddev)
 Generates log-normally distributed half values. More...
 
rocrand_status ROCRANDAPI rocrand_generate_poisson (rocrand_generator generator, unsigned int *output_data, size_t n, double lambda)
 Generates Poisson-distributed 32-bit unsigned integers. More...
 
rocrand_status ROCRANDAPI rocrand_initialize_generator (rocrand_generator generator)
 Initializes the generator's state on GPU or host. More...
 
rocrand_status ROCRANDAPI rocrand_set_stream (rocrand_generator generator, hipStream_t stream)
 Sets the current stream for kernel launches. More...
 
rocrand_status ROCRANDAPI rocrand_set_seed (rocrand_generator generator, unsigned long long seed)
 Sets the seed of a pseudo-random number generator. More...
 
rocrand_status ROCRANDAPI rocrand_set_seed_uint4 (rocrand_generator generator, uint4 seed)
 Sets the seeds of a pseudo-random number generator. More...
 
rocrand_status ROCRANDAPI rocrand_set_offset (rocrand_generator generator, unsigned long long offset)
 Sets the offset of a random number generator. More...
 
rocrand_status ROCRANDAPI rocrand_set_ordering (rocrand_generator generator, rocrand_ordering order)
 Sets the ordering of a random number generator. More...
 
rocrand_status ROCRANDAPI rocrand_set_quasi_random_generator_dimensions (rocrand_generator generator, unsigned int dimensions)
 Set the number of dimensions of a quasi-random number generator. More...
 
rocrand_status ROCRANDAPI rocrand_get_version (int *version)
 Returns the version number of the library. More...
 
rocrand_status ROCRANDAPI rocrand_create_poisson_distribution (double lambda, rocrand_discrete_distribution *discrete_distribution)
 Construct the histogram for a Poisson distribution. More...
 
rocrand_status ROCRANDAPI rocrand_create_discrete_distribution (const double *probabilities, unsigned int size, unsigned int offset, rocrand_discrete_distribution *discrete_distribution)
 Construct the histogram for a custom discrete distribution. More...
 
rocrand_status ROCRANDAPI rocrand_destroy_discrete_distribution (rocrand_discrete_distribution discrete_distribution)
 Destroy the histogram array for a discrete distribution. More...
 
rocrand_status ROCRANDAPI rocrand_get_direction_vectors32 (const unsigned int **vectors, rocrand_direction_vector_set set)
 Get the vector for 32-bit (scrambled-)sobol generation. More...
 
rocrand_status ROCRANDAPI rocrand_get_direction_vectors64 (const unsigned long long **vectors, rocrand_direction_vector_set set)
 Get the vector for 64-bit (scrambled-)sobol generation. More...
 
rocrand_status ROCRANDAPI rocrand_get_scramble_constants32 (const unsigned int **constants)
 Get the scramble constants for 32-bit scrambled sobol generation. More...
 
rocrand_status ROCRANDAPI rocrand_get_scramble_constants64 (const unsigned long long **constants)
 Get the scramble constants for 64-bit scrambled sobol generation. More...
 

Detailed Description

Enumeration Type Documentation

◆ rocrand_ordering

enum rocrand_ordering

rocRAND generator ordering

Enumerator
ROCRAND_ORDERING_PSEUDO_BEST 

Best ordering for pseudorandom results.

ROCRAND_ORDERING_PSEUDO_DEFAULT 

Default ordering for pseudorandom results.

ROCRAND_ORDERING_PSEUDO_SEEDED 

Fast lower quality pseudorandom results.

ROCRAND_ORDERING_PSEUDO_LEGACY 

Legacy ordering for pseudorandom results.

ROCRAND_ORDERING_PSEUDO_DYNAMIC 

Adjust to the device executing the generator. The global memory usage may be higher than with the other orderings.

ROCRAND_ORDERING_QUASI_DEFAULT 

n-dimensional ordering for quasirandom results

◆ rocrand_rng_type

enum rocrand_rng_type

rocRAND generator type

Enumerator
ROCRAND_RNG_PSEUDO_DEFAULT 

Default pseudorandom generator.

ROCRAND_RNG_PSEUDO_XORWOW 

XORWOW pseudorandom generator.

ROCRAND_RNG_PSEUDO_MRG32K3A 

MRG32k3a pseudorandom generator.

ROCRAND_RNG_PSEUDO_MTGP32 

Mersenne Twister MTGP32 pseudorandom generator.

ROCRAND_RNG_PSEUDO_PHILOX4_32_10 

PHILOX-4x32-10 pseudorandom generator.

ROCRAND_RNG_PSEUDO_MRG31K3P 

MRG31k3p pseudorandom generator.

ROCRAND_RNG_PSEUDO_LFSR113 

LFSR113 pseudorandom generator.

ROCRAND_RNG_PSEUDO_MT19937 

Mersenne Twister MT19937 pseudorandom generator.

ROCRAND_RNG_PSEUDO_THREEFRY2_32_20 

ThreeFry 32 bit state size 2 pseudorandom generator.

ROCRAND_RNG_PSEUDO_THREEFRY2_64_20 

ThreeFry 64 bit state size 2 pseudorandom generator.

ROCRAND_RNG_PSEUDO_THREEFRY4_32_20 

ThreeFry 32 bit state size 4 pseudorandom generator.

ROCRAND_RNG_PSEUDO_THREEFRY4_64_20 

ThreeFry 64 bit state size 4 pseudorandom generator.

ROCRAND_RNG_QUASI_DEFAULT 

Default quasirandom generator.

ROCRAND_RNG_QUASI_SOBOL32 

Sobol32 quasirandom generator.

ROCRAND_RNG_QUASI_SCRAMBLED_SOBOL32 

Scrambled Sobol32 quasirandom generator.

ROCRAND_RNG_QUASI_SOBOL64 

Sobol64 quasirandom generator.

ROCRAND_RNG_QUASI_SCRAMBLED_SOBOL64 

Scrambled Sobol64 quasirandom generator.

◆ rocrand_status

enum rocrand_status

rocRAND function call status type

Enumerator
ROCRAND_STATUS_SUCCESS 

No errors.

ROCRAND_STATUS_VERSION_MISMATCH 

Header file and linked library version do not match.

ROCRAND_STATUS_NOT_CREATED 

Generator was not created using rocrand_create_generator.

ROCRAND_STATUS_ALLOCATION_FAILED 

Memory allocation failed during execution.

ROCRAND_STATUS_TYPE_ERROR 

Generator type is wrong.

ROCRAND_STATUS_OUT_OF_RANGE 

Argument out of range.

ROCRAND_STATUS_LENGTH_NOT_MULTIPLE 

Requested size is not a multiple of quasirandom generator's dimension, or requested size is not even (see rocrand_generate_normal()), or pointer is misaligned (see rocrand_generate_normal())

ROCRAND_STATUS_DOUBLE_PRECISION_REQUIRED 

GPU does not have double precision.

ROCRAND_STATUS_LAUNCH_FAILURE 

Kernel launch failure.

ROCRAND_STATUS_INTERNAL_ERROR 

Internal library error.

Function Documentation

◆ rocrand_create_discrete_distribution()

rocrand_status ROCRANDAPI rocrand_create_discrete_distribution ( const double *  probabilities,
unsigned int  size,
unsigned int  offset,
rocrand_discrete_distribution *  discrete_distribution 
)

Construct the histogram for a custom discrete distribution.

Construct the histogram for the discrete distribution of size 32-bit unsigned integers from the range [offset, offset + size) using probabilities as probabilities.

Parameters
probabilities- probabilities of the the distribution in host memory
size- size of probabilities
offset- offset of values
discrete_distribution- pointer to the histogram in device memory
Returns
  • ROCRAND_STATUS_ALLOCATION_FAILED if memory could not be allocated
  • ROCRAND_STATUS_OUT_OF_RANGE if discrete_distribution pointer was null
  • ROCRAND_STATUS_OUT_OF_RANGE if size was zero
  • ROCRAND_STATUS_SUCCESS if the histogram was constructed successfully

◆ rocrand_create_generator()

rocrand_status ROCRANDAPI rocrand_create_generator ( rocrand_generator *  generator,
rocrand_rng_type  rng_type 
)

Creates a new random number generator.

Creates a new pseudo random number generator of type rng_type and returns it in generator.

Values for rng_type are:

  • ROCRAND_RNG_PSEUDO_XORWOW
  • ROCRAND_RNG_PSEUDO_MRG31K3P
  • ROCRAND_RNG_PSEUDO_MRG32K3A
  • ROCRAND_RNG_PSEUDO_MTGP32
  • ROCRAND_RNG_PSEUDO_PHILOX4_32_10
  • ROCRAND_RNG_PSEUDO_LFSR113
  • ROCRAND_RNG_PSEUDO_THREEFRY2_32_20
  • ROCRAND_RNG_PSEUDO_THREEFRY2_64_20
  • ROCRAND_RNG_PSEUDO_THREEFRY4_32_20
  • ROCRAND_RNG_PSEUDO_THREEFRY4_64_20
  • ROCRAND_RNG_QUASI_SOBOL32
  • ROCRAND_RNG_QUASI_SCRAMBLED_SOBOL32
  • ROCRAND_RNG_QUASI_SOBOL64
  • ROCRAND_RNG_QUASI_SCRAMBLED_SOBOL64
Parameters
generator- Pointer to generator
rng_type- Type of generator to create
Returns
  • ROCRAND_STATUS_ALLOCATION_FAILED, if memory could not be allocated
  • ROCRAND_STATUS_VERSION_MISMATCH if the header file version does not match the dynamically linked library version
  • ROCRAND_STATUS_TYPE_ERROR if the value for rng_type is invalid
  • ROCRAND_STATUS_SUCCESS if generator was created successfully

◆ rocrand_create_generator_host()

rocrand_status ROCRANDAPI rocrand_create_generator_host ( rocrand_generator *  generator,
rocrand_rng_type  rng_type 
)

Creates a new host random number generator.

Creates a new pseudo random number generator of type rng_type and returns it in generator. This generator is executed on the host rather than on a device, and it is enqueued on the stream associated with the generator.

All generators are supported.

Parameters
generator- Pointer to generator
rng_type- Type of generator to create
Returns
  • ROCRAND_STATUS_ALLOCATION_FAILED, if memory could not be allocated
  • ROCRAND_STATUS_VERSION_MISMATCH if the header file version does not match the dynamically linked library version
  • ROCRAND_STATUS_TYPE_ERROR if the value for rng_type is invalid
  • ROCRAND_STATUS_SUCCESS if generator was created successfully

◆ rocrand_create_poisson_distribution()

rocrand_status ROCRANDAPI rocrand_create_poisson_distribution ( double  lambda,
rocrand_discrete_distribution *  discrete_distribution 
)

Construct the histogram for a Poisson distribution.

Construct the histogram for the Poisson distribution with lambda lambda.

Parameters
lambda- lambda for the Poisson distribution
discrete_distribution- pointer to the histogram in device memory
Returns
  • ROCRAND_STATUS_ALLOCATION_FAILED if memory could not be allocated
  • ROCRAND_STATUS_OUT_OF_RANGE if discrete_distribution pointer was null
  • ROCRAND_STATUS_OUT_OF_RANGE if lambda is non-positive
  • ROCRAND_STATUS_SUCCESS if the histogram was constructed successfully

◆ rocrand_destroy_discrete_distribution()

rocrand_status ROCRANDAPI rocrand_destroy_discrete_distribution ( rocrand_discrete_distribution  discrete_distribution)

Destroy the histogram array for a discrete distribution.

Destroy the histogram array for a discrete distribution created by rocrand_create_poisson_distribution.

Parameters
discrete_distribution- pointer to the histogram in device memory
Returns
  • ROCRAND_STATUS_OUT_OF_RANGE if discrete_distribution was null
  • ROCRAND_STATUS_SUCCESS if the histogram was destroyed successfully

◆ rocrand_destroy_generator()

rocrand_status ROCRANDAPI rocrand_destroy_generator ( rocrand_generator  generator)

Destroys random number generator.

Destroys random number generator and frees related memory.

Parameters
generator- Generator to be destroyed
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_SUCCESS if generator was destroyed successfully

◆ rocrand_generate()

rocrand_status ROCRANDAPI rocrand_generate ( rocrand_generator  generator,
unsigned int *  output_data,
size_t  n 
)

Generates uniformly distributed 32-bit unsigned integers.

Generates n uniformly distributed 32-bit unsigned integers and saves them to output_data.

Generated numbers are between 0 and 2^32, including 0 and excluding 2^32.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of 32-bit unsigned integers to generate
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_char()

rocrand_status ROCRANDAPI rocrand_generate_char ( rocrand_generator  generator,
unsigned char *  output_data,
size_t  n 
)

Generates uniformly distributed 8-bit unsigned integers.

Generates n uniformly distributed 8-bit unsigned integers and saves them to output_data.

Generated numbers are between 0 and 2^8, including 0 and excluding 2^8.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of 8-bit unsigned integers to generate
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_log_normal()

rocrand_status ROCRANDAPI rocrand_generate_log_normal ( rocrand_generator  generator,
float *  output_data,
size_t  n,
float  mean,
float  stddev 
)

Generates log-normally distributed float values.

Generates n log-normally distributed 32-bit floating-point values and saves them to output_data.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of floats to generate
mean- Mean value of log normal distribution
stddev- Standard deviation value of log normal distribution
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_log_normal_double()

rocrand_status ROCRANDAPI rocrand_generate_log_normal_double ( rocrand_generator  generator,
double *  output_data,
size_t  n,
double  mean,
double  stddev 
)

Generates log-normally distributed double values.

Generates n log-normally distributed 64-bit double-precision floating-point values and saves them to output_data.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of doubles to generate
mean- Mean value of log normal distribution
stddev- Standard deviation value of log normal distribution
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_log_normal_half()

rocrand_status ROCRANDAPI rocrand_generate_log_normal_half ( rocrand_generator  generator,
half *  output_data,
size_t  n,
half  mean,
half  stddev 
)

Generates log-normally distributed half values.

Generates n log-normally distributed 16-bit half-precision floating-point values and saves them to output_data.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of halfs to generate
mean- Mean value of log normal distribution
stddev- Standard deviation value of log normal distribution
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_long_long()

rocrand_status ROCRANDAPI rocrand_generate_long_long ( rocrand_generator  generator,
unsigned long long int *  output_data,
size_t  n 
)

Generates uniformly distributed 64-bit unsigned integers.

Generates n uniformly distributed 64-bit unsigned integers and saves them to output_data.

Generated numbers are between 0 and 2^64, including 0 and excluding 2^64.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of 64-bit unsigned integers to generate
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_TYPE_ERROR if the generator can't natively generate 64-bit random numbers
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_normal()

rocrand_status ROCRANDAPI rocrand_generate_normal ( rocrand_generator  generator,
float *  output_data,
size_t  n,
float  mean,
float  stddev 
)

Generates normally distributed float values.

Generates n normally distributed distributed 32-bit floating-point values and saves them to output_data.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of floats to generate
mean- Mean value of normal distribution
stddev- Standard deviation value of normal distribution
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_normal_double()

rocrand_status ROCRANDAPI rocrand_generate_normal_double ( rocrand_generator  generator,
double *  output_data,
size_t  n,
double  mean,
double  stddev 
)

Generates normally distributed double values.

Generates n normally distributed 64-bit double-precision floating-point numbers and saves them to output_data.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of doubles to generate
mean- Mean value of normal distribution
stddev- Standard deviation value of normal distribution
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_normal_half()

rocrand_status ROCRANDAPI rocrand_generate_normal_half ( rocrand_generator  generator,
half *  output_data,
size_t  n,
half  mean,
half  stddev 
)

Generates normally distributed half values.

Generates n normally distributed 16-bit half-precision floating-point numbers and saves them to output_data.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of halfs to generate
mean- Mean value of normal distribution
stddev- Standard deviation value of normal distribution
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_poisson()

rocrand_status ROCRANDAPI rocrand_generate_poisson ( rocrand_generator  generator,
unsigned int *  output_data,
size_t  n,
double  lambda 
)

Generates Poisson-distributed 32-bit unsigned integers.

Generates n Poisson-distributed 32-bit unsigned integers and saves them to output_data.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of 32-bit unsigned integers to generate
lambda- lambda for the Poisson distribution
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_OUT_OF_RANGE if lambda is non-positive
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_short()

rocrand_status ROCRANDAPI rocrand_generate_short ( rocrand_generator  generator,
unsigned short *  output_data,
size_t  n 
)

Generates uniformly distributed 16-bit unsigned integers.

Generates n uniformly distributed 16-bit unsigned integers and saves them to output_data.

Generated numbers are between 0 and 2^16, including 0 and excluding 2^16.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of 16-bit unsigned integers to generate
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_uniform()

rocrand_status ROCRANDAPI rocrand_generate_uniform ( rocrand_generator  generator,
float *  output_data,
size_t  n 
)

Generates uniformly distributed float values.

Generates n uniformly distributed 32-bit floating-point values and saves them to output_data.

Generated numbers are between 0.0f and 1.0f, excluding 0.0f and including 1.0f.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of floats to generate
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_uniform_double()

rocrand_status ROCRANDAPI rocrand_generate_uniform_double ( rocrand_generator  generator,
double *  output_data,
size_t  n 
)

Generates uniformly distributed double-precision floating-point values.

Generates n uniformly distributed 64-bit double-precision floating-point values and saves them to output_data.

Generated numbers are between 0.0 and 1.0, excluding 0.0 and including 1.0.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of doubles to generate
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_generate_uniform_half()

rocrand_status ROCRANDAPI rocrand_generate_uniform_half ( rocrand_generator  generator,
half *  output_data,
size_t  n 
)

Generates uniformly distributed half-precision floating-point values.

Generates n uniformly distributed 16-bit half-precision floating-point values and saves them to output_data.

Generated numbers are between 0.0 and 1.0, excluding 0.0 and including 1.0.

Parameters
generator- Generator to use
output_data- Pointer to memory to store generated numbers
n- Number of halfs to generate
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasi-random generator
  • ROCRAND_STATUS_SUCCESS if random numbers were successfully generated

◆ rocrand_get_direction_vectors32()

rocrand_status ROCRANDAPI rocrand_get_direction_vectors32 ( const unsigned int **  vectors,
rocrand_direction_vector_set  set 
)

Get the vector for 32-bit (scrambled-)sobol generation.

Parameters
vectors- location where to write the vector pointer to
set- which direction vector set to use
Returns
  • ROCRAND_STATUS_OUT_OF_RANGE if set was invalid for this method
  • ROCRAND_STATUS_SUCCESS if the pointer was set succesfully

◆ rocrand_get_direction_vectors64()

rocrand_status ROCRANDAPI rocrand_get_direction_vectors64 ( const unsigned long long **  vectors,
rocrand_direction_vector_set  set 
)

Get the vector for 64-bit (scrambled-)sobol generation.

Parameters
vectors- location where to write the vector pointer to
set- which direction vector set to use
Returns
  • ROCRAND_STATUS_OUT_OF_RANGE if set was invalid for this method
  • ROCRAND_STATUS_SUCCESS if the pointer was set succesfully

◆ rocrand_get_scramble_constants32()

rocrand_status ROCRANDAPI rocrand_get_scramble_constants32 ( const unsigned int **  constants)

Get the scramble constants for 32-bit scrambled sobol generation.

Parameters
constants- location where to write the constants pointer to
Returns
  • ROCRAND_STATUS_SUCCESS if the pointer was set succesfully

◆ rocrand_get_scramble_constants64()

rocrand_status ROCRANDAPI rocrand_get_scramble_constants64 ( const unsigned long long **  constants)

Get the scramble constants for 64-bit scrambled sobol generation.

Parameters
constants- location where to write the constants pointer to
Returns
  • ROCRAND_STATUS_SUCCESS if the pointer was set succesfully

◆ rocrand_get_version()

rocrand_status ROCRANDAPI rocrand_get_version ( int *  version)

Returns the version number of the library.

Returns in version the version number of the dynamically linked rocRAND library.

Parameters
version- Version of the library
Returns
  • ROCRAND_STATUS_OUT_OF_RANGE if version is NULL
  • ROCRAND_STATUS_SUCCESS if the version number was successfully returned

◆ rocrand_initialize_generator()

rocrand_status ROCRANDAPI rocrand_initialize_generator ( rocrand_generator  generator)

Initializes the generator's state on GPU or host.

Initializes the generator's state on GPU or host. User it not required to call this function before using a generator.

If rocrand_initialize() was not called for a generator, it will be automatically called by functions which generates random numbers like rocrand_generate(), rocrand_generate_uniform() etc.

Parameters
generator- Generator to initialize
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_LAUNCH_FAILURE if a HIP kernel launch failed
  • ROCRAND_STATUS_SUCCESS if the seeds were generated successfully

◆ rocrand_set_offset()

rocrand_status ROCRANDAPI rocrand_set_offset ( rocrand_generator  generator,
unsigned long long  offset 
)

Sets the offset of a random number generator.

Sets the absolute offset of the random number generator.

  • This operation resets the generator's internal state.
  • This operation does not change the generator's seed.

Absolute offset cannot be set if generator's type is ROCRAND_RNG_PSEUDO_MTGP32 or ROCRAND_RNG_PSEUDO_LFSR113.

Parameters
generator- Random number generator
offset- New absolute offset
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_SUCCESS if offset was successfully set
  • ROCRAND_STATUS_TYPE_ERROR if generator's type is ROCRAND_RNG_PSEUDO_MTGP32 or ROCRAND_RNG_PSEUDO_LFSR113

◆ rocrand_set_ordering()

rocrand_status ROCRANDAPI rocrand_set_ordering ( rocrand_generator  generator,
rocrand_ordering  order 
)

Sets the ordering of a random number generator.

Sets the ordering of the results of a random number generator.

  • This operation resets the generator's internal state.
  • This operation does not change the generator's seed.
Parameters
generator- Random number generator
order- New ordering of results

The ordering choices for pseudorandom sequences are the following. Note that not all generators support all orderings. For details, see the Programmer's Guide in the documentation.

  • ROCRAND_ORDERING_PSEUDO_DEFAULT
  • ROCRAND_ORDERING_PSEUDO_LEGACY
  • ROCRAND_ORDERING_PSEUDO_BEST
  • ROCRAND_ORDERING_PSEUDO_SEEDED
  • ROCRAND_ORDERING_PSEUDO_DYNAMIC

For quasirandom sequences there is only one ordering, ROCRAND_ORDERING_QUASI_DEFAULT.

Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_OUT_OF_RANGE if the ordering is not valid
  • ROCRAND_STATUS_SUCCESS if the ordering was successfully set
  • ROCRAND_STATUS_TYPE_ERROR if generator's type is not valid

◆ rocrand_set_quasi_random_generator_dimensions()

rocrand_status ROCRANDAPI rocrand_set_quasi_random_generator_dimensions ( rocrand_generator  generator,
unsigned int  dimensions 
)

Set the number of dimensions of a quasi-random number generator.

Set the number of dimensions of a quasi-random number generator. Supported values of dimensions are 1 to 20000.

  • This operation resets the generator's internal state.
  • This operation does not change the generator's offset.
Parameters
generator- Quasi-random number generator
dimensions- Number of dimensions
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_TYPE_ERROR if the generator is not a quasi-random number generator
  • ROCRAND_STATUS_OUT_OF_RANGE if dimensions is out of range
  • ROCRAND_STATUS_SUCCESS if the number of dimensions was set successfully

◆ rocrand_set_seed()

rocrand_status ROCRANDAPI rocrand_set_seed ( rocrand_generator  generator,
unsigned long long  seed 
)

Sets the seed of a pseudo-random number generator.

Sets the seed of the pseudo-random number generator.

  • This operation resets the generator's internal state.
  • This operation does not change the generator's offset.

For an MRG32K3a or MRG31K3p generator the seed value can't be zero. If seed is equal to zero and generator's type is ROCRAND_RNG_PSEUDO_MRG32K3A or ROCRAND_RNG_PSEUDO_MRG31K3P, value 12345 is used as seed instead.

For a LFSR113 generator seed values must be larger than 1, 7, 15,

  1. The seed upper and lower 32 bits used as first and second seed value. If those values smaller than 2 and/or 8, those are increased with 1 and/or 7.
Parameters
generator- Pseudo-random number generator
seed- New seed value
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_TYPE_ERROR if the generator is a quasi-random number generator
  • ROCRAND_STATUS_SUCCESS if seed was set successfully

◆ rocrand_set_seed_uint4()

rocrand_status ROCRANDAPI rocrand_set_seed_uint4 ( rocrand_generator  generator,
uint4  seed 
)

Sets the seeds of a pseudo-random number generator.

Sets the seed of the pseudo-random number generator. Currently only for LFSR113

  • This operation resets the generator's internal state.
  • This operation does not change the generator's offset.

Only usable for LFSR113.

For a LFSR113 generator seed values must be bigger than 1, 7, 15,

  1. If those values smaller, than the requested minimum values [2, 8, 16, 128], then it will be increased with the minimum values minus 1 [1, 7, 15, 127].
Parameters
generator- Pseudo-random number generator
seed- New seed value
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_TYPE_ERROR if the generator is a quasi-random number generator
  • ROCRAND_STATUS_SUCCESS if seed was set successfully

◆ rocrand_set_stream()

rocrand_status ROCRANDAPI rocrand_set_stream ( rocrand_generator  generator,
hipStream_t  stream 
)

Sets the current stream for kernel launches.

Sets the current stream for all kernel launches of the generator. All functions will use this stream.

Parameters
generator- Generator to modify
stream- Stream to use or NULL for default stream
Returns
  • ROCRAND_STATUS_NOT_CREATED if the generator wasn't created
  • ROCRAND_STATUS_SUCCESS if stream was set successfully