Template of the specialized interface for specific generators (not to be included as is!) More...

#include <clRNG.h>
#include <stdio.h>

Data Structures
struct	clrngStreamState
	Stream state [device]. More...

struct	clrngStream
	Stream object [device]. More...

struct	clrngHostStream
	Host stream object [device-only]. More...

struct	clrngStreamCreator
	Stream creator object. More...

Functions
Stream Creators
Functions to create, destroy and modify stream creator objects (factory pattern).
clrngStreamCreator *	clrngCopyStreamCreator (const clrngStreamCreator creator, clrngStatus err)
	Duplicate an existing stream creator object. More...

clrngStatus	clrngDestroyStreamCreator (clrngStreamCreator *creator)
	Destroy a stream creator object. More...

clrngStatus	clrngRewindStreamCreator (clrngStreamCreator *creator)
	Reset a stream creator to its original initial state. More...

clrngStatus	clrngSetBaseCreatorState (clrngStreamCreator creator, const clrngStreamState baseState)
	Change the base stream state of a stream creator. More...

clrngStatus	clrngChangeStreamsSpacing (clrngStreamCreator *creator, cl_int e, cl_int c)
	Change the spacing between successive streams. More...

Stream Allocation, Destruction and Initialization
Functions to create or destroy random streams and arrays of random streams.
clrngStream *	clrngAllocStreams (size_t count, size_t bufSize, clrngStatus err)
	Reserve memory for one or more stream objects. More...

clrngStatus	clrngDestroyStreams (clrngStream *streams)
	Destroy one or many stream objects. More...

clrngStream *	clrngCreateStreams (clrngStreamCreator creator, size_t count, size_t bufSize, clrngStatus *err)
	Allocate memory for and create new RNG stream objects. More...

clrngStatus	clrngCreateOverStreams (clrngStreamCreator creator, size_t count, clrngStream streams)
	Create new RNG stream objects in already allocated memory. More...

clrngStream *	clrngCopyStreams (size_t count, const clrngStream streams, clrngStatus err)
	Clone RNG stream objects. More...

clrngStatus	clrngCopyOverStreams (size_t count, clrngStream destStreams, const clrngStream srcStreams)
	Copy RNG stream objects in already allocated memory [device]. More...

clrngStatus	clrngCopyOverStreamsFromGlobal (size_t count, clrngStream destStreams, const clrngHostStream srcStreams)
	Copy RNG host stream objects from global memory into private memory [device-only]. More...

clrngStatus	clrngCopyOverStreamsToGlobal (size_t count, clrngHostStream destStreams, const clrngStream srcStreams)
	Copy RNG device stream objects from private memory into global memory [device-only]. More...

Stream Output
Functions to read successive values from a random stream.
cl_double	clrngRandomU01 (clrngStream *stream)
	Generate the next random value in (0,1) [device]. More...

cl_int	clrngRandomInteger (clrngStream *stream, cl_int i, cl_int j)
	Generate the next random integer value [device]. More...

clrngStatus	clrngRandomU01Array (clrngStream stream, size_t count, cl_double buffer)
	Fill an array with successive random values in (0,1) [device]. More...

clrngStatus	clrngRandomIntegerArray (clrngStream stream, cl_int i, cl_int j, size_t count, cl_int buffer)
	Fill an array with successive random integer values [device]. More...

Stream Navigation
Functions to roll back or advance streams by many steps.
clrngStatus	clrngRewindStreams (size_t count, clrngStream *streams)
	Reinitialize streams to their initial states [device]. More...

clrngStatus	clrngRewindSubstreams (size_t count, clrngStream *streams)
	Reinitialize streams to their initial substream states [device]. More...

clrngStatus	clrngForwardToNextSubstreams (size_t count, clrngStream *streams)
	Advance streams to the next substreams [device]. More...

clrngStream *	clrngMakeSubstreams (clrngStream stream, size_t count, size_t bufSize, clrngStatus *err)
	Allocate and make an array of substreams of a stream. More...

