muRAND Host API Reference

muRAND provides pseudorandom and quasirandom number generation for MUSA applications. Pseudorandom generators produce deterministic sequences for statistical simulation, while quasirandom generators produce low-discrepancy point sets for workloads that benefit from more even multidimensional coverage.

muRAND exposes two public programming models: a host-side library-call model and a device-side state-based model. This document describes the host-side model and points to the device reference when in-kernel generation is the better fit.

1. Introduction

1.1 What Is the muRAND Host API

The host API is the library-call programming model in muRAND. The application creates a murandGenerator_t, configures generator behavior on the host, and then calls muRAND routines to fill caller-provided output buffers.

Use this model when random-number generation is a separate stage in the application pipeline and you need explicit control over generator type, seed, offset, ordering, dimensions, stream assignment, or distribution setup. If random values need to be generated and consumed immediately inside device code, see the muRAND Device API Reference.

1.2 Document Scope in MUSA SDK 5.2

This reference describes the muRAND host generator APIs supported in MUSA SDK 5.2. Public declarations that exist in the headers but do not appear in this document are experimental in MUSA SDK 5.2 and are provided for reference only.

1.3 Host Generator Model

The host API uses a murandGenerator_t handle to manage a generator instance. Lifecycle routines create and destroy that handle, generation routines write results to output buffers passed by the caller, generator options control seeds, offsets, ordering, and quasirandom dimensions, and support routines expose direction vectors, scramble constants, and discrete-distribution data needed by specific workflows.

1.4 How to Use This Document

Read Chapter 2 first if you need the high-level host workflow. Chapter 3 then groups the supported functions by creation and configuration, generation routines, distribution support, and direction-vector support.

2. Using the muRAND Host API

2.1 Host-Side Setup and Generator Model

To use the host API, include the public host header murand.h and call the muRAND routines from host code. The central object is murandGenerator_t, which encapsulates the state required to produce a pseudorandom or quasirandom sequence. A generator can then be configured and reused across multiple generation calls.

2.2 Generator Types and Configuration

The host API supports pseudorandom and quasirandom generator types selected through murandCreateGenerator. In this release, the documented generator types are MURAND_RNG_PSEUDO_XORWOW, MURAND_RNG_PSEUDO_MRG32K3A, MURAND_RNG_PSEUDO_MTGP32, MURAND_RNG_PSEUDO_PHILOX4_32_10, MURAND_RNG_QUASI_SOBOL32, MURAND_RNG_QUASI_SCRAMBLED_SOBOL32, MURAND_RNG_QUASI_SOBOL64, and MURAND_RNG_QUASI_SCRAMBLED_SOBOL64.

Configuration routines control seed selection for pseudorandom generators, absolute offsets, result ordering, quasirandom dimensions, and stream assignment. murandSetPseudoRandomGeneratorSeed, murandSetGeneratorOffset, murandSetGeneratorOrdering, and murandSetQuasiRandomGeneratorDimensions reset generator state as described in their function entries. For quasirandom generators, the only ordering in this reference is MURAND_ORDERING_QUASI_DEFAULT. Quasirandom dimensions are 1 to 20,000. For MURAND_RNG_PSEUDO_MTGP32, absolute offset setting is not supported. For MURAND_RNG_PSEUDO_MRG32K3A, a zero seed is replaced with 12345.

2.3 Support Data and Memory Placement

Generation routines write results into caller-provided output buffers. Quasirandom setup routines return direction vectors and scramble constants in host memory. murandGetDirectionVectors32 and murandGetDirectionVectors64 return arrays of 32-bit or 64-bit direction vectors, and murandGetScrambleConstants32 and murandGetScrambleConstants64 return matching scramble constants in host memory.

The supported host-side setup routines bridge host and device workflows. murandGetDirectionVectors32, murandGetDirectionVectors64, murandGetScrambleConstants32, and murandGetScrambleConstants64 provide the Sobol and scrambled Sobol setup material used by device-side workflows. murandCreatePoissonDistribution and murandDestroyDistribution operate on the corresponding device-memory histogram objects for Poisson workflows.

