File: random-distributions.html

package info (click to toggle)
boost 1.27.0-3
links: PTS
area: main
in suites: woody
size: 19,908 kB
ctags: 26,546
sloc: cpp: 122,225; ansic: 10,956; python: 4,412; sh: 855; yacc: 803; makefile: 257; perl: 165; lex: 90; csh: 6
file content (781 lines) | stat: -rw-r--r-- 26,822 bytes

<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<title>Boost Random Number Library Distributions</title>
</head>

<body bgcolor="#FFFFFF" text="#000000">

<h1>Random Number Library Distributions</h1>

<ul>
<li><a href="#intro">Introduction</a>
<li><a href="#synopsis">Synopsis</a>
<li><a href="#uniform_smallint">Class template
<code>uniform_smallint</code></a>
<li><a href="#uniform_int">Class template <code>uniform_int</code></a>
<li><a href="#uniform_01">Class template <code>uniform_01</code></a>
<li><a href="#uniform_real">Class template
<code>uniform_real</code></a>
<li><a href="#bernoulli_distribution">Class template
<code>bernoulli_distribution</code></a>
<li><a href="#geometric_distribution">Class template
<code>geometric_distribution</code></a>
<li><a href="#triangle_distribution">Class template
<code>triangle_distribution</code></a>
<li><a href="#exponential_distribution">Class template
<code>exponential_distribution</code></a>
<li><a href="#normal_distribution">Class template
<code>normal_distribution</code></a>
<li><a href="#lognormal_distribution">Class template
<code>lognormal_distribution</code></a>
<li><a href="#uniform_on_sphere">Class template
<code>uniform_on_sphere</code></a>
</ul>

<h2><a name="intro">Introduction</a></h2>

In addition to the <a href="random-generators.html">random number
generators</a>, this library provides distribution functions which map
one distribution (often a uniform distribution provided by some
generator) to another.

<p>
Usually, there are several possible implementations of any given
mapping.  Often, there is a choice between using more space, more
invocations of the underlying source of random numbers, or more
time-consuming arithmetic such as trigonometric functions.  This
interface description does not mandate any specific implementation.
However, implementations which cannot reach certain values of the
specified distribution or otherwise do not converge statistically to
it are not acceptable.

<p>
<table border="1">
<tr><th>distribution</th><th>explanation</th><th>example</th></tr>

<tr>
<td><code><a href="#uniform_smallint">uniform_smallint</a></code></td>
<td>discrete uniform distribution on a small set of integers (much
smaller than the range of the underlying generator)</td>
<td>drawing from an urn</td>
</tr>

<tr>
<td><code><a href="#uniform_int">uniform_int</a></code></td>
<td>discrete uniform distribution on a set of integers; the underlying
generator may be called several times to gather enough randomness for
the output</td>
<td>drawing from an urn</td>
</tr>

<tr>
<td><code><a href="#uniform_01">uniform_01</a></code></td>
<td>continuous uniform distribution on the range [0,1); important
basis for other distributions</td>
<td>-</td>
</tr>

<tr>
<td><code><a href="#uniform_real">uniform_real</a></code></td>
<td>continuous uniform distribution on some range [min, max) of real
numbers</td>
<td>for the range [0, 2pi): randomly dropping a stick and measuring
its angle in radiants (assuming the angle is uniformly
distributed)</td>
</tr>

<tr>
<td><code><a href="#bernoulli_distribution">bernoulli_distribution</a></code></td>
<td>Bernoulli experiment: discrete boolean valued distribution with
configurable probability</td>
<td>tossing a coin (p=0.5)</td>
</tr>

<tr>
<td><code><a href="#geometric_distribution">geometric_distribution</a></code></td>
<td>measures distance between outcomes of repeated Bernoulli experiments</td>
<td>throwing a die several times and counting the number of tries
until a "6" appears for the first time</td>
</tr>

<tr>
<td><code><a href="#triangle_distribution">triangle_distribution</a></code></td>
<td>?</td>
<td>?</td>
</tr>