clrngStatus	clrngMakeOverSubstreams (clrngStream stream, size_t count, clrngStream substreams)
	Make an array of substreams of a stream. More...

clrngStatus	clrngAdvanceStreams (size_t count, clrngStream *streams, cl_int e, cl_int c)
	Advance the state of streams by many steps. More...

Work Functions
Functions to submit work-items to command queues.
clrngStatus	clrngDeviceRandomU01Array (size_t streamCount, cl_mem streams, size_t numberCount, cl_mem outBuffer, cl_uint numQueuesAndEvents, cl_command_queue commQueues, cl_uint numWaitEvents, const cl_event waitEvents, cl_event *outEvents)
	Fill a buffer of random numbers. More...

Miscellaneous Functions
clrngStatus	clrngWriteStreamInfo (const clrngStream stream, FILE file)
	Format and output information about a stream object to a file. More...

Detailed Description

Template of the specialized interface for specific generators (not to be included as is!)

The function and type names in this API all start with clrng. In each specific implementation, this prefix is expanded to a specific prefix; e.g., clrngMrg31k3p for the MRG31k3p generator.

In the standard case, streams and substreams are defined as in [10], [2], [5] . The sequence of successive states of the base RNG over its entire period of length \(\rho\) is divided into streams whose starting points are \(Z\) steps apart. The sequence for each stream (of length \(Z\)) is further divided into substreams of length \(W\). The integers \(Z\) and \(W\) have default values that have been carefully selected to avoid detectable dependence between successive streams and substreams, and are large enough to make sure that streams and substreams will not be exhausted in practice. It is strongly recommended to never change these values (even if the software allows it). The initial state of the first stream (the seed of the library) has a default value. It can be changed by invoking clrngSetBaseCreatorState() before creating a first stream.

A stream object is a structure that contains the current state of the stream, its initial state (at the beginning of the stream), and the initial state of the current substream. Whenever the user creates a new stream, the software automatically jumps ahead by \(Z\) steps to find its initial state, and the three states in the stream object are set to it. The form of the state depends on the type of RNG.

Some functions are available on both the host and the devices (they can be used within a kernel) whereas others (such as stream creation) are available only on the host. Many functions are defined only for arrays of streams; for a single stream, it suffices to specify an array of size 1.

When a kernel is called, one should pass a copy of the streams from the host to the global memory of the device. Another copy of the stream state must be stored in the private memory of the work item that uses it in the kernel code to generate random numbers. In the current implementation, to avoid wasting (scarce) private memory, without the option CLRNG_ENABLE_SUBSTREAMS (see below), only the current state of the stream is stored explicitly in the work-item's private memory. The work item also keeps in private memory a pointer to the initial state of the stream, but this initial state is not copied into private memory, and the work item does not keep track of the initial state of the current substream. With the option CLRNG_ENABLE_SUBSTREAMS, the initial state of the current substream is also stored into private memory. This permits one to rewind the current state to it or move forward to the next substream.

To use the clRNG library from within a user-defined kernel, the user must include the clRNG header file corresponding to the desired RNG via an include directive. Other specific preprocessor macros can be placed before including the header file to change settings of the library when the default values are not suitable for the user. The following options are currently available:

CLRNG_SINGLE_PRECISION: With this option, all the random numbers returned by clrngRandomU01() and clrngRandomU01Array(), and generated by clrngDeviceRandomU01Array(), will be of type cl_float instead of cl_double (the default setting). This option can be activated on the device and the host separately (i.e., on either one or on both), and affects all implemented RNGs.
CLRNG_ENABLE_SUBSTREAMS: With this option, the current state of a stream can be reset on the device to the initial state of the current or next substream. This is made possible by storing in private memory the initial substream state. Without this option, by default, this is not possible and only the current state of the stream and a pointer to its initial state (left in global memory) are kept in private memory and is accessible, in a work item. This option applies only to the device; operations on substreams are always available on the host.

