unison/src/core/model/random-variable-stream.h

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2006 Georgia Tech Research Corporation
 * Copyright (c) 2011 Mathieu Lacage
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation;
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Authors: Rajib Bhattacharjea<raj.b@gatech.edu>
 *          Hadi Arbabi<marbabi@cs.odu.edu>
 *          Mathieu Lacage <mathieu.lacage@gmail.com>
 *
 * Modified by Mitch Watrous <watrous@u.washington.edu>
 *
 */
#ifndef RANDOM_VARIABLE_STREAM_H
#define RANDOM_VARIABLE_STREAM_H

#include "type-id.h"
#include "object.h"
#include "attribute-helper.h"
#include <stdint.h>

namespace ns3 {

class RngStream;

/**
 * \ingroup randomvariable
 * \brief The Random Number Generator (RNG) that allows stream numbers to be set deterministically.
 *
 * Note: The underlying random number generation method used
 * by NS-3 is the RngStream code by Pierre L'Ecuyer at
 * the University of Montreal.
 *
 * NS-3 has a rich set of random number generators that allow stream
 * numbers to be set deterministically if desired.  Class
 * RandomVariableStream defines the base class functionalty required
 * for all such random number generators.
 *
 * By default, the underlying generator is seeded all the time with
 * the same seed value and run number coming from the ns3::GlobalValue
 * \ref GlobalValueRngSeed "RngSeed" and \ref GlobalValueRngRun
 * "RngRun".  Also by default, the stream number value for this RNG
 * stream is automatically allocated.
 */
class RandomVariableStream : public Object
{
public:
  static TypeId GetTypeId (void);
  RandomVariableStream ();
  virtual ~RandomVariableStream();

  /**
   * \brief Specifies the stream number for this RNG stream.
   * \param stream The stream number for this RNG stream. -1 means "allocate a stream number automatically".
 */
  void SetStream (int64_t stream);

  /**
   * \brief Returns the stream number for this RNG stream.
   * \return The stream number for this RNG stream. -1 means "allocate a stream number automatically".
   */
  int64_t GetStream(void) const;

  /**
   * \brief Specifies whether antithetic values should be generated.
   * \param isAntithetic Set equal to true if antithetic values should
   * be generated by this RNG stream.
   */
  void SetAntithetic(bool isAntithetic);

  /**
   * \brief Returns true if antithetic values should be generated.
   * \return A bool value that indicates if antithetic values should
   * be generated by this RNG stream.
   */
  bool IsAntithetic(void) const;

  /**
   * \brief Returns a random double from the underlying distribution
   * \return A floating point random value.
   */
  virtual double GetValue (void) = 0;

  /**
   * \brief Returns a random integer integer from the underlying distribution
   * \return  Integer cast of RandomVariableStream::GetValue
   */
  virtual uint32_t GetInteger (void) = 0;

protected:
  /**
   * \brief Returns a pointer to the underlying RNG stream.
   */
  RngStream *Peek(void) const;

private:
  // you can't copy these objects.
  // Theoretically, it is possible to give them good copy semantics
  // but not enough time to iron out the details.
  RandomVariableStream (const RandomVariableStream &o);
  RandomVariableStream &operator = (const RandomVariableStream &o);

  /// Pointer to the underlying RNG stream.
  RngStream *m_rng;

  /// Indicates if antithetic values should be generated by this RNG stream.
  bool m_isAntithetic;

  /// The stream number for this RNG stream.
  int64_t m_stream;
};

/**
 * \ingroup randomvariable
 * \brief The uniform distribution Random Number Generator (RNG) that allows stream numbers to be set deterministically.
 *
 * This class supports the creation of objects that return random numbers
 * from a fixed uniform distribution.  It also supports the generation of
 * single random numbers from various uniform distributions.
 *
 * The low end of the range is always included and the high end
 * of the range is always excluded.
 *
 * Here is an example of how to use this class:
 * \code
 *   double min = 0.0;
 *   double max = 10.0;
 *  
 *   Ptr<UniformRandomVariable> x = CreateObject<UniformRandomVariable> ();
 *   x->SetAttribute ("Min", DoubleValue (min));
 *   x->SetAttribute ("Max", DoubleValue (max));
 * 
 *   // The values returned by a uniformly distributed random
 *   // variable should always be within the range
 *   //
 *   //     [min, max)  .
 *   //
 *   double value = x->GetValue ();
 * \endcode
 */
class UniformRandomVariable : public RandomVariableStream
{
public:
  static TypeId GetTypeId (void);

