TUnuran class.

Interface to the UNU.RAN package for generating non uniform random numbers. This class wraps the UNU.RAN calls in C++ methods. It provides methods for initializing Unuran and then to sample the desired distribution. It provides support for initializing UNU.RAN in these following way (various signatures for TUnuran::Init)

with string API via TUnuran::Init passing the distribution type and the method
using a one-dimensional distribution object defined by TUnuranContDist
using a multi-dimensional distribution object defined by TUnuranMultiContDist
using a discrete one-dimensional distribution object defined by TUnuranDiscrDist
using an empirical distribution defined by TUnuranEmpDist
using pre-defined distributions. Presently only support for Poisson (TUnuran::InitPoisson) and Binomial (TUnuran::InitBinomial) are provided. Other distributions can however be generated using the previous methods (in particular via the string API)

The sampling is provided via these methods:

TUnuran::Sample() returns a double for all one-dimensional distribution
TUnuran::SampleDiscr() returns an integer for one-dimensional discrete distribution
TUnuran::Sample(double *) sample a multi-dimensional distribution. A pointer to a vector with size at least equal to the distribution dimension must be passed

In addition is possible to set the random number generator in the constructor of the class, its seed via the TUnuran::SetSeed() method.

Definition at line 79 of file TUnuran.h.

Public Member Functions
	TUnuran (const TUnuran &)=delete

	TUnuran (TRandom *r=nullptr, unsigned int log=0)
	Constructor with a generator instance and given level of log output.

	TUnuran (TUnuran &&)=delete

	~TUnuran ()
	Destructor.

int	GetDimension () const
	Return the dimension of unuran generator method.

int	GetDistType () const
	Return the type of the distribution.

std::string	GetGenId () const
	Return an ID string about the unuran generator method.

std::string	GetInfo (bool extended=false)
	Return an information string about the used Unuran generator method.

TRandom *	GetRandom ()
	Return instance of the random engine used.

bool	Init (const std::string &distr, const std::string &method)
	Initialize with Unuran string API interface.

bool	Init (const TUnuranContDist &distr, const std::string &method="auto")
	Initialize method for continuous one-dimensional distribution.

bool	Init (const TUnuranDiscrDist &distr, const std::string &method="auto")
	Initialize method for continuous one-dimensional discrete distribution.

bool	Init (const TUnuranEmpDist &distr, const std::string &method="empk")
	Initialize method for continuous empirical distribution.

bool	Init (const TUnuranMultiContDist &distr, const std::string &method="vnrou")
	Initialize method for continuous multi-dimensional distribution.

bool	InitBinomial (unsigned int ntot, double prob, const std::string &method="dstd")
	Initialize method for the Binomial distribution.

bool	InitPoisson (double mu, const std::string &method="dstd")
	Initialize method for the Poisson distribution.

bool	IsDistCont () const
	Return true for a univariate continuous distribution.

bool	IsDistDiscrete () const
	Return true for a discrete distribution.

bool	IsDistEmpirical () const
	Return true for an empirical distribution.

bool	IsDistMultiCont () const
	Return true for a multivariate continuous distribution.

const std::string &	MethodName () const
	used Unuran method

TUnuran &	operator= (const TUnuran &rhs)=delete

TUnuran &	operator= (TUnuran &&rhs)=delete

bool	ReInitDiscrDist (unsigned int npar, double *params)
	Reinitialize UNURAN by changing the distribution parameters but maintaining same distribution and method.

double	Sample ()
	Sample 1D distribution.

int	SampleDiscr ()
	Sample discrete distributions.

bool	SampleMulti (double *x)
	Sample multidimensional distributions.

bool	SetLogLevel (unsigned int iflag=1)
	set log level

bool	SetLogStream ()
	set stream for log and error (not yet implemented)

void	SetRandom (TRandom *r)
	Set the random engine.

void	SetSeed (unsigned int seed)
	set the seed for the random number generator

Protected Member Functions
bool	SetContDistribution (const TUnuranContDist &dist)

bool	SetDiscreteDistribution (const TUnuranDiscrDist &dist)