2.4 Typical Workflow

The normal host-side workflow is:

1. Create a generator with murandCreateGenerator.
2. Choose the generator type that matches the workload.
3. Apply any required configuration, such as seed, offset, ordering, dimensions, or stream.
4. Retrieve direction vectors or scramble constants for quasirandom workflows, or create a distribution histogram for discrete or Poisson workflows when needed.
5. Optionally call murandGenerateSeeds. If it is not called explicitly, generation routines initialize state automatically when needed.
6. Call one of the murandGenerate* routines to fill the output buffer.
7. Reuse the same generator for additional generation calls with the same or updated configuration.
8. Call murandDestroyGenerator when the generator is no longer needed.

2.5 Execution and Length Constraints

murandSetStream assigns the stream used for all kernel launches issued by a generator. Generation routines and murandGenerateSeeds can report MURAND_STATUS_LAUNCH_FAILURE, so they should be treated as execution operations rather than pure host-side bookkeeping calls.

For quasirandom generators, generation length constraints apply. Requests can fail with MURAND_STATUS_LENGTH_NOT_MULTIPLE when n is not a multiple of the generator dimension. Additional constraints depend on the routine; for example, murandGeneratePoisson requires a positive lambda.

2.6 Return Values

The host functions in this reference return murandStatus_t. Each function entry lists the exact status values that apply to that routine.

3. Host API Reference

3.1 Generator Creation and Configuration

3.1.1 murandCreateGenerator

murandStatus_t murandCreateGenerator(murandGenerator_t *generator, murandRngType_t rng_type)

Description

• Creates a new random number generator.
• Creates a new pseudorandom number generator of type rng_type and returns it in generator.
• Values for rng_type are: MURAND_RNG_PSEUDO_XORWOW MURAND_RNG_PSEUDO_MRG32K3A MURAND_RNG_PSEUDO_MTGP32 MURAND_RNG_PSEUDO_PHILOX4_32_10 MURAND_RNG_QUASI_SOBOL32 MURAND_RNG_QUASI_SCRAMBLED_SOBOL32 MURAND_RNG_QUASI_SOBOL64 MURAND_RNG_QUASI_SCRAMBLED_SOBOL64

Parameters

• generator (murandGenerator_t *): Pointer to generator
• rng_type (murandRngType_t): Type of generator to create

Returns

• MURAND_STATUS_ALLOCATION_FAILED, if memory could not be allocated MURAND_STATUS_VERSION_MISMATCH if the header file version does not match the dynamically linked library version MURAND_STATUS_TYPE_ERROR if the value for rng_type is invalid MURAND_STATUS_SUCCESS if generator was created successfully

3.1.2 murandDestroyGenerator

murandStatus_t murandDestroyGenerator(murandGenerator_t generator)

Description

• Destroys a random number generator and frees related memory.

Parameters

• generator (murandGenerator_t): Generator to destroy

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_SUCCESS if generator was destroyed successfully

3.1.3 murandGenerateSeeds

murandStatus_t murandGenerateSeeds(murandGenerator_t generator)

Description

• Initializes the generator's state on GPU or host.
• Initializes the generator's state on GPU or host. It is not required to call this function before using a generator.
• If murand_initialize() was not called for a generator, it will be automatically called by functions that generate random numbers such as murandGenerate().

Parameters

• generator (murandGenerator_t): Generator to initialize

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_SUCCESS if the seeds were generated successfully

3.1.4 murandGetVersion

murandStatus_t murandGetVersion(int *version)

Description

• Returns the version number of the library.
• Returns the version number of the dynamically linked muRAND library in version.

Parameters

• version (int *): Version of the library

Returns

• MURAND_STATUS_OUT_OF_RANGE if version is NULL MURAND_STATUS_SUCCESS if the version number was successfully returned

3.1.5 murandSetGeneratorOffset

murandStatus_t murandSetGeneratorOffset(murandGenerator_t generator, unsigned long long offset)

