name: Random

synopsis:

g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_system.a

#include <Random.h>

Random();
boolean seed(long seed);
double get();

quick start:

Random rand;
rand.seed(27);
double value = rand.get();

description:

The Random class implements a variety of random number generators, including a uniform random number generator based on a subtractive method, and a Gaussian random number generator that is based on a transformation of the uniform random number generator. An interface to the standard system random number generator is supplied also.

This class has been carefully designed to allow users to maintain independent random number generators by instantiating separate classes. However, a global default generator is used (by default) for applications in which all random numbers should be drawn from the same source.

The algorithms implemented here are based on original work by Knuth, The Art of Computer Programming, and parallel implementations described in:

Numerical Recipes in C

This resource was chosen because the uniform random number generator is portable, fast, and more accurate than the ANSI-standard generator supplied on most systems. The Gaussian generator is extremely fast as well.

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"Random";

define algorithm choices:

enum ALGORITHM { UNIFORM = 0, GAUSSIAN, DEF_ALGORITHM = UNIFORM };

define implementations:

enum IMPLEMENTATION { SUBTRACTIVE = 0, CONGRUENTIAL, TRANSFORMATION, DEF_IMPLEMENTATION = SUBTRACTIVE };

define global random number generators:

Random Random::GLOBAL_UNIFORM(UNIFORM, SUBTRACTIVE);

Random Random::GLOBAL_GAUSSIAN(GAUSSIAN, TRANSFORMATION);

define default values to seed the uniform subtractive method:

static const long US_MBIG = 1000000000;

static const long US_MSEED = 161803398;

static const long US_MZ = 0;

static const long US_MDIM = 56;

static const long US_CONST = 30;

static const double US_FAC = (1.0 / (double)US_MBIG);

define default values used in the uniform congruential method:
```
static const long INV_RAND_MAX = 1.0 / RAND_MAX;
```
define a default value for the random number seed:
```
static const long DEF_SEED = 27;
```

error codes:

error codes indicating general errors:
```
static const long ERR = 1900;
```

protected data:

data common to all algorithms and implementations:

algorithm name:
ALGORITHM algorithm_d;

implementation name:
IMPLEMENTATION implementation_d;

declare a register to hold the current seed:
long seed_d;

declare a static debug level for all class instantiations:
static Integral::DEBUG debug_level_d;

static memory manager:
static MemoryManager mgr_d;

initialization flag:
boolean is_valid_d;
algorithm and implementation specific variables:
- algorithm: uniform
  implementation: subtractive
  - define some registers to maintain history:
```
long us_inext_d;
```
```
long us_inextp_d;
```
```
long us_ma_d[US_MDIM];
```
- algorithm: Gaussian
  implementation: transformation
  - define some registers to maintain history:
```
boolean gt_iset_d;
```
```
double gt_gset_d;
```

required public methods:

static methods:

static const SysString& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods:

static boolean setDebug(Integral::DEBUG level);

boolean debug(const unichar* message) const;

destructor/constructor(s):

~Random();

Random(long seed = DEF_SEED);

Random(const Random& arg);

assign methods:
```
boolean assign(const Random& arg);
```
operator= methods:
```
Random& operator=(const Random& arg_a);
```

i/o methods:

i/o methods are omitted because this class can't write itself to an Sof file

equality methods:
```
boolean eq(const Random& arg);
```

memory management methods:

static void* operator new(size_t size);

static void* operator new[](size_t size);

static void operator delete(void* ptr);

static void operator delete[](void* ptr);

static boolean setGrowSize(long grow_size);

boolean clear(Integral::CMODE ctype_a = Integral::DEF_CMODE);

class-specific public methods:

constructor:

Random(ALGORITHM alg, IMPLEMENTATION impl, long seed = DEF_SEED)

set and get methods:

boolean setAlgorithm(ALGORITHM algorithm);

boolean setImplementation(IMPLEMENTATION implementation);

ALGORITHM getAlgorithm() const;

IMPLEMENTATION getImplementation() const;

boolean seed(long value = DEF_SEED);

double get();

operator double();

initialization and computation methods: these methods initialize class constants, reset internal registers and compute a new random number
```
boolean init();
```
```
boolean compute();
```

private methods:

algorithm-specific computation methods: uniform/subtractive

boolean initUniformSubtractive();

boolean computeUniformSubtractive();

algorithm-specific computation methods: uniform/congruential

boolean initUniformCongruential();

boolean computeUniformCongruential();

algorithm-specific computation methods: Gaussian/transformation

boolean initGaussianTransform();

boolean computeGaussianTransform();

examples:

This example shows how to generate a random number using default values:
```
Random rand;
double value = rand.get();
```

This example demonstrates how to configure an object for a specific algorithm and implementation:

Random rand;
rand.setAlgorithm(GAUSSIAN);
rand.setImplementation(TRANSFORMATION);
rand.seed((long)27);


for (long i = 0; i < 100; i++) {
  double value = rand.get();
}

notes:

The uniform congruential method calls the ANSI-standard rand function. It is included here mainly for completeness. It does not allow independent generators - all come from a common system source.