Usage of PRNG
*************

Interface Description
=====================

The interface has changed dramatically in version 2.0. As more and more generator types were added to this package, a new generic interface was needed. While still plain Ansi C, the architecture is now object-oriented.

All generators are identified by a textual description. This description is either of the form "type(parameter1,parameter2, ...)" or is a shortcut name for a common PRNG as defined in src/prng_def.h.

Calling prng_new with such a description as the only argument will allocate a new generator object, initialize it, and return its handle (struct prng *).

All further calls need this handle as the first argument. They are best explained by example:

     #include <prng.h>   /* make sure that the compiler can find this file. */

     main()
     {
        struct prng *g;
        prng_num seed, n, M;
        double next, *array;
        int count;

        g = prng_new("eicg(2147483647,111,1,0)");

        if (g == NULL) /* always check whether prng_new has been successful */
        {
           fprintf(stderr,"Initialisation of generator failed.\n");
           exit (-1);
        }

        printf("Short name: %s\n",prng_short_name(g));
                                       /* definition as in call to prng_new */
        printf("Expanded name: %s\n",prng_long_name(g));
                                       /* Shortcuts expanded                */

        next = prng_get_next(g);       /* get next number 0 <= next < 1     */
        prng_get_array(g,array,count); /* fill array with count numbers     */
        prng_reset(g);                 /* reset the generator */
        prng_free(g);                  /* deallocate the generator object   */

     }

These functions work with all generators. For certain generators, the following functions are available, too:

     if (prng_is_congruential(g))
     {
        n = prng_get_next_int(g);       /* return next *unscaled* number    */
        M = prng_get_modulus(g);        /* return the modulus of the prng   */
     }

     if (prng_can_seed(g))
        prng_seed(g,seed);              /* reseed the generator             */

     if (prng_can_fast_sub(g))
        puts(prng_get_sub_def(g,20,0)); /* Get subsequence definition       */

     if (prng_can_fast_con(g))
        puts(prng_get_con_def(g,20,1)); /* Get block definition             */

NOTE:

prng_new performs only a rudimentary check on the parameters. The user is responsible for enforcing all restrictions on the parameters, such as checking that the modulus of an [E]ICG is prime, or that LCG and ICG are maximum period generators.

Most of these functions are implemented as macros, so be careful with autoincrements (++) in parameters.

PRNG Functions
==============

Library Function struct prng prng_new (char *STR) Create a new generator object. If initialisation of the generator object fails then NULL is returned. Thus the pointer returned by this routine must be checked against NULL before using it. Otherwise the program aborts with a segmentation fault.

Library Function void prng_reset (struct prng *G) Reset random number generator.

Library Function double prng_get_next (struct prng *G) Sample from generator (get next pseudo-random number from stream).

Library Function void prng_get_array (struct prng *G, double *ARRAY, int COUNT) Sample array of length COUNT.

Library Function prng_num prng_get_next_int (struct prng *G) Sample integer random number from generator.

Library Function void prng_free (struct prng *G) Destroy generator object.

Library Function char* prng_short_name (struct prng *G) Get name of generator as in call to prng_new.

Library Function char* prng_long_name (struct prng *G) Get name of generator with shortcuts expanded.

Library Function int prng_is_congruential (struct prng *G) TRUE if G is a congruential generator.

Library Function prng_num prng_get_modulus (struct prng *G) Return modulus of generator.

Library Function int prng_can_seed (struct prng *G) TRUE if generator G can be reseeded.

Library Function void prng_seed (struct prng *G, prng_num NEXT) Reseed generator.

Library Function int prng_can_fast_sub (struct prng *G) TRUE if subsequences of the random stream can computed directly.

Library Function char* prng_get_sub_def (struct prng *G, int S, int I) Get definition for the generator of the subsequence stream of G with starting point I and stepwidth S. It returns a character string that can be used a argument for prng_new. For generators where prng_can_fast_sub is TRUE. (see also SUB).

Library Function int prng_can_fast_con (struct prng *G) TRUE if blocks of the random stream can computed directly.

Library Function int prng_get_con_def (struct prng *G, int L, int I) Get definition for the generator of the blocked stream of G with position I and block length L. It returns a character string that can be used a argument for prng_new. For generators where prng_can_fast_con is TRUE. (see also CON).

Examples
========

examples/pairs.c is an example how to generate overlapping pairs of PRN using this package.

examples/tuples.c is a more general version of pairs.