<tr>
<td><code><a href="#exponential_distribution">exponential_distribution</a></code></td>
<td>exponential distribution</td>
<td>measuring the inter-arrival time of alpha particles emitted by
radioactive matter</td>
</tr>

<tr>
<td><code><a href="#normal_distribution">normal_distribution</a></code></td>
<td>counts outcomes of (infinitely) repeated Bernoulli experiments</td>
<td>tossing a coin 10000 times and counting how many front sides are shown</td>
</tr>

<tr>
<td><code><a href="#lognormal_distribution">lognormal_distribution</a></code></td>
<td>lognormal distribution (sometimes used in simulations)</td>
<td>measuring the job completion time of an assembly line worker</td>
</tr>

<tr>
<td><code><a href="#uniform_on_sphere">uniform_on_sphere</a></code></td>
<td>uniform distribution on a unit sphere of arbitrary dimension</td>
<td>choosing a random point on Earth (assumed to be a sphere) where to
spend the next vacations</td>
</tr>

</table>

<p>

The template parameters of the distribution functions are always in
the order
<ul>
<li>Underlying source of random numbers
<li>If applicable, return type, with a default to a reasonable type.
</ul>

<p>
<em>The distribution functions no longer satisfy the input iterator
requirements (std:24.1.1 [lib.input.iterators]), because this is
redundant given the Generator interface and imposes a run-time
overhead on all users.  Moreover, a Generator interface appeals to
random number generation as being more "natural".  Use an
<a href="../utility/iterator_adaptors.htm">iterator adaptor</a>
if you need to wrap any of the generators in an input iterator
interface.</em>
<p>

All of the distribution functions described below store a non-const
reference to the underlying source of random numbers.  Therefore, the
distribution functions are not Assignable.  However, they are
CopyConstructible.  Copying a distribution function will copy the
parameter values.  Furthermore, both the copy and the original will
refer to the same underlying source of random numbers.  Therefore,
both the copy and the original will obtain their underlying random
numbers from a single sequence.

<p>
In this description, I have refrained from documenting those members
in detail which are already defined in the
<a href="random-concepts.html">concept documentation</a>.


<h2><a name="synopsis">Synopsis of the distributions</a> available from header
<code>&lt;boost/random.hpp&gt;</code> </h2>

<pre>
namespace boost {
  template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
  class uniform_smallint;
  template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
  class uniform_int;
  template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
  class uniform_01;
  template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
  class uniform_real;

  // discrete distributions
  template&lt;class UniformRandomNumberGenerator&gt;
  class bernoulli_distribution;
  template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
  class geometric_distribution;

  // continuous distributions
  template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
  class triangle_distribution;
  template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
  class exponential_distribution;
  template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
  class normal_distribution;
  template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
  class lognormal_distribution;
  template&lt;class UniformRandomNumberGenerator, class RealType = double,
    class Cont = std::vector&lt;RealType&gt; &gt;
  class uniform_on_sphere;
}
</pre>

<h2><a name="uniform_smallint">Class template
<code>uniform_smallint</code></a></h2>

<h3>Synopsis</h3>

<pre>
#include &lt;<a href="../../boost/random/uniform_smallint.hpp">boost/random/uniform_smallint.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class uniform_smallint
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef IntType result_type;
  static const bool has_fixed_range = false;
  uniform_smallint(base_type & rng, IntType min, IntType max);
  result_type operator()();
  result_type min() const;
  result_type max() const;
};
</pre>

<h3>Description</h3>

The distribution function <code>uniform_smallint</code> models a
<a href="random-concepts.html#uniform-rng">uniform random number
generator</a>.  On each invocation, it returns a random integer value
uniformly distributed in the set of integer numbers {min, min+1,
min+2, ..., max}.  It assumes that the desired range (max-min+1) is
small compared to the range of the underlying source of random
numbers and thus makes no attempt to limit quantization errors.
<p>
Let r<sub>out</sub>=(max-min+1) the desired range of integer numbers,
and let r<sub>base</sub> be the range of the underlying source of
random numbers.  Then, for the uniform distribution, the theoretical
probability for any number i in the range r<sub>out</sub> will be
p<sub>out</sub>(i) = 1/r<sub>out</sub>.  Likewise, assume a uniform
distribution on r<sub>base</sub> for the underlying source of random
numbers, i.e. p<sub>base</sub>(i) = 1/r<sub>base</sub>.  Let
p<sub>out_s</sub>(i) denote the random distribution generated by
<code>uniform_smallint</code>.  Then the sum over all i in
r<sub>out</sub> of (p<sub>out_s</sub>(i)/p<sub>out</sub>(i)
-1)<sup>2</sup> shall not exceed
r<sub>out</sub>/r<sub>base</sub><sup>2</sup> (r<sub>base</sub> mod
r<sub>out</sub>)(r<sub>out</sub> - r<sub>base</sub> mod
r<sub>out</sub>).
<p>

The template parameter <code>UniformRandomNumberGenerator</code> shall
denote a class which models a uniform random number generator.
Additionally, <code>UniformRandomNumberGenerator::result_type</code>
shall denote an integral type.  The template parameter
<code>IntType</code> shall denote an integer-like value type.

<p>
<em>Note:</em> The property above is the square sum of the relative
differences in probabilities between the desired uniform distribution
p<sub>out</sub>(i) and the generated distribution
p<sub>out_s</sub>(i).  The property can be fulfilled with the
calculation (base_rng mod r<sub>out</sub>), as follows: Let r =
r<sub>base</sub> mod r<sub>out</sub>.  The base distribution on
r<sub>base</sub> is folded onto the range r<sub>out</sub>.  The
numbers i &lt; r have assigned (r<sub>base</sub> div
r<sub>out</sub>)+1 numbers of the base distribution, the rest has only
(r<sub>base</sub> div r<sub>out</sub>).  Therefore,
p<sub>out_s</sub>(i) = ((r<sub>base</sub> div r<sub>out</sub>)+1) /
r<sub>base</sub> for i &lt; r and p<sub>out_s</sub>(i) =
(r<sub>base</sub> div r<sub>out</sub>)/r<sub>base</sub> otherwise.
Substituting this in the above sum formula leads to the desired
result.
<p>
<em>Note:</em> The upper bound for (r<sub>base</sub> mod r<sub>out</sub>)(r<sub>out</sub> - r<sub>base</sub>
mod r<sub>out</sub>) is r<sub>out</sub><sup>2</sup>/4.  Regarding the upper bound for the square
sum of the relative quantization error of r<sub>out</sub><sup>3</sup>/(4*r<sub>base</sub><sup>2</sup>), it
seems wise to either choose r<sub>base</sub> so that r<sub>base</sub> &gt; 10*r<sub>out</sub><sup>2</sup> or
ensure that r<sub>base</sub> is divisible by r<sub>out</sub>.


<h3>Members</h3>

<pre>uniform_smallint(base_type & rng, IntType min, IntType max)</pre>

<strong>Effects:</strong> Constructs a <code>uniform_smallint</code>
functor with the uniform random number generator <code>rng</code> as
the underlying source of random numbers. <code>min</code> and
<code>max</code> are the lower and upper bounds of the output range,
respectively.


<h2><a name="uniform_int">Class template <code>uniform_int</code></a></h2>

<h3>Synopsis</h3>

<pre>
#include &lt;<a href="../../boost/random/uniform_int.hpp">boost/random/uniform_int.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class uniform_int
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef IntType result_type;
  static const bool has_fixed_range = false;
  uniform_int(base_type & rng, IntType min, IntType max);
  IntType operator()();
  result_type min() const;
  result_type max() const;
};
</pre>

<h3>Description</h3>

The distribution function <code>uniform_int</code> models a
<a href="random-concepts.html#uniform-rng">uniform random number
generator</a>.  On each invocation, it returns a random integer
value uniformly distributed in the set of integer numbers
{min, min+1, min+2, ..., max}.
<p>

The template parameter <code>IntType</code> shall denote an
integer-like value type.

<h3>Members</h3>

<pre>uniform_int(base_type & rng, IntType min, IntType max)</pre>

<strong>Effects:</strong> Constructs a <code>uniform_int</code> functor
with the uniform random number generator <code>rng</code> as the
underlying source of random numbers. <code>min</code> and
<code>max</code> are the lower and upper bounds of the output range,
respectively.