For example, to enable substreams support, generate single-precision floating point numbers on the device, and use the MRG31k3p generator, one would have, in the device code:

#define  CLRNG_ENABLE_SUBSTREAMS
#define  CLRNG_SINGLE_PRECISION
#include <mrg31k3p.clh>

To generate single-precision floating point numbers also on the host, still using the MRG31k3p generator, the host code should contain:

#define CLRNG_SINGLE_PRECISION

#include <mrg31k3p.h>

The functions described here are all available on the host, in all implementations, unless specified otherwise. Only some of the functions and types are also available on the device in addition to the host; they are tagged with [device]. Other functions are only available on the device; they are tagged with [device-only]. Some functions return an error code in err.

Implemented RNG's

The following table lists the RNG's that are currently implemented in clRNG with the name of the corresponding header file.

RNG	Prefix	Host Header File	Device Header File
MRG31k3p	`Mrg31k3p`	mrg31k3p.h	mrg31k3p.clh
MRG32k3a	`Mrg32k3a`	mrg32k3a.h	mrg32k3a.clh
LFSR113	`Lfsr113`	lfsr113.h	lfsr113.clh
Philox-4×32-10	`Philox432`	philox432.h	philox432.clh

The MRG31k3p Generator

The MRG31k3p generator is defined in [4] . In its specific implementation, the function and type names start with clrngMrg31k3p. For this RNG, a state is a vector of six 31-bit integers, represented internally as cl_uint. The entire period length of approximately \(2^{185}\) is divided into approximately \(2^{51}\) non-overlapping streams of length \(Z=2^{134}\). Each stream is further partitioned into substreams of length \(W=2^{72}\). The state (and seed) of each stream is a vector of six 31-bit integers. This size of state is appropriate for having streams running in work items on GPU cards, for example, while providing a sufficient period length for most applications.

The MRG32k3a Generator

MRG32k3a is a combined multiple recursive generator (MRG) proposed by L'Ecuyer [7] , implemented here in 64-bit integer arithmetic. This RNG has a period length of approximately \(2^{191}\), and is divided into approximately \(2^{64}\) non-overlapping streams of length \(Z = 2^{127}\), and each stream is subdivided in \(2^{51}\) substreams of length \(W = 2^{76}\). These are the same numbers as in [5] . The state of a stream at any given step is a six-dimensional vector of 32-bit integers, but those integers are stored as cl_ulong (64-bit integers) in the present implementation (so they use twice the space). The generator has 32 bits of resolution. Note that in the original version proposed in [7] and [5], the recurrences are implemented in double instead, and the state is stored in six 32-bit integers. The change in implementation is to avoid using double's, which are not available on many GPU devices, and also because the 64-bit implementation is much faster than that in double when 64-bit integer arithmetic is available on the hardware.

The LFSR113 Generator

The LFSR113 generator is defined in [8] . In its implementation, the function and type names start with clrngLfsr113. For this RNG, a state vector of four 31-bit integers, represented internally as cl_uint. The period length of approximately \(2^{113}\) is divided into approximately \(2^{23}\) non-overlapping streams of length \(Z=2^{90}\). Each stream is further partitioned into \(2^{35}\) substreams of length \(W=2^{55}\). Note that the functions clrngLfsr113ChangeStreamsSpacing() and clrngLfsr113AdvancedStreams() are not implemented in the current version.

The Philox-4×32-10 Generator

