UNU.RAN – Universal Non-Uniform RANdom number generators

1.1 Usage of this document

We designed this document in a way such that one can use UNU.RAN with reading as little as necessary. Read Installation for the instructions to install the library. Concepts of UNU.RAN, discribes the basics of UNU.RAN. It also has a short guideline for choosing an appropriate method. In Examples examples are given that can be copied and modified. They also can be found in the directory examples in the source tree.

Further information are given in consecutive chapters. Handling distribution objects, describes how to create and manipulate distribution objects. standard distributions, describes predefined distribution objects that are ready to use. Methods for generating non-uniform random variates describes the various methods in detail. For each of possible distribution classes (continuous, discrete, empirical, multivariate) there exists a short overview section that can be used to choose an appropriate method followed by sections that describe each of the particular methods in detail. These are merely for users with some knowledge about the methods who want to change method-specific parameters and can be ignored by others.

Abbreviations and explanation of some basic terms can be found in Glossary.

1.2 Installation

UNU.RAN was developed on an Intel architecture under Linux with the GNU C compiler but should compile and run on any computing environment. It requires an ANSI compliant C compiler.

Below find the installation instructions for unices.

Uniform random number generator

UNU.RAN can be used with any uniform random number generator but (at the moment) some features work best with Pierre L’Ecuyer’s RngStreams library (see http://statmath.wu.ac.at/software/RngStreams/ for a description and downloading. For details on using uniform random number in UNU.RAN see Using uniform random number generators.

Install the required libraries first.

UNU.RAN

1. First unzip and untar the package and change to the directory:

   tar zxvf unuran-1.11.0.tar.gz
   cd unuran-1.11.0
   

2. Optional: Edit the file src/unuran_config.h
3. Run a configuration script:

   sh ./configure --prefix=<prefix>
   

   where <prefix> is the root of the installation tree. When omitted /usr/local is used.

   Use ./configure --help to get a list of other options. In particular the following flags are important:

   • Enable support for some external sources of uniform random number generators (see Using uniform random number generators):

     --with-urng-rngstream

     URNG: use Pierre L’Ecuyer’s RNGSTREAM library [default=no]

     --with-urng-prng

     URNG: use Otmar Lendl’s PRNG library [default=no]

     --with-urng-gsl

     URNG: use random number generators from GNU Scientific Library [default=no]

     --with-urng-default

     URNG: global default URNG (builtin|rngstream) [default=builtin]

     We strongly recommend to use RngStreams library:

     sh ./configure --with-urng-rngstream --with-urng-default=rngstream
     

     Important: You must install the respective libraries RngStreams, PRNG and GSL before ./configure is executed.

   • Also make a shared library:

     --enable-shared

     build shared libraries [default=no]

   • The library provides the function unur_gen_info for information about generator objects. This is intented for using in interactive computing environments. This feature can be enabled / disabled by means of the configure flag

     --enable-info

     INFO: provide function with information about generator objects [default=yes]

   • Enable support for deprecated UNU.RAN routines if you have some problems with older application after upgrading the library:

     --enable-deprecated

     enable support for deprecated UNU.RAN routines [default=no]

   • Enable debugging tools:

     --enable-check-struct

     Debug: check validity of pointers to structures [default=no]

     --enable-logging

     Debug: print informations about generator into logfile [default=no]

4. Compile and install the libray:

   make
   make install
   

   Obviously $(prefix)/include and $(prefix)/lib must be in the search path of your compiler. You can use environment variables to add these directories to the search path. If you are using the bash type (or add to your profile):

   export LIBRARY_PATH="<prefix>/lib"
   export C_INCLURE_PATH="<prefix>/include"
   

   If you want to make a shared library, then making such a library can be enabled using

   sh ./configure --enable-shared
   

   If you want to link against the shared library make sure that it can be found when executing the binary that links to the library. If it is not installed in the usual path, then the easiest way is to set the LD_LIBRARY_PATH environment variable. See any operating system documentation about shared libraries for more information, such as the ld(1) and ld.so(8) manual pages.

5. Documentation in various formats (PDF, HTML, info, plain text) can be found in directory doc.
6. You can run some tests by

   make check
   

   However, some of these tests requires the usage of the PRNG or RngStreams library and are only executed if these are installed enabled by the corresponding configure flag.

   An extended set of tests is run by

   make fullcheck
   

   However some of these might fail occasionally due to roundoff errors or the mysteries of floating point arithmetic, since we have used some extreme settings to test the library.

Upgrading

• Important:

  UNU.RAN now relies on some aspects of IEEE 754 compliant floating point arithmetic. In particular, 1./0. and 0./0. must result in infinity and NaN (not a number), respectively, and must not cause a floating point exception. For allmost all modern compting architecture this is implemented in hardware. For others there should be a special compiler flag to get this feature (e.g., -MIEEE on DEC alpha or -mp for the Intel C complier).

• Upgrading UNU.RAN from version 0.9.x or earlier:

  With UNU.RAN version 1.0.x some of the macro definitions in file src/unuran_config.h are moved into file config.h and are set/controlled by the ./configure script.

  Writting logging information into the logfile must now be enabled when running the configure script:

  sh ./configure --enable-logging
  

• Upgrading UNU.RAN from version 0.7.x or earlier:

  With UNU.RAN version 0.8.0 the interface for changing underlying distributions and running a reinitialization routine has been simplified. The old routines can be compiled into the library using the following configure flag:

  sh ./configure --enable-deprecated
  

  Notice: Using these deprecated routines is not supported any more and this strong discouraged.

  Wrapper functions for external sources of uniform random numbers are now enabled by configure flags and not by macros defined in file src/unuran_config.h.

  The file src/unuran_config.h is not installed any more. It is now only included when the library is compiled. It should be removed from the global include path of the compiler.

1.3 Using the library

ANSI C Compliance

The library is written in ANSI C and is intended to conform to the ANSI C standard. It should be portable to any system with a working ANSI C compiler.

The library does not rely on any non-ANSI extensions in the interface it exports to the user. Programs you write using UNU.RAN can be ANSI compliant. Extensions which can be used in a way compatible with pure ANSI C are supported, however, via conditional compilation. This allows the library to take advantage of compiler extensions on those platforms which support them.

To avoid namespace conflicts all exported function names and variables have the prefix unur_, while exported macros have the prefix UNUR_.

Compiling and Linking

If you want to use the library you must include the UNU.RAN header file

#include <unuran.h>

If you also need the test routines then also add

#include <unuran_tests.h>

If wrapper functions for external sources of uniform random number generators are used, the corresponding header files must also be included, e.g.,

#include <unuran_urng_rngstream.h>

If these header files are not installed on the standard search path of your compiler you will also need to provide its location to the preprocessor as a command line flag. The default location of the unuran.h is /usr/local/include. A typical compilation command for a source file app.c with the GNU C compiler gcc is,

gcc -I/usr/local/include -c app.c

This results in an object file app.o. The default include path for gcc searches /usr/local/include automatically so the -I option can be omitted when UNU.RAN is installed in its default location.

The library is installed as a single file, libunuran.a. A shared version of the library is also installed on systems that support shared libraries. The default location of these files is /usr/local/lib. To link against the library you need to specify the main library. The following example shows how to link an application with the library (and the the RNGSTREAMS library if you decide to use this source of uniform pseudo-random numbers),

gcc app.o -lunuran -lrngstreams -lm

Shared Libraries

To run a program linked with the shared version of the library it may be necessary to define the shell variable LD_LIBRARY_PATH to include the directory where the library is installed. For example,

LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

To compile a statically linked version of the program instead, use the -static flag in gcc,

gcc -static app.o -lunuran -lrngstreams -lm

Compatibility with C++

The library header files automatically define functions to have extern "C" linkage when included in C++ programs.

1.4 Concepts of UNU.RAN

UNU.RAN is a C library for generating non-uniformly distributed random variates. Its emphasis is on the generation of non-standard distribution and on streams of random variates of special purposes. It is designed to provide a consistent tool to sample from distributions with various properties. Since there is no universal method that fits for all situations, various methods for sampling are implemented.

UNU.RAN solves this complex task by means of an object oriented programming interface. Three basic objects are used:

• distribution object UNUR_DISTR
  Hold all information about the random variates that should be generated.
• generator object UNUR_GEN
  Hold the generators for the given distributions. Two generator objects are completely independent of each other. They may share a common uniform random number generator or have their owns.
• parameter object UNUR_PAR
  Hold all information for creating a generator object. It is necessary due to various parameters and switches for each of these generation methods.

  Notice that the parameter objects only hold pointers to arrays but do not have their own copy of such an array. Especially, if a dynamically allocated array is used it must not be freed until the generator object has been created!

The idea behind these structures is that creatin distributions, choosing a generation method and draing samples are orthogonal (ie. independent) functions of the library. The parameter object is only introduced due to the necessity to deal with various parameters and switches for each of these generation methods which are required to adjust the algorithms to unusual distributions with extreme properties but have default values that are suitable for most applications. These parameters and the data for distributions are set by various functions.

Once a generator object has been created sampling (from the univariate continuous distribution) can be done by the following command:

double x = unur_sample_cont(generator);

Analogous commands exist for discrete and multivariate distributions. For detailed examples that can be copied and modified see Examples.

Distribution objects

All information about a distribution are stored in objects (structures) of type UNUR_DISTR. UNU.RAN has five different types of distribution objects:

cont

Continuous univariate distributions.

cvec

Continuous multivariate distributions.

discr

Discrete univariate distributions.

cemp

Continuous empirical univariate distribution, ie. given by a sample.

cvemp

Continuous empirical multivariate distribution, ie. given by a sample.

matr

Matrix distributions.

Distribution objects can be created from scratch by the following call

distr = unur_distr_<type>_new();

where <type> is one of the five possible types from the above table. Notice that these commands only create an empty object which still must be filled by means of calls for each type of distribution object (see Handling distribution objects). The naming scheme of these functions is designed to indicate the corresponding type of the distribution object and the task to be performed. It is demonstated on the following example.

unur_distr_cont_set_pdf(distr, mypdf);

This command stores a PDF named mypdf in the distribution object distr which must have the type cont.

Of course UNU.RAN provides an easier way to use standard distributions. Instead of using unur_distr_<type>_new calls and fuctions unur_distr_<type>_set_<…> for setting data, objects for standard distribution can be created by a single call. Eg. to get an object for the normal distribution with mean 2 and standard deviation 5 use

double parameter[2] = {2.0 ,5.0};
UNUR_DISTR *distr = unur_distr_normal(parameter, 2);

For a list of standard distributions see Standard distributions.

Generation methods

The information that a distribution object must contain depends heavily on the chosen generation method choosen.

Brackets indicate optional information while a tilde indicates that only an approximation must be provided. See Glossary, for unfamiliar terms.

Because of tremendous variety of possible problems, UNU.RAN provides many methods. All information for creating a generator object has to be collected in a parameter object first. For example, if the task is to sample from a continuous distribution the method AROU might be a good choice. Then the call

UNUR_PAR *par = unur_arou_new(distribution);

creates an parameter object par with a pointer to the distribution object and default values for all necessary parameters for method AROU. Other methods can be used by replacing arou with the name of the desired methods (in lower case letters):

UNUR_PAR *par = unur_<method>_new(distribution);

This sets the default values for all necessary parameters for the chosen method. These are suitable for almost all applications. Nevertheless, it is possible to control the behavior of the method using corresponding set calls for each method. This might be necessary to adjust the algorithm for an unusual distribution with extreme properties, or just for fine tuning the perforence of the algorithm. The following example demonstrates how to change the maximum number of iterations for method NINV to the value 50:

unur_ninv_set_max_iteration(par, 50);

All available methods are described in details in Methods for generating non-uniform random variates.

Creating a generator object

Now it is possible to create a generator object:

UNUR_GEN *generator = unur_init(par);
if (generator == NULL) exit(EXIT_FAILURE);

Important: You must always check whether unur_init has been executed successfully. Otherwise the NULL pointer is returned which causes a segmentation fault when used for sampling.

Important: The call of unur_init destroys the parameter object!
Moreover, it is recommended to call unur_init immediately after the parameter object par has created and modified.

An existing generator object is a rather static construct. Nevertheless, some of the parameters can still be modified by chg calls, e.g.

unur_ninv_chg_max_iteration(gen, 30);

Notice that it is important when parameters are changed because different functions must be used:

The function name includes the term set and the first argument must be of type UNUR_PAR when the parameters are changed before the generator object is created.

The function name includes the term chg and the first argument must be of type UNUR_GEN when the parameters are changed for an existing generator object.

For details see Methods for generating non-uniform random variates.

Sampling

You can now use your generator object in any place of your program to sample from your distribution. You only have to take care about the type of variates it computes: double, int or a vector (array of doubles). Notice that at this point it does not matter whether you are sampling from a gamma distribution, a truncated normal distribution or even an empirical distribution.

Reinitializing

It is possible for a generator object to change the parameters and the domain of the underlying distribution. This must be done by extracting this object by means of a unur_get_distr call and changing the distribution using the correspondig set calls, see Handling distribution objects. The generator object must then be reinitialized by means of the unur_reinit call.

Important: Currently not all methods allow reinitialization, see the description of the particular method (keyword Reinit).

Destroy

When you do not need your generator object any more, you should destroy it:

unur_free(generator);

Uniform random numbers

Each generator object can have its own uniform random number generator or share one with others. When created a parameter object the pointer for the uniform random number generator is set to the default generator. However, it can be changed at any time to any other generator:

unur_set_urng(par, urng);

or

unur_chg_urng(generator, urng);

respectively. See Using uniform random number generators, for details.

1.5 Contact the authors

If you have any problems with UNU.RAN, suggestions how to improve the library, or find a bug, please contact us via email unuran@statmath.wu.ac.at.

For news please visit out homepage at http://statmath.wu.ac.at/unuran/.

2.1 As short as possible

Select a distribution and let UNU.RAN do all necessary steps.

/* ------------------------------------------------------------- */
/* File: example0.c                                              */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Declare the three UNURAN objects.                           */
  UNUR_DISTR *distr;    /* distribution object                   */
  UNUR_PAR   *par;      /* parameter object                      */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Use a predefined standard distribution:                     */
  /*   Gaussian with mean zero and standard deviation 1.         */
  /*   Since this is the standard form of the distribution,      */
  /*   we need not give these parameters.                        */
  distr = unur_distr_normal(NULL, 0);

  /* Use method AUTO:                                            */
  /*   Let UNURAN select a suitable method for you.              */
  par = unur_auto_new(distr);

  /* Now you can change some of the default settings for the     */
  /* parameters of the chosen method. We don't do it here.       */

  /* Create the generator object.                                */
  gen = unur_init(par);

  /* Notice that this call has also destroyed the parameter      */
  /* object `par' as a side effect.                              */

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* It is possible to reuse the distribution object to create   */
  /* another generator object. If you do not need it any more,   */
  /* it should be destroyed to free memory.                      */
  unur_distr_free(distr);

  /* Now you can use the generator object `gen' to sample from   */
  /* the standard Gaussian distribution.                         */
  /* Eg.:                                                        */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.2 As short as possible (String API)

Select a distribution and let UNU.RAN do all necessary steps.

/* ------------------------------------------------------------- */
/* File: example0_str.c                                          */
/* ------------------------------------------------------------- */
/* String API.                                                   */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Declare UNURAN generator object.                            */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Create the generator object.                                */
  /* Use a predefined standard distribution:                     */
  /*   Standard Gaussian distribution.                           */
  /* Use method AUTO:                                            */
  /*   Let UNURAN select a suitable method for you.              */
  gen = unur_str2gen("normal()");         

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* Now you can use the generator object `gen' to sample from   */
  /* the standard Gaussian distribution.                         */
  /* Eg.:                                                        */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.3 Select a method

Select method AROU and use it with default parameters.

/* ------------------------------------------------------------- */
/* File: example1.c                                              */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Declare the three UNURAN objects.                           */
  UNUR_DISTR *distr;    /* distribution object                   */
  UNUR_PAR   *par;      /* parameter object                      */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Use a predefined standard distribution:                     */
  /*   Gaussian with mean zero and standard deviation 1.         */
  /*   Since this is the standard form of the distribution,      */
  /*   we need not give these parameters.                        */
  distr = unur_distr_normal(NULL, 0);

  /* Choose a method: AROU.                                      */
  /* For other (suitable) methods replace "arou" with the        */
  /* respective name (in lower case letters).                    */
  par = unur_arou_new(distr);

  /* Now you can change some of the default settings for the     */
  /* parameters of the chosen method. We don't do it here.       */

  /* Create the generator object.                                */
  gen = unur_init(par);

  /* Notice that this call has also destroyed the parameter      */
  /* object `par' as a side effect.                              */

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* It is possible to reuse the distribution object to create   */
  /* another generator object. If you do not need it any more,   */
  /* it should be destroyed to free memory.                      */
  unur_distr_free(distr);

  /* Now you can use the generator object `gen' to sample from   */
  /* the standard Gaussian distribution.                         */
  /* Eg.:                                                        */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.4 Select a method (String API)

Select method AROU and use it with default parameters.

/* ------------------------------------------------------------- */
/* File: example1_str.c                                          */
/* ------------------------------------------------------------- */
/* String API.                                                   */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Declare UNURAN generator object.                            */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Create the generator object.                                */
  /* Use a predefined standard distribution:                     */
  /*   Standard Gaussian distribution.                           */
  /* Choose a method: AROU.                                      */
  /*   For other (suitable) methods replace "arou" with the      */
  /*   respective name.                                          */
  gen = unur_str2gen("normal() & method=arou");         

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* Now you can use the generator object `gen' to sample from   */
  /* the standard Gaussian distribution.                         */
  /* Eg.:                                                        */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.5 Arbitrary distributions

If you want to sample from a non-standard distribution, UNU.RAN might be exactly what you need. Depending on the information is available, a method must be choosen for sampling, see Concepts of UNU.RAN for an overview and Methods for generating non-uniform random variates for details.

/* ------------------------------------------------------------- */
/* File: example2.c                                              */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

/* In this example we build a distribution object from scratch   */
/* and sample from this distribution.                            */
/*                                                               */
/* We use method TDR (Transformed Density Rejection) which       */
/* required a PDF and the derivative of the PDF.                 */

/* ------------------------------------------------------------- */

/* Define the PDF and dPDF of our distribution.                  */
/*                                                               */
/* Our distribution has the PDF                                  */
/*                                                               */
/*          /  1 - x*x  if |x| <= 1                              */
/*  f(x) = <                                                     */
/*          \  0        otherwise                                */
/*                                                               */

/* The PDF of our distribution:                                  */
double mypdf( double x, const UNUR_DISTR *distr )
     /* The second argument (`distr') can be used for parameters */
     /* for the PDF. (We do not use parameters in our example.)  */
{
  if (fabs(x) >= 1.)
    return 0.;
  else
    return (1.-x*x);
} /* end of mypdf() */

/* The derivative of the PDF of our distribution:                */
double mydpdf( double x, const UNUR_DISTR *distr )
{
  if (fabs(x) >= 1.)
    return 0.;
  else
    return (-2.*x);
} /* end of mydpdf() */

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Declare the three UNURAN objects.                           */
  UNUR_DISTR *distr;    /* distribution object                   */
  UNUR_PAR   *par;      /* parameter object                      */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Create a new distribution object from scratch.              */
  /* It is a continuous distribution, and we need a PDF and the  */
  /* derivative of the PDF. Moreover we set the domain.          */

  /* Get empty distribution object for a continuous distribution */
  distr = unur_distr_cont_new();

  /* Assign the PDF and dPDF (defined above).                    */
  unur_distr_cont_set_pdf( distr, mypdf );
  unur_distr_cont_set_dpdf( distr, mydpdf );

  /* Set the domain of the distribution (optional for TDR).      */
  unur_distr_cont_set_domain( distr, -1., 1. );

  /* Choose a method: TDR.                                       */
  par = unur_tdr_new(distr);

  /* Now you can change some of the default settings for the     */
  /* parameters of the chosen method. We don't do it here.       */

  /* Create the generator object.                                */
  gen = unur_init(par);

  /* Notice that this call has also destroyed the parameter      */
  /* object `par' as a side effect.                              */

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* It is possible to reuse the distribution object to create   */
  /* another generator object. If you do not need it any more,   */
  /* it should be destroyed to free memory.                      */
  unur_distr_free(distr);

  /* Now you can use the generator object `gen' to sample from   */
  /* the distribution. Eg.:                                      */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.6 Arbitrary distributions (String API)

If you want to sample from a non-standard distribution, UNU.RAN might be exactly what you need. Depending on the information is available, a method must be choosen for sampling, see Concepts of UNU.RAN for an overview and Methods for generating non-uniform random variates for details.

/* ------------------------------------------------------------- */
/* File: example2_str.c                                          */
/* ------------------------------------------------------------- */
/* String API.                                                   */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

/* In this example we use a generic distribution object          */
/* and sample from this distribution.                            */
/*                                                               */
/* The PDF of our distribution is given by                       */
/*                                                               */
/*          /  1 - x*x  if |x| <= 1                              */
/*  f(x) = <                                                     */
/*          \  0        otherwise                                */
/*                                                               */
/* We use method TDR (Transformed Density Rejection) which       */
/* required a PDF and the derivative of the PDF.                 */

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Declare UNURAN generator object.                            */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Create the generator object.                                */
  /* Use a generic continuous distribution.                      */
  /* Choose a method: TDR.                                       */
  gen = unur_str2gen(
        "distr = cont; pdf=\"1-x*x\"; domain=(-1,1) & method=tdr");

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* Now you can use the generator object `gen' to sample from   */
  /* the distribution. Eg.:                                      */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.7 Change parameters of the method

Each method for generating random numbers allows several parameters to be modified. If you do not want to use default values, it is possible to change them. The following example illustrates how to change parameters. For details see Methods for generating non-uniform random variates.

/* ------------------------------------------------------------- */
/* File: example3.c                                              */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;          /* loop variable                            */
  double x;          /* will hold the random number              */

  double fparams[2]; /* array for parameters for distribution    */

  /* Declare the three UNURAN objects.                           */
  UNUR_DISTR *distr;    /* distribution object                   */
  UNUR_PAR   *par;      /* parameter object                      */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Use a predefined standard distribution:                     */
  /*   Gaussian with mean 2. and standard deviation 0.5.         */
  fparams[0] = 2.;
  fparams[1] = 0.5;
  distr = unur_distr_normal( fparams, 2 );

  /* Choose a method: TDR.                                       */
  par = unur_tdr_new(distr);

  /* Change some of the default parameters.                      */

  /* We want to use T(x)=log(x) for the transformation.          */
  unur_tdr_set_c( par, 0. );

  /* We want to have the variant with immediate acceptance.      */
  unur_tdr_set_variant_ia( par );

  /* We want to use 10 construction points for the setup         */
  unur_tdr_set_cpoints ( par, 10, NULL );

  /* Create the generator object.                                */
  gen = unur_init(par);

  /* Notice that this call has also destroyed the parameter      */
  /* object `par' as a side effect.                              */

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* It is possible to reuse the distribution object to create   */
  /* another generator object. If you do not need it any more,   */
  /* it should be destroyed to free memory.                      */
  unur_distr_free(distr);

  /* Now you can use the generator object `gen' to sample from   */
  /* the distribution. Eg.:                                      */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* It is possible with method TDR to truncate the distribution */
  /* for an existing generator object ...                        */
  unur_tdr_chg_truncated( gen, -1., 0. );

  /* ... and sample again.                                       */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.8 Change parameters of the method (String API)

Each method for generating random numbers allows several parameters to be modified. If you do not want to use default values, it is possible to change them. The following example illustrates how to change parameters. For details see Methods for generating non-uniform random variates.

/* ------------------------------------------------------------- */
/* File: example3_str.c                                              */
/* ------------------------------------------------------------- */
/* String API.                                                   */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;          /* loop variable                            */
  double x;          /* will hold the random number              */

  /* Declare UNURAN generator object.                            */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Create the generator object.                                */
  /* Use a predefined standard distribution:                     */
  /*   Gaussian with mean 2. and standard deviation 0.5.         */
  /* Choose a method: TDR with parameters                        */
  /*   c = 0: use T(x)=log(x) for the transformation;            */
  /*   variant "immediate acceptance";                           */
  /*   number of construction points = 10.                       */
  gen = unur_str2gen(
       "normal(2,0.5) & method=tdr; c=0.; variant_ia; cpoints=10");         

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* Now you can use the generator object `gen' to sample from   */
  /* the distribution. Eg.:                                      */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* It is possible with method TDR to truncate the distribution */
  /* for an existing generator object ...                        */
  unur_tdr_chg_truncated( gen, -1., 0. );

  /* ... and sample again.                                       */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.9 Change uniform random generator

All generator object use the same default uniform random number generator by default. This can be changed to any generator of your choice such that each generator object has its own random number generator or can share it with some other objects. It is also possible to change the default generator at any time. See Using uniform random number generators, for details.

The following example shows how the uniform random number generator can be set or changed for a generator object. It requires the RNGSTREAMS library to be installed and used. Otherwise the example must be modified accordingly.

/* ------------------------------------------------------------- */
/* File: example_rngstreams.c                                    */
/* ------------------------------------------------------------- */
#ifdef UNURAN_SUPPORTS_RNGSTREAM
/* ------------------------------------------------------------- */
/* This example makes use of the RNGSTREAM library for           */
/* for generating uniform random numbers.                        */
/* (see http://statmath.wu.ac.at/software/RngStreams/)           */
/* To compile this example you must have set                     */
/*   ./configure --with-urng-rngstream                           */
/* (Of course the executable has to be linked against the        */
/* RNGSTREAM library.)                                           */
/* ------------------------------------------------------------- */

/* Include UNURAN header files.                                  */
#include <unuran.h>
#include <unuran_urng_rngstreams.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;          /* loop variable                            */
  double x;          /* will hold the random number              */
  double fparams[2]; /* array for parameters for distribution    */

  /* Declare the three UNURAN objects.                           */
  UNUR_DISTR *distr;    /* distribution object                   */
  UNUR_PAR   *par;      /* parameter object                      */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Declare objects for uniform random number generators.       */
  UNUR_URNG  *urng1, *urng2;    /* uniform generator objects     */

  /* The RNGSTREAMS library sets a package seed.                 */
  unsigned long seed[] = {111u, 222u, 333u, 444u, 555u, 666u};
  RngStream_SetPackageSeed(seed);

  /* RngStreams only:                                            */
  /* Make a object for uniform random number generator.          */
  /* For details see                                             */
  /* http://statmath.wu.ac.at/software/RngStreams/               */
  urng1 = unur_urng_rngstream_new("urng-1");
  if (urng1 == NULL) exit (EXIT_FAILURE);

  /* Use a predefined standard distribution:                     */
  /*   Beta with parameters 2 and 3.                             */
  fparams[0] = 2.;
  fparams[1] = 3.;
  distr = unur_distr_beta( fparams, 2 );

  /* Choose a method: TDR.                                       */
  par = unur_tdr_new(distr);

  /* Set uniform generator in parameter object                   */
  unur_set_urng( par, urng1 );

  /* Create the generator object.                                */
  gen = unur_init(par);

  /* Notice that this call has also destroyed the parameter      */
  /* object `par' as a side effect.                              */

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* It is possible to reuse the distribution object to create   */
  /* another generator object. If you do not need it any more,   */
  /* it should be destroyed to free memory.                      */
  unur_distr_free(distr);

  /* Now you can use the generator object `gen' to sample from   */
  /* the distribution. Eg.:                                      */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* Now we want to switch to a different (independent) stream   */
  /* of uniform random numbers.                                  */
  urng2 = unur_urng_rngstream_new("urng-2");
  if (urng2 == NULL) exit (EXIT_FAILURE);
  unur_chg_urng( gen, urng2 );

  /* ... and sample again.                                       */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  /* We also should destroy the uniform random number generators.*/
  unur_urng_free(urng1);
  unur_urng_free(urng2);

  exit (EXIT_SUCCESS);
} /* end of main() */

