1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
---
title: stats_distribution_exponential
---
# Statistical Distributions -- Exponential Distribution Module
[TOC]
## `rvs_exp` - exponential distribution random variates
### Status
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 location `loc` specifies the value by which the distribution is shifted.
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 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 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]
### Syntax
`result = ` [[stdlib_stats_distribution_exponential(module):rvs_exp(interface)]] `([loc, scale] [[, array_size]])`
or
`result = ` [[stdlib_stats_distribution_exponential(module):rvs_exp(interface)]] `([lambda] [[, array_size]])`
### Class
Elemental function
### Arguments
`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
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
{!example/stats_distribution_exponential/example_exponential_rvs.f90!}
```
## `pdf_exp` - exponential distribution probability density function
### Status
Experimental
### Description
The probability density function (pdf) of the single real variable exponential distribution is:
$$f(x)=\begin{cases} \lambda e^{-\lambda x} &x\geqslant 0 \\\\ 0 &x< 0\end{cases}$$
For a complex variable \(z=(x + y i)\) with independent real \(x\) and imaginary \(y\) parts, the joint probability density function is the product of the corresponding real and imaginary marginal pdfs:[^2]
$$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, loc, scale)`
or
`result = ` [[stdlib_stats_distribution_exponential(module):pdf_exp(interface)]] `(x, lambda)`
### Class
Elemental function
### Arguments
`x`: has `intent(in)` and is a scalar of type `real` or `complex`.
`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 non-positive `lambda` or `scale`, the result is `NaN`.
### Example
```fortran
{!example/stats_distribution_exponential/example_exponential_pdf.f90!}
```
## `cdf_exp` - exponential cumulative distribution function
### Status
Experimental
### Description
Cumulative distribution function (cdf) of the single real variable exponential distribution:
$$F(x)=\begin{cases}1 - e^{-\lambda x} &x\geqslant 0 \\\\ 0 &x< 0\end{cases}$$
For a complex variable \(z=(x + y i)\) with independent real \(x\) and imaginary \(y\) parts, the joint cumulative distribution function is the product of corresponding real and imaginary marginal cdfs:[^2]
$$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}$$
Alternative to 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, loc, scale)`
or
`result = ` [[stdlib_stats_distribution_exponential(module):cdf_exp(interface)]] `(x, lambda)`
### Class
Elemental function
### Arguments
`x`: has `intent(in)` and is a scalar of type `real` or `complex`.
`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. With non-positive `lambda` or `scale`, the result is `NaN`.
### Example
```fortran
{!example/stats_distribution_exponential/example_exponential_cdf.f90!}
```
[^1]: Marsaglia, George, and Wai Wan Tsang. "The ziggurat method for generating random variables." _Journal of statistical software_ 5 (2000): 1-7.
[^2]: Miller, Scott, and Donald Childers. _Probability and random processes: With applications to signal processing and communications_. Academic Press, 2012 (p. 197).
|