The counter-based Philox-4×32-10 generator is defined in [11] . Unlike the previous three generators, its design is not supported by a theoretical analysis of equidistribution. It has only been subjected to empirical testing with the TestU01 software [3] (the other three generators also have). In its implementation, the function and type names start with clrngPhilox432. For this RNG, a state is a 128-bit counter with a 64-bit key, and a 2-bit index used to iterate over the four 32-bit outputs generated for each counter value. The counter is represented internally as a vector of four 32-bit cl_uint values and the index, as a single cl_uint value. In the current clRNG version, the key is the same for all streams, so it is not stored in each stream object but rather hardcoded in the implementation. The period length of \(2^{130}\) is divided into \(2^{28}\) non-overlapping streams of length \(Z=2^{102}\). Each stream is further partitioned into \(2^{36}\) substreams of length \(W=2^{66}\). The key (all bits to 0), initial counter and order in which the four outputs per counter value are returned are chosen to generate the same values, in the same order, as Random123's Engine module [11], designed for use with the standard C++11 random library. Note that the function clrngPhilox432ChangeStreamsSpacing() supports only values of \(c\) that are multiples of 4, with either \(e = 0\) or \(e \geq 2\).

Function Documentation

clrngStreamCreator* clrngCopyStreamCreator	(	const clrngStreamCreator *	creator,
		clrngStatus *	err
	)

Duplicate an existing stream creator object.

Create an identical copy (a clone) of the stream creator creator. To create a copy of the default creator, put NULL as the creator parameter. All the new stream creators returned by clrngCopyStreamCreator(NULL, NULL) will create the same sequence of random streams, unless the default stream creator is used to create streams between successive calls to this function.

Parameters

[in]	creator	Stream creator object to be copied, or `NULL` to copy the default stream creator.
[out]	err	Error status variable, or `NULL`.

Returns: The newly created stream creator object.

clrngStatus clrngDestroyStreamCreator ( clrngStreamCreator * creator )

Destroy a stream creator object.

Release the resources associated to a stream creator object.

Parameters

[out] creator Stream creator object to be destroyed.

Returns: Error status

clrngStatus clrngRewindStreamCreator ( clrngStreamCreator * creator )

Reset a stream creator to its original initial state.

Reset the stream creator to its original initial state, so it can re-create the same streams over again.

Parameters

[in] creator Stream creator object to be reset.

Returns: Error status

clrngStatus clrngSetBaseCreatorState	(	clrngStreamCreator *	creator,
		const clrngStreamState *	baseState
	)

Change the base stream state of a stream creator.

Set the base state of the stream creator, which can be seen as the seed of the underlying RNG. This will be the initial state (or seed) of the first stream created by this creator. Then, for most conventional RNGs, the initial states of successive streams will be spaced equally, by \(Z\) steps in the RNG sequence. The type and size of the baseState parameter depends on the type of RNG. The base state always has a default value, so this function does not need to be invoked.

Parameters

[in,out]	creator	Stream creator object.
[in]	baseState	New initial base stream state. Can be set to `NULL` to use the library default.

Returns: Error status

Warning: It is recommended to use the library default base state.

clrngStatus clrngChangeStreamsSpacing	(	clrngStreamCreator *	creator,
		cl_int	e,
		cl_int	c
	)

Change the spacing between successive streams.

This function should be used only in exceptional circumstances. It changes the spacing \(Z\) between the initial states of the successive streams from the default value to \(Z = 2^e + c\) if \(e > 0\), or to \(Z = c\) if \(e = 0\). One must have \(e \geq 0\) but \(c\) can take negative values. The default spacing values have been carefully selected for each RNG to avoid overlap and dependence between streams, and it is highly recommended not to change them.

Parameters

[in,out]	creator	Stream creator object.
[in]	e	Value of \(e\).
[in]	c	Value of \(c\).

Returns: Error status

Warning: It is recommended to use the library default spacing and not to invoke this function.

clrngStream* clrngAllocStreams	(	size_t	count,
		size_t *	bufSize,
		clrngStatus *	err
	)

Reserve memory for one or more stream objects.

Reserve memory space for count stream objects, without creating the stream objects. Returns a pointer to the allocated buffer and returns in bufSize the size of the allocated buffer, in bytes.

Parameters

[in]	count	Number of stream objects to allocate.
[out]	bufSize	Size in bytes of the allocated buffer, or `NULL` if not needed.
[out]	err	Error status variable, or `NULL`.

