ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation. |
This module contains classes and procedures for computing various statistical quantities related to the univariate Uniform distribution. More...
Data Types | |
type | distUnif_type |
This is the derived type for signifying distributions that are of type Uniform as defined in the description of pm_distUnif. More... | |
interface | getUnifCDF |
Generate and return the Cumulative Distribution Function (CDF) of a univariate Standard Uniform distribution or a Uniform distribution with the specified support via lower and upper input arguments at the specified input values. More... | |
interface | getUnifRand |
Generate and return a scalar or a contiguous array of rank 1 of length s1 of randomly uniformly distributed discrete logical , integer , character value(s), or continuous real or `complex value(s) within the specified input range.More... | |
interface | getUnifRandState |
Generate and return an allocatable array of rank 1 containing the state vector of the Fortran default random number generator (RNG) or, optionally set the RNG state based on a reference input scalar seed, optionally distinctly on each processor. More... | |
interface | getUnifRandStateSize |
Generate and return the size of the seed vector of the Fortran default random number generator (RNG). More... | |
type | rngf_type |
This is a concrete derived type whose instances can be used to define/request the default uniform random number generator (RNG) of the Fortran standard. More... | |
interface | rngf_typer |
Generate and return a scalar object of type rngf_type. More... | |
type | rngu_type |
This is the abstract base derived type for defining various Uniform Random Number Generator (URNG) derived types.More... | |
interface | setUnifCDF |
Return the Cumulative Distribution Function (CDF) of a univariate Standard Uniform distribution or a Uniform distribution with the specified support via lower and upper input arguments at the specified input values. More... | |
interface | setUnifRand |
Return a uniform random scalar or contiguous array of arbitrary rank of randomly uniformly distributed discrete logical , integer , character value(s), or continuous real or `complex value(s) within the specified input range. More... | |
interface | setUnifRandState |
Set the state of the Fortran default random number generator (RNG) to a random value or to an optionally deterministic, optionally processor-dependent value based on the user-specified input scalar seed and processor ID. More... | |
type | splitmix64_type |
This is the derived type for declaring and generating objects of type splitmix64_type containing a unique instance of an splitmix64 random number generator (RNG). More... | |
interface | splitmix64_typer |
Generate, initialize, and return a scalar object of type splitmix64_type. More... | |
type | xoshiro256ss_type |
This is the abstract base derived type for defining variants of Xoshiro256** Uniform Random Number Generator derived types.More... | |
type | xoshiro256ssg_type |
This is the derived type for declaring and generating objects of type xoshiro256ssg_type containing a unique instance of a greedy Xoshiro256** random number generator (RNG). More... | |
interface | xoshiro256ssg_typer |
Generate, initialize, and return a scalar object of type xoshiro256ssg_type. More... | |
type | xoshiro256ssw_type |
This is the derived type for declaring and generating objects of type xoshiro256ssw_type containing a unique instance of a Xoshiro256** random number generator (RNG). More... | |
interface | xoshiro256ssw_typer |
Generate, initialize, and return a scalar object of type xoshiro256ssw_type. More... | |
Variables | |
character(*, SK), parameter | MODULE_NAME = "@pm_distUnif" |
integer(IK), parameter | xoshiro256ssStreamBitSize = int(bit_size(0_IK64), IK) |
The constant scalar of type integer of default kind containing the number of binary digits of the stream component Xoshiro256** random number generator.More... | |
integer(IK), parameter | xoshiro256ssStateSize = 4_IK |
The constant scalar of type integer of default kind IK containing the size of the state vector of Xoshiro256** random number generator.More... | |
integer(IK64), dimension(xoshiro256ssStateSize), parameter | xoshiro256ssJump128 = [ +1733541517147835066_IK64 , -3051731464161248980_IK64 , -6244198995065845334_IK64 , +4155657270789760540_IK64 ] |
The constant vector of size xoshiro256ssStateSize of type integer of kind IK64 containing the state jump for the Xoshiro256** random number generator.More... | |
integer(IK64), dimension(xoshiro256ssStateSize), parameter | xoshiro256ssJump192 = [ +8566230491382795199_IK64 , -4251311993797857357_IK64 , +8606660816089834049_IK64 , +4111957640723818037_IK64 ] |
The constant vector of size xoshiro256ssStateSize of type integer of kind IK64 containing the state jump for the Xoshiro256** random number generator.More... | |
type(rngf_type) | rngf |
The scalar constant object of type rngf_type whose presence signified the use of the Fortran intrinsic random number generator (RNGF). More... | |
This module contains classes and procedures for computing various statistical quantities related to the univariate Uniform distribution.
Specifically, this module contains routines for computing the following quantities of the univariate Uniform distribution:
The continuous uniform distributions or rectangular distributions are a family of symmetric probability distributions.
Such a distribution describes an experiment where there is an arbitrary outcome that lies between certain bounds.
The bounds are defined by the parameters, \(a\) and \(b\), which are the minimum and maximum values.
The interval can either be closed (i.e., \([a, b]\)) or open (i.e., \((a, b)\)).
Therefore, the distribution is often abbreviated as \(U(a,b)\) where \(U\) stands for uniform distribution.
The difference between the bounds defines the interval length.
All intervals of the same length on the distribution's support are equally probable.
Probability density function (PDF)
The PDF of the continuous uniform distribution is,
\begin{equation} f(x) = \begin{cases} \frac{1}{b - a} & \text{for} a\leq x \leq b ~, \\ 0 & \text{for} x < a ~ \text{or} ~ x > b ~. \end{cases} \end{equation}
The values of \(f(x)\) at the two boundaries \(a\) and \(b\) are usually unimportant, because they do not alter the value of \(\int_c^d f(x) dx\) over any interval \([c,d]\) nor of \(\int_a^b x f(x) dx\) nor of any higher moment.
Sometimes they are chosen to be zero, and sometimes chosen to be \(\frac{1}{b-a}\).
The latter is appropriate in the context of estimation by the method of maximum likelihood.
In the context of Fourier analysis, one may take the value of \(f(a)\) or \(f(b)\) to be \(\frac{1}{2(b - a)}\) because then the inverse transform of many integral transforms of this uniform function will yield back the function itself, rather than a function which is equal almost everywhere, i.e., except on a set of points with zero measure.
Also, it is consistent with the sign function, which has no such ambiguity.
Any probability density function integrates to \(1\).
Thus, the PDF of the continuous uniform distribution is graphically portrayed as a rectangle where \(b − a\) is the base length and \(\frac{1}{b-a}\) is the height.
As the base length increases, the height (the density at any particular value within the distribution boundaries) decreases.
In terms of mean \(\mu\) and variance \(\sigma^{2}\) the probability density function of the continuous uniform distribution is,
\begin{equation} f(x) = \begin{cases} \frac{1}{2\sigma\sqrt{3}} & \text{for} -\sigma\sqrt{3} \leq x - \mu \leq \sigma\sqrt{3} ~, \\ 0 & \text{otherwise} ~. \end{cases} \end{equation}
Cumulative distribution function (CDF)
The CDF of the continuous uniform distribution is,
\begin{equation} F(x) = \begin{cases} 0 & \text{for} x < a ~,\\ \frac{x - a}{b - a} & \text{for} a\leq x\leq b ~, \\ 1 & \text{for} x > b ~. \end{cases} \end{equation}
In terms of mean \(\mu\) and variance \(\sigma^{2}\), the cumulative distribution function of the continuous uniform distribution is,
\begin{equation} F(x) = \begin{cases} 0 & \text{for} x - \mu < -\sigma\sqrt{3} ~, \\ \frac{1}{2}\left(\frac{x - \mu}{\sigma\sqrt{3}} + 1\right) & \text{for} -\sigma\sqrt{3} \leq x - \mu < \sigma\sqrt{3} ~, \\ 1 & \text{for} x - \mu \geq \sigma\sqrt{3} \end{cases} \end{equation}
elemental
functions that accept optional
arguments of arbitrary ranks.elemental
procedures appear to incur no performance penalty with scalar arguments. However, there appears to exist a runtime performance penalty of ~2-3 times more than the rank-specific routines for array arguments, comparable to 10-20 CPU cycles.elemental
procedures for array arguments.elemental
performance penalty is likely insignificant in most practical cases, unless the elemental
procedures are to be called on the order of tens of billions of times in a program, in which, case, the over all performance penalty, as of 2022, appears to be on the order of a few minutes or less.elemental
procedures and remove the overhead of repeatedly calling the elemental
function.Inverse Cumulative distribution function (ICDF) or Quantile Function
The Quantile function of continuous Uniform distribution is given by,
\begin{equation} F^{-1}(p) = a + p(b - a) \quad \text{for} 0 < p < 1 ~. \end{equation}
In terms of mean \(\mu\) and variance \(\sigma^{2}\), the Quantile function of the continuous uniform distribution is,
\begin{equation} F^{-1}(p) = \sigma\sqrt{3} (2p - 1) + \mu \quad \text{for} 0 \leq p \leq 1 ~. \end{equation}
Random Number Generation (RNG)
This module contains two generic functional and subroutine interfaces
for generating uniformly distributed random values of all intrinsic types and kinds supported by the Fortran standard and the processor (character
, integer
, logical
, complex
, real
).
The functional interface is merely a wrapper around the generic subroutine interface.
This module also contains four random number generator (RNG) algorithms that can be specified via the corresponding types,
random_number()
) Usage
logical
random values, although it can be used for random value generation of any type and kind.
Benchmark :: The runtime performance of scalar getUnifCDF vs. setUnifCDF without bounds ⛓
ifort
compiler ⛓ ifort
compiler ⛓ gfortran
compiler ⛓ elemental
functions with optional
arguments. In the absence of the optional
arguments, the default values are used, but the associated computations will be redundant.
Benchmark :: The runtime performance of array getUnifCDF vs. setUnifCDF without bounds ⛓
ifort
compiler ⛓ ifort
compiler ⛓ gfortran
compiler ⛓ elemental
functions with optional
arguments.optional
arguments, the default values are used, but the associated computations will be redundant.elemental
functions incur a performance penalty for input array arguments due to internal looping performed by the compiler to call the function repeatedly for different array elements.
Benchmark :: The runtime performance of scalar getUnifCDF vs. setUnifCDF with bounds ⛓
ifort
compiler ⛓ ifort
compiler ⛓ gfortran
compiler ⛓ elemental
functions with optional
arguments.optional
arguments, the user-specified values are used.
Benchmark :: The runtime performance of array getUnifCDF vs. setUnifCDF with bounds ⛓
ifort
compiler ⛓ ifort
compiler ⛓ gfortran
compiler ⛓ elemental
functions with optional
arguments.optional
arguments, the user-specified values are used.elemental
functions incur a performance penalty for input array arguments due to internal looping performed by the compiler to call the function repeatedly for different array elements, the costs of computations in getUnifCDF become more comparable to the procedures under the generic interface setUnifCDF which are rank-specific and carefully designed to avoid redundant computations.
Benchmark :: The runtime performance of setUnifRand vs. Fortran intrinsic random_number()
. ⛓
ifort
compiler ⛓ ifort
compiler ⛓ gfortran
compiler ⛓ random_number()
.random_number()
.integer
, logical
, complex
, or character
uniform random RNG whereas setUnifRand provides a unified API for random numbers of all types.
Benchmark :: The runtime performance of intrinsic random_number()
vs. splitmix64_type vs. xoshiro256ssw_type. ⛓
ifort
compiler ⛓ ifort
compiler ⛓ gfortran
compiler ⛓ gfortran
and Intel Classic Fortran Compiler ifort
.logical
random number generation, use the greedy xoshiro256ssg_type RNG.
Final Remarks ⛓
If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.
This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.
character(*, SK), parameter pm_distUnif::MODULE_NAME = "@pm_distUnif" |
Definition at line 284 of file pm_distUnif.F90.
type(rngf_type) pm_distUnif::rngf |
The scalar constant object of type rngf_type whose presence signified the use of the Fortran intrinsic random number generator (RNGF).
This constant is merely a convenience for making easier calls to routines that require a default RNGF.
Possible calling interfaces ⛓
ifort
version 2021.8.0 20221119 ifort
cannot handle the creation of a module constant of type rngf_type as done for this object, yielding the following error. GNU compiler compiles and runs the code without complaining.
Remedy (as of ParaMonte Library version 2.0.0): For now, the parameter
attribute is removed from the declaration of rngf.
Final Remarks ⛓
If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.
This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.
Definition at line 2886 of file pm_distUnif.F90.
integer(IK64), dimension(xoshiro256ssStateSize), parameter pm_distUnif::xoshiro256ssJump128 = [ +1733541517147835066_IK64 , -3051731464161248980_IK64 , -6244198995065845334_IK64 , +4155657270789760540_IK64 ] |
The constant vector of size xoshiro256ssStateSize of type integer
of kind IK64 containing the state jump for the Xoshiro256** random number generator.
This state jump can be passed to the constructor of xoshiro256ssw_type to request an RNG whose state starts at imageID * 2**128
steps (i.e., random number generations) ahead of the RNG constructed with imageID = 1
.
Using this jump, one can generate 2**128
independent RNG sequences each of which has a period of 2**128
in parallel applications.
For more information see the documentation of xoshiro256ssg_type and xoshiro256ssw_type.
The elements of this constant vector are obtained by transferring the following unsigned integers to signed values.
Final Remarks ⛓
If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.
This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.
Definition at line 2675 of file pm_distUnif.F90.
integer(IK64), dimension(xoshiro256ssStateSize), parameter pm_distUnif::xoshiro256ssJump192 = [ +8566230491382795199_IK64 , -4251311993797857357_IK64 , +8606660816089834049_IK64 , +4111957640723818037_IK64 ] |
The constant vector of size xoshiro256ssStateSize of type integer
of kind IK64 containing the state jump for the Xoshiro256** random number generator.
This state jump can be passed to the constructor of xoshiro256ssw_type to request an RNG whose state starts at imageID * 2**192
steps (i.e., random number generations) ahead of the RNG constructed with imageID = 1
.
Using this jump, one can generate 2**64
independent RNG sequences each of which has a period of 2**192
in parallel applications.
For more information see the documentation of xoshiro256ssg_type and xoshiro256ssw_type.
The elements of this constant vector are obtained by transferring the following unsigned integers to signed values.
Final Remarks ⛓
If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.
This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.
Definition at line 2715 of file pm_distUnif.F90.
integer(IK), parameter pm_distUnif::xoshiro256ssStateSize = 4_IK |
The constant scalar of type integer
of default kind IK containing the size of the state vector of Xoshiro256** random number generator.
For more information see the documentation of xoshiro256ssg_type and xoshiro256ssw_type.
Final Remarks ⛓
If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.
This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.
Definition at line 2641 of file pm_distUnif.F90.
integer(IK), parameter pm_distUnif::xoshiro256ssStreamBitSize = int(bit_size(0_IK64), IK) |
The constant scalar of type integer
of default kind containing the number of binary digits of the stream
component Xoshiro256** random number generator.
By definition, this number is 64
, because the type kind parameter of stream
is IK64.
Final Remarks ⛓
If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.
This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.
Definition at line 2619 of file pm_distUnif.F90.