NORSYS SOFTWARE © 2012

NETICA API

JAVA VERSION 5.04

norsys.netica
Class RandomGenerator

java.lang.Object
  |
  +--norsys.netica.RandomGenerator

public class RandomGenerator

extends java.lang.Object

A class that manages the generation of random numbers.

Since:

5.02

Version:

5.04 - January 21, 2012

Constructor Summary

RandomGenerator(java.lang.String seed, Environ env, java.lang.String options)

Creates a new object to control the randomized aspects of Netica, or generate pseudo-random numbers.

Method Summary

void	finalize() Removes this RandomGenerator object and frees all its resources (e.g., memory).
double	generateRandomNumbers(double[] results, int num, java.lang.String options) Generates num pseudo-random numbers using this RandomGenerator and puts them in the array results, returning the first one.
Environ	getEnviron() Returns this RandomGenerator's environment.
java.lang.String	getState(java.lang.String options) Returns a string that can be used as a seed to RandomGenerator to create a random generator that will produce exactly the same pseudo-random results as this one will.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

public RandomGenerator (

String	seed,
Environ	env,
String	options

) throws NeticaException

Creates a new object to control the randomized aspects of Netica, or generate pseudo-random numbers.

For seed, pass a positive (or zero) integer in the form of a string, for example:

new RandomGenerator ("32", env, null);

The sequence of random results generated will be based on the starting seed (same sequence for same seed). Alternately, the return value of getState can be passed for seed, which will result in in the same behaviour as the random generator from which the state was extracted with getState. A final possibility is to pass the string "Nondeterministic" for options, in which case, seed is ignored and the random sequence will be nondeterministic.

options should either be null or the string "Nondeterministic".

Netica API behaviour can be made completely deterministic, which is very useful for regression tests and repeatability under debugging. Under single-threading the only requirement is to not pass "Nondeterministic" to RandomGenerator. Under multi-threading, you also have to take into account the varying scheduling of threads, to be sure that if two different threads are operating on the same object that the order in which they do so does not negatively influence the repeatability of the object. Usually the best way is to limit the number of threads that can access the object (such as a rule of only one thread per Bayes net), or to synchronize their access to the object. In particular, multiple threads using the same random generator can produce varying pseudo-random sequences. The solution is to have multiple random generators, usually one for each thread that needs it. Netica makes that possible by allowing you to associate a random generator with a Bayes net (using Net.setRandomGenerator), so that operations on the Bayes net will use that random generator, and to pass random generators to some functions (such as generateRandomCase).

Parameters:

String		seed		Determines which pseudo-random sequence generated.
Environ		env		The environment that will contain this generator.
String		options		Controls behavior of the generator.

Version:

Versions 3.04 and later have this method.
In the C Version of the API, this function is named NewRandomGenerator_ns.

See Also:

finalize		To free the RandomGenerator when done with it.
getState		To obtain a seed value.
generateRandomNumbers		Use the RandomGenerator to make random numbers.
Net.generateRandomCase		Use it to control simulation.
Net.setRandomGenerator		Associate a RandomGenerator with a net.

Example:

 RandomGenerator randGen = new RandomGenerator ("1", env, null);
 double xr = randGen.generateRandomNumbers (null, 1, null); // creates pseudo-random number xr
 double xrs[100];
 randGen.generateRandomNumbers (xrs, 100, null);            // then generates 100 more random numbers in xrs
 String rstr = randGen.getState (null);    // save the state of rand
 net.setRandomGenerator (randGen, true);  // will affect the operation on net of the methods:  
                                          // generateRandomCase  equationToTable  learnCPTs
                                          // don't use randGen after this, because it is given to the net
 net.generateRandomCase (net.getNetNodes(), Net.DEFAULT_SAMPLING, 100, null);     // for example
 RandomGenerator randGen2 = new RandomGenerator (rstr, env, null);// create a new generator in the same state that randGen 
                                                                  // was in earlier
 net.generateRandomCase (net.getNetNodes(), Net.DEFAULT_SAMPLING, 100, randGen2); // will generate the same case as above, 
                                                                    // because its random generator was in the same state.
 randGen2.finalize();                     // don't need to do this for randGen, because it was given to the net

Method Detail

public void finalize ( ) throws NeticaException

Removes this RandomGenerator object and frees all its resources (e.g., memory).

You must not call this on a RandomGenerator that was passed to setRandomGenerator with true for the isPrivate argument.

Version:

Versions 3.04 and later have this method.
In the C Version of the API, this function is named DeleteRandomGen_ns.

See Also:

RandomGenerator

To create a new RandomGenerator.

Example:

See RandomGenerator.

Overrides:

finalize in class java.lang.Object

public double generateRandomNumbers (

double[ ]	results,
int	num,
String	options

) throws NeticaException

Generates num pseudo-random numbers using this RandomGenerator and puts them in the array results, returning the first one.

The numbers will be between 0 (inclusive) and 1 (exclusive), that is, from the interval [0,1).

results should be an array with enough room to store the required numbers, or results may be null (in which case it will still return the random number, and it will change the state of this RandomGenerator as if all the numbers were generated).

This randomGenerator will be left in a state to generate further random numbers, or it can be passed to any Netica API function that takes a RandomGenerator.

Pass null for options; it is only for future expansion.

Parameters:

double[]		results		An array with enough room to store the required numbers; it may be null.
int		num		The quantity of numbers to generate.
String		options		Controls behavior of the generation.

Version:

Versions 5.02 and later have this method.
In the C Version of the API, this function is named GenerateRandomNumbers_ns.

See Also:

RandomGenerator

To create a new RandomGenerator.

Example:

See RandomGenerator.

public Environ getEnviron ( )

Returns this RandomGenerator's environment.

Version:

Versions 3.04 and later have this method.

public String getState (

String

options

) throws NeticaException

Returns a string that can be used as a seed to RandomGenerator to create a random generator that will produce exactly the same pseudo-random results as this one will.

So you can save the state of a random generator to later make an equivalent generator.

The string returned will always be a string of printing ascii characters, so it can be easily printed to a file (but keep in mind the saved string may not be usable with future versions of Netica API).

Pass null for options; it is only for future expansion.

NOTE: As an alternative to using this function, you can create a new RandomGenerator with RandomGenerator, remember the seed value used, and use the new generator instead of this one. Then in future, to obtain the same sequence of random results, instead of using the saved state to create the RandomGenerator, you use the remembered seed.

Parameters:

String

options

For future expandability. Pass null for now.

Version:

Versions 5.02 and later have this method.
In the C Version of the API, this function is named GetRandomGenState_ns.

See Also:

RandomGenerator

Create a new RandomGenerator with the value returned.

Example:

See RandomGenerator.