Returns: Pointer to the newly allocated buffer.

clrngStatus clrngDestroyStreams ( clrngStream * streams )

Destroy one or many stream objects.

Release the memory space taken by those stream objects.

Parameters

[in,out] streams Stream object buffer to be released.

Returns: Error status

Examples:: MultiStream/multistream.c, and RandomArray/randomarray.c.

clrngStream* clrngCreateStreams	(	clrngStreamCreator *	creator,
		size_t	count,
		size_t *	bufSize,
		clrngStatus *	err
	)

Allocate memory for and create new RNG stream objects.

Create and return an array of count new streams using the specified creator. This function also reserves the memory space required for the structures and initializes the stream states. It returns in bufSize the size of the allocated buffer, in bytes. To use the default creator, put NULL as the creator parameter. To create a single stream, just put set count to 1.

Parameters

[in,out]	creator	Stream creator object, or `NULL` to use the default stream creator.
[in]	count	Size of the array (use 1 for a single stream object).
[out]	bufSize	Size in bytes of the allocated buffer, or `NULL` if not needed.
[out]	err	Error status variable, or `NULL`.

Returns: The newly created array of stream object.

Examples:: MultiStream/multistream.c, and RandomArray/randomarray.c.

clrngStatus clrngCreateOverStreams	(	clrngStreamCreator *	creator,
		size_t	count,
		clrngStream *	streams
	)

Create new RNG stream objects in already allocated memory.

This function is similar to clrngCreateStreams(), except that it does not reserve memory for the structure. It creates the array of new streams in the preallocated streams buffer, which could have been reserved earlier via either clrngAllocStreams() or clrngCreateStreams(). It permits the client to reuse memory that was previously allocated for other streams.

Parameters

[in,out]	creator	Stream creator object, or `NULL` to use the default stream creator.
[in]	count	Size of the array (use 1 for a single stream object).
[out]	streams	Buffer in which the new stream(s) will be stored.

Returns: Error status

clrngStream* clrngCopyStreams	(	size_t	count,
		const clrngStream *	streams,
		clrngStatus *	err
	)

Clone RNG stream objects.

Create an identical copy (a clone) of each of the count stream objects in the array streams. This function allocates memory for all the new structures before cloning, and returns a pointer to the new structure.

Parameters

[in]	count	Number of random number in the array (use 1 for a single stream object).
[in]	streams	Stream object or array of stream objects to be cloned.
[out]	err	Error status variable, or `NULL`.

Returns: The newly created stream object or array of stream objects.

Examples:: MultiStream/multistream.c.

clrngStatus clrngCopyOverStreams	(	size_t	count,
		clrngStream *	destStreams,
		const clrngStream *	srcStreams
	)

Copy RNG stream objects in already allocated memory [device].

Copy (or restore) the stream objects srcStreams into the buffer destStreams, and each of the count stream objects from the array srcStreams into the buffer destStreams. This function does not allocate memory for the structures in destStreams; it assumes that this has already been done. Note: The device API offers variants of this function to convert stream objects across their host and device representations, while copying across different types of memory.

Parameters

[in]	count	Number of stream objects to copy (use 1 for a single stream object).
[out]	destStreams	Destination buffer into which to copy (its content will be overwritten).
[in]	srcStreams	Stream object or array of stream objects to be copied.

Returns: Error status

Note: The device API offers two variants of this function called clrngCopyOverStreamsFromGlobal(), for which srcStreams is a pointer to constant clrngHostStream objects in global memory, and clrngCopyOverStreamsToGlobal(), for which destStreams is a pointer to (non-constant) clrngHostStream objects in global memory.

clrngStatus clrngCopyOverStreamsFromGlobal	(	size_t	count,
		clrngStream *	destStreams,
		const clrngHostStream *	srcStreams
	)

Copy RNG host stream objects from global memory into private memory [device-only].

