Skip to main content
`Ctrl`+`K`

# rocRAND host API

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

## Macros

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

## 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.
rocrand_status ROCRANDAPI | rocrand_create_generator_host (rocrand_generator *generator, rocrand_rng_type rng_type)
| Creates a new host random number generator.
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.
rocrand_status ROCRANDAPI | rocrand_generate (rocrand_generator generator, unsigned int *output_data, size_t n)
| Generates uniformly distributed 32-bit unsigned integers.
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.
rocrand_status ROCRANDAPI | rocrand_generate_char (rocrand_generator generator, unsigned char *output_data, size_t n)
| Generates uniformly distributed 8-bit unsigned integers.
rocrand_status ROCRANDAPI | rocrand_generate_short (rocrand_generator generator, unsigned short *output_data, size_t n)
| Generates uniformly distributed 16-bit unsigned integers.
rocrand_status ROCRANDAPI | rocrand_generate_uniform (rocrand_generator generator, float *output_data, size_t n)
| Generates uniformly distributed `float` values.
rocrand_status ROCRANDAPI | rocrand_generate_uniform_double (rocrand_generator generator, double *output_data, size_t n)
| Generates uniformly distributed double-precision floating-point values.
rocrand_status ROCRANDAPI | rocrand_generate_uniform_half (rocrand_generator generator, half *output_data, size_t n)
| Generates uniformly distributed half-precision floating-point values.
rocrand_status ROCRANDAPI | rocrand_generate_normal (rocrand_generator generator, float *output_data, size_t n, float mean, float stddev)
| Generates normally distributed `float` values.
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.
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.
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.
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.
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.
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.
rocrand_status ROCRANDAPI | rocrand_initialize_generator (rocrand_generator generator)
| Initializes the generator's state on GPU or host.
rocrand_status ROCRANDAPI | rocrand_set_stream (rocrand_generator generator, hipStream_t stream)
| Sets the current stream for kernel launches.
rocrand_status ROCRANDAPI | rocrand_set_seed (rocrand_generator generator, unsigned long long seed)
| Sets the seed of a pseudo-random number generator.
rocrand_status ROCRANDAPI | rocrand_set_seed_uint4 (rocrand_generator generator, uint4 seed)
| Sets the seeds of a pseudo-random number generator.
rocrand_status ROCRANDAPI | rocrand_set_offset (rocrand_generator generator, unsigned long long offset)
| Sets the offset of a random number generator.
rocrand_status ROCRANDAPI | rocrand_set_ordering (rocrand_generator generator, rocrand_ordering order)
| Sets the ordering of a random number generator.
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.
rocrand_status ROCRANDAPI | rocrand_get_version (int *version)
| Returns the version number of the library.
rocrand_status ROCRANDAPI | rocrand_create_poisson_distribution (double lambda, rocrand_discrete_distribution *discrete_distribution)
| Construct the histogram for a Poisson 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.
rocrand_status ROCRANDAPI | rocrand_destroy_discrete_distribution (rocrand_discrete_distribution discrete_distribution)
| Destroy the histogram array for a discrete distribution.
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.
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.
rocrand_status ROCRANDAPI | rocrand_get_scramble_constants32 (const unsigned int **constants)
| Get the scramble constants for 32-bit scrambled sobol generation.
rocrand_status ROCRANDAPI | rocrand_get_scramble_constants64 (const unsigned long long **constants)
| Get the scramble constants for 64-bit scrambled sobol generation.

## 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