mom_random module reference

Provides gridded random number capability.

More…

Data Types

randomnumbersequence

A private type used by the Mersenne Twistor.

prng

Container for pseudo-random number generators.

Functions/Subroutines

random_01()

Returns a random number between 0 and 1.

random_01_cb()

Returns a random number between 0 and 1 See https://arxiv.org/abs/2004.06278 .

random_norm()

Returns an approximately normally distributed random number with mean 0 and variance 1.

random_2d_01()

Generates random numbers between 0 and 1 for each cell of the model grid.

random_2d_norm()

Returns an approximately normally distributed random number with mean 0 and variance 1 for each cell of the model grid.

random_0d_constructor()

Constructor for scalar PRNG.

random_2d_constructor()

Constructor for gridded PRNG.

seed_from_time()

Return a seed derived as hash of values in Time.

seed_from_index()

Create seed from position index.

random_destruct()

Destructor for PRNG.

new_randomnumbersequence()

Return an initialized twister using seed.

getrandomint()

Return a random integer on interval [0,0xffffffff].

getrandomreal()

Return a random real number on interval [0,1].

mixbits()

Merge bits of u and v.

twist()

Twist bits of u and v.

nextstate()

Update internal state of twister to the next state in the sequence.

temper()

Tempering of bits in y.

random_unit_tests()

Runs some statistical tests on the PRNG.

test_fn()

Convenience function for reporting result of test.

Detailed Description

Provides MOM6 implementation of the Mersenne Twistor, copied from the FMS implementation which was originally written by Robert Pincus ( Robert.Pincus@colorado.edu ). We once used the FMS implementation directly but since random numers do not need to be infrastructure specific, and because MOM6 should be infrastructure agnostic, we have copied the parts of MT that we used here.

Example usage:

type(PRNG)  ::  rng
real  ::  rn
call  random_0d_constructor(rng,  Time,  seed)  !  Call  this  each  time-step
rn  =  random_01(rng)
rn  =  random_norm(rng)

type(PRNG)  ::  rng
real,  dimension(:,:)  ::  rn2d
call  random_2d_constructor(rng,  HI,  Time,  seed)  !  Call  this  each  time-step
call  random_2d_01(rng,  HI,  rn2d)
call  random_2d_norm(rng,  HI,  rn2d)

Note:  reproducibility  across  restarts  is  implemented  by  using  time-derived
seeds  to  pass  to  the  Mersenne  twister.  It  is  therefore  important  that  any
PRNG  type  be  re-initialized  each  time-step.

Type Documentation

type mom_random/randomnumbersequence

A private type used by the Mersenne Twistor.

Type fields:
  • % currentelement [integer,private] :: Index into state vector.

  • % state [integer(0: blocksize -1),private] :: State vector.

type mom_random/prng

Container for pseudo-random number generators.

Type fields:
  • % stream0d [type( randomnumbersequence )] :: Scalar random number generator for whole model.

  • % stream2d [type( randomnumbersequence )(:,:),allocatable] :: Random number generator for each cell on horizontal grid.

Function/Subroutine Documentation

function mom_random/random_01(CS) [real]

Returns a random number between 0 and 1.

Parameters:

cs :: [inout] Container for pseudo-random number generators

Call to:

getrandomreal

Called from:

random_unit_tests

function mom_random/random_01_cb(ctr, key) [real]

Returns a random number between 0 and 1 See https://arxiv.org/abs/2004.06278 . Not an exact reproduction of “squares” because Fortran doesn’t have a uint64 type, and not all compilers provide integers with > 64 bits…

Parameters:
  • ctr :: [in] ctr should be incremented each time you call the function

  • key :: [in] key is like a seed: use a different key for each random stream

function mom_random/random_norm(CS) [real]

Returns an approximately normally distributed random number with mean 0 and variance 1.

Parameters:

cs :: [inout] Container for pseudo-random number generators

Call to:

getrandomreal

Called from:

random_unit_tests

subroutine mom_random/random_2d_01(CS, HI, rand)

Generates random numbers between 0 and 1 for each cell of the model grid.

Parameters:
  • cs :: [inout] Container for pseudo-random number generators

  • hi :: [in] Horizontal index structure

  • rand :: [out] Random numbers between 0 and 1

Call to:

getrandomreal

Called from:

random_unit_tests

subroutine mom_random/random_2d_norm(CS, HI, rand)

Returns an approximately normally distributed random number with mean 0 and variance 1 for each cell of the model grid.

