ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
pm_ziggurat::getZig Interface Reference

Generate and return a Ziggurat set for the specified distribution that can be subsequently used for random number generation from the distribution. More...

Detailed Description

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.

Parameters
[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
where 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
where 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
where 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.)
Returns
zig : The output array of shape (1 : 2, 0 : nlay) of the same type and kind as abserr, containing the Ziggurat set.
  1. The subset 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.
  2. The subset 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).
  3. The element 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).
    The element zig(2, 0) contains the corresponding function value at this fictitious point, which is assumed to be 0.
    The zeroth subset is important for random number generation purposes using the Ziggurat algorithm.


Possible calling interfaces

use pm_ziggurat, only: getZig
zig(1 : 2, 0 : nlay) = getZig(nlay, getFunc, getFuncInv, getZigArea, abserr, abstol = abstol)
Generate and return a Ziggurat set for the specified distribution that can be subsequently used for r...
This module contains procedures and generic interfaces for computing the Ziggurat set for for pseudo-...
Definition: pm_ziggurat.F90:43
Warning
The condition 1 < nlay must hold for the corresponding input arguments.
The condition 0 < abstol must hold for the corresponding input arguments.
This condition is verified only if the library is built with the preprocessor macro CHECK_ENABLED=1.
Remarks
The procedures under discussion are impure.
See also
getZig
getZigNorm
Test:
test_pm_ziggurat
Todo:
Normal Priority: Examples should be added to the documentation of this generic interface in future.


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.

  1. 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.
  2. 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.

Author:
Amir Shahmoradi, April 25, 2015, 2:21 PM, National Institute for Fusion Studies, The University of Texas Austin

Definition at line 177 of file pm_ziggurat.F90.


The documentation for this interface was generated from the following file: