| NORSYS SOFTWARE © 2012 | NETICA API | JAVA VERSION 5.04

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD