Probability Distribution and Statistical Functions -- Uniform Distribution Module

doc/specs/index.md

@@ -17,6 +17,7 @@ This is and index/directory of the specifications (specs) for each new module/fe
  - [optval](./stdlib_optval.html) - Fallback value for optional arguments
  - [quadrature](./stdlib_quadrature.html) - Numerical integration
  - [stats](./stdlib_stats.html) - Descriptive Statistics
+ - [stats_distribution_PRNG](./stdlib_stats_distribution_PRNG.html) - Probability Distributions random number generator
 
 ## Missing specs
 

doc/specs/stdlib_stats_distribution_uniform.md

@@ -0,0 +1,344 @@
+---
+title: stats_distribution
+---
+
+# Statistical Distributions Uniform Module
+
+[TOC]
+
+## `shuffle` - Using Fisher-Yates algorithm to generate a random permutation of a list.
+
+### Status
+
+Experimental
+
+### Description
+
+Applying Fisher-Yates algorithm to generate an unbiased permutation for any list of intrinsic numerical data types.
+
+### Syntax
+
+`result = [[stdlib_stats_distribution_uniform(module):shuffle(interface)]]( list )`
+
+### Arguments
+
+`list`: argument has intent `in` and is a rank one array of integer, real, or complx type.
+
+### Return value
+
+Return a randomized rank one array of the input type.
+
+### Example
+
+```fortran
+program demo_shuffle
+    use stdlib_stats_distribution_PRNG, only : random_seed
+    use stdlib_stats_distribution_uniform, only : shuffle
+    implicit none
+    integer :: seed_put, seed_get, i
+    real :: x(10)
+    integer :: n(10)
+    complex :: z(10)
+
+    do i=1, 10
+        n(i) = i
+        x(i) = real(i)
+        z(i) = cmplx(real(i), real(i))
+    end do
+    seed_put = 32165498
+    call random_seed(seed_put, seed_get)    ! set and get current value of seed
+    n = shuffle(n)                          ! get randomized n
+![10, 6, 9, 2, 8, 1, 3, 5, 7, 4]
+    x = shuffle(x)                          ! get randomized x
+! [5.0, 10.0, 9.0, 4.0, 3.0, 8.0, 2.0, 1.0, 7.0, 6.0]
+    z = shuffle(z)                          ! get randomized z
+![(8.0, 8.0), (7.0, 7.0), (4.0, 4.0), (1.0, 1.0), (5.0, 5.0), (9.0, 9.0),
+!(6.0, 6.0), (3.0, 3.0), (2.0, 2.0), (10.0, 10.0)]
+end program demo_shuffle
+```
+
+## `uniform_distribution_rvs` - uniform distribution random variates
+
+### Status
+
+Experimental
+
+### Description
+
+Without augument the function returns a scalar standard uniformly distributed variate U(0,1) of real type with single precision on [0,1].
+
+With single augument `scale` of integer type the function returns a scalar uniformly distributed variate of integer type on [0,scale]. This is the standard Rectangular distribtuion. Function is elemental.
+
+With single augument `scale` of real or complx type the function returns a scalar uniformly distributed variate of real or complx type on [0, scale]. The real part and imaginary part of a complx type are independent of each other. Function is elemental.
+
+With double auguments `loc` and `scale` the function returns a scalar uniformly distributed random variates of integer, real or complx type on [loc, loc + scale] dependent of input type. If it is complex augument, the real part and imaginary part are independent of each other. Function is elemental.
+
+With triple auguments `loc`, `scale` and `array_size` the function returns a rank one array of uniformly distributed variates of integer, real or complx type with an array size of `array_size`.
+
+### Syntax
+
+`result = [[stdlib_stats_distribution_uniform(module):uniform_distribution_rvs(interface)]]([[loc,] scale] [[[,array_size]]])`
+
+### Arguments
+
+`loc`: optional argument has intent `in` and is a scalar of type `integer`, `real` or `complx`.
+
+`scale`: optional argument has intent `in` and is a scalar of type `integer`, `real` or `complx`.
+
+`array_size`: optional argument has intent `in` and is a scalar of type `integer`.
+
+`loc` and `scale` must have the same type when both are present.
+
+### Return value
+
+The result is a scalar or a rank one array, with size of `array_size`, of type `integer`, `real` or `complx` depending on the input type.
+
+### Example
+
+```fortran
+program demo_uniform_rvs
+    use stdlib_stats_distribution_PRNG, only:random_seed
+    use stdlib_stats_distribution_uniform, only:uni=> uniform_distribution_rvs
+
+    implicit none
+    complx :: loc, scale
+    real :: a(3,4,5), b(3,4,5)
+    integer :: seed_put, seed_get
+
+    seed_put = 1234567
+    call random_seed(seed_put, seed_get)
+
+    print *, uni( )           !real standard uniform random variate in [0., 1.]
+! 0.161520019
+
+    print *, uni(3.0)         !an uniform random variate in [0., 3.]
+! 1.65974522
+
+    print *, uni(-0.5, 1.0)   !an uniform random variate in [-0.5, 0.5]
+! 0.486900032
+
+    print *, uni(-1.0,2.0,10) !an array of 10 uniform random variates in [-1., 1.]
+![0.884182811, -0.771520197, 0.560377002, 0.709313750, -7.12267756E-02, !-0.431066573, 0.497536063, -0.396331906, -0.325983286, 0.137686729]
+
+    print *, uni(20)          !a random integer variate in [0, 20]
+! 17
+
+    print *, uni(5,13)        !a random integer variate in [5, 13]
+! 15
+
+    print *, uni(3,19,10)     !an array of 10 integer variates in [3,19]
+! [7, 16, 16, 12, 9, 21, 19, 4, 3, 19]
+
+    loc = (-0.5, -0.5)
+    scale = (1.0, 1.0)
+
+    print *, uni(scale)       !a complex uniform random variate in unit square
+!(0.139202669,0.361759573)
+
+    print *, uni(loc,scale)
+    !a complex uniform random variate in [(-0.5, -0.5), (0.5, 0.5)]
+!(0.296536088,-0.143987954)
+
+    print *, uni(loc, scale, 10)
+    !an array of 10 complex uniform random variate in [(-0.5, -0.5), (0.5, 0.5)]
+
+![(-0.302334785,-0.401923567), (0.281620383,9.534919262E-02),
+! (-0.374348879,0.457528770),  (0.442990601,-0.240510434),
+! (-0.421572685,0.279313922),  (-0.182090610,5.901372433E-02),
+! (-7.864198089E-02,0.378484428), (-0.423258364,-0.201292425),
+! (0.193327367,-0.353985727), (-0.397661150,0.355926156)]
+
+    a(:,:,:) = -0.5
+    b(:,:,:) = 1.0
+
+    print *, uni(a,b)
+    !a rank 3 array of random variates in [-0.5,0.5]
+
+! [-0.249188632, -0.199248433, -0.389813602, 2.88307667E-03, 0.238479793,
+!  0.264856219, -0.205177426, -0.480921626, 0.131218433, 0.252170086,
+! -0.303151041, -8.89462233E-02, -0.377370685, 0.341802299, 0.323204756,
+! 0.358679056, -0.138909757, 0.384329498, -0.109372199, 0.132353067,
+! 0.494320452, 0.419343710, -0.103044361, 0.461389005, 0.403132677,
+! 0.121850729, 0.403839290, -0.349389791, 0.490482628, 0.156600773,
+! 8.46788883E-02, -0.483680278, 0.388107836, 0.119698405, 0.154214382,
+! 0.153113484, 0.236523747, 0.155937552, -0.135760903, 0.219589531,
+! 0.394639254, 6.30156994E-02, -0.342692465, -0.444846451, -0.215700030,
+! 0.204189956, -0.208748132, 0.355063021, 8.98272395E-02, -0.237928331,
+! 2.98077464E-02, -0.485149682, -8.06870461E-02, -0.372713923,
+! -0.178335011, 0.283877611, -2.13934183E-02, -9.21690464E-03, 4.56320047E-02,
+! 0.220112979]
+end program demo_uniform_rvs
+```
+
+## `uniform_distribution_pdf` - uniform probability density function
+
+### Status
+
+Experimental
+
+### Description
+
+The probability density function of the uniform distribution.
+
+f(x) = 1 / (scale + 1);            for discrete uniform distribution
+f(x) = 1 / scale;                  for continuous uniform distribution
+f(x) = 1 / (scale%re * scale%im);  for complx uniform distribution
+
+### Syntax
+
+`result = [[stdlib_stats_distribution_uniform(module):uniform_distribution_pdf(interface)]](x, loc, scale)`
+
+### Arguments
+
+`x`: has intent `in` and is a scalar of type `integer`, `real` or `complx`.
+
+`loc`: has intent `in` and is a scalar of type `integer`, `real` or `complx`.
+
+`scale`: has intent `in` and is a scalar of type `integer`, `real` or `complx`.
+
+The function is elemental, i.e., all three auguments could be arrays conformable to each other. All three arguments must have the same type.
+
+### Return value
+
+The result is a scalar or an array, with a shape conformable to auguments, of type `real`.
+
+### Example
+
+```fortran
+program demo_uniform_pdf
+    use stdlib_stats_distribution_PRNG, only : random_seed
+    use stdlib_stats_distribution_uniform,  only :                              &
+                                           uni_pdf => uniform_distribution_pdf, &
+                                           uni => uniform_distribution_rvs
+
+    implicit none
+    complx :: loc, scale
+    real :: a(3,4,5), b(3,4,5), x(3,4,5)
+    integer :: seed_put, seed_get
+
+    seed_put = 1234567
+    call random_seed(seed_put, seed_get)
+
+    print *, uni_pdf(3, 2, 10)       !probability density at 3 in range [2, 10]
+
+! 9.09090936E-02
+
+    print *, uni_pdf(0.5,0.0,1.0)    !a probability density at 0.5 in [0., 1.]
+
+! 1.00000000
+
+
+    print *, uni_pdf(0.7,-1.0,2.0)   !a probability density at 0.7 in [-1., 1.]
+
+! 0.500000000
+
+    a(:,:,:) = 0.0
+    b(:,:,:) = 2.0
+    x = reshape(uni(0.,2.,60),[3,4,5])! uniform random variates array in [0., 2.]
+    print *, uni_pdf(x, a, b)         ! probability density array in [0., 2.]
+
+![0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, &
+! 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000, 0.500000000]
+
+    loc = (-0.5,-0.5)
+    scale = (1.0,1.0)
+    print *, uni_pdf((-0.1,0.2), loc, scale)
+    ! joint probability density at (-0.1,0.2) in [(-0.5, -0.5), (0.5, 0.5)]
+
+! 1.00000000
+end program demo_uniform_pdf
+
+```
+
+## `uniform_distribution_cdf` - uniform cumulative distribution function
+
+### Status
+
+Experimental
+
+### Description
+
+Cumulative distribution function of the uniform distribution
+
+F(x) = (x - loc + 1) / (scale + 1);      for discrete uniform distribution
+F(x) = (x - loc) / scale;                for continuous uniform distribution
+F(x) = (x%re - loc%re)(x%im - loc%im) / (scale%re * scale%im); for complx uniform distribution
+
+### Syntax
+
+`result = [[stdlib_stats_distribution_uniform(module):uniform_distribution_cdf(interface)]](x, loc, scale)`
+
+### Arguments
+
+`x`: has intent `in` and is a scalar of type `integer`, `real` or `complx`.
+
+`loc`: has intent `in` and is a scalar of type `integer`, `real` or `complx`.
+
+`scale`: has intent `in` and is a scalar of type `integer`, `real` or `complx`.
+
+The function is elemental, i.e., all three auguments could be arrays conformable to each other. All three arguments must have the same type.
+
+### Return value
+
+The result is a scalar or an array, with a shape conformable to auguments, of type `real`.
+
+### Example
+
+```fortran
+program demo_uniform_cdf
+    use stdlib_stats_distribution, only : uni_cdf => uniform_distribution_cdf,  &
+                                          uni => uniform_distribution_rvs,      &
+                                          random_seed
+    implicit none
+    real :: x(3,4,5), a(3,4,5), b(3,4,5)
+    complx :: loc, scale
+    integer :: seed_put, seed_get
+
+    seed_put = 1234567
+    call random_seed(seed_put, seed_get)
+
+    print *, uni_cdf(0.5,0.,1.)      ! a cumulative at 0.5 in [0., 1.]
+
+!0.500000000
+
+    print *, uni_cdf(0.7,-1.0,2.0)   ! a cumulative at 0.7 in [-1.0, 1.0]
+
+! 0.850000024
+
+    print *, uni_cdf(6, 2, 10)       ! a cumulative at 6 in [2, 10]
+
+! 0.454545468
+
+    a(:,:,:) = -1.0
+    b(:,:,:) = 2.0
+    x = reshape(uni(-1.0,2.0,60),[3,4,5]) ! uniform random variates array
+    print *, uni_cdf(x,a,b)        ! cumulative array in [-1.0, 1.0]
+
+![0.161520004, 0.553248405, 0.986900032, 0.942091405, 0.114239901, 0.780188501, &
+! 0.854656875, 0.464386612, 0.284466714, 0.748768032, 0.301834047, 0.337008357, &
+!0.568843365, 0.596165061, 0.180993259, 0.614166319, 0.214835495,7.98164606E-02,&
+!0.641274095, 0.607101977, 0.701139212, 0.230517209, 1.97925568E-02,0.857982159,&
+!0.712761045, 0.139202654, 0.361759573, 0.796536088, 0.356012046, 0.197665215,  &
+!9.80764329E-02,0.781620383, 0.595349193, 0.125651121, 0.957528770, 0.942990601,&
+!0.259489566, 7.84273148E-02, 0.779313922, 0.317909390, 0.559013724,0.421358019,&
+!0.878484428, 7.67416358E-02, 0.298707575, 0.693327367, 0.146014273,0.102338850,&
+!0.855926156, 0.250811368, 0.300751567, 0.110186398, 0.502883077, 0.738479793,  &
+!0.764856219, 0.294822574, 1.90783739E-02,0.631218433,0.752170086, 0.196848959]
+
+    loc = (0., 0.)
+    scale=(2., 1.)
+    print *, uni_cdf((1.2,0.5), loc, scale)
+    ! joint cumulative distribution at (1.2,0.5) in [(0.,0.), (2.,1.)]
+
+! 0.300000012
+end program demo_uniform_cdf
+
+```

src/CMakeLists.txt

@@ -2,6 +2,9 @@
 
 # Create a list of the files to be preprocessed
 set(fppFiles
+    stdlib_bitsets.fypp
+    stdlib_bitsets_64.fypp
+    stdlib_bitsets_large.fypp
     stdlib_io.fypp
     stdlib_linalg.fypp
     stdlib_linalg_diag.fypp
@@ -15,6 +18,8 @@ set(fppFiles
     stdlib_quadrature.fypp
     stdlib_quadrature_trapz.fypp
     stdlib_quadrature_simps.fypp
+    stdlib_stats_distribution_PRNG.fypp
+    stdlib_stats_distribution_uniform.fypp
 )