rstream-class: Class "rstream" - Multiple streams of uniform random numbers

In rstream: Streams of Random Numbers

Class "rstream" – Multiple streams of uniform random numbers

Description

The virtual class "rstream" provides a unified interface to uniform random number generators. Objects of its subclasses act as a source of streams for random numbers that can be handled by a set of methods and which can be used as arguments of functions that require sources of randomness, e.g. discrete event models, Monte Carlo integration or other stochastic simulations.

The instances of objects of this class and its subclasses are independent, i.e., sampling random numbers from one instance or reseting and changing its state does not effect any other instance. (However, different streams may not be stochastically independent if they are not carefully seeded!)

Additionally there is a mechanismus interface to save and restore such streams, e.g. for the next R session, for a reruning some stochastic calculations with identical input, or for sending the stream object to a slave node in parallel computing via MPI.

The interface to these classes is inspired by Pierre L'Ecuyers RngStreams package.

Objects from the Class

A virtual Class: No objects may be created from it.

Methods

The virtual class "rstream" prepares the following methods for handling random stream objects. Some methods that return parameters of the stream object have a variant that uses <- to change the respective parameters. See the man pages for the respective methods for details.

Notice: Some subclasses only implement a subset of these interfaces. The methods that do not work produce an error message.

Methods to use the stream (available for all subclasses):

rstream.sample

signature(object = "rstream"): Get a random sample from the stream object.

r

signature(object = "rstream"): Same as rstream.sample.

rstream.reset

signature(object = "rstream"): Reset stream into initial state.

Some subclasses have implemented the concept of substreams. This is especially usefull if two or more streams should be synchronized:

rstream.nextsubstream

signature(object = "rstream"): Set state of stream to next substream.

rstream.resetsubstream

signature(object = "rstream"): Reset current substream into starting state.

Antithetic random streams return numbers which have smallest possible correlation (i.e. -1) to their respective counterparts:

rstream.antithetic

signature(object = "rstream"): Whether or not the stream object returns antithetic random numbers.

rstream.antithetic<-

signature(object = "rstream"): Change antithetic flag (TRUE or FALSE).

Most sources of pseudo random numbers generate random numbers of precision 2^(-32) ~ 2.e-10. For some streams this can be increased to machine epsilon (i.e. ~ 1.e-16) by combining two random numbers of lower precision:

rstream.incprecision

signature(object = "rstream"): Whether or not the stream object returns random numbers with increased precision.

rstream.incprecision<-

signature(object = "rstream"): Change flag for increased precision (TRUE or FALSE).

Handling "rstream" objects:

print

signature(x = "rstream"): Print state of the stream object.

show

signature(x = "rstream"): Same as print.

rstream.name

signature(object = "rstream"): The name of the stream object.

rstream.name<-

signature(object = "rstream"): Change the name of the stream object.

rstream.clone

signature(object = "rstream"): Make a copy (clone) of stream object.

When a "rstream" object should be used in another R session or saved for some kind of later reuse all information about the object must be packed. Notice no method other than unpacking can be applied to a packed object. It must be unpacked before.

rstream.packed

signature(object = "rstream"): Whether or not the stream object is packed.

rstream.packed<-

signature(object = "rstream"): Pack or unpack object: set packed to TRUE or FALSE.

Warning

When "rstream" objects should be used in later R sessions they must be packed before the current R session is stopped and unpacked after the new R session has been started and the workspace image has been reloaded.

Note

"rstream" objects cannot simply be copied by <-. The new variable does not hold a copy of an "rstream" object but just points to the old object which might not be the wanted result (similar to R environments). Use rstream.clone instead.

The actual interface is implemented in subclasses, one for each source (package/library) of random numbers. The slots of this class and of all its subclasses must not be accessed directly. Use the above methods instead.

One may miss a method for reseeding a random stream. However, there is no need for such a method as there is a method for resetting the stream to its initial state. I one needs a stream with a different stream, then a new rstream object should be created at all.

Packed objects must be unpacked before any other method can be applied.

Author(s)

Josef Leydold [e-mail]

References

L'Ecuyer, P., Simard, R., Chen, E. J., and Kelton, W. D. (2002) An object-oriented random-number package with many long streams and substreams. Operations Research 50(6), 1073-1075.

See Also

rstream.mrg32k3a, rstream.runif. rstream.antithetic-methods, rstream.clone-methods, rstream.incprecision-methods, rstream.name-methods, rstream.packed-methods, rstream.reset-methods, rstream.sample-methods, rstream.nextsubstream-methods, rstream.RNG.

rstream documentation built on Oct. 19, 2022, 5:30 p.m.