1.1 --- a/doc/manual/random.texi	Sun Mar 01 12:11:00 2009 +0000
     1.2 +++ b/doc/manual/random.texi	Sun Mar 01 11:16:39 2009 -0800
     1.3 @@ -12,10 +12,19 @@
     1.4  
     1.5  ns-3 random numbers are provided via instances of @code{class RandomVariable}.
     1.6  @itemize @bullet
     1.7 -@item @strong{by default, ns-3 simulations use a random seed}; if there is any 
     1.8 -randomness in the simulation, each run of the program will yield different results.  To use a fixed seed, users must call 
     1.9 -@code{RandomVariable::UseGlobalSeed ()} at the beginning of the program;
    1.10 -see section @xref{Seeding and independent replications}
    1.11 +@item @strong{by default, ns-3 simulations use a fixed seed}; if there is any 
    1.12 +randomness in the simulation, each run of the program will yield identical
    1.13 +results uniess the seed and/or run number is changed.  
    1.14 +@itemize @bullet
    1.15 +@item @strong{in ns-3.3 and earlier, ns-3 simulations used a random seed by 
    1.16 +default; this marks a change in policy starting with ns-3.4}
    1.17 +@end itemize
    1.18 +@item to obtain randomness across multiple simulation runs, you must either
    1.19 +set the seed differently or set the run number differently.  To set a seed, call
    1.20 +@code{SeedManager::SetSeed(uint32_t)} at the beginning of the program;
    1.21 +to set a run number with the same seed, call
    1.22 +@code{SeedManager::SetRun (uint32_t)} at the beginning of the program;
    1.23 +@xref{Seeding and independent replications}
    1.24  @item each RandomVariable used in ns-3 has a virtual random number 
    1.25  generator associated with it; all random variables use either a fixed
    1.26  or random seed based on the use of the global seed (previous bullet);
    1.27 @@ -100,27 +109,24 @@
    1.28  a fixed, deterministic seed with the same run number, it should give 
    1.29  the same output each time it is run.
    1.30  
    1.31 -By default, ns-3 simulations use random seeds where the seeding
    1.32 -is drawn from @code{/dev/random} (if it is available) or else from
    1.33 -the time of day.  A user who wants to fix the initial seeding
    1.34 -of the PRNG must call the following static method during simulation
    1.35 -configuration:
    1.36 -@verbatim
    1.37 -RandomVariable::UseGlobalSeed (uint32_t s0, s1, s2, s3, s4, s5);
    1.38 -@end verbatim
    1.39 -where the six parameters are each of type uint32_t.
    1.40 +By default, ns-3 simulations use a fixed seed and run number.
    1.41 +These values are stored in two @code{ns3::GlobalValue} instances:
    1.42 +@code{g_rngSeed} and @code{g_rngRun}.
    1.43  
    1.44  A typical use case is to run a simulation as a sequence of independent
    1.45  trials, so as to compute statistics on a large number of independent
    1.46  runs.  The user can either change the global seed and rerun the 
    1.47 -simulation, or can advance the substream state of the RNG.  
    1.48 +simulation, or can advance the substream state of the RNG, which is
    1.49 +referred to as incrementing the run number.  
    1.50 +
    1.51 +A class @code{ns3::SeedManager ()} provides an API to control
    1.52 +the seeding and run number behavior.
    1.53  This seeding and substream state setting must be called before any 
    1.54  random variables are created; e.g.
    1.55  
    1.56  @verbatim
    1.57 -  RandomVariable::UseGlobalSeed(1,2,3,4,5,6);
    1.58 -  int N = atol(argv[1]); //read in run number from command line
    1.59 -  RandomVariable::SetRunNumber(N);
    1.60 +  SeedManager::SetSeed (3);  // Changes seed from default of 1 to 3
    1.61 +  SeedManager::SetRun (7);  // Changes run number from default of 1 to 7
    1.62    // Now, create random variables
    1.63    UniformVariable x(0,10);
    1.64    ExponentialVariable y(2902);
    1.65 @@ -135,12 +141,29 @@
    1.66  @strong{Therefore, use the substream capability to produce
    1.67  multiple independent runs of the same simulation.}
    1.68  In other words, the more statistically rigorous way to configure
    1.69 -multiple independent replications is not to simply ignore the
    1.70 -seeding (and use /dev/random to seed the generator each time) but
    1.71 -instead to use a fixed seed and to iterate the run number.
    1.72 -This implementation allows for a maximum of
    1.73 +multiple independent replications is to use a fixed seed and to
    1.74 +advance the run number.  This implementation allows for a maximum of
    1.75  2.3x10^15 independent replications using the substreams. 
    1.76  
    1.77 +For ease of use, it is not necessary to control the seed and run number
    1.78 +from within the program; the user can set the 
    1.79 +@code{NS_GLOBAL_VALUE} environment variable as follows:
    1.80 +@verbatim
    1.81 +  NS_GLOBAL_VALUE="RngRun=3" ./waf --run program-name
    1.82 +@end verbatim
    1.83 +
    1.84 +Another way to control this is by passing a command-line argument; since
    1.85 +this is an ns3 GlobalValue instance, it is equivalently done such as follows:
    1.86 +@verbatim
    1.87 +  ./waf --command-template="%s --RngRun=3" --run program-name
    1.88 +@end verbatim
    1.89 +or, if you are running programs directly outside of waf:
    1.90 +@verbatim
    1.91 +  ./build/optimized/scratch/program-name --RngRun=3
    1.92 +@end verbatim
    1.93 +The above command-line variants make it easy to run lots of different
    1.94 +runs from a shell script by just passing a different RngRun index.
    1.95 +
    1.96  @node class RandomVariable
    1.97  @section class RandomVariable
    1.98