/* ------------------------------------------------------------- */
#else
#include <stdio.h>
#include <stdlib.h>
int main(void) {
  printf("You must enable the RNGSTREAM library to run this example!\n\n");
  exit (77);    /* exit code for automake check routines */
}
#endif
/* ------------------------------------------------------------- */

2.10 Change parameters of underlying distribution

One a generator object has been created it allows to draw samples from the distribution with the given parameters. However, some methods allow to change the parameters of the underlying distribution and reinitialize the generator object again. Thus when the parameters of the distribution vary for each draw we save overhead for destroying the old object and creating a new one.

The following example shows how the parameters of a GIG distribution can be changed when method CSTD is used.

/* ------------------------------------------------------------- */
/* File: example_reinit.c                                        */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

/* In this example we show how the parameters of the underlying  */
/* distribution can be changed for an existing generator object. */

/* We use the GIG distribution with method CSTD.                 */

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Parameters of distribution.                                 */ 
  double dparam[3] = {0.5, 1., 5.};

  /* Declare the three UNURAN objects.                           */
  UNUR_DISTR *distr;    /* distribution object                   */
  UNUR_PAR   *par;      /* parameter object                      */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Create initial GIG distribution object                      */
  distr = unur_distr_gig(dparam, 3);

  /* Choose a method: CSTD.                                      */
  par = unur_cstd_new(distr);

  /* Create the generator object.                                */
  gen = unur_init(par);

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* It is possible to reuse the distribution object to create   */
  /* another generator object. If you do not need it any more,   */
  /* it should be destroyed to free memory.                      */
  unur_distr_free(distr);
  
  /* Now you can use the generator object `gen' to sample from   */
  /* the distribution. Eg.:                                      */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* It is possible for method CSTD to change the parameters of  */
  /* underlying distribution. However, we have to extract to     */
  /* pointer to the distribution. Be carefull with this pointer! */
  distr = unur_get_distr(gen);

  /* Change the parameter(s).                                    */
  dparam[2] = 0.001;
  unur_distr_cont_set_pdfparams(distr,dparam,3);

  /* Do not forget to reinitialize the generator object.         */
  /* Check the return code.                                      */
  /* (and try to find a better error handling)                   */
  if (unur_reinit(gen) != UNUR_SUCCESS) {
    fprintf(stderr, "ERROR: cannot reinitialize generator object\n");
    exit (EXIT_FAILURE);
  }

  /* Draw a new sample.                                          */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* Changing parameters can be repeated.                        */
  dparam[2] = 1000;
  unur_distr_cont_set_pdfparams(distr,dparam,3);
  if (unur_reinit(gen) != UNUR_SUCCESS) {
    fprintf(stderr, "ERROR: cannot reinitialize generator object\n");
    exit (EXIT_FAILURE);
  }
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

2.11 Sample pairs of antithetic random variates

Using Method TDR it is easy to sample pairs of antithetic random variates.

/* ------------------------------------------------------------- */
/* File: example_anti.c                                          */
/* ------------------------------------------------------------- */
#ifdef UNURAN_SUPPORTS_PRNG
/* ------------------------------------------------------------- */
/* This example makes use of the PRNG library for generating     */
/* uniform random numbers.                                       */
/* (see http://statmath.wu.ac.at/prng/)                          */
/* To compile this example you must have set                     */
/*   ./configure --with-urng-prng                                */
/* (Of course the executable has to be linked against the        */
/* PRNG library.)                                                */
/* ------------------------------------------------------------- */

/* Example how to sample from two streams of antithetic random   */
/* variates from Gaussian N(2,5) and Gamma(4) distribution, resp.*/

/* ------------------------------------------------------------- */

