!===============================================================================
!
! ran/README - BQCD interface to random number generators
!
!-------------------------------------------------------------------------------
!
! Copyright (C) 2008-2016 Hinnerk Stueben
!
! This file is part of BQCD -- Berlin Quantum ChromoDynamics program
!
! BQCD is free software: you can redistribute it and/or modify
! it under the terms of the GNU General Public License as published by
! the Free Software Foundation, either version 3 of the License, or
! (at your option) any later version.
!
! BQCD is distributed in the hope that it will be useful,
! but WITHOUT ANY WARRANTY; without even the implied warranty of
! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
! GNU General Public License for more details.
!
! You should have received a copy of the GNU General Public License
! along with BQCD.  If not, see <http://www.gnu.org/licenses/>.
!
!-------------------------------------------------------------------------------

For each random number generator an interface is defined in:

    <name-of-random-number-generator>/ran.F90

It consists of the following routines:
(RAN_NAME, SEED, and REAL are defined in defs.h)


    RAN_NAME function ran_name()

            returns the name of the random number generator

    subroutine ran_init(seed)

            SEED, intent(in) :: seed
            initialises the random number generator

    REAL function ran_number()

            returns a random number

    subroutine ran_vector(n, x)

            integer, intent(in) :: n
            REAL, intent(out)   :: x(n)
            returns n random numbers in x

    subroutine ran_skip(n)

            integer, intent(in) :: n
            skips n random numbers

    subroutine ran_dump(unit)

            dumps the internal state to file
            if (unit == URAN) open(unit, file = ran_file()) (and close it later)
            else just write to unit 

    subroutine ran_restore(unit)

            restores the internal state from file written by ran_dump()  
            if (unit == URAN) open(unit, file = ran_file()) (and close it later)
            else just read from unit 

    SEED function ran_get_seed()

            returns the seed, if the internal state is given by a seed
            or -1 if this is not the case

    subroutine ran_check() 

            checks that internal state is identical on all processes

    subroutine ran_state_to_string(s)

            character(*), intent(out) :: s
            returns state of random number generator in s

    integer function ran_state_strlen()

            returns length of string needed in ran_state_to_string()

    subroutine ran_field(m, mx, field)

            use module_lattice
            integer, intent(in) :: m
            integer, intent(in) :: mx  ! typically: mx = nxh (or: mx = nx)
            REAL, intent(out)   :: field(m, 0:mx-1, 0:ny-1, 0:nz-1, 0:nt-1)

            fills 'field' with (parallel) random numbers in a way which is
            independent of the decomposition (-> results are independent
            of the decomposition)

!-------------------------------------------------------------------------------

Parallel random number generation is performed in the following way.

In general:  All processes have the same instance of the random number
generator.  Each process generates all random numbers but only picks the
ones that belong to its local lattice.  In principle that is not a
parallel operation. 

RANF: Because skipping an arbitrary number in the sequence of random
numbers is cheap, ranf runs in parallel (up to the overhead of
skipping).

RANLUX: For ranlux a 'field-parallel' mode was added, which is used if
'tuning_ran_field_parallel' is non-zero.  In that mode each process has
one instance of ranlux for global random numbers (Monte-Carlo acceptance
check) plus one instance for each xy-plane.  This is a compromise to
achieve the following goals:
- parallel random number generation (there is (Lz*Lt)-fold parallelism)
- results are independent of the number of processes used
- state/restart information is small (Lx*Ly*105) integers

!==============================================================================
