VSelector 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 <VSelector.h>

Inheritance diagram for ThePEG::VSelector< T, WeightType >:

[legend]

Public Types
typedef vector< WeightType >	WeightVector
	A vector of weights.

typedef WeightVector::const_iterator	WIterator
	The weight vector iterator type.

typedef vector< T >	ObjectVector
	A vector ob objects.

typedef ObjectVector::iterator	iterator
	The object vector iterator type.

typedef ObjectVector::const_iterator	const_iterator
	The object vector const iterator type.

typedef ObjectVector::size_type	size_type
	Size type of the underlying vector.

Public Member Functions
	VSelector (size_type reserved=0)
	Default constructor.

void	swap (VSelector &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, const T &)
	Reweight an object previously inserted giving it a new weight.

WeightType	erase (const T &)
	Erase an object, previously inserted.

void	replace (const T &told, const T &tnew)
	Replace all occurencies of told with tnew without changing the probability for the entry.

T &	select (double rnd, double *remainder=0)
	Select an object randomly.

T &	operator[] (double rnd)
	Selct an object randomly.

const T &	select (double rnd, double *remainder=0) const
	Selct an object randomly.

const T &	operator[] (double rnd) const
	Selct an object randomly.

template<typename RNDGEN >
T &	select (RNDGEN &rnd)
	Selct an object randomly.

template<typename RNDGEN >
const T &	select (RNDGEN &rnd) const
	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 vector of objects.

const_iterator	end () const
	Access to the `end()` iterator in the underlying vector of objects.

bool	empty () const
	Returns true if the VSelector is empty.

size_type	size () const
	Returns the number of objects in the selector.

void	reserve (size_type reserved)
	Allocate space for a number of objects in the underlying vectors.

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.

Protected Member Functions
size_type	iselect (double rnd, double *remainder) const
	Internal selection engine.

Private Attributes
WeightVector	theSums
	The vector of accumulated weights for the objects in the selector.

WeightVector	theWeights
	The vector of weights for the objects in the selector.

ObjectVector	theObjects
	The vector of objects in the selector.

WeightType	theSum
	The sum of all weights.

Detailed Description

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

VSelector 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 vector parallel to a vector of the probability of the corresponding object plus the accumulated sum of probabilities of all objects before the current one in the vector. 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.
VSelector<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: Selector

Definition at line 46 of file VSelector.h.

Member Typedef Documentation

◆ const_iterator

template<typename T , typename WeightType = double>

typedef ObjectVector::const_iterator ThePEG::VSelector< T, WeightType >::const_iterator

The object vector const iterator type.

Definition at line 63 of file VSelector.h.

◆ iterator

template<typename T , typename WeightType = double>

typedef ObjectVector::iterator ThePEG::VSelector< T, WeightType >::iterator

The object vector iterator type.

Definition at line 60 of file VSelector.h.

◆ ObjectVector

template<typename T , typename WeightType = double>

typedef vector<T> ThePEG::VSelector< T, WeightType >::ObjectVector

A vector ob objects.

Definition at line 57 of file VSelector.h.

◆ size_type

template<typename T , typename WeightType = double>

typedef ObjectVector::size_type ThePEG::VSelector< T, WeightType >::size_type

Size type of the underlying vector.

Definition at line 66 of file VSelector.h.

◆ WeightVector

template<typename T , typename WeightType = double>

typedef vector<WeightType> ThePEG::VSelector< T, WeightType >::WeightVector

A vector of weights.

Definition at line 51 of file VSelector.h.

◆ WIterator

template<typename T , typename WeightType = double>

typedef WeightVector::const_iterator ThePEG::VSelector< T, WeightType >::WIterator

The weight vector iterator type.

Definition at line 54 of file VSelector.h.

Constructor & Destructor Documentation

◆ VSelector()

template<typename T , typename WeightType = double>

ThePEG::VSelector< T, WeightType >::VSelector ( size_type reserved = 0 )

inline

Default constructor.