Copy the host stream objects srcStreams from global memory as device stream objects into the buffer destStreams in private memory.

Parameters

[in]	count	Number of stream objects to copy (use 1 for a single stream object).
[out]	destStreams	Destination buffer into which to copy (its content will be overwritten).
[in]	srcStreams	Host stream object or array of host stream objects to be copied.

Returns: Error status

clrngStatus clrngCopyOverStreamsToGlobal	(	size_t	count,
		clrngHostStream *	destStreams,
		const clrngStream *	srcStreams
	)

Copy RNG device stream objects from private memory into global memory [device-only].

Parameters

[in]	count	Number of stream objects to copy (use 1 for a single stream object).
[out]	destStreams	Destination buffer into which to copy (its content will be overwritten).
[in]	srcStreams	Device stream object or array of device stream objects to be copied.

Returns: Error status

cl_double clrngRandomU01 ( clrngStream * stream )

Generate the next random value in (0,1) [device].

Generate and return a (pseudo)random number from the uniform distribution over the interval \((0,1)\), using stream. If this stream is from an RNG, the stream state is advanced by one step before producing the (pseudo)random number.

By default, the returned value is of type cl_double. But if the option CLRNG_SINGLE_PRECISION is defined, the returned value will be of type cl_float. Setting this option changes the type of the returned value for all RNGs and all functions that use clrngRandomU01().

Parameters

[in,out] stream Stream used to generate the random value.

Returns: A random floating-point value uniformly distributed in \((0,1)\)

Examples:: MultiStream/multistream.c, and RandomArray/randomarray.c.

cl_int clrngRandomInteger	(	clrngStream *	stream,
		cl_int	i,
		cl_int	j
	)

Generate the next random integer value [device].

Generate and return a (pseudo)random integer from the discrete uniform distribution over the integers \(\{i, \dots, j \}\), using stream, by calling clrngRandomU01() once and transforming the output by inversion. That is, it returns i + (cl_int)((j-i+1) * clrngRandomU01(stream)).

Parameters

[in,out]	stream	Stream used to generate the random value.
[in]	i	Smallest integer value (inclusive).
[in]	j	Largest integer value (inclusive).

Returns: A random integer value uniformly distributed in \(\{i, \dots, j \}\)

clrngStatus clrngRandomU01Array	(	clrngStream *	stream,
		size_t	count,
		cl_double *	buffer
	)

Fill an array with successive random values in (0,1) [device].

Fill preallocated buffer with count successive (pseudo)random numbers. Equivalent to calling clrngRandomU01() count times to fill the buffer.

If CLRNG_SINGLE_PRECISION is defined, the buffer argument is of type cl_float and will be filled by count values of type cl_float instead.

Parameters

[in,out]	stream	Stream used to generate the random values.
[in]	count	Number of values in the array.
[out]	buffer	Destination buffer (must be pre-allocated).

Returns: Error status

clrngStatus clrngRandomIntegerArray	(	clrngStream *	stream,
		cl_int	i,
		cl_int	j,
		size_t	count,
		cl_int *	buffer
	)

Fill an array with successive random integer values [device].

Same as clrngRandomU01Array(), but for integer values in \(\{i,\dots,j\}\). Equivalent to calling clrngRandomInteger() count times to fill the buffer.

Parameters

[in,out]	stream	Stream used to generate the random values.
[in]	i	Smallest integer value (inclusive).
[in]	j	Largest integer value (inclusive).
[in]	count	Number of values in the array.
[out]	buffer	Destination buffer (must be pre-allocated).

Returns: Error status

clrngStatus clrngRewindStreams	(	size_t	count,
		clrngStream *	streams
	)

Reinitialize streams to their initial states [device].

Reinitialize all the streams in streams to their initial states. The current substream also becomes the initial one.

Parameters

[in]	count	Number of stream objects in the array (use 1 for a single stream object).
[in,out]	streams	Stream object or array of stream objects to be reset to the start of the stream(s).