Description

• Sets the offset of a random number generator.
• Sets the absolute offset of the random number generator.
• This operation resets the generator state. It does not change the generator seed.
• Absolute offset cannot be set if generator's type is MURAND_RNG_PSEUDO_MTGP32.

Parameters

• generator (murandGenerator_t): Random number generator
• offset (unsigned long long): New absolute offset

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_SUCCESS if offset was successfully set MURAND_STATUS_TYPE_ERROR if generator's type is MURAND_RNG_PSEUDO_MTGP32

3.1.6 murandSetGeneratorOrdering

murandStatus_t murandSetGeneratorOrdering(murandGenerator_t generator, murandOrdering_t order)

Description

• Sets the ordering of a random number generator.
• Sets the ordering of the results of a random number generator.
• This operation resets the generator state. It does not change the generator seed.
• For quasirandom sequences there is only one ordering, MURAND_ORDERING_QUASI_DEFAULT.

Parameters

• generator (murandGenerator_t): Random number generator
• order (murandOrdering_t): New ordering of results

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_OUT_OF_RANGE if the ordering is not valid MURAND_STATUS_SUCCESS if the ordering was successfully set MURAND_STATUS_TYPE_ERROR if generator's type is not valid

3.1.7 murandSetPseudoRandomGeneratorSeed

murandStatus_t murandSetPseudoRandomGeneratorSeed(murandGenerator_t generator, unsigned long long seed)

Description

• Sets the seed of a pseudorandom number generator.
• Sets the seed of the pseudorandom number generator.
• This operation resets the generator state. It does not change the generator offset.
• For a MRG32K3a generator seed value can't be zero. If seed is equal zero and generator's type is MURAND_RNG_PSEUDO_MRG32K3A, value 12345 is used as a seed instead.

Parameters

• generator (murandGenerator_t): Pseudo-random number generator
• seed (unsigned long long): New seed value

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_TYPE_ERROR if the generator is a quasirandom number generator MURAND_STATUS_SUCCESS if seed was set successfully

3.1.8 murandSetQuasiRandomGeneratorDimensions

murandStatus_t murandSetQuasiRandomGeneratorDimensions(murandGenerator_t generator, unsigned int dimensions)

Description

• Sets the number of dimensions of a quasirandom number generator.
• Sets the number of dimensions of a quasirandom number generator. Supported values of dimensions are 1 to 20000.
• This operation resets the generator state. It does not change the generator offset.

Parameters

• generator (murandGenerator_t): Quasi-random number generator
• dimensions (unsigned int): Number of dimensions

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_TYPE_ERROR if the generator is not a quasirandom number generator MURAND_STATUS_OUT_OF_RANGE if dimensions is out of range MURAND_STATUS_SUCCESS if the number of dimensions was set successfully

3.1.9 murandSetStream

murandStatus_t murandSetStream(murandGenerator_t generator, MUstream stream)

Description

• 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 (murandGenerator_t): Generator to modify
• stream (MUstream): Stream to use or NULL for default stream

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_SUCCESS if stream was set successfully

3.2 Integer and Uniform Generation

3.2.1 murandGenerate

murandStatus_t murandGenerate(murandGenerator_t generator, unsigned int *output_data, size_t n)

Description

• 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 (murandGenerator_t): Generator to use
• output_data (unsigned int *): Pointer to memory to store generated numbers
• n (size_t): Number of 32-bit unsigned integers to generate

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.2.2 murandGenerateLongLong

murandStatus_t murandGenerateLongLong(murandGenerator_t generator, unsigned long long int *output_data, size_t n)

Description

• 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 (murandGenerator_t): Generator to use
• output_data (unsigned long long int *): Pointer to memory to store generated numbers
• n (size_t): Number of 64-bit unsigned integers to generate

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a kernel launch failed MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_TYPE_ERROR if the generator can't natively generate 64-bit random numbers MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.2.3 murandGenerateUniform