  /**
   * \brief Creates a uniform distribution RNG with the default range.
   */
  UniformRandomVariable ();

  /**
   * \brief Returns the lower bound on values that can be returned by this RNG stream.
   * \return The lower bound on values that can be returned by this RNG stream.
   */
  double GetMin (void) const;

  /**
   * \brief Returns the upper bound on values that can be returned by this RNG stream.
   * \return The upper bound on values that can be returned by this RNG stream.
   */
  double GetMax (void) const;

  /**
   * \brief Returns a random double from the uniform distribution with the specified range.
   * \param min Low end of the range.
   * \param max High end of the range.
   * \return A floating point random value.
   *
   * Note that antithetic values are being generated if
   * m_isAntithetic is equal to true.  If \f$x\f$ is a value that
   * would be returned normally, then \f$(max - x\f$) is the distance
   * that \f$x\f$ would be from \f$max\f$.  The value returned in the
   * antithetic case, \f$x'\f$, is calculated as
   *
   *    \f[
   *    x'  =  min + (max - x)  ,
   *    \f]
   *
   * which is the lower bound plus the distance \f$x\f$ is from the
   * upper bound.
   */
  double GetValue (double min, double max);

  /**
   * \brief Returns a random unsigned integer from a uniform distribution over the interval [min,max] including both ends.
   * \param min Low end of the range.
   * \param max High end of the range.
   * \return A random unsigned integer value.
   *
   * Note that antithetic values are being generated if
   * m_isAntithetic is equal to true.  If \f$x\f$ is a value that
   * would be returned normally, then \f$(max - x\f$) is the distance
   * that \f$x\f$ would be from \f$max\f$.  The value returned in the
   * antithetic case, \f$x'\f$, is calculated as
   *
   *    \f[
   *    x'  =  min + (max - x)  ,
   *    \f]
   *
   * which is the lower bound plus the distance \f$x\f$ is from the
   * upper bound.
   */
  uint32_t GetInteger (uint32_t min, uint32_t max);

  /**
   * \brief Returns a random double from the uniform distribution with the range [min,max), where min and max are the current lower and upper bounds.
   * \return A floating point random value.
   *
   * Note that antithetic values are being generated if
   * m_isAntithetic is equal to true.  If \f$x\f$ is a value that
   * would be returned normally, then \f$(max - x\f$) is the distance
   * that \f$x\f$ would be from \f$max\f$.  The value returned in the
   * antithetic case, \f$x'\f$, is calculated as
   *
   *    \f[
   *        x'  =  min + (max - x)  ,
   *    \f]
   *
   * which is the lower bound plus the distance \f$x\f$ is from the
   * upper bound.
   *
   * Note that we have to re-implement this method here because the method is
   * overloaded above for the two-argument variant and the c++ name resolution
   * rules don't work well with overloads split between parent and child
   * classes.
   */
  virtual double GetValue (void);

  /**
   * \brief Returns a random unsigned integer from a uniform distribution over the interval [min,max] including both ends, where min and max are the current lower and upper bounds.
   * \return A random unsigned integer value.
   *
   * Note that antithetic values are being generated if
   * m_isAntithetic is equal to true.  If \f$x\f$ is a value that
   * would be returned normally, then \f$(max - x\f$) is the distance
   * that \f$x\f$ would be from \f$max\f$.  The value returned in the
   * antithetic case, \f$x'\f$, is calculated as
   *
   *    \f[
   *        x'  =  min + (max - x)  ,
   *    \f]
   *
   * which is the lower bound plus the distance \f$x\f$ is from the
   * upper bound.
   */
  virtual uint32_t GetInteger (void);
private:
  /// The lower bound on values that can be returned by this RNG stream.
  double m_min;

  /// The upper bound on values that can be returned by this RNG stream.
  double m_max;
};

} // namespace ns3

#endif /* RANDOM_VARIABLE_STREAM_H */