Parameters:
  • cs :: [inout] Container for pseudo-random number generators

  • hi :: [in] Horizontal index structure

  • rand :: [out] Random numbers between 0 and 1

Call to:

getrandomreal

Called from:

mom_stoch_eos::mom_stoch_eos_init mom_stoch_eos::mom_stoch_eos_run random_unit_tests

subroutine mom_random/random_0d_constructor(CS, Time, seed)

Constructor for scalar PRNG. Can be used to reset the sequence.

Parameters:
  • cs :: [inout] Container for pseudo-random number generators

  • time :: [in] Current model time

  • seed :: [in] Seed for PRNG

Call to:

new_randomnumbersequence seed_from_time

Called from:

random_unit_tests

subroutine mom_random/random_2d_constructor(CS, HI, Time, seed)

Constructor for gridded PRNG. Can be used to reset the sequence.

Parameters:
  • cs :: [inout] Container for pseudo-random number generators

  • hi :: [in] Horizontal index structure

  • time :: [in] Current model time

  • seed :: [in] Seed for PRNG

Call to:

new_randomnumbersequence seed_from_index seed_from_time

Called from:

mom_stoch_eos::mom_stoch_eos_init mom_stoch_eos::mom_stoch_eos_run random_unit_tests

function mom_random/seed_from_time(Time) [integer]

Return a seed derived as hash of values in Time.

Parameters:

time :: [in] Current model time

Called from:

random_0d_constructor random_2d_constructor random_unit_tests

function mom_random/seed_from_index(HI, i, j) [integer]

Create seed from position index.

Parameters:
  • hi :: [in] Horizontal index structure

  • i :: [in] i-index (of h-cell)

  • j :: [in] j-index (of h-cell)

Called from:

random_2d_constructor random_unit_tests

subroutine mom_random/random_destruct(CS)

Destructor for PRNG.

Parameters:

cs :: Container for pseudo-random number generators

function mom_random/new_randomnumbersequence(seed) [type(randomnumbersequence)]

Return an initialized twister using seed.

Code was based on initialize_scaler() from the FMS implementation of the Mersenne Twistor

Parameters:

seed :: [in] Seed to initialize twister

Return:

undefined :: The Mersenne Twister container

Call to:

blocksize

Called from:

random_0d_constructor random_2d_constructor

function mom_random/getrandomint(twister) [integer]

Return a random integer on interval [0,0xffffffff].

Code was based on getRandomInt() from the FMS implementation of the Mersenne Twistor

Parameters:

twister :: [inout] The Mersenne Twister container

Call to:

blocksize nextstate temper

Called from:

getrandomreal

function mom_random/getrandomreal(twister) [precision]

Return a random real number on interval [0,1].

Code was based on getRandomReal() from the FMS implementation of the Mersenne Twistor

Call to:

getrandomint

Called from:

random_01 random_2d_01 random_2d_norm random_norm

function mom_random/mixbits(u, v) [integer]

Merge bits of u and v.

Parameters:
  • u :: [in] An integer

  • v :: [in] An integer

Call to:

lmask umask

Called from:

twist

function mom_random/twist(u, v) [integer]

Twist bits of u and v.

Parameters:
  • u :: [in] An integer

  • v :: [in] An integer

Call to:

mixbits

Called from:

nextstate

subroutine mom_random/nextstate(twister)

Update internal state of twister to the next state in the sequence.

Parameters:

twister :: [inout] Container for the Mersenne Twister

Call to:

blocksize m twist

Called from:

getrandomint

function mom_random/temper(y) [integer]

Tempering of bits in y.

Parameters:

y :: [in] An integer

Call to:

tmaskb tmaskc

Called from:

getrandomint

function mom_random/random_unit_tests(verbose) [logical]

Runs some statistical tests on the PRNG.

Parameters:

verbose :: True if results should be written to stdout

Call to:

random_01 random_0d_constructor random_2d_01 random_2d_constructor random_2d_norm random_norm seed_from_index seed_from_time test_fn

Called from:

mom_unit_tests::unit_tests

function mom_random/test_fn(verbose, good, label, rvalue, ivalue) [logical]

Convenience function for reporting result of test.

Parameters:
  • verbose :: [in] Verbosity

  • good :: [in] True if pass, false otherwise

  • label :: [in] Label for messages

  • rvalue :: [in] Result of calculation

  • ivalue :: [in] Result of calculation

Called from:

random_unit_tests