ThePEG::Selector< T, WeightType > Class Template Reference

Selector is a templated class for storing objects associated with probabilities in a way such that, given a flat random number between 0 and 1, an object can be selected according to its relative probability. More...

#include <Selector.h>

List of all members.

Public Types

typedef map< WeightType, T,
less< WeightType > > 
MapType
 Map doubles to objects.
typedef MapType::const_iterator const_iterator
 Iterator corresponding to the underlying map.
typedef MapType::iterator iterator
 Iterator corresponding to the underlying map.
typedef MapType::size_type size_type
 Size type of the underlying map.

Public Member Functions

 Selector ()
 Default constructor.
void swap (Selector &s)
 Swap the underlying representation with the argument.
WeightType insert (WeightType d, const T &t)
 Insert an object given a probability for this object.
WeightType reweight (WeightType d, const T &t)
 Reweight an object previously inserted giving it a new weight.
WeightType erase (const T &)
 Erase an object, previously inserted.
void replace (const T &oldObject, const T &newObject)
 Replace all occurencies of oldObject with newObject without changing the probability for the entry.
T & select (double rnd, double *remainder=0) throw (range_error)
 Select an object randomly.
T & operator[] (double rnd) throw (range_error)
 Selct an object randomly.
const T & select (double rnd, double *remainder=0) const throw (range_error)
 Selct an object randomly.
const T & operator[] (double rnd) const throw (range_error)
 Selct an object randomly.
template<typename RNDGEN>
T & select (RNDGEN &rnd) throw (range_error)
 Selct an object randomly.
template<typename RNDGEN>
const T & select (RNDGEN &rnd) const throw (range_error)
 Selct an object randomly.
WeightType sum () const
 Return the sum of probabilities of the objects inserted.
const_iterator begin () const
 Access to the begin() iterator of the underlying map.
const_iterator end () const
 Access to the end() iterator in the underlying map.
bool empty () const
 Returns true if the Selector is empty.
size_type size () const
 Returns the number of objects in the selector.
void clear ()
 Erases all objects.
template<typename OStream>
void output (OStream &) const
 Output to a stream.
template<typename IStream>
void input (IStream &)
 Input from a stream.

Private Attributes

MapType theMap
 The underlying map relating sums of probabilities to inserted objects.
WeightType theSum
 The sum of all probabilities assicialted with inserted objects.


Detailed Description

template<typename T, typename WeightType = double>
class ThePEG::Selector< T, WeightType >

Selector is a templated class for storing objects associated with probabilities in a way such that, given a flat random number between 0 and 1, an object can be selected according to its relative probability.

Internally, the objects of class T are stored in a map where the key is the probability of the corresponding object plus the accumulated sum of probabilities of all objects before the current one in the map. This allows for fast retreival of an object according to its probability. Where fast means that the time increases as a logarithm of the number of objects in the selector.

Here is an example on how to use the class:
double random(); // A random generator returning a number between 0 and 1.
class foo; // Any class.
Selector<foo*> bar; // A selector.
foo f1, f2;
bar.insert(0.5,&f1) // assign probability 0.5
bar.insert(0.5,&f2) // to each of f1 and f2
foo * f = bar.select(random()) // randomly returns a pointer to f1 or f2

See also:
VSelector

Definition at line 46 of file Selector.h.


Member Typedef Documentation

template<typename T, typename WeightType = double>
typedef map<WeightType, T, less<WeightType> > ThePEG::Selector< T, WeightType >::MapType

Map doubles to objects.

Definition at line 51 of file Selector.h.

template<typename T, typename WeightType = double>
typedef MapType::const_iterator ThePEG::Selector< T, WeightType >::const_iterator

Iterator corresponding to the underlying map.

Definition at line 54 of file Selector.h.

template<typename T, typename WeightType = double>
typedef MapType::iterator ThePEG::Selector< T, WeightType >::iterator

Iterator corresponding to the underlying map.

Definition at line 57 of file Selector.h.

template<typename T, typename WeightType = double>
typedef MapType::size_type ThePEG::Selector< T, WeightType >::size_type

Size type of the underlying map.

Definition at line 60 of file Selector.h.


Member Function Documentation

template<typename T, typename WeightType = double>
WeightType ThePEG::Selector< T, WeightType >::insert ( WeightType  d,
const T &  t 
) [inline]

Insert an object given a probability for this object.

If the probability is zero or negative, the object will not be inserted and the probability itself is returned. Otherwise the sum of probabilities so far is returned.

Definition at line 84 of file Selector.h.

Referenced by ThePEG::Selector< ThePEG::Pointer::TransientRCPtr >::reweight().

template<typename T, typename WeightType = double>
WeightType ThePEG::Selector< T, WeightType >::reweight ( WeightType  d,
const T &  t 
) [inline]

Reweight an object previously inserted giving it a new weight.

