\image html LRlogo.png \image latex LRlogo.eps "LibRan library"
The LibRan package is a library of various pseudo-random number generators along with their \e exact probability and cumulative probability density functions. The libary contains its own optimized sequential congruential uniform pseudo-random number generator on the interval \f$ x \in [0,1) \f$; along with useful tools such as methods for collecting statistics into \e bins.
Each of the random variate distributions rely on a number of internal attributes to \e customize the distribution. The library is written in an object oriented fashion (in C) such that each object's attributes and random number generator is separate from every other object. There are also \e generic routines for calling the various specialized routines for the given random variate distribution.
Each random variate included here has at least three provided methods,
and for two numeric precisions - (f = float and d = double).
The data or numeric precision is given by the \e enum LR_data_type
in libran.h.
| Routine | Generic Fn | Description |
|---|---|---|
| LR?_*_RAN | LR?_RAN | Random variate generator |
| LR?_*_PDF | LR?_PDF | Random variate probability distribution function |
| LR?_*_CDF | LR?_CDF | Random variate cumulative distribution function |
Where \f$ \mbox{PDF}(x) = \frac{d}{dx} \mbox{CDF}(x) \f$, and \f$ \mbox{CDF}(x) \f$ is a \e monotonically non-decreasing function such that \f[ \mbox{CDF}(x_1) \le \mbox{CDF}(x_2) \mbox{ where } x_1 < x_2 \f] and \f[ 0 \le \mbox{CDF}(x) \le 1 \mbox{ for all } x \f]
The \e generic functions are found in LRdf.c.
[For discrete distributions the probability mass function (PMF) is taken here as synonymous with the probability distribtuion function (PDF).]
There are a number of built-in random variate distributions and the complete
list of allowed distribution types is given by the \e enum LR_type in
libran.h.
They fall into a few types as follows:
These random variate distributions will generate variates where \f$ x \in (-\infty,\infty) \f$. These distributions are defined with attributes \e m and \e s representing the mean or mode and the width of the distribution.
| Type | Source | Distribution Description |
|---|---|---|
| unif | LRunif.c | uniformly on given interval |
| gausbm | LRgaus.c | Gaussian or Normal using Box-Muller method |
| gausmar | LRgaus.c | Gaussian or Normal using Marsaglia method |
| cauchy | LRcauchy.c | Cauchy using inverse method |
| cauchymar | LRcauchy.c | Cauchy using Marsaglia method |
These random variate distributions will generate variates where \f$ x \in (0,\infty) \f$.
| Type | Source | Distribution Description |
|---|---|---|
| nexp | LRnexp.c | negative exponential |
These random variate distributions will generate variates on a finite interval \f$ x \in (a,b) \f$.
| Type | Source | Distribution Description |
|---|---|---|
| gsn2 | LRgsn.c | Gaussian-like (sawtooth) |
| gsn4 | LRgsn.c | Gaussian-like (simple bell curve) |
| gsn12 | LRgsn.c | Gaussian-like (close Gaussian approximation) |
These distributions have user-defined shapes.
| Type | Source | Distribution Description |
|---|---|---|
| lspline | LRlspline.c | Linear spline PDF on [a,b] |
| piece | LRpiece.c | Histogram-like PDF on [a,b] |
| inverse | LRuinvcdf.c | User defined CDF |
These distributions return discrete (integer values) which are distributed according to the probability mass function (PMF), but denoted here as the probability density function (PDF).
| Type | Source | Distribution Description |
|---|---|---|
| poisson | LRpoisson.c | Events in a fixed interval |
Here is an example code showing how to use the LR_obj and LR_bin
objects and how to set-up the LR_bin tally bins. The expected values
rely on calculating the difference of CDFs at the boundaries.
The median is at \f$ x = 3 \f$ with a width of 2. This code can be used
\e as-is by just changing the LR_type from \e gausbm to either
\e gausmar, \e gsn12, \e cauchy, or \e cauchymar.
The code can be simply changed for those random variate distributions
with definite endpoints \e a and \e b.
\code /* example LibRan code */
#include <stdio.h> #include <math.h> #include "libran.h"
#define MAXBIN 60
int main() { int nsamples = 50000; // create LR object and binning object LR_obj *o = LR_new(gausbm, LR_double); LR_bin *b = LR_bin_new(MAXBIN + 2); if (!o) { fprintf(stderr, "Error in creating LR object\n"); return 1; } if (!b) { fprintf(stderr, "Error in creating bin object\n"); return 2; } // set attributes if (LR_set_all(o, "ms", 3., 1.) > 0) { LRperror("Sample Code", o->errno); return 3; } // check the object if (LR_check(o)) { LRperror("Sample Code - check", o->errno); return 4; } // set seed LR_lsetseed(o, 19580512L);
// set up bins (use attributes)
double start = o->m.d - 3.0*o->s.d,
finish = o->m.d + 3.0*o->s.d,
incr = 6.0*o->s.d / MAXBIN;
for (int i = 0; i <= MAXBIN; i++) {
if (LR_bin_set(b, start + i*incr)) {
LRperror("Sample Code - bin", b->errno);
return 5;
}
}
// set up expectation histogram
double prevcdf = 0.0, thiscdf, ehist[MAXBIN+2];
for (int i = 0; i < MAXBIN+1; i++) {
if (isnan(thiscdf = LRd_CDF(o, start + i*incr))){
LRperror("Sample Code - CDF", o->errno);
return 6;
}
ehist[i] = nsamples * (thiscdf - prevcdf);
prevcdf = thiscdf;
}
// last bin
ehist[MAXBIN+1] = nsamples * (1.0 - prevcdf);
// run samples
double x;
for (int i = 0; i < nsamples; i++) {
if (isnan(x = LRd_RAN(o))) {
LRperror("Sample Code - RAN", o->errno);
return 7;
}
if (LR_bin_add(b, x)) {
LRperror("Sample Code - bin add", b->errno);
return 8;
}
}
// output results (have 99 = inf here)
double prevbdr = -99., thisbdr;
printf("\n"
" n > lo - hi : sample , expected\n" "--- ------- -------- ---------- ---------\n"); for (int i = 0; i < MAXBIN+1; i++) { thisbdr = b->bdrs[i]; printf("% 3d>% 6.1f - % 6.1f : % 9ld , % 9.2f\n", i, prevbdr, thisbdr, b->bins[i], ehist[i]); prevbdr = thisbdr; } // last bin printf("% 3d>% 6.1f - % 6.1f : % 9ld , % 9.2f\n", MAXBIN+1, prevbdr, 99., b->bins[MAXBIN+1], ehist[MAXBIN+1]);
// clean up
LR_bin_rm(&b);
LR_rm(&o);
return 0;
} \endcode
The output may look like this:
\code
n > lo - hi : sample , expected
0> -99.0 - 0.0 : 60 , 67.49 1> 0.0 - 0.1 : 21 , 25.80 2> 0.1 - 0.2 : 30 , 34.47 3> 0.2 - 0.3 : 53 , 45.59 4> 0.3 - 0.4 : 62 , 59.71 5> 0.4 - 0.5 : 83 , 77.42 6> 0.5 - 0.6 : 103 , 99.39 7> 0.6 - 0.7 : 132 , 126.33 8> 0.7 - 0.8 : 157 , 158.97 9> 0.8 - 0.9 : 177 , 198.05 10> 0.9 - 1.0 : 226 , 244.29 11> 1.0 - 1.1 : 287 , 298.32 12> 1.1 - 1.2 : 377 , 360.69 13> 1.2 - 1.3 : 411 , 431.76 14> 1.3 - 1.4 : 526 , 511.69 15> 1.4 - 1.5 : 609 , 600.40 16> 1.5 - 1.6 : 676 , 697.47 17> 1.6 - 1.7 : 793 , 802.19 18> 1.7 - 1.8 : 920 , 913.46 19> 1.8 - 1.9 : 1009 , 1029.82 20> 1.9 - 2.0 : 1134 , 1149.46 21> 2.0 - 2.1 : 1225 , 1270.24 22> 2.1 - 2.2 : 1413 , 1389.76 23> 2.2 - 2.3 : 1488 , 1505.41 24> 2.3 - 2.4 : 1553 , 1614.47 25> 2.4 - 2.5 : 1734 , 1714.22 26> 2.5 - 2.6 : 1780 , 1802.04 27> 2.6 - 2.7 : 1817 , 1875.52 28> 2.7 - 2.8 : 1982 , 1932.59 29> 2.8 - 2.9 : 1969 , 1971.59 30> 2.9 - 3.0 : 2023 , 1991.39 31> 3.0 - 3.1 : 2046 , 1991.39 32> 3.1 - 3.2 : 1978 , 1971.59 33> 3.2 - 3.3 : 1898 , 1932.59 34> 3.3 - 3.4 : 1878 , 1875.52 35> 3.4 - 3.5 : 1811 , 1802.04 36> 3.5 - 3.6 : 1687 , 1714.22 37> 3.6 - 3.7 : 1685 , 1614.47 38> 3.7 - 3.8 : 1490 , 1505.41 39> 3.8 - 3.9 : 1390 , 1389.76 40> 3.9 - 4.0 : 1289 , 1270.24 41> 4.0 - 4.1 : 1148 , 1149.46 42> 4.1 - 4.2 : 1006 , 1029.82 43> 4.2 - 4.3 : 931 , 913.46 44> 4.3 - 4.4 : 776 , 802.19 45> 4.4 - 4.5 : 718 , 697.47 46> 4.5 - 4.6 : 644 , 600.40 47> 4.6 - 4.7 : 537 , 511.69 48> 4.7 - 4.8 : 419 , 431.76 49> 4.8 - 4.9 : 365 , 360.69 50> 4.9 - 5.0 : 290 , 298.32 51> 5.0 - 5.1 : 249 , 244.29 52> 5.1 - 5.2 : 215 , 198.05 53> 5.2 - 5.3 : 158 , 158.97 54> 5.3 - 5.4 : 140 , 126.33 55> 5.4 - 5.5 : 109 , 99.39 56> 5.5 - 5.6 : 77 , 77.42 57> 5.6 - 5.7 : 58 , 59.71 58> 5.7 - 5.8 : 49 , 45.59 59> 5.8 - 5.9 : 29 , 34.47 60> 5.9 - 6.0 : 23 , 25.80 61> 6.0 - 99.0 : 77 , 67.49
\endcode
The central \e git repository is at SourceForge and can be read-only cloned with: \code
git clone git://git.code.sf.net/p/libran/code libran-code
\endcode
The SourceForge site is - https://sourceforge.net/projects/libran
The on-line documentation is at http://libran.org/
\include lgpl.md
\include EXPAND.md