<p>
<em>Note:</em> Invocations of <code>operator()</code> may call the
underlying generator several times and concatenate the result to build
the required range.  Thus, using this distribution with generators
such as linear congruential ones which tend to produce non-random bits
in some positions is strongly discouraged.

<h2><a name="uniform_01">Class template <code>uniform_01</code></a></h2>

<h3>Synopsis</h3>

<pre>
#include &lt;<a href="../../boost/random/uniform_01.hpp">boost/random/uniform_01.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class uniform_01
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef RealType result_type;
  static const bool has_fixed_range = false;
  explicit uniform_01(base_type & rng);
  result_type operator()();
  result_type min() const;
  result_type max() const;
};
</pre>

<h3>Description</h3>

The distribution function <code>uniform_01</code> models a
<a href="random-concepts.html#uniform-rng">uniform random number
generator</a>.  On each invocation, it returns a random floating-point
value uniformly distributed in the range [0..1).

The value is computed using
<code>std::numeric_limits&lt;RealType&gt;::digits</code> random binary
digits, i.e. the mantissa of the floating-point value is completely
filled with random bits. [<em>Note:</em> Should this be configurable?]

<p>
The template parameter <code>RealType</code> shall denote a float-like
value type with support for binary operators +, -, and /.  It must be
large enough to hold floating-point numbers of value
<code>rng.max()-rng.min()+1</code>.
<p>
<code>base_type::result_type</code> must be a number-like value type,
it must support <code>static_cast&lt;&gt;</code> to
<code>RealType</code> and binary operator -.

<p>

<em>Note:</em> The current implementation is buggy, because it may not
fill all of the mantissa with random bits.  I'm unsure how to fill a
(to-be-invented) <code>boost::bigfloat</code> class with random bits
efficiently.  It's probably time for a traits class.

<h3>Members</h3>

<pre>explicit uniform_01(base_type & rng)</pre>

<strong>Effects:</strong> Constructs a <code>uniform_01</code> functor
with the given uniform random number generator as the underlying
source of random numbers.


<h2><a name="uniform_real">Class template <code>uniform_real</code></a></h2>

<h3>Synopsis</h3>

<pre>
#include &lt;<a href="../../boost/random/uniform_real.hpp">boost/random/uniform_real.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class uniform_real
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef RealType result_type;
  static const bool has_fixed_range = false;
  uniform_real(base_type & rng, RealType min, RealType max);
  result_type operator()();
  result_type min() const;
  result_type max() const;
};
</pre>

<h3>Description</h3>

The distribution function <code>uniform_real</code> models a
<a href="random-concepts.html#uniform-rng">uniform random number
generator</a>.  On each invocation, it returns a random floating-point
value uniformly distributed in the range [min..max). The value is
computed using
<code>std::numeric_limits&lt;RealType&gt;::digits</code> random binary
digits, i.e. the mantissa of the floating-point value is completely
filled with random bits.
<p>

<em>Note:</em> The current implementation is buggy, because it may not
fill all of the mantissa with random bits.


<h3>Members</h3>

<pre>explicit uniform_real(base_type & rng, RealType min, RealType max)</pre>

<strong>Effects:</strong> Constructs a <code>uniform_real</code>
functor.  <code>rng</code> specifies the uniform random number
generator to be used as the underlying source of random numbers,
<code>min</code> and <code>max</code> are the lower and upper bounds of
the output range.


<h2><a name="bernoulli_distribution">Class template
<code>bernoulli_distribution</code></a></h2>

<h3>Synopsis</h3>

<pre>
#include &lt;<a href="../../boost/random/bernoulli_distribution.hpp">boost/random/bernoulli_distribution.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator&gt;
class bernoulli_distribution
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef bool result_type;
  bernoulli_distribution(base_type & rng, double q);
  result_type operator()();
};
</pre>

<h3>Description</h3>

Instantiations of class template <code>bernoulli_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>.  It transforms a uniform distribution into a Bernoulli
one.

<h3>Members</h3>

