rstream-class            package:rstream            R Documentation

_C_l_a_s_s "_r_s_t_r_e_a_m" - _M_u_l_t_i_p_l_e _s_t_r_e_a_m_s _o_f _u_n_i_f_o_r_m _r_a_n_d_o_m _n_u_m_b_e_r_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

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

_M_e_t_h_o_d_s:

     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):

     _r_s_t_r_e_a_m._s_a_m_p_l_e 'signature(object = "rstream")':  Get a random
          sample from the stream object.

     _r 'signature(object = "rstream")': Same as 'rstream.sample'.

     _r_s_t_r_e_a_m._r_e_s_e_t '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:

     _r_s_t_r_e_a_m._n_e_x_t_s_u_b_s_t_r_e_a_m 'signature(object = "rstream")': Set state
          of stream to next substream.

     _r_s_t_r_e_a_m._r_e_s_e_t_s_u_b_s_t_r_e_a_m '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:

     _r_s_t_r_e_a_m._a_n_t_i_t_h_e_t_i_c 'signature(object = "rstream")': Whether or not
          the stream object returns antithetic random numbers.

     _r_s_t_r_e_a_m._a_n_t_i_t_h_e_t_i_c<- '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:

     _r_s_t_r_e_a_m._i_n_c_p_r_e_c_i_s_i_o_n 'signature(object = "rstream")': Whether or
          not the stream object returns random numbers with increased
          precision.

     _r_s_t_r_e_a_m._i_n_c_p_r_e_c_i_s_i_o_n<- 'signature(object = "rstream")': Change
          flag for increased precision ('TRUE' or 'FALSE').

     Handling "rstream" objects:

     _p_r_i_n_t 'signature(x = "rstream")': Print state of the stream
          object.

     _s_h_o_w 'signature(x = "rstream")': Same as 'print'.

     _r_s_t_r_e_a_m._n_a_m_e 'signature(object = "rstream")': The name of the
          stream object.

     _r_s_t_r_e_a_m._n_a_m_e<- 'signature(object = "rstream")': Change the name of
          the stream object.

     _r_s_t_r_e_a_m._c_l_o_n_e '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.

     _r_s_t_r_e_a_m._p_a_c_k_e_d 'signature(object = "rstream")': Whether or not the
          stream object is packed.

     _r_s_t_r_e_a_m._p_a_c_k_e_d<- 'signature(object = "rstream")': Pack or unpack
          object: set packed to 'TRUE' or 'FALSE'.

_W_a_r_n_i_n_g:

     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.

_N_o_t_e:

     "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.

_A_u_t_h_o_r(_s):

     Josef Leydold (leydold@statistik.wu-wien.ac.at)

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

     'rstream.mrg32k3a-class', 'rstream.runif-class'.
     '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'.

