mom_random module reference

Provides gridded random number capability.

More…

Data Types

prng

Container for pseudo-random number generators.

randomnumbersequence

A private type used by the Mersenne Twistor.

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/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.

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.

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

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

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