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.
- Parameters
-
[in,out] | rng | : The input/output scalar of type,
-
rngf_type, or
-
splitmix64_type, or
-
xoshiro256ssg_type,
-
xoshiro256ssw_type,
containing the user-specified random number generator algorithm to be used.
The user must initialize the object with the corresponding type constructors if non-deterministic RNG are desired. (optional, default = rngf_type) |
[in] | lb | : The input scalar (or array of the same shape as the desired output rand and other input array-like arguments) of the same type and kind as the output rand , representing the lower bound of the Uniform distribution.
If the output random value rand is to be of type logical , then lb , if present, must be logical(.false., kind = kind(rand)) .
If the input argument s1 is present, then lb must be a scalar.
(optional, default = .false. ) |
[in] | ub | : The input scalar or array of the same type, kind, rank, and shape as lb , representing the upper bound of the Uniform distribution.
If the input argument s1 is present, ub must be a scalar.
If the output random value rand is to be of type logical , then ub , if present, must be logical(.true., kind = kind(rand)) .
(optional, default = .true. ) |
[in] | s1 | : The input scalar of type integer of default kind IK, representing the size of the output rand array along its first dimension.
(optional. It must be present if s2 is present. If missing, the rank and size of the output rand is that of lb or ub with a non-zero rank.) |
[in] | s2 | : The input scalar of type integer of default kind IK, representing the size of the output rand array along its second dimension.
(optional. It must be present if s3 is present. If missing, the rank and size of the output rand is that of lb or ub with a non-zero rank.) |
- Returns
rand
: The output scalar or vector of rank 1
of length s1
or array of the same shape as the non-zero rank of the input lb
and ub
, containing the uniformly-distributed random output value(s).
If lb
and ub
are missing, then the output rand
is of type logical
of default kind LK.
Otherwise, it is either of,
-
type
character
of the same kind as lb
and ub
, of the same length type parameter len
as that of lb
and ub
or,
-
type
integer
of the same kind as lb
and ub
, or
-
type
logical
of the same kind as lb
and ub
, or
-
type
complex
of the same kind as lb
and ub
, or
-
type
real
of the same kind as lb
and ub
.
Note that,
-
If
lb
is of type character
, then the random characters will be drawn from the character collating sequence of the processor.
-
If
lb
and ub
are of type integer
, then rand
will be in the interval [lb, ub]
.
-
If
lb
and ub
are of type real
, then rand
will be in the interval [lb, ub)
.
-
If
lb
and ub
are of type character
, then rand
will be in the interval [lb, ub]
as defined by the processor collating sequence.
-
If
lb
and ub
are of type complex
, then rand%re
and rand%im
will be in the intervals [lb%re, ub%re)
and [lb%im, ub%im)
respectively.
-
If
lb
and ub
are both missing, then the output will be a logical
of default kind LK with possible values .false._LK
and .true._LK
.
Possible calling interfaces ⛓
rand(
1:s1,
1:s2,
1:s3)
= getUnifRand(rng, lb, ub, s1, s2, s3)
!
Generate and return a scalar or a contiguous array of rank 1 of length s1 of randomly uniformly distr...
This module contains classes and procedures for computing various statistical quantities related to t...
- Warning
- The condition
len(lb) == len(ub) .or. len(lb) == 1 .or. len(ub) == 1
for the corresponding input arguments of type character
.
The condition lb <= ub
must hold for the corresponding input arguments where logical values are compared by the procedures of module pm_logicalCompare and complex values are compared by the procedures of module pm_complexCompareAll.
These conditions are verified only if the library is built with the preprocessor macro CHECK_ENABLED=1
.
- Note
- The interface
getUnifRand()
corresponds to coin-flipping experiment with two possible outputs: .true.
(head) and .false.
(tail).
See isHead for generating values from a biased-coin flipping experiment.
-
By default random characters are generated from the ASCII collating sequence to ensure portability across compilers and platforms.
If random uniform characters from the processor collating sequence are desired, specify the lb
and ub
inputs argument as integer
s of default kind IK, such that the random numbers are generated from the processor-dependent character interval [char(lb), char(ub)]
.
- See also
- rngf
isHead
getUnifCDF
getUnifRand
setUnifRand
getUnifRandState
setUnifRandState
rngu_type
rngf_type
splitmix64_type
xoshiro256ssw_type
getUnifRandStateSize
Example usage ⛓
12 integer(IK) ,
parameter :: NP
= 5_IK
14 character(
5,SK) :: rand_D0_SK
15 character(
2,SK) :: rand_D1_SK(NP)
16 integer(IK) :: rand_D0_IK, rand_D1_IK(NP)
17 complex(CK) :: rand_D0_CK, rand_D1_CK(NP)
18 real(RK) :: rand_D0_RK, rand_D1_RK(NP)
20 type(display_type) :: disp
26 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
27 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
28 call disp%show(
"! Generate `logical`-valued random numbers.")
29 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
30 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
34 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
35 call disp%show(
"! Generate a scalar logical random number.")
36 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
39 call disp%show(
"getUnifRand() ! single random coin flipping `logical` result in the default range [.false._LK, .true._LK].")
44 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
45 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
46 call disp%show(
"! Generate random `character` values.")
47 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
48 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
52 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
53 call disp%show(
"! Generate a scalar character random value.")
54 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
57 call disp%show(
"rand_D0_SK = getUnifRand(lb = SK_'AA0aa', ub = SK_'ZZ9zz') ! random ASCII character in the specified range per single character.")
58 rand_D0_SK
= getUnifRand(lb
= SK_
'AA0aa', ub
= SK_
'ZZ9zz')
60 call disp%show( rand_D0_SK , deliml
= SK_
"""" )
64 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
65 call disp%show(
"! Generate a vector of character random values.")
66 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
69 call disp%show(
"rand_D1_SK = getUnifRand(lb = SK_'Aa', ub = SK_'Zz', s1 = size(rand_D1_SK, kind = IK)) ! random ASCII character in the range [""Aa"", ""Zz""] per character in string separately.")
70 rand_D1_SK
= getUnifRand(lb
= SK_
'Aa', ub
= SK_
'Zz', s1
= size(rand_D1_SK,
kind = IK))
72 call disp%show( rand_D1_SK , deliml
= SK_
"""" )
77 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
78 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
79 call disp%show(
"! Generate `integer`-valued random numbers.")
80 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
81 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
85 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
86 call disp%show(
"! Generate a scalar integer random number.")
87 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
90 call disp%show(
"rand_D0_IK = getUnifRand(-3_IK, 2_IK) ! random integer in range [-3 2].")
97 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
98 call disp%show(
"! Generate a vector of integer random numbers.")
99 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
102 call disp%show(
"rand_D1_IK = getUnifRand(-3_IK, 2_IK, s1 = size(rand_D1_IK, kind = IK)) ! random integer in range [-3 2].")
103 rand_D1_IK
= getUnifRand(
-3_IK,
2_IK, s1
= size(rand_D1_IK,
kind = IK))
108 call disp%show(
"getUnifRand([0_IK, 5_IK, 10_IK], 15_IK)")
112 call disp%show(
"getUnifRand([0_IK, 6_IK, 11_IK], [5_IK, 10_IK, 15_IK])")
118 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
119 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
120 call disp%show(
"! Generate `complex`-valued random numbers.")
121 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
122 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
126 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
127 call disp%show(
"! Generate a scalar complex random number.")
128 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
131 call disp%show(
"rand_D0_CK = getUnifRand(lb = (-3._CK, -2._CK), ub = (2._CK, 3._CK)).")
132 rand_D0_CK
= getUnifRand(lb
= (
-3._CK,
-2._CK), ub
= (
2._CK,
3._CK))
138 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
139 call disp%show(
"! Generate a vector of complex random numbers.")
140 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
142 call disp%show(
"rand_D1_CK = getUnifRand((-3._CK, 2._CK), (2._CK, 4._CK), s1 = size(rand_D1_CK, kind = IK)).")
143 rand_D1_CK
= getUnifRand((
-3._CK,
2._CK), (
2._CK,
4._CK), s1
= size(rand_D1_CK,
kind = IK))
150 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
151 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
152 call disp%show(
"! Generate `real`-valued random numbers.")
153 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
154 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
158 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
159 call disp%show(
"! Generate a scalar real random number.")
160 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
163 call disp%show(
"rand_D0_RK = getUnifRand(-3._RK, 2._RK) ! random real in range [-3 2].")
170 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
171 call disp%show(
"! Generate a vector of real random numbers.")
172 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
175 call disp%show(
"rand_D1_RK = getUnifRand(-3._RK, 2._RK, s1 = size(rand_D1_RK, kind = IK)) ! random real in range [-3 2].")
176 rand_D1_RK
= getUnifRand(
-3._RK,
2._RK, s1
= size(rand_D1_RK,
kind = IK))
184 integer :: fileUnit,i
185 open(newunit
= fileUnit, file
= "main.unif.rand.txt")
186 write(fileUnit,
"(2(g0,:,','))")
getUnifRand((
0._CK,
100._CK), (
100._CK,
150._CK), s1
= 500_IK)
This is a generic method of the derived type display_type with pass attribute.
This is a generic method of the derived type display_type with pass attribute.
This module contains classes and procedures for input/output (IO) or generic display operations on st...
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
integer, parameter RK
The default real kind in the ParaMonte library: real64 in Fortran, c_double in C-Fortran Interoperati...
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
integer, parameter CKS
The single-precision complex kind in Fortran mode. On most platforms, this is a 32-bit real kind.
integer, parameter CK
The default complex kind in the ParaMonte library: real64 in Fortran, c_double_complex in C-Fortran I...
integer, parameter IKS
The single-precision integer kind in Fortran mode. On most platforms, this is a 32-bit integer kind.
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
integer, parameter RKS
The single-precision real kind in Fortran mode. On most platforms, this is an 32-bit real kind.
Generate and return an object of type display_type.
Example Unix compile command via Intel ifort
compiler ⛓
3ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
Example Windows Batch compile command via Intel ifort
compiler ⛓
2set PATH=..\..\..\lib;%PATH%
3ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
Example Unix / MinGW compile command via GNU gfortran
compiler ⛓
3gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
Example output ⛓
28rand_D0_SK
= getUnifRand(lb
= SK_
'AA0aa', ub
= SK_
'ZZ9zz')
37rand_D1_SK
= getUnifRand(lb
= SK_
'Aa', ub
= SK_
'Zz', s1
= size(rand_D1_SK,
kind = IK))
39"Tx",
"Ga",
"Gb",
"Co",
"Ra"
62rand_D1_IK
= getUnifRand(
-3_IK,
2_IK, s1
= size(rand_D1_IK,
kind = IK))
69getUnifRand([
0_IK,
6_IK,
11_IK], [
5_IK,
10_IK,
15_IK])
84rand_D0_CK
= getUnifRand(lb
= (
-3._CK,
-2._CK), ub
= (
2._CK,
3._CK)).
86(
-1.67726970,
-0.527853787)
93rand_D1_CK
= getUnifRand((
-3._CK,
2._CK), (
2._CK,
4._CK), s1
= size(rand_D1_CK,
kind = IK)).
95(
-0.177443147,
+3.85852003), (
-1.46542192,
+2.05900240), (
-0.464476347E-1,
+2.60506773), (
+0.660932064E-2,
+3.58348203), (
+1.71687555,
+2.33132100)
118rand_D1_RK
= getUnifRand(
-3._RK,
2._RK, s1
= size(rand_D1_RK,
kind = IK))
120-2.02551842,
-0.292747021E-1,
-1.13210428,
-2.74293470,
-0.808377147
Postprocessing of the example output ⛓
3import matplotlib.pyplot
as plt
7rand = pd.read_csv(
"main.unif.rand.txt")
9fig = plt.figure(figsize = 1.25 * np.array([6.4, 4.8]), dpi = 200)
12plt.plot( rand.values[:, 0]
18ax.set_xlabel(
"Real Random Component", fontsize = 17)
19ax.set_ylabel(
"Imaginary Random Component", fontsize = 17)
20ax.set_title(
"A scatter plot of Complex-valued random numbers".format(len(rand)), fontsize = 17)
22plt.grid(visible =
True, which =
"both", axis =
"both", color =
"0.85", linestyle =
"-")
23ax.tick_params(axis =
"y", which =
"minor")
24ax.tick_params(axis =
"x", which =
"minor")
26plt.savefig(
"getUnifRand.CK.png")
Visualization of the example output ⛓
- Test:
- test_pm_distUnif
- Todo:
- The current random
integer
generator uses a simple double precision real
conversion to integer
values.
While this works fairly well for most use cases, it may biased for generating large random integer
of kind IK4.
A future remedy should use Bitmask with Rejection as described here.
As of 2021, the use of double precision (64-bit) vs. single-precision for random number generation increases the computational cost of the algorithms by about three times.
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.
-
If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
-
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
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.
- Copyright
- Computational Data Science Lab
- Author:
- Amir Shahmoradi, Oct 16, 2009, 11:14 AM, Michigan
Definition at line 4150 of file pm_distUnif.F90.