/* Include UNURAN header files.                                  */
#include <unuran.h>
#include <unuran_urng_prng.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;          /* loop variable                            */
  double xn, xg;     /* will hold the random number              */
  double fparams[2]; /* array for parameters for distribution    */

  /* Declare the three UNURAN objects.                           */
  UNUR_DISTR *distr;    /* distribution object                   */
  UNUR_PAR   *par;      /* parameter object                      */
  UNUR_GEN   *gen_normal, *gen_gamma;
                        /* generator objects                     */

  /* Declare objects for uniform random number generators.       */
  UNUR_URNG  *urng1, *urng2;    /* uniform generator objects     */

  /* PRNG only:                                                  */
  /* Make a object for uniform random number generator.          */
  /* For details see http://statmath.wu.ac.at/prng/.             */


  /* The first generator: Gaussian N(2,5) */

  /* uniform generator: We use the Mersenne Twister.             */
  urng1 = unur_urng_prng_new("mt19937(1237)");
  if (urng1 == NULL) exit (EXIT_FAILURE);

  /* UNURAN generator object for N(2,5) */
  fparams[0] = 2.;
  fparams[1] = 5.;
  distr = unur_distr_normal( fparams, 2 );

  /* Choose method TDR with variant PS.                          */
  par = unur_tdr_new( distr );
  unur_tdr_set_variant_ps( par );

  /* Set uniform generator in parameter object.                  */
  unur_set_urng( par, urng1 );

  /* Set auxilliary uniform random number generator.             */
  /* We use the default generator.                               */
  unur_use_urng_aux_default( par );

  /* Alternatively you can create and use your own auxilliary    */
  /* uniform random number generator:                            */
  /*    UNUR_URNG  *urng_aux;                                    */
  /*    urng_aux = unur_urng_prng_new("tt800");                  */
  /*    if (urng_aux == NULL) exit (EXIT_FAILURE);               */
  /*    unur_set_urng_aux( par, urng_aux );                      */                    

  /* Create the generator object.                                */
  gen_normal = unur_init(par);
  if (gen_normal == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* Destroy distribution object (gen_normal has its own copy).  */
  unur_distr_free(distr);


  /* The second generator: Gamma(4) with antithetic variates.    */

  /* uniform generator: We use the Mersenne Twister.             */
  urng2 = unur_urng_prng_new("anti(mt19937(1237))");
  if (urng2 == NULL) exit (EXIT_FAILURE);

  /* UNURAN generator object for gamma(4) */
  fparams[0] = 4.;
  distr = unur_distr_gamma( fparams, 1 );

  /* Choose method TDR with variant PS.                          */
  par = unur_tdr_new( distr );
  unur_tdr_set_variant_ps( par );

  /* Set uniform generator in parameter object.                  */
  unur_set_urng( par, urng2 );

  /* Set auxilliary uniform random number generator.             */
  /* We use the default generator.                               */
  unur_use_urng_aux_default( par );

  /* Alternatively you can create and use your own auxilliary    */
  /* uniform random number generator (see above).                */
  /* Notice that both generator objects gen_normal and           */
  /* gen_gamma can share the same auxilliary URNG.               */

  /* Create the generator object.                                */
  gen_gamma = unur_init(par);
  if (gen_gamma == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* Destroy distribution object (gen_normal has its own copy).  */
  unur_distr_free(distr);


  /* Now we can sample pairs of negatively correlated random     */
  /* variates. E.g.:                                             */
  for (i=0; i<10; i++) {
    xn = unur_sample_cont(gen_normal);
    xg = unur_sample_cont(gen_gamma);
    printf("%g, %g\n",xn,xg);
  }


  /* When you do not need the generator objects any more, you    */
  /* can destroy it.                                             */
  unur_free(gen_normal);
  unur_free(gen_gamma);

  /* We also should destroy the uniform random number generators.*/
  unur_urng_free(urng1);
  unur_urng_free(urng2);

  exit (EXIT_SUCCESS);
} /* end of main() */

/* ------------------------------------------------------------- */
#else
#include <stdio.h>
#include <stdlib.h>
int main(void) {
  printf("You must enable the PRNG library to run this example!\n\n");
  exit (77);    /* exit code for automake check routines */
}
#endif
/* ------------------------------------------------------------- */

2.12 Sample pairs of antithetic random variates (String API)

Using Method TDR it is easy to sample pairs of antithetic random variates.

/* ------------------------------------------------------------- */
/* File: example_anti_str.c                                      */
/* ------------------------------------------------------------- */
/* String API.                                                   */
/* ------------------------------------------------------------- */
#ifdef UNURAN_SUPPORTS_PRNG
/* ------------------------------------------------------------- */
/* This example makes use of the PRNG library for generating     */
/* uniform random numbers.                                       */
/* (see http://statmath.wu.ac.at/prng/)                          */
/* To compile this example you must have set                     */
/*   ./configure --with-urng-prng                                */
/* (Of course the executable has to be linked against the        */
/* PRNG library.)                                                */
/* ------------------------------------------------------------- */

/* Example how to sample from two streams of antithetic random   */
/* variates from Gaussian N(2,5) and Gamma(4) distribution, resp.*/

/* ------------------------------------------------------------- */

/* Include UNURAN header files.                                  */
#include <unuran.h>
#include <unuran_urng_prng.h>

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;          /* loop variable                            */
  double xn, xg;     /* will hold the random number              */

  /* Declare UNURAN generator objects.                           */
  UNUR_GEN   *gen_normal, *gen_gamma;

  /* PRNG only:                                                  */
  /* Make a object for uniform random number generator.          */
  /* For details see http://statmath.wu.ac.at/prng/.             */

  /* Create the first generator: Gaussian N(2,5)                 */
  gen_normal = unur_str2gen("normal(2,5) & method=tdr; variant_ps & urng=mt19937(1237)");
  if (gen_normal == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }
  /* Set auxilliary uniform random number generator.             */
  /* We use the default generator.                               */
  unur_chgto_urng_aux_default(gen_normal);

  /* The second generator: Gamma(4) with antithetic variates.    */
  gen_gamma = unur_str2gen("gamma(4) & method=tdr; variant_ps & urng=anti(mt19937(1237))");
  if (gen_gamma == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }
  unur_chgto_urng_aux_default(gen_gamma);


  /* Now we can sample pairs of negatively correlated random     */
  /* variates. E.g.:                                             */
  for (i=0; i<10; i++) {
    xn = unur_sample_cont(gen_normal);
    xg = unur_sample_cont(gen_gamma);
    printf("%g, %g\n",xn,xg);
  }


  /* When you do not need the generator objects any more, you    */
  /* can destroy it.                                             */

  /* But first we have to destroy the uniform random number      */
  /* generators.                                                 */
  unur_urng_free(unur_get_urng(gen_normal));
  unur_urng_free(unur_get_urng(gen_gamma));

  unur_free(gen_normal);
  unur_free(gen_gamma);


  exit (EXIT_SUCCESS);
} /* end of main() */

/* ------------------------------------------------------------- */
#else
#include <stdio.h>
#include <stdlib.h>
int main(void) {
  printf("You must enable the PRNG library to run this example!\n\n");
  exit (77);    /* exit code for automake check routines */
}
#endif
/* ------------------------------------------------------------- */

2.13 More examples

See Methods for continuous univariate distributions.

See Methods for continuous empirical univariate distributions.

See Methods for continuous empirical multivariate distributions.

See Methods for discrete univariate distributions.

3.1 Syntax of String Interface

The given string holds information about the requested distribution and (optional) about the sampling method and the uniform random number generator invoked. The interpretation of the string is not case-sensitive, all white spaces are ignored.

The string consists of up to three blocks, separated by ampersands &.

Each block consists of <key>=<value> pairs, separated by semicolons ;.

The first key in each block is used to indicate each block. We have three different blocks with the following (first) keys:

distr

definition of the distribution (see Distribution String).

method

description of the transformation method (see Method String).

urng

uniform random number generation (see Uniform RNG String).

The distr block must be the very first block and is obligatory. All the other blocks are optional and can be arranged in arbitrary order.

For details see the following description of each block.

In the following example

distr = normal(3.,0.75); domain = (0,inf) & method = tdr; c = 0

we have a distribution block for the truncated normal distribution with mean 3 and standard deviation 0.75 on domain (0,infinity); and block for choosing method TDR with parameter c set to 0.

The <key>=<value> pairs that follow the first (initial) pair in each block are used to set parameters. The name of the parameter is given by the <key> string. It is deduced from the UNU.RAN set calls by taking the part after …_set_. The <value> string holds the parameters to be set, separated by commata ,. There are three types of parameters:

string "…" or '…'