bool	SetEmpiricalDistribution (const TUnuranEmpDist &dist)

bool	SetMethodAndInit ()
	change the method and initialize Unuran with the previously given distribution

bool	SetMultiDistribution (const TUnuranMultiContDist &dist)

bool	SetRandomGenerator ()

Protected Attributes
std::unique_ptr< TUnuranBaseDist >	fDist

UNUR_GEN *	fGen

std::string	fMethod

TRandom *	fRng

UNUR_DISTR *	fUdistr

UNUR_URNG *	fUrng

#include <TUnuran.h>

Constructor & Destructor Documentation

◆ TUnuran() [1/3]

TUnuran::TUnuran	(	TRandom *	r = `nullptr`,
		unsigned int	log = `0`
	)

Constructor with a generator instance and given level of log output.

Definition at line 32 of file TUnuran.cxx.

◆ ~TUnuran()

TUnuran::~TUnuran ( )

Destructor.

Definition at line 53 of file TUnuran.cxx.

◆ TUnuran() [2/3]

TUnuran::TUnuran ( const TUnuran & )

delete

◆ TUnuran() [3/3]

TUnuran::TUnuran ( TUnuran && )

delete

Member Function Documentation

◆ GetDimension()

int TUnuran::GetDimension ( ) const

Return the dimension of unuran generator method.

For 1D method returns 1 and for the multi-dimensional case must be equal to the distribution dimension.

Definition at line 376 of file TUnuran.cxx.

◆ GetDistType()

int TUnuran::GetDistType ( ) const

Return the type of the distribution.

See documentation of unuran_distr_get_type for the possible types of distributions.

Definition at line 383 of file TUnuran.cxx.

◆ GetGenId()

std::string TUnuran::GetGenId ( ) const

Return an ID string about the unuran generator method.

Definition at line 369 of file TUnuran.cxx.

◆ GetInfo()

std::string TUnuran::GetInfo ( bool extended = false )

Return an information string about the used Unuran generator method.

Parameters

extended : if true return some helper information about the existing options of the method.

Definition at line 362 of file TUnuran.cxx.

◆ GetRandom()

TRandom * TUnuran::GetRandom ( )

inline

Return instance of the random engine used.

Definition at line 223 of file TUnuran.h.

◆ Init() [1/5]

bool TUnuran::Init	(	const std::string &	distr,
		const std::string &	method
	)

Initialize with Unuran string API interface.

See https://statmath.wu.ac.at/unuran/doc/unuran.html#StringAPI

Parameters

distr	: UNU.RAN distribution string
method	: UNU.RAN method string

Here is an example using the string API:

Tunuran unr;

unr.Init("normal(3.,0.75); domain = (0,inf)", "method = tdr; c = 0");

Definition at line 62 of file TUnuran.cxx.

◆ Init() [2/5]

bool TUnuran::Init	(	const TUnuranContDist &	distr,
		const std::string &	method = `"auto"`
	)

Initialize method for continuous one-dimensional distribution.

User must provide a distribution object (which is copied inside) and a string for a method. For the list of available method for 1D cont. distribution see the UnuRan doc. A re-initialization is needed whenever distribution parameters have been changed. Note that the method string can contain in addition to the method name all the specific method parameters specified using the UNURAN method string API. For example a valid string can be "method=arou; max_segments=1000; max_sqhratio = 0.9"

Definition at line 76 of file TUnuran.cxx.

◆ Init() [3/5]

bool TUnuran::Init	(	const TUnuranDiscrDist &	distr,
		const std::string &	method = `"auto"`
	)

Initialize method for continuous one-dimensional discrete distribution.

User must provide a distribution object (which is copied inside) and a string for a method. For the list of available method for 1D discrete distribution see the UnuRan doc A re-initialization is needed whenever distribution parameters have been changed.

Definition at line 108 of file TUnuran.cxx.

◆ Init() [4/5]

bool TUnuran::Init	(	const TUnuranEmpDist &	distr,
		const std::string &	method = `"empk"`
	)

Initialize method for continuous empirical distribution.

