Re: built-in RNG distributions

[Sven N. Thommesen]

At 09:23 PM 1/26/1998 -0500, you wrote:
>
>Could someone please remind me where in the documentation
>tree there is a description of the current 
>built-in RNG distributions?  
>
>I have found one reference to them at the end very end of (a 
>long..) swarmdocs/src/random/UsageGuide.html page.
>But maybe there is a more accesible place they are described,
>for beginning users (including a description of the -varySeed
>parameter)?
>
>Thanks!
> - r

Rick,

the best description of the -varySeed functionality is found in
$SWARMHOME/src/random/docs/WHATS.NEW.in.0.75. This functionality was
changed between random 0.7 and random 0.75. I'm sorry if a description of
this change has not percolated into the README.Generators.v075 file, which
is repeated in that online Usage Guide document. (I should probably get
together with the Hive to better streamline the random documentation.)

I repeat the -varySeed comments below.

In general, my own documentation for the random library is found in the
../src/random/docs directory. I have no control over what the Hive puts
into the online documentation -- but I also have no doubt that my own
efforts could be better. Please let me know if you find info that's
incomplete or confusing or just plain wrong ...

Cheers,
--Sven

-----------------------------------------------------------------------
Excerpt from ../src/random/docs/WHATS.NEW.in.0.75:
-----------------------------------------------------------------------

4. Generators: the macros defining 'random' seeds have
changed, for two
reasons: 

(a) in 0.7, if '-varySeed' was not specified on the 
command
line, all generators created using the
-createWithDefault method were
created with the *same*
seed (DEFAULTSEED). This could lead to many
generators
running in lockstep, which we want to avoid.

(b) the RANDOMSEED
macro sometimes returned 0 
(notably, under Solaris).

The new usage is as
follows:

A. If the program is started without '-varySeed', the
default
generator (randomGenerator, an MT19937 object) is started with
the
fixed seed DEFAULTSEED, as before.

B. If the program is started with the
'-varySeed' switch, the
default generator is started with seed PIDTIMESEED,
which
depends on the process id and calendar time and will generally
be
different between program runs.

C. If further generators are created using
the -createWithDefaults
method, then these generators are created with the
STARTSEED seed.
This seed value depends on the '-varySeed' flag:
  (a) if
'-varySeed' is set, STARTSEED invokes RANDOMSEED, which
depends in an
unpredictable way on program runtime. (This macro
has changed from 0.7.)

(b) if '-varySeed' is not set, STARTSEED invokes NEXTSEED, which
creates a
sequence of seed values using an inline LCG and hence is
predictable and
repeatable.

If you want, you can of course specify '-varySeed' to get a
different
starting seed, but create other generators using NEXTSEED
explicitly.

D. Generators can of course be created using seed values
supplied 
by the programmer or by the user/researcher.

E. The following
macros are available for generating seed values:
  STARTSEED (=> NEXTSEED
or RANDOMSEED, depending on -varySeed)
  NEXTSEED: a sequence of values
created by an inline LCG
  RANDOMSEED: values that depend on the program's
runtime

F. Fixed seed values DEFAULTSEED, DEFAULTSEED1,
DEFAULTSEED2,
DEFAULTSEED3, DEFAULTSEED4 remain unchanged. There is also
macro 
FIRSTSEED, which returns the value that the default generator
was
started with.

--------------------------------------------------------------------

                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.
                  ==================================