i.e. any sequence of characters enclosed by double quotes "…" or single quotes '…' (there is no distinction between double quotes " and single quotes ').

list (…,…)

i.e. list of numbers, separated by commata ,, enclosed in parenthesis (...).

number

a sequence of characters that is not enclosed by double quotes "…", single quotes '…', or parenthesis (...). It is interpreted as float or integer depending on the type of the corresponding parameter.

The <value> string (including the character =) can be omitted when no argument is required.

At the moment not all set calls are supported. The syntax for the <value> can be directly derived from the corresponding set calls. To simplify the syntax additional shortcuts are possible. The following table lists the parameters for the set calls that are supported by the string interface; the entry in parenthesis gives the type of the argument as <value> string:

int (number):

The number is interpreted as an integer. true and on are transformed to 1, false and off are transformed to 0. A missing argument is interpreted as 1.

int, int (number, number or list):

The two numbers or the first two entries in the list are interpreted as a integers. inf and -inf are transformed to INT_MAX and INT_MIN respectively, i.e. the largest and smallest integers that can be represented by the computer.

unsigned (number):

The number is interpreted as an unsigned hexadecimal integer.

double (number):

The number is interpreted as a floating point number. inf is transformed to UNUR_INFINITY.

double, double (number, number or list):

The two numbers or the first two entries in the list are interpreted as a floating point numbers. inf is transformed to UNUR_INFINITY. However using inf in the list might not work for all versions of C. Then it is recommended to use two single numbers instead of a list.

int, double* ([number,] list or number):

• The list is interpreted as a double array. The (first) number as its length. If it is less than the actual size of the array only the first entries of the array are used.
• If only the list is given (i.e., if the first number is omitted), the first number is set to the actual size of the array.
• If only the number is given (i.e., if the list is omitted), the NULL pointer is used instead an array as argument.

double*, int (list [,number]):

The list is interpreted as a double array. The (second) number as its length. If the length is omitted, it is replaced by the actual size of the array. (Only in the distribution block!)

char* (string):

The character string is passed as is to the corresponding set call.

Notice that missing entries in a list of numbers are interpreted as 0. E.g, a the list (1,,3) is read as (1,0,3), the list (1,2,) as (1,2,0).

The the list of key strings in Keys for Distribution String, and Keys for Method String, for further details.

3.2 Distribution String

The distr block must be the very first block and is obligatory. For that reason the keyword distr is optional and can be omitted (together with the = character). Moreover it is ignored while parsing the string. However, to avoid some possible confusion it has to start with the letter d (if it is given at all).

The value of the distr key is used to get the distribution object, either via a unur_distr_<value> call for a standard distribution via a unur_distr_<value>_new call to get an object of a generic distribution. However not all generic distributions are supported yet.

The parameters for the standard distribution are given as a list. There must not be any character (other than white space) between the name of the standard distribution and the opening parenthesis ( of this list. E.g., to get a beta distribution, use

distr = beta(2,4)

To get an object for a discrete distribution with probability vector (0.5,0.2,0.3), use

distr = discr; pv = (0.5,0.2,0.3)

It is also possible to set a PDF, PMF, or CDF using a string. E.g., to create a continuous distribution with PDF proportional to exp(-sqrt(2+(x-1)^2) + (x-1)) and domain (0,inf) use

distr = cont; pdf = "exp(-sqrt(2+(x-1)^2) + (x-1))"

Notice: If this string is used in an unur_str2distr or unur_str2gen call the double quotes " must be protected by \". Alternatively, single quotes may be used instead

distr = cont; pdf = 'exp(-sqrt(2+(x-1)^2) + (x-1))'

For the details of function strings see Function String.

• Keys for Distribution String

3.3 Function String

In unuran it is also possible to define functions (e.g. CDF or PDF) as strings. As you can see in Example 2 (Arbitrary distributions (String API)) it is very easy to define the PDF of a distribution object by means of a string. The possibilities using this string interface are more restricted than using a pointer to a routine coded in C (Arbitrary distributions). But the differences in evaluation time is small. When a distribution object is defined using this string interface then of course the same conditions on the given density or CDF must be satisfied for a chosen method as for the standard API. This string interface can be used for both within the UNU.RAN string API using the unur_str2gen call, and for calls that define the density or CDF for a particular distribution object as done with (e.g.) the call unur_distr_cont_set_pdfstr. Here is an example for the latter case:

unur_distr_cont_set_pdfstr(distr,"1-x*x");

Syntax

The syntax for the function string is case insensitive, white spaces are ingnored. The expressions are similar to most programming languages and mathematical programs (see also the examples below). It is especially influenced by C. The usual preceedence rules are used (from highest to lowest preceedence: functions, power, multiplication, addition, relation operators). Use parentheses in case of doubt or when these preceedences should be changed.

Relation operators can be used as indicator functions, i.e. the term (x>1) is evaluted as 1 if this relation is satisfied, and as 0 otherwise.

The first unknown symbol (letter or word) is interpreted as the variable of the function. It is recommended to use x. Only one variable can be used.

Important: The symbol e is used twice, for Euler’s constant (= 2.7182…) and as exponent. The multiplication operator * must not be omitted, i.e. 2 x is interpreted as the string 2x (which will result in a syntax error).

List of symbols

Examples

1.231+7.9876*x-1.234e-3*x^2+3.335e-5*x^3
sin(2*pi*x)+x^2
exp(-((x-3)/2.1)^2)

It is also possible to define functions using different terms on separate domains. However, instead of constructs using if … then … else … indicator functions are available.

For example to define the density of triangular distribution with domain (-1,1) and mode 0 use

(x>-1)*(x<0)*(1+x) + (x>=0)*(x<1)*(1-x)

3.4 Method String

The key method is obligatory, it must be the first key and its value is the name of a method suitable for the choosen standard distribution. E.g., if method AROU is chosen, use

method = arou

Of course the all following keys dependend on the method choosen at first. All corresponding set calls of UNU.RAN are available and the key is the string after the unur_<methodname>_set_ part of the command. E.g., UNU.RAN provides the command unur_arou_set_max_sqhratio to set a parameter of method AROU. To call this function via the string-interface, the key max_sqhratio can be used:

max_sqhratio = 0.9

Additionally the keyword debug can be used to set debugging flags (see Debugging, for details).

If this block is omitted, a suitable default method is used. Notice however that the default method may change in future versions of UNU.RAN.

• Keys for Method String

3.5 Uniform RNG String

The value of the urng key is passed to the PRNG interface (see PRNG manual for details). However it only works when using the PRNG library is enabled, see Installation for details. There are no other keys.

IMPORTANT: UNU.RAN creates a new uniform random number generator for the generator object. The pointer to this uniform generator has to be read and saved via a unur_get_urng call in order to clear the memory before the UNU.RAN generator object is destroyed.

If this block is omitted the UNU.RAN default generator is used (which must not be destroyed).

4.1 Functions for all kinds of distribution objects

The calls in this section can be applied to all distribution objects.

• Destroy free an instance of a generator object.
• Ask for the type of a generator object.
• Ask for the dimension of a generator object.
• Deal with the name (identifier string) of a generator object.

Function reference

• unur_distr_free
• unur_distr_set_name
• unur_distr_get_name
• unur_distr_get_dim
• unur_distr_get_type
• unur_distr_is_cont
• unur_distr_is_cvec
• unur_distr_is_cemp
• unur_distr_is_cvemp
• unur_distr_is_discr
• unur_distr_is_matr
• unur_distr_set_extobj
• unur_distr_get_extobj

: void unur_distr_free (UNUR_DISTR* distribution) ¶

Destroy the distribution object.

: int unur_distr_set_name (UNUR_DISTR* distribution, const char* name) ¶

: const char* unur_distr_get_name (const UNUR_DISTR* distribution) ¶

Set and get name of distribution. The name can be an arbitrary character string. It can be used to identify generator objects for the user. It is used by UNU.RAN when printing information of the distribution object into a log files.

: int unur_distr_get_dim (const UNUR_DISTR* distribution) ¶

Get number of components of a random vector (its dimension) the distribution.

For univariate distributions it returns dimension 1.

For matrix distributions it returns the number of components (i.e., number of rows times number of columns). When the respective numbers of rows and columns are needed use unur_distr_matr_get_dim instead.

: unsigned int unur_distr_get_type (const UNUR_DISTR* distribution) ¶

Get type of distribution. Possible types are

UNUR_DISTR_CONT

univariate continuous distribution

UNUR_DISTR_CEMP

empirical continuous univariate distribution (i.e. a sample)

UNUR_DISTR_CVEC

continuous mulitvariate distribution

UNUR_DISTR_CVEMP

empirical continuous multivariate distribution (i.e. a vector sample)

UNUR_DISTR_DISCR

discrete univariate distribution

UNUR_DISTR_MATR

matrix distribution

Alternatively the unur_distr_is_<TYPE> calls can be used.

: int unur_distr_is_cont (const UNUR_DISTR* distribution) ¶

TRUE if distribution is a continuous univariate distribution.

: int unur_distr_is_cvec (const UNUR_DISTR* distribution) ¶

TRUE if distribution is a continuous multivariate distribution.

: int unur_distr_is_cemp (const UNUR_DISTR* distribution) ¶

TRUE if distribution is an empirical continuous univariate distribution, i.e. a sample.

: int unur_distr_is_cvemp (const UNUR_DISTR* distribution) ¶

TRUE if distribution is an empirical continuous multivariate distribution.

: int unur_distr_is_discr (const UNUR_DISTR* distribution) ¶

TRUE if distribution is a discrete univariate distribution.

: int unur_distr_is_matr (const UNUR_DISTR* distribution) ¶

TRUE if distribution is a matrix distribution.

: int unur_distr_set_extobj (UNUR_DISTR* distribution, const void* extobj) ¶

Store a pointer to an external object. This might be usefull if the PDF, PMF, CDF or other functions used to implement a particular distribution a parameter set that cannot be stored as doubles (e.g. pointers to some structure that holds information of the distribution).

Important: When UNU.RAN copies this distribution object into the generator object, then the address extobj that this pointer contains is simply copied. Thus the generator holds an address of a non-private object! Once the generator object has been created any change in the external object might effect the generator object.

Warning: External objects must be used with care. Once the generator object has been created or the distribution object has been copied you must not destroy this external object.

: const void* unur_distr_get_extobj (const UNUR_DISTR* distribution) ¶

Get the pointer to the external object.

Important: Changing this object must be done with with extreme care.

4.2 Continuous univariate distributions

The calls in this section can be applied to continuous univariate distributions.

• Create a new instance of a continuous univariate distribution.
• Handle and evaluate distribution function (CDF, cdf), probability density function (PDF, pdf) and the derivative of the density function (dpdf). The following is important:
  • pdf need not be normalized, i.e., any integrable nonnegative function can be used.
  • dpdf must the derivate of the function provided as pdf.
  • cdf must be a distribution function, i.e. it must be monotonically increasing with range [0,1].
  • If cdf and pdf are used together for a pariticular generation method, then pdf must be the derivate of the cdf, i.e., it must be normalized.
• Handle and evaluate the logarithm of the probability density function (logPDF, logpdf) and the derivative of the logarithm of the density function (dlogpdf).

  Some methods use the logarithm of the density if available.

• Set (and change) parameters (pdfparams) and the area below the graph (pdfarea) of the given density.
• Set the mode (or pole) of the distribution.
• Set the center of the distribution. It is used by some generation methods to adjust the parameters of the generation algorithms to gain better performance. It can be seens as the location of the “central part” of the distribution.
• Some generation methods require the hazard rate (hr) of the distribution instead of its pdf.
• Alternatively, cdf, pdf, dpdf, and hr can be provided as strings instead of function pointers.
• Set the domain of the distribution. Notice that the library also can handle truncated distributions, i.e., distributions that are derived from (standard) distributions by simply restricting its domain to a subset. However, there is a subtle difference between changing the domain of a distribution object by a unur_distr_cont_set_domain call and changing the (truncated) domain for an existing generator object. The domain of the distribution object is used to create the generator object with hats, squeezes, tables, etc. Whereas truncating the domain of an existing generator object need not necessarily require a recomputation of these data. Thus by a unur_<method>_chg_truncated call (if available) the sampling region is restricted to the subset of the domain of the given distribution object. However, generation methods that require a recreation of the generator object when the domain is changed have a unur_<method>_chg_domain call instead. For these calls there are of course no restrictions on the given domain (i.e., it is possible to increase the domain of the distribution) (see Methods for generating non-uniform random variates, for details).

Function reference

• unur_distr_cont_new
• unur_distr_cont_set_pdf
• unur_distr_cont_set_dpdf
• unur_distr_cont_set_cdf
• unur_distr_cont_set_invcdf
• unur_distr_cont_get_pdf
• unur_distr_cont_get_dpdf
• unur_distr_cont_get_cdf
• unur_distr_cont_get_invcdf
• unur_distr_cont_eval_pdf
• unur_distr_cont_eval_dpdf
• unur_distr_cont_eval_cdf
• unur_distr_cont_eval_invcdf
• unur_distr_cont_set_logpdf
• unur_distr_cont_set_dlogpdf
• unur_distr_cont_set_logcdf
• unur_distr_cont_get_logpdf
• unur_distr_cont_get_dlogpdf
• unur_distr_cont_get_logcdf
• unur_distr_cont_eval_logpdf
• unur_distr_cont_eval_dlogpdf
• unur_distr_cont_eval_logcdf
• unur_distr_cont_set_pdfstr
• unur_distr_cont_set_cdfstr
• unur_distr_cont_get_pdfstr
• unur_distr_cont_get_dpdfstr
• unur_distr_cont_get_cdfstr
• unur_distr_cont_set_pdfparams
• unur_distr_cont_get_pdfparams
• unur_distr_cont_set_pdfparams_vec
• unur_distr_cont_get_pdfparams_vec
• unur_distr_cont_set_logpdfstr
• unur_distr_cont_get_logpdfstr
• unur_distr_cont_get_dlogpdfstr
• unur_distr_cont_set_logcdfstr
• unur_distr_cont_get_logcdfstr
• unur_distr_cont_set_domain
• unur_distr_cont_get_domain
• unur_distr_cont_get_truncated
• unur_distr_cont_set_hr
• unur_distr_cont_get_hr
• unur_distr_cont_eval_hr
• unur_distr_cont_set_hrstr
• unur_distr_cont_get_hrstr
• unur_distr_cont_set_mode
• unur_distr_cont_upd_mode
• unur_distr_cont_get_mode
• unur_distr_cont_set_center
• unur_distr_cont_get_center
• unur_distr_cont_set_pdfarea
• unur_distr_cont_upd_pdfarea
• unur_distr_cont_get_pdfarea

: UNUR_DISTR* unur_distr_cont_new (void) ¶

Create a new (empty) object for univariate continuous distribution.

Essential parameters

: int unur_distr_cont_set_pdf (UNUR_DISTR* distribution, UNUR_FUNCT_CONT* pdf) ¶

: int unur_distr_cont_set_dpdf (UNUR_DISTR* distribution, UNUR_FUNCT_CONT* dpdf) ¶

: int unur_distr_cont_set_cdf (UNUR_DISTR* distribution, UNUR_FUNCT_CONT* cdf) ¶

: int unur_distr_cont_set_invcdf (UNUR_DISTR* distribution, UNUR_FUNCT_CONT* invcdf) ¶

Set respective pointer to the probability density function (PDF), the derivative of the probability density function (dPDF), the cumulative distribution function (CDF), and the inverse CDF of the distribution. Each of these function pointers must be of type double funct(double x, const UNUR_DISTR *distr).

Due to the fact that some of the methods do not require a normalized PDF the following is important:

• The given CDF must be the cumulative distribution function of the (non-truncated) distribution. If a distribution from the UNU.RAN library of standard distributions (see Standard distributions) is truncated, there is no need to change the CDF.
• If both the CDF and the PDF are used (for a method or for order statistics), the PDF must be the derivative of the CDF. If a truncated distribution for one of the standard distributions from the UNU.RAN library of standard distributions is used, there is no need to change the PDF.
• If the area below the PDF is required for a given distribution it must be given by the unur_distr_cont_set_pdfarea call. For a truncated distribution this must be of course the integral of the PDF in the given truncated domain. For distributions from the UNU.RAN library of standard distributions this is done automatically by the unur_distr_cont_upd_pdfarea call.

It is important to note that all these functions must return a result for all values of x. Eg., if the domain of a given PDF is the interval [-1,1], then the given function must return 0.0 for all points outside this interval. In case of an overflow the PDF should return UNUR_INFINITY.

It is not possible to change such a function. Once the PDF or CDF is set it cannot be overwritten. This also holds when the logPDF is given or when the PDF is given by the unur_distr_cont_set_pdfstr or unur_distr_cont_set_logpdfstr call. A new distribution object has to be used instead.

: UNUR_FUNCT_CONT* unur_distr_cont_get_pdf (const UNUR_DISTR* distribution) ¶

: UNUR_FUNCT_CONT* unur_distr_cont_get_dpdf (const UNUR_DISTR* distribution) ¶

: UNUR_FUNCT_CONT* unur_distr_cont_get_cdf (const UNUR_DISTR* distribution) ¶

: UNUR_FUNCT_CONT* unur_distr_cont_get_invcdf (const UNUR_DISTR* distribution) ¶

Get the respective pointer to the PDF, the derivative of the PDF, the CDF, and the inverse CDF of the distribution. The pointer is of type double funct(double x, const UNUR_DISTR *distr). If the corresponding function is not available for the distribution, the NULL pointer is returned.

: double unur_distr_cont_eval_pdf (double x, const UNUR_DISTR* distribution) ¶

: double unur_distr_cont_eval_dpdf (double x, const UNUR_DISTR* distribution) ¶

: double unur_distr_cont_eval_cdf (double x, const UNUR_DISTR* distribution) ¶

: double unur_distr_cont_eval_invcdf (double u, const UNUR_DISTR* distribution) ¶

Evaluate the PDF, derivative of the PDF, the CDF, and the inverse CDF at x and u,respectively. Notice that distribution must not be the NULL pointer. If the corresponding function is not available for the distribution, UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_DATA.

IMPORTANT: In the case of a truncated standard distribution these calls always return the respective values of the untruncated distribution!

: int unur_distr_cont_set_logpdf (UNUR_DISTR* distribution, UNUR_FUNCT_CONT* logpdf) ¶

: int unur_distr_cont_set_dlogpdf (UNUR_DISTR* distribution, UNUR_FUNCT_CONT* dlogpdf) ¶

: int unur_distr_cont_set_logcdf (UNUR_DISTR* distribution, UNUR_FUNCT_CONT* logcdf) ¶

: UNUR_FUNCT_CONT* unur_distr_cont_get_logpdf (const UNUR_DISTR* distribution) ¶

: UNUR_FUNCT_CONT* unur_distr_cont_get_dlogpdf (const UNUR_DISTR* distribution) ¶

: UNUR_FUNCT_CONT* unur_distr_cont_get_logcdf (const UNUR_DISTR* distribution) ¶

: double unur_distr_cont_eval_logpdf (double x, const UNUR_DISTR* distribution) ¶

: double unur_distr_cont_eval_dlogpdf (double x, const UNUR_DISTR* distribution) ¶

: double unur_distr_cont_eval_logcdf (double x, const UNUR_DISTR* distribution) ¶

Analogous calls for the logarithm of the density distribution functions.

: int unur_distr_cont_set_pdfstr (UNUR_DISTR* distribution, const char* pdfstr) ¶

This function provides an alternative way to set a PDF and its derivative of the distribution. pdfstr is a character string that contains the formula for the PDF, see Function String, for details. The derivative of the given PDF is computed automatically. See also the remarks for the unur_distr_cont_set_pdf call.

It is not possible to call this funtion twice or to call this function after a unur_distr_cont_set_pdf call.

: int unur_distr_cont_set_cdfstr (UNUR_DISTR* distribution, const char* cdfstr) ¶

This function provides an alternative way to set a CDF; analogously to the unur_distr_cont_set_pdfstr call. The PDF and its derivative of the given CDF are computed automatically.

: char* unur_distr_cont_get_pdfstr (const UNUR_DISTR* distribution) ¶

: char* unur_distr_cont_get_dpdfstr (const UNUR_DISTR* distribution) ¶

: char* unur_distr_cont_get_cdfstr (const UNUR_DISTR* distribution) ¶

Get pointer to respective string for PDF, derivate of PDF, and CDF of distribution that is given as string (instead of a function pointer). This call allocates memory to produce this string. It should be freed when it is not used any more.

: int unur_distr_cont_set_pdfparams (UNUR_DISTR* distribution, const double* params, int n_params) ¶

Sets array of parameters for distribution. There is an upper limit for the number of parameters n_params. It is given by the macro UNUR_DISTR_MAXPARAMS in unuran_config.h. (It is set to 5 by default but can be changed to any appropriate nonnegative number.) If n_params is negative or exceeds this limit no parameters are copied into the distribution object and unur_errno is set to UNUR_ERR_DISTR_NPARAMS.

For standard distributions from the UNU.RAN library the parameters are checked. Moreover, the domain is updated automatically unless it has been changed before by a unur_distr_cont_set_domain call. If the given parameters are invalid for the standard distribution, then no parameters are set and an error code is returned. Notice, that the given parameter list for such a distribution is handled in the same way as in the corresponding new calls, i.e. optional parameters for the PDF that are not present in the given list are (re-)set to their default values.

Important: If the parameters of a distribution from the UNU.RAN library of standard distributions (see Standard distributions) are changed, then neither its mode nor the normalization constant are updated. Please use the respective calls unur_distr_cont_upd_mode and unur_distr_cont_upd_pdfarea. Moreover, if the domain has been changed by a unur_distr_cont_set_domain it is not automatically updated, either. Updating the normalization constant is in particular very important, when the CDF of the distribution is used.

: int unur_distr_cont_get_pdfparams (const UNUR_DISTR* distribution, const double** params) ¶

Get number of parameters of the PDF and set pointer params to array of parameters. If no parameters are stored in the object, an error code is returned and params is set to NULL.

Important: Do not change the entries in params!

: int unur_distr_cont_set_pdfparams_vec (UNUR_DISTR* distribution, int par, const double* param_vec, int n_param_vec) ¶

This function provides an interface for additional vector parameters for a continuous distribution.

It sets the parameter with number par. par indicates directly which of the parameters is set and must be a number between 0 and UNUR_DISTR_MAXPARAMS-1 (the upper limit of possible parameters defined in unuran_config.h; it is set to 5 but can be changed to any appropriate nonnegative number.)

The entries of a this parameter are given by the array param_vec of size n_param_vec.

If param_vec is NULL then the corresponding entry is cleared.

If an error occurs no parameters are copied into the parameter object unur_errno is set to UNUR_ERR_DISTR_DATA.

: int unur_distr_cont_get_pdfparams_vec (const UNUR_DISTR* distribution, int par, const double** param_vecs) ¶

Get parameter of the PDF with number par. The pointer to the parameter array is stored in param_vecs, its size is returned by the function. If the requested parameter is not set, then an error code is returned and params is set to NULL.

Important: Do not change the entries in param_vecs!

: int unur_distr_cont_set_logpdfstr (UNUR_DISTR* distribution, const char* logpdfstr) ¶

: char* unur_distr_cont_get_logpdfstr (const UNUR_DISTR* distribution) ¶

: char* unur_distr_cont_get_dlogpdfstr (const UNUR_DISTR* distribution) ¶

: int unur_distr_cont_set_logcdfstr (UNUR_DISTR* distribution, const char* logcdfstr) ¶

: char* unur_distr_cont_get_logcdfstr (const UNUR_DISTR* distribution) ¶

Analogous calls for the logarithm of the density and distribution functions.

: int unur_distr_cont_set_domain (UNUR_DISTR* distribution, double left, double right) ¶

Set the left and right borders of the domain of the distribution. This can also be used to truncate an existing distribution. For setting the boundary to +/- infinity use +/- UNUR_INFINITY. If right is not strictly greater than left no domain is set and unur_errno is set to UNUR_ERR_DISTR_SET.

Important: For some technical reasons it is assumed that the density is unimodal and thus monotone on either side of the mode! This is used in the case when the given mode is outside of the original domain. Then the mode is set to the corresponding boundary of the new domain. If this result is not the desired it must be changed by using a unur_distr_cont_set_mode call (or a unur_distr_cont_upd_mode call). The same holds for the center of the distribution.

: int unur_distr_cont_get_domain (const UNUR_DISTR* distribution, double* left, double* right) ¶

Get the left and right borders of the domain of the distribution. If the domain is not set +/- UNUR_INFINITY is assumed and returned. No error is reported in this case.

: int unur_distr_cont_get_truncated (const UNUR_DISTR* distribution, double* left, double* right) ¶

Get the left and right borders of the (truncated) domain of the distribution. For non-truncated distribution this call is equivalent to the unur_distr_cont_get_domain call.

This call is only useful in connection with a unur_get_distr call to get the boundaries of the sampling region of a generator object.

: int unur_distr_cont_set_hr (UNUR_DISTR* distribution, UNUR_FUNCT_CONT* hazard) ¶

Set pointer to the hazard rate (HR) of the distribution.

The hazard rate (or failure rate) is a mathematical way of describing aging. If the lifetime X is a random variable with density f(x) and CDF F(x) the hazard rate h(x) is defined as h(x) = f(x) / (1-F(x)). In other words, h(x) represents the (conditional) rate of failure of a unit that has survived up to time x with probability 1-F(x). The key distribution is the exponential distribution as it has constant hazard rate of value 1. Hazard rates tending to infinity describe distributions with sub-exponential tails whereas distributions with hazard rates tending to zero have heavier tails than the exponential distribution.

It is important to note that all these functions must return a result for all floats x. In case of an overflow the PDF should return UNUR_INFINITY.

Important: Do not simply use f(x) / (1-F(x)), since this is numerically very unstable and results in numerical noise if F(x) is (very) close to 1. Moreover, if the density f(x) is known a generation method that uses the density is more appropriate.

It is not possible to change such a function. Once the HR is set it cannot be overwritten. This also holds when the HR is given by the unur_distr_cont_set_hrstr call. A new distribution object has to be used instead.

: UNUR_FUNCT_CONT* unur_distr_cont_get_hr (const UNUR_DISTR* distribution) ¶

Get the pointer to the hazard rate of the distribution. The pointer is of type double funct(double x, const UNUR_DISTR *distr). If the corresponding function is not available for the distribution, the NULL pointer is returned.

: double unur_distr_cont_eval_hr (double x, const UNUR_DISTR* distribution) ¶

Evaluate the hazard rate at x. Notice that distribution must not be the NULL pointer. If the corresponding function is not available for the distribution, UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_DATA.

: int unur_distr_cont_set_hrstr (UNUR_DISTR* distribution, const char* hrstr) ¶

This function provides an alternative way to set a hazard rate and its derivative of the distribution. hrstr is a character string that contains the formula for the HR, see Function String, for details. See also the remarks for the unur_distr_cont_set_hr call.

It is not possible to call this funtion twice or to call this function after a unur_distr_cont_set_hr call.

: char* unur_distr_cont_get_hrstr (const UNUR_DISTR* distribution) ¶

Get pointer to string for HR of distribution that is given via the string interface. This call allocates memory to produce this string. It should be freed when it is not used any more.

Derived parameters

The following paramters must be set whenever one of the essential parameters has been set or changed (and the parameter is required for the chosen method).

: int unur_distr_cont_set_mode (UNUR_DISTR* distribution, double mode) ¶

Set mode of distribution. The mode must be contained in the domain of distribution. Otherwise the mode is not set and unur_errno is set to UNUR_ERR_DISTR_SET. For distributions with unbounded density, this call is used to set the pole of the PDF. Notice that the PDF should then return UNUR_INFINITY at the pole. Notice that the mode is adjusted when the domain is set, see the remark for the unur_distr_cont_set_domain call.

: int unur_distr_cont_upd_mode (UNUR_DISTR* distribution) ¶

Recompute the mode of the distribution. This call works properly for distribution objects from the UNU.RAN library of standard distributions when the corresponding function is available. Otherwise a (slow) numerical mode finder based on Brent’s algorithm is used. If it failes unur_errno is set to UNUR_ERR_DISTR_DATA.

: double unur_distr_cont_get_mode (UNUR_DISTR* distribution) ¶

Get mode of distribution. If the mode is not marked as known, unur_distr_cont_upd_mode is called to compute the mode. If this is not successful UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_GET. (There is no difference between the case where no routine for computing the mode is available and the case where no mode exists for the distribution at all.)

: int unur_distr_cont_set_center (UNUR_DISTR* distribution, double center) ¶

Set center of the distribution. The center is used by some methods to shift the distribution in order to decrease numerical round-off error. If not given explicitly a default is used.

Important: This call does not check whether the center is contained in the given domain.

Default: The mode, if set by a unur_distr_cont_set_mode or unur_distr_cont_upd_mode call; otherwise 0.

: double unur_distr_cont_get_center (const UNUR_DISTR* distribution) ¶

Get center of the distribution. It always returns some point as there always exists a default for the center, see unur_distr_cont_set_center.

: int unur_distr_cont_set_pdfarea (UNUR_DISTR* distribution, double area) ¶

Set the area below the PDF. If area is non-positive, no area is set and unur_errno is set to UNUR_ERR_DISTR_SET.

For a distribution object created by the UNU.RAN library of standard distributions you always should use the unur_distr_cont_upd_pdfarea. Otherwise there might be ambiguous side-effects.

: int unur_distr_cont_upd_pdfarea (UNUR_DISTR* distribution) ¶

Recompute the area below the PDF of the distribution. It only works for distribution objects from the UNU.RAN library of standard distributions when the corresponding function is available. Otherwise unur_errno is set to UNUR_ERR_DISTR_DATA.

This call also sets the normalization constant such that the given PDF is the derivative of a given CDF, i.e. the area is 1. However, for truncated distributions the area is smaller than 1.

The call does not work for distributions from the UNU.RAN library of standard distributions with truncated domain when the CDF is not available.

: double unur_distr_cont_get_pdfarea (UNUR_DISTR* distribution) ¶

Get the area below the PDF of the distribution. If this area is not known,
unur_distr_cont_upd_pdfarea is called to compute it. If this is not successful UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_GET.

4.3 Continuous univariate order statistics

These are special cases of a continuous univariate distributions and thus they have most of these parameters (with the exception that functions cannot be changed). Additionally,

• there is a call to extract the underlying distribution,
• and a call to handle the rank of the order statistics.

Function reference

• unur_distr_corder_new
• unur_distr_corder_get_distribution
• unur_distr_corder_set_rank
• unur_distr_corder_get_rank
• unur_distr_corder_get_pdf
• unur_distr_corder_get_dpdf
• unur_distr_corder_get_cdf
• unur_distr_corder_eval_pdf
• unur_distr_corder_eval_dpdf
• unur_distr_corder_eval_cdf
• unur_distr_corder_set_pdfparams
• unur_distr_corder_get_pdfparams
• unur_distr_corder_set_domain
• unur_distr_corder_get_domain
• unur_distr_corder_get_truncated
• unur_distr_corder_set_mode
• unur_distr_corder_upd_mode
• unur_distr_corder_get_mode
• unur_distr_corder_set_pdfarea
• unur_distr_corder_upd_pdfarea
• unur_distr_corder_get_pdfarea

: UNUR_DISTR* unur_distr_corder_new (const UNUR_DISTR* distribution, int n, int k) ¶

Create an object for order statistics of sample size n and rank k. distribution must be a pointer to a univariate continuous distribution. The resulting generator object is of the same type as of a unur_distr_cont_new call. (However, it cannot be used to make an order statistics out of an order statistics.)

To have a PDF for the order statistics, the given distribution object must contain a CDF and a PDF. Moreover, it is assumed that the given PDF is the derivative of the given CDF. Otherwise the area below the PDF of the order statistics is not computed correctly.

Important: There is no warning when the computed area below the PDF of the order statistics is wrong.

: const UNUR_DISTR* unur_distr_corder_get_distribution (const UNUR_DISTR* distribution) ¶

Get pointer to distribution object for underlying distribution.

Essential parameters

: int unur_distr_corder_set_rank (UNUR_DISTR* distribution, int n, int k) ¶

Change sample size n and rank k of order statistics. In case of invalid data, no parameters are changed. The area below the PDF can be set to that of the underlying distribution by a unur_distr_corder_upd_pdfarea call.

: int unur_distr_corder_get_rank (const UNUR_DISTR* distribution, int* n, int* k) ¶

Get sample size n and rank k of order statistics. In case of error an error code is returned.

Additionally most of the set and get calls for continuous univariate distributions work. The most important exceptions are that the PDF and CDF cannot be changed and unur_distr_cont_upd_mode uses in any way a (slow) numerical method that might fail.

: UNUR_FUNCT_CONT* unur_distr_corder_get_pdf (UNUR_DISTR* distribution) ¶

: UNUR_FUNCT_CONT* unur_distr_corder_get_dpdf (UNUR_DISTR* distribution) ¶

: UNUR_FUNCT_CONT* unur_distr_corder_get_cdf (UNUR_DISTR* distribution) ¶

Get the respective pointer to the PDF, the derivative of the PDF and the CDF of the distribution, respectively. The pointer is of type double funct(double x, UNUR_DISTR *distr). If the corresponding function is not available for the distribution, the NULL pointer is returned. See also unur_distr_cont_get_pdf. (Macro)

: double unur_distr_corder_eval_pdf (double x, UNUR_DISTR* distribution) ¶

: double unur_distr_corder_eval_dpdf (double x, UNUR_DISTR* distribution) ¶

: double unur_distr_corder_eval_cdf (double x, UNUR_DISTR* distribution) ¶

Evaluate the PDF, derivative of the PDF. and the CDF, respectively, at x. Notice that distribution must not be the NULL pointer. If the corresponding function is not available for the distribution, UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_DATA. See also unur_distr_cont_eval_pdf. (Macro)

IMPORTANT: In the case of a truncated standard distribution these calls always return the respective values of the untruncated distribution!

: int unur_distr_corder_set_pdfparams (UNUR_DISTR* distribution, double* params, int n_params) ¶

Set array of parameters for underlying distribution. See unur_distr_cont_set_pdfparams for details. (Macro)

: int unur_distr_corder_get_pdfparams (UNUR_DISTR* distribution, double** params) ¶

Get number of parameters of the PDF of the underlying distribution and set pointer params to array of parameters. See unur_distr_cont_get_pdfparams for details. (Macro)

: int unur_distr_corder_set_domain (UNUR_DISTR* distribution, double left, double right) ¶

Set the left and right borders of the domain of the distribution. See unur_distr_cont_set_domain for details. (Macro)

: int unur_distr_corder_get_domain (UNUR_DISTR* distribution, double* left, double* right) ¶

Get the left and right borders of the domain of the distribution. See unur_distr_cont_get_domain for details. (Macro)

: int unur_distr_corder_get_truncated (UNUR_DISTR* distribution, double* left, double* right) ¶

Get the left and right borders of the (truncated) domain of the distribution. See unur_distr_cont_get_truncated for details. (Macro)

Derived parameters

The following paramters must be set whenever one of the essential parameters has been set or changed (and the parameter is required for the chosen method).

: int unur_distr_corder_set_mode (UNUR_DISTR* distribution, double mode) ¶

Set mode of distribution. See also unur_distr_corder_set_mode. (Macro)

: double unur_distr_corder_upd_mode (UNUR_DISTR* distribution) ¶

Recompute the mode of the distribution numerically. Notice that this routine is slow and might not work properly in every case. See also unur_distr_cont_upd_mode for further details. (Macro)

: double unur_distr_corder_get_mode (UNUR_DISTR* distribution) ¶

Get mode of distribution. See unur_distr_cont_get_mode for details. (Macro)

: int unur_distr_corder_set_pdfarea (UNUR_DISTR* distribution, double area) ¶

Set the area below the PDF. See unur_distr_cont_set_pdfarea for details. (Macro)

: double unur_distr_corder_upd_pdfarea (UNUR_DISTR* distribution) ¶

Recompute the area below the PDF of the distribution. It only works for order statistics for distribution objects from the UNU.RAN library of standard distributions when the corresponding function is available. unur_distr_cont_upd_pdfarea assumes that the PDF of the underlying distribution is normalized, i.e. it is the derivative of its CDF. Otherwise the computed area is wrong and there is no warning about this failure. See unur_distr_cont_upd_pdfarea for further details. (Macro)

: double unur_distr_corder_get_pdfarea (UNUR_DISTR* distribution) ¶

Get the area below the PDF of the distribution. See unur_distr_cont_get_pdfarea for details. (Macro)

4.4 Continuous empirical univariate distributions

Empirical univariate distributions are derived from observed data. There are two ways to create such a generator object:

1. By a list of raw data by means of a unur_distr_cemp_set_data call.
2. By a histogram (i.e. preprocessed data) by means of a unur_distr_cemp_set_hist call.

How these data are used to sample from the empirical distribution depends from the chosen generation method.

Function reference

• unur_distr_cemp_new
• unur_distr_cemp_set_data
• unur_distr_cemp_read_data
• unur_distr_cemp_get_data
• unur_distr_cemp_set_hist
• unur_distr_cemp_set_hist_prob
• unur_distr_cemp_set_hist_domain
• unur_distr_cemp_set_hist_bins

: UNUR_DISTR* unur_distr_cemp_new (void) ¶

Create a new (empty) object for empirical univariate continuous distribution.

Essential parameters

: int unur_distr_cemp_set_data (UNUR_DISTR* distribution, const double* sample, int n_sample) ¶

Set observed sample for empirical distribution.

: int unur_distr_cemp_read_data (UNUR_DISTR* distribution, const char* filename) ¶

Read data from file filename. It reads the first number from each line. Numbers are parsed by means of the C standard routine strtod. Lines that do not start with +, -, ., or a digit are ignored. (Beware of lines starting with a blank!)

In case of an error (file cannot be opened, invalid string for double in line) no data are copied into the distribution object and an error code is returned.

: int unur_distr_cemp_get_data (const UNUR_DISTR* distribution, const double** sample) ¶

Get number of samples and set pointer sample to array of observations. If no sample has been given, an error code is returned and sample is set to NULL.

Important: Do not change the entries in sample!

: int unur_distr_cemp_set_hist (UNUR_DISTR* distribution, const double* prob, int n_prob, double xmin, double xmax) ¶

Set a histogram with bins of equal width. prob is an array of length n_prob that contains the probabilities for the bins (in ascending order). xmin and xmax give the lower and upper bound of the histogram, respectively. The bins are assumed to have equal width.

Remark: This is shortcut for calling unur_distr_cemp_set_hist_prob and unur_distr_cemp_set_hist_domain. Notice: All sampling methods either use raw data or histogram. It is possible to set both types of data; however, it is not checked whether the given histogran corresponds to possibly given raw data.

: int unur_distr_cemp_set_hist_prob (UNUR_DISTR* distribution, const double* prob, int n_prob) ¶

Set probabilities of a histogram with n_prob bins. Hence prob must be an array of length n_prob that contains the probabilities for the bins in ascending order. It is important also to set the location of the bins either with a unur_distr_cemp_set_hist_domain for bins of equal width or unur_distr_cemp_set_hist_bins when the bins have different width.

Notice: All sampling methods either use raw data or histogram. It is possible to set both types of data; however, it is not checked whether the given histogram corresponds to possibly given raw data.

: int unur_distr_cemp_set_hist_domain (UNUR_DISTR* distribution, double xmin, double xmax) ¶

Set a domain of a histogram with bins of equal width. xmin and xmax give the lower and upper bound of the histogram, respectively.

: int unur_distr_cemp_set_hist_bins (UNUR_DISTR* distribution, const double* bins, int n_bins) ¶

Set location of bins of a histogram with n_bins bins. Hence bins must be an array of length n_bins. The domain of the distribution is automatically set by this call and overrides any calls to unur_distr_cemp_set_hist_domain. Important: The probabilities of the bins of the distribution must be already be set by a unur_distr_cemp_set_hist_prob (or a unur_distr_cemp_set_hist call) and the value of n_bins must equal n_prob+1 from the corresponding value of the respective call.

4.5 Continuous multivariate distributions

The following calls handle multivariate distributions. However, the requirements of particular generation methods is not as unique as for univariate distributions. Moreover, random vector generation methods are still under development. The below functions are a first attempt to handle this situation.

Notice that some of the parameters – when given carelessly – might contradict to others. For example: Some methods require the marginal distribution and some methods need a standardized form of the marginal distributions, where the actual mean and variance is stored in the mean vector and the covariance matrix, respectively.

We also have to mention that some methods might abuse some of the parameters. Please read the discription of the chosen sampling method carfully.

The following kind of calls exists:

• Create a new instance of a continuous multivariate distribution;
• Handle and evaluate probability density function (PDF, pdf) and the gradient of the density function (dpdf). The following is important:
  • pdf need not be normalized, i.e., any integrable nonnegative function can be used.
  • dpdf must the derivate of the function provided as pdf.
• Handle and evaluate the logarithm of the probability density function (logPDF, logpdf) and the gradient of the logarithm of the density function (dlogpdf).

  Some methods use the logarithm of the density if available.

• Set (and change) parameters (pdfparams) and the volume below the graph (pdfvol) of the given density.
• Set mode and mean of the distribution.
• Set the center of the distribution. It is used by some generation methods to adjust the parameters of the generation algorithms to gain better performance. It can be seens as the location of the “central part” of the distribution.
• Handle the covariance matrix of the distribution and its cholesky and invverse matrices.
• Set the rankcorrelation matrix of the distribution.
• Deal with marginal distributions.
• Set domain of the distribution.

Function reference

• unur_distr_cvec_new
• unur_distr_cvec_set_pdf
• unur_distr_cvec_set_dpdf
• unur_distr_cvec_set_pdpdf
• unur_distr_cvec_get_pdf
• unur_distr_cvec_get_dpdf
• unur_distr_cvec_eval_pdf
• unur_distr_cvec_eval_dpdf
• unur_distr_cvec_eval_pdpdf
• unur_distr_cvec_set_logpdf
• unur_distr_cvec_set_dlogpdf
• unur_distr_cvec_set_pdlogpdf
• unur_distr_cvec_get_logpdf
• unur_distr_cvec_get_dlogpdf
• unur_distr_cvec_eval_logpdf
• unur_distr_cvec_eval_dlogpdf
• unur_distr_cvec_eval_pdlogpdf
• unur_distr_cvec_set_mean
• unur_distr_cvec_get_mean
• unur_distr_cvec_set_covar
• unur_distr_cvec_set_covar_inv
• unur_distr_cvec_get_covar
• unur_distr_cvec_get_cholesky
• unur_distr_cvec_get_covar_inv
• unur_distr_cvec_set_rankcorr
• unur_distr_cvec_get_rankcorr
• unur_distr_cvec_get_rk_cholesky
• unur_distr_cvec_set_marginals
• unur_distr_cvec_set_marginal_array
• unur_distr_cvec_set_marginal_list
• unur_distr_cvec_get_marginal
• unur_distr_cvec_set_pdfparams
• unur_distr_cvec_get_pdfparams
• unur_distr_cvec_set_pdfparams_vec
• unur_distr_cvec_get_pdfparams_vec
• unur_distr_cvec_set_domain_rect
• unur_distr_cvec_is_indomain
• unur_distr_cvec_set_mode
• unur_distr_cvec_upd_mode
• unur_distr_cvec_get_mode
• unur_distr_cvec_set_center
• unur_distr_cvec_get_center
• unur_distr_cvec_set_pdfvol
• unur_distr_cvec_upd_pdfvol
• unur_distr_cvec_get_pdfvol

: UNUR_DISTR* unur_distr_cvec_new (int dim) ¶

Create a new (empty) object for multivariate continuous distribution. dim is the number of components of the random vector (i.e. its dimension). It is also possible to use dimension 1. Notice, however, that this is treated as a distribution of random vectors with only one component and not as a distribution of real numbers. For the latter unur_distr_cont_new should be used to create an object for a univariate distribution.

Essential parameters

: int unur_distr_cvec_set_pdf (UNUR_DISTR* distribution, UNUR_FUNCT_CVEC* pdf) ¶

Set respective pointer to the PDF of the distribution. This function must be of type double funct(const double *x, UNUR_DISTR *distr), where x must be a pointer to a double array of appropriate size (i.e. of the same size as given to the unur_distr_cvec_new call).

It is not necessary that the given PDF is normalized, i.e. the integral need not be 1. Nevertheless the volume below the PDF can be provided by a unur_distr_cvec_set_pdfvol call.

It is not possible to change the PDF. Once the PDF is set it cannot be overwritten. This also holds when the logPDF is given. A new distribution object has to be used instead.

: int unur_distr_cvec_set_dpdf (UNUR_DISTR* distribution, UNUR_VFUNCT_CVEC* dpdf) ¶

Set pointer to the gradient of the PDF. The type of this function must be int funct(double *result, const double *x, UNUR_DISTR *distr), where result and x must be pointers to double arrays of appropriate size (i.e. of the same size as given to the unur_distr_cvec_new call). The gradient of the PDF is stored in the array result. The function should return an error code in case of an error and must return UNUR_SUCCESS otherwise.

The given function must be the gradient of the function given by a unur_distr_cvec_set_pdf call.

It is not possible to change the gradient of the PDF. Once the dPDF is set it cannot be overwritten. This also holds when the gradient of the logPDF is given. A new distribution object has to be used instead.

: int unur_distr_cvec_set_pdpdf (UNUR_DISTR* distribution, UNUR_FUNCTD_CVEC* pdpdf) ¶

Set pointer to partial derivatives of the PDF. The type of this function must be double funct(const double *x, int coord, UNUR_DISTR *distr), where x must be a pointer to a double array of appropriate size (i.e. of the same size as given to the unur_distr_cvec_new call). coord is the coordinate for which the partial dervative should be computed.

Notice that coord must be an integer from {0,…,dim-1}.

It is not possible to change the partial derivative of the PDF. Once the pdPDF is set it cannot be overwritten. This also holds when the partial derivative of the logPDF is given. A new distribution object has to be used instead.

: UNUR_FUNCT_CVEC* unur_distr_cvec_get_pdf (const UNUR_DISTR* distribution) ¶

Get the pointer to the PDF of the distribution. The pointer is of type double funct(const double *x, UNUR_DISTR *distr). If the corresponding function is not available for the distribution, the NULL pointer is returned.

: UNUR_VFUNCT_CVEC* unur_distr_cvec_get_dpdf (const UNUR_DISTR* distribution) ¶

Get the pointer to the gradient of the PDF of the distribution. The pointer is of type int double funct(double *result, const double *x, UNUR_DISTR *distr). If the corresponding function is not available for the distribution, the NULL pointer is returned.

: double unur_distr_cvec_eval_pdf (const double* x, UNUR_DISTR* distribution) ¶

Evaluate the PDF of the distribution at x. x must be a pointer to a double array of appropriate size (i.e. of the same size as given to the unur_distr_cvec_new call) that contains the vector for which the function has to be evaluated.

Notice that distribution must not be the NULL pointer. If the corresponding function is not available for the distribution, UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_DATA.

: int unur_distr_cvec_eval_dpdf (double* result, const double* x, UNUR_DISTR* distribution) ¶

Evaluate the gradient of the PDF of the distribution at x. The result is stored in the double array result. Both result and x must be pointer to double arrays of appropriate size (i.e. of the same size as given to the unur_distr_cvec_new call).

Notice that distribution must not be the NULL pointer. If the corresponding function is not available for the distribution, an error code is returned and unur_errno is set to UNUR_ERR_DISTR_DATA (result is left unmodified).

: double unur_distr_cvec_eval_pdpdf (const double* x, int coord, UNUR_DISTR* distribution) ¶

Evaluate the partial derivative of the PDF of the distribution at x for the coordinate coord. x must be a pointer to a double array of appropriate size (i.e. of the same size as given to the unur_distr_cvec_new call) that contains the vector for which the function has to be evaluated.

Notice that coord must be an integer from {0,…,dim-1}.

Notice that distribution must not be the NULL pointer. If the corresponding function is not available for the distribution, UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_DATA.

: int unur_distr_cvec_set_logpdf (UNUR_DISTR* distribution, UNUR_FUNCT_CVEC* logpdf) ¶

: int unur_distr_cvec_set_dlogpdf (UNUR_DISTR* distribution, UNUR_VFUNCT_CVEC* dlogpdf) ¶

: int unur_distr_cvec_set_pdlogpdf (UNUR_DISTR* distribution, UNUR_FUNCTD_CVEC* pdlogpdf) ¶

: UNUR_FUNCT_CVEC* unur_distr_cvec_get_logpdf (const UNUR_DISTR* distribution) ¶

: UNUR_VFUNCT_CVEC* unur_distr_cvec_get_dlogpdf (const UNUR_DISTR* distribution) ¶

: double unur_distr_cvec_eval_logpdf (const double* x, UNUR_DISTR* distribution) ¶

: int unur_distr_cvec_eval_dlogpdf (double* result, const double* x, UNUR_DISTR* distribution) ¶

: double unur_distr_cvec_eval_pdlogpdf (const double* x, int coord, UNUR_DISTR* distribution) ¶

Analogous calls for the logarithm of the density function.

: int unur_distr_cvec_set_mean (UNUR_DISTR* distribution, const double* mean) ¶

Set mean vector for multivariate distribution. mean must be a pointer to an array of size dim, where dim is the dimension returned by unur_distr_get_dim. A NULL pointer for mean is interpreted as the zero vector (0,…,0).

Important: If the parameters of a distribution from the UNU.RAN library of standard distributions (see Standard distributions) are changed, then neither its mode nor the normalization constant are updated. Please use the respective calls unur_distr_cvec_upd_mode and unur_distr_cvec_upd_pdfvol.

: const double* unur_distr_cvec_get_mean (const UNUR_DISTR* distribution) ¶

Get the mean vector of the distribution. The function returns a pointer to an array of size dim. If the mean vector is not marked as known the NULL pointer is returned and unur_errno is set to UNUR_ERR_DISTR_GET.

Important: Do not modify the array that holds the mean vector!

: int unur_distr_cvec_set_covar (UNUR_DISTR* distribution, const double* covar) ¶

Set covariance matrix for multivariate distribution. covar must be a pointer to an array of size dim x dim, where dim is the dimension returned by unur_distr_get_dim. The rows of the matrix have to be stored consecutively in this array.

covar must be a variance-covariance matrix of the distribution, i.e. it must be symmetric and positive definit and its diagonal entries (i.e. the variance of the components of the random vector) must be strictly positive. The Cholesky factor is computed (and stored) to verify the positive definiteness condition. Notice that the inverse of the given covariance matrix is automatically computed when it is requested by some routine. Notice that the computation of this inverse matrix is unstable in case of high correlations and/or high dimensions. Thus it might fail and methods that require this inverse cannot be used. As an alternative the inverse of the covariance matrix can be directly set by a unur_distr_cvec_set_covar_inv call.

A NULL pointer for covar is interpreted as the identity matrix.

Important: This entry is abused in some methods which do not require the covariance matrix. It is then used to perform some transformation to obtain better performance.

Important: In case of an error (e.g. because covar is not a valid covariance matrix) an error code is returned. Moreover, the covariance matrix is not set and is marked as unknown. A previously set covariance matrix is then no longer available.

Important: If the parameters of a distribution from the UNU.RAN library of standard distributions (see Standard distributions) are changed, then neither its mode nor the normalization constant are updated. Please use the respective calls unur_distr_cvec_upd_mode and unur_distr_cvec_upd_pdfvol. Remark: UNU.RAN does not check whether the an eventually set covariance matrix and a rank-correlation matrix do not contradict each other.

: int unur_distr_cvec_set_covar_inv (UNUR_DISTR* distribution, const double* covar_inv) ¶

Set inverse of the covariance matrix for multivariate distribution. covar_inv must be a pointer to an array of size dim x dim, where dim is the dimension returned by unur_distr_get_dim. The rows of the matrix have to be stored consecutively in this array.

covar_inv must be symmetric and positive definit. Only the symmetry of the matrix is checked.

A NULL pointer for covar_inv is interpreted as the identity matrix.

Important: In case of an error (because covar_inv is not symetric) an error code is returned. Moreover, the inverse of the covariance matrix is not set and is marked as unknown. A previously set inverse matrix is then no longer available.

Remark: UNU.RAN does not check whether the given matrix is positive definit.

Remark: UNU.RAN does not check whether the matrix covar_inv is the inverse of the eventually set covariance matrix.

: const double* unur_distr_cvec_get_covar (const UNUR_DISTR* distribution) ¶

: const double* unur_distr_cvec_get_cholesky (const UNUR_DISTR* distribution) ¶

: const double* unur_distr_cvec_get_covar_inv (UNUR_DISTR* distribution) ¶

Get covariance matrix of distribution, its Cholesky factor, and its inverse, respectively. The function returns a pointer to an array of size dim x dim. The rows of the matrix are stored consecutively in this array. If the requested matrix is not marked as known the NULL pointer is returned and unur_errno is set to UNUR_ERR_DISTR_GET.

Important: Do not modify the array that holds the covariance matrix!

Remark: The inverse of the covariance matrix is computed if it is not already stored.

: int unur_distr_cvec_set_rankcorr (UNUR_DISTR* distribution, const double* rankcorr) ¶

Set rank-correlation matrix (Spearman’s correlation) for multivariate distribution. rankcorr must be a pointer to an array of size dim x dim, where dim is the dimension returned by unur_distr_get_dim. The rows of the matrix have to be stored consecutively in this array.

rankcorr must be a rank-correlation matrix of the distribution, i.e. it must be symmetric and positive definite and its diagonal entries must be equal to 1.

The Cholesky factor is computed (and stored) to verify the positive definiteness condition.

A NULL pointer for rankcorr is interpreted as the identity matrix.

Important: In case of an error (e.g. because rankcorr is not a valid rank-correlation matrix) an error code is returned. Moreover, the rank-correlation matrix is not set and is marked as unknown. A previously set rank-correlation matrix is then no longer available.

Remark: UNU.RAN does not check whether the an eventually set covariance matrix and a rank-correlation matrix do not contradict each other.

: const double* unur_distr_cvec_get_rankcorr (const UNUR_DISTR* distribution) ¶

: const double* unur_distr_cvec_get_rk_cholesky (const UNUR_DISTR* distribution) ¶

Get rank-correlation matrix and its cholesky factor, respectively, of distribution. The function returns a pointer to an array of size dim x dim. The rows of the matrix are stored consecutively in this array. If the requested matrix is not marked as known the NULL pointer is returned and unur_errno is set to UNUR_ERR_DISTR_GET.

Important: Do not modify the array that holds the rank-correlation matrix!

: int unur_distr_cvec_set_marginals (UNUR_DISTR* distribution, UNUR_DISTR* marginal) ¶

Sets marginal distributions of the given distribution to the same marginal distribution object. The marginal distribution must be an instance of a continuous univariate distribution object. Notice that the marginal distribution is copied into the distribution object.

: int unur_distr_cvec_set_marginal_array (UNUR_DISTR* distribution, UNUR_DISTR** marginals) ¶

Analogously to the above unur_distr_cvec_set_marginals call. However, now an array marginals of the pointers to each of the marginal distributions must be given. It must be an array of size dim, where dim is the dimension returned by unur_distr_get_dim. Notice: Local copies for each of the entries are stored in the distribution object. If some of these entries are identical (i.e. contain the same pointer), then for each of these a new copy is made.

: int unur_distr_cvec_set_marginal_list (UNUR_DISTR* distribution, ...) ¶

Similar to the above unur_distr_cvec_set_marginal_array call. However, now the pointers to the particular marginal distributions can be given as parameter and does not require an array of pointers. Additionally the given distribution objects are immediately destroyed. Thus calls like unur_distr_normal can be used as arguments. (With unur_distr_cvec_set_marginal_array the result of such call has to be stored in a pointer since it has to be freed afterwarts to avoid memory leaks!)

The number of pointers to in the list of function arguments must be equal to the dimension of the distribution, i.e. the dimension returned by unur_distr_get_dim. If one of the given pointer to marginal distributions is the NULL pointer then the marginal distributions of distribution are not set (or previous settings are not changed) and an error code is returned.

Important: All distribution objects given in the argument list are destroyed!

: const UNUR_DISTR* unur_distr_cvec_get_marginal (const UNUR_DISTR* distribution, int n) ¶

Get pointer to the n-th marginal distribution object from the given multivariate distribution. If this does not exist, NULL is returned. The marginal distributions are enumerated from 1 to dim, where dim is the dimension returned by unur_distr_get_dim.

: int unur_distr_cvec_set_pdfparams (UNUR_DISTR* distribution, const double* params, int n_params) ¶

Sets array of parameters for distribution. There is an upper limit for the number of parameters n_params. It is given by the macro UNUR_DISTR_MAXPARAMS in unuran_config.h. (It is set to 5 by default but can be changed to any appropriate nonnegative number.) If n_params is negative or exceeds this limit no parameters are copied into the distribution object and unur_errno is set to UNUR_ERR_DISTR_NPARAMS.

For standard distributions from the UNU.RAN library the parameters are checked. Moreover, the domain is updated automatically. If the given parameters are invalid for the standard distribution, then no parameters are set and an error code is returned. Notice that the given parameter list for such a distribution is handled in the same way as in the corresponding new calls, i.e. optional parameters for the PDF that are not present in the given list are (re-)set to their default values.

Important: If the parameters of a distribution from the UNU.RAN library of standard distributions (see Standard distributions) are changed, then neither its mode nor the normalization constant are updated. Please use the respective calls unur_distr_cvec_upd_mode and unur_distr_cvec_upd_pdfvol.

: int unur_distr_cvec_get_pdfparams (const UNUR_DISTR* distribution, const double** params) ¶

Get number of parameters of the PDF and set pointer params to array of parameters. If no parameters are stored in the object, an error code is returned and params is set to NULL.

Important: Do not change the entries in params!

: int unur_distr_cvec_set_pdfparams_vec (UNUR_DISTR* distribution, int par, const double* param_vec, int n_params) ¶

This function provides an interface for additional vector parameters for a multivariate distribution besides mean vector and covariance matrix which have their own calls.

It sets the parameter with number par. par indicates directly which of the parameters is set and must be a number between 0 and UNUR_DISTR_MAXPARAMS-1 (the upper limit of possible parameters defined in unuran_config.h; it is set to 5 but can be changed to any appropriate nonnegative number.)

The entries of a this parameter are given by the array param_vec of size n_params. Notice that using this interface an An (n x m)-matrix has to be stored in an array of length n_params = n times m; where the rows of the matrix are stored consecutively in this array.

Due to great variety of possible parameters for a multivariate distribution there is no simpler interface.

If param_vec is NULL then the corresponding entry is cleared.

Important: If the parameters of a distribution from the UNU.RAN library of standard distributions (see Standard distributions) are changed, then neither its mode nor the normalization constant are updated. Please use the respective calls unur_distr_cvec_upd_mode and unur_distr_cvec_upd_pdfvol. If an error occurs no parameters are copied into the parameter object unur_errno is set to UNUR_ERR_DISTR_DATA.

: int unur_distr_cvec_get_pdfparams_vec (const UNUR_DISTR* distribution, int par, const double** param_vecs) ¶

Get parameter of the PDF with number par. The pointer to the parameter array is stored in param_vecs, its size is returned by the function. If the requested parameter is not set, then an error code is returned and params is set to NULL.

Important: Do not change the entries in param_vecs!

: int unur_distr_cvec_set_domain_rect (UNUR_DISTR* distribution, const double* lowerleft, const double* upperright) ¶

Set rectangular domain for distribution with lowerleft and upperright vertices. Both must be pointer to an array of the size returned by unur_distr_get_dim. A NULL pointer is interpreted as the zero vector (0,…,0). For setting a coordinate of the boundary to +/- infinity use +/- UNUR_INFINITY. The lowerleft vertex must be strictly smaller than upperright in each component. Otherwise no domain is set and unur_errno is set to UNUR_ERR_DISTR_SET.

By default the domain of a distribution is unbounded. Thus one can use this call to truncate an existing distribution.

Important: Changing the domain of distribution marks derived parameters like the mode or the center as unknown and must be set after changing the domain. This is important for the already set (or default) value for the center does not fall into the given domain. Notice that calls of the PDF and derived functions return 0. when the parameter is not contained in the domain.

: int unur_distr_cvec_is_indomain (const double* x, const UNUR_DISTR* distribution) ¶

Check whether x falls into the domain of distribution.

Derived parameters

The following paramters must be set whenever one of the essential parameters has been set or changed (and the parameter is required for the chosen method).

: int unur_distr_cvec_set_mode (UNUR_DISTR* distribution, const double* mode) ¶

Set mode of the distribution. mode must be a pointer to an array of the size returned by unur_distr_get_dim. A NULL pointer for mode is interpreted as the zero vector (0,…,0).

: int unur_distr_cvec_upd_mode (UNUR_DISTR* distribution) ¶

Recompute the mode of the distribution. This call works properly for distribution objects from the UNU.RAN library of standard distributions when the corresponding function is available. If it failes unur_errno is set to UNUR_ERR_DISTR_DATA.

: const double* unur_distr_cvec_get_mode (UNUR_DISTR* distribution) ¶

Get mode of the distribution. The function returns a pointer to an array of the size returned by unur_distr_get_dim. If the mode is not marked as known the NULL pointer is returned and unur_errno is set to UNUR_ERR_DISTR_GET. (There is no difference between the case where no routine for computing the mode is available and the case where no mode exists for the distribution at all.)

Important: Do not modify the array that holds the mode!

: int unur_distr_cvec_set_center (UNUR_DISTR* distribution, const double* center) ¶

Set center of the distribution. center must be a pointer to an array of the size returned by unur_distr_get_dim. A NULL pointer for center is interpreted as the zero vector (0,…,0).

The center is used by some methods to shift the distribution in order to decrease numerical round-off error. If not given explicitly a default is used. Moreover, it is used as starting point for several numerical search algorithm (e.g. for the mode). Then center must be a pointer where the call to the PDF returns a non-zero value. In particular center must contained in the domain of the distribution.

Default: The mode, if given by a unur_distr_cvec_set_mode call; else the mean, if given by a unur_distr_cvec_set_mean call; otherwise the null vector (0,…,0).

: const double* unur_distr_cvec_get_center (UNUR_DISTR* distribution) ¶

Get center of the distribution. The function returns a pointer to an array of the size returned by unur_distr_get_dim. It always returns some point as there always exists a default for the center, see unur_distr_cvec_set_center. Important: Do not modify the array that holds the center!

: int unur_distr_cvec_set_pdfvol (UNUR_DISTR* distribution, double volume) ¶

Set the volume below the PDF. If vol is non-positive, no volume is set and unur_errno is set to UNUR_ERR_DISTR_SET.

: int unur_distr_cvec_upd_pdfvol (UNUR_DISTR* distribution) ¶

Recompute the volume below the PDF of the distribution. It only works for distribution objects from the UNU.RAN library of standard distributions when the corresponding function is available. Otherwise unur_errno is set to UNUR_ERR_DISTR_DATA.

This call also sets the normalization constant such that the given PDF is the derivative of a given CDF, i.e. the volume is 1.

: double unur_distr_cvec_get_pdfvol (UNUR_DISTR* distribution) ¶

Get the volume below the PDF of the distribution. If this volume is not known,
unur_distr_cont_upd_pdfarea is called to compute it. If this is not successful UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_GET.

4.6 Continuous univariate full conditional distribution

Full conditional distribution for a given continuous multivariate distributiion. The condition is a position vector and either a variable that is variated or a vector that indicates the direction on which the random vector can variate.

There is a subtle difference between using direction vector and using the k-th variable. When a direction vector is given the PDF of the conditional distribution is defined by f(t) = PDF(pos + t * dir). When a variable is selected the full conditional distribution with all other variables fixed is used.

This is a special case of a continuous univariate distribution and thus they have most of these parameters (with the exception that functions cannot be changed). Additionally,

• there is a call to extract the underlying multivariate distribution,
• and a call to handle the variables that are fixed and the direction for changing the random vector.

This distibution type is primarily used for evaluation the conditional distribution and its derivative (as required for, e.g., the Gibbs sampler). The density is not normalized (i.e. does not integrate to one). Mode and area are not available and it does not make sense to use any call to set or change parameters except the ones given below.

Function reference

• unur_distr_condi_new
• unur_distr_condi_set_condition
• unur_distr_condi_get_condition
• unur_distr_condi_get_distribution

: UNUR_DISTR* unur_distr_condi_new (const UNUR_DISTR* distribution, const double* pos, const double* dir, int k) ¶

Create an object for full conditional distribution for the given distribution. The condition is given by a position vector pos and either the k-th variable that is variated or the vector dir that contains the direction on which the random vector can variate.

distribution must be a pointer to a multivariate continuous distribution. pos must be a pointer to an array of size dim, where dim is the dimension of the underlying distribution object. dir must be a pointer to an array if size dim or NULL. k must be in the range 0, …, dim-1. If the k-th variable is used, dir must be set to NULL.

Notice: There is a subtle difference between using direction vector dir and using the k-th variable. When dir is given, the current position pos is mapped into 0 of the conditional distribution and the derivative is taken from the function PDF(pos+t*dir) w.r.t. t. On the other hand, when the coordinate k is used (i.e., when dir is set to NULL), the full conditional distribution of the distribution is considered (as used for the Gibbs sampler). In particular, the current point is just projected into the one-dimensional subspace without mapping it into the point 0.

Notice: If a coordinate k is used, then the k-th partial derivative is used if it as available. Otherwise the gradient is computed and the k-th component is returned.

The resulting generator object is of the same type as of a unur_distr_cont_new call.

: int unur_distr_condi_set_condition (struct unur_distr* distribution, const double* pos, const double* dir, int k) ¶

Set/change condition for conditional distribution. Change values of fixed variables to pos and use direction dir or k-th variable of conditional distribution.

pos must be a pointer to an array of size dim, where dim is the dimension of the underlying distribution object. dir must be a pointer to an array if size dim or NULL. k must be in the range 0, …, dim-1. If the k-th variable is used, dir must be set to NULL.

Notice: There is a subtle difference between using direction vector dir and using the k-th variable. When dir is given, the current position pos is mapped into 0 of the conditional distribution and the derivative is taken from the function PDF(pos+t*dir) w.r.t. t. On the other hand, when the coordinate k is used (i.e., when dir is set to NULL), the full conditional distribution of the distribution is considered (as used for the Gibbs sampler). In particular, the current point is just projected into the one-dimensional subspace without mapping it into the point 0.

: int unur_distr_condi_get_condition (struct unur_distr* distribution, const double** pos, const double** dir, int* k) ¶

Get condition for conditional distribution. The values for the fixed variables are stored in pos, which must be a pointer to an array of size dim. The condition is stored in dir and k, respectively.

Important: Do not change the entries in pos and dir!

: const UNUR_DISTR* unur_distr_condi_get_distribution (const UNUR_DISTR* distribution) ¶

Get pointer to distribution object for underlying distribution.

4.7 Continuous empirical multivariate distributions

Empirical multivariate distributions are just lists of vectors (with the same dimension). Thus there are only calls to insert these data. How these data are used to sample from the empirical distribution depends from the chosen generation method.

Function reference

• unur_distr_cvemp_new
• unur_distr_cvemp_set_data
• unur_distr_cvemp_read_data
• unur_distr_cvemp_get_data

: UNUR_DISTR* unur_distr_cvemp_new (int dim) ¶

Create a new (empty) object for an empirical multivariate continuous distribution. dim is the number of components of the random vector (i.e. its dimension). It must be at least 2; otherwise unur_distr_cemp_new should be used to create an object for an empirical univariate distribution.

Essential parameters

: int unur_distr_cvemp_set_data (UNUR_DISTR* distribution, const double* sample, int n_sample) ¶

Set observed sample for empirical distribution. sample is an array of doubles of size dim x n_sample, where dim is the dimension of the distribution returned by unur_distr_get_dim. The data points must be stored consecutively in sample, i.e., data points (x1, y1), (x2, y2), … are given as an array {x1, y1, x2, y2, …}.

: int unur_distr_cvemp_read_data (UNUR_DISTR* distribution, const char* filename) ¶

Read data from file filename. It reads the first dim numbers from each line, where dim is the dimension of the distribution returned by unur_distr_get_dim. Numbers are parsed by means of the C standard routine strtod. Lines that do not start with +, -, ., or a digit are ignored. (Beware of lines starting with a blank!)

In case of an error (file cannot be opened, too few entries in a line, invalid string for double in line) no data are copied into the distribution object and an error code is returned.

: int unur_distr_cvemp_get_data (const UNUR_DISTR* distribution, const double** sample) ¶

Get number of samples and set pointer sample to array of observations. If no sample has been given, an error code is returned and sample is set to NULL. If successful sample points to an array of length dim x n_sample, where dim is the dimension of the distribution returned by unur_distr_get_dim and n_sample the return value of the function.

Important: Do not modify the array sample.

4.8 MATRix distributions

Distributions for random matrices. Notice that UNU.RAN uses arrays of doubles to handle matrices. The rows of the matrix are stored consecutively.

Function reference

• unur_distr_matr_new
• unur_distr_matr_get_dim

: UNUR_DISTR* unur_distr_matr_new (int n_rows, int n_cols) ¶

Create a new (empty) object for a matrix distribution. n_rows and n_cols are the respective numbers of rows and columns of the random matrix (i.e. its dimensions). It is also possible to have only one number or rows and/or columns. Notice, however, that this is treated as a distribution of random matrices with only one row or column or component and not as a distribution of vectors or real numbers. For the latter unur_distr_cont_new or unur_distr_cvec_new should be used to create an object for a univariate distribution and a multivariate (vector) distribution, respectively.

Essential parameters

: int unur_distr_matr_get_dim (const UNUR_DISTR* distribution, int* n_rows, int* n_cols) ¶

Get number of rows and columns of random matrix (its dimension). It returns the total number of components. If successfull UNUR_SUCCESS is returned.

4.9 Discrete univariate distributions

The calls in this section can be applied to discrete univariate distributions.

• Create a new instance of a discrete univariate distribution.
• Handle and evaluate distribution function (CDF, cdf) and probability mass function (PMF, pmf). The following is important:
  • pmf need not be normalized, i.e., any summable nonnegative function on the set of intergers can be used.
  • cdf must be a distribution function, i.e. it must be monotonically increasing with range [0,1].
  • If cdf and pdf are used together for a pariticular generation method, then pmf must be normalized, i.e. it must sum to 1.
• Alternatively, cdf and pdf can be provided as strings instead of function pointers.
• Some generation methods require a (finite) probability vector (PV, pv), i.e. an array of doubles. It can be automatically computed if the pmf is given but pv is not.
• Set (and change) parameters (pmfparams) and the total sum (pmfsum) of the given PMF or PV.
• Set the mode of the distribution.
• Set the domain of the distribution.

Function reference

• unur_distr_discr_new
• unur_distr_discr_set_pv
• unur_distr_discr_make_pv
• unur_distr_discr_get_pv
• unur_distr_discr_set_pmf
• unur_distr_discr_set_cdf
• unur_distr_discr_set_invcdf
• unur_distr_discr_eval_pv
• unur_distr_discr_eval_pmf
• unur_distr_discr_eval_cdf
• unur_distr_discr_eval_invcdf
• unur_distr_discr_set_pmfstr
• unur_distr_discr_set_cdfstr
• unur_distr_discr_get_pmfstr
• unur_distr_discr_get_cdfstr
• unur_distr_discr_set_pmfparams
• unur_distr_discr_get_pmfparams
• unur_distr_discr_set_domain
• unur_distr_discr_get_domain
• unur_distr_discr_set_mode
• unur_distr_discr_upd_mode
• unur_distr_discr_get_mode
• unur_distr_discr_set_pmfsum
• unur_distr_discr_upd_pmfsum
• unur_distr_discr_get_pmfsum

: UNUR_DISTR* unur_distr_discr_new (void) ¶

Create a new (empty) object for a univariate discrete distribution.

Essential parameters

There are two interfaces for discrete univariate distributions: Either provide a (finite) probability vector (PV). Or provide a probability mass function (PMF). For the latter case there are also a couple of derived parameters that are not required when a PV is given.

It is not possible to set both a PMF and a PV directly. However, the PV can be computed from the PMF (or the CDF if no PMF is available) by means of a unur_distr_discr_make_pv call. If both the PV and the PMF are given in the distribution object it depends on the generation method which of these is used.

: int unur_distr_discr_set_pv (UNUR_DISTR* distribution, const double* pv, int n_pv) ¶

Set finite probability vector (PV) for the distribution. It is not necessary that the entries in the given PV sum to 1. n_pv must be positive. However, there is no testing whether all entries in pv are non-negative.

If no domain has been set, then the left boundary is set to 0, by default. If n_pv is too large, e.g. because left boundary + n_pv exceeds the range of integers, then the call fails.

Notice that it is not possible to set both a PV and a PMF or CDF. If the PMF or CDF is set first one cannot set the PV. If the PMF or CDF is set first after a PV is set, the latter is removed (and recomputed using unur_distr_discr_make_pv when required).

: int unur_distr_discr_make_pv (UNUR_DISTR* distribution) ¶

Compute a PV when a PMF or CDF is given. However, when the domain is not given or is too large and the sum over the PMF is given then the (right) tail of the distribution is chopped off such that the probability for the tail region is less than 1.e-8. If the sum over the PMF is not given a PV of maximal length is computed.

The maximal size of the created PV is bounded by the macro UNUR_MAX_AUTO_PV that is defined in unuran_config.h.

If successful, the length of the generated PV is returned. If the sum over the PMF on the chopped tail is not neglible small (i.e. greater than 1.e-8 or unknown) than the negative of the length of the PV is returned and unur_errno is set to UNUR_ERR_DISTR_SET.

Notice that the left boundary of the PV is set to 0 by default when a discrete distribution object is created from scratch.

If computing a PV fails for some reasons, an error code is returned and unur_errno is set to UNUR_ERR_DISTR_SET.

: int unur_distr_discr_get_pv (const UNUR_DISTR* distribution, const double** pv) ¶

Get length of PV of the distribution and set pointer pv to array of probabilities. If no PV is given, an error code is returned and pv is set to NULL.
(It does not call unur_distr_discr_make_pv !)

: int unur_distr_discr_set_pmf (UNUR_DISTR* distribution, UNUR_FUNCT_DISCR* pmf) ¶

: int unur_distr_discr_set_cdf (UNUR_DISTR* distribution, UNUR_FUNCT_DISCR* cdf) ¶

Set respective pointer to the PMF and the CDF of the distribution. These functions must be of type double funct(int k, const UNUR_DISTR *distr).

It is important to note that all these functions must return a result for all integers k. E.g., if the domain of a given PMF is the interval {1,2,3,…,100}, than the given function must return 0.0 for all points outside this interval.

The default domain for the PMF or CDF is [0, INT_MAX]. The domain can be changed using a unur_distr_discr_set_domain call.

It is not possible to change such a function. Once the PMF or CDF is set it cannot be overwritten. A new distribution object has to be used instead.

Notice that it is not possible to set both a PV and a PMF or CDF. If the PMF or CDF is set first one cannot set the PV. If the PMF or CDF is set first after a PV is set, the latter is removed (and recomputed using unur_distr_discr_make_pv when required).

: int unur_distr_discr_set_invcdf (UNUR_DISTR* distribution, UNUR_IFUNCT_DISCR* invcdf) ¶

Set inverse CDF of the distribution. invcdf must be a pointer must be of type int funct(double x, const UNUR_DISTR *distr), i.e., it should return a double.

: double unur_distr_discr_eval_pv (int k, const UNUR_DISTR* distribution) ¶

: double unur_distr_discr_eval_pmf (int k, const UNUR_DISTR* distribution) ¶

: double unur_distr_discr_eval_cdf (int k, const UNUR_DISTR* distribution) ¶

Evaluate the PV, PMF, and the CDF, respectively, at k. Notice that distribution must not be the NULL pointer. If no PV is set for the distribution, then unur_distr_discr_eval_pv behaves like unur_distr_discr_eval_pmf. If the corresponding function is not available for the distribution, UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_DATA.

IMPORTANT: In the case of a truncated standard distribution these calls always return the respective values of the untruncated distribution!

: int unur_distr_discr_eval_invcdf (double u, const UNUR_DISTR* distribution) ¶

Evaluate the inverse CDF at u. Notice that distribution must not be the NULL pointer. If the corresponding function is not available for the distribution, INT_MAX is returned and unur_errno is set to UNUR_ERR_DISTR_DATA.

IMPORTANT: In the case of a truncated standard distribution these calls always return the respective values of the untruncated distribution!

: int unur_distr_discr_set_pmfstr (UNUR_DISTR* distribution, const char* pmfstr) ¶

This function provides an alternative way to set a PMF of the distribution. pmfstr is a character string that contains the formula for the PMF, see Function String, for details. See also the remarks for the unur_distr_discr_set_pmf call.

It is not possible to call this funtion twice or to call this function after a unur_distr_discr_set_pmf call.

: int unur_distr_discr_set_cdfstr (UNUR_DISTR* distribution, const char* cdfstr) ¶

This function provides an alternative way to set a CDF; analogously to the unur_distr_discr_set_pmfstr call.

: char* unur_distr_discr_get_pmfstr (const UNUR_DISTR* distribution) ¶

: char* unur_distr_discr_get_cdfstr (const UNUR_DISTR* distribution) ¶

Get pointer to respective string for PMF and CDF of distribution that is given via the string interface. This call allocates memory to produce this string. It should be freed when it is not used any more.

: int unur_distr_discr_set_pmfparams (UNUR_DISTR* distribution, const double* params, int n_params) ¶

Set array of parameters for distribution. There is an upper limit for the number of parameters n_params. It is given by the macro UNUR_DISTR_MAXPARAMS in unuran_config.h. (It is set to 5 but can be changed to any appropriate nonnegative number.) If n_params is negative or exceeds this limit no parameters are copied into the distribution object and unur_errno is set to UNUR_ERR_DISTR_NPARAMS.

For standard distributions from the UNU.RAN library the parameters are checked. Moreover, the domain is updated automatically unless it has been changed before by a unur_distr_discr_set_domain call. If the given parameters are invalid for the standard distribution, then no parameters are set and an error code is returned. Notice that the given parameter list for such a distribution is handled in the same way as in the corresponding new calls, i.e. optional parameters for the PDF that are not present in the given list are (re-)set to their default values.

Important: Integer parameter must be given as doubles.

: int unur_distr_discr_get_pmfparams (const UNUR_DISTR* distribution, const double** params) ¶

Get number of parameters of the PMF and set pointer params to array of parameters. If no parameters are stored in the object, an error code is returned and params is set to NULL.

: int unur_distr_discr_set_domain (UNUR_DISTR* distribution, int left, int right) ¶

Set the left and right borders of the domain of the distribution. This can also be used to truncate an existing distribution. For setting the boundary to +/- infinity use INT_MIN and INT_MAX, respectively. If right is not strictly greater than left no domain is set and unur_errno is set to UNUR_ERR_DISTR_SET. It is allowed to use this call to increase the domain. If the PV of the discrete distribution is used, than the right boudary is ignored (and internally set to left + size of PV - 1). Notice that INT_MIN and INT_MAX are interpreted as (minus/plus) infinity.

Default: [0, INT_MAX].

: int unur_distr_discr_get_domain (const UNUR_DISTR* distribution, int* left, int* right) ¶

Get the left and right borders of the domain of the distribution. If the domain is not set explicitly the interval [INT_MIN, INT_MAX] is assumed and returned. When a PV is given then the domain is set automatically to [0,size of PV - 1].

Derived parameters

The following paramters must be set whenever one of the essential parameters has been set or changed (and the parameter is required for the chosen method).

: int unur_distr_discr_set_mode (UNUR_DISTR* distribution, int mode) ¶

Set mode of distribution.

: int unur_distr_discr_upd_mode (UNUR_DISTR* distribution) ¶

Recompute the mode of the distribution. This call works properly for distribution objects from the UNU.RAN library of standard distributions when the corresponding function is available. Otherwise a (slow) numerical mode finder is used. It only works properly for unimodal probability mass functions. If it failes unur_errno is set to UNUR_ERR_DISTR_DATA.

: int unur_distr_discr_get_mode (UNUR_DISTR* distribution) ¶

Get mode of distribution. If the mode is not marked as known, unur_distr_discr_upd_mode is called to compute the mode. If this is not successful INT_MAX is returned and unur_errno is set to UNUR_ERR_DISTR_GET. (There is no difference between the case where no routine for computing the mode is available and the case where no mode exists for the distribution at all.)

: int unur_distr_discr_set_pmfsum (UNUR_DISTR* distribution, double sum) ¶

Set the sum over the PMF. If sum is non-positive, no sum is set and unur_errno is set to UNUR_ERR_DISTR_SET.

For a distribution object created by the UNU.RAN library of standard distributions you always should use the unur_distr_discr_upd_pmfsum. Otherwise there might be ambiguous side-effects.

: int unur_distr_discr_upd_pmfsum (UNUR_DISTR* distribution) ¶

Recompute the sum over the PMF of the distribution. In most cases the normalization constant is recomputed and thus the sum is 1. This call works for distribution objects from the UNU.RAN library of standard distributions when the corresponding function is available. When a PV, a PMF with finite domain, or a CDF is given, a simple generic function which uses a naive summation loop is used. If this computation is not possible, an error code is returned and unur_errno is set to UNUR_ERR_DISTR_DATA.

The call does not work for distributions from the UNU.RAN library of standard distributions with truncated domain when the CDF is not available.

: double unur_distr_discr_get_pmfsum (UNUR_DISTR* distribution) ¶

Get the sum over the PMF of the distribution. If this sum is not known, unur_distr_discr_upd_pmfsum is called to compute it. If this is not successful UNUR_INFINITY is returned and unur_errno is set to UNUR_ERR_DISTR_GET.

5.1 Routines for all generator objects

Routines for all generator objects.

Function reference

• unur_init
• unur_reinit
• unur_sample_discr
• unur_sample_cont
• unur_sample_vec
• unur_sample_matr
• unur_quantile
• unur_free
• unur_gen_info
• unur_get_dimension
• unur_get_genid
• unur_get_method
• unur_gen_is_inversion
• unur_get_distr
• unur_set_use_distr_privatecopy

: UNUR_GEN* unur_init (UNUR_PAR* parameters) ¶

Initialize a generator object. All necessary information must be stored in the parameter object.

Important: If an error has occurred a NULL pointer is return. This must not be used for the sampling routines (this causes a segmentation fault).

Always check whether the call was successful or not!

Important: This call destroys the parameter object automatically. Thus it is not necessary/allowed to free it.

: int unur_reinit (UNUR_GEN* generator) ¶

Update an existing generator object after the underlying distribution has been modified (using unur_get_distr together with corresponding set calls. It must be executed before sampling using this generator object is continued as otherwise it produces an invalid sample or might even cause a segmentation fault.

Important: Currently not all methods allow reinitialization, see the description of the particular method (keyword Reinit).

Important: Reinitialization of the generator object might fail. Thus one must check the return code:

UNUR_SUCCESS (0x0u)

success (no error)

UNUR_ERR_NO_REINIT

reinit routine not implemented.

other values

some error has occured while trying to reinitialize the generator object.

Important: When reinitialization fails then sampling routines always return UNUR_INFINITY (for continuous distributions) or 0 (for discrete distributions), respectively. However, it is still possible to change the underlying distribution and try to reinitialize again.

Important: When one tries to run unur_reinit but reinitialization is not implemented, then the generator object cannot be used any more and must be destroyed and a new one has to be built from scratch.

: int unur_sample_discr (UNUR_GEN* generator) ¶

: double unur_sample_cont (UNUR_GEN* generator) ¶

: int unur_sample_vec (UNUR_GEN* generator, double* vector) ¶

: int unur_sample_matr (UNUR_GEN* generator, double* matrix) ¶

Sample from generator object. The three routines depend on the type of the generator object (discrete or continuous univariate distribution, multivariate distribution, or random matrix).

Notice: UNU.RAN uses arrays of doubles to handle matrices. There the rows of the matrix are stored consecutively.

Notice: The routines unur_sample_vec and unur_sample_matr return UNUR_SUCCESS if generation was successful and some error code otherwise.

Important: These routines do not check whether generator is an invalid NULL pointer.

: double unur_quantile (UNUR_GEN* generator, double U) ¶

Compute the U quantile of a continuous distribution using a generator object that implements an (approximate) inversion methods.

The following methods are currently available:

• HINV, see HINV – Hermite interpolation based INVersion of CDF.
• NINV, see NINV – Numerical INVersion.
• PINV, see PINV – Polynomial interpolation based INVersion of CDF.
• CSTD, see CSTD – Continuous STandarD distributions.
  This requires that generator implements an inversion method.
• DGT, see DGT – (Discrete) Guide Table method (indexed search).
  The return value is (of course) type casted to double.

Important: This routine does not check whether generator is an invalid NULL pointer.

In case of an error UNUR_INFINITY or INT_MAX (depending on the type of generator) is returned.

: void unur_free (UNUR_GEN* generator) ¶

Destroy (free) the given generator object.

: const char* unur_gen_info (UNUR_GEN* generator, int help) ¶

Get a string with informations about the given generator. These informations allow some fine tuning of the generation method. If help is TRUE, some hints on setting parameters are given.

This function is intented for using in interactive environments (like R).

If an error occurs, then NULL is returned.

: int unur_get_dimension (const UNUR_GEN* generator) ¶

Get the number of dimension of a (multivariate) distribution. For a univariate distribution 1 is return.

: const char* unur_get_genid (const UNUR_GEN* generator) ¶

Get identifier string for generator.

: unsigned int unur_get_method (const UNUR_GEN* generator) ¶

Get identifier for generating method. These identifiers are declared in src/methods/unur_metthods.h.

: int unur_gen_is_inversion (const UNUR_GEN* gen) ¶

Return TRUE if the generator object implements an inversion method, and FALSE otherwise.

: UNUR_DISTR* unur_get_distr (const UNUR_GEN* generator) ¶

Get pointer to distribution object from generator object. This function can be used to change the parameters of the distribution and reinitialize the generator object. Notice that currently not all generating methods have a reinitialize routine. This function should be used with extreme care. Changing the distribution is changed and using the generator object without reinitializing might cause wrong samples or segmentation faults. Moreover, if the corresponding generator object is freed, the pointer must not be used.

Important: The returned distribution object must not be freed. If the distribution object is changed then one must run unur_reinit !

: int unur_set_use_distr_privatecopy (UNUR_PAR* parameters, int use_privatecopy) ¶

Set flag whether the generator object should make a private copy of the given distribution object or just stores the pointer to this distribution object. Values for use_privatecopy:

TRUE

make a private copy (default)

FALSE

do not make a private copy and store pointer to given (external) distribution object.

By default, generator objects keep their own private copy of the given distribution object. Thus the generator object can be handled independently from other UNU.RAN objects (with uniform random number generators as the only exception). When the generator object is initialized the given distribution object is cloned and stored.

However, in some rare situations it can be useful when only the pointer to the given distribution object is stored without making a private copy. A possible example is when only one random variate has to be drawn from the distribution. This behavior can be achieved when use_localcopy is set to FALSE.

Warning! Using a pointer to the external distribution object instead of a private copy must be done with extreme care! When the distrubtion object is changed or freed then the generator object does not work any more, might case a segmentation fault, or (even worse) produces garbage. On the other hand, when the generator object is initialized or used to draw a random sampling the distribution object may be changed.

Notice: The prototypes of all unur_<method>_new calls use a const qualifier for the distribution argument. However, if use_privatecopy is set to FALSE this qualifier is discarded and the distribution might be changed.

Important! If use_localcopy is set to FALSE and the corresponding distribution object is changed then one must run unur_reinit on the generator object. (Notice that currently not all generation methods support reinitialization.)

Default: use_privatecopy is TRUE.

5.2 AUTO – Select method automatically

AUTO selects a an appropriate method for the given distribution object automatically. There are no parameters for this method, yet. But it is planned to give some parameter to describe the task for which the random variate generator is used for and thus make the choice of the generating method more appropriate. Notice that the required sampling routine for the generator object depends on the type of the given distribution object.

The chosen method also depends on the sample size for which the generator object will be used. If only a few random variates the order of magnitude of the sample size should be set via a unur_auto_set_logss call.

IMPORTANT: This is an experimental version and the method chosen may change in future releases of UNU.RAN.

For an example see Example: As short as possible.

How To Use

Create a generator object for the given distribution object.

Function reference

• unur_auto_new
• unur_auto_set_logss

: UNUR_PAR* unur_auto_new (const UNUR_DISTR* distribution) ¶

Get default parameters for generator.

: int unur_auto_set_logss (UNUR_PAR* parameters, int logss) ¶

Set the order of magnitude for the size of the sample that will be generated by the generator, i.e., the the common logarithm of the sample size.

Default is 10.

Notice: This feature will be used in future releases of UNU.RAN only.

5.3 Methods for continuous univariate distributions

Overview of methods

Example

/* ------------------------------------------------------------- */
/* File: example_cont.c                                          */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

/* Example how to sample from a continuous univariate            */
/* distribution.                                                 */
/*                                                               */
/* We build a distribution object from scratch and sample.       */

/* ------------------------------------------------------------- */

/* Define the PDF and dPDF of our distribution.                  */
/*                                                               */
/* Our distribution has the PDF                                  */
/*                                                               */
/*          /  1 - x*x  if |x| <= 1                              */
/*  f(x) = <                                                     */
/*          \  0        otherwise                                */
/*                                                               */

/* The PDF of our distribution:                                  */
double mypdf( double x, const UNUR_DISTR *distr )
     /* The second argument (`distr') can be used for parameters */
     /* for the PDF. (We do not use parameters in our example.)  */
{
  if (fabs(x) >= 1.)
    return 0.;
  else
    return (1.-x*x);
} /* end of mypdf() */

/* The derivative of the PDF of our distribution:                */
double mydpdf( double x, const UNUR_DISTR *distr )
{
  if (fabs(x) >= 1.)
    return 0.;
  else
    return (-2.*x);
} /* end of mydpdf() */

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Declare the three UNURAN objects.                           */
  UNUR_DISTR *distr;    /* distribution object                   */
  UNUR_PAR   *par;      /* parameter object                      */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Create a new distribution object from scratch.              */

  /* Get empty distribution object for a continuous distribution */
  distr = unur_distr_cont_new();

  /* Fill the distribution object -- the provided information    */
  /* must fulfill the requirements of the method choosen below.  */
  unur_distr_cont_set_pdf(distr,  mypdf);     /* PDF             */
  unur_distr_cont_set_dpdf(distr, mydpdf);    /* its derivative  */
  unur_distr_cont_set_mode(distr, 0.);        /* mode            */
  unur_distr_cont_set_domain(distr, -1., 1.); /* domain          */

  /* Choose a method: TDR.                                       */
  par = unur_tdr_new(distr);

  /* Set some parameters of the method TDR.                      */
  unur_tdr_set_variant_gw(par);
  unur_tdr_set_max_sqhratio(par, 0.90);
  unur_tdr_set_c(par, -0.5);
  unur_tdr_set_max_intervals(par, 100);
  unur_tdr_set_cpoints(par, 10, NULL);

  /* Create the generator object.                                */
  gen = unur_init(par);

  /* Notice that this call has also destroyed the parameter      */
  /* object `par' as a side effect.                              */

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* It is possible to reuse the distribution object to create   */
  /* another generator object. If you do not need it any more,   */
  /* it should be destroyed to free memory.                      */
  unur_distr_free(distr);

  /* Now you can use the generator object `gen' to sample from   */
  /* the distribution. Eg.:                                      */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

Example (String API)

/* ------------------------------------------------------------- */
/* File: example_cont_str.c                                      */
/* ------------------------------------------------------------- */
/* String API.                                                   */
/* ------------------------------------------------------------- */

/* Include UNURAN header file.                                   */
#include <unuran.h>

/* ------------------------------------------------------------- */

/* Example how to sample from a continuous univariate            */
/* distribution.                                                 */

/* We use a generic distribution object and sample.              */
/*                                                               */
/* The PDF of our distribution is given by                       */
/*                                                               */
/*          /  1 - x*x  if |x| <= 1                              */
/*  f(x) = <                                                     */
/*          \  0        otherwise                                */
/*                                                               */

/* ------------------------------------------------------------- */

int main(void)
{
  int    i;     /* loop variable                                 */
  double x;     /* will hold the random number                   */

  /* Declare UNURAN generator object.                            */
  UNUR_GEN   *gen;      /* generator object                      */

  /* Create the generator object.                                */
  /* Use a generic continuous distribution.                      */
  /* Choose a method: TDR.                                       */
  gen = unur_str2gen(
           "distr = cont; pdf=\"1-x*x\"; domain=(-1,1); mode=0. & \
            method=tdr; variant_gw; max_sqhratio=0.90; c=-0.5; \
            max_intervals=100; cpoints=10");

  /* It is important to check if the creation of the generator   */
  /* object was successful. Otherwise `gen' is the NULL pointer  */ 
  /* and would cause a segmentation fault if used for sampling.  */
  if (gen == NULL) {
     fprintf(stderr, "ERROR: cannot create generator object\n");
     exit (EXIT_FAILURE);
  }

  /* Now you can use the generator object `gen' to sample from   */
  /* the distribution. Eg.:                                      */
  for (i=0; i<10; i++) {
    x = unur_sample_cont(gen);
    printf("%f\n",x);
  }

  /* When you do not need the generator object any more, you     */
  /* can destroy it.                                             */
  unur_free(gen);

  exit (EXIT_SUCCESS);

} /* end of main() */

/* ------------------------------------------------------------- */

• AROU – Automatic Ratio-Of-Uniforms method
• ARS – Adaptive Rejection Sampling
• CEXT – wrapper for Continuous EXTernal generators
• CSTD – Continuous STandarD distributions
• HINV – Hermite interpolation based INVersion of CDF
• HRB – Hazard Rate Bounded
• HRD – Hazard Rate Decreasing
• HRI – Hazard Rate Increasing
• ITDR – Inverse Transformed Density Rejection
• NINV – Numerical INVersion
• NROU – Naive Ratio-Of-Uniforms method
• PINV – Polynomial interpolation based INVersion of CDF
• SROU – Simple Ratio-Of-Uniforms method
• SSR – Simple Setup Rejection
• TABL – a TABLe method with piecewise constant hats
• TDR – Transformed Density Rejection
• UTDR – Universal Transformed Density Rejection