mirror of https://github.com/CGAL/cgal
144 lines
5.6 KiB
TeX
144 lines
5.6 KiB
TeX
% =============================================================================
|
|
% The CGAL Reference Manual
|
|
% Chapter: Geometric Object Generators
|
|
% Section: Random Numbers Generator
|
|
% -----------------------------------------------------------------------------
|
|
% file : doc_tex/support/Generator/Random.tex
|
|
% author: Sven Schönherr <sven@inf.ethz.ch>
|
|
% -----------------------------------------------------------------------------
|
|
% $CGAL_Chapter: Geometric Object Generators $
|
|
% $CGAL_Package: Random_numbers WIP $
|
|
% $Id$
|
|
% $Date$
|
|
% =============================================================================
|
|
|
|
\begin{ccRefClass}{Random}
|
|
\label{sec:random_numbers_generator}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccDefinition
|
|
|
|
The class \ccRefName{} is a random numbers generator. It generates
|
|
uniformly distributed random \ccc{bool}s, \ccc{int}s and \ccc{double}s.
|
|
It can be used as the random number generating function object in the
|
|
\stl\ algorithm \ccc{random_shuffle}.
|
|
|
|
Instances of \ccClassName\ can be seen as input streams. Different
|
|
streams are \emph{independent} of each other, i.e.\ the sequence of
|
|
numbers from one stream does \emph{not} depend upon how many numbers
|
|
were extracted from the other streams. At each time, an instance has
|
|
a \emph{state} that uniquely determines the subsequent numbers being
|
|
produced.
|
|
|
|
It can be very useful, e.g.\ for debugging, to reproduce a sequence of
|
|
random numbers. This can be done by either initialising with a fixed
|
|
seed, or by using the state functions as described below.
|
|
|
|
\ccInclude{CGAL/Random.h}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccTypes
|
|
|
|
\ccUnchecked
|
|
\ccNestedType{State}{The State type.}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccCreation
|
|
\ccCreationVariable{random}
|
|
|
|
\ccConstructor{ Random( );}{
|
|
introduces a variable \ccVar\ of type \ccClassTemplateName. The
|
|
seed is chosen ``randomly'', depending on the system time.}
|
|
|
|
\ccConstructor{ Random( unsigned int seed);}{
|
|
introduces a variable \ccVar\ of type \ccClassTemplateName\
|
|
and initializes its internal state using \ccc{seed}. Equal
|
|
values for \ccc{seed} result in equal sequences of random
|
|
numbers.}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccOperations
|
|
|
|
\ccMemberFunction{ bool get_bool( );}{
|
|
returns a random \ccc{bool}.}
|
|
|
|
\ccMemberFunction{ template <int b> int get_bits();}{
|
|
returns a random \ccc{int} value from the interval
|
|
$[\mbox{\ccc{0},\ccc{2^b}})$. This is supposed to
|
|
be efficient.}
|
|
|
|
\ccMemberFunction{ int get_int( int lower, int upper);}{
|
|
returns a random \ccc{int} from the interval
|
|
$[\mbox{\ccc{lower},\ccc{upper}})$. }
|
|
|
|
\ccMemberFunction{ double get_double( double lower = 0.0,
|
|
double upper = 1.0);}{
|
|
returns a random \ccc{double} from the interval
|
|
$[\mbox{\ccc{lower},\ccc{upper}})$.}
|
|
|
|
|
|
\ccHeading{Distributions}
|
|
|
|
The following member functions are a 1-to-1 correspondence to
|
|
some distributions from the boost random library.
|
|
|
|
|
|
\ccMemberFunction{ template <typename IntType> IntType uniform_smallint( IntType lower=0, IntType upper=9);}{
|
|
returns a random \ccc{IntType} from the interval
|
|
$[\mbox{\ccc{lower},\ccc{upper}}]$. \ccc{IntType} can be an integral type
|
|
as \ccc{int}, \ccc{std::ptrdiff_t}, \ccc{std::size_t},etc. {\bf Warning: In contrast to \ccc{get_int} this function may return \ccc{upper}. } }
|
|
|
|
\ccMemberFunction{ template <typename IntType> IntType uniform_int( IntType lower=0, IntType upper=9);}{
|
|
returns a random \ccc{IntType} from the interval
|
|
$[\mbox{\ccc{lower},\ccc{upper}}]$. \ccc{IntType} can be an integral type
|
|
as \ccc{int}, \ccc{std::ptrdiff_t}, \ccc{std::size_t},etc. {\bf Warning: In contrast to \ccc{get_int} this function may return \ccc{upper}. } }
|
|
|
|
\ccMemberFunction{ template <typename RealType> Realtype uniform_real( RealType lower = 0.0,
|
|
RealType upper = 1.0);}{
|
|
returns a random \ccc{RealType} from the interval
|
|
$[\mbox{\ccc{lower},\ccc{upper}})$. \ccc{RealType} can be \ccc{float}, \ccc{double}, etc.}
|
|
|
|
\ccMemberFunction{ template <typename RealType> RealType uniform_01();}{
|
|
returns a random \ccc{RealType} from the interval
|
|
$[0,1)$. \ccc{RealType} can be \ccc{float}, \ccc{double}, etc.}
|
|
|
|
|
|
|
|
\ccMemberFunction{ template <typename IntType> IntType operator() ( IntType upper);}{
|
|
returns \ccVar\ccc{uniform_int<IntType>( 0, upper-1)}.}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccHeading{Seed and State Functions}
|
|
|
|
\ccMemberFunction{ unsigned int get_seed() const;}{
|
|
returns the seed used for initialization.}
|
|
|
|
\ccMemberFunction{ void save_state( State& state) const;}{
|
|
saves the current internal state in \ccc{state}.}
|
|
|
|
\ccMemberFunction{ void restore_state( State const& state);}{
|
|
restores the internal state from \ccc{state}.}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccHeading{Equality Test}
|
|
|
|
\ccMemberFunction{ bool operator == ( Random const& random2) const;}{
|
|
returns \ccc{true}, iff \ccVar\ and \ccc{random2} have equal
|
|
internal states.}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccImplementation
|
|
|
|
We use the boost random library function \ccc{boost::rand48} to generate the random
|
|
numbers.
|
|
|
|
|
|
|
|
\ccSeeAlso
|
|
|
|
\ccRefIdfierPage{CGAL::default_random}\\
|
|
|
|
\end{ccRefClass}
|
|
|
|
% ===== EOF ===================================================================
|