<pre>bernoulli_distribution(base_type & rng, double q)</pre>

<strong>Effects:</strong> Constructs a
<code>bernoulli_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>q</code> is the parameter for the distribution.

<pre>result_type operator()()</pre>
<strong>Returns:</strong> A random boolean value with p(true) = q and
p(false) = 1-q.  For example, with q = 1/2 this can be interpreted as
tossing a coin.


<h2><a name="geometric_distribution">Class template
<code>geometric_distribution</code></a></h2>

<h3>Synopsis</h3>
<pre>
#include &lt;<a href="../../boost/random/geometric_distribution.hpp">boost/random/geometric_distribution.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class geometric_distribution
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef IntType result_type;
  geometric_distribution(base_type& rng, double q);
  result_type operator()();
};
</pre>


<h3>Description</h3>

Instantiations of class template <code>geometric_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>.  It transforms a uniform distribution into a geometric
one.


<h3>Members</h3>

<pre>geometric_distribution(base_type& rng, const result_type& q)</pre>

<strong>Effects:</strong> Constructs a
<code>geometric_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>q</code> is the parameter for the distribution.
<p>

<pre>result_type operator()()</pre>

<strong>Returns:</strong> A random integer value <em>i</em> >= 1 with
p(i) = (1-q) * q<sup>i-1</sup>.  For example, with q = 5/6 this can be
interpreted as the number of times one has to roll a die until a given
number shows up.


<h2><a name="triangle_distribution">Class template
<code>triangle_distribution</code></a></h2>

<h3>Synopsis</h3>
<pre>
#include &lt;<a href="../../boost/random/triangle_distribution.hpp">boost/random/triangle_distribution.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class triangle_distribution
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef RealType result_type;
  triangle_distribution(base_type& rng, result_type a, result_type b, result_type c);
  result_type operator()();
};
</pre>


<h3>Description</h3>

Instantiations of class template <code>triangle_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>.  It transforms a uniform distribution into a triangle
one.


<h3>Members</h3>

<pre>triangle_distribution(base_type& rng, result_type a, result_type b, result_type c)</pre>

<strong>Effects:</strong> Constructs a
<code>triangle_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>a, b, c</code> are the parameters for the distribution.
<p>

<pre>result_type operator()()</pre>

<strong>Returns:</strong> A random floating-point value <code>x</code>
where <code>a <= x <= c</code>; <code>x</code> has a triangle
distribution, where <code>b</code> is the most probable value for
<code>x</code>.


<h2><a name="exponential_distribution">Class template
<code>exponential_distribution</code></a></h2>

<h3>Synopsis</h3>
<pre>
#include &lt;<a href="../../boost/random/exponential_distribution.hpp">boost/random/exponential_distribution.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class exponential_distribution
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef RealType result_type;
  exponential_distribution(base_type& rng, const result_type& lambda);
  result_type operator()();
};
</pre>

<h3>Description</h3>

Instantiations of class template <code>exponential_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>.  It transforms a uniform distribution into an
exponential one.

<h3>Members</h3>

<pre>exponential_distribution(base_type& rng, const result_type& lambda)</pre>

<strong>Effects:</strong> Constructs an
<code>exponential_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>lambda</code> is the parameter for the distribution.
<p>

<pre>result_type operator()()</pre>

<strong>Returns:</strong> A random floating-point value <em>x</em>
&gt; 0 with p(x) = <code>lambda</code> * exp(-<code>lambda</code> *
x).


<h2><a name="normal_distribution">Class template
<code>normal_distribution</code></a></h2>

<h3>Synopsis</h3>

<pre>
#include &lt;<a href="../../boost/random/normal_distribution.hpp">boost/random/normal_distribution.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class normal_distribution
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef RealType result_type;
  explicit normal_distribution(base_type& rng, const result_type& mean = 0,
			       const result_type& sigma = 1);
  result_type operator()();
};
</pre>

<h3>Description</h3>

Instantiations of class template <code>normal_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>.  It transforms a uniform distribution into a
normal (Gaussian) one.

<h3>Members</h3>

