/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file randomnumbers.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */

/** \page randomnumbers Random Number Generation
 *
 * There is a factory for random number generators present. This implementation
 * has been necessary due to lack of a common interface on the side of the
 * boost::random programmer. Hence, we added a RandomNumberInterface for both
 * engine and distribution and a factory for both and finally the conglomerate
 * for combining both into a single RandomNumberGenerator.
 *
 * Whereever random numbers should be picked with a varying distribution or
 * even better a user-controlled one, this RandomNumberGenerator should be
 * used, e.g. as this
 * \code
 * RandomNumberGenerator &random = RandomNumberGeneratorFactory::getInstance().makeRandomNumberGenerator();
 * const double rng_min = random.min();
 * const double rng_max = random.max();
 * \endcode
 * This returns a reference to a random number generator instance. And also we obtain
 * its RandomNumberGenerator::min() and RandomNumberGenerator::max() values.
 * Then, we may create random values as simple as this:
 * \code
 * double random_value = (random()/((rng_max-rng_min)/2.) - 1.);
 * \endcode
 * which creates a random value within [-1,1]. Note that random() here is
 * RandomNumberGenerator::operator() and not some global function.
 *
 * \note Do not necessarily use the random number generation when just a uniform
 * distribution is required. The implementation is especially designed to allow
 * the user control over the random number distribution. E.g. when filling the void
 * space in a simulation box with molecules he may choose a discrete distribution
 * with a small number of values to have a few, but random orientations of the
 * molecules (MoleculeFillVoidWithMoleculeAction()).
 *
 * \date 2011-10-31
 *
 */