reintroduced old interface through wrappers and updated specs

Author: sebastian-mutz

doc/specs/stdlib_stats_distribution_exponential.md

@@ -15,14 +15,19 @@ Experimental
 ### Description
 
 An exponential distribution is the distribution of time between events in a Poisson point process.
-The inverse scale parameter `lambda` specifies the average time between events (\(\lambda\)), also called the rate of events.
+The inverse `scale` parameter `lambda` specifies the average time between events (\(\lambda\)), also called the rate of events. The location `loc` specifies the value by which the distribution is shifted.
 
-Without argument, the function returns a random sample from the standard exponential distribution \(E(\lambda=1)\).
+Without argument, the function returns a random sample from the unshifted standard exponential distribution \(E(\lambda=1)\) or \(E(loc=0, scale=1)\).
 
-With a single argument, the function returns a random sample from the exponential distribution \(E(\lambda=\text{lambda})\).
+With a single argument of type `real`, the function returns a random sample from the exponential distribution \(E(\lambda=\text{lambda})\). 
 For complex arguments, the real and imaginary parts are sampled independently of each other.
 
-With two arguments, the function returns a rank-1 array of exponentially distributed random variates.
+With one argument of type `real` and one argument of type `integer`, the function returns a rank-1 array of exponentially distributed random variates for (E(\lambda=\text{lambda})\).
+
+With two arguments of type `real`, the function returns a random sample from the exponential distribution \(E(loc=loc, scale=scale)\).
+For complex arguments, the real and imaginary parts are sampled independently of each other.
+
+With two arguments of type `real` and one argument of type `integer`, the function returns a rank-1 array of exponentially distributed random variates for \(E(loc=loc, scale=scale)\).
 
 @note
 The algorithm used for generating exponential random variates is fundamentally limited to double precision.[^1]
@@ -31,6 +36,10 @@ The algorithm used for generating exponential random variates is fundamentally l
 
 `result = ` [[stdlib_stats_distribution_exponential(module):rvs_exp(interface)]] `([lambda] [[, array_size]])`
 
+or
+
+`result = ` [[stdlib_stats_distribution_exponential(module):rvs_exp(interface)]] `([loc, scale] [[, array_size]])`
+
 ### Class
 
 Elemental function
@@ -40,13 +49,21 @@ Elemental function
 `lambda`: optional argument has `intent(in)` and is a scalar of type `real` or `complex`.
 If `lambda` is `real`, its value must be positive. If `lambda` is `complex`, both the real and imaginary components must be positive.
 
+`loc`: optional argument has `intent(in)` and is a scalar of type `real` or `complex`. 
+
+`scale`: optional argument has `intent(in)` and is a positive scalar of type `real` or `complex`.
+If `scale` is `real`, its value must be positive. If `scale` is `complex`, both the real and imaginary components must be positive.
+
 `array_size`: optional argument has `intent(in)` and is a scalar of type `integer` with default kind.
 
 ### Return value
 
-The result is a scalar or rank-1 array with a size of `array_size`, and the same type as `lambda`.
+If `lambda` is passed, the result is a scalar or rank-1 array with a size of `array_size`, and the same type as `lambda`.
 If `lambda` is non-positive, the result is `NaN`.
 