<pre>normal_distribution(base_type& rng, const result_type& mean = 0,
		     const result_type& sigma = 1)</pre>

<strong>Effects:</strong> Constructs a
<code>normal_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>mean</code> and <code>sigma</code> are the parameters for
the distribution.
<p>

<pre>result_type operator()()</pre>

<strong>Returns:</strong> A random floating-point value <em>x</em>
with p(x) = 1/sqrt(2*pi*sigma) * exp(- (x-mean)<sup>2</sup> /
(2*sigma<sup>2</sup>) ).


<h2><a name="lognormal_distribution">Class template
<code>lognormal_distribution</code></a></h2>

<h3>Synopsis</h3>

<pre>
#include &lt;<a href="../../boost/random/lognormal_distribution.hpp">boost/random/lognormal_distribution.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class lognormal_distribution
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef RealType result_type;
  explicit lognormal_distribution(base_type& rng, const result_type& mean,
			          const result_type& sigma);
  result_type operator()();
};
</pre>

<h3>Description</h3>

Instantiations of class template <code>lognormal_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>.  It transforms a uniform distribution into a
lognormal one.

<h3>Members</h3>

<pre>lognormal_distribution(base_type& rng, const result_type& mean,
	   	       const result_type& sigma)</pre>

<strong>Effects:</strong> Constructs a
<code>lognormal_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>mean</code> and <code>sigma</code> are the mean and
standard deviation of the lognormal distribution.
<p>

<pre>result_type operator()()</pre>

<!-- <strong>Returns:</strong> A random floating-point value <em>x</em>
with p(x) = 1/(x * sigma * sqrt(2*pi)) * exp(-
(log(x)-mean)<sup>2</sup> / (2*sigma<sup>2</sup>) ) for x > 0.
<p> -->
<strong>Returns:</strong> A random floating-point value <em>x</em>
with p(x) = 1/(x * normal_sigma * sqrt(2*pi)) * exp(
-(log(x)-normal_mean)<sup>2</sup> / (2*normal_sigma<sup>2</sup>) )
for x > 0,
where normal_mean = log(mean<sup>2</sup>/sqrt(sigma<sup>2</sup>
+ mean<sup>2</sup>))
and normal_sigma = sqrt(log(1 + sigma<sup>2</sup>/mean<sup>2</sup>)).


<h2><a name="uniform_on_sphere">Class template
<code>uniform_on_sphere</code></a></h2>

<h3>Synopsis</h3>

<pre>
#include &lt;<a href="../../boost/random/uniform_on_sphere.hpp">boost/random/uniform_on_sphere.hpp</a>&gt;

template&lt;class UniformRandomNumberGenerator, class RealType = double,
  class Cont = std::vector&lt;RealType&gt; &gt;
class uniform_on_sphere
{
public:
  typedef UniformRandomNumberGenerator base_type;
  typedef Cont result_type;
  explicit uniform_on_sphere(base_type & rng, int dim = 2);
  const result_type & operator()();
};
</pre>

<h3>Description</h3>

Instantiations of class template <code>uniform_on_sphere</code> model a
Generator (std:25.2.6 [lib.alg.generate]).  It transforms a uniform
distribution into a uniform distribution on the unit sphere of
arbitrary dimension.  The <code>Cont</code> template parameter must be
a STL-like container type with <code>begin</code> and <code>end</code>
operations returning non-const ForwardIterators of type
<code>Cont::iterator</code>.

<h3>Members</h3>

<pre>explicit uniform_on_sphere(base_type & rng, int dim = 2)</pre>

<strong>Effects:</strong> Constructs a <code>uniform_on_sphere</code>
functor with the uniform random number generator <code>rng</code> as
the underlying source of random numbers. <code>dim</code> is the
dimension of the sphere.
<p>

<pre>result_type operator()()</pre>

<strong>Returns:</strong> A position on the unit sphere of
<code>dim</code> dimensions in cartesian coordinates.  The positions
are uniformly distributed on the unit sphere.
<p>
<strong>Complexity:</strong> Proportional to the number of dimensions.

<p>
<hr>
Jens Maurer, 2001-04-15

</body>
</html>