Semantically reweight(w,o); is equivalent to erase(o); insert(w,o);

Definition at line 97 of file Selector.h.

template<typename T, typename WeightType = double>
WeightType ThePEG::Selector< T, WeightType >::erase ( const T &   ) 

Erase an object, previously inserted.

If the object had not been inserted, nothing will happen. If several copies of the object has been inserted, all will be removed removed. In all cases the sum of the remaining probabilities is returned.

Referenced by ThePEG::Selector< ThePEG::Pointer::TransientRCPtr >::reweight().

template<typename T, typename WeightType = double>
T& ThePEG::Selector< T, WeightType >::select ( double  rnd,
double *  remainder = 0 
) throw (range_error)

Select an object randomly.

Given a random number flatly distributed in the interval ]0,1[ Select an object according to the individual probabilities specified when they were inserted. If rnd <= 0 or if rnd >= 1 or the Selector is empty, a range_error will be thrown.

Parameters:
rnd a flat random number in the interval ]0,1[
remainder if non-zero the double pointed to will be set to a uniform random number in the interval ]0,1[ calculated from the fraction of rnd which was in the range of the selected object.

Referenced by ThePEG::Selector< ThePEG::Pointer::TransientRCPtr >::operator[](), and ThePEG::Selector< ThePEG::Pointer::TransientRCPtr >::select().

template<typename T, typename WeightType = double>
T& ThePEG::Selector< T, WeightType >::operator[] ( double  rnd  )  throw (range_error) [inline]

Selct an object randomly.

Given a random number flatly distributed in the interval ]0,1[ Select an object according to the individual probabilities specified when they were inserted. If rnd <= 0 or if rnd >= 1 or the Selector is empty, a range_error will be thrown.

Definition at line 140 of file Selector.h.

template<typename T, typename WeightType = double>
const T& ThePEG::Selector< T, WeightType >::select ( double  rnd,
double *  remainder = 0 
) const throw (range_error)

Selct an object randomly.

Given a random number flatly distributed in the interval ]0,1[ Select an object according to the individual probabilities specified when they were inserted. If rnd <= 0 or if rnd >= 1 or the Selector is empty, a range_error will be thrown.

Parameters:
rnd a flat random number in the interval ]0,1[
remainder if non-zero the double pointed to will be set to a uniform random number in the interval ]0,1[ calculated from the fraction of rnd which was in the range of the selected object.

template<typename T, typename WeightType = double>
const T& ThePEG::Selector< T, WeightType >::operator[] ( double  rnd  )  const throw (range_error) [inline]

Selct an object randomly.

Given a random number flatly distributed in the interval ]0,1[ select an object according to the individual probabilities specified when they were inserted. If rnd <= 0 or if rnd >= 1 or the Selector is empty, a range_error will be thrown.

Definition at line 162 of file Selector.h.

template<typename T, typename WeightType = double>
template<typename RNDGEN>
T& ThePEG::Selector< T, WeightType >::select ( RNDGEN &  rnd  )  throw (range_error) [inline]

Selct an object randomly.

Given a random number generator which generates flat random numbers in the interval ]0,1[ with the operator()() function, select an object according to the individual probabilities specified when they were inserted. If the generated number is outside the allowed range or the Selector is empty, a range_error will be thrown. The generator should have a push_back function which will be used push back a uniform random number in the interval ]0,1[ calculated from the fraction of rnd which was in the range of the selected object.

Definition at line 177 of file Selector.h.

template<typename T, typename WeightType = double>
template<typename RNDGEN>
const T& ThePEG::Selector< T, WeightType >::select ( RNDGEN &  rnd  )  const throw (range_error) [inline]

Selct an object randomly.

Given a random number generator which generates flat random numbers in the interval ]0,1[ with the operator()() function, select an object according to the individual probabilities specified when they were inserted. If the generated number is outside the allowed range or the Selector is empty, a range_error will be thrown. The generator should have a push_back function which will be used push back a uniform random number in the interval ]0,1[ calculated from the fraction of rnd which was in the range of the selected object.

Definition at line 197 of file Selector.h.

template<typename T, typename WeightType = double>
WeightType ThePEG::Selector< T, WeightType >::sum (  )  const [inline]

Return the sum of probabilities of the objects inserted.

Note that probabilities specified when objects are inserted are rescaled with this number to give unit probability for 'select()'.

Definition at line 210 of file Selector.h.

template<typename T, typename WeightType = double>
const_iterator ThePEG::Selector< T, WeightType >::begin (  )  const [inline]

Access to the begin() iterator of the underlying map.

Dereferenced, it will give a std::pair<WeightType, T>, where 'first' is the sum of all probabilities up to this one, and 'second' is the object inserted.

Definition at line 218 of file Selector.h.


The documentation for this class was generated from the following file:

Generated on Thu Apr 29 12:43:25 2010 for ThePEG by  doxygen 1.5.5