Returns: Error status

Warning: This function can be slow on the device, because it reads the initial state from global memory.

Examples:: MultiStream/multistream.c, and RandomArray/randomarray.c.

clrngStatus clrngRewindSubstreams	(	size_t	count,
		clrngStream *	streams
	)

Reinitialize streams to their initial substream states [device].

Reinitialize all the streams in streams to the initial states of their current substream.

Parameters

[in]	count	Number of stream objects in the array (use 1 for a single stream object).
[in,out]	streams	Stream object or array of stream objects to be reset to the beginning of the current substream(s).

Returns: Error status

Warning: This function is available on the device only if the preprocessor symbol CLRNG_ENABLE_SUBSTREAMS is defined.

Examples:: MultiStream/multistream.c.

clrngStatus clrngForwardToNextSubstreams	(	size_t	count,
		clrngStream *	streams
	)

Advance streams to the next substreams [device].

Reinitialize all the streams in streams to the initial states of their next substream. The current states and the initial states of the current substreams are changed.

Parameters

[in]	count	Number of stream objects in the array (use 1 for a single stream object).
[in,out]	streams	Stream object or array of stream objects to be advanced to the next substream(s).

Returns: Error status

Warning: This function is available on the device only if the preprocessor symbol CLRNG_ENABLE_SUBSTREAMS is defined.

Examples:: MultiStream/multistream.c.

clrngStream* clrngMakeSubstreams	(	clrngStream *	stream,
		size_t	count,
		size_t *	bufSize,
		clrngStatus *	err
	)

Allocate and make an array of substreams of a stream.

Make and return an array of count copies of stream, whose current (and initial substream) states are the initial states of count successive substreams of stream. The first substream in the returned array is simply a copy of stream. This function also reserves the memory space required for the structures and initializes the stream states. It returns in bufSize the size of the allocated buffer, in bytes. To create a single stream, just set count to 1. When this function is invoked, the substream state and initial state of stream are advanced by count substreams.

clrngStatus clrngMakeOverSubstreams	(	clrngStream *	stream,
		size_t	count,
		clrngStream *	substreams
	)

Make an array of substreams of a stream.

This function is similar to clrngMakeStreams(), except that it does not reserve memory for the structure. It creates the array of new streams in the preallocated substreams buffer, which could have been reserved earlier via either clrngAllocStreams(), clrngMakeSubstreams() or clrngCreateStreams(). It permits the client to reuse memory that was previously allocated for other streams.

clrngStatus clrngAdvanceStreams	(	size_t	count,
		clrngStream *	streams,
		cl_int	e,
		cl_int	c
	)

Advance the state of streams by many steps.

This function should be used only in very exceptional circumstances. It advances the state of the streams in array streams by \(k\) steps, without modifying the states of other streams, nor the initial stream and substream states for those streams. If \(e > 0\), then \(k = 2^e + c\); if \(e < 0\), then \(k = −2^{|e|} + c\); and if \(e = 0\), then \(k = c\). Note that \(c\) can take negative values. We discourage the use of this procedure to customize the length of streams and substreams. It is better to use the default spacing, which has been carefully selected for each RNG type.

Parameters

[in]	count	Number of stream objects in the array (use 1 for a single stream object).
[in,out]	streams	Stream object or array of stream objects to be advanced.
[in]	e	Value of \(e\).
[in]	c	Value of \(c\).

Returns: Error status

Warning: Check the implementation for all cases \(e > 0\), \(e = 0\) and \(e < 0\).

clrngStatus clrngDeviceRandomU01Array	(	size_t	streamCount,
		cl_mem	streams,
		size_t	numberCount,
		cl_mem	outBuffer,
		cl_uint	numQueuesAndEvents,
		cl_command_queue *	commQueues,
		cl_uint	numWaitEvents,
		const cl_event *	waitEvents,
		cl_event *	outEvents
	)