murandStatus_t murandGenerateUniform(murandGenerator_t generator, float *output_data, size_t n)

Description

• 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 (murandGenerator_t): Generator to use
• output_data (float *): Pointer to memory to store generated numbers
• n (size_t): Number of floats to generate

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.2.4 murandGenerateUniformDouble

murandStatus_t murandGenerateUniformDouble(murandGenerator_t generator, double *output_data, size_t n)

Description

• 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 (murandGenerator_t): Generator to use
• output_data (double *): Pointer to memory to store generated numbers
• n (size_t): Number of doubles to generate

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.3 Normal and Log-Normal Generation

3.3.1 murandGenerateNormal

murandStatus_t murandGenerateNormal(murandGenerator_t generator, float *output_data, size_t n, float mean, float stddev)

Description

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

Parameters

• generator (murandGenerator_t): Generator to use
• output_data (float *): Pointer to memory to store generated numbers
• n (size_t): Number of floats to generate
• mean (float): Mean value of normal distribution
• stddev (float): Standard deviation value of normal distribution

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.3.2 murandGenerateNormalDouble

murandStatus_t murandGenerateNormalDouble(murandGenerator_t generator, double *output_data, size_t n, double mean, double stddev)

Description

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

Parameters

• generator (murandGenerator_t): Generator to use
• output_data (double *): Pointer to memory to store generated numbers
• n (size_t): Number of doubles to generate
• mean (double): Mean value of normal distribution
• stddev (double): Standard deviation value of normal distribution

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.3.3 murandGenerateLogNormal

murandStatus_t murandGenerateLogNormal(murandGenerator_t generator, float *output_data, size_t n, float mean, float stddev)

Description

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

Parameters

• generator (murandGenerator_t): Generator to use
• output_data (float *): Pointer to memory to store generated numbers
• n (size_t): Number of floats to generate
• mean (float): Mean value of log normal distribution
• stddev (float): Standard deviation value of log normal distribution

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.3.4 murandGenerateLogNormalDouble

murandStatus_t murandGenerateLogNormalDouble(murandGenerator_t generator, double *output_data, size_t n, double mean, double stddev)

Description

• 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 (murandGenerator_t): Generator to use
• output_data (double *): Pointer to memory to store generated numbers
• n (size_t): Number of doubles to generate
• mean (double): Mean value of log normal distribution
• stddev (double): Standard deviation value of log normal distribution

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.4 Poisson and Discrete Distribution Support

3.4.1 murandGeneratePoisson

murandStatus_t murandGeneratePoisson(murandGenerator_t generator, unsigned int *output_data, size_t n, double lambda)

Description

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

Parameters

• generator (murandGenerator_t): Generator to use
• output_data (unsigned int *): Pointer to memory to store generated numbers
• n (size_t): Number of 32-bit unsigned integers to generate
• lambda (double): lambda for the Poisson distribution

Returns

• MURAND_STATUS_NOT_INITIALIZED if the generator wasn't created MURAND_STATUS_LAUNCH_FAILURE if a MUSA kernel launch failed MURAND_STATUS_OUT_OF_RANGE if lambda is non-positive MURAND_STATUS_LENGTH_NOT_MULTIPLE if n is not a multiple of the dimension of used quasirandom generator MURAND_STATUS_SUCCESS if random numbers were successfully generated

3.4.2 murandCreatePoissonDistribution

murandStatus_t murandCreatePoissonDistribution(double lambda, murandDiscreteDistribution_t *discrete_distribution)

Description

• Constructs the histogram for a Poisson distribution.
• Constructs the histogram for the Poisson distribution with lambda lambda.

Parameters

• lambda (double): lambda for the Poisson distribution
• discrete_distribution (murandDiscreteDistribution_t *): pointer to the histogram in device memory

Returns

• MURAND_STATUS_ALLOCATION_FAILED if memory could not be allocated MURAND_STATUS_OUT_OF_RANGE if discrete_distribution pointer was null MURAND_STATUS_OUT_OF_RANGE if lambda is non-positive MURAND_STATUS_SUCCESS if the histogram was constructed successfully

