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

To search the API, refer to the API :ref:`genindex`.

To use the device API, include the file rocrand_kernel.h in files that define kernels that use rocRAND device functions. Follow these steps to use the device functions in the device kernel definition:

1. Create a new generator state object of the desired generator type.
2. Initialize the generator state parameters using rocrand_init.
3. Generate random numbers by calling the generation function on the generator state.
4. Use the results.

The rocRAND device functions are invoked from inside the user kernel. This means the generated numbers can be used immediately in the kernel without copying them to the host memory.

In the following example, random number generation uses the XORWOW generator.

#include <hip/hip_runtime.h>
#include <rocrand/rocrand_kernel.h>

__global__
void test()
{
    uint                 tid = blockDim.x * blockIdx.x + threadIdx.x;
    rocrand_state_xorwow state;
    rocrand_init(123, tid, 0, &state);

    for(int i = 0; i < 3; ++i)
    {
        const auto value = rocrand(&state);
        printf("thread %d, index %u: %u\n", tid, i, value);
    }
}

int main()
{
    test<<<dim3(1), dim3(32)>>>();
    hipDeviceSynchronize();
}

.. doxygengroup:: rocranddevice

The C host API allows encapsulation of the internal generator state. Random numbers can be produced either on the host or device, depending on the created generator object. The typical sequence of operations for device generation consists of the following steps:

1. Allocate memory on the device with hipMalloc.
2. Create a new generator of the desired type with rocrand_create_generator.
3. Set the generator options, for example, use rocrand_set_seed to set the seed.
4. Generate random numbers with rocrand_generate or another generation function.
5. Use the results.
6. Clean up with rocrand_destroy_generator and hipFree.

To generate random numbers on the host, allocate the memory in the first step using a host memory allocation call. In step two, call rocrand_create_generator_host instead. In the last step, release the appropriate memory using rocrand_destroy_generator. All other calls work identically whether you are generating random numbers on the device or on the host CPU.

The example below uses the C host API to generate ten random floats using GPU capabilities.

#include <hip/hip_runtime.h>
#include <rocrand.h>
#include <stdio.h>

int main()
{
    size_t n = 10;

    rocrand_generator gen;
    float *           d_rand, *h_rand;

    h_rand = (float*)malloc(sizeof(float) * n);
    hipMalloc((void**)&d_rand, n * sizeof(float));

    rocrand_create_generator(&gen, ROCRAND_RNG_PSEUDO_DEFAULT);
    rocrand_set_seed(gen, 123);
    rocrand_generate_uniform(gen, d_rand, n);

    hipMemcpy(h_rand, d_rand, n * sizeof(float), hipMemcpyDeviceToHost);

    for(int i = 0; i < n; i++)
    {
        printf("%f\n", h_rand[i]);
    }

    rocrand_destroy_generator(gen);
    hipFree(d_rand);

    return 0;
}

.. doxygengroup:: rocrandhost

The C++ host API wrapper provides resource management and an object-oriented interface for random number generation facilities.

The example below uses the C++ host API wrapper to produce a random number using the default generation parameters.

#include <hip/hip_runtime.h>
#include <rocrand/rocrand.hpp>

#include <iostream>

int main()
{
    float* d_rand;
    float  h_rand;
    hipMalloc((void**)&d_rand, sizeof(float));

    rocrand_cpp::xorwow                gen;
    rocrand_cpp::normal_distribution<> dist;

    dist(gen, d_rand, 1);

    hipMemcpy(&h_rand, d_rand, sizeof(float), hipMemcpyDeviceToHost);

    std::cout << h_rand << std::endl;

    hipFree(d_rand);

    return 0;
}

.. doxygengroup:: rocrandhostcpp