|
ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation. |
|
|
ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation. |
Generate and return a Ziggurat set for the specified distribution that can be subsequently used for random number generation from the distribution. More...
Generate and return a Ziggurat set for the specified distribution that can be subsequently used for random number generation from the distribution.
The following figure illustrates the concept of the layers and rectangle corners.
The shared regions are the Ziggurat rectangles formed and the thin violet curve represents the underlying density function returned by the user-specified function getFunc().
All layers have equal areas.
| [in] | nlay | : The input scalar integer of default kind IK, representing the number of Ziggurat rectangles that will be used to approximate the target distribution.One of the most popular values for nlay is 256. |
| getFunc | : The external user-specified function that takes a single input scalar argument x of the same type and kind as the input argument abserr.On output, getFunc must return a scalar of the same type and kind as the input x, containing the value of the target distribution at the specified input x.The following illustrates the generic interface of getFunc, function getFunc(x) result(func)
real(KIND) , intent(in) :: x
real(KIND) :: func
end function
KIND represents the real kind of the input argument x, which must be that of the input argument abserr.The density function represented by getFunc() must be monotonically decreasing to \(+\infty\), starting from \(x = 0\). | |
| getFuncInv | : The external user-specified function that takes a single input scalar argument func of the same type and kind as the input argument abserr.On output, getFuncInv must return a scalar of the same type and kind as the input func, containing the location x within the domain of the distribution such that func = getFunc(x).In other words, getFuncInv is the inverse of getFunc.The following illustrates the generic interface of getFuncInv, function getFuncInv(func) result(x)
real(KIND) , intent(in) :: func
real(KIND) :: x
end function
KIND represents the real kind of the input argument func, which must be that of the input argument abserr. | |
| getZigArea | : The external user-specified function that takes a single input scalar argument r of the same type and kind as the input argument abserr.On output, getZigArea must return a scalar of the same type and kind as the input r, containing the area of individual Ziggurat rectangles area.This area is computed as, \begin{equation} \ms{area} = r \times \ms{getFunc}(r) + \int_r^{+\infty} \ms{getFunc}(x) ~dx ~, \end{equation} where \(r\) is (frequently) the last point in the Ziggurat set (beyond which there is no more rectangles defined, but only a distribution tail).The following illustrates the generic interface of getFuncInv, function getZigArea(r) result(area)
real(KIND) , intent(in) :: r
real(KIND) :: area
end function
KIND represents the real kind of the input argument r, which must be that of the input argument abserr. | |
| [out] | abserr | : The output scalar of type real of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128).On output it contains an estimate of the error in computing the areas of individual rectangles in the Ziggurat set. The returned value of abserr must be typically zero or near epsilon(abserr).A significant deviation strongly indicates lack of convergence to the correct Ziggurat set, in which case, the output set is likely unreliable. As a general rule of thumb, the value of abserr should be typically less than sqrt(epsilon(real(0, kind(abserr)))). |
| [in] | abstol | : The input scalar of same type and kind as the output abserr, representing the absolute tolerance used as the stopping criterion of the search.The search iterations continue until the search interval becomes smaller than abstol in absolute units.Care must be taken for specifying a reasonable value for abstol (see the warnings below).If no suitable value for abstol is known a priori, try abstol = epsilon(0._RKG)**.8 * (abs(lb) + abs(ub)) where RKG refers to the kind of the output argument root.See also the corresponding argument of getRoot. (optional The default value is set by getRoot.) |
zig : The output array of shape (1 : 2, 0 : nlay) of the same type and kind as abserr, containing the Ziggurat set.zig(1, 1 : nlay) contains the rightmost corners of the rectangles corresponding to the nlay Ziggurat layers, \(\{x_{i} ~:~ i = 1, \ms{nlay}\}\) as depicted in the figure above.zig(2, 1 : nlay) contains the density function values returned by the user-specified getFunc() corresponding to the rightmost corners of the rectangles stored in the subset zig(1, 1 : nlay).zig(1, 0) contains the fictitious point \(x_0\) representing the rightmost corner of a hypothetical rectangle of the same area as the lowermost Ziggurat layer (which includes the tail).zig(2, 0) contains the corresponding function value at this fictitious point, which is assumed to be 0.
Possible calling interfaces ⛓
1 < nlay must hold for the corresponding input arguments.0 < abstol must hold for the corresponding input arguments.CHECK_ENABLED=1.impure.
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 177 of file pm_ziggurat.F90.
1.9.3