randgen_ns* NewRandomGenerator_ns ( const char*  seed,   environ_ns*  env,   const char*  options )

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:

  NewRandomGenerator_ns ("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 GetRandomGenState_ns can be passed for seed, which will result in in the same behaviour as the random generator from which the state was extracted with GetRandomGenState_ns. 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".

When you are finished with the random generator object, free the resources it uses by calling DeleteRandomGen_ns.

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 NewRandomGenerator_ns. 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 SetNetRandomGen_bn), so that operations on the Bayes net will use that random generator, and to pass random generators to some functions (such as GenerateRandomCase_bn).

Version:

Versions 3.04 and later have this function.

See also:

DeleteRandomGen_ns    To free the randgen_ns when done with it.
GetRandomGenState_ns    To obtain a seed value.
GenerateRandomNumbers_ns    Use the randgen_ns to make random numbers.
GenerateRandomCase_bn    Use it to control simulation.
SetNetRandomGen_bn    Associate a randgen_ns with a net.

Example:

randgen_ns* rand = NewRandomGenerator_ns ("1", env, NULL);
double xr = GenerateRandomNumbers_ns (rand, NULL, 1, NULL); // creates pseudo-random number xr
double xrs[100];
GenerateRandomNumbers_ns (rand, xrs, 100, NULL);            // then generates 100 more random numbers in xrs
char* rstr = strdup (GetRandomGenState_ns (rand, NULL));    // save the state of rand
SetNetRandomGen_bn (net, rand);    // will affect the operation on net of the functions:  
                                   //   GenerateRandomCase_bn   EquationToTable_bn   LearnCPTs_bn
                                   // don't use or free rand after this, because it is given to the net
GenerateRandomCase_bn (GetNetNodes2_bn (net, NULL), DEFAULT_SAMPLING, 100, NULL);    // for example
randgen_ns* rand2 = NewRandomGenerator_ns (rstr, env, NULL);// create a new generator in the same state that rand was in earlier
GenerateRandomCase_bn (GetNetNodes2_bn (net, NULL), DEFAULT_SAMPLING, 100, rand2);    // will generate the same case as above, 
                                                            // because its random generator was in the same state.
DeleteRandomGen_ns (rand2);                                 // don't need to do this for rand, because it was given to the net