3.4.3 murandDestroyDistribution

murandStatus_t murandDestroyDistribution(murandDiscreteDistribution_t discrete_distribution)

Description

• Destroy the histogram array for a discrete distribution.
• Destroy the histogram array for a discrete distribution created by murandCreatePoissonDistribution.

Parameters

• discrete_distribution (murandDiscreteDistribution_t): pointer to the histogram in device memory

Returns

• MURAND_STATUS_OUT_OF_RANGE if discrete_distribution was null MURAND_STATUS_SUCCESS if the histogram was destroyed successfully

3.5 Direction Vector and Scramble Constant Support

3.5.1 murandGetDirectionVectors32

murandStatus_t murandGetDirectionVectors32(murandDirectionVectors32_t *vectors[], murandDirectionVectorSet_t set)

Description

• Get direction vectors for 32-bit quasirandom number generation.
• Get a pointer to an array of direction vectors that can be used for quasirandom number generation. The resulting pointer will reference an array of direction vectors in host memory.
• The array contains vectors for many dimensions. Each dimension has 32 vectors. Each individual vector is an unsigned int.
• Legal values for set are: MURAND_DIRECTION_VECTORS_32_JOEKUO6 (20,000 dimensions) MURAND_SCRAMBLED_DIRECTION_VECTORS_32_JOEKUO6 (20,000 dimensions)

Parameters

• vectors (murandDirectionVectors32_t *): Address of pointer in which to return direction vectors
• set (murandDirectionVectorSet_t): Which set of direction vectors to use

Returns

• MURAND_STATUS_OUT_OF_RANGE if the choice of set is invalid MURAND_STATUS_SUCCESS if the pointer was set successfully

3.5.2 murandGetDirectionVectors64

murandStatus_t murandGetDirectionVectors64(murandDirectionVectors64_t *vectors[], murandDirectionVectorSet_t set)

Description

• Get direction vectors for 64-bit quasirandom number generation.
• Get a pointer to an array of direction vectors that can be used for quasirandom number generation. The resulting pointer will reference an array of direction vectors in host memory.
• The array contains vectors for many dimensions. Each dimension has 64 vectors. Each individual vector is an unsigned long long.
• Legal values for set are: MURAND_DIRECTION_VECTORS_64_JOEKUO6 (20,000 dimensions) MURAND_SCRAMBLED_DIRECTION_VECTORS_64_JOEKUO6 (20,000 dimensions)

Parameters

• vectors (murandDirectionVectors64_t *): Address of pointer in which to return direction vectors
• set (murandDirectionVectorSet_t): Which set of direction vectors to use

Returns

• MURAND_STATUS_OUT_OF_RANGE if the choice of set is invalid MURAND_STATUS_SUCCESS if the pointer was set successfully

3.5.3 murandGetScrambleConstants32

murandStatus_t murandGetScrambleConstants32(unsigned int **constants)

Description

• Gets scramble constants for 32-bit scrambled Sobol' generation.
• Gets a pointer to an array of scramble constants that can be used for quasirandom number generation. The resulting pointer references an array of unsigned int values in host memory.
• The array contains constants for many dimensions. Each dimension has a single unsigned int constant.

Parameters

• constants (unsigned int **): Address of pointer in which to return scramble constants

Returns

• MURAND_STATUS_SUCCESS if the pointer was set successfully

3.5.4 murandGetScrambleConstants64

murandStatus_t murandGetScrambleConstants64(unsigned long long **constants)

Description

• Gets scramble constants for 64-bit scrambled Sobol' generation.
• Gets a pointer to an array of scramble constants that can be used for quasirandom number generation. The resulting pointer references an array of unsigned long long values in host memory.
• The array contains constants for many dimensions. Each dimension has a single unsigned long long constant.

Parameters

• constants (unsigned long long **): Address of pointer in which to return scramble constants

Returns

• MURAND_STATUS_SUCCESS if the pointer was set successfully