+If `loc` and `scale` are passed, the result is a scalar or rank-1 array with a size of `array_size`, and the same type as `scale`.
+If `scale` is non-positive, the result is `NaN`.
+
 ### Example
 
 ```fortran
@@ -69,10 +86,16 @@ For a complex variable \(z=(x + y i)\) with independent real \(x\) and imaginary
 
 $$f(x+\mathit{i}y)=f(x)f(y)=\begin{cases} \lambda_{x} \lambda_{y} e^{-(\lambda_{x} x + \lambda_{y} y)} &x\geqslant 0, y\geqslant 0 \\\\ 0 &\text{otherwise}\end{cases}$$
 
+Instead of of the inverse scale parameter `lambda`, it is possible to pass `loc` and `scale`, where \(scale = \frac{1}{\lambda}\) and `loc` specifies the value by which the distribution is shifted.
+
 ### Syntax
 
 `result = ` [[stdlib_stats_distribution_exponential(module):pdf_exp(interface)]] `(x, lambda)`
 
+or
+
+`result = ` [[stdlib_stats_distribution_exponential(module):pdf_exp(interface)]] `(x, loc, scale)`
+
 ### Class
 
 Elemental function
@@ -84,11 +107,20 @@ Elemental function
 `lambda`: has `intent(in)` and is a scalar of type `real` or `complex`.
 If `lambda` is `real`, its value must be positive. If `lambda` is `complex`, both the real and imaginary components must be positive.
 
+`loc`: has `intent(in)` and is a scalar of type `real` or `complex`.
+
+`scale`: has `intent(in)` and is a positive scalar of type `real` or `complex`.
+If `scale` is `real`, its value must be positive. If `scale` is `complex`, both the real and imaginary components must be positive.
+
 All arguments must have the same type.
 
 ### Return value
 
-The result is a scalar or an array, with a shape conformable to the arguments, and the same type as the input arguments. If `lambda` is non-positive, the result is `NaN`.
+If `lambda` is passed, the result is a scalar or an array, with a shape conformable to the arguments, and the same type as the input arguments. If `lambda` is non-positive, the result is `NaN`.
+
+
+If `loc` and `scale` are passed, the result is a scalar or an array, with a shape conformable to the arguments, and the same type as the input arguments. If `scale` is non-positive, the result is `NaN`.
+
 
 ### Example
 
@@ -112,10 +144,16 @@ For a complex variable  \(z=(x + y i)\) with independent real \(x\) and imaginar
 
 $$F(x+\mathit{i}y)=F(x)F(y)=\begin{cases} (1 - e^{-\lambda_{x} x})(1 - e^{-\lambda_{y} y}) &x\geqslant 0, \;\; y\geqslant 0 \\\\ 0 & \text{otherwise} \end{cases}$$
 
+Instead of of the inverse scale parameter `lambda`, it is possible to pass `loc` and `scale`, where \(scale = \frac{1}{\lambda}\) and `loc` specifies the value by which the distribution is shifted.
+
 ### Syntax
 
 `result = ` [[stdlib_stats_distribution_exponential(module):cdf_exp(interface)]] `(x, lambda)`
 
+or
+
+`result = ` [[stdlib_stats_distribution_exponential(module):cdf_exp(interface)]] `(x, loc, scale)`
+
 ### Class
 
 Elemental function
@@ -127,11 +165,19 @@ Elemental function
 `lambda`: has `intent(in)` and is a scalar of type `real` or `complex`.
 If `lambda` is `real`, its value must be positive. If `lambda` is `complex`, both the real and imaginary components must be positive.
 
+`loc`: has `intent(in)` and is a scalar of type `real` or `complex`.
+
+`scale`: has `intent(in)` and is a positive scalar of type `real` or `complex`.
+If `scale` is `real`, its value must be positive. If `scale` is `complex`, both the real and imaginary components must be positive.
+
 All arguments must have the same type.
 
 ### Return value
 
-The result is a scalar or an array, with a shape conformable to the arguments, and the same type as the input arguments. If `lambda` is non-positive, the result is `NaN`.
+If `lamba` is passed, the result is a scalar or an array, with a shape conformable to the arguments, and the same type as the input arguments. If `lambda` is non-positive, the result is `NaN`.
+
+
+If `loc` and `scale` are passed, the result is a scalar or an array, with a shape conformable to the arguments, and the same type as the input arguments. If `scale` is non-positive, the result is `NaN`.
 
 ### Example
 

example/stats_distribution_exponential/example_exponential_cdf.f90

@@ -12,10 +12,18 @@ program example_exponential_cdf
   seed_put = 1234567
   call random_seed(seed_put, seed_get)
 
+  ! standard exponential cumulative distribution at x=1.0 with lambda=1.0
+  print *, exp_cdf(1.0, 1.0)
+  ! 0.632120550
+
   ! standard exponential cumulative distribution at x=1.0 with loc=0.0, scale=1.0
   print *, exp_cdf(1.0, 0.0, 1.0)
   ! 0.632120550
 
+  ! cumulative distribution at x=2.0 with lambda=2
+  print *, exp_cdf(2.0, 2.0)
+  ! 0.981684387
+
   ! cumulative distribution at x=2.0 with loc=0.0 and scale=0.5 (equivalent of lambda=2)
   print *, exp_cdf(2.0, 0.0, 0.5)
   ! 0.981684387

example/stats_distribution_exponential/example_exponential_pdf.f90

@@ -12,10 +12,18 @@ program example_exponential_pdf
   seed_put = 1234567
   call random_seed(seed_put, seed_get)
 
-  ! probability density at x=1.0 with loc=0 and in standard exponential
+  ! probability density at x=1.0 with lambda=1.0
+  print *, exp_pdf(1.0, 1.0)
+  ! 0.367879450
+
+  ! probability density at x=1.0 with loc=0 and scale=1.0
   print *, exp_pdf(1.0, 0.0, 1.0)
   ! 0.367879450
 
+  ! probability density at x=2.0 with lambda=2.0
+  print *, exp_pdf(2.0, 2.0)
+  ! 3.66312787E-02
+
   ! probability density at x=2.0 with loc=0.0 and scale=0.5 (lambda=2.0)
   print *, exp_pdf(2.0, 0.0, 0.5)
   ! 3.66312787E-02

example/stats_distribution_exponential/example_exponential_rvs.f90

@@ -9,22 +9,32 @@ program example_exponential_rvs
   seed_put = 1234567
   call random_seed(seed_put, seed_get)
 
-  print *, rexp()         !single standard exponential random variate
-! 0.358690143
+ ! single standard exponential random variate
+  print *, rexp()
+  ! 0.358690143
 
-  print *, rexp(0.6, 0.2) !exponential random variate with loc=0.6 and scale=0.5 (lambda=2)
-! 0.681645989
+  ! exponential random variate with lambda=2
+   print *, rexp(2.0)
+  ! 0.204114929
 
-  print *, rexp(0.0, 3.0, 10)   !an array of 10 variates with loc=0.0 and scale=3.0 (lambda=1/3)
-! 0.184008643      0.359742016       1.36567295       2.62772131      0.362352759
-! 5.47133636       2.13591909      0.410784155       5.83882189       6.71128035
+  ! exponential random variate with loc=0 and scale=0.5 (lambda=2)
+  print *, rexp(0.0, 0.5)
+  ! 0.122672431
 
+  ! exponential random variate with loc=0.6 and scale=0.2 (lambda=5)
+  print *, rexp(0.6, 0.2)
+  ! 0.681645989
+
+  ! an array of 10 variates with loc=0.0 and scale=3.0 (lambda=1/3)
+  print *, rexp(0.0, 3.0, 10)
+  ! 1.36567295       2.62772131      0.362352759       5.47133636       2.13591909
+  ! 0.410784155      5.83882189      6.71128035        1.31730068       1.90963650
+
+  ! single complex exponential random variate with real part of scale=0.5 (lambda=2.0);
+  ! imagainary part of scale=1.6 (lambda=0.625)
   cloc   = (0.0, 0.0)
   cscale = (0.5, 1.6)
   print *, rexp(cloc, cscale)
-!single complex exponential random variate with real part of scale=0.5 (lambda=2.0);
-!imagainary part of scale=1.6 (lambda=0.625)
-
-! (0.219550118,1.01847279)
+  ! (0.426896989,2.56968451)
 
 end program example_exponential_rvs