Structure Diagram for RAN: Random Number Generator
                    ==================================================
 
         An Introduction to the Structure Diagrams is available.
        NB  These links will be broken until the HTML Version of the Code is installed.
 
 
Introduction
------------

RAN is the random number generator used by SNOMAN. It uses "universal"
lagged-Fibonacci method of Marsaglia, Zaman and Tang.
     
Calling SNORAN
--------------

The parameter ICALL is not used within the routine.  It serves to
avoid a subtle possible bug, which is that some compilers will
optimize a function called twice within a line or within a loop to
have the same returned value.  By using different values for ICALL in
the function call this can be avoided.  The recommended convention is
as follows:-

 1)  For code that is not in any kind of a loop, use arguments
     1,2,3...  e.g.

     x = snoran(1)
     y = snoran(2) * cos (snoran(3))

 2)  For all other code have a counter that is used as the argument
     and increment it by units of 100 to avoid conflicts with 1)
     and to allow multiple calls per line.  E.g.

       integer  i_snoran

       i_snoran = 0
       i_snoran = i_snoran + 100

       x = snoran(i_snoran)
       i_snoran = i_snoran + 100
       y = snoran(i_snoran) * cos (snoran(i_snoran+1))


Calling SNORAN during initialisation
------------------------------------

A powerful debug facility is the ability to regenerate any event
simply by running SNOMAN again and resetting the random number
generator to the value at the start of the event. However this
requires that no random numbers are consumed during initialisation, as
these move the random number sequence on so that the event would not
receive the same number as when SNOMAN was run the first time.
However there are situations were random numbers are needed during
initialisation, for example to set up some spectrum which will
subsequently be sampled. The solution is to have two random number
generators, one for initialisation and the other for normal execution.
There is a single interface to the two generators (snoran) and
selection is made via this subroutine.  All initialisation code has to
be bracketed by:-

   snoran_select(2)

      initialisation code

   snoran_select(1)

to ensure that it uses the alternative generator.

Selecting Seed Sequences
------------------------

These can be set using the symbolic commands:-

  $starting_seed   n1  n2  n3  (for normal execution)
  $starting_seed_2 n1  n2  n3  (for initialisation)

In both cases, n1 and n2 define the sequence and n3 the position
within the sequence. Valid values are:-

  1 <= n1 <= 31328
  1 <= n2 <= 30081
  0 <= n3 <= 999999999

If the two seed sequences numbers n1,n2 for the normal execution 
are set equal to the corresponding numbers in the initialisation
sequence then all seeds are taken from the normal execution
sequence.

IMPORTANT:  Currently only the main seed sequence is recorded in
the event data structure and reported when there are problems so
it is recommended that, for normal production work, the sequence
used for  initialisation is left at its default (as defined by
the SEED.2 titles bank) of:-

      31328 30080 0


Titles Banks Used
-----------------
 
SEED
 
 
Initialisation Routines
-----------------------
 
SNORAN_INI
SNORAN_SET
 
 
Execution Routines
------------------
 
SNORAN
SNORAN_SELECT
 
Termination Routines
--------------------
 
SNORAN_TRM