Fill a buffer of random numbers.

Fill the buffer pointed to by outBuffer with numberCount uniform random numbers of type cl_double (or of type cl_float if CLRNG_SINGLE_PRECISION is defined), using streamCount work items. In the current implementation, numberCount must be a multiple of streamCount. See clEnqueueNDRangeKernel() from the OpenCL API documentation for a description of the numWaitEvents and waitEvents arguments.

Parameters

[in]	streamCount	Number of streams in `stream_array`.
[in]	streams	OpenCL buffer that contains an array of stream objects.
[in]	numberCount	Number of random number to store in the buffer.
[out]	outBuffer	OpenCL buffer in which the generated numbers will be stored.
[in]	numQueuesAndEvents	numbers of queues and events (for now only the value 1 is supported)
[in]	commQueues	OpenCL command queue.
[in]	numWaitEvents	Number of events in the event wait list.
[in]	waitEvents	Event wait list.
[in]	outEvents	Event object.

Returns: Error status

Note: This function requires access to the clRNG device header files (like mrg31k3p.clh) and assumes that the environment variable CLRNG_ROOT points to the installation path of the clRNG package, where lies the cl/include subdirectory that contains these files. Means of setting an environment variable depend on the operating system used.

Todo:: Add instructions for OSX, Linux and Windows users on how to set this environment variable.

Warning: In the current implementation, numberCount must be a multiple of streamCount.; In the current implementation, the array streams is left unchanged, as there is no write-back from the device code.; In the current implementation, if the device doesn't support OpenCL 2.0, numberCount must be smaller than or a multiple of the device's maximum workgroup size.; In the current implementation, only numQueuesAndEvents = 1 is supported.

Assume the variables context and queue are a valid OpenCL context and command queue, and that we want to generate number_count using stream_count distinct streams, where number_count is a multiple of stream_count. To use the clrngDeviceRandomU01Array() function, we must first create an array of stream objects:

size_t streams_buf_size;

clrngStream* streams = clrngCreateStreams(NULL, stream_count, &streams_buf_size, (clrngStatus *)&err);

and create the OpenCL buffers for the stream objects:

cl_mem streams_buf = clCreateBuffer(context, CL_MEM_HOST_WRITE_ONLY | CL_MEM_READ_ONLY | CL_MEM_COPY_HOST_PTR, streams_buf_size, streams, &err);

and for the generated numbers:

cl_mem numbers_buf = clCreateBuffer(context, CL_MEM_HOST_READ_ONLY | CL_MEM_WRITE_ONLY, number_count * sizeof(fp_type), NULL, &err);

Next, these can be used to invoke clrngDeviceRandomU01Array():

cl_event event;

err = clrngDeviceRandomU01Array(stream_count, streams_buf, number_count, numbers_buf, 1, &queue, 0, NULL, &event);

At the moment the generated numbers are needed, we must wait for the completion of the generation of the random numbers:

err = clWaitForEvents(1, &event);

Then, we can allocate memory for the output numbers and fetch them from the device:

fp_type* numbers = (fp_type*) malloc(number_count * sizeof(fp_type));

err = clEnqueueReadBuffer(queue, numbers_buf, CL_TRUE, 0, number_count * sizeof(fp_type), numbers, 0, NULL, NULL);

The complete code for this example can be found in RandomArray/randomarray.c.

Examples:: RandomArray/randomarray.c.

clrngStatus clrngWriteStreamInfo	(	const clrngStream *	stream,
		FILE *	file
	)

Format and output information about a stream object to a file.

Parameters

[in]	stream	Stream object about which to write information.
[in]	file	File to which to output. Can be set to `stdout` or `stderr` for standard output and error.

Returns: Error status

Data Structures

Functions

Detailed Description

Implemented RNG's

The MRG31k3p Generator

The MRG32k3a Generator

The LFSR113 Generator

The Philox-4×32-10 Generator

Function Documentation