c_cpp/etc/calc/help/srand

   1 NAME
   2     srand - seed the subtractive 100 shuffle pseudo-random number generator
   3
   4 SYNOPSIS
   5     srand([seed])
   6
   7 TYPES
   8     seed        integer, matrix of integers or rand state
   9
  10     return      rand state
  11
  12 DESCRIPTION
  13     Seed the pseudo-random number using an subtractive 100 shuffle generator.
  14
  15     For integer seed != 0:
  16
  17         Any buffered rand generator bits are flushed.  The subtractive table
  18         for the rand generator is loaded with the default subtractive table.
  19         The low order 64 bits of seed is xor-ed against each table value.
  20         The subtractive table is shuffled according to seed/2^64.
  21
  22         The following calc code produces the same effect on the internal
  23         subtractive table:
  24
  25             /* reload default subtractive table xor-ed with low 64 seed bits */
  26             seed_xor = seed & ((1<<64)-1);
  27             for (i=0; i < 100; ++i) {
  28                 subtractive[i] = xor(default_subtractive[i], seed_xor);
  29             }
  30
  31             /* shuffle the subtractive table */
  32             seed >>= 64;
  33             for (i=100; seed > 0 && i > 0; --i) {
  34                 quomod(seed, i+1, seed, j);
  35                 swap(subtractive[i], subtractive[j]);
  36             }
  37
  38         Seed must be >= 0.  All seed values < 0 are reserved for future use.
  39
  40         The subtractive table pointers are reset to subtractive[36]
  41         and subtractive[99].  Last the shuffle table is loaded with
  42         successive values from the subtractive 100 generator.
  43
  44         There is no limit on the size of a seed.  On the other hand,
  45         extremely large seeds require large tables and long seed times.
  46         Using a seed in the range of [2^64, 2^64 * 100!) should be
  47         sufficient for most purposes.  An easy way to stay within this
  48         range to to use seeds that are between 21 and 178 digits, or
  49         64 to 588 bits long.
  50
  51         To help make the generator produced by seed S, significantly
  52         different from S+1, seeds are scrambled prior to use.  The
  53         internal function randreseed64 maps [0,2^64) into [0,2^64) in a
  54         1-to-1 and onto fashion for every 64 bits of S.
  55
  56         The purpose of the randreseed64() is not to add security.  It
  57         simply helps remove the human perception of the relationship
  58         between the seed and the production of the generator.
  59
  60         The randreseed64 process does not reduce the security of the
  61         rand generator.  Every seed is converted into a different
  62         unique seed.  No seed is ignored or favored.  See the rand
  63         help file for details.
  64
  65     For integer seed == 0:
  66
  67         Restore the initial state and modulus of the rand generator.
  68         After this call, the rand generator is restored to its initial
  69         state after calc started.
  70
  71         The subtractive 100 pointers are reset to subtractive[36]
  72         and subtractive[99].  Last the shuffle table is loaded with
  73         successive values from the subtractive 100 generator.
  74
  75         The call:
  76
  77             srand(0)
  78
  79         restores the rand generator to the initial conditions at calc startup.
  80
  81     For matrix arg:
  82
  83         Any buffered random bits are flushed.  The subtractive table with the
  84         first 100 entries of the matrix mod 2^64.
  85
  86         The subtractive 100 pointers are reset to subtractive[36]
  87         and subtractive[99].  Last the shuffle table is loaded with
  88         successive values from the subtractive 100 generator.
  89
  90         This form allows one to load the internal subtractive 100 generator
  91         with user supplied values.
  92
  93         The randreseed64 process is NOT applied to the matrix values.
  94
  95     For rand state arg:
  96
  97         Restore the rand state and return the previous state.  Note that
  98         the argument state is a rand state value (isrand(state) is true).
  99         Any internally buffered random bits are restored.
 100
 101         All calls to srand(seed) return the previous state or current
 102         state in case of srand().  Their return value can be supplied
 103         to srand in restore the generator to that previous state:
 104
 105              state = srand(123456789);
 106              newstate = srand();        /* save state */
 107
 108              x = rand();
 109              ...
 110              srand(newstate);   /* restore state to after srand(123456789) */
 111              x1 = rand();       /* produces the same value as x */
 112              ...
 113              srand(state);      /* restore original state */
 114
 115     For no arg given:
 116
 117         Return current s100 generator state.  This call does not alter
 118         the generator state.
 119
 120         This call allows one to take a snapshot of the current generator state.
 121
 122     See the rand help file for details on the generator.
 123
 124 EXAMPLE
 125     ; srand(0x8d2dcb2bed3212844f4ad31)
 126             RAND state
 127     ; state = srand();
 128     ; print rand(123), rand(123), rand(123), rand(123), rand(123), rand(123);
 129     80 95 41 78 100 27
 130     ; print rand(123), rand(123), rand(123), rand(123), rand(123), rand(123);
 131     122 109 12 95 80 32
 132     ; state2 = srand(state);
 133     ; print rand(123), rand(123), rand(123), rand(123), rand(123), rand(123);
 134     80 95 41 78 100 27
 135     ; print rand(123), rand(123), rand(123), rand(123), rand(123), rand(123);
 136     122 109 12 95 80 32
 137     ; state3 = srand();
 138     ; print state3 == state2;
 139     1
 140     ; print rand();
 141     10710588361472584495
 142
 143 LIMITS
 144     for matrix arg, the matrix must have at least 100 integers
 145
 146 LINK LIBRARY
 147     RAND *zsrand(ZVALUE *pseed, MATRIX *pmat100)
 148     RAND *zsetrand(RAND *state)
 149
 150 SEE ALSO
 151     seed, srandom, randbit, isrand, random, srandom, israndom
 152
 153 ## Copyright (C) 1999  Landon Curt Noll
 154 ##
 155 ## Calc is open software; you can redistribute it and/or modify it under
 156 ## the terms of the version 2.1 of the GNU Lesser General Public License
 157 ## as published by the Free Software Foundation.
 158 ##
 159 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 160 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 161 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 162 ## Public License for more details.
 163 ##
 164 ## A copy of version 2.1 of the GNU Lesser General Public License is
 165 ## distributed with calc under the filename COPYING-LGPL.  You should have
 166 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 167 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 168 ##
 169 ## @(#) $Revision: 30.1 $
 170 ## @(#) $Id: srand,v 30.1 2007/03/16 11:10:42 chongo Exp $
 171 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/srand,v $
 172 ##
 173 ## Under source code control:   1996/01/01 04:19:07
 174 ## File existed as early as:    1996
 175 ##
 176 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 177 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/