Definition at line 73 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::reserve().

Member Function Documentation

◆ begin()

template<typename T , typename WeightType = double>

const_iterator ThePEG::VSelector< T, WeightType >::begin ( ) const

inline

Access to the begin() iterator of the underlying vector of objects.

Definition at line 231 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theObjects.

◆ clear()

template<typename T , typename WeightType = double>

void ThePEG::VSelector< T, WeightType >::clear ( )

inline

Erases all objects.

Definition at line 261 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theObjects, ThePEG::VSelector< T, WeightType >::theSum, ThePEG::VSelector< T, WeightType >::theSums, and ThePEG::VSelector< T, WeightType >::theWeights.

◆ empty()

template<typename T , typename WeightType = double>

bool ThePEG::VSelector< T, WeightType >::empty ( ) const

inline

Returns true if the VSelector is empty.

Definition at line 242 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theObjects.

◆ end()

template<typename T , typename WeightType = double>

const_iterator ThePEG::VSelector< T, WeightType >::end ( ) const

inline

Access to the end() iterator in the underlying vector of objects.

Definition at line 237 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theObjects.

◆ erase()

template<typename T , typename WeightType = double>

WeightType ThePEG::VSelector< 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 probabilities is returned.

◆ insert()

template<typename T , typename WeightType = double>

WeightType ThePEG::VSelector< 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 is returned.

Definition at line 94 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theObjects, ThePEG::VSelector< T, WeightType >::theSum, ThePEG::VSelector< T, WeightType >::theSums, and ThePEG::VSelector< T, WeightType >::theWeights.

◆ operator[]() [1/2]

template<typename T , typename WeightType = double>

T & ThePEG::VSelector< T, WeightType >::operator[] ( double rnd )

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 149 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::select().

◆ operator[]() [2/2]

template<typename T , typename WeightType = double>

const T & ThePEG::VSelector< T, WeightType >::operator[] ( double rnd ) const

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 175 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::select().

◆ replace()

template<typename T , typename WeightType = double>

void ThePEG::VSelector< T, WeightType >::replace	(	const T &	told,
		const T &	tnew
	)

inline

Replace all occurencies of told with tnew without changing the probability for the entry.

Definition at line 122 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theObjects.

◆ reserve()

template<typename T , typename WeightType = double>

void ThePEG::VSelector< T, WeightType >::reserve ( size_type reserved )

inline

Allocate space for a number of objects in the underlying vectors.

Definition at line 252 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theObjects, ThePEG::VSelector< T, WeightType >::theSums, and ThePEG::VSelector< T, WeightType >::theWeights.

Referenced by ThePEG::VSelector< T, WeightType >::VSelector().

◆ reweight()

template<typename T , typename WeightType = double>

WeightType ThePEG::VSelector< T, WeightType >::reweight	(	WeightType	,
		const T &
	)

Reweight an object previously inserted giving it a new weight.

If several equivalent objects exists, all of them will be reweighted.

◆ select() [1/4]

template<typename T , typename WeightType = double>

T & ThePEG::VSelector< T, WeightType >::select	(	double	rnd,
		double *	remainder = `0`
	)

inline

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.

Definition at line 138 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::iselect(), and ThePEG::VSelector< T, WeightType >::theObjects.

Referenced by ThePEG::VSelector< T, WeightType >::operator[](), and ThePEG::VSelector< T, WeightType >::select().

◆ select() [2/4]

template<typename T , typename WeightType = double>

const T & ThePEG::VSelector< T, WeightType >::select	(	double	rnd,
		double *	remainder = `0`
	)		const

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.

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.

Definition at line 164 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::iselect(), and ThePEG::VSelector< T, WeightType >::theObjects.

◆ select() [3/4]

template<typename T , typename WeightType = double>

template<typename RNDGEN >

T & ThePEG::VSelector< T, WeightType >::select ( RNDGEN & rnd )

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 192 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::select().

◆ select() [4/4]