User must provide a distribution object (which is copied inside) and a string for a method. The distribution object can represent binned (only 1D) or unbinned (1D or multi-dim) data The method for the unbinned empirical distribution are based on the kernel smoothing, see UnuRan doc A re-initialization is needed whenever distribution parameters have been changed.

Definition at line 122 of file TUnuran.cxx.

◆ Init() [5/5]

bool TUnuran::Init	(	const TUnuranMultiContDist &	distr,
		const std::string &	method = `"vnrou"`
	)

Initialize method for continuous multi-dimensional distribution.

User must provide a distribution object (which is copied inside) and a string for a method. For the list of available method for multivariate cont. distribution see the UnuRan doc A re-initialization is needed whenever distribution parameters have been changed.

The default method used for multi-dimensional distributions is "vnrou" Note that some of the multi-dimensional continuous distribution methods like "hitro" are based on Markov-CHain sampler and they are much faster for sampling but require more time to converge. Furthermore, since they are Markov-Chain methods their generated sample values are correlated and cannot be used as i.i.d., one can instead use the obtained sample distribution. (see also the ROOT issue: #10222 ).

Definition at line 92 of file TUnuran.cxx.

◆ InitBinomial()

bool TUnuran::InitBinomial	(	unsigned int	ntot,
		double	prob,
		const std::string &	method = `"dstd"`
	)

Initialize method for the Binomial distribution.

Used to generate poisson numbers for a constant parameters (n,p) of the Binomial distribution. Use after the method TUnuran::SampleDiscr to generate the numbers. The flag reinit perform a fast re-initialization when only the distribution parameters are changed in the subsequent calls. If the same TUnuran object is used to generate with other distributions it cannot be used.

Definition at line 462 of file TUnuran.cxx.

◆ InitPoisson()

bool TUnuran::InitPoisson	(	double	mu,
		const std::string &	method = `"dstd"`
	)

Initialize method for the Poisson distribution.

Used to generate poisson numbers for a constant parameter mu of the Poisson distribution. Use after the method TUnuran::SampleDiscr to generate the numbers. The flag reinit perform a fast re-initialization when only the distribution parameters are changed in the subsequent calls. If the same TUnuran object is used to generate with other distributions it cannot be used.

Definition at line 448 of file TUnuran.cxx.

◆ IsDistCont()

bool TUnuran::IsDistCont ( ) const

Return true for a univariate continuous distribution.

Definition at line 390 of file TUnuran.cxx.

◆ IsDistDiscrete()

bool TUnuran::IsDistDiscrete ( ) const

Return true for a discrete distribution.

Definition at line 398 of file TUnuran.cxx.

◆ IsDistEmpirical()

bool TUnuran::IsDistEmpirical ( ) const

Return true for an empirical distribution.

Definition at line 402 of file TUnuran.cxx.

◆ IsDistMultiCont()

bool TUnuran::IsDistMultiCont ( ) const

Return true for a multivariate continuous distribution.

Definition at line 394 of file TUnuran.cxx.

◆ MethodName()

const std::string & TUnuran::MethodName ( ) const

inline

used Unuran method

Definition at line 281 of file TUnuran.h.

◆ operator=() [1/2]

TUnuran & TUnuran::operator= ( const TUnuran & rhs )

delete

◆ operator=() [2/2]

TUnuran & TUnuran::operator= ( TUnuran && rhs )

delete

◆ ReInitDiscrDist()

bool TUnuran::ReInitDiscrDist	(	unsigned int	npar,
		double *	params
	)

Reinitialize UNURAN by changing the distribution parameters but maintaining same distribution and method.

It is implemented now only for predefined discrete distributions like the poisson or the binomial

Definition at line 477 of file TUnuran.cxx.

◆ Sample()

double TUnuran::Sample ( )

Sample 1D distribution.

User is responsible for having previously correctly initialized with TUnuran::Init

Definition at line 414 of file TUnuran.cxx.

◆ SampleDiscr()

int TUnuran::SampleDiscr ( )

Sample discrete distributions.

User is responsible for having previously correctly initialized with TUnuran::Init

Definition at line 407 of file TUnuran.cxx.

◆ SampleMulti()

bool TUnuran::SampleMulti ( double * x )

Sample multidimensional distributions.

User is responsible for having previously correctly initialized with TUnuran::Init

Definition at line 421 of file TUnuran.cxx.

◆ SetContDistribution()

bool TUnuran::SetContDistribution ( const TUnuranContDist & dist )

protected

Definition at line 156 of file TUnuran.cxx.

◆ SetDiscreteDistribution()

bool TUnuran::SetDiscreteDistribution ( const TUnuranDiscrDist & dist )

protected

Definition at line 287 of file TUnuran.cxx.

◆ SetEmpiricalDistribution()

bool TUnuran::SetEmpiricalDistribution ( const TUnuranEmpDist & dist )

protected

Definition at line 246 of file TUnuran.cxx.

◆ SetLogLevel()

bool TUnuran::SetLogLevel ( unsigned int iflag = 1 )

set log level

Definition at line 433 of file TUnuran.cxx.

◆ SetLogStream()

bool TUnuran::SetLogStream ( )

inline

set stream for log and error (not yet implemented)

Definition at line 276 of file TUnuran.h.

◆ SetMethodAndInit()

bool TUnuran::SetMethodAndInit ( )

protected

change the method and initialize Unuran with the previously given distribution

Definition at line 332 of file TUnuran.cxx.

◆ SetMultiDistribution()

bool TUnuran::SetMultiDistribution ( const TUnuranMultiContDist & dist )

protected

Definition at line 202 of file TUnuran.cxx.

◆ SetRandom()

void TUnuran::SetRandom ( TRandom * r )

inline

Set the random engine.

Must be called before init to have effect

Definition at line 216 of file TUnuran.h.

◆ SetRandomGenerator()

bool TUnuran::SetRandomGenerator ( )

protected

Definition at line 139 of file TUnuran.cxx.

◆ SetSeed()

void TUnuran::SetSeed ( unsigned int seed )

set the seed for the random number generator

Definition at line 429 of file TUnuran.cxx.

Member Data Documentation

◆ fDist

std::unique_ptr<TUnuranBaseDist> TUnuran::fDist

protected

Definition at line 308 of file TUnuran.h.

◆ fGen

UNUR_GEN* TUnuran::fGen

protected

Definition at line 305 of file TUnuran.h.

◆ fMethod

std::string TUnuran::fMethod

protected

Definition at line 310 of file TUnuran.h.

◆ fRng

TRandom* TUnuran::fRng

protected

Definition at line 309 of file TUnuran.h.

◆ fUdistr

UNUR_DISTR* TUnuran::fUdistr

protected

Definition at line 306 of file TUnuran.h.

◆ fUrng

UNUR_URNG* TUnuran::fUrng

protected

Definition at line 307 of file TUnuran.h.

Libraries for TUnuran:

[legend]

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

math/unuran/inc/TUnuran.h
math/unuran/src/TUnuran.cxx

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ TUnuran() [1/3]

◆ ~TUnuran()

◆ TUnuran() [2/3]

◆ TUnuran() [3/3]

Member Function Documentation

◆ GetDimension()

◆ GetDistType()

◆ GetGenId()

◆ GetInfo()

◆ GetRandom()

◆ Init() [1/5]

◆ Init() [2/5]

◆ Init() [3/5]

◆ Init() [4/5]

◆ Init() [5/5]

◆ InitBinomial()

◆ InitPoisson()

◆ IsDistCont()

◆ IsDistDiscrete()

◆ IsDistEmpirical()

◆ IsDistMultiCont()

◆ MethodName()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ReInitDiscrDist()

◆ Sample()

◆ SampleDiscr()

◆ SampleMulti()

◆ SetContDistribution()

◆ SetDiscreteDistribution()

◆ SetEmpiricalDistribution()

◆ SetLogLevel()

◆ SetLogStream()

◆ SetMethodAndInit()

◆ SetMultiDistribution()

◆ SetRandom()

◆ SetRandomGenerator()

◆ SetSeed()

Member Data Documentation

◆ fDist

◆ fGen

◆ fMethod

◆ fRng

◆ fUdistr

◆ fUrng