template<typename T , typename WeightType = double>

template<typename RNDGEN >

const T & ThePEG::VSelector< T, WeightType >::select ( RNDGEN & rnd ) const

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 212 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::select().

◆ size()

template<typename T , typename WeightType = double>

size_type ThePEG::VSelector< T, WeightType >::size ( ) const

inline

Returns the number of objects in the selector.

Definition at line 247 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theObjects.

◆ sum()

template<typename T , typename WeightType = double>

WeightType ThePEG::VSelector< 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 225 of file VSelector.h.

References ThePEG::VSelector< T, WeightType >::theSum.

◆ swap()

template<typename T , typename WeightType = double>

void ThePEG::VSelector< T, WeightType >::swap ( VSelector< T, WeightType > & s )

inline

Swap the underlying representation with the argument.

Definition at line 81 of file VSelector.h.

References std::swap(), ThePEG::VSelector< T, WeightType >::theObjects, ThePEG::VSelector< T, WeightType >::theSum, ThePEG::VSelector< T, WeightType >::theSums, and ThePEG::VSelector< T, WeightType >::theWeights.

Member Data Documentation

◆ theObjects

template<typename T , typename WeightType = double>

ObjectVector ThePEG::VSelector< T, WeightType >::theObjects

private

The vector of objects in the selector.

Definition at line 302 of file VSelector.h.

Referenced by ThePEG::VSelector< T, WeightType >::begin(), ThePEG::VSelector< T, WeightType >::clear(), ThePEG::VSelector< T, WeightType >::empty(), ThePEG::VSelector< T, WeightType >::end(), ThePEG::VSelector< T, WeightType >::insert(), ThePEG::VSelector< T, WeightType >::replace(), ThePEG::VSelector< T, WeightType >::reserve(), ThePEG::VSelector< T, WeightType >::select(), ThePEG::VSelector< T, WeightType >::size(), and ThePEG::VSelector< T, WeightType >::swap().

◆ theSum

template<typename T , typename WeightType = double>

WeightType ThePEG::VSelector< T, WeightType >::theSum

private

The sum of all weights.

Definition at line 307 of file VSelector.h.

Referenced by ThePEG::VSelector< T, WeightType >::clear(), ThePEG::VSelector< T, WeightType >::insert(), ThePEG::VSelector< T, WeightType >::sum(), and ThePEG::VSelector< T, WeightType >::swap().

◆ theSums

template<typename T , typename WeightType = double>

WeightVector ThePEG::VSelector< T, WeightType >::theSums

private

The vector of accumulated weights for the objects in the selector.

Definition at line 292 of file VSelector.h.

Referenced by ThePEG::VSelector< T, WeightType >::clear(), ThePEG::VSelector< T, WeightType >::insert(), ThePEG::VSelector< T, WeightType >::reserve(), and ThePEG::VSelector< T, WeightType >::swap().

◆ theWeights

template<typename T , typename WeightType = double>

WeightVector ThePEG::VSelector< T, WeightType >::theWeights

private

The vector of weights for the objects in the selector.

Definition at line 297 of file VSelector.h.

Referenced by ThePEG::VSelector< T, WeightType >::clear(), ThePEG::VSelector< T, WeightType >::insert(), ThePEG::VSelector< T, WeightType >::reserve(), and ThePEG::VSelector< T, WeightType >::swap().

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

VSelector.h

Public Types

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ iterator

◆ ObjectVector

◆ size_type

◆ WeightVector

◆ WIterator

Constructor & Destructor Documentation

◆ VSelector()

Member Function Documentation

◆ begin()

◆ clear()

◆ empty()

◆ end()

◆ erase()

◆ insert()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ replace()

◆ reserve()

◆ reweight()

◆ select() [1/4]

◆ select() [2/4]

◆ select() [3/4]

◆ select() [4/4]

◆ size()

◆ sum()

◆ swap()

Member Data Documentation

◆ theObjects

◆ theSum

◆ theSums

◆ theWeights