1@c automatically generated by `make_texi.pl' 2 3@c ------------------------------------- 4@c top.dh 5@c 6 7@node TOP 8@top UNU.RAN -- Universal Non-Uniform RANdom number generators 9 10@menu 11* Intro:: Introduction 12* Examples:: Examples 13* StringAPI:: String Interface 14* Distribution_objects:: Handling distribution objects 15* Methods:: Methods for generating non-uniform random variates 16* URNG:: Using uniform random number generators 17* Stddist:: UNU.RAN Library of standard distributions 18* Error_Debug:: Error handling and Debugging 19* Testing:: Testing 20* Misc:: Miscelleanous 21* RVG:: A Short Introduction to Random Variate Generation 22* Glossary:: Glossary 23* Bibliography:: Bibliography 24* FIndex:: Function Index 25@end menu 26 27 28@ifinfo 29@noindent 30This is the online-documentation of UNU.RAN.@* 31Version: @value{VERSION}@* 32Date: @value{UPDATED} 33@end ifinfo 34 35 36UNU.RAN (Universal Non-Uniform RAndom Number generator) is 37a collection of algorithms for generating non-uniform 38pseudorandom variates as a library of C functions 39designed and implemented by the ARVAG (Automatic Random VAriate 40Generation) project group in Vienna, and 41released under the GNU Public License (GPL). 42It is especially designed for such situations where 43 44@itemize @minus 45@item a non-standard distribution or a truncated distribution is 46needed. 47 48@item experiments with different types of distributions are made. 49 50@item random variates for variance reduction techniques are used. 51 52@item fast generators of predictable quality are necessary. 53 54@end itemize 55 56Of course it is also well suited for standard distributions. 57However due to its more sophisticated programming interface it 58might not be as easy to use if you only look for a generator for 59the standard normal distribution. (Although UNU.RAN provides 60generators that are superior in many aspects to those found in 61quite a number of other libraries.) 62 63 64 65UNU.RAN implements several methods for generating random numbers. 66The choice depends primary on the information about the 67distribution can be provided and -- if the user is familar with 68the different methods -- on the preferences of the user. 69 70The design goals of UNU.RAN are to provide @emph{reliable}, 71@emph{portable} and @emph{robust} (as far as this is possible) 72functions with a consisent and easy to use interface. It is 73suitable for all situation where experiments with different 74distributions including non-standard distributions. 75For example it is no problem to replace the normal distribution 76by an empirical distribution in a model. 77 78Since originally designed as a library for so called black-box or 79universal algorithms its interface is different from other 80libraries. (Nevertheless it also contains special generators for 81standard distributions.) It does not provide subroutines for 82random variate generation for particular distributions. Instead 83it uses an object-oriented interface. Distributions and 84generators are treated as independent objects. This approach 85allows one not only to have different methods for generating 86non-uniform random variates. It is also possible to choose the 87method which is optimal for a given situation (e.g. speed, quality 88of random numbers, using for variance reduction techniques, 89etc.). It also allows to sample from non-standard distribution or 90even from distributions that arise in a model and can only be 91computed in a complicated subroutine. 92 93Sampling from a particular distribution requires the following steps: 94 95@enumerate 96@item 97Create a distribution object. 98(Objects for standard distributions are available in the library) 99 100@item 101Choose a method. 102 103@item 104Initialize the generator, i.e., create the generator object. 105If the choosen method is not suitable for the given distribution 106(or if the distribution object contains too little information 107about the distribution) the initialization routine fails and 108produces an error message. Thus the generator object does 109(probably) not produce false results (random variates of a 110different distribution). 111 112@item 113Use this generator object to sample from the distribution. 114 115@end enumerate 116 117There are four types of objects that can be manipulated 118independently: 119 120@itemize @bullet 121 122@item 123@strong{Distribution objects:} 124hold all information about the random variates that should be 125generated. The following types of distributions are available: 126 127@itemize @minus 128@item 129Continuous and Discrete distributions 130@item 131Empirical distributions 132@item 133Multivariate distributions 134@end itemize 135 136Of course a library of standard distributions is included 137(and these can be further modified to get, e.g., truncated 138distributions). Moreover the library provides subroutines to 139build almost arbitrary distributions. 140 141@item 142@strong{Generator objects:} 143hold the generators for the given distributions. It is possible 144to build independent generator objects for the same distribution 145object which might use the same or different methods for 146generation. (If the choosen method is not suitable for the given 147method, a @code{NULL} pointer is returned in the initialization step). 148 149@item 150@strong{Parameter objects:} 151Each transformation method requires several parameters to adjust 152the generator to a given distribution. The parameter object holds 153all this information. When created it contains all necessary 154default settings. It is only used to create a generator object 155and destroyed immediately. Altough there is no need to change 156these parameters or even know about their existence for ``usual 157distributions'', they allow a fine tuning of the generator to 158work with distributions with some awkward properties. The library 159provides all necessary functions to change these default 160parameters. 161 162@item 163@strong{Uniform Random Number Generators:} 164All generator objects need one (or more) streams of uniform 165random numbers that are transformed into random variates of the 166given distribution. These are given as pointers to appropriate 167functions or structures (objects). Two generator objects may have 168their own uniform random number generators or share a common 169one. Any functions that produce uniform (pseudo-) random numbers 170can be used. We suggest Otmar Lendl's PRNG library. 171 172@end itemize 173 174 175 176@c 177@c end of top.dh 178@c ------------------------------------- 179@c ------------------------------------- 180@c intro.dh 181@c 182 183@node Intro 184@chapter Introduction 185 186@menu 187* UsageDoc:: Usage of this document 188* Installation:: Installation 189* UsageLib:: Using the library 190* Concepts:: Concepts of UNU.RAN 191* Contact:: Contact the authors 192@end menu 193 194 195@c 196@c end of intro.dh 197@c ------------------------------------- 198@c ------------------------------------- 199@c intro.dh 200@c 201 202@node UsageDoc 203@section Usage of this document 204 205 206We designed this document in a way such that one can 207use UNU.RAN with reading as little as necessary. 208Read @ref{Installation} for the instructions to 209install the library. 210@ref{Concepts,,Concepts of UNU.RAN}, 211discribes the basics of UNU.RAN. 212It also has a short guideline for choosing an appropriate method. 213In @ref{Examples} examples are given that can be copied and modified. 214They also can be found in the directory @file{examples} in the 215source tree. 216 217Further information are given in consecutive chapters. 218@ref{Distribution_objects,,Handling distribution objects}, 219describes how to create and manipulate distribution objects. 220@ref{Stddist,,standard distributions}, 221describes predefined distribution objects that are ready to use. 222@ref{Methods} describes the various methods in detail. 223For each of possible distribution classes 224(continuous, discrete, empirical, multivariate) 225there exists a short overview section that can be used to choose an 226appropriate method followed by sections that describe each of the 227particular methods in detail. 228These are merely for users with some knowledge about 229the methods who want to change method-specific parameters and can 230be ignored by others. 231 232Abbreviations and explanation of some basic terms can be found in 233@ref{Glossary}. 234 235 236@c 237@c end of intro.dh 238@c ------------------------------------- 239@c ------------------------------------- 240@c installation.dh 241@c 242 243@node Installation 244@section Installation 245 246 247UNU.RAN was developed on an Intel architecture under Linux with 248the GNU C compiler but should compile and run on any computing 249environment. It requires an ANSI compliant C compiler. 250 251Below find the installation instructions for unices. 252 253 254@subsubheading Uniform random number generator 255 256UNU.RAN can be used with any uniform random number generator but (at the 257moment) some features work best with Pierre L'Ecuyer's RngStreams library 258(see @url{http://statmath.wu.ac.at/software/RngStreams/} for a 259description and downloading. 260For details on using uniform random number in UNU.RAN 261see @ref{URNG,,Using uniform random number generators}. 262 263Install the required libraries first. 264 265 266@subsubheading UNU.RAN 267 268@enumerate 269 270@item First unzip and untar the package and change to the directory: 271@smallexample 272tar zxvf unuran-@value{VERSION}.tar.gz 273cd unuran-@value{VERSION} 274@end smallexample 275 276@item Optional: Edit the file @file{src/unuran_config.h} 277 278@item Run a configuration script: 279@smallexample 280sh ./configure --prefix=<prefix> 281@end smallexample 282 283where @code{<prefix>} is the root of the installation tree. 284When omitted @file{/usr/local} is used. 285 286Use @code{./configure --help} to get a list of other options. 287In particular the following flags are important: 288 289@itemize @bullet 290@item 291Enable support for some external sources of uniform random 292number generators 293(@pxref{URNG,,Using uniform random number generators}): 294 295@table @code 296@item --with-urng-rngstream 297URNG: use Pierre L'Ecuyer's RNGSTREAM library 298[default=@code{no}] 299 300@item --with-urng-prng 301URNG: use Otmar Lendl's PRNG library 302[default=@code{no}] 303 304@item --with-urng-gsl 305URNG: use random number generators from GNU Scientific Library 306[default=@code{no}] 307 308@item --with-urng-default 309URNG: global default URNG (builtin|rngstream) 310[default=@code{builtin}] 311@end table 312 313We strongly recommend to use RngStreams library: 314@smallexample 315sh ./configure --with-urng-rngstream --with-urng-default=rngstream 316@end smallexample 317 318@emph{Important:} You must install the respective libraries 319@file{RngStreams}, @file{PRNG} and @file{GSL} before 320@code{./configure} is executed. 321 322@item 323Also make a shared library: 324 325@table @code 326@item --enable-shared 327build shared libraries [default=@code{no}] 328@end table 329 330@item 331The library provides the function @code{unur_gen_info} for 332information about generator objects. This is intented for 333using in interactive computing environments. 334This feature can be enabled / disabled by means of the 335configure flag 336 337@table @code 338@item --enable-info 339INFO: provide function with information about 340generator objects [default=@code{yes}] 341@end table 342 343@item 344Enable support for deprecated UNU.RAN routines if you have 345some problems with older application after upgrading the 346library: 347 348@table @code 349@item --enable-deprecated 350enable support for deprecated UNU.RAN routines 351[default=@code{no}] 352@end table 353 354@item 355Enable debugging tools: 356 357@table @code 358@item --enable-check-struct 359Debug: check validity of pointers to structures 360[default=@code{no}] 361 362@item --enable-logging 363Debug: print informations about generator into logfile 364[default=no] 365@end table 366@end itemize 367 368 369@item Compile and install the libray: 370@smallexample 371make 372make install 373@end smallexample 374 375Obviously @code{$(prefix)/include} and @code{$(prefix)/lib} 376must be in the search path of your compiler. You can use environment 377variables to add these directories to the search path. If you 378are using the bash type (or add to your profile): 379@smallexample 380export LIBRARY_PATH="<prefix>/lib" 381export C_INCLURE_PATH="<prefix>/include" 382@end smallexample 383 384If you want to make a shared library, then making such 385a library can be enabled using 386@smallexample 387sh ./configure --enable-shared 388@end smallexample 389If you want to link against the shared library make sure that 390it can be found when executing the binary that links to the 391library. If it is not installed in the usual path, then the 392easiest way is to set the @code{LD_LIBRARY_PATH} environment 393variable. See any operating system documentation about shared 394libraries for more information, such as the ld(1) and 395ld.so(8) manual pages. 396 397@item Documentation in various formats (PDF, HTML, info, plain 398text) can be found in directory @file{doc}. 399 400@item You can run some tests by 401@smallexample 402make check 403@end smallexample 404 405However, some of these tests requires the usage of the PRNG or 406RngStreams library and are only executed if these are installed 407enabled by the corresponding configure flag. 408 409An extended set of tests is run by 410@smallexample 411make fullcheck 412@end smallexample 413 414However some of these might fail occasionally due to 415roundoff errors or the mysteries of floating point arithmetic, 416since we have used some extreme settings to test the library. 417 418@end enumerate 419 420 421@subsubheading Upgrading 422 423@itemize @minus 424@item @emph{Important:} 425 426UNU.RAN now relies on some aspects of IEEE 427754 compliant floating point arithmetic. In particular, 428@code{1./0.} and @code{0./0.} must result in @code{infinity} 429and @code{NaN} (not a number), respectively, and must not 430cause a floating point exception. 431For allmost all modern compting architecture this is implemented 432in hardware. For others there should be a special compiler flag 433to get this feature (e.g., @code{-MIEEE} on DEC alpha or 434@code{-mp} for the Intel C complier). 435 436@item Upgrading UNU.RAN from version 0.9.x or earlier: 437 438With UNU.RAN version 1.0.x some of the macro definitions in 439file @file{src/unuran_config.h} are moved into file 440@file{config.h} and are set/controlled by the 441@code{./configure} script. 442 443Writting logging information into the logfile must now be 444enabled when running the configure script: 445@smallexample 446sh ./configure --enable-logging 447@end smallexample 448 449@item Upgrading UNU.RAN from version 0.7.x or earlier: 450 451With UNU.RAN version 0.8.0 the interface for changing 452underlying distributions and running a reinitialization 453routine has been simplified. The old routines can be compiled 454into the library using the following configure flag: 455@smallexample 456sh ./configure --enable-deprecated 457@end smallexample 458 459Notice: Using these deprecated routines is not supported any 460more and this strong discouraged. 461 462Wrapper functions for external sources of uniform random 463numbers are now enabled by configure flags and not by macros 464defined in file @file{src/unuran_config.h}. 465 466The file @file{src/unuran_config.h} is not installed any 467more. It is now only included when the library is compiled. 468It should be removed from the global include path of the 469compiler. 470 471@end itemize 472 473 474 475@c 476@c end of installation.dh 477@c ------------------------------------- 478@c ------------------------------------- 479@c intro.dh 480@c 481 482@node UsageLib 483@section Using the library 484 485 486 487@subsubheading ANSI C Compliance 488 489The library is written in ANSI C and is intended to conform to the 490ANSI C standard. It should be portable to any system with a 491working ANSI C compiler. 492 493The library does not rely on any non-ANSI extensions in the 494interface it exports to the user. Programs you write using UNU.RAN 495can be ANSI compliant. Extensions which can be used in a way 496compatible with pure ANSI C are supported, however, via conditional 497compilation. This allows the library to take advantage of compiler 498extensions on those platforms which support them. 499 500To avoid namespace conflicts all exported function names and 501variables have the prefix @code{unur_}, while exported macros have 502the prefix @code{UNUR_}. 503 504 505@subsubheading Compiling and Linking 506 507If you want to use the library you must include the UNU.RAN header 508file 509@smallexample 510#include <unuran.h> 511@end smallexample 512If you also need the test routines then also add 513@smallexample 514#include <unuran_tests.h> 515@end smallexample 516If wrapper functions for external sources of uniform random number 517generators are used, the corresponding header files must also be 518included, e.g., 519@smallexample 520#include <unuran_urng_rngstream.h> 521@end smallexample 522 523@noindent 524If these header files are not installed on the standard search path 525of your compiler you will also need to provide its location to the 526preprocessor as a command line flag. The default location of the 527@file{unuran.h} is @file{/usr/local/include}. A typical compilation 528command for a source file @file{app.c} with the GNU C compiler 529@code{gcc} is, 530 531@smallexample 532gcc -I/usr/local/include -c app.c 533@end smallexample 534 535@noindent 536This results in an object file @file{app.o}. The default include 537path for @code{gcc} searches @file{/usr/local/include} 538automatically so the @code{-I} option can be omitted when UNU.RAN is 539installed in its default location. 540 541The library is installed as a single file, @file{libunuran.a}. A 542shared version of the library is also installed on systems that 543support shared libraries. The default location of these files is 544@file{/usr/local/lib}. To link against the library you need to 545specify the main library. The following example shows how to link 546an application with the library (and the the RNGSTREAMS library if you 547decide to use this source of uniform pseudo-random numbers), 548 549@smallexample 550gcc app.o -lunuran -lrngstreams -lm 551@end smallexample 552 553 554@subsubheading Shared Libraries 555 556To run a program linked with the shared version of the library it 557may be necessary to define the shell variable 558@code{LD_LIBRARY_PATH} to include the directory where the library 559is installed. For example, 560 561@smallexample 562LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH 563@end smallexample 564@noindent 565To compile a statically linked version of the program instead, use the 566@code{-static} flag in @code{gcc}, 567 568@smallexample 569gcc -static app.o -lunuran -lrngstreams -lm 570@end smallexample 571 572 573@subsubheading Compatibility with C++ 574 575The library header files automatically define functions to have 576@code{extern "C"} linkage when included in C++ programs. 577 578 579 580 581@c 582@c end of intro.dh 583@c ------------------------------------- 584@c ------------------------------------- 585@c intro.dh 586@c 587 588@node Concepts 589@section Concepts of UNU.RAN 590 591 592UNU.RAN is a C library for generating non-uniformly distributed 593random variates. Its emphasis is on the generation of non-standard 594distribution and on streams of random variates of special purposes. 595It is designed to provide a consistent tool to 596sample from distributions with various properties. 597Since there is no universal method that fits for all situations, 598various methods for sampling are implemented. 599 600UNU.RAN solves this complex task by means of an object oriented 601programming interface. Three basic objects are used: 602 603@itemize @bullet 604@item distribution object @code{UNUR_DISTR}@* 605Hold all information about the random variates that should be 606generated. 607 608@item generator object @code{UNUR_GEN}@* 609Hold the generators for the given distributions. 610Two generator objects are completely independent of each other. 611They may share a common uniform random number generator or have 612their owns. 613 614@item parameter object @code{UNUR_PAR}@* 615Hold all information for creating a generator object. It is 616necessary due to various parameters and switches for each of 617these generation methods. 618 619Notice that the parameter objects only hold pointers to arrays 620but do not have their own copy of such an array. 621Especially, if a dynamically allocated array is used 622it @emph{must not} be freed until the generator object has 623been created! 624 625@end itemize 626 627The idea behind these structures is that creatin distributions, 628choosing a generation method and draing samples are orthogonal 629(ie. independent) functions of the library. 630The parameter object is only introduced due to the necessity to 631deal with various parameters and switches for 632each of these generation methods which are required to adjust the 633algorithms to unusual distributions with extreme properties but 634have default values that are suitable for most applications. 635These parameters and the data for distributions are set by various 636functions. 637 638Once a generator object has been created sampling (from the 639univariate continuous distribution) can be done by 640the following command: 641@example 642double x = unur_sample_cont(generator); 643@end example 644@noindent 645Analogous commands exist for discrete and multivariate 646distributions. 647For detailed examples that can be copied and modified 648see @ref{Examples}. 649 650 651@subheading Distribution objects 652 653All information about a distribution are stored in objects 654(structures) of type @code{UNUR_DISTR}. 655UNU.RAN has five different types of distribution objects: 656 657@table @code 658@item cont 659Continuous univariate distributions. 660@item cvec 661Continuous multivariate distributions. 662@item discr 663Discrete univariate distributions. 664@item cemp 665Continuous empirical univariate distribution, ie. given by a sample. 666@item cvemp 667Continuous empirical multivariate distribution, ie. given by a sample. 668@item matr 669Matrix distributions. 670 671@end table 672 673@noindent 674Distribution objects can be 675created from scratch by the following call 676@example 677distr = unur_distr_<type>_new(); 678@end example 679@noindent 680where @code{<type>} is one of the five possible types from the 681above table. 682Notice that these commands only create an @emph{empty} object which 683still must be filled by means of calls for each type of 684distribution object 685(@pxref{Distribution_objects,,Handling distribution objects}). 686The naming scheme of these functions is designed to indicate the 687corresponding type of the distribution object and the task to be 688performed. It is demonstated on the following example. 689@example 690unur_distr_cont_set_pdf(distr, mypdf); 691@end example 692@noindent 693This command stores a PDF named @code{mypdf} in the distribution 694object @code{distr} which must have the type @code{cont}. 695 696Of course UNU.RAN provides an easier way to use standard distributions. 697Instead of using @command{unur_distr_<type>_new} calls and fuctions 698@command{unur_distr_<type>_set_<@dots{}>} for setting data, 699objects for standard distribution can be created by a single call. 700Eg. to get an object for the normal distribution with mean 2 and 701standard deviation 5 use 702@example 703double parameter[2] = @{2.0 ,5.0@}; 704UNUR_DISTR *distr = unur_distr_normal(parameter, 2); 705@end example 706@noindent 707For a list of standard distributions 708see @ref{Stddist,,Standard distributions}. 709 710 711@subheading Generation methods 712 713The information that a distribution object must contain depends 714heavily on the chosen generation method choosen. 715 716Brackets indicate optional information while a tilde indicates 717that only an approximation must be provided. 718See @ref{Glossary}, for unfamiliar terms. 719 720@sp 1 721@include methods_cont.texi 722 723@sp 1 724@include methods_cemp.texi 725 726@sp 1 727@include methods_cvec.texi 728 729@sp 1 730@include methods_cvemp.texi 731 732@sp 1 733@include methods_discr.texi 734 735@sp 1 736@include methods_matr.texi 737 738@sp 1 739@include methods_mcmc.texi 740 741@sp 2 742 743Because of tremendous variety of possible problems, UNU.RAN provides many 744methods. All information for creating a generator object has to be 745collected in a parameter object first. 746For example, if the task is to sample from a continuous distribution 747the method AROU might be a good choice. Then the call 748@example 749UNUR_PAR *par = unur_arou_new(distribution); 750@end example 751@noindent 752creates an parameter object @code{par} with a pointer to the 753distribution object and default values for all necessary parameters 754for method AROU. 755Other methods can be used by replacing @code{arou} with the name 756of the desired methods (in lower case letters): 757@example 758UNUR_PAR *par = unur_<method>_new(distribution); 759@end example 760@noindent 761This sets the default values for all necessary parameters for the 762chosen method. These are suitable for almost all 763applications. Nevertheless, it is possible to control the behavior 764of the method using corresponding @command{set} calls for each method. 765This might be necessary to adjust the algorithm for an unusual 766distribution with extreme properties, or just for fine tuning the 767perforence of the algorithm. 768The following example demonstrates how to change the maximum 769number of iterations for method NINV to the value 50: 770@example 771unur_ninv_set_max_iteration(par, 50); 772@end example 773All available methods are described in details in 774@ref{Methods}. 775 776 777@subheading Creating a generator object 778 779Now it is possible to create a generator object: 780@example 781UNUR_GEN *generator = unur_init(par); 782if (generator == @code{NULL}) exit(EXIT_FAILURE); 783@end example 784 785@noindent 786@strong{Important:} You must always check whether 787@ifhtml 788@ref{funct:unur_init,@command{unur_init}} 789@end ifhtml 790@ifnothtml 791@command{unur_init} 792@end ifnothtml 793has 794been executed successfully. Otherwise the @code{NULL} pointer is returned 795which causes a segmentation fault when used for sampling. 796 797@noindent 798@strong{Important:} 799The call of 800@ifhtml 801@ref{funct:unur_init,@command{unur_init}} 802@end ifhtml 803@ifnothtml 804@command{unur_init} 805@end ifnothtml 806@strong{destroys} the parameter object!@* 807Moreover, it is recommended to call 808@ifhtml 809@ref{funct:unur_init,@command{unur_init}} 810@end ifhtml 811@ifnothtml 812@command{unur_init} 813@end ifnothtml 814immediately after 815the parameter object @code{par} has created and modified. 816 817@sp 1 818An existing generator object is a rather static construct. 819Nevertheless, some of the parameters can still be modified by 820@command{chg} calls, e.g. 821@example 822unur_ninv_chg_max_iteration(gen, 30); 823@end example 824 825@sp 1 826Notice that it is important @emph{when} parameters are 827changed because different functions must be used: 828 829The function name includes the term @command{set} and the first 830argument must be of type @code{UNUR_PAR} when the parameters are 831changed @emph{before} the generator object is created. 832 833The function name includes the term @command{chg} and the first 834argument must be of type @code{UNUR_GEN} when the parameters are 835changed for an @emph{existing} generator object. 836 837For details see @ref{Methods}. 838 839 840@subheading Sampling 841 842You can now use your generator object in any place of your program 843to sample from your distribution. You only have to take care about 844the type of variates it computes: @code{double}, @code{int} or a 845vector (array of @code{double}s). 846Notice that at this point it does not matter whether you are 847sampling from a gamma distribution, a truncated normal distribution 848or even an empirical distribution. 849 850 851@subheading Reinitializing 852 853It is possible for a generator object to change the parameters and 854the domain of the underlying distribution. This must be done by 855extracting this object by means of a 856@ifhtml 857@ref{funct:unur_get_distr,@command{unur_get_distr}} 858@end ifhtml 859@ifnothtml 860@command{unur_get_distr} 861@end ifnothtml 862call and 863changing the distribution using the correspondig set calls, 864see @ref{Distribution_objects,,Handling distribution objects}. 865The generator object @strong{must} then be reinitialized by means 866of the 867@ifhtml 868@ref{funct:unur_reinit,@command{unur_reinit}} 869@end ifhtml 870@ifnothtml 871@command{unur_reinit} 872@end ifnothtml 873call. 874 875@emph{Important}: Currently not all methods allow reinitialization, 876see the description of the particular method (keyword @i{Reinit}). 877 878 879@subheading Destroy 880 881When you do not need your generator object any more, you should 882destroy it: 883@example 884unur_free(generator); 885@end example 886 887 888@subheading Uniform random numbers 889 890Each generator object can have its own uniform random number 891generator or share one with others. 892When created a parameter object the pointer for the uniform random 893number generator is set to the default generator. However, it can be 894changed at any time to any other generator: 895@example 896unur_set_urng(par, urng); 897@end example 898@noindent 899or 900@example 901unur_chg_urng(generator, urng); 902@end example 903@noindent 904respectively. 905See @ref{URNG,,Using uniform random number generators}, 906for details. 907 908 909 910@c 911@c end of intro.dh 912@c ------------------------------------- 913@c ------------------------------------- 914@c intro.dh 915@c 916 917@node Contact 918@section Contact the authors 919 920 921If you have any problems with UNU.RAN, suggestions how to improve 922the library, or find a bug, please contact us via email 923@email{unuran@@statmath.wu.ac.at}. 924 925For news please visit out homepage at 926@uref{http://statmath.wu.ac.at/unuran/}. 927 928 929 930@c 931@c end of intro.dh 932@c ------------------------------------- 933@c ------------------------------------- 934@c examples.dh 935@c 936 937@node Examples 938@chapter Examples 939 940@menu 941* Example_0:: As short as possible 942* Example_0_str:: As short as possible (String API) 943* Example_1:: Select a method 944* Example_1_str:: Select a method (String API) 945* Example_2:: Arbitrary distributions 946* Example_2_str:: Arbitrary distributions (String API) 947* Example_3:: Change parameters of the method 948* Example_3_str:: Change parameters of the method (String API) 949* Example_4:: Change uniform random generator 950* Example_anti:: Sample pairs of antithetic random variates 951* Example_anti_str:: Sample pairs of antithetic random variates (String API) 952* Example_More:: More examples 953@end menu 954 955 956 957The examples in this chapter should compile cleanly and can be 958found in the directory @file{examples} of the source tree of 959UNU.RAN. Assuming that UNU.RAN as well as the PRNG libraries 960have been installed properly (@pxref{Installation}) each 961of these can be compiled (using the GCC in this example) with 962@example 963gcc -Wall -O2 -o example example.c -lunuran -lprng -lm 964@end example 965@noindent 966@emph{Remark:} @code{-lprng} must be omitted when the PRNG library 967is not installed. Then however some of the examples might not work. 968 969The library uses three objects: 970@code{UNUR_DISTR}, @code{UNUR_PAR} and @code{UNUR_GEN}. 971It is not important to understand the details of these objects but 972it is important not to changed the order of their creation. 973The distribution object can be destroyed @emph{after} the generator 974object has been made. (The parameter object is freed automatically 975by the 976@ifhtml 977@ref{funct:unur_init,@command{unur_init}} 978@end ifhtml 979@ifnothtml 980@command{unur_init} 981@end ifnothtml 982call.) It is also important to check the result 983of the 984@ifhtml 985@ref{funct:unur_init,@command{unur_init}} 986@end ifhtml 987@ifnothtml 988@command{unur_init} 989@end ifnothtml 990call. If it has failed the @code{NULL} pointer is 991returned and causes a segmentation fault when used for sampling. 992 993We give all examples with the UNU.RAN standard API and the more 994convenient string API. 995 996 997 998@c 999@c end of examples.dh 1000@c ------------------------------------- 1001@c ------------------------------------- 1002@c examples.dh 1003@c 1004 1005@page 1006@node Example_0 1007@section As short as possible 1008 1009 1010 1011Select a distribution and let UNU.RAN do all necessary steps. 1012 1013@smallexample 1014@include ref_example0.texi 1015@end smallexample 1016 1017 1018 1019@c 1020@c end of examples.dh 1021@c ------------------------------------- 1022@c ------------------------------------- 1023@c examples.dh 1024@c 1025 1026@page 1027@node Example_0_str 1028@section As short as possible (String API) 1029 1030 1031 1032Select a distribution and let UNU.RAN do all necessary steps. 1033 1034@smallexample 1035@include ref_example0_str.texi 1036@end smallexample 1037 1038 1039 1040@c 1041@c end of examples.dh 1042@c ------------------------------------- 1043@c ------------------------------------- 1044@c examples.dh 1045@c 1046 1047@page 1048@node Example_1 1049@section Select a method 1050 1051 1052 1053Select method AROU and use it with default parameters. 1054 1055@smallexample 1056@include ref_example1.texi 1057@end smallexample 1058 1059 1060 1061@c 1062@c end of examples.dh 1063@c ------------------------------------- 1064@c ------------------------------------- 1065@c examples.dh 1066@c 1067 1068@page 1069@node Example_1_str 1070@section Select a method (String API) 1071 1072 1073 1074Select method AROU and use it with default parameters. 1075 1076@smallexample 1077@include ref_example1_str.texi 1078@end smallexample 1079 1080 1081 1082@c 1083@c end of examples.dh 1084@c ------------------------------------- 1085@c ------------------------------------- 1086@c examples.dh 1087@c 1088 1089@page 1090@node Example_2 1091@section Arbitrary distributions 1092 1093 1094 1095If you want to sample from a non-standard distribution, 1096UNU.RAN might be exactly what you need. 1097Depending on the information is available, a method 1098must be choosen for sampling, 1099see @ref{Concepts} for an overview and 1100@ref{Methods} for details. 1101 1102@smallexample 1103@include ref_example2.texi 1104@end smallexample 1105 1106 1107 1108@c 1109@c end of examples.dh 1110@c ------------------------------------- 1111@c ------------------------------------- 1112@c examples.dh 1113@c 1114 1115@page 1116@node Example_2_str 1117@section Arbitrary distributions (String API) 1118 1119 1120 1121If you want to sample from a non-standard distribution, 1122UNU.RAN might be exactly what you need. 1123Depending on the information is available, a method 1124must be choosen for sampling, 1125see @ref{Concepts} for an overview and 1126@ref{Methods} for details. 1127 1128@smallexample 1129@include ref_example2_str.texi 1130@end smallexample 1131 1132 1133 1134@c 1135@c end of examples.dh 1136@c ------------------------------------- 1137@c ------------------------------------- 1138@c examples.dh 1139@c 1140 1141@page 1142@node Example_3 1143@section Change parameters of the method 1144 1145 1146 1147Each method for generating random numbers allows several 1148parameters to be modified. If you do not want to use default values, 1149it is possible to change them. 1150The following example illustrates how to change parameters. 1151For details see @ref{Methods}. 1152 1153@smallexample 1154@include ref_example3.texi 1155@end smallexample 1156 1157 1158 1159@c 1160@c end of examples.dh 1161@c ------------------------------------- 1162@c ------------------------------------- 1163@c examples.dh 1164@c 1165 1166@page 1167@node Example_3_str 1168@section Change parameters of the method (String API) 1169 1170 1171 1172Each method for generating random numbers allows several 1173parameters to be modified. If you do not want to use default values, 1174it is possible to change them. 1175The following example illustrates how to change parameters. 1176For details see @ref{Methods}. 1177 1178@smallexample 1179@include ref_example3_str.texi 1180@end smallexample 1181 1182 1183 1184@c 1185@c end of examples.dh 1186@c ------------------------------------- 1187@c ------------------------------------- 1188@c examples.dh 1189@c 1190 1191@page 1192@node Example_4 1193@section Change uniform random generator 1194 1195 1196 1197All generator object use the same default uniform random number 1198generator by default. This can be changed to any generator of your 1199choice such that each generator object has its own random number 1200generator or can share it with some other objects. 1201It is also possible to change the default generator at any time. 1202See @ref{URNG,,Using uniform random number generators}, 1203for details. 1204 1205The following example shows how the uniform random number generator 1206can be set or changed for a generator object. It requires the 1207RNGSTREAMS library to be installed and used. Otherwise the example must be 1208modified accordingly. 1209 1210@smallexample 1211@include ref_example_rngstreams.texi 1212@end smallexample 1213 1214 1215 1216@c 1217@c end of examples.dh 1218@c ------------------------------------- 1219@c ------------------------------------- 1220@c examples.dh 1221@c 1222 1223@page 1224@node Example_anti 1225@section Sample pairs of antithetic random variates 1226 1227 1228Using Method TDR it is easy to sample pairs of antithetic random variates. 1229 1230@smallexample 1231@include ref_example_anti.texi 1232@end smallexample 1233 1234 1235 1236@c 1237@c end of examples.dh 1238@c ------------------------------------- 1239@c ------------------------------------- 1240@c examples.dh 1241@c 1242 1243@page 1244@node Example_anti_str 1245@section Sample pairs of antithetic random variates (String API) 1246 1247 1248Using Method TDR it is easy to sample pairs of antithetic random variates. 1249 1250@smallexample 1251@include ref_example_anti_str.texi 1252@end smallexample 1253 1254 1255 1256@c 1257@c end of examples.dh 1258@c ------------------------------------- 1259@c ------------------------------------- 1260@c examples.dh 1261@c 1262 1263@page 1264@node Example_More 1265@section More examples 1266 1267 1268 1269@xref{Methods_for_CONT,,Methods for continuous univariate distributions}. 1270 1271@xref{Methods_for_CEMP,,Methods for continuous empirical univariate distributions}. 1272 1273@xref{Methods_for_CVEMP,,Methods for continuous empirical multivariate distributions}. 1274 1275@xref{Methods_for_DISCR,,Methods for discrete univariate distributions}. 1276 1277 1278 1279@c 1280@c end of examples.dh 1281@c ------------------------------------- 1282@c ------------------------------------- 1283@c parser.h 1284@c 1285 1286@node StringAPI 1287@chapter String Interface 1288 1289@menu 1290* StringSyntax:: Syntax of String Interface 1291* StringDistr:: Distribution String 1292* StringFunct:: Function String 1293* StringMethod:: Method String 1294* StringURNG:: Uniform RNG String 1295@end menu 1296 1297 1298 1299The string interface (string API) provided by the 1300@ifhtml 1301@ref{funct:unur_str2gen,@command{unur_str2gen}} 1302@end ifhtml 1303@ifnothtml 1304@command{unur_str2gen} 1305@end ifnothtml 1306call is the easiest way to use UNU.RAN. This 1307function takes a character string as its argument. The string is 1308parsed and the information obtained is used to create a generator 1309object. It returns @code{NULL} if this fails, either due to a syntax 1310error, or due to invalid data. In both cases @code{unur_error} is 1311set to the corresponding error codes 1312(@pxref{Error_reporting,,Error reporting}). 1313Additionally there exists the call 1314@ifhtml 1315@ref{funct:unur_str2distr,@command{unur_str2distr}} 1316@end ifhtml 1317@ifnothtml 1318@command{unur_str2distr} 1319@end ifnothtml 1320that only 1321produces a distribution object. 1322 1323Notice that the string interface does not implement all features of 1324the UNU.RAN library. For trickier tasks it might be necessary to use 1325the UNU.RAN calls. 1326 1327In @ref{Examples}, all examples are given using both the 1328UNU.RAN standard API and this convenient string API. 1329The corresponding programm codes are equivalent. 1330 1331 1332@subheading Function reference 1333 1334@ifhtml 1335@itemize 1336@item @ref{funct:unur_str2gen,unur_str2gen} 1337@item @ref{funct:unur_str2distr,unur_str2distr} 1338@item @ref{funct:unur_makegen_ssu,unur_makegen_ssu} 1339@item @ref{funct:unur_makegen_dsu,unur_makegen_dsu} 1340@end itemize 1341@end ifhtml 1342 1343 1344@ifinfo 1345@anchor{funct:unur_str2gen} 1346@deftypefn Function {UNUR_GEN*} unur_str2gen (const @var{char* string}) 1347Get a generator object for the distribution, method and uniform 1348random number generator as described in the given @var{string}. 1349See @ref{StringSyntax,,Syntax of String Interface}, for details. 1350@end deftypefn 1351@end ifinfo 1352@ifnotinfo 1353@anchor{funct:unur_str2gen} 1354@deftypefn {} {UNUR_GEN*} unur_str2gen (const @var{char* string}) 1355Get a generator object for the distribution, method and uniform 1356random number generator as described in the given @var{string}. 1357See @ref{StringSyntax,,Syntax of String Interface}, for details. 1358@end deftypefn 1359@end ifnotinfo 1360 1361@ifinfo 1362@anchor{funct:unur_str2distr} 1363@deftypefn Function {UNUR_DISTR*} unur_str2distr (const @var{char* string}) 1364Get a distribution object for the distribution described in 1365@var{string}. 1366See @ref{StringSyntax,,Syntax of String Interface}, 1367and @ref{StringDistr,,Distribution String}, 1368for details. However, only the block for the distribution object is 1369allowed. 1370@end deftypefn 1371@end ifinfo 1372@ifnotinfo 1373@anchor{funct:unur_str2distr} 1374@deftypefn {} {UNUR_DISTR*} unur_str2distr (const @var{char* string}) 1375Get a distribution object for the distribution described in 1376@var{string}. 1377See @ref{StringSyntax,,Syntax of String Interface}, 1378and @ref{StringDistr,,Distribution String}, 1379for details. However, only the block for the distribution object is 1380allowed. 1381@end deftypefn 1382@end ifnotinfo 1383 1384@ifinfo 1385@anchor{funct:unur_makegen_ssu} 1386@deftypefn Function {UNUR_GEN*} unur_makegen_ssu (const @var{char* distrstr}, const @var{char* methodstr}, UNUR_URNG* @var{urng}) 1387@anchor{funct:unur_makegen_dsu} 1388@deftypefnx Function {UNUR_GEN*} unur_makegen_dsu (const @var{UNUR_DISTR* distribution}, const @var{char* methodstr}, UNUR_URNG* @var{urng}) 1389Make a generator object for the distribution, method and uniform 1390random number generator. The distribution can be given either as 1391string @var{distrstr} or as a distribution object @var{distr}. 1392The method must be given as a string @var{methodstr}. 1393For the syntax of these strings see 1394@ref{StringSyntax,,Syntax of String Interface}. 1395However, the @code{method} keyword is optional for these calls 1396and can be omitted. If @var{methodstr} is the empty (blank) string 1397or @code{NULL} method AUTO is used. 1398The uniform random number generator is optional. If 1399@var{urng} is @code{NULL} then the default uniform random number generator 1400is used. 1401@end deftypefn 1402@end ifinfo 1403@ifnotinfo 1404@anchor{funct:unur_makegen_ssu} 1405@deftypefn {} {UNUR_GEN*} unur_makegen_ssu (const @var{char* distrstr}, const @var{char* methodstr}, UNUR_URNG* @var{urng}) 1406@anchor{funct:unur_makegen_dsu} 1407@deftypefnx {} {UNUR_GEN*} unur_makegen_dsu (const @var{UNUR_DISTR* distribution}, const @var{char* methodstr}, UNUR_URNG* @var{urng}) 1408Make a generator object for the distribution, method and uniform 1409random number generator. The distribution can be given either as 1410string @var{distrstr} or as a distribution object @var{distr}. 1411The method must be given as a string @var{methodstr}. 1412For the syntax of these strings see 1413@ref{StringSyntax,,Syntax of String Interface}. 1414However, the @code{method} keyword is optional for these calls 1415and can be omitted. If @var{methodstr} is the empty (blank) string 1416or @code{NULL} method AUTO is used. 1417The uniform random number generator is optional. If 1418@var{urng} is @code{NULL} then the default uniform random number generator 1419is used. 1420@end deftypefn 1421@end ifnotinfo 1422 1423 1424 1425 1426@c 1427@c end of parser.h 1428@c ------------------------------------- 1429@c ------------------------------------- 1430@c parser.h 1431@c 1432 1433@node StringSyntax 1434@section Syntax of String Interface 1435 1436 1437 1438The given string holds information about the requested distribution 1439and (optional) about the sampling method and the uniform random 1440number generator invoked. The interpretation of the string is not 1441case-sensitive, all white spaces are ignored. 1442 1443The string consists of up to three blocks, separated by ampersands 1444@code{&}. 1445 1446Each block consists of @code{<key>=<value>} pairs, separated by 1447semicolons @code{;}. 1448 1449The first key in each block is used to indicate each block. 1450We have three different blocks with the following (first) keys: 1451@table @code 1452@item distr 1453definition of the distribution 1454(@pxref{StringDistr,,Distribution String}). 1455 1456@item method 1457description of the transformation method 1458(@pxref{StringMethod,,Method String}). 1459 1460@item urng 1461uniform random number generation 1462(@pxref{StringURNG,,Uniform RNG String}). 1463@end table 1464 1465The @code{distr} block must be the very first block and is 1466obligatory. All the other blocks are optional and can be arranged 1467in arbitrary order. 1468 1469For details see the following description of each block. 1470 1471In the following example 1472@smallexample 1473distr = normal(3.,0.75); domain = (0,inf) & method = tdr; c = 0 1474@end smallexample 1475we have a distribution block for the truncated normal distribution 1476with mean 3 and standard deviation 0.75 on domain (0,infinity); 1477and block for choosing method TDR with parameter c set to 0. 1478 1479@sp 1 1480The @code{<key>=<value>} pairs that follow the first (initial) pair 1481in each block are used to set parameters. 1482The name of the parameter is given by the @code{<key>} string. It is 1483deduced from the UNU.RAN set calls by taking the part after 1484@code{@dots{}_set_}. 1485The @code{<value>} string holds the parameters to be 1486set, separated by commata @code{,}. 1487There are three types of parameters: 1488@table @emph 1489@item string @code{"@dots{}"} 1490i.e. any sequence of characters enclosed by double quotes 1491@code{"@dots{}"}, 1492@item list @code{(@dots{},@dots{})} 1493i.e. list of @emph{numbers}, separated by commata @code{,}, 1494enclosed in parenthesis @code{(...)}, and 1495@item number 1496a sequence of characters that is not enclosed by quotes 1497@code{"@dots{}"} or parenthesis @code{(...)}. 1498It is interpreted as float or integer depending on the type of 1499the corresponding parameter. 1500@end table 1501The @code{<value>} string (including the character @code{=}) can be 1502omitted when no argument is required. 1503 1504At the moment not all @command{set} calls are supported. 1505The syntax for the @code{<value>} can be directly derived from the 1506corresponding @command{set} calls. To simplify the syntax additional 1507shortcuts are possible. The following table lists the parameters for 1508the @code{set} calls that are supported by the string interface; the 1509entry in parenthesis gives the type of the argument as 1510@code{<value>} string: 1511 1512@table @code 1513@item int @i{(number)}: 1514The @i{number} is interpreted as an integer. 1515@code{true} and @code{on} are transformed to @code{1}, 1516@code{false} and @code{off} are transformed to @code{0}. 1517A missing argument is interpreted as @code{1}. 1518 1519@item int, int @i{(number, number} @r{or} @i{list)}: 1520The two numbers or the first two entries in the list are 1521interpreted as a integers. 1522@code{inf} and @code{-inf} are transformed to @code{INT_MAX} and 1523@code{INT_MIN} respectively, i.e. the largest and smallest 1524integers that can be represented by the computer. 1525 1526@item unsigned @i{(number)}: 1527The @i{number} is interpreted as an unsigned hexadecimal 1528integer. 1529 1530@item double @i{(number)}: 1531The number is interpreted as a floating point number. 1532@code{inf} is transformed to @code{UNUR_INFINITY}. 1533 1534@item double, double @i{(number, number} @r{or} @i{list)}: 1535The two numbers or the first two entries in the list are 1536interpreted as a floating point numbers. 1537@code{inf} is transformed to @code{UNUR_INFINITY}. However using 1538@code{inf} in the list might not work for all versions of C. Then it 1539is recommended to use two single numbers instead of a list. 1540 1541@item int, double* @i{([number,] list} @r{or} @i{number)}: 1542@itemize @minus 1543@item 1544The list is interpreted as a double array. 1545The (first) number as its length. 1546If it is less than the actual size of the array only the 1547first entries of the array are used. 1548@item 1549If only the list is given (i.e., if the first number is omitted), 1550the first number is set to the actual size of the array. 1551@item 1552If only the number is given (i.e., if the list is omitted), the @code{NULL} 1553pointer is used instead an array as argument. 1554@end itemize 1555 1556@item double*, int @i{(list [,number])}: 1557The list is interpreted as a double array. 1558The (second) number as its length. 1559If the length is omitted, it is replaced by the actual size of the 1560array. (Only in the @code{distribution} block!) 1561 1562@item char* @i{(string)}: 1563The character string is passed as is to the corresponding set 1564call. 1565 1566@end table 1567 1568Notice that missing entries in a list of numbers are interpreted as 1569@code{0}. E.g, a the list @code{(1,,3)} is read as @code{(1,0,3)}, the 1570list @code{(1,2,)} as @code{(1,2,0)}. 1571 1572The the list of @code{key} strings in 1573@ref{KeysDistr,,Keys for Distribution String}, and 1574@ref{KeysMethod,,Keys for Method String}, for further details. 1575 1576 1577 1578@c 1579@c end of parser.h 1580@c ------------------------------------- 1581@c ------------------------------------- 1582@c parser.h 1583@c 1584 1585@page 1586@node StringDistr 1587@section Distribution String 1588 1589@menu 1590* KeysDistr:: Keys for Distribution String 1591@end menu 1592 1593 1594 1595The @code{distr} block must be the very first block and is 1596obligatory. For that reason the keyword @code{distr} is optional and 1597can be omitted (together with the @code{=} character). 1598Moreover it is ignored while parsing the string. However, to 1599avoid some possible confusion it has to start with the 1600letter @code{d} (if it is given at all). 1601 1602The value of the @code{distr} key is used to get the distribution 1603object, either via a @command{unur_distr_<value>} call for a standard 1604distribution via a @command{unur_distr_<value>_new} call to get an 1605object of a generic distribution. 1606However not all generic distributions are supported yet. 1607 1608The parameters for the standard distribution are given 1609as a list. There must not be any character (other than white space) 1610between the name of the standard distribution and the opening 1611parenthesis @code{(} of this list. E.g., to get a beta distribution, 1612use 1613@smallexample 1614distr = beta(2,4) 1615@end smallexample 1616 1617To get an object for a discrete distribution with probability 1618vector (0.5,0.2,0.3), use 1619@smallexample 1620distr = discr; pv = (0.5,0.2,0.3) 1621@end smallexample 1622 1623It is also possible to set a PDF, PMF, or CDF using a string. 1624E.g., to create a continuous distribution with PDF proportional to 1625@code{exp(-sqrt(2+(x-1)^2) + (x-1))} and domain (0,inf) use 1626@smallexample 1627distr = cont; pdf = "exp(-sqrt(2+(x-1)^2) + (x-1))" 1628@end smallexample 1629Notice: If this string is used in an 1630@ifhtml 1631@ref{funct:unur_str2distr,@command{unur_str2distr}} 1632@end ifhtml 1633@ifnothtml 1634@command{unur_str2distr} 1635@end ifnothtml 1636or 1637@ifhtml 1638@ref{funct:unur_str2gen,@command{unur_str2gen}} 1639@end ifhtml 1640@ifnothtml 1641@command{unur_str2gen} 1642@end ifnothtml 1643call the double quotes @code{"} must be protected by 1644@code{\"}. Alternatively, single quotes may be used instead 1645@smallexample 1646distr = cont; pdf = 'exp(-sqrt(2+(x-1)^2) + (x-1))' 1647@end smallexample 1648 1649For the details of function strings see 1650@ref{StringFunct,,Function String}. 1651 1652 1653 1654@c 1655@c end of parser.h 1656@c ------------------------------------- 1657@c ------------------------------------- 1658@c stringparser_doc.dh 1659@c 1660 1661@node KeysDistr 1662@subsection Keys for Distribution String 1663 1664 1665 1666List of standard distributions @pxref{Stddist,,Standard distributions} 1667 1668@itemize @minus 1669@item @code{[distr =] beta(@dots{})} @ @ @ @ @result{} @pxref{beta} 1670@item @code{[distr =] binomial(@dots{})} @ @ @ @ @result{} @pxref{binomial} 1671@item @code{[distr =] cauchy(@dots{})} @ @ @ @ @result{} @pxref{cauchy} 1672@item @code{[distr =] chi(@dots{})} @ @ @ @ @result{} @pxref{chi} 1673@item @code{[distr =] chisquare(@dots{})} @ @ @ @ @result{} @pxref{chisquare} 1674@item @code{[distr =] exponential(@dots{})} @ @ @ @ @result{} @pxref{exponential} 1675@item @code{[distr =] extremeI(@dots{})} @ @ @ @ @result{} @pxref{extremeI} 1676@item @code{[distr =] extremeII(@dots{})} @ @ @ @ @result{} @pxref{extremeII} 1677@item @code{[distr =] F(@dots{})} @ @ @ @ @result{} @pxref{F} 1678@item @code{[distr =] gamma(@dots{})} @ @ @ @ @result{} @pxref{gamma} 1679@item @code{[distr =] geometric(@dots{})} @ @ @ @ @result{} @pxref{geometric} 1680@item @code{[distr =] gig(@dots{})} @ @ @ @ @result{} @pxref{gig} 1681@item @code{[distr =] gig2(@dots{})} @ @ @ @ @result{} @pxref{gig2} 1682@item @code{[distr =] hyperbolic(@dots{})} @ @ @ @ @result{} @pxref{hyperbolic} 1683@item @code{[distr =] hypergeometric(@dots{})} @ @ @ @ @result{} @pxref{hypergeometric} 1684@item @code{[distr =] ig(@dots{})} @ @ @ @ @result{} @pxref{ig} 1685@item @code{[distr =] laplace(@dots{})} @ @ @ @ @result{} @pxref{laplace} 1686@item @code{[distr =] logarithmic(@dots{})} @ @ @ @ @result{} @pxref{logarithmic} 1687@item @code{[distr =] logistic(@dots{})} @ @ @ @ @result{} @pxref{logistic} 1688@item @code{[distr =] lognormal(@dots{})} @ @ @ @ @result{} @pxref{lognormal} 1689@item @code{[distr =] lomax(@dots{})} @ @ @ @ @result{} @pxref{lomax} 1690@item @code{[distr =] negativebinomial(@dots{})} @ @ @ @ @result{} @pxref{negativebinomial} 1691@item @code{[distr =] normal(@dots{})} @ @ @ @ @result{} @pxref{normal} 1692@item @code{[distr =] pareto(@dots{})} @ @ @ @ @result{} @pxref{pareto} 1693@item @code{[distr =] poisson(@dots{})} @ @ @ @ @result{} @pxref{poisson} 1694@item @code{[distr =] powerexponential(@dots{})} @ @ @ @ @result{} @pxref{powerexponential} 1695@item @code{[distr =] rayleigh(@dots{})} @ @ @ @ @result{} @pxref{rayleigh} 1696@item @code{[distr =] slash(@dots{})} @ @ @ @ @result{} @pxref{slash} 1697@item @code{[distr =] student(@dots{})} @ @ @ @ @result{} @pxref{student} 1698@item @code{[distr =] triangular(@dots{})} @ @ @ @ @result{} @pxref{triangular} 1699@item @code{[distr =] uniform(@dots{})} @ @ @ @ @result{} @pxref{uniform} 1700@item @code{[distr =] weibull(@dots{})} @ @ @ @ @result{} @pxref{weibull} 1701@end itemize 1702 1703@sp 1 1704List of generic distributions @pxref{Distribution_objects,,Handling Distribution Objects} 1705 1706@itemize @minus 1707@item @code{[distr =] cemp} @ @ @ @ @result{} @pxref{CEMP} 1708@item @code{[distr =] cont} @ @ @ @ @result{} @pxref{CONT} 1709@item @code{[distr =] discr} @ @ @ @ @result{} @pxref{DISCR} 1710@end itemize 1711 1712@sp 1 1713@emph{Notice}: 1714Order statistics for continuous distributions (@pxref{CORDER}) are 1715supported by using the key @code{orderstatistics} for distributions 1716of type @code{CONT}. 1717 1718@sp 1 1719 1720List of keys that are available via the String API. 1721For description see the corresponding UNU.RAN set calls. 1722 1723@itemize @bullet 1724@item All distribution types 1725@table @code 1726@item name = "@i{<string>}" 1727@result{} @pxref{funct:unur_distr_set_name,,@command{unur_distr_set_name}} 1728@end table 1729 1730@sp 1 1731@item @code{cemp} @ @i{(Distribution Type)}@ @ @ @ (@pxref{CEMP}) 1732@table @code 1733@item data = (@i{<list>}) [, @i{<int>}] 1734@result{} @pxref{funct:unur_distr_cemp_set_data,,@command{unur_distr_cemp_set_data}} 1735@item hist_bins = (@i{<list>}) [, @i{<int>}] 1736@result{} @pxref{funct:unur_distr_cemp_set_hist_bins,,@command{unur_distr_cemp_set_hist_bins}} 1737@item hist_domain = @i{<double>}, @i{<double>} | (@i{<list>}) 1738@result{} @pxref{funct:unur_distr_cemp_set_hist_domain,,@command{unur_distr_cemp_set_hist_domain}} 1739@item hist_prob = (@i{<list>}) [, @i{<int>}] 1740@result{} @pxref{funct:unur_distr_cemp_set_hist_prob,,@command{unur_distr_cemp_set_hist_prob}} 1741@end table 1742 1743@sp 1 1744@item @code{cont} @ @i{(Distribution Type)}@ @ @ @ (@pxref{CONT}) 1745@table @code 1746@item cdf = "@i{<string>}" 1747@result{} @pxref{funct:unur_distr_cont_set_cdfstr,,@command{unur_distr_cont_set_cdfstr}} 1748@item center = @i{<double>} 1749@result{} @pxref{funct:unur_distr_cont_set_center,,@command{unur_distr_cont_set_center}} 1750@item domain = @i{<double>}, @i{<double>} | (@i{<list>}) 1751@result{} @pxref{funct:unur_distr_cont_set_domain,,@command{unur_distr_cont_set_domain}} 1752@item hr = "@i{<string>}" 1753@result{} @pxref{funct:unur_distr_cont_set_hrstr,,@command{unur_distr_cont_set_hrstr}} 1754@item logcdf = "@i{<string>}" 1755@result{} @pxref{funct:unur_distr_cont_set_logcdfstr,,@command{unur_distr_cont_set_logcdfstr}} 1756@item logpdf = "@i{<string>}" 1757@result{} @pxref{funct:unur_distr_cont_set_logpdfstr,,@command{unur_distr_cont_set_logpdfstr}} 1758@item mode = @i{<double>} 1759@result{} @pxref{funct:unur_distr_cont_set_mode,,@command{unur_distr_cont_set_mode}} 1760@item pdf = "@i{<string>}" 1761@result{} @pxref{funct:unur_distr_cont_set_pdfstr,,@command{unur_distr_cont_set_pdfstr}} 1762@item pdfarea = @i{<double>} 1763@result{} @pxref{funct:unur_distr_cont_set_pdfarea,,@command{unur_distr_cont_set_pdfarea}} 1764@item pdfparams = (@i{<list>}) [, @i{<int>}] 1765@result{} @pxref{funct:unur_distr_cont_set_pdfparams,,@command{unur_distr_cont_set_pdfparams}} 1766@item orderstatistics = @i{<int>}, @i{<int>} | (@i{<list>}) 1767Make order statistics for given distribution. The first parameter 1768gives the sample size, the second parameter its rank. 1769(see @pxref{funct:unur_distr_corder_new,,@command{unur_distr_corder_new}}) 1770@end table 1771 1772@sp 1 1773@item @code{discr} @ @i{(Distribution Type)}@ @ @ @ (@pxref{DISCR}) 1774@table @code 1775@item cdf = "@i{<string>}" 1776@result{} @pxref{funct:unur_distr_discr_set_cdfstr,,@command{unur_distr_discr_set_cdfstr}} 1777@item domain = @i{<int>}, @i{<int>} | (@i{<list>}) 1778@result{} @pxref{funct:unur_distr_discr_set_domain,,@command{unur_distr_discr_set_domain}} 1779@item mode [= @i{<int>}] 1780@result{} @pxref{funct:unur_distr_discr_set_mode,,@command{unur_distr_discr_set_mode}} 1781@item pmf = "@i{<string>}" 1782@result{} @pxref{funct:unur_distr_discr_set_pmfstr,,@command{unur_distr_discr_set_pmfstr}} 1783@item pmfparams = (@i{<list>}) [, @i{<int>}] 1784@result{} @pxref{funct:unur_distr_discr_set_pmfparams,,@command{unur_distr_discr_set_pmfparams}} 1785@item pmfsum = @i{<double>} 1786@result{} @pxref{funct:unur_distr_discr_set_pmfsum,,@command{unur_distr_discr_set_pmfsum}} 1787@item pv = (@i{<list>}) [, @i{<int>}] 1788@result{} @pxref{funct:unur_distr_discr_set_pv,,@command{unur_distr_discr_set_pv}} 1789@end table 1790 1791@sp 1 1792@end itemize 1793 1794 1795 1796 1797@c 1798@c end of stringparser_doc.dh 1799@c ------------------------------------- 1800@c ------------------------------------- 1801@c functparser_doc.dh 1802@c 1803 1804@page 1805@node StringFunct 1806@section Function String 1807 1808 1809 1810In unuran it is also possible to define functions (e.g. CDF or PDF) as 1811strings. As you can see in Example 2 (@ref{Example_2_str}) it is very 1812easy to define the PDF of a distribution object by means of a string. 1813The possibilities using this string interface are more restricted than 1814using a pointer to a routine coded in C (@ref{Example_2}). 1815But the differences in evaluation time is small. 1816When a distribution object is defined using this string interface then 1817of course the same conditions on the given density or CDF must be 1818satisfied for a chosen method as for the standard API. 1819This string interface can be used for both within the UNU.RAN string 1820API using the 1821@ifhtml 1822@ref{funct:unur_str2gen,@command{unur_str2gen}} 1823@end ifhtml 1824@ifnothtml 1825@command{unur_str2gen} 1826@end ifnothtml 1827call, and for calls that define the 1828density or CDF for a particular distribution object as done with 1829(e.g.) the call 1830@ifhtml 1831@ref{funct:unur_distr_cont_set_pdfstr,@command{unur_distr_cont_set_pdfstr}.} 1832@end ifhtml 1833@ifnothtml 1834@command{unur_distr_cont_set_pdfstr}. 1835@end ifnothtml 1836Here is an example for the latter case: 1837 1838@smallexample 1839unur_distr_cont_set_pdfstr(distr,"1-x*x"); 1840@end smallexample 1841 1842 1843@subheading Syntax 1844 1845The syntax for the function string is case insensitive, white spaces 1846are ingnored. The expressions are similar to most programming languages 1847and mathematical programs (see also the examples below). It is especially 1848influenced by C. The usual preceedence rules are used (from highest 1849to lowest preceedence: functions, power, multiplication, 1850addition, relation operators). Use parentheses in case of doubt or 1851when these preceedences should be changed. 1852 1853Relation operators can be used as indicator functions, i.e. the term 1854@code{(x>1)} is evaluted as @code{1} if this relation is satisfied, 1855and as @code{0} otherwise. 1856 1857The first unknown symbol (letter or word) is interpreted as the 1858variable of the function. It is recommended to use @code{x}. 1859Only one variable can be used. 1860 1861@sp 1 1862@noindent 1863@emph{Important}: The symbol @code{e} is used twice, for Euler's 1864constant (= 2.7182@dots{}) and as exponent. 1865The multiplication operator @code{*} must not be omitted, i.e. 1866@code{2 x} is interpreted as the string @code{2x} (which will result 1867in a syntax error). 1868 1869 1870@subheading List of symbols 1871 1872@cartouche 1873@noindent 1874@b{Numbers} 1875@sp 1 1876@noindent 1877Numbers are composed using digits and, optionally, a sign, 1878a decimal point, and an exponent indicated by @code{e}. 1879@sp 1 1880@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 1881@item Symbol @tab Explanation @tab Examples 1882@item @code{0@dots{}9} @tab @i{digits} @tab @code{2343} 1883@item @code{.} @tab @i{decimal point} @tab @code{165.567} 1884@item @code{-} @tab @i{negative sign} @tab @code{-465.223} 1885@item @code{e} @tab @i{exponet} @tab @code{13.2e-4} (=0.00132) 1886@end multitable 1887@end cartouche 1888 1889@sp 1 1890@cartouche 1891@noindent 1892@b{Constants} 1893@sp 1 1894@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 1895@item @code{pi} @tab @i{pi = 3.1415@dots{}} @tab @code{3*pi+2} 1896@item @code{e} @tab @i{Euler's constant} @tab @code{3*e+2} (= 10.15@dots{}; 1897do not cofuse with @code{3e2} = 300) 1898@item @code{inf} @tab @i{infinity} @tab (used for domains) 1899@end multitable 1900@end cartouche 1901 1902@sp 1 1903@cartouche 1904@noindent 1905@b{Special symbols} 1906@sp 1 1907@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 1908@item @code{(} @tab @i{opening parenthesis} @tab @code{2*(3+x)} 1909@item @code{)} @tab @i{closing parenthesis} @tab @code{2*(3+x)} 1910@item @code{,} @tab @i{(argument) list separator} @tab @code{mod(13,2)} 1911@end multitable 1912@end cartouche 1913 1914@sp 1 1915@cartouche 1916@noindent 1917@b{Relation operators (Indicator functions)} 1918@sp 1 1919@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 1920@item @code{<} @tab @i{less than} @tab @code{(x<1)} 1921@item @code{=} @tab @i{equal} @tab @code{(2=x)} 1922@item @code{==} @tab @i{same as} @code{=} @tab @code{(x==3)} 1923@item @code{>} @tab @i{greater than} @tab @code{(x>0)} 1924@item @code{<=} @tab @i{less than or equal} @tab @code{(x<=1)} 1925@item @code{!=} @tab @i{not equal} @tab @code{(x!0)} 1926@item @code{<>} @tab @i{same as} @code{!=} @tab @code{(x<>pi)} 1927@item @code{>=} @tab @i{greater or equal} @tab @code{(x>=1)} 1928@end multitable 1929@end cartouche 1930 1931@sp 1 1932@cartouche 1933@noindent 1934@b{Arithmetic operators} 1935@sp 1 1936@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 1937@item @code{+} @tab @i{addition} @tab @code{2+x} 1938@item @code{-} @tab @i{subtraction} @tab @code{2-x} 1939@item @code{*} @tab @i{multiplication} @tab @code{2*x} 1940@item @code{/} @tab @i{division} @tab @code{x/2} 1941@item @code{^} @tab @i{power} @tab @code{x^2} 1942@end multitable 1943@end cartouche 1944 1945@sp 1 1946@cartouche 1947@noindent 1948@b{Functions} 1949@sp 1 1950@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 1951@item @code{mod} @tab @code{mod(m,n)} @i{remainder of devision m over n} @tab mod(x,2) 1952@item @code{exp} @tab @i{exponential function 1953(same as @code{e^x})} @tab @code{exp(-x^2)} (same as @code{e^(-x^2)}) 1954@item @code{log} @tab @i{natural logarithm} @tab @code{log(x)} 1955@item @code{sin} @tab @i{sine} @tab @code{sin(x)} 1956@item @code{cos} @tab @i{cosine} @tab @code{cos(x)} 1957@item @code{tan} @tab @i{tangent} @tab @code{tan(x)} 1958@item @code{sec} @tab @i{secant} @tab @code{sec(x*2)} 1959@item @code{sqrt} @tab @i{square root} @tab @code{sqrt(2*x)} 1960@item @code{abs} @tab @i{absolute value} @tab @code{abs(x)} 1961@item @code{sgn} @tab @i{sign function} @tab @code{sign(x)*3} 1962@end multitable 1963@end cartouche 1964 1965@sp 1 1966@cartouche 1967@noindent 1968@b{Variable} 1969@sp 1 1970@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 1971@item @code{x} @tab @i{variable} @tab @code{3*x^2} 1972@end multitable 1973@end cartouche 1974 1975 1976@subheading Examples 1977 1978@example 1979 19801.231+7.9876*x-1.234e-3*x^2+3.335e-5*x^3 1981 1982sin(2*pi*x)+x^2 1983 1984exp(-((x-3)/2.1)^2) 1985 1986@end example 1987 1988@noindent 1989It is also possible to define functions using different terms 1990on separate domains. However, instead of constructs using 1991@code{if @dots{} then @dots{} else @dots{}} 1992indicator functions are available. 1993 1994@noindent 1995For example to define the density of triangular distribution 1996with domain (-1,1) and mode 0 use 1997 1998@example 1999(x>-1)*(x<0)*(1+x) + (x>=0)*(x<1)*(1-x) 2000@end example 2001 2002 2003 2004@c 2005@c end of functparser_doc.dh 2006@c ------------------------------------- 2007@c ------------------------------------- 2008@c parser.h 2009@c 2010 2011@page 2012@node StringMethod 2013@section Method String 2014 2015@menu 2016* KeysMethod:: Keys for Method String 2017@end menu 2018 2019 2020 2021The key @code{method} is obligatory, it must be the first key and its 2022value is the name of a method suitable for the choosen standard 2023distribution. E.g., if method AROU is chosen, use 2024@smallexample 2025method = arou 2026@end smallexample 2027 2028Of course the all following keys dependend on the method choosen at 2029first. All corresponding @command{set} calls of UNU.RAN are available 2030and the key is the string after the @command{unur_<methodname>_set_} 2031part of the command. E.g., UNU.RAN provides the command 2032@command{unur_arou_set_max_sqhratio} to set a parameter of method AROU. 2033To call this function via the string-interface, the 2034key @code{max_sqhratio} can be used: 2035@smallexample 2036max_sqhratio = 0.9 2037@end smallexample 2038Additionally the keyword @code{debug} can be used to set debugging 2039flags (see @ref{Debug,,Debugging}, for details). 2040 2041If this block is omitted, a suitable default method is used. Notice 2042however that the default method may change in future versions of 2043UNU.RAN. 2044 2045 2046 2047@c 2048@c end of parser.h 2049@c ------------------------------------- 2050@c ------------------------------------- 2051@c stringparser_doc.dh 2052@c 2053 2054@node KeysMethod 2055@subsection Keys for Method String 2056 2057 2058 2059List of methods and keys that are available via the String API. 2060For description see the corresponding UNU.RAN set calls. 2061 2062@itemize @bullet 2063@item @code{method = arou} @ @ @ @ @result{} @command{unur_arou_new} 2064(@pxref{AROU}) 2065@table @code 2066@item cpoints = @i{<int>} [, (@i{<list>})] | (@i{<list>}) 2067@result{} @pxref{funct:unur_arou_set_cpoints,,@command{unur_arou_set_cpoints}} 2068@item darsfactor = @i{<double>} 2069@result{} @pxref{funct:unur_arou_set_darsfactor,,@command{unur_arou_set_darsfactor}} 2070@item guidefactor = @i{<double>} 2071@result{} @pxref{funct:unur_arou_set_guidefactor,,@command{unur_arou_set_guidefactor}} 2072@item max_segments [= @i{<int>}] 2073@result{} @pxref{funct:unur_arou_set_max_segments,,@command{unur_arou_set_max_segments}} 2074@item max_sqhratio = @i{<double>} 2075@result{} @pxref{funct:unur_arou_set_max_sqhratio,,@command{unur_arou_set_max_sqhratio}} 2076@item pedantic [= @i{<int>}] 2077@result{} @pxref{funct:unur_arou_set_pedantic,,@command{unur_arou_set_pedantic}} 2078@item usecenter [= @i{<int>}] 2079@result{} @pxref{funct:unur_arou_set_usecenter,,@command{unur_arou_set_usecenter}} 2080@item usedars [= @i{<int>}] 2081@result{} @pxref{funct:unur_arou_set_usedars,,@command{unur_arou_set_usedars}} 2082@item verify [= @i{<int>}] 2083@result{} @pxref{funct:unur_arou_set_verify,,@command{unur_arou_set_verify}} 2084@end table 2085 2086@sp 1 2087@item @code{method = ars} @ @ @ @ @result{} @command{unur_ars_new} 2088(@pxref{ARS}) 2089@table @code 2090@item cpoints = @i{<int>} [, (@i{<list>})] | (@i{<list>}) 2091@result{} @pxref{funct:unur_ars_set_cpoints,,@command{unur_ars_set_cpoints}} 2092@item max_intervals [= @i{<int>}] 2093@result{} @pxref{funct:unur_ars_set_max_intervals,,@command{unur_ars_set_max_intervals}} 2094@item max_iter [= @i{<int>}] 2095@result{} @pxref{funct:unur_ars_set_max_iter,,@command{unur_ars_set_max_iter}} 2096@item pedantic [= @i{<int>}] 2097@result{} @pxref{funct:unur_ars_set_pedantic,,@command{unur_ars_set_pedantic}} 2098@item reinit_ncpoints [= @i{<int>}] 2099@result{} @pxref{funct:unur_ars_set_reinit_ncpoints,,@command{unur_ars_set_reinit_ncpoints}} 2100@item reinit_percentiles = @i{<int>} [, (@i{<list>})] | (@i{<list>}) 2101@result{} @pxref{funct:unur_ars_set_reinit_percentiles,,@command{unur_ars_set_reinit_percentiles}} 2102@item verify [= @i{<int>}] 2103@result{} @pxref{funct:unur_ars_set_verify,,@command{unur_ars_set_verify}} 2104@end table 2105 2106@sp 1 2107@item @code{method = auto} @ @ @ @ @result{} @command{unur_auto_new} 2108(@pxref{AUTO}) 2109@table @code 2110@item logss [= @i{<int>}] 2111@result{} @pxref{funct:unur_auto_set_logss,,@command{unur_auto_set_logss}} 2112@end table 2113 2114@sp 1 2115@item @code{method = cstd} @ @ @ @ @result{} @command{unur_cstd_new} 2116(@pxref{CSTD}) 2117@table @code 2118@item variant = @i{<unsigned>} 2119@result{} @pxref{funct:unur_cstd_set_variant,,@command{unur_cstd_set_variant}} 2120@end table 2121 2122@sp 1 2123@item @code{method = dari} @ @ @ @ @result{} @command{unur_dari_new} 2124(@pxref{DARI}) 2125@table @code 2126@item cpfactor = @i{<double>} 2127@result{} @pxref{funct:unur_dari_set_cpfactor,,@command{unur_dari_set_cpfactor}} 2128@item squeeze [= @i{<int>}] 2129@result{} @pxref{funct:unur_dari_set_squeeze,,@command{unur_dari_set_squeeze}} 2130@item tablesize [= @i{<int>}] 2131@result{} @pxref{funct:unur_dari_set_tablesize,,@command{unur_dari_set_tablesize}} 2132@item verify [= @i{<int>}] 2133@result{} @pxref{funct:unur_dari_set_verify,,@command{unur_dari_set_verify}} 2134@end table 2135 2136@sp 1 2137@item @code{method = dau} @ @ @ @ @result{} @command{unur_dau_new} 2138(@pxref{DAU}) 2139@table @code 2140@item urnfactor = @i{<double>} 2141@result{} @pxref{funct:unur_dau_set_urnfactor,,@command{unur_dau_set_urnfactor}} 2142@end table 2143 2144@sp 1 2145@item @code{method = dgt} @ @ @ @ @result{} @command{unur_dgt_new} 2146(@pxref{DGT}) 2147@table @code 2148@item guidefactor = @i{<double>} 2149@result{} @pxref{funct:unur_dgt_set_guidefactor,,@command{unur_dgt_set_guidefactor}} 2150@item variant = @i{<unsigned>} 2151@result{} @pxref{funct:unur_dgt_set_variant,,@command{unur_dgt_set_variant}} 2152@end table 2153 2154@sp 1 2155@item @code{method = dsrou} @ @ @ @ @result{} @command{unur_dsrou_new} 2156(@pxref{DSROU}) 2157@table @code 2158@item cdfatmode = @i{<double>} 2159@result{} @pxref{funct:unur_dsrou_set_cdfatmode,,@command{unur_dsrou_set_cdfatmode}} 2160@item verify [= @i{<int>}] 2161@result{} @pxref{funct:unur_dsrou_set_verify,,@command{unur_dsrou_set_verify}} 2162@end table 2163 2164@sp 1 2165@item @code{method = dstd} @ @ @ @ @result{} @command{unur_dstd_new} 2166(@pxref{DSTD}) 2167@table @code 2168@item variant = @i{<unsigned>} 2169@result{} @pxref{funct:unur_dstd_set_variant,,@command{unur_dstd_set_variant}} 2170@end table 2171 2172@sp 1 2173@item @code{method = empk} @ @ @ @ @result{} @command{unur_empk_new} 2174(@pxref{EMPK}) 2175@table @code 2176@item beta = @i{<double>} 2177@result{} @pxref{funct:unur_empk_set_beta,,@command{unur_empk_set_beta}} 2178@item kernel = @i{<unsigned>} 2179@result{} @pxref{funct:unur_empk_set_kernel,,@command{unur_empk_set_kernel}} 2180@item positive [= @i{<int>}] 2181@result{} @pxref{funct:unur_empk_set_positive,,@command{unur_empk_set_positive}} 2182@item smoothing = @i{<double>} 2183@result{} @pxref{funct:unur_empk_set_smoothing,,@command{unur_empk_set_smoothing}} 2184@item varcor [= @i{<int>}] 2185@result{} @pxref{funct:unur_empk_set_varcor,,@command{unur_empk_set_varcor}} 2186@end table 2187 2188@sp 1 2189@item @code{method = gibbs} @ @ @ @ @result{} @command{unur_gibbs_new} 2190(@pxref{GIBBS}) 2191@table @code 2192@item burnin [= @i{<int>}] 2193@result{} @pxref{funct:unur_gibbs_set_burnin,,@command{unur_gibbs_set_burnin}} 2194@item c = @i{<double>} 2195@result{} @pxref{funct:unur_gibbs_set_c,,@command{unur_gibbs_set_c}} 2196@item thinning [= @i{<int>}] 2197@result{} @pxref{funct:unur_gibbs_set_thinning,,@command{unur_gibbs_set_thinning}} 2198@item variant_coordinate 2199@result{} @pxref{funct:unur_gibbs_set_variant_coordinate,,@command{unur_gibbs_set_variant_coordinate}} 2200@item variant_random_direction 2201@result{} @pxref{funct:unur_gibbs_set_variant_random_direction,,@command{unur_gibbs_set_variant_random_direction}} 2202@end table 2203 2204@sp 1 2205@item @code{method = hinv} @ @ @ @ @result{} @command{unur_hinv_new} 2206(@pxref{HINV}) 2207@table @code 2208@item boundary = @i{<double>}, @i{<double>} | (@i{<list>}) 2209@result{} @pxref{funct:unur_hinv_set_boundary,,@command{unur_hinv_set_boundary}} 2210@item cpoints = (@i{<list>}), @i{<int>} 2211@result{} @pxref{funct:unur_hinv_set_cpoints,,@command{unur_hinv_set_cpoints}} 2212@item guidefactor = @i{<double>} 2213@result{} @pxref{funct:unur_hinv_set_guidefactor,,@command{unur_hinv_set_guidefactor}} 2214@item max_intervals [= @i{<int>}] 2215@result{} @pxref{funct:unur_hinv_set_max_intervals,,@command{unur_hinv_set_max_intervals}} 2216@item order [= @i{<int>}] 2217@result{} @pxref{funct:unur_hinv_set_order,,@command{unur_hinv_set_order}} 2218@item u_resolution = @i{<double>} 2219@result{} @pxref{funct:unur_hinv_set_u_resolution,,@command{unur_hinv_set_u_resolution}} 2220@end table 2221 2222@sp 1 2223@item @code{method = hitro} @ @ @ @ @result{} @command{unur_hitro_new} 2224(@pxref{HITRO}) 2225@table @code 2226@item adaptive_multiplier = @i{<double>} 2227@result{} @pxref{funct:unur_hitro_set_adaptive_multiplier,,@command{unur_hitro_set_adaptive_multiplier}} 2228@item burnin [= @i{<int>}] 2229@result{} @pxref{funct:unur_hitro_set_burnin,,@command{unur_hitro_set_burnin}} 2230@item r = @i{<double>} 2231@result{} @pxref{funct:unur_hitro_set_r,,@command{unur_hitro_set_r}} 2232@item thinning [= @i{<int>}] 2233@result{} @pxref{funct:unur_hitro_set_thinning,,@command{unur_hitro_set_thinning}} 2234@item use_adaptiveline [= @i{<int>}] 2235@result{} @pxref{funct:unur_hitro_set_use_adaptiveline,,@command{unur_hitro_set_use_adaptiveline}} 2236@item use_adaptiverectangle [= @i{<int>}] 2237@result{} @pxref{funct:unur_hitro_set_use_adaptiverectangle,,@command{unur_hitro_set_use_adaptiverectangle}} 2238@item use_boundingrectangle [= @i{<int>}] 2239@result{} @pxref{funct:unur_hitro_set_use_boundingrectangle,,@command{unur_hitro_set_use_boundingrectangle}} 2240@item v = @i{<double>} 2241@result{} @pxref{funct:unur_hitro_set_v,,@command{unur_hitro_set_v}} 2242@item variant_coordinate 2243@result{} @pxref{funct:unur_hitro_set_variant_coordinate,,@command{unur_hitro_set_variant_coordinate}} 2244@item variant_random_direction 2245@result{} @pxref{funct:unur_hitro_set_variant_random_direction,,@command{unur_hitro_set_variant_random_direction}} 2246@end table 2247 2248@sp 1 2249@item @code{method = hrb} @ @ @ @ @result{} @command{unur_hrb_new} 2250(@pxref{HRB}) 2251@table @code 2252@item upperbound = @i{<double>} 2253@result{} @pxref{funct:unur_hrb_set_upperbound,,@command{unur_hrb_set_upperbound}} 2254@item verify [= @i{<int>}] 2255@result{} @pxref{funct:unur_hrb_set_verify,,@command{unur_hrb_set_verify}} 2256@end table 2257 2258@sp 1 2259@item @code{method = hrd} @ @ @ @ @result{} @command{unur_hrd_new} 2260(@pxref{HRD}) 2261@table @code 2262@item verify [= @i{<int>}] 2263@result{} @pxref{funct:unur_hrd_set_verify,,@command{unur_hrd_set_verify}} 2264@end table 2265 2266@sp 1 2267@item @code{method = hri} @ @ @ @ @result{} @command{unur_hri_new} 2268(@pxref{HRI}) 2269@table @code 2270@item p0 = @i{<double>} 2271@result{} @pxref{funct:unur_hri_set_p0,,@command{unur_hri_set_p0}} 2272@item verify [= @i{<int>}] 2273@result{} @pxref{funct:unur_hri_set_verify,,@command{unur_hri_set_verify}} 2274@end table 2275 2276@sp 1 2277@item @code{method = itdr} @ @ @ @ @result{} @command{unur_itdr_new} 2278(@pxref{ITDR}) 2279@table @code 2280@item cp = @i{<double>} 2281@result{} @pxref{funct:unur_itdr_set_cp,,@command{unur_itdr_set_cp}} 2282@item ct = @i{<double>} 2283@result{} @pxref{funct:unur_itdr_set_ct,,@command{unur_itdr_set_ct}} 2284@item verify [= @i{<int>}] 2285@result{} @pxref{funct:unur_itdr_set_verify,,@command{unur_itdr_set_verify}} 2286@item xi = @i{<double>} 2287@result{} @pxref{funct:unur_itdr_set_xi,,@command{unur_itdr_set_xi}} 2288@end table 2289 2290@sp 1 2291@item @code{method = mvtdr} @ @ @ @ @result{} @command{unur_mvtdr_new} 2292(@pxref{MVTDR}) 2293@table @code 2294@item boundsplitting = @i{<double>} 2295@result{} @pxref{funct:unur_mvtdr_set_boundsplitting,,@command{unur_mvtdr_set_boundsplitting}} 2296@item maxcones [= @i{<int>}] 2297@result{} @pxref{funct:unur_mvtdr_set_maxcones,,@command{unur_mvtdr_set_maxcones}} 2298@item stepsmin [= @i{<int>}] 2299@result{} @pxref{funct:unur_mvtdr_set_stepsmin,,@command{unur_mvtdr_set_stepsmin}} 2300@item verify [= @i{<int>}] 2301@result{} @pxref{funct:unur_mvtdr_set_verify,,@command{unur_mvtdr_set_verify}} 2302@end table 2303 2304@sp 1 2305@item @code{method = ninv} @ @ @ @ @result{} @command{unur_ninv_new} 2306(@pxref{NINV}) 2307@table @code 2308@item max_iter [= @i{<int>}] 2309@result{} @pxref{funct:unur_ninv_set_max_iter,,@command{unur_ninv_set_max_iter}} 2310@item start = @i{<double>}, @i{<double>} | (@i{<list>}) 2311@result{} @pxref{funct:unur_ninv_set_start,,@command{unur_ninv_set_start}} 2312@item table [= @i{<int>}] 2313@result{} @pxref{funct:unur_ninv_set_table,,@command{unur_ninv_set_table}} 2314@item u_resolution = @i{<double>} 2315@result{} @pxref{funct:unur_ninv_set_u_resolution,,@command{unur_ninv_set_u_resolution}} 2316@item usebisect 2317@result{} @pxref{funct:unur_ninv_set_usebisect,,@command{unur_ninv_set_usebisect}} 2318@item usenewton 2319@result{} @pxref{funct:unur_ninv_set_usenewton,,@command{unur_ninv_set_usenewton}} 2320@item useregula 2321@result{} @pxref{funct:unur_ninv_set_useregula,,@command{unur_ninv_set_useregula}} 2322@item x_resolution = @i{<double>} 2323@result{} @pxref{funct:unur_ninv_set_x_resolution,,@command{unur_ninv_set_x_resolution}} 2324@end table 2325 2326@sp 1 2327@item @code{method = nrou} @ @ @ @ @result{} @command{unur_nrou_new} 2328(@pxref{NROU}) 2329@table @code 2330@item center = @i{<double>} 2331@result{} @pxref{funct:unur_nrou_set_center,,@command{unur_nrou_set_center}} 2332@item r = @i{<double>} 2333@result{} @pxref{funct:unur_nrou_set_r,,@command{unur_nrou_set_r}} 2334@item u = @i{<double>}, @i{<double>} | (@i{<list>}) 2335@result{} @pxref{funct:unur_nrou_set_u,,@command{unur_nrou_set_u}} 2336@item v = @i{<double>} 2337@result{} @pxref{funct:unur_nrou_set_v,,@command{unur_nrou_set_v}} 2338@item verify [= @i{<int>}] 2339@result{} @pxref{funct:unur_nrou_set_verify,,@command{unur_nrou_set_verify}} 2340@end table 2341 2342@sp 1 2343@item @code{method = pinv} @ @ @ @ @result{} @command{unur_pinv_new} 2344(@pxref{PINV}) 2345@table @code 2346@item boundary = @i{<double>}, @i{<double>} | (@i{<list>}) 2347@result{} @pxref{funct:unur_pinv_set_boundary,,@command{unur_pinv_set_boundary}} 2348@item keepcdf [= @i{<int>}] 2349@result{} @pxref{funct:unur_pinv_set_keepcdf,,@command{unur_pinv_set_keepcdf}} 2350@item max_intervals [= @i{<int>}] 2351@result{} @pxref{funct:unur_pinv_set_max_intervals,,@command{unur_pinv_set_max_intervals}} 2352@item order [= @i{<int>}] 2353@result{} @pxref{funct:unur_pinv_set_order,,@command{unur_pinv_set_order}} 2354@item searchboundary = @i{<int>}, @i{<int>} | (@i{<list>}) 2355@result{} @pxref{funct:unur_pinv_set_searchboundary,,@command{unur_pinv_set_searchboundary}} 2356@item smoothness [= @i{<int>}] 2357@result{} @pxref{funct:unur_pinv_set_smoothness,,@command{unur_pinv_set_smoothness}} 2358@item u_resolution = @i{<double>} 2359@result{} @pxref{funct:unur_pinv_set_u_resolution,,@command{unur_pinv_set_u_resolution}} 2360@item use_upoints [= @i{<int>}] 2361@result{} @pxref{funct:unur_pinv_set_use_upoints,,@command{unur_pinv_set_use_upoints}} 2362@item usecdf 2363@result{} @pxref{funct:unur_pinv_set_usecdf,,@command{unur_pinv_set_usecdf}} 2364@item usepdf 2365@result{} @pxref{funct:unur_pinv_set_usepdf,,@command{unur_pinv_set_usepdf}} 2366@end table 2367 2368@sp 1 2369@item @code{method = srou} @ @ @ @ @result{} @command{unur_srou_new} 2370(@pxref{SROU}) 2371@table @code 2372@item cdfatmode = @i{<double>} 2373@result{} @pxref{funct:unur_srou_set_cdfatmode,,@command{unur_srou_set_cdfatmode}} 2374@item pdfatmode = @i{<double>} 2375@result{} @pxref{funct:unur_srou_set_pdfatmode,,@command{unur_srou_set_pdfatmode}} 2376@item r = @i{<double>} 2377@result{} @pxref{funct:unur_srou_set_r,,@command{unur_srou_set_r}} 2378@item usemirror [= @i{<int>}] 2379@result{} @pxref{funct:unur_srou_set_usemirror,,@command{unur_srou_set_usemirror}} 2380@item usesqueeze [= @i{<int>}] 2381@result{} @pxref{funct:unur_srou_set_usesqueeze,,@command{unur_srou_set_usesqueeze}} 2382@item verify [= @i{<int>}] 2383@result{} @pxref{funct:unur_srou_set_verify,,@command{unur_srou_set_verify}} 2384@end table 2385 2386@sp 1 2387@item @code{method = ssr} @ @ @ @ @result{} @command{unur_ssr_new} 2388(@pxref{SSR}) 2389@table @code 2390@item cdfatmode = @i{<double>} 2391@result{} @pxref{funct:unur_ssr_set_cdfatmode,,@command{unur_ssr_set_cdfatmode}} 2392@item pdfatmode = @i{<double>} 2393@result{} @pxref{funct:unur_ssr_set_pdfatmode,,@command{unur_ssr_set_pdfatmode}} 2394@item usesqueeze [= @i{<int>}] 2395@result{} @pxref{funct:unur_ssr_set_usesqueeze,,@command{unur_ssr_set_usesqueeze}} 2396@item verify [= @i{<int>}] 2397@result{} @pxref{funct:unur_ssr_set_verify,,@command{unur_ssr_set_verify}} 2398@end table 2399 2400@sp 1 2401@item @code{method = tabl} @ @ @ @ @result{} @command{unur_tabl_new} 2402(@pxref{TABL}) 2403@table @code 2404@item areafraction = @i{<double>} 2405@result{} @pxref{funct:unur_tabl_set_areafraction,,@command{unur_tabl_set_areafraction}} 2406@item boundary = @i{<double>}, @i{<double>} | (@i{<list>}) 2407@result{} @pxref{funct:unur_tabl_set_boundary,,@command{unur_tabl_set_boundary}} 2408@item cpoints = @i{<int>} [, (@i{<list>})] | (@i{<list>}) 2409@result{} @pxref{funct:unur_tabl_set_cpoints,,@command{unur_tabl_set_cpoints}} 2410@item darsfactor = @i{<double>} 2411@result{} @pxref{funct:unur_tabl_set_darsfactor,,@command{unur_tabl_set_darsfactor}} 2412@item guidefactor = @i{<double>} 2413@result{} @pxref{funct:unur_tabl_set_guidefactor,,@command{unur_tabl_set_guidefactor}} 2414@item max_intervals [= @i{<int>}] 2415@result{} @pxref{funct:unur_tabl_set_max_intervals,,@command{unur_tabl_set_max_intervals}} 2416@item max_sqhratio = @i{<double>} 2417@result{} @pxref{funct:unur_tabl_set_max_sqhratio,,@command{unur_tabl_set_max_sqhratio}} 2418@item nstp [= @i{<int>}] 2419@result{} @pxref{funct:unur_tabl_set_nstp,,@command{unur_tabl_set_nstp}} 2420@item pedantic [= @i{<int>}] 2421@result{} @pxref{funct:unur_tabl_set_pedantic,,@command{unur_tabl_set_pedantic}} 2422@item slopes = (@i{<list>}), @i{<int>} 2423@result{} @pxref{funct:unur_tabl_set_slopes,,@command{unur_tabl_set_slopes}} 2424@item usedars [= @i{<int>}] 2425@result{} @pxref{funct:unur_tabl_set_usedars,,@command{unur_tabl_set_usedars}} 2426@item useear [= @i{<int>}] 2427@result{} @pxref{funct:unur_tabl_set_useear,,@command{unur_tabl_set_useear}} 2428@item variant_ia [= @i{<int>}] 2429@result{} @pxref{funct:unur_tabl_set_variant_ia,,@command{unur_tabl_set_variant_ia}} 2430@item variant_splitmode = @i{<unsigned>} 2431@result{} @pxref{funct:unur_tabl_set_variant_splitmode,,@command{unur_tabl_set_variant_splitmode}} 2432@item verify [= @i{<int>}] 2433@result{} @pxref{funct:unur_tabl_set_verify,,@command{unur_tabl_set_verify}} 2434@end table 2435 2436@sp 1 2437@item @code{method = tdr} @ @ @ @ @result{} @command{unur_tdr_new} 2438(@pxref{TDR}) 2439@table @code 2440@item c = @i{<double>} 2441@result{} @pxref{funct:unur_tdr_set_c,,@command{unur_tdr_set_c}} 2442@item cpoints = @i{<int>} [, (@i{<list>})] | (@i{<list>}) 2443@result{} @pxref{funct:unur_tdr_set_cpoints,,@command{unur_tdr_set_cpoints}} 2444@item darsfactor = @i{<double>} 2445@result{} @pxref{funct:unur_tdr_set_darsfactor,,@command{unur_tdr_set_darsfactor}} 2446@item guidefactor = @i{<double>} 2447@result{} @pxref{funct:unur_tdr_set_guidefactor,,@command{unur_tdr_set_guidefactor}} 2448@item max_intervals [= @i{<int>}] 2449@result{} @pxref{funct:unur_tdr_set_max_intervals,,@command{unur_tdr_set_max_intervals}} 2450@item max_sqhratio = @i{<double>} 2451@result{} @pxref{funct:unur_tdr_set_max_sqhratio,,@command{unur_tdr_set_max_sqhratio}} 2452@item pedantic [= @i{<int>}] 2453@result{} @pxref{funct:unur_tdr_set_pedantic,,@command{unur_tdr_set_pedantic}} 2454@item reinit_ncpoints [= @i{<int>}] 2455@result{} @pxref{funct:unur_tdr_set_reinit_ncpoints,,@command{unur_tdr_set_reinit_ncpoints}} 2456@item reinit_percentiles = @i{<int>} [, (@i{<list>})] | (@i{<list>}) 2457@result{} @pxref{funct:unur_tdr_set_reinit_percentiles,,@command{unur_tdr_set_reinit_percentiles}} 2458@item usecenter [= @i{<int>}] 2459@result{} @pxref{funct:unur_tdr_set_usecenter,,@command{unur_tdr_set_usecenter}} 2460@item usedars [= @i{<int>}] 2461@result{} @pxref{funct:unur_tdr_set_usedars,,@command{unur_tdr_set_usedars}} 2462@item usemode [= @i{<int>}] 2463@result{} @pxref{funct:unur_tdr_set_usemode,,@command{unur_tdr_set_usemode}} 2464@item variant_gw 2465@result{} @pxref{funct:unur_tdr_set_variant_gw,,@command{unur_tdr_set_variant_gw}} 2466@item variant_ia 2467@result{} @pxref{funct:unur_tdr_set_variant_ia,,@command{unur_tdr_set_variant_ia}} 2468@item variant_ps 2469@result{} @pxref{funct:unur_tdr_set_variant_ps,,@command{unur_tdr_set_variant_ps}} 2470@item verify [= @i{<int>}] 2471@result{} @pxref{funct:unur_tdr_set_verify,,@command{unur_tdr_set_verify}} 2472@end table 2473 2474@sp 1 2475@item @code{method = utdr} @ @ @ @ @result{} @command{unur_utdr_new} 2476(@pxref{UTDR}) 2477@table @code 2478@item cpfactor = @i{<double>} 2479@result{} @pxref{funct:unur_utdr_set_cpfactor,,@command{unur_utdr_set_cpfactor}} 2480@item deltafactor = @i{<double>} 2481@result{} @pxref{funct:unur_utdr_set_deltafactor,,@command{unur_utdr_set_deltafactor}} 2482@item pdfatmode = @i{<double>} 2483@result{} @pxref{funct:unur_utdr_set_pdfatmode,,@command{unur_utdr_set_pdfatmode}} 2484@item verify [= @i{<int>}] 2485@result{} @pxref{funct:unur_utdr_set_verify,,@command{unur_utdr_set_verify}} 2486@end table 2487 2488@sp 1 2489@item @code{method = vempk} @ @ @ @ @result{} @command{unur_vempk_new} 2490(@pxref{VEMPK}) 2491@table @code 2492@item smoothing = @i{<double>} 2493@result{} @pxref{funct:unur_vempk_set_smoothing,,@command{unur_vempk_set_smoothing}} 2494@item varcor [= @i{<int>}] 2495@result{} @pxref{funct:unur_vempk_set_varcor,,@command{unur_vempk_set_varcor}} 2496@end table 2497 2498@sp 1 2499@item @code{method = vnrou} @ @ @ @ @result{} @command{unur_vnrou_new} 2500(@pxref{VNROU}) 2501@table @code 2502@item r = @i{<double>} 2503@result{} @pxref{funct:unur_vnrou_set_r,,@command{unur_vnrou_set_r}} 2504@item v = @i{<double>} 2505@result{} @pxref{funct:unur_vnrou_set_v,,@command{unur_vnrou_set_v}} 2506@item verify [= @i{<int>}] 2507@result{} @pxref{funct:unur_vnrou_set_verify,,@command{unur_vnrou_set_verify}} 2508@end table 2509 2510@sp 1 2511@end itemize 2512 2513 2514 2515 2516@c 2517@c end of stringparser_doc.dh 2518@c ------------------------------------- 2519@c ------------------------------------- 2520@c parser.h 2521@c 2522 2523@page 2524@node StringURNG 2525@section Uniform RNG String 2526 2527 2528 2529The value of the @code{urng} key is passed to the PRNG interface (see 2530@ifinfo 2531@xref{Top,,Overview,prng,PRNG Manual}. 2532@end ifinfo 2533@ifnotinfo 2534@uref{http://statmath.wu.ac.at/prng/manual/,PRNG manual} 2535@end ifnotinfo 2536for details). 2537However it only works when using the PRNG library is enabled, 2538see @ref{Installation} for details. There are no other keys. 2539 2540IMPORTANT: UNU.RAN creates a new uniform random number generator for 2541the generator object. The pointer to this uniform generator 2542has to be read and saved via a 2543@ifhtml 2544@ref{funct:unur_get_urng,@command{unur_get_urng}} 2545@end ifhtml 2546@ifnothtml 2547@command{unur_get_urng} 2548@end ifnothtml 2549call in order to 2550clear the memory @emph{before} the UNU.RAN generator object is 2551destroyed. 2552 2553If this block is omitted the UNU.RAN default generator is used 2554(which @emph{must not} be destroyed). 2555 2556 2557 2558@c 2559@c end of parser.h 2560@c ------------------------------------- 2561@c ------------------------------------- 2562@c distr.h 2563@c 2564 2565@page 2566@node Distribution_objects 2567@chapter Handling distribution objects 2568 2569@menu 2570* AllDistr:: Functions for all kinds of distribution objects 2571* CONT:: Continuous univariate distributions 2572* CORDER:: Continuous univariate order statistics 2573* CEMP:: Continuous empirical univariate distributions 2574* CVEC:: Continuous multivariate distributions 2575* CONDI:: Continuous univariate full conditional distribution 2576* CVEMP:: Continuous empirical multivariate distributions 2577* MATR:: MATRix distributions 2578* DISCR:: Discrete univariate distributions 2579@end menu 2580 2581 2582Objects of type @code{UNUR_DISTR} are used for handling 2583distributions. All data about a distribution are stored in this 2584object. UNU.RAN provides functions that return instances of such 2585objects for standard distributions 2586(@pxref{Stddist,,Standard distributions}). 2587It is then possible to change these distribution objects by 2588various set calls. Moreover, it is possible to build a 2589distribution object entirely from scratch. For this purpose 2590there exists @command{unur_distr_<type>_new} calls that 2591return an empty object of this type for each object type 2592(eg. univariate contiuous) which can be filled with the 2593appropriate set calls. 2594 2595UNU.RAN distinguishes between several types of distributions, 2596each of which has its own sets of possible parameters (for 2597details see the corresponding sections): 2598@itemize @minus 2599@item continuous univariate distributions 2600@item continuous univariate order statistics 2601@item continuous empirical univariate distributions 2602@item continuous multivariate distributions 2603@item continuous empirical multivariate distributions 2604@item matrix distributions 2605@item discrete univariate distributions 2606@end itemize 2607 2608Notice that there are essential data about a distribution, 2609eg. the PDF, a list of (shape, scale, location) parameters for 2610the distribution, and the domain of (the possibly truncated) 2611distribution. And there exist parameters that are/can be 2612derived from these, eg. the mode of the distribution or the area 2613below the given PDF (which need not be normalized for many 2614methods). UNU.RAN keeps track of parameters which are 2615known. Thus if one of the essential parameters is changed all 2616derived parameters are marked as unknown and must be set again 2617if these are required for the chosen generation method. 2618Additionally to set calls there are calls for updating derived 2619parameters for objects provided by the UNU.RAN library of standard 2620distributions (one for each parameter to avoid computational 2621overhead since not all parameters are required for all generator 2622methods). 2623 2624All parameters of distribution objects can be read by 2625corresponding get calls. 2626 2627Every generator object has its own copy of a distribution object 2628which is accessible by a 2629@ifhtml 2630@ref{funct:unur_get_distr,@command{unur_get_distr}} 2631@end ifhtml 2632@ifnothtml 2633@command{unur_get_distr} 2634@end ifnothtml 2635call. Thus the 2636parameter for this distribution can be read. However, 2637@strong{never} extract the distribution object out of a 2638generator object and run one of the set calls on it to modify 2639the distribution. (How should the poor generator object know 2640what has happend?) Instead there exist calls for each of the 2641generator methods that change particular parameters of the 2642internal copy of the distribution object. 2643 2644 2645@subsubheading How To Use 2646 2647 2648UNU.RAN collects all data required for a particular generation 2649method in a @emph{distribution object}. There are two ways to 2650get an instance of a distributions object: 2651@enumerate 2652@item 2653Build a distribtion from scratch, by means of 2654the corresponding @command{unur_distr_<type>_new} call, 2655where @command{<type>} is the type of the distribution as 2656listed in the below subsections. 2657 2658@item 2659Use the corresponding @command{unur_distr_<name>_new} call 2660to get prebuild distribution from the UNU.RAN library of standard 2661distributions. 2662Here @command{<name>} is the name of the 2663standard distribution in @ref{Stddist,,Standard distributions}. 2664@end enumerate 2665 2666In either cases the corresponding 2667@command{unur_distr_<type>_set_<param>} calls to set the 2668necessary parameters @command{<param>} (case 1), or 2669change the values of the standard distribution in case 2 (if 2670this makes sense for you). In the latter case @command{<type>} 2671is the type to which the standard distribution belongs to. 2672These @command{set} calls return @code{UNUR_SUCCESS} when the 2673correspondig parameter has been set successfully. Otherwise an 2674error code is returned. 2675 2676The parameters of a distribution are divided into 2677@emph{essential} and @emph{derived} parameters. 2678 2679Notice, that there are some restrictions in setting parameters 2680to avoid possible confusions. 2681Changing essential parameters marks derived parameters as 2682@code{unknown}. Some of the parameters cannot be changed any 2683more when already set; some parameters block each others. 2684In such a case a new instance of a distribution object has to be 2685build. 2686 2687Additionally @command{unur_distr_<type>_upd_<param>} calls can 2688be used for updating derived parameters for objects provided by 2689the UNU.RAN library of standard distributions. 2690 2691All parameters of a distribution object get be read by means of 2692@command{unur_distr_<type>_get_<param>} calls. 2693 2694Every distribution object be identified by its @code{name} which 2695is a string of arbitrary characters provided by the user. For 2696standard distribution it is automatically set to 2697@command{<name>} in the corresponding @command{new} call. It can 2698be changed to any other string. 2699 2700 2701 2702 2703 2704@c 2705@c end of distr.h 2706@c ------------------------------------- 2707@c ------------------------------------- 2708@c distr.h 2709@c 2710 2711@page 2712@node AllDistr 2713@section Functions for all kinds of distribution objects 2714 2715 2716The calls in this section can be applied to all distribution 2717objects. 2718 2719@itemize @minus 2720@item Destroy @command{free} an instance of a generator object. 2721 2722@item Ask for the @command{type} of a generator object. 2723 2724@item Ask for the @command{dimension} of a generator object. 2725 2726@item Deal with the @command{name} (identifier string) of a generator object. 2727@end itemize 2728 2729 2730@subheading Function reference 2731 2732@ifhtml 2733@itemize 2734@item @ref{funct:unur_distr_free,unur_distr_free} 2735@item @ref{funct:unur_distr_set_name,unur_distr_set_name} 2736@item @ref{funct:unur_distr_get_name,unur_distr_get_name} 2737@item @ref{funct:unur_distr_get_dim,unur_distr_get_dim} 2738@item @ref{funct:unur_distr_get_type,unur_distr_get_type} 2739@item @ref{funct:unur_distr_is_cont,unur_distr_is_cont} 2740@item @ref{funct:unur_distr_is_cvec,unur_distr_is_cvec} 2741@item @ref{funct:unur_distr_is_cemp,unur_distr_is_cemp} 2742@item @ref{funct:unur_distr_is_cvemp,unur_distr_is_cvemp} 2743@item @ref{funct:unur_distr_is_discr,unur_distr_is_discr} 2744@item @ref{funct:unur_distr_is_matr,unur_distr_is_matr} 2745@item @ref{funct:unur_distr_set_extobj,unur_distr_set_extobj} 2746@item @ref{funct:unur_distr_get_extobj,unur_distr_get_extobj} 2747@end itemize 2748@end ifhtml 2749 2750 2751@ifinfo 2752@anchor{funct:unur_distr_free} 2753@deftypefn Function {void} unur_distr_free (UNUR_DISTR* @var{distribution}) 2754Destroy the @var{distribution} object. 2755@end deftypefn 2756@end ifinfo 2757@ifnotinfo 2758@anchor{funct:unur_distr_free} 2759@deftypefn {} {void} unur_distr_free (UNUR_DISTR* @var{distribution}) 2760Destroy the @var{distribution} object. 2761@end deftypefn 2762@end ifnotinfo 2763 2764@ifinfo 2765@anchor{funct:unur_distr_set_name} 2766@deftypefn Function {int} unur_distr_set_name (UNUR_DISTR* @var{distribution}, const @var{char* name}) 2767@anchor{funct:unur_distr_get_name} 2768@deftypefnx Function {const char*} unur_distr_get_name (const @var{UNUR_DISTR* distribution}) 2769Set and get @var{name} of @var{distribution}. The @var{name} can be 2770an arbitrary character string. It can be used to identify generator 2771objects for the user. It is used by UNU.RAN when printing 2772information of the distribution object into a log files. 2773@end deftypefn 2774@end ifinfo 2775@ifnotinfo 2776@anchor{funct:unur_distr_set_name} 2777@deftypefn {} {int} unur_distr_set_name (UNUR_DISTR* @var{distribution}, const @var{char* name}) 2778@anchor{funct:unur_distr_get_name} 2779@deftypefnx {} {const char*} unur_distr_get_name (const @var{UNUR_DISTR* distribution}) 2780Set and get @var{name} of @var{distribution}. The @var{name} can be 2781an arbitrary character string. It can be used to identify generator 2782objects for the user. It is used by UNU.RAN when printing 2783information of the distribution object into a log files. 2784@end deftypefn 2785@end ifnotinfo 2786 2787@ifinfo 2788@anchor{funct:unur_distr_get_dim} 2789@deftypefn Function {int} unur_distr_get_dim (const @var{UNUR_DISTR* distribution}) 2790Get number of components of a random vector (its dimension) the 2791@var{distribution}. 2792 2793For univariate distributions it returns dimension @code{1}. 2794 2795For matrix distributions it returns the number of components 2796(i.e., number of rows times number of columns). 2797When the respective numbers of rows and columns are needed use 2798@ifhtml 2799@ref{funct:unur_distr_matr_get_dim,@command{unur_distr_matr_get_dim}} 2800@end ifhtml 2801@ifnothtml 2802@command{unur_distr_matr_get_dim} 2803@end ifnothtml 2804instead. 2805@end deftypefn 2806@end ifinfo 2807@ifnotinfo 2808@anchor{funct:unur_distr_get_dim} 2809@deftypefn {} {int} unur_distr_get_dim (const @var{UNUR_DISTR* distribution}) 2810Get number of components of a random vector (its dimension) the 2811@var{distribution}. 2812 2813For univariate distributions it returns dimension @code{1}. 2814 2815For matrix distributions it returns the number of components 2816(i.e., number of rows times number of columns). 2817When the respective numbers of rows and columns are needed use 2818@ifhtml 2819@ref{funct:unur_distr_matr_get_dim,@command{unur_distr_matr_get_dim}} 2820@end ifhtml 2821@ifnothtml 2822@command{unur_distr_matr_get_dim} 2823@end ifnothtml 2824instead. 2825@end deftypefn 2826@end ifnotinfo 2827 2828@ifinfo 2829@anchor{funct:unur_distr_get_type} 2830@deftypefn Function {unsigned int} unur_distr_get_type (const @var{UNUR_DISTR* distribution}) 2831Get type of @var{distribution}. 2832Possible types are 2833@table @code 2834@item UNUR_DISTR_CONT 2835univariate continuous distribution 2836@item UNUR_DISTR_CEMP 2837empirical continuous univariate distribution (i.e. a sample) 2838@item UNUR_DISTR_CVEC 2839continuous mulitvariate distribution 2840@item UNUR_DISTR_CVEMP 2841empirical continuous multivariate distribution (i.e. a vector sample) 2842@item UNUR_DISTR_DISCR 2843discrete univariate distribution 2844@item UNUR_DISTR_MATR 2845matrix distribution 2846@end table 2847 2848Alternatively the @command{unur_distr_is_<TYPE>} 2849calls can be used. 2850@end deftypefn 2851@end ifinfo 2852@ifnotinfo 2853@anchor{funct:unur_distr_get_type} 2854@deftypefn {} {unsigned int} unur_distr_get_type (const @var{UNUR_DISTR* distribution}) 2855Get type of @var{distribution}. 2856Possible types are 2857@table @code 2858@item UNUR_DISTR_CONT 2859univariate continuous distribution 2860@item UNUR_DISTR_CEMP 2861empirical continuous univariate distribution (i.e. a sample) 2862@item UNUR_DISTR_CVEC 2863continuous mulitvariate distribution 2864@item UNUR_DISTR_CVEMP 2865empirical continuous multivariate distribution (i.e. a vector sample) 2866@item UNUR_DISTR_DISCR 2867discrete univariate distribution 2868@item UNUR_DISTR_MATR 2869matrix distribution 2870@end table 2871 2872Alternatively the @command{unur_distr_is_<TYPE>} 2873calls can be used. 2874@end deftypefn 2875@end ifnotinfo 2876 2877@ifinfo 2878@anchor{funct:unur_distr_is_cont} 2879@deftypefn Function {int} unur_distr_is_cont (const @var{UNUR_DISTR* distribution}) 2880@code{TRUE} if @var{distribution} is a continuous univariate distribution. 2881@end deftypefn 2882@end ifinfo 2883@ifnotinfo 2884@anchor{funct:unur_distr_is_cont} 2885@deftypefn {} {int} unur_distr_is_cont (const @var{UNUR_DISTR* distribution}) 2886@code{TRUE} if @var{distribution} is a continuous univariate distribution. 2887@end deftypefn 2888@end ifnotinfo 2889 2890@ifinfo 2891@anchor{funct:unur_distr_is_cvec} 2892@deftypefn Function {int} unur_distr_is_cvec (const @var{UNUR_DISTR* distribution}) 2893@code{TRUE} if @var{distribution} is a continuous multivariate distribution. 2894@end deftypefn 2895@end ifinfo 2896@ifnotinfo 2897@anchor{funct:unur_distr_is_cvec} 2898@deftypefn {} {int} unur_distr_is_cvec (const @var{UNUR_DISTR* distribution}) 2899@code{TRUE} if @var{distribution} is a continuous multivariate distribution. 2900@end deftypefn 2901@end ifnotinfo 2902 2903@ifinfo 2904@anchor{funct:unur_distr_is_cemp} 2905@deftypefn Function {int} unur_distr_is_cemp (const @var{UNUR_DISTR* distribution}) 2906@code{TRUE} if @var{distribution} is an empirical continuous univariate distribution, 2907i.e. a sample. 2908@end deftypefn 2909@end ifinfo 2910@ifnotinfo 2911@anchor{funct:unur_distr_is_cemp} 2912@deftypefn {} {int} unur_distr_is_cemp (const @var{UNUR_DISTR* distribution}) 2913@code{TRUE} if @var{distribution} is an empirical continuous univariate distribution, 2914i.e. a sample. 2915@end deftypefn 2916@end ifnotinfo 2917 2918@ifinfo 2919@anchor{funct:unur_distr_is_cvemp} 2920@deftypefn Function {int} unur_distr_is_cvemp (const @var{UNUR_DISTR* distribution}) 2921@code{TRUE} if @var{distribution} is an empirical continuous multivariate 2922distribution. 2923@end deftypefn 2924@end ifinfo 2925@ifnotinfo 2926@anchor{funct:unur_distr_is_cvemp} 2927@deftypefn {} {int} unur_distr_is_cvemp (const @var{UNUR_DISTR* distribution}) 2928@code{TRUE} if @var{distribution} is an empirical continuous multivariate 2929distribution. 2930@end deftypefn 2931@end ifnotinfo 2932 2933@ifinfo 2934@anchor{funct:unur_distr_is_discr} 2935@deftypefn Function {int} unur_distr_is_discr (const @var{UNUR_DISTR* distribution}) 2936@code{TRUE} if @var{distribution} is a discrete univariate distribution. 2937@end deftypefn 2938@end ifinfo 2939@ifnotinfo 2940@anchor{funct:unur_distr_is_discr} 2941@deftypefn {} {int} unur_distr_is_discr (const @var{UNUR_DISTR* distribution}) 2942@code{TRUE} if @var{distribution} is a discrete univariate distribution. 2943@end deftypefn 2944@end ifnotinfo 2945 2946@ifinfo 2947@anchor{funct:unur_distr_is_matr} 2948@deftypefn Function {int} unur_distr_is_matr (const @var{UNUR_DISTR* distribution}) 2949@code{TRUE} if @var{distribution} is a matrix distribution. 2950@end deftypefn 2951@end ifinfo 2952@ifnotinfo 2953@anchor{funct:unur_distr_is_matr} 2954@deftypefn {} {int} unur_distr_is_matr (const @var{UNUR_DISTR* distribution}) 2955@code{TRUE} if @var{distribution} is a matrix distribution. 2956@end deftypefn 2957@end ifnotinfo 2958 2959@ifinfo 2960@anchor{funct:unur_distr_set_extobj} 2961@deftypefn Function {int} unur_distr_set_extobj (UNUR_DISTR* @var{distribution}, const @var{void* extobj}) 2962Store a pointer to an external object. This might be usefull if 2963the PDF, PMF, CDF or other functions used to implement a particular 2964distribution a parameter set that cannot be stored as doubles 2965(e.g. pointers to some structure that holds information of the distribution). 2966 2967@strong{Important:} 2968When UNU.RAN copies this distribution object into the generator object, 2969then the address @var{extobj} that this pointer contains is simply copied. 2970Thus the generator holds an address of a non-private object! 2971Once the generator object has been created any change in the external 2972object might effect the generator object. 2973 2974@strong{Warning:} 2975External objects must be used with care. Once the generator object has been 2976created or the distribution object has been copied you @emph{must not} 2977destroy this external object. 2978@end deftypefn 2979@end ifinfo 2980@ifnotinfo 2981@anchor{funct:unur_distr_set_extobj} 2982@deftypefn {} {int} unur_distr_set_extobj (UNUR_DISTR* @var{distribution}, const @var{void* extobj}) 2983Store a pointer to an external object. This might be usefull if 2984the PDF, PMF, CDF or other functions used to implement a particular 2985distribution a parameter set that cannot be stored as doubles 2986(e.g. pointers to some structure that holds information of the distribution). 2987 2988@strong{Important:} 2989When UNU.RAN copies this distribution object into the generator object, 2990then the address @var{extobj} that this pointer contains is simply copied. 2991Thus the generator holds an address of a non-private object! 2992Once the generator object has been created any change in the external 2993object might effect the generator object. 2994 2995@strong{Warning:} 2996External objects must be used with care. Once the generator object has been 2997created or the distribution object has been copied you @emph{must not} 2998destroy this external object. 2999@end deftypefn 3000@end ifnotinfo 3001 3002@ifinfo 3003@anchor{funct:unur_distr_get_extobj} 3004@deftypefn Function {const void*} unur_distr_get_extobj (const @var{UNUR_DISTR* distribution}) 3005Get the pointer to the external object. 3006 3007@emph{Important:} 3008Changing this object must be done with with extreme care. 3009@end deftypefn 3010@end ifinfo 3011@ifnotinfo 3012@anchor{funct:unur_distr_get_extobj} 3013@deftypefn {} {const void*} unur_distr_get_extobj (const @var{UNUR_DISTR* distribution}) 3014Get the pointer to the external object. 3015 3016@emph{Important:} 3017Changing this object must be done with with extreme care. 3018@end deftypefn 3019@end ifnotinfo 3020 3021 3022 3023 3024@c 3025@c end of distr.h 3026@c ------------------------------------- 3027@c ------------------------------------- 3028@c cont.h 3029@c 3030 3031@page 3032@node CONT 3033@section Continuous univariate distributions 3034 3035 3036The calls in this section can be applied to continuous 3037univariate distributions. 3038 3039@itemize @minus 3040@item Create a @command{new} instance of a continuous univariate 3041distribution. 3042 3043@item Handle and evaluate 3044distribution function (CDF, @command{cdf}), 3045probability density function (PDF, @command{pdf}) and the 3046derivative of the density function (@command{dpdf}). 3047The following is important: 3048@itemize . 3049@item @command{pdf} need not be normalized, i.e., 3050any integrable nonnegative function can be used. 3051@item @command{dpdf} must the derivate of the function provided 3052as @command{pdf}. 3053@item @command{cdf} must be a distribution function, i.e. it 3054must be monotonically increasing with range [0,1]. 3055@item If @command{cdf} and @command{pdf} are used together for a 3056pariticular generation method, then @command{pdf} must be the 3057derivate of the @command{cdf}, i.e., it must be normalized. 3058@end itemize 3059 3060@item Handle and evaluate 3061the logarithm of the probability density function (logPDF, 3062@command{logpdf}) and the derivative of the logarithm of the 3063density function (@command{dlogpdf}). 3064 3065Some methods use the logarithm of the density if available. 3066 3067@item Set (and change) parameters (@command{pdfparams}) and the 3068area below the graph (@command{pdfarea}) of the given density. 3069 3070@item Set the @command{mode} (or pole) of the distribution. 3071 3072@item Set the @command{center} of the distribution. 3073It is used by some generation methods to adjust the parameters 3074of the generation algorithms to gain better performance. It can 3075be seens as the location of the ``central part'' of the 3076distribution. 3077 3078@item Some generation methods require the hazard rate 3079(@command{hr}) of the distribution instead of its @command{pdf}. 3080 3081@item Alternatively, @command{cdf}, @command{pdf}, @command{dpdf}, 3082and @command{hr} can be provided as @command{str}ings instead of 3083function pointers. 3084 3085@item Set the @command{domain} of the distribution. Notice that 3086the library also can handle truncated distributions, i.e., 3087distributions that are derived from (standard) distributions by 3088simply restricting its domain to a subset. However, there is a 3089subtle difference between changing the domain of a distribution 3090object by a 3091@ifhtml 3092@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 3093@end ifhtml 3094@ifnothtml 3095@command{unur_distr_cont_set_domain} 3096@end ifnothtml 3097call and changing the 3098(truncated) domain for an existing generator object. The domain 3099of the distribution object is used to create the generator 3100object with hats, squeezes, tables, etc. Whereas truncating the 3101domain of an existing generator object need not necessarily 3102require a recomputation of these data. Thus by a 3103@command{unur_<method>_chg_truncated} call (if available) the 3104sampling region is restricted to the subset of the domain of the 3105given distribution object. However, generation methods that 3106require a recreation of the generator object when the domain is 3107changed have a @command{unur_<method>_chg_domain} call instead. 3108For these calls there are of course no restrictions on the given 3109domain (i.e., it is possible to increase the domain of the 3110distribution) (@pxref{Methods}, for details). 3111 3112@end itemize 3113 3114 3115@subheading Function reference 3116 3117@ifhtml 3118@itemize 3119@item @ref{funct:unur_distr_cont_new,unur_distr_cont_new} 3120@item @ref{funct:unur_distr_cont_set_pdf,unur_distr_cont_set_pdf} 3121@item @ref{funct:unur_distr_cont_set_dpdf,unur_distr_cont_set_dpdf} 3122@item @ref{funct:unur_distr_cont_set_cdf,unur_distr_cont_set_cdf} 3123@item @ref{funct:unur_distr_cont_set_invcdf,unur_distr_cont_set_invcdf} 3124@item @ref{funct:unur_distr_cont_get_pdf,unur_distr_cont_get_pdf} 3125@item @ref{funct:unur_distr_cont_get_dpdf,unur_distr_cont_get_dpdf} 3126@item @ref{funct:unur_distr_cont_get_cdf,unur_distr_cont_get_cdf} 3127@item @ref{funct:unur_distr_cont_get_invcdf,unur_distr_cont_get_invcdf} 3128@item @ref{funct:unur_distr_cont_eval_pdf,unur_distr_cont_eval_pdf} 3129@item @ref{funct:unur_distr_cont_eval_dpdf,unur_distr_cont_eval_dpdf} 3130@item @ref{funct:unur_distr_cont_eval_cdf,unur_distr_cont_eval_cdf} 3131@item @ref{funct:unur_distr_cont_eval_invcdf,unur_distr_cont_eval_invcdf} 3132@item @ref{funct:unur_distr_cont_set_logpdf,unur_distr_cont_set_logpdf} 3133@item @ref{funct:unur_distr_cont_set_dlogpdf,unur_distr_cont_set_dlogpdf} 3134@item @ref{funct:unur_distr_cont_set_logcdf,unur_distr_cont_set_logcdf} 3135@item @ref{funct:unur_distr_cont_get_logpdf,unur_distr_cont_get_logpdf} 3136@item @ref{funct:unur_distr_cont_get_dlogpdf,unur_distr_cont_get_dlogpdf} 3137@item @ref{funct:unur_distr_cont_get_logcdf,unur_distr_cont_get_logcdf} 3138@item @ref{funct:unur_distr_cont_eval_logpdf,unur_distr_cont_eval_logpdf} 3139@item @ref{funct:unur_distr_cont_eval_dlogpdf,unur_distr_cont_eval_dlogpdf} 3140@item @ref{funct:unur_distr_cont_eval_logcdf,unur_distr_cont_eval_logcdf} 3141@item @ref{funct:unur_distr_cont_set_pdfstr,unur_distr_cont_set_pdfstr} 3142@item @ref{funct:unur_distr_cont_set_cdfstr,unur_distr_cont_set_cdfstr} 3143@item @ref{funct:unur_distr_cont_get_pdfstr,unur_distr_cont_get_pdfstr} 3144@item @ref{funct:unur_distr_cont_get_dpdfstr,unur_distr_cont_get_dpdfstr} 3145@item @ref{funct:unur_distr_cont_get_cdfstr,unur_distr_cont_get_cdfstr} 3146@item @ref{funct:unur_distr_cont_set_pdfparams,unur_distr_cont_set_pdfparams} 3147@item @ref{funct:unur_distr_cont_get_pdfparams,unur_distr_cont_get_pdfparams} 3148@item @ref{funct:unur_distr_cont_set_pdfparams_vec,unur_distr_cont_set_pdfparams_vec} 3149@item @ref{funct:unur_distr_cont_get_pdfparams_vec,unur_distr_cont_get_pdfparams_vec} 3150@item @ref{funct:unur_distr_cont_set_logpdfstr,unur_distr_cont_set_logpdfstr} 3151@item @ref{funct:unur_distr_cont_get_logpdfstr,unur_distr_cont_get_logpdfstr} 3152@item @ref{funct:unur_distr_cont_get_dlogpdfstr,unur_distr_cont_get_dlogpdfstr} 3153@item @ref{funct:unur_distr_cont_set_logcdfstr,unur_distr_cont_set_logcdfstr} 3154@item @ref{funct:unur_distr_cont_get_logcdfstr,unur_distr_cont_get_logcdfstr} 3155@item @ref{funct:unur_distr_cont_set_domain,unur_distr_cont_set_domain} 3156@item @ref{funct:unur_distr_cont_get_domain,unur_distr_cont_get_domain} 3157@item @ref{funct:unur_distr_cont_get_truncated,unur_distr_cont_get_truncated} 3158@item @ref{funct:unur_distr_cont_set_hr,unur_distr_cont_set_hr} 3159@item @ref{funct:unur_distr_cont_get_hr,unur_distr_cont_get_hr} 3160@item @ref{funct:unur_distr_cont_eval_hr,unur_distr_cont_eval_hr} 3161@item @ref{funct:unur_distr_cont_set_hrstr,unur_distr_cont_set_hrstr} 3162@item @ref{funct:unur_distr_cont_get_hrstr,unur_distr_cont_get_hrstr} 3163@item @ref{funct:unur_distr_cont_set_mode,unur_distr_cont_set_mode} 3164@item @ref{funct:unur_distr_cont_upd_mode,unur_distr_cont_upd_mode} 3165@item @ref{funct:unur_distr_cont_get_mode,unur_distr_cont_get_mode} 3166@item @ref{funct:unur_distr_cont_set_center,unur_distr_cont_set_center} 3167@item @ref{funct:unur_distr_cont_get_center,unur_distr_cont_get_center} 3168@item @ref{funct:unur_distr_cont_set_pdfarea,unur_distr_cont_set_pdfarea} 3169@item @ref{funct:unur_distr_cont_upd_pdfarea,unur_distr_cont_upd_pdfarea} 3170@item @ref{funct:unur_distr_cont_get_pdfarea,unur_distr_cont_get_pdfarea} 3171@end itemize 3172@end ifhtml 3173 3174 3175@ifinfo 3176@anchor{funct:unur_distr_cont_new} 3177@deftypefn Function {UNUR_DISTR*} unur_distr_cont_new (void) 3178Create a new (empty) object for univariate continuous distribution. 3179@end deftypefn 3180@end ifinfo 3181@ifnotinfo 3182@anchor{funct:unur_distr_cont_new} 3183@deftypefn {} {UNUR_DISTR*} unur_distr_cont_new (void) 3184Create a new (empty) object for univariate continuous distribution. 3185@end deftypefn 3186@end ifnotinfo 3187 3188@subsubheading Essential parameters 3189 3190@ifinfo 3191@anchor{funct:unur_distr_cont_set_pdf} 3192@deftypefn Function {int} unur_distr_cont_set_pdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{pdf}) 3193@anchor{funct:unur_distr_cont_set_dpdf} 3194@deftypefnx Function {int} unur_distr_cont_set_dpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{dpdf}) 3195@anchor{funct:unur_distr_cont_set_cdf} 3196@deftypefnx Function {int} unur_distr_cont_set_cdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{cdf}) 3197@anchor{funct:unur_distr_cont_set_invcdf} 3198@deftypefnx Function {int} unur_distr_cont_set_invcdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{invcdf}) 3199Set respective pointer to the probability density function (PDF), 3200the derivative of the probability density function (dPDF), the 3201cumulative distribution function (CDF), and the inverse CDF of the 3202@var{distribution}. 3203Each of these function pointers must be of type 3204@code{double funct(double x, const UNUR_DISTR *distr)}. 3205 3206Due to the fact that some of the methods do not require a 3207normalized PDF the following is important: 3208 3209@itemize @minus 3210@item 3211The given CDF must be the cumulative distribution function of 3212the (non-truncated) distribution. If a distribution from the 3213UNU.RAN library of standard distributions 3214(@pxref{Stddist,,Standard distributions}) 3215is truncated, there is no need to change the CDF. 3216 3217@item 3218If both the CDF and the PDF are used (for a method or for order 3219statistics), the PDF must be the derivative of the CDF. 3220If a truncated distribution for one of the standard distributions 3221from the UNU.RAN library of standard distributions is used, 3222there is no need to change the PDF. 3223 3224@item 3225If the area below the PDF is required for a given distribution 3226it must be given by the 3227@ifhtml 3228@ref{funct:unur_distr_cont_set_pdfarea,@command{unur_distr_cont_set_pdfarea}} 3229@end ifhtml 3230@ifnothtml 3231@command{unur_distr_cont_set_pdfarea} 3232@end ifnothtml 3233call. 3234For a truncated distribution this must be of course the integral of 3235the PDF in the given truncated domain. 3236For distributions from the UNU.RAN library of standard 3237distributions this is done automatically by the 3238@ifhtml 3239@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 3240@end ifhtml 3241@ifnothtml 3242@command{unur_distr_cont_upd_pdfarea} 3243@end ifnothtml 3244call. 3245 3246@end itemize 3247 3248It is important to note that all these functions must return a 3249result for all values of @var{x}. Eg., if the domain of a given 3250PDF is the interval [-1,1], then the given function must return 3251@code{0.0} for all points outside this interval. 3252In case of an overflow the PDF should return 3253@code{UNUR_INFINITY}. 3254 3255It is not possible to change such a function. Once the PDF or 3256CDF is set it cannot be overwritten. This also holds when the 3257logPDF is given or when the PDF 3258is given by the 3259@ifhtml 3260@ref{funct:unur_distr_cont_set_pdfstr,@command{unur_distr_cont_set_pdfstr}} 3261@end ifhtml 3262@ifnothtml 3263@command{unur_distr_cont_set_pdfstr} 3264@end ifnothtml 3265or 3266@ifhtml 3267@ref{funct:unur_distr_cont_set_logpdfstr,@command{unur_distr_cont_set_logpdfstr}} 3268@end ifhtml 3269@ifnothtml 3270@command{unur_distr_cont_set_logpdfstr} 3271@end ifnothtml 3272call. 3273A new distribution object has to be used instead. 3274@end deftypefn 3275@end ifinfo 3276@ifnotinfo 3277@anchor{funct:unur_distr_cont_set_pdf} 3278@deftypefn {} {int} unur_distr_cont_set_pdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{pdf}) 3279@anchor{funct:unur_distr_cont_set_dpdf} 3280@deftypefnx {} {int} unur_distr_cont_set_dpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{dpdf}) 3281@anchor{funct:unur_distr_cont_set_cdf} 3282@deftypefnx {} {int} unur_distr_cont_set_cdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{cdf}) 3283@anchor{funct:unur_distr_cont_set_invcdf} 3284@deftypefnx {} {int} unur_distr_cont_set_invcdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{invcdf}) 3285Set respective pointer to the probability density function (PDF), 3286the derivative of the probability density function (dPDF), the 3287cumulative distribution function (CDF), and the inverse CDF of the 3288@var{distribution}. 3289Each of these function pointers must be of type 3290@code{double funct(double x, const UNUR_DISTR *distr)}. 3291 3292Due to the fact that some of the methods do not require a 3293normalized PDF the following is important: 3294 3295@itemize @minus 3296@item 3297The given CDF must be the cumulative distribution function of 3298the (non-truncated) distribution. If a distribution from the 3299UNU.RAN library of standard distributions 3300(@pxref{Stddist,,Standard distributions}) 3301is truncated, there is no need to change the CDF. 3302 3303@item 3304If both the CDF and the PDF are used (for a method or for order 3305statistics), the PDF must be the derivative of the CDF. 3306If a truncated distribution for one of the standard distributions 3307from the UNU.RAN library of standard distributions is used, 3308there is no need to change the PDF. 3309 3310@item 3311If the area below the PDF is required for a given distribution 3312it must be given by the 3313@ifhtml 3314@ref{funct:unur_distr_cont_set_pdfarea,@command{unur_distr_cont_set_pdfarea}} 3315@end ifhtml 3316@ifnothtml 3317@command{unur_distr_cont_set_pdfarea} 3318@end ifnothtml 3319call. 3320For a truncated distribution this must be of course the integral of 3321the PDF in the given truncated domain. 3322For distributions from the UNU.RAN library of standard 3323distributions this is done automatically by the 3324@ifhtml 3325@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 3326@end ifhtml 3327@ifnothtml 3328@command{unur_distr_cont_upd_pdfarea} 3329@end ifnothtml 3330call. 3331 3332@end itemize 3333 3334It is important to note that all these functions must return a 3335result for all values of @var{x}. Eg., if the domain of a given 3336PDF is the interval [-1,1], then the given function must return 3337@code{0.0} for all points outside this interval. 3338In case of an overflow the PDF should return 3339@code{UNUR_INFINITY}. 3340 3341It is not possible to change such a function. Once the PDF or 3342CDF is set it cannot be overwritten. This also holds when the 3343logPDF is given or when the PDF 3344is given by the 3345@ifhtml 3346@ref{funct:unur_distr_cont_set_pdfstr,@command{unur_distr_cont_set_pdfstr}} 3347@end ifhtml 3348@ifnothtml 3349@command{unur_distr_cont_set_pdfstr} 3350@end ifnothtml 3351or 3352@ifhtml 3353@ref{funct:unur_distr_cont_set_logpdfstr,@command{unur_distr_cont_set_logpdfstr}} 3354@end ifhtml 3355@ifnothtml 3356@command{unur_distr_cont_set_logpdfstr} 3357@end ifnothtml 3358call. 3359A new distribution object has to be used instead. 3360@end deftypefn 3361@end ifnotinfo 3362 3363@ifinfo 3364@anchor{funct:unur_distr_cont_get_pdf} 3365@deftypefn Function {UNUR_FUNCT_CONT*} unur_distr_cont_get_pdf (const @var{UNUR_DISTR* distribution}) 3366@anchor{funct:unur_distr_cont_get_dpdf} 3367@deftypefnx Function {UNUR_FUNCT_CONT*} unur_distr_cont_get_dpdf (const @var{UNUR_DISTR* distribution}) 3368@anchor{funct:unur_distr_cont_get_cdf} 3369@deftypefnx Function {UNUR_FUNCT_CONT*} unur_distr_cont_get_cdf (const @var{UNUR_DISTR* distribution}) 3370@anchor{funct:unur_distr_cont_get_invcdf} 3371@deftypefnx Function {UNUR_FUNCT_CONT*} unur_distr_cont_get_invcdf (const @var{UNUR_DISTR* distribution}) 3372Get the respective pointer to the PDF, the derivative of the 3373PDF, the CDF, and the inverse CDF of the @var{distribution}. The 3374pointer is of type @code{double funct(double x, const UNUR_DISTR *distr)}. 3375If the corresponding function is not available for the distribution, 3376the @code{NULL} pointer is returned. 3377@end deftypefn 3378@end ifinfo 3379@ifnotinfo 3380@anchor{funct:unur_distr_cont_get_pdf} 3381@deftypefn {} {UNUR_FUNCT_CONT*} unur_distr_cont_get_pdf (const @var{UNUR_DISTR* distribution}) 3382@anchor{funct:unur_distr_cont_get_dpdf} 3383@deftypefnx {} {UNUR_FUNCT_CONT*} unur_distr_cont_get_dpdf (const @var{UNUR_DISTR* distribution}) 3384@anchor{funct:unur_distr_cont_get_cdf} 3385@deftypefnx {} {UNUR_FUNCT_CONT*} unur_distr_cont_get_cdf (const @var{UNUR_DISTR* distribution}) 3386@anchor{funct:unur_distr_cont_get_invcdf} 3387@deftypefnx {} {UNUR_FUNCT_CONT*} unur_distr_cont_get_invcdf (const @var{UNUR_DISTR* distribution}) 3388Get the respective pointer to the PDF, the derivative of the 3389PDF, the CDF, and the inverse CDF of the @var{distribution}. The 3390pointer is of type @code{double funct(double x, const UNUR_DISTR *distr)}. 3391If the corresponding function is not available for the distribution, 3392the @code{NULL} pointer is returned. 3393@end deftypefn 3394@end ifnotinfo 3395 3396@ifinfo 3397@anchor{funct:unur_distr_cont_eval_pdf} 3398@deftypefn Function {double} unur_distr_cont_eval_pdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3399@anchor{funct:unur_distr_cont_eval_dpdf} 3400@deftypefnx Function {double} unur_distr_cont_eval_dpdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3401@anchor{funct:unur_distr_cont_eval_cdf} 3402@deftypefnx Function {double} unur_distr_cont_eval_cdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3403@anchor{funct:unur_distr_cont_eval_invcdf} 3404@deftypefnx Function {double} unur_distr_cont_eval_invcdf (double @var{u}, const @var{UNUR_DISTR* distribution}) 3405Evaluate the PDF, derivative of the PDF, the CDF, and the inverse 3406CDF at @var{x} and @var{u},respectively. 3407Notice that @var{distribution} must not be the @code{NULL} pointer. 3408If the corresponding function is not available for the distribution, 3409@code{UNUR_INFINITY} is returned and @code{unur_errno} is set to 3410@code{UNUR_ERR_DISTR_DATA}. 3411 3412@emph{IMPORTANT:} 3413In the case of a truncated standard distribution these calls always 3414return the respective values of the @emph{untruncated} distribution! 3415@end deftypefn 3416@end ifinfo 3417@ifnotinfo 3418@anchor{funct:unur_distr_cont_eval_pdf} 3419@deftypefn {} {double} unur_distr_cont_eval_pdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3420@anchor{funct:unur_distr_cont_eval_dpdf} 3421@deftypefnx {} {double} unur_distr_cont_eval_dpdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3422@anchor{funct:unur_distr_cont_eval_cdf} 3423@deftypefnx {} {double} unur_distr_cont_eval_cdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3424@anchor{funct:unur_distr_cont_eval_invcdf} 3425@deftypefnx {} {double} unur_distr_cont_eval_invcdf (double @var{u}, const @var{UNUR_DISTR* distribution}) 3426Evaluate the PDF, derivative of the PDF, the CDF, and the inverse 3427CDF at @var{x} and @var{u},respectively. 3428Notice that @var{distribution} must not be the @code{NULL} pointer. 3429If the corresponding function is not available for the distribution, 3430@code{UNUR_INFINITY} is returned and @code{unur_errno} is set to 3431@code{UNUR_ERR_DISTR_DATA}. 3432 3433@emph{IMPORTANT:} 3434In the case of a truncated standard distribution these calls always 3435return the respective values of the @emph{untruncated} distribution! 3436@end deftypefn 3437@end ifnotinfo 3438 3439@ifinfo 3440@anchor{funct:unur_distr_cont_set_logpdf} 3441@deftypefn Function {int} unur_distr_cont_set_logpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{logpdf}) 3442@anchor{funct:unur_distr_cont_set_dlogpdf} 3443@deftypefnx Function {int} unur_distr_cont_set_dlogpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{dlogpdf}) 3444@anchor{funct:unur_distr_cont_set_logcdf} 3445@deftypefnx Function {int} unur_distr_cont_set_logcdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{logcdf}) 3446@anchor{funct:unur_distr_cont_get_logpdf} 3447@deftypefnx Function {UNUR_FUNCT_CONT*} unur_distr_cont_get_logpdf (const @var{UNUR_DISTR* distribution}) 3448@anchor{funct:unur_distr_cont_get_dlogpdf} 3449@deftypefnx Function {UNUR_FUNCT_CONT*} unur_distr_cont_get_dlogpdf (const @var{UNUR_DISTR* distribution}) 3450@anchor{funct:unur_distr_cont_get_logcdf} 3451@deftypefnx Function {UNUR_FUNCT_CONT*} unur_distr_cont_get_logcdf (const @var{UNUR_DISTR* distribution}) 3452@anchor{funct:unur_distr_cont_eval_logpdf} 3453@deftypefnx Function {double} unur_distr_cont_eval_logpdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3454@anchor{funct:unur_distr_cont_eval_dlogpdf} 3455@deftypefnx Function {double} unur_distr_cont_eval_dlogpdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3456@anchor{funct:unur_distr_cont_eval_logcdf} 3457@deftypefnx Function {double} unur_distr_cont_eval_logcdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3458Analogous calls for the logarithm of the density distribution functions. 3459@end deftypefn 3460@end ifinfo 3461@ifnotinfo 3462@anchor{funct:unur_distr_cont_set_logpdf} 3463@deftypefn {} {int} unur_distr_cont_set_logpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{logpdf}) 3464@anchor{funct:unur_distr_cont_set_dlogpdf} 3465@deftypefnx {} {int} unur_distr_cont_set_dlogpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{dlogpdf}) 3466@anchor{funct:unur_distr_cont_set_logcdf} 3467@deftypefnx {} {int} unur_distr_cont_set_logcdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{logcdf}) 3468@anchor{funct:unur_distr_cont_get_logpdf} 3469@deftypefnx {} {UNUR_FUNCT_CONT*} unur_distr_cont_get_logpdf (const @var{UNUR_DISTR* distribution}) 3470@anchor{funct:unur_distr_cont_get_dlogpdf} 3471@deftypefnx {} {UNUR_FUNCT_CONT*} unur_distr_cont_get_dlogpdf (const @var{UNUR_DISTR* distribution}) 3472@anchor{funct:unur_distr_cont_get_logcdf} 3473@deftypefnx {} {UNUR_FUNCT_CONT*} unur_distr_cont_get_logcdf (const @var{UNUR_DISTR* distribution}) 3474@anchor{funct:unur_distr_cont_eval_logpdf} 3475@deftypefnx {} {double} unur_distr_cont_eval_logpdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3476@anchor{funct:unur_distr_cont_eval_dlogpdf} 3477@deftypefnx {} {double} unur_distr_cont_eval_dlogpdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3478@anchor{funct:unur_distr_cont_eval_logcdf} 3479@deftypefnx {} {double} unur_distr_cont_eval_logcdf (double @var{x}, const @var{UNUR_DISTR* distribution}) 3480Analogous calls for the logarithm of the density distribution functions. 3481@end deftypefn 3482@end ifnotinfo 3483 3484@ifinfo 3485@anchor{funct:unur_distr_cont_set_pdfstr} 3486@deftypefn Function {int} unur_distr_cont_set_pdfstr (UNUR_DISTR* @var{distribution}, const @var{char* pdfstr}) 3487This function provides an alternative way to set a PDF and its 3488derivative of the @var{distribution}. 3489@var{pdfstr} is a character string that contains the formula 3490for the PDF, see @ref{StringFunct,,Function String}, for details. 3491The derivative of the given PDF is computed automatically. 3492See also the remarks for the 3493@ifhtml 3494@ref{funct:unur_distr_cont_set_pdf,@command{unur_distr_cont_set_pdf}} 3495@end ifhtml 3496@ifnothtml 3497@command{unur_distr_cont_set_pdf} 3498@end ifnothtml 3499call. 3500 3501It is not possible to call this funtion twice or to call this 3502function after a 3503@ifhtml 3504@ref{funct:unur_distr_cont_set_pdf,@command{unur_distr_cont_set_pdf}} 3505@end ifhtml 3506@ifnothtml 3507@command{unur_distr_cont_set_pdf} 3508@end ifnothtml 3509call. 3510@end deftypefn 3511@end ifinfo 3512@ifnotinfo 3513@anchor{funct:unur_distr_cont_set_pdfstr} 3514@deftypefn {} {int} unur_distr_cont_set_pdfstr (UNUR_DISTR* @var{distribution}, const @var{char* pdfstr}) 3515This function provides an alternative way to set a PDF and its 3516derivative of the @var{distribution}. 3517@var{pdfstr} is a character string that contains the formula 3518for the PDF, see @ref{StringFunct,,Function String}, for details. 3519The derivative of the given PDF is computed automatically. 3520See also the remarks for the 3521@ifhtml 3522@ref{funct:unur_distr_cont_set_pdf,@command{unur_distr_cont_set_pdf}} 3523@end ifhtml 3524@ifnothtml 3525@command{unur_distr_cont_set_pdf} 3526@end ifnothtml 3527call. 3528 3529It is not possible to call this funtion twice or to call this 3530function after a 3531@ifhtml 3532@ref{funct:unur_distr_cont_set_pdf,@command{unur_distr_cont_set_pdf}} 3533@end ifhtml 3534@ifnothtml 3535@command{unur_distr_cont_set_pdf} 3536@end ifnothtml 3537call. 3538@end deftypefn 3539@end ifnotinfo 3540 3541@ifinfo 3542@anchor{funct:unur_distr_cont_set_cdfstr} 3543@deftypefn Function {int} unur_distr_cont_set_cdfstr (UNUR_DISTR* @var{distribution}, const @var{char* cdfstr}) 3544This function provides an alternative way to set a CDF; analogously 3545to the 3546@ifhtml 3547@ref{funct:unur_distr_cont_set_pdfstr,@command{unur_distr_cont_set_pdfstr}} 3548@end ifhtml 3549@ifnothtml 3550@command{unur_distr_cont_set_pdfstr} 3551@end ifnothtml 3552call. 3553The PDF and its derivative of the given CDF are computed automatically. 3554@end deftypefn 3555@end ifinfo 3556@ifnotinfo 3557@anchor{funct:unur_distr_cont_set_cdfstr} 3558@deftypefn {} {int} unur_distr_cont_set_cdfstr (UNUR_DISTR* @var{distribution}, const @var{char* cdfstr}) 3559This function provides an alternative way to set a CDF; analogously 3560to the 3561@ifhtml 3562@ref{funct:unur_distr_cont_set_pdfstr,@command{unur_distr_cont_set_pdfstr}} 3563@end ifhtml 3564@ifnothtml 3565@command{unur_distr_cont_set_pdfstr} 3566@end ifnothtml 3567call. 3568The PDF and its derivative of the given CDF are computed automatically. 3569@end deftypefn 3570@end ifnotinfo 3571 3572@ifinfo 3573@anchor{funct:unur_distr_cont_get_pdfstr} 3574@deftypefn Function {char*} unur_distr_cont_get_pdfstr (const @var{UNUR_DISTR* distribution}) 3575@anchor{funct:unur_distr_cont_get_dpdfstr} 3576@deftypefnx Function {char*} unur_distr_cont_get_dpdfstr (const @var{UNUR_DISTR* distribution}) 3577@anchor{funct:unur_distr_cont_get_cdfstr} 3578@deftypefnx Function {char*} unur_distr_cont_get_cdfstr (const @var{UNUR_DISTR* distribution}) 3579Get pointer to respective string for PDF, derivate of PDF, and CDF 3580of @var{distribution} that is given as string (instead of a 3581function pointer). 3582This call allocates memory to produce this string. It should be 3583freed when it is not used any more. 3584@end deftypefn 3585@end ifinfo 3586@ifnotinfo 3587@anchor{funct:unur_distr_cont_get_pdfstr} 3588@deftypefn {} {char*} unur_distr_cont_get_pdfstr (const @var{UNUR_DISTR* distribution}) 3589@anchor{funct:unur_distr_cont_get_dpdfstr} 3590@deftypefnx {} {char*} unur_distr_cont_get_dpdfstr (const @var{UNUR_DISTR* distribution}) 3591@anchor{funct:unur_distr_cont_get_cdfstr} 3592@deftypefnx {} {char*} unur_distr_cont_get_cdfstr (const @var{UNUR_DISTR* distribution}) 3593Get pointer to respective string for PDF, derivate of PDF, and CDF 3594of @var{distribution} that is given as string (instead of a 3595function pointer). 3596This call allocates memory to produce this string. It should be 3597freed when it is not used any more. 3598@end deftypefn 3599@end ifnotinfo 3600 3601@ifinfo 3602@anchor{funct:unur_distr_cont_set_pdfparams} 3603@deftypefn Function {int} unur_distr_cont_set_pdfparams (UNUR_DISTR* @var{distribution}, const @var{double* params}, int @var{n_params}) 3604Sets array of parameters for @var{distribution}. There is an upper limit 3605for the number of parameters @code{n_params}. It is given by the 3606macro @code{UNUR_DISTR_MAXPARAMS} in @file{unuran_config.h}. (It is set to 36075 by default but can be changed to any appropriate nonnegative number.) 3608If @var{n_params} is negative or exceeds this limit no parameters 3609are copied into the distribution object and @code{unur_errno} is set to 3610@code{UNUR_ERR_DISTR_NPARAMS}. 3611 3612For standard distributions from the UNU.RAN library the parameters 3613are checked. Moreover, the domain is updated automatically unless it 3614has been changed before by a 3615@ifhtml 3616@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 3617@end ifhtml 3618@ifnothtml 3619@command{unur_distr_cont_set_domain} 3620@end ifnothtml 3621call. 3622If the given parameters are invalid for the standard distribution, 3623then no parameters are set and an error code is returned. 3624Notice, that the given parameter list for such a distribution is 3625handled in the same way as in the corresponding @command{new} 3626calls, i.e. optional parameters for the PDF that are not present in 3627the given list are (re-)set to their default values. 3628 3629@strong{Important:} If the parameters of a distribution from the 3630UNU.RAN library of standard distributions 3631(@pxref{Stddist,,Standard distributions}) 3632are changed, then neither its mode nor the normalization 3633constant are updated. Please use the respective calls 3634@ifhtml 3635@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 3636@end ifhtml 3637@ifnothtml 3638@command{unur_distr_cont_upd_mode} 3639@end ifnothtml 3640and 3641@ifhtml 3642@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}.} 3643@end ifhtml 3644@ifnothtml 3645@command{unur_distr_cont_upd_pdfarea}. 3646@end ifnothtml 3647Moreover, if the domain has been changed by a 3648@ifhtml 3649@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 3650@end ifhtml 3651@ifnothtml 3652@command{unur_distr_cont_set_domain} 3653@end ifnothtml 3654it is not automatically updated, either. 3655Updating the normalization constant is in particular very important, 3656when the CDF of the distribution is used. 3657@end deftypefn 3658@end ifinfo 3659@ifnotinfo 3660@anchor{funct:unur_distr_cont_set_pdfparams} 3661@deftypefn {} {int} unur_distr_cont_set_pdfparams (UNUR_DISTR* @var{distribution}, const @var{double* params}, int @var{n_params}) 3662Sets array of parameters for @var{distribution}. There is an upper limit 3663for the number of parameters @code{n_params}. It is given by the 3664macro @code{UNUR_DISTR_MAXPARAMS} in @file{unuran_config.h}. (It is set to 36655 by default but can be changed to any appropriate nonnegative number.) 3666If @var{n_params} is negative or exceeds this limit no parameters 3667are copied into the distribution object and @code{unur_errno} is set to 3668@code{UNUR_ERR_DISTR_NPARAMS}. 3669 3670For standard distributions from the UNU.RAN library the parameters 3671are checked. Moreover, the domain is updated automatically unless it 3672has been changed before by a 3673@ifhtml 3674@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 3675@end ifhtml 3676@ifnothtml 3677@command{unur_distr_cont_set_domain} 3678@end ifnothtml 3679call. 3680If the given parameters are invalid for the standard distribution, 3681then no parameters are set and an error code is returned. 3682Notice, that the given parameter list for such a distribution is 3683handled in the same way as in the corresponding @command{new} 3684calls, i.e. optional parameters for the PDF that are not present in 3685the given list are (re-)set to their default values. 3686 3687@strong{Important:} If the parameters of a distribution from the 3688UNU.RAN library of standard distributions 3689(@pxref{Stddist,,Standard distributions}) 3690are changed, then neither its mode nor the normalization 3691constant are updated. Please use the respective calls 3692@ifhtml 3693@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 3694@end ifhtml 3695@ifnothtml 3696@command{unur_distr_cont_upd_mode} 3697@end ifnothtml 3698and 3699@ifhtml 3700@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}.} 3701@end ifhtml 3702@ifnothtml 3703@command{unur_distr_cont_upd_pdfarea}. 3704@end ifnothtml 3705Moreover, if the domain has been changed by a 3706@ifhtml 3707@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 3708@end ifhtml 3709@ifnothtml 3710@command{unur_distr_cont_set_domain} 3711@end ifnothtml 3712it is not automatically updated, either. 3713Updating the normalization constant is in particular very important, 3714when the CDF of the distribution is used. 3715@end deftypefn 3716@end ifnotinfo 3717 3718@ifinfo 3719@anchor{funct:unur_distr_cont_get_pdfparams} 3720@deftypefn Function {int} unur_distr_cont_get_pdfparams (const @var{UNUR_DISTR* distribution}, const @var{double** params}) 3721Get number of parameters of the PDF and set pointer @var{params} to 3722array of parameters. If no parameters are stored in the object, an 3723error code is returned and @code{params} is set to @code{NULL}. 3724 3725@emph{Important:} Do @strong{not} change the entries in @var{params}! 3726@end deftypefn 3727@end ifinfo 3728@ifnotinfo 3729@anchor{funct:unur_distr_cont_get_pdfparams} 3730@deftypefn {} {int} unur_distr_cont_get_pdfparams (const @var{UNUR_DISTR* distribution}, const @var{double** params}) 3731Get number of parameters of the PDF and set pointer @var{params} to 3732array of parameters. If no parameters are stored in the object, an 3733error code is returned and @code{params} is set to @code{NULL}. 3734 3735@emph{Important:} Do @strong{not} change the entries in @var{params}! 3736@end deftypefn 3737@end ifnotinfo 3738 3739@ifinfo 3740@anchor{funct:unur_distr_cont_set_pdfparams_vec} 3741@deftypefn Function {int} unur_distr_cont_set_pdfparams_vec (UNUR_DISTR* @var{distribution}, int @var{par}, const @var{double* param_vec}, int @var{n_param_vec}) 3742This function provides an interface for additional vector parameters for a 3743continuous @var{distribution}. 3744 3745It sets the parameter with number @var{par}. 3746@var{par} indicates directly which of the parameters is set and 3747must be a number between @code{0} and @code{UNUR_DISTR_MAXPARAMS}-1 3748(the upper limit of possible parameters defined in 3749@file{unuran_config.h}; it is set to 5 but can be changed to any 3750appropriate nonnegative number.) 3751 3752The entries of a this parameter are given by the array @var{param_vec} 3753of size @var{n_param_vec}. 3754 3755If @var{param_vec} is @code{NULL} then the corresponding entry is cleared. 3756 3757If an error occurs no parameters are copied into the parameter 3758object @code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 3759@end deftypefn 3760@end ifinfo 3761@ifnotinfo 3762@anchor{funct:unur_distr_cont_set_pdfparams_vec} 3763@deftypefn {} {int} unur_distr_cont_set_pdfparams_vec (UNUR_DISTR* @var{distribution}, int @var{par}, const @var{double* param_vec}, int @var{n_param_vec}) 3764This function provides an interface for additional vector parameters for a 3765continuous @var{distribution}. 3766 3767It sets the parameter with number @var{par}. 3768@var{par} indicates directly which of the parameters is set and 3769must be a number between @code{0} and @code{UNUR_DISTR_MAXPARAMS}-1 3770(the upper limit of possible parameters defined in 3771@file{unuran_config.h}; it is set to 5 but can be changed to any 3772appropriate nonnegative number.) 3773 3774The entries of a this parameter are given by the array @var{param_vec} 3775of size @var{n_param_vec}. 3776 3777If @var{param_vec} is @code{NULL} then the corresponding entry is cleared. 3778 3779If an error occurs no parameters are copied into the parameter 3780object @code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 3781@end deftypefn 3782@end ifnotinfo 3783 3784@ifinfo 3785@anchor{funct:unur_distr_cont_get_pdfparams_vec} 3786@deftypefn Function {int} unur_distr_cont_get_pdfparams_vec (const @var{UNUR_DISTR* distribution}, int @var{par}, const @var{double** param_vecs}) 3787Get parameter of the PDF with number @var{par}. 3788The pointer to the parameter array is stored in @var{param_vecs}, its 3789size is returned by the function. 3790If the requested parameter is not set, then an error code is returned 3791and @code{params} is set to @code{NULL}. 3792 3793@emph{Important:} Do @strong{not} change the entries in @var{param_vecs}! 3794@end deftypefn 3795@end ifinfo 3796@ifnotinfo 3797@anchor{funct:unur_distr_cont_get_pdfparams_vec} 3798@deftypefn {} {int} unur_distr_cont_get_pdfparams_vec (const @var{UNUR_DISTR* distribution}, int @var{par}, const @var{double** param_vecs}) 3799Get parameter of the PDF with number @var{par}. 3800The pointer to the parameter array is stored in @var{param_vecs}, its 3801size is returned by the function. 3802If the requested parameter is not set, then an error code is returned 3803and @code{params} is set to @code{NULL}. 3804 3805@emph{Important:} Do @strong{not} change the entries in @var{param_vecs}! 3806@end deftypefn 3807@end ifnotinfo 3808 3809@ifinfo 3810@anchor{funct:unur_distr_cont_set_logpdfstr} 3811@deftypefn Function {int} unur_distr_cont_set_logpdfstr (UNUR_DISTR* @var{distribution}, const @var{char* logpdfstr}) 3812@anchor{funct:unur_distr_cont_get_logpdfstr} 3813@deftypefnx Function {char*} unur_distr_cont_get_logpdfstr (const @var{UNUR_DISTR* distribution}) 3814@anchor{funct:unur_distr_cont_get_dlogpdfstr} 3815@deftypefnx Function {char*} unur_distr_cont_get_dlogpdfstr (const @var{UNUR_DISTR* distribution}) 3816@anchor{funct:unur_distr_cont_set_logcdfstr} 3817@deftypefnx Function {int} unur_distr_cont_set_logcdfstr (UNUR_DISTR* @var{distribution}, const @var{char* logcdfstr}) 3818@anchor{funct:unur_distr_cont_get_logcdfstr} 3819@deftypefnx Function {char*} unur_distr_cont_get_logcdfstr (const @var{UNUR_DISTR* distribution}) 3820Analogous calls for the logarithm of the density and distribution functions. 3821@end deftypefn 3822@end ifinfo 3823@ifnotinfo 3824@anchor{funct:unur_distr_cont_set_logpdfstr} 3825@deftypefn {} {int} unur_distr_cont_set_logpdfstr (UNUR_DISTR* @var{distribution}, const @var{char* logpdfstr}) 3826@anchor{funct:unur_distr_cont_get_logpdfstr} 3827@deftypefnx {} {char*} unur_distr_cont_get_logpdfstr (const @var{UNUR_DISTR* distribution}) 3828@anchor{funct:unur_distr_cont_get_dlogpdfstr} 3829@deftypefnx {} {char*} unur_distr_cont_get_dlogpdfstr (const @var{UNUR_DISTR* distribution}) 3830@anchor{funct:unur_distr_cont_set_logcdfstr} 3831@deftypefnx {} {int} unur_distr_cont_set_logcdfstr (UNUR_DISTR* @var{distribution}, const @var{char* logcdfstr}) 3832@anchor{funct:unur_distr_cont_get_logcdfstr} 3833@deftypefnx {} {char*} unur_distr_cont_get_logcdfstr (const @var{UNUR_DISTR* distribution}) 3834Analogous calls for the logarithm of the density and distribution functions. 3835@end deftypefn 3836@end ifnotinfo 3837 3838@ifinfo 3839@anchor{funct:unur_distr_cont_set_domain} 3840@deftypefn Function {int} unur_distr_cont_set_domain (UNUR_DISTR* @var{distribution}, double @var{left}, double @var{right}) 3841Set the left and right borders of the domain of the 3842distribution. This can also be used to truncate an existing 3843distribution. For setting the boundary to 3844@math{+/- infinity} 3845use @code{+/- UNUR_INFINITY}. 3846If @var{right} is not strictly greater than @var{left} no domain 3847is set and @code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 3848 3849@emph{Important:} For some technical reasons it is assumed that the density 3850is unimodal and thus monotone on either side of the mode! This is used in 3851the case when the given mode is outside of the original domain. Then the 3852mode is set to the corresponding boundary of the new domain. 3853If this result is not the desired it must be changed by using a 3854@ifhtml 3855@ref{funct:unur_distr_cont_set_mode,@command{unur_distr_cont_set_mode}} 3856@end ifhtml 3857@ifnothtml 3858@command{unur_distr_cont_set_mode} 3859@end ifnothtml 3860call (or a 3861@ifhtml 3862@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 3863@end ifhtml 3864@ifnothtml 3865@command{unur_distr_cont_upd_mode} 3866@end ifnothtml 3867call). The same holds for the center of the distribution. 3868@end deftypefn 3869@end ifinfo 3870@ifnotinfo 3871@anchor{funct:unur_distr_cont_set_domain} 3872@deftypefn {} {int} unur_distr_cont_set_domain (UNUR_DISTR* @var{distribution}, double @var{left}, double @var{right}) 3873Set the left and right borders of the domain of the 3874distribution. This can also be used to truncate an existing 3875distribution. For setting the boundary to 3876@iftex 3877@math{\pm\infty} 3878@end iftex 3879@ifhtml 3880@html 3881+/- infinity 3882@end html 3883@end ifhtml 3884use @code{+/- UNUR_INFINITY}. 3885If @var{right} is not strictly greater than @var{left} no domain 3886is set and @code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 3887 3888@emph{Important:} For some technical reasons it is assumed that the density 3889is unimodal and thus monotone on either side of the mode! This is used in 3890the case when the given mode is outside of the original domain. Then the 3891mode is set to the corresponding boundary of the new domain. 3892If this result is not the desired it must be changed by using a 3893@ifhtml 3894@ref{funct:unur_distr_cont_set_mode,@command{unur_distr_cont_set_mode}} 3895@end ifhtml 3896@ifnothtml 3897@command{unur_distr_cont_set_mode} 3898@end ifnothtml 3899call (or a 3900@ifhtml 3901@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 3902@end ifhtml 3903@ifnothtml 3904@command{unur_distr_cont_upd_mode} 3905@end ifnothtml 3906call). The same holds for the center of the distribution. 3907@end deftypefn 3908@end ifnotinfo 3909 3910@ifinfo 3911@anchor{funct:unur_distr_cont_get_domain} 3912@deftypefn Function {int} unur_distr_cont_get_domain (const @var{UNUR_DISTR* distribution}, double* @var{left}, double* @var{right}) 3913Get the left and right borders of the domain of the 3914distribution. If the domain is not set @code{+/- UNUR_INFINITY} is 3915assumed and returned. No error is reported in this case. 3916@end deftypefn 3917@end ifinfo 3918@ifnotinfo 3919@anchor{funct:unur_distr_cont_get_domain} 3920@deftypefn {} {int} unur_distr_cont_get_domain (const @var{UNUR_DISTR* distribution}, double* @var{left}, double* @var{right}) 3921Get the left and right borders of the domain of the 3922distribution. If the domain is not set @code{+/- UNUR_INFINITY} is 3923assumed and returned. No error is reported in this case. 3924@end deftypefn 3925@end ifnotinfo 3926 3927@ifinfo 3928@anchor{funct:unur_distr_cont_get_truncated} 3929@deftypefn Function {int} unur_distr_cont_get_truncated (const @var{UNUR_DISTR* distribution}, double* @var{left}, double* @var{right}) 3930Get the left and right borders of the (truncated) domain of the 3931distribution. For non-truncated distribution this call is 3932equivalent to the 3933@ifhtml 3934@ref{funct:unur_distr_cont_get_domain,@command{unur_distr_cont_get_domain}} 3935@end ifhtml 3936@ifnothtml 3937@command{unur_distr_cont_get_domain} 3938@end ifnothtml 3939call. 3940 3941This call is only useful in connection with a 3942@ifhtml 3943@ref{funct:unur_get_distr,@command{unur_get_distr}} 3944@end ifhtml 3945@ifnothtml 3946@command{unur_get_distr} 3947@end ifnothtml 3948call 3949to get the boundaries of the sampling region of a generator object. 3950@end deftypefn 3951@end ifinfo 3952@ifnotinfo 3953@anchor{funct:unur_distr_cont_get_truncated} 3954@deftypefn {} {int} unur_distr_cont_get_truncated (const @var{UNUR_DISTR* distribution}, double* @var{left}, double* @var{right}) 3955Get the left and right borders of the (truncated) domain of the 3956distribution. For non-truncated distribution this call is 3957equivalent to the 3958@ifhtml 3959@ref{funct:unur_distr_cont_get_domain,@command{unur_distr_cont_get_domain}} 3960@end ifhtml 3961@ifnothtml 3962@command{unur_distr_cont_get_domain} 3963@end ifnothtml 3964call. 3965 3966This call is only useful in connection with a 3967@ifhtml 3968@ref{funct:unur_get_distr,@command{unur_get_distr}} 3969@end ifhtml 3970@ifnothtml 3971@command{unur_get_distr} 3972@end ifnothtml 3973call 3974to get the boundaries of the sampling region of a generator object. 3975@end deftypefn 3976@end ifnotinfo 3977 3978@ifinfo 3979@anchor{funct:unur_distr_cont_set_hr} 3980@deftypefn Function {int} unur_distr_cont_set_hr (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{hazard}) 3981Set pointer to the hazard rate (HR) of the @var{distribution}. 3982 3983The @emph{hazard rate} (or failure rate) is a mathematical way of 3984describing aging. If the lifetime @i{X} is a random variable with 3985density @i{f(x)} and CDF @i{F(x)} the hazard rate @i{h(x)} 3986is defined as @i{h(x) = f(x) / (1-F(x))}. 3987In other words, @i{h(x)} represents the (conditional) rate of 3988failure of a unit that has survived up to time @i{x} with 3989probability @i{1-F(x)}. 3990The key distribution is the exponential distribution as it has 3991constant hazard rate of value 1. Hazard rates tending to infinity 3992describe distributions with sub-exponential tails whereas 3993distributions with hazard rates tending to zero have heavier tails 3994than the exponential distribution. 3995 3996It is important to note that all these functions must return a 3997result for all floats @i{x}. In case of an overflow the PDF should 3998return @code{UNUR_INFINITY}. 3999 4000@strong{Important}: Do not simply use @i{f(x) / (1-F(x))}, since 4001this is numerically very unstable and results in numerical noise 4002if @i{F(x)} is (very) close to 1. Moreover, if the density @i{f(x)} 4003is known a generation method that uses the density is more 4004appropriate. 4005 4006It is not possible to change such a function. Once the HR is set it 4007cannot be overwritten. This also holds when the HR is given by the 4008@ifhtml 4009@ref{funct:unur_distr_cont_set_hrstr,@command{unur_distr_cont_set_hrstr}} 4010@end ifhtml 4011@ifnothtml 4012@command{unur_distr_cont_set_hrstr} 4013@end ifnothtml 4014call. A new distribution object has to 4015be used instead. 4016@end deftypefn 4017@end ifinfo 4018@ifnotinfo 4019@anchor{funct:unur_distr_cont_set_hr} 4020@deftypefn {} {int} unur_distr_cont_set_hr (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CONT* @var{hazard}) 4021Set pointer to the hazard rate (HR) of the @var{distribution}. 4022 4023The @emph{hazard rate} (or failure rate) is a mathematical way of 4024describing aging. If the lifetime @i{X} is a random variable with 4025density @i{f(x)} and CDF @i{F(x)} the hazard rate @i{h(x)} 4026is defined as @i{h(x) = f(x) / (1-F(x))}. 4027In other words, @i{h(x)} represents the (conditional) rate of 4028failure of a unit that has survived up to time @i{x} with 4029probability @i{1-F(x)}. 4030The key distribution is the exponential distribution as it has 4031constant hazard rate of value 1. Hazard rates tending to infinity 4032describe distributions with sub-exponential tails whereas 4033distributions with hazard rates tending to zero have heavier tails 4034than the exponential distribution. 4035 4036It is important to note that all these functions must return a 4037result for all floats @i{x}. In case of an overflow the PDF should 4038return @code{UNUR_INFINITY}. 4039 4040@strong{Important}: Do not simply use @i{f(x) / (1-F(x))}, since 4041this is numerically very unstable and results in numerical noise 4042if @i{F(x)} is (very) close to 1. Moreover, if the density @i{f(x)} 4043is known a generation method that uses the density is more 4044appropriate. 4045 4046It is not possible to change such a function. Once the HR is set it 4047cannot be overwritten. This also holds when the HR is given by the 4048@ifhtml 4049@ref{funct:unur_distr_cont_set_hrstr,@command{unur_distr_cont_set_hrstr}} 4050@end ifhtml 4051@ifnothtml 4052@command{unur_distr_cont_set_hrstr} 4053@end ifnothtml 4054call. A new distribution object has to 4055be used instead. 4056@end deftypefn 4057@end ifnotinfo 4058 4059@ifinfo 4060@anchor{funct:unur_distr_cont_get_hr} 4061@deftypefn Function {UNUR_FUNCT_CONT*} unur_distr_cont_get_hr (const @var{UNUR_DISTR* distribution}) 4062Get the pointer to the hazard rate of the @var{distribution}. The 4063pointer is of type 4064@code{double funct(double x, const UNUR_DISTR *distr)}. 4065If the corresponding function is not available for the distribution, 4066the @code{NULL} pointer is returned. 4067@end deftypefn 4068@end ifinfo 4069@ifnotinfo 4070@anchor{funct:unur_distr_cont_get_hr} 4071@deftypefn {} {UNUR_FUNCT_CONT*} unur_distr_cont_get_hr (const @var{UNUR_DISTR* distribution}) 4072Get the pointer to the hazard rate of the @var{distribution}. The 4073pointer is of type 4074@code{double funct(double x, const UNUR_DISTR *distr)}. 4075If the corresponding function is not available for the distribution, 4076the @code{NULL} pointer is returned. 4077@end deftypefn 4078@end ifnotinfo 4079 4080@ifinfo 4081@anchor{funct:unur_distr_cont_eval_hr} 4082@deftypefn Function {double} unur_distr_cont_eval_hr (double @var{x}, const @var{UNUR_DISTR* distribution}) 4083Evaluate the hazard rate at @var{x}. 4084Notice that @var{distribution} must not be the @code{NULL} pointer. 4085If the corresponding function is not available for the distribution, 4086@code{UNUR_INFINITY} is returned and @code{unur_errno} is set to 4087@code{UNUR_ERR_DISTR_DATA}. 4088@end deftypefn 4089@end ifinfo 4090@ifnotinfo 4091@anchor{funct:unur_distr_cont_eval_hr} 4092@deftypefn {} {double} unur_distr_cont_eval_hr (double @var{x}, const @var{UNUR_DISTR* distribution}) 4093Evaluate the hazard rate at @var{x}. 4094Notice that @var{distribution} must not be the @code{NULL} pointer. 4095If the corresponding function is not available for the distribution, 4096@code{UNUR_INFINITY} is returned and @code{unur_errno} is set to 4097@code{UNUR_ERR_DISTR_DATA}. 4098@end deftypefn 4099@end ifnotinfo 4100 4101@ifinfo 4102@anchor{funct:unur_distr_cont_set_hrstr} 4103@deftypefn Function {int} unur_distr_cont_set_hrstr (UNUR_DISTR* @var{distribution}, const @var{char* hrstr}) 4104This function provides an alternative way to set a hazard rate and its 4105derivative of the @var{distribution}. 4106@var{hrstr} is a character string that contains the formula 4107for the HR, see @ref{StringFunct,,Function String}, for details. 4108See also the remarks for the 4109@ifhtml 4110@ref{funct:unur_distr_cont_set_hr,@command{unur_distr_cont_set_hr}} 4111@end ifhtml 4112@ifnothtml 4113@command{unur_distr_cont_set_hr} 4114@end ifnothtml 4115call. 4116 4117It is not possible to call this funtion twice or to call this 4118function after a 4119@ifhtml 4120@ref{funct:unur_distr_cont_set_hr,@command{unur_distr_cont_set_hr}} 4121@end ifhtml 4122@ifnothtml 4123@command{unur_distr_cont_set_hr} 4124@end ifnothtml 4125call. 4126@end deftypefn 4127@end ifinfo 4128@ifnotinfo 4129@anchor{funct:unur_distr_cont_set_hrstr} 4130@deftypefn {} {int} unur_distr_cont_set_hrstr (UNUR_DISTR* @var{distribution}, const @var{char* hrstr}) 4131This function provides an alternative way to set a hazard rate and its 4132derivative of the @var{distribution}. 4133@var{hrstr} is a character string that contains the formula 4134for the HR, see @ref{StringFunct,,Function String}, for details. 4135See also the remarks for the 4136@ifhtml 4137@ref{funct:unur_distr_cont_set_hr,@command{unur_distr_cont_set_hr}} 4138@end ifhtml 4139@ifnothtml 4140@command{unur_distr_cont_set_hr} 4141@end ifnothtml 4142call. 4143 4144It is not possible to call this funtion twice or to call this 4145function after a 4146@ifhtml 4147@ref{funct:unur_distr_cont_set_hr,@command{unur_distr_cont_set_hr}} 4148@end ifhtml 4149@ifnothtml 4150@command{unur_distr_cont_set_hr} 4151@end ifnothtml 4152call. 4153@end deftypefn 4154@end ifnotinfo 4155 4156@ifinfo 4157@anchor{funct:unur_distr_cont_get_hrstr} 4158@deftypefn Function {char*} unur_distr_cont_get_hrstr (const @var{UNUR_DISTR* distribution}) 4159Get pointer to string for HR of @var{distribution} that is given 4160via the string interface. This call allocates memory to produce 4161this string. It should be freed when it is not used any more. 4162@end deftypefn 4163@end ifinfo 4164@ifnotinfo 4165@anchor{funct:unur_distr_cont_get_hrstr} 4166@deftypefn {} {char*} unur_distr_cont_get_hrstr (const @var{UNUR_DISTR* distribution}) 4167Get pointer to string for HR of @var{distribution} that is given 4168via the string interface. This call allocates memory to produce 4169this string. It should be freed when it is not used any more. 4170@end deftypefn 4171@end ifnotinfo 4172 4173@subsubheading Derived parameters 4174 4175The following paramters @strong{must} be set whenever one of the essential 4176parameters has been set or changed (and the parameter is required 4177for the chosen method). 4178 4179@ifinfo 4180@anchor{funct:unur_distr_cont_set_mode} 4181@deftypefn Function {int} unur_distr_cont_set_mode (UNUR_DISTR* @var{distribution}, double @var{mode}) 4182Set mode of @var{distribution}. The @var{mode} must be contained in 4183the domain of @var{distribution}. Otherwise the mode is not set and 4184@code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 4185For distributions with unbounded density, this call is used to set 4186the pole of the PDF. Notice that the PDF should then return 4187UNUR_INFINITY at the pole. 4188Notice that the mode is adjusted when the domain is set, see the 4189remark for the 4190@ifhtml 4191@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 4192@end ifhtml 4193@ifnothtml 4194@command{unur_distr_cont_set_domain} 4195@end ifnothtml 4196call. 4197@end deftypefn 4198@end ifinfo 4199@ifnotinfo 4200@anchor{funct:unur_distr_cont_set_mode} 4201@deftypefn {} {int} unur_distr_cont_set_mode (UNUR_DISTR* @var{distribution}, double @var{mode}) 4202Set mode of @var{distribution}. The @var{mode} must be contained in 4203the domain of @var{distribution}. Otherwise the mode is not set and 4204@code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 4205For distributions with unbounded density, this call is used to set 4206the pole of the PDF. Notice that the PDF should then return 4207UNUR_INFINITY at the pole. 4208Notice that the mode is adjusted when the domain is set, see the 4209remark for the 4210@ifhtml 4211@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 4212@end ifhtml 4213@ifnothtml 4214@command{unur_distr_cont_set_domain} 4215@end ifnothtml 4216call. 4217@end deftypefn 4218@end ifnotinfo 4219 4220@ifinfo 4221@anchor{funct:unur_distr_cont_upd_mode} 4222@deftypefn Function {int} unur_distr_cont_upd_mode (UNUR_DISTR* @var{distribution}) 4223Recompute the mode of the @var{distribution}. This call works 4224properly for distribution objects from the UNU.RAN library of 4225standard distributions when the corresponding function is 4226available. Otherwise a (slow) numerical mode finder based on 4227Brent's algorithm is used. If it failes @code{unur_errno} is set to 4228@code{UNUR_ERR_DISTR_DATA}. 4229@end deftypefn 4230@end ifinfo 4231@ifnotinfo 4232@anchor{funct:unur_distr_cont_upd_mode} 4233@deftypefn {} {int} unur_distr_cont_upd_mode (UNUR_DISTR* @var{distribution}) 4234Recompute the mode of the @var{distribution}. This call works 4235properly for distribution objects from the UNU.RAN library of 4236standard distributions when the corresponding function is 4237available. Otherwise a (slow) numerical mode finder based on 4238Brent's algorithm is used. If it failes @code{unur_errno} is set to 4239@code{UNUR_ERR_DISTR_DATA}. 4240@end deftypefn 4241@end ifnotinfo 4242 4243@ifinfo 4244@anchor{funct:unur_distr_cont_get_mode} 4245@deftypefn Function {double} unur_distr_cont_get_mode (UNUR_DISTR* @var{distribution}) 4246Get mode of @var{distribution}. If the mode is not marked as known, 4247@ifhtml 4248@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 4249@end ifhtml 4250@ifnothtml 4251@command{unur_distr_cont_upd_mode} 4252@end ifnothtml 4253is called to compute the mode. If this 4254is not successful @code{UNUR_INFINITY} is returned and 4255@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 4256(There is no difference between the case where no routine for 4257computing the mode is available and the case where no mode exists 4258for the distribution at all.) 4259@end deftypefn 4260@end ifinfo 4261@ifnotinfo 4262@anchor{funct:unur_distr_cont_get_mode} 4263@deftypefn {} {double} unur_distr_cont_get_mode (UNUR_DISTR* @var{distribution}) 4264Get mode of @var{distribution}. If the mode is not marked as known, 4265@ifhtml 4266@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 4267@end ifhtml 4268@ifnothtml 4269@command{unur_distr_cont_upd_mode} 4270@end ifnothtml 4271is called to compute the mode. If this 4272is not successful @code{UNUR_INFINITY} is returned and 4273@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 4274(There is no difference between the case where no routine for 4275computing the mode is available and the case where no mode exists 4276for the distribution at all.) 4277@end deftypefn 4278@end ifnotinfo 4279 4280@ifinfo 4281@anchor{funct:unur_distr_cont_set_center} 4282@deftypefn Function {int} unur_distr_cont_set_center (UNUR_DISTR* @var{distribution}, double @var{center}) 4283Set center of the @var{distribution}. The center is used by some 4284methods to shift the distribution in order to decrease numerical 4285round-off error. If not given explicitly a default is used. 4286 4287@emph{Important:} This call does not check whether the center is 4288contained in the given domain. 4289 4290Default: The mode, if set by a 4291@ifhtml 4292@ref{funct:unur_distr_cont_set_mode,@command{unur_distr_cont_set_mode}} 4293@end ifhtml 4294@ifnothtml 4295@command{unur_distr_cont_set_mode} 4296@end ifnothtml 4297or 4298@ifhtml 4299@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 4300@end ifhtml 4301@ifnothtml 4302@command{unur_distr_cont_upd_mode} 4303@end ifnothtml 4304call; otherwise @code{0}. 4305@end deftypefn 4306@end ifinfo 4307@ifnotinfo 4308@anchor{funct:unur_distr_cont_set_center} 4309@deftypefn {} {int} unur_distr_cont_set_center (UNUR_DISTR* @var{distribution}, double @var{center}) 4310Set center of the @var{distribution}. The center is used by some 4311methods to shift the distribution in order to decrease numerical 4312round-off error. If not given explicitly a default is used. 4313 4314@emph{Important:} This call does not check whether the center is 4315contained in the given domain. 4316 4317Default: The mode, if set by a 4318@ifhtml 4319@ref{funct:unur_distr_cont_set_mode,@command{unur_distr_cont_set_mode}} 4320@end ifhtml 4321@ifnothtml 4322@command{unur_distr_cont_set_mode} 4323@end ifnothtml 4324or 4325@ifhtml 4326@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 4327@end ifhtml 4328@ifnothtml 4329@command{unur_distr_cont_upd_mode} 4330@end ifnothtml 4331call; otherwise @code{0}. 4332@end deftypefn 4333@end ifnotinfo 4334 4335@ifinfo 4336@anchor{funct:unur_distr_cont_get_center} 4337@deftypefn Function {double} unur_distr_cont_get_center (const @var{UNUR_DISTR* distribution}) 4338Get center of the @var{distribution}. It always returns some point 4339as there always exists a default for the center, see 4340@ifhtml 4341@ref{funct:unur_distr_cont_set_center,@command{unur_distr_cont_set_center}.} 4342@end ifhtml 4343@ifnothtml 4344@command{unur_distr_cont_set_center}. 4345@end ifnothtml 4346@end deftypefn 4347@end ifinfo 4348@ifnotinfo 4349@anchor{funct:unur_distr_cont_get_center} 4350@deftypefn {} {double} unur_distr_cont_get_center (const @var{UNUR_DISTR* distribution}) 4351Get center of the @var{distribution}. It always returns some point 4352as there always exists a default for the center, see 4353@ifhtml 4354@ref{funct:unur_distr_cont_set_center,@command{unur_distr_cont_set_center}.} 4355@end ifhtml 4356@ifnothtml 4357@command{unur_distr_cont_set_center}. 4358@end ifnothtml 4359@end deftypefn 4360@end ifnotinfo 4361 4362@ifinfo 4363@anchor{funct:unur_distr_cont_set_pdfarea} 4364@deftypefn Function {int} unur_distr_cont_set_pdfarea (UNUR_DISTR* @var{distribution}, double @var{area}) 4365Set the area below the PDF. If @code{area} is non-positive, no 4366area is set and @code{unur_errno} is set to 4367@code{UNUR_ERR_DISTR_SET}. 4368 4369For a distribution object created by the 4370UNU.RAN library of standard distributions you always should use 4371the 4372@ifhtml 4373@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}.} 4374@end ifhtml 4375@ifnothtml 4376@command{unur_distr_cont_upd_pdfarea}. 4377@end ifnothtml 4378Otherwise there might be 4379ambiguous side-effects. 4380@end deftypefn 4381@end ifinfo 4382@ifnotinfo 4383@anchor{funct:unur_distr_cont_set_pdfarea} 4384@deftypefn {} {int} unur_distr_cont_set_pdfarea (UNUR_DISTR* @var{distribution}, double @var{area}) 4385Set the area below the PDF. If @code{area} is non-positive, no 4386area is set and @code{unur_errno} is set to 4387@code{UNUR_ERR_DISTR_SET}. 4388 4389For a distribution object created by the 4390UNU.RAN library of standard distributions you always should use 4391the 4392@ifhtml 4393@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}.} 4394@end ifhtml 4395@ifnothtml 4396@command{unur_distr_cont_upd_pdfarea}. 4397@end ifnothtml 4398Otherwise there might be 4399ambiguous side-effects. 4400@end deftypefn 4401@end ifnotinfo 4402 4403@ifinfo 4404@anchor{funct:unur_distr_cont_upd_pdfarea} 4405@deftypefn Function {int} unur_distr_cont_upd_pdfarea (UNUR_DISTR* @var{distribution}) 4406Recompute the area below the PDF of the distribution. 4407It only works for distribution objects from the 4408UNU.RAN library of standard distributions when the 4409corresponding function is available. Otherwise @code{unur_errno} is 4410set to @code{UNUR_ERR_DISTR_DATA}. 4411 4412This call also sets the normalization constant such that the given 4413PDF is the derivative of a given CDF, i.e. the area is 1. 4414However, for truncated distributions the area is smaller than 1. 4415 4416The call does not work for distributions from the 4417UNU.RAN library of standard distributions with truncated 4418domain when the CDF is not available. 4419@end deftypefn 4420@end ifinfo 4421@ifnotinfo 4422@anchor{funct:unur_distr_cont_upd_pdfarea} 4423@deftypefn {} {int} unur_distr_cont_upd_pdfarea (UNUR_DISTR* @var{distribution}) 4424Recompute the area below the PDF of the distribution. 4425It only works for distribution objects from the 4426UNU.RAN library of standard distributions when the 4427corresponding function is available. Otherwise @code{unur_errno} is 4428set to @code{UNUR_ERR_DISTR_DATA}. 4429 4430This call also sets the normalization constant such that the given 4431PDF is the derivative of a given CDF, i.e. the area is 1. 4432However, for truncated distributions the area is smaller than 1. 4433 4434The call does not work for distributions from the 4435UNU.RAN library of standard distributions with truncated 4436domain when the CDF is not available. 4437@end deftypefn 4438@end ifnotinfo 4439 4440@ifinfo 4441@anchor{funct:unur_distr_cont_get_pdfarea} 4442@deftypefn Function {double} unur_distr_cont_get_pdfarea (UNUR_DISTR* @var{distribution}) 4443Get the area below the PDF of the distribution. If this area is 4444not known,@* 4445@ifhtml 4446@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 4447@end ifhtml 4448@ifnothtml 4449@command{unur_distr_cont_upd_pdfarea} 4450@end ifnothtml 4451is called to compute 4452it. If this is not successful @code{UNUR_INFINITY} is returned and 4453@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 4454@end deftypefn 4455@end ifinfo 4456@ifnotinfo 4457@anchor{funct:unur_distr_cont_get_pdfarea} 4458@deftypefn {} {double} unur_distr_cont_get_pdfarea (UNUR_DISTR* @var{distribution}) 4459Get the area below the PDF of the distribution. If this area is 4460not known,@* 4461@ifhtml 4462@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 4463@end ifhtml 4464@ifnothtml 4465@command{unur_distr_cont_upd_pdfarea} 4466@end ifnothtml 4467is called to compute 4468it. If this is not successful @code{UNUR_INFINITY} is returned and 4469@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 4470@end deftypefn 4471@end ifnotinfo 4472 4473 4474 4475 4476@c 4477@c end of cont.h 4478@c ------------------------------------- 4479@c ------------------------------------- 4480@c corder.h 4481@c 4482 4483@page 4484@node CORDER 4485@section Continuous univariate order statistics 4486 4487 4488These are special cases of a continuous univariate distributions 4489and thus they have most of these parameters (with the exception 4490that functions cannot be changed). Additionally, 4491 4492@itemize @minus 4493@item there is a call to extract the underlying distribution, 4494 4495@item and a call to handle the @command{rank} of the order 4496statistics. 4497 4498@end itemize 4499 4500 4501@subheading Function reference 4502 4503@ifhtml 4504@itemize 4505@item @ref{funct:unur_distr_corder_new,unur_distr_corder_new} 4506@item @ref{funct:unur_distr_corder_get_distribution,unur_distr_corder_get_distribution} 4507@item @ref{funct:unur_distr_corder_set_rank,unur_distr_corder_set_rank} 4508@item @ref{funct:unur_distr_corder_get_rank,unur_distr_corder_get_rank} 4509@item @ref{funct:unur_distr_corder_get_pdf,unur_distr_corder_get_pdf} 4510@item @ref{funct:unur_distr_corder_get_dpdf,unur_distr_corder_get_dpdf} 4511@item @ref{funct:unur_distr_corder_get_cdf,unur_distr_corder_get_cdf} 4512@item @ref{funct:unur_distr_corder_eval_pdf,unur_distr_corder_eval_pdf} 4513@item @ref{funct:unur_distr_corder_eval_dpdf,unur_distr_corder_eval_dpdf} 4514@item @ref{funct:unur_distr_corder_eval_cdf,unur_distr_corder_eval_cdf} 4515@item @ref{funct:unur_distr_corder_set_pdfparams,unur_distr_corder_set_pdfparams} 4516@item @ref{funct:unur_distr_corder_get_pdfparams,unur_distr_corder_get_pdfparams} 4517@item @ref{funct:unur_distr_corder_set_domain,unur_distr_corder_set_domain} 4518@item @ref{funct:unur_distr_corder_get_domain,unur_distr_corder_get_domain} 4519@item @ref{funct:unur_distr_corder_get_truncated,unur_distr_corder_get_truncated} 4520@item @ref{funct:unur_distr_corder_set_mode,unur_distr_corder_set_mode} 4521@item @ref{funct:unur_distr_corder_upd_mode,unur_distr_corder_upd_mode} 4522@item @ref{funct:unur_distr_corder_get_mode,unur_distr_corder_get_mode} 4523@item @ref{funct:unur_distr_corder_set_pdfarea,unur_distr_corder_set_pdfarea} 4524@item @ref{funct:unur_distr_corder_upd_pdfarea,unur_distr_corder_upd_pdfarea} 4525@item @ref{funct:unur_distr_corder_get_pdfarea,unur_distr_corder_get_pdfarea} 4526@end itemize 4527@end ifhtml 4528 4529 4530@ifinfo 4531@anchor{funct:unur_distr_corder_new} 4532@deftypefn Function {UNUR_DISTR*} unur_distr_corder_new (const @var{UNUR_DISTR* distribution}, int @var{n}, int @var{k}) 4533Create an object for order statistics of sample size 4534@var{n} and rank @var{k}. 4535@var{distribution} must be a pointer to a univariate continuous 4536distribution. 4537The resulting generator object is of the same type as of a 4538@ifhtml 4539@ref{funct:unur_distr_cont_new,@command{unur_distr_cont_new}} 4540@end ifhtml 4541@ifnothtml 4542@command{unur_distr_cont_new} 4543@end ifnothtml 4544call. 4545(However, it cannot be used to make an order statistics out of an 4546order statistics.) 4547 4548To have a PDF for the order statistics, the given distribution 4549object must contain a CDF and a PDF. Moreover, it is assumed that 4550the given PDF is the derivative of the given CDF. Otherwise the 4551area below the PDF of the order statistics is not computed correctly. 4552 4553@emph{Important:} There is no warning when the computed area below 4554the PDF of the order statistics is wrong. 4555@end deftypefn 4556@end ifinfo 4557@ifnotinfo 4558@anchor{funct:unur_distr_corder_new} 4559@deftypefn {} {UNUR_DISTR*} unur_distr_corder_new (const @var{UNUR_DISTR* distribution}, int @var{n}, int @var{k}) 4560Create an object for order statistics of sample size 4561@var{n} and rank @var{k}. 4562@var{distribution} must be a pointer to a univariate continuous 4563distribution. 4564The resulting generator object is of the same type as of a 4565@ifhtml 4566@ref{funct:unur_distr_cont_new,@command{unur_distr_cont_new}} 4567@end ifhtml 4568@ifnothtml 4569@command{unur_distr_cont_new} 4570@end ifnothtml 4571call. 4572(However, it cannot be used to make an order statistics out of an 4573order statistics.) 4574 4575To have a PDF for the order statistics, the given distribution 4576object must contain a CDF and a PDF. Moreover, it is assumed that 4577the given PDF is the derivative of the given CDF. Otherwise the 4578area below the PDF of the order statistics is not computed correctly. 4579 4580@emph{Important:} There is no warning when the computed area below 4581the PDF of the order statistics is wrong. 4582@end deftypefn 4583@end ifnotinfo 4584 4585@ifinfo 4586@anchor{funct:unur_distr_corder_get_distribution} 4587@deftypefn Function {const UNUR_DISTR*} unur_distr_corder_get_distribution (const @var{UNUR_DISTR* distribution}) 4588Get pointer to distribution object for underlying distribution. 4589@end deftypefn 4590@end ifinfo 4591@ifnotinfo 4592@anchor{funct:unur_distr_corder_get_distribution} 4593@deftypefn {} {const UNUR_DISTR*} unur_distr_corder_get_distribution (const @var{UNUR_DISTR* distribution}) 4594Get pointer to distribution object for underlying distribution. 4595@end deftypefn 4596@end ifnotinfo 4597 4598@subsubheading Essential parameters 4599 4600@ifinfo 4601@anchor{funct:unur_distr_corder_set_rank} 4602@deftypefn Function {int} unur_distr_corder_set_rank (UNUR_DISTR* @var{distribution}, int @var{n}, int @var{k}) 4603Change sample size @var{n} and rank @var{k} of order statistics. 4604In case of invalid data, no parameters are changed. 4605The area below the PDF can be set to that of the underlying 4606distribution by a 4607@ifhtml 4608@ref{funct:unur_distr_corder_upd_pdfarea,@command{unur_distr_corder_upd_pdfarea}} 4609@end ifhtml 4610@ifnothtml 4611@command{unur_distr_corder_upd_pdfarea} 4612@end ifnothtml 4613call. 4614@end deftypefn 4615@end ifinfo 4616@ifnotinfo 4617@anchor{funct:unur_distr_corder_set_rank} 4618@deftypefn {} {int} unur_distr_corder_set_rank (UNUR_DISTR* @var{distribution}, int @var{n}, int @var{k}) 4619Change sample size @var{n} and rank @var{k} of order statistics. 4620In case of invalid data, no parameters are changed. 4621The area below the PDF can be set to that of the underlying 4622distribution by a 4623@ifhtml 4624@ref{funct:unur_distr_corder_upd_pdfarea,@command{unur_distr_corder_upd_pdfarea}} 4625@end ifhtml 4626@ifnothtml 4627@command{unur_distr_corder_upd_pdfarea} 4628@end ifnothtml 4629call. 4630@end deftypefn 4631@end ifnotinfo 4632 4633@ifinfo 4634@anchor{funct:unur_distr_corder_get_rank} 4635@deftypefn Function {int} unur_distr_corder_get_rank (const @var{UNUR_DISTR* distribution}, int* @var{n}, int* @var{k}) 4636Get sample size @var{n} and rank @var{k} of order statistics. 4637In case of error an error code is returned. 4638@end deftypefn 4639@end ifinfo 4640@ifnotinfo 4641@anchor{funct:unur_distr_corder_get_rank} 4642@deftypefn {} {int} unur_distr_corder_get_rank (const @var{UNUR_DISTR* distribution}, int* @var{n}, int* @var{k}) 4643Get sample size @var{n} and rank @var{k} of order statistics. 4644In case of error an error code is returned. 4645@end deftypefn 4646@end ifnotinfo 4647 4648Additionally most of the set and get calls for continuous 4649univariate distributions work. The most important exceptions are 4650that the PDF and CDF cannot be changed and 4651@ifhtml 4652@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 4653@end ifhtml 4654@ifnothtml 4655@command{unur_distr_cont_upd_mode} 4656@end ifnothtml 4657uses in any way a (slow) numerical 4658method that might fail. 4659 4660@ifinfo 4661@anchor{funct:unur_distr_corder_get_pdf} 4662@deftypefn Function {UNUR_FUNCT_CONT*} unur_distr_corder_get_pdf (UNUR_DISTR* @var{distribution}) 4663@anchor{funct:unur_distr_corder_get_dpdf} 4664@deftypefnx Function {UNUR_FUNCT_CONT*} unur_distr_corder_get_dpdf (UNUR_DISTR* @var{distribution}) 4665@anchor{funct:unur_distr_corder_get_cdf} 4666@deftypefnx Function {UNUR_FUNCT_CONT*} unur_distr_corder_get_cdf (UNUR_DISTR* @var{distribution}) 4667Get the respective pointer to the PDF, the derivative of the 4668PDF and the CDF of the distribution, respectively. The pointer is of type 4669@code{double funct(double x, UNUR_DISTR *distr)}. 4670If the corresponding function is not available for the distribution, 4671the @code{NULL} pointer is returned. 4672See also 4673@ifhtml 4674@ref{funct:unur_distr_cont_get_pdf,@command{unur_distr_cont_get_pdf}.} 4675@end ifhtml 4676@ifnothtml 4677@command{unur_distr_cont_get_pdf}. 4678@end ifnothtml 4679(Macro) 4680@end deftypefn 4681@end ifinfo 4682@ifnotinfo 4683@anchor{funct:unur_distr_corder_get_pdf} 4684@deftypefn {} {UNUR_FUNCT_CONT*} unur_distr_corder_get_pdf (UNUR_DISTR* @var{distribution}) 4685@anchor{funct:unur_distr_corder_get_dpdf} 4686@deftypefnx {} {UNUR_FUNCT_CONT*} unur_distr_corder_get_dpdf (UNUR_DISTR* @var{distribution}) 4687@anchor{funct:unur_distr_corder_get_cdf} 4688@deftypefnx {} {UNUR_FUNCT_CONT*} unur_distr_corder_get_cdf (UNUR_DISTR* @var{distribution}) 4689Get the respective pointer to the PDF, the derivative of the 4690PDF and the CDF of the distribution, respectively. The pointer is of type 4691@code{double funct(double x, UNUR_DISTR *distr)}. 4692If the corresponding function is not available for the distribution, 4693the @code{NULL} pointer is returned. 4694See also 4695@ifhtml 4696@ref{funct:unur_distr_cont_get_pdf,@command{unur_distr_cont_get_pdf}.} 4697@end ifhtml 4698@ifnothtml 4699@command{unur_distr_cont_get_pdf}. 4700@end ifnothtml 4701(Macro) 4702@end deftypefn 4703@end ifnotinfo 4704 4705@ifinfo 4706@anchor{funct:unur_distr_corder_eval_pdf} 4707@deftypefn Function {double} unur_distr_corder_eval_pdf (double @var{x}, UNUR_DISTR* @var{distribution}) 4708@anchor{funct:unur_distr_corder_eval_dpdf} 4709@deftypefnx Function {double} unur_distr_corder_eval_dpdf (double @var{x}, UNUR_DISTR* @var{distribution}) 4710@anchor{funct:unur_distr_corder_eval_cdf} 4711@deftypefnx Function {double} unur_distr_corder_eval_cdf (double @var{x}, UNUR_DISTR* @var{distribution}) 4712Evaluate the PDF, derivative of the PDF. and the CDF, 4713respectively, at @var{x}. 4714Notice that @var{distribution} must not be the @code{NULL} pointer. 4715If the corresponding function is not available for the distribution, 4716@code{UNUR_INFINITY} is returned and @code{unur_errno} is set to 4717@code{UNUR_ERR_DISTR_DATA}. 4718See also 4719@ifhtml 4720@ref{funct:unur_distr_cont_eval_pdf,@command{unur_distr_cont_eval_pdf}.} 4721@end ifhtml 4722@ifnothtml 4723@command{unur_distr_cont_eval_pdf}. 4724@end ifnothtml 4725(Macro) 4726 4727@emph{IMPORTANT:} 4728In the case of a truncated standard distribution these calls always 4729return the respective values of the @emph{untruncated} distribution! 4730@end deftypefn 4731@end ifinfo 4732@ifnotinfo 4733@anchor{funct:unur_distr_corder_eval_pdf} 4734@deftypefn {} {double} unur_distr_corder_eval_pdf (double @var{x}, UNUR_DISTR* @var{distribution}) 4735@anchor{funct:unur_distr_corder_eval_dpdf} 4736@deftypefnx {} {double} unur_distr_corder_eval_dpdf (double @var{x}, UNUR_DISTR* @var{distribution}) 4737@anchor{funct:unur_distr_corder_eval_cdf} 4738@deftypefnx {} {double} unur_distr_corder_eval_cdf (double @var{x}, UNUR_DISTR* @var{distribution}) 4739Evaluate the PDF, derivative of the PDF. and the CDF, 4740respectively, at @var{x}. 4741Notice that @var{distribution} must not be the @code{NULL} pointer. 4742If the corresponding function is not available for the distribution, 4743@code{UNUR_INFINITY} is returned and @code{unur_errno} is set to 4744@code{UNUR_ERR_DISTR_DATA}. 4745See also 4746@ifhtml 4747@ref{funct:unur_distr_cont_eval_pdf,@command{unur_distr_cont_eval_pdf}.} 4748@end ifhtml 4749@ifnothtml 4750@command{unur_distr_cont_eval_pdf}. 4751@end ifnothtml 4752(Macro) 4753 4754@emph{IMPORTANT:} 4755In the case of a truncated standard distribution these calls always 4756return the respective values of the @emph{untruncated} distribution! 4757@end deftypefn 4758@end ifnotinfo 4759 4760@ifinfo 4761@anchor{funct:unur_distr_corder_set_pdfparams} 4762@deftypefn Function {int} unur_distr_corder_set_pdfparams (UNUR_DISTR* @var{distribution}, double* @var{params}, int @var{n_params}) 4763Set array of parameters for underlying distribution. 4764See 4765@ifhtml 4766@ref{funct:unur_distr_cont_set_pdfparams,@command{unur_distr_cont_set_pdfparams}} 4767@end ifhtml 4768@ifnothtml 4769@command{unur_distr_cont_set_pdfparams} 4770@end ifnothtml 4771for details. 4772(Macro) 4773@end deftypefn 4774@end ifinfo 4775@ifnotinfo 4776@anchor{funct:unur_distr_corder_set_pdfparams} 4777@deftypefn {} {int} unur_distr_corder_set_pdfparams (UNUR_DISTR* @var{distribution}, double* @var{params}, int @var{n_params}) 4778Set array of parameters for underlying distribution. 4779See 4780@ifhtml 4781@ref{funct:unur_distr_cont_set_pdfparams,@command{unur_distr_cont_set_pdfparams}} 4782@end ifhtml 4783@ifnothtml 4784@command{unur_distr_cont_set_pdfparams} 4785@end ifnothtml 4786for details. 4787(Macro) 4788@end deftypefn 4789@end ifnotinfo 4790 4791@ifinfo 4792@anchor{funct:unur_distr_corder_get_pdfparams} 4793@deftypefn Function {int} unur_distr_corder_get_pdfparams (UNUR_DISTR* @var{distribution}, double** @var{params}) 4794Get number of parameters of the PDF of the underlying distribution 4795and set pointer @var{params} to array of parameters. 4796See 4797@ifhtml 4798@ref{funct:unur_distr_cont_get_pdfparams,@command{unur_distr_cont_get_pdfparams}} 4799@end ifhtml 4800@ifnothtml 4801@command{unur_distr_cont_get_pdfparams} 4802@end ifnothtml 4803for details. 4804(Macro) 4805@end deftypefn 4806@end ifinfo 4807@ifnotinfo 4808@anchor{funct:unur_distr_corder_get_pdfparams} 4809@deftypefn {} {int} unur_distr_corder_get_pdfparams (UNUR_DISTR* @var{distribution}, double** @var{params}) 4810Get number of parameters of the PDF of the underlying distribution 4811and set pointer @var{params} to array of parameters. 4812See 4813@ifhtml 4814@ref{funct:unur_distr_cont_get_pdfparams,@command{unur_distr_cont_get_pdfparams}} 4815@end ifhtml 4816@ifnothtml 4817@command{unur_distr_cont_get_pdfparams} 4818@end ifnothtml 4819for details. 4820(Macro) 4821@end deftypefn 4822@end ifnotinfo 4823 4824@ifinfo 4825@anchor{funct:unur_distr_corder_set_domain} 4826@deftypefn Function {int} unur_distr_corder_set_domain (UNUR_DISTR* @var{distribution}, double @var{left}, double @var{right}) 4827Set the left and right borders of the domain of the 4828distribution. 4829See 4830@ifhtml 4831@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 4832@end ifhtml 4833@ifnothtml 4834@command{unur_distr_cont_set_domain} 4835@end ifnothtml 4836for details. 4837(Macro) 4838@end deftypefn 4839@end ifinfo 4840@ifnotinfo 4841@anchor{funct:unur_distr_corder_set_domain} 4842@deftypefn {} {int} unur_distr_corder_set_domain (UNUR_DISTR* @var{distribution}, double @var{left}, double @var{right}) 4843Set the left and right borders of the domain of the 4844distribution. 4845See 4846@ifhtml 4847@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 4848@end ifhtml 4849@ifnothtml 4850@command{unur_distr_cont_set_domain} 4851@end ifnothtml 4852for details. 4853(Macro) 4854@end deftypefn 4855@end ifnotinfo 4856 4857@ifinfo 4858@anchor{funct:unur_distr_corder_get_domain} 4859@deftypefn Function {int} unur_distr_corder_get_domain (UNUR_DISTR* @var{distribution}, double* @var{left}, double* @var{right}) 4860Get the left and right borders of the domain of the 4861distribution. 4862See 4863@ifhtml 4864@ref{funct:unur_distr_cont_get_domain,@command{unur_distr_cont_get_domain}} 4865@end ifhtml 4866@ifnothtml 4867@command{unur_distr_cont_get_domain} 4868@end ifnothtml 4869for details. 4870(Macro) 4871@end deftypefn 4872@end ifinfo 4873@ifnotinfo 4874@anchor{funct:unur_distr_corder_get_domain} 4875@deftypefn {} {int} unur_distr_corder_get_domain (UNUR_DISTR* @var{distribution}, double* @var{left}, double* @var{right}) 4876Get the left and right borders of the domain of the 4877distribution. 4878See 4879@ifhtml 4880@ref{funct:unur_distr_cont_get_domain,@command{unur_distr_cont_get_domain}} 4881@end ifhtml 4882@ifnothtml 4883@command{unur_distr_cont_get_domain} 4884@end ifnothtml 4885for details. 4886(Macro) 4887@end deftypefn 4888@end ifnotinfo 4889 4890@ifinfo 4891@anchor{funct:unur_distr_corder_get_truncated} 4892@deftypefn Function {int} unur_distr_corder_get_truncated (UNUR_DISTR* @var{distribution}, double* @var{left}, double* @var{right}) 4893Get the left and right borders of the (truncated) domain of the 4894distribution. 4895See 4896@ifhtml 4897@ref{funct:unur_distr_cont_get_truncated,@command{unur_distr_cont_get_truncated}} 4898@end ifhtml 4899@ifnothtml 4900@command{unur_distr_cont_get_truncated} 4901@end ifnothtml 4902for details. 4903(Macro) 4904@end deftypefn 4905@end ifinfo 4906@ifnotinfo 4907@anchor{funct:unur_distr_corder_get_truncated} 4908@deftypefn {} {int} unur_distr_corder_get_truncated (UNUR_DISTR* @var{distribution}, double* @var{left}, double* @var{right}) 4909Get the left and right borders of the (truncated) domain of the 4910distribution. 4911See 4912@ifhtml 4913@ref{funct:unur_distr_cont_get_truncated,@command{unur_distr_cont_get_truncated}} 4914@end ifhtml 4915@ifnothtml 4916@command{unur_distr_cont_get_truncated} 4917@end ifnothtml 4918for details. 4919(Macro) 4920@end deftypefn 4921@end ifnotinfo 4922 4923@subsubheading Derived parameters 4924 4925The following paramters @strong{must} be set whenever one of the essential 4926parameters has been set or changed (and the parameter is required 4927for the chosen method). 4928 4929@ifinfo 4930@anchor{funct:unur_distr_corder_set_mode} 4931@deftypefn Function {int} unur_distr_corder_set_mode (UNUR_DISTR* @var{distribution}, double @var{mode}) 4932Set mode of distribution. 4933See also 4934@ifhtml 4935@ref{funct:unur_distr_corder_set_mode,@command{unur_distr_corder_set_mode}.} 4936@end ifhtml 4937@ifnothtml 4938@command{unur_distr_corder_set_mode}. 4939@end ifnothtml 4940(Macro) 4941@end deftypefn 4942@end ifinfo 4943@ifnotinfo 4944@anchor{funct:unur_distr_corder_set_mode} 4945@deftypefn {} {int} unur_distr_corder_set_mode (UNUR_DISTR* @var{distribution}, double @var{mode}) 4946Set mode of distribution. 4947See also 4948@ifhtml 4949@ref{funct:unur_distr_corder_set_mode,@command{unur_distr_corder_set_mode}.} 4950@end ifhtml 4951@ifnothtml 4952@command{unur_distr_corder_set_mode}. 4953@end ifnothtml 4954(Macro) 4955@end deftypefn 4956@end ifnotinfo 4957 4958@ifinfo 4959@anchor{funct:unur_distr_corder_upd_mode} 4960@deftypefn Function {double} unur_distr_corder_upd_mode (UNUR_DISTR* @var{distribution}) 4961Recompute the mode of the distribution numerically. Notice that 4962this routine is slow and might not work properly in every case. 4963See also 4964@ifhtml 4965@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 4966@end ifhtml 4967@ifnothtml 4968@command{unur_distr_cont_upd_mode} 4969@end ifnothtml 4970for further details. 4971(Macro) 4972@end deftypefn 4973@end ifinfo 4974@ifnotinfo 4975@anchor{funct:unur_distr_corder_upd_mode} 4976@deftypefn {} {double} unur_distr_corder_upd_mode (UNUR_DISTR* @var{distribution}) 4977Recompute the mode of the distribution numerically. Notice that 4978this routine is slow and might not work properly in every case. 4979See also 4980@ifhtml 4981@ref{funct:unur_distr_cont_upd_mode,@command{unur_distr_cont_upd_mode}} 4982@end ifhtml 4983@ifnothtml 4984@command{unur_distr_cont_upd_mode} 4985@end ifnothtml 4986for further details. 4987(Macro) 4988@end deftypefn 4989@end ifnotinfo 4990 4991@ifinfo 4992@anchor{funct:unur_distr_corder_get_mode} 4993@deftypefn Function {double} unur_distr_corder_get_mode (UNUR_DISTR* @var{distribution}) 4994Get mode of distribution. 4995See 4996@ifhtml 4997@ref{funct:unur_distr_cont_get_mode,@command{unur_distr_cont_get_mode}} 4998@end ifhtml 4999@ifnothtml 5000@command{unur_distr_cont_get_mode} 5001@end ifnothtml 5002for details. 5003(Macro) 5004@end deftypefn 5005@end ifinfo 5006@ifnotinfo 5007@anchor{funct:unur_distr_corder_get_mode} 5008@deftypefn {} {double} unur_distr_corder_get_mode (UNUR_DISTR* @var{distribution}) 5009Get mode of distribution. 5010See 5011@ifhtml 5012@ref{funct:unur_distr_cont_get_mode,@command{unur_distr_cont_get_mode}} 5013@end ifhtml 5014@ifnothtml 5015@command{unur_distr_cont_get_mode} 5016@end ifnothtml 5017for details. 5018(Macro) 5019@end deftypefn 5020@end ifnotinfo 5021 5022@ifinfo 5023@anchor{funct:unur_distr_corder_set_pdfarea} 5024@deftypefn Function {int} unur_distr_corder_set_pdfarea (UNUR_DISTR* @var{distribution}, double @var{area}) 5025Set the area below the PDF. 5026See 5027@ifhtml 5028@ref{funct:unur_distr_cont_set_pdfarea,@command{unur_distr_cont_set_pdfarea}} 5029@end ifhtml 5030@ifnothtml 5031@command{unur_distr_cont_set_pdfarea} 5032@end ifnothtml 5033for details. 5034(Macro) 5035@end deftypefn 5036@end ifinfo 5037@ifnotinfo 5038@anchor{funct:unur_distr_corder_set_pdfarea} 5039@deftypefn {} {int} unur_distr_corder_set_pdfarea (UNUR_DISTR* @var{distribution}, double @var{area}) 5040Set the area below the PDF. 5041See 5042@ifhtml 5043@ref{funct:unur_distr_cont_set_pdfarea,@command{unur_distr_cont_set_pdfarea}} 5044@end ifhtml 5045@ifnothtml 5046@command{unur_distr_cont_set_pdfarea} 5047@end ifnothtml 5048for details. 5049(Macro) 5050@end deftypefn 5051@end ifnotinfo 5052 5053@ifinfo 5054@anchor{funct:unur_distr_corder_upd_pdfarea} 5055@deftypefn Function {double} unur_distr_corder_upd_pdfarea (UNUR_DISTR* @var{distribution}) 5056Recompute the area below the PDF of the distribution. 5057It only works for order statistics for distribution objects from 5058the UNU.RAN library of standard distributions when the 5059corresponding function is available. 5060@ifhtml 5061@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 5062@end ifhtml 5063@ifnothtml 5064@command{unur_distr_cont_upd_pdfarea} 5065@end ifnothtml 5066assumes that the PDF of the underlying 5067distribution is normalized, i.e. it is the derivative of its CDF. 5068Otherwise the computed area is wrong and there is @strong{no} warning 5069about this failure. 5070See 5071@ifhtml 5072@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 5073@end ifhtml 5074@ifnothtml 5075@command{unur_distr_cont_upd_pdfarea} 5076@end ifnothtml 5077for further details. 5078(Macro) 5079@end deftypefn 5080@end ifinfo 5081@ifnotinfo 5082@anchor{funct:unur_distr_corder_upd_pdfarea} 5083@deftypefn {} {double} unur_distr_corder_upd_pdfarea (UNUR_DISTR* @var{distribution}) 5084Recompute the area below the PDF of the distribution. 5085It only works for order statistics for distribution objects from 5086the UNU.RAN library of standard distributions when the 5087corresponding function is available. 5088@ifhtml 5089@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 5090@end ifhtml 5091@ifnothtml 5092@command{unur_distr_cont_upd_pdfarea} 5093@end ifnothtml 5094assumes that the PDF of the underlying 5095distribution is normalized, i.e. it is the derivative of its CDF. 5096Otherwise the computed area is wrong and there is @strong{no} warning 5097about this failure. 5098See 5099@ifhtml 5100@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 5101@end ifhtml 5102@ifnothtml 5103@command{unur_distr_cont_upd_pdfarea} 5104@end ifnothtml 5105for further details. 5106(Macro) 5107@end deftypefn 5108@end ifnotinfo 5109 5110@ifinfo 5111@anchor{funct:unur_distr_corder_get_pdfarea} 5112@deftypefn Function {double} unur_distr_corder_get_pdfarea (UNUR_DISTR* @var{distribution}) 5113Get the area below the PDF of the distribution. 5114See 5115@ifhtml 5116@ref{funct:unur_distr_cont_get_pdfarea,@command{unur_distr_cont_get_pdfarea}} 5117@end ifhtml 5118@ifnothtml 5119@command{unur_distr_cont_get_pdfarea} 5120@end ifnothtml 5121for details. 5122(Macro) 5123@end deftypefn 5124@end ifinfo 5125@ifnotinfo 5126@anchor{funct:unur_distr_corder_get_pdfarea} 5127@deftypefn {} {double} unur_distr_corder_get_pdfarea (UNUR_DISTR* @var{distribution}) 5128Get the area below the PDF of the distribution. 5129See 5130@ifhtml 5131@ref{funct:unur_distr_cont_get_pdfarea,@command{unur_distr_cont_get_pdfarea}} 5132@end ifhtml 5133@ifnothtml 5134@command{unur_distr_cont_get_pdfarea} 5135@end ifnothtml 5136for details. 5137(Macro) 5138@end deftypefn 5139@end ifnotinfo 5140 5141 5142 5143 5144@c 5145@c end of corder.h 5146@c ------------------------------------- 5147@c ------------------------------------- 5148@c cemp.h 5149@c 5150 5151@page 5152@node CEMP 5153@section Continuous empirical univariate distributions 5154 5155 5156Empirical univariate distributions are derived from observed data. 5157There are two ways to create such a generator object: 5158@enumerate 5159@item 5160By a list of @emph{raw data} by means of a 5161@ifhtml 5162@ref{funct:unur_distr_cemp_set_data,@command{unur_distr_cemp_set_data}} 5163@end ifhtml 5164@ifnothtml 5165@command{unur_distr_cemp_set_data} 5166@end ifnothtml 5167call. 5168@item 5169By a @emph{histogram} (i.e. preprocessed data) by means of a 5170@ifhtml 5171@ref{funct:unur_distr_cemp_set_hist,@command{unur_distr_cemp_set_hist}} 5172@end ifhtml 5173@ifnothtml 5174@command{unur_distr_cemp_set_hist} 5175@end ifnothtml 5176call. 5177@end enumerate 5178How these data are used to sample from the empirical distribution 5179depends from the chosen generation method. 5180 5181 5182@subheading Function reference 5183 5184@ifhtml 5185@itemize 5186@item @ref{funct:unur_distr_cemp_new,unur_distr_cemp_new} 5187@item @ref{funct:unur_distr_cemp_set_data,unur_distr_cemp_set_data} 5188@item @ref{funct:unur_distr_cemp_read_data,unur_distr_cemp_read_data} 5189@item @ref{funct:unur_distr_cemp_get_data,unur_distr_cemp_get_data} 5190@item @ref{funct:unur_distr_cemp_set_hist,unur_distr_cemp_set_hist} 5191@item @ref{funct:unur_distr_cemp_set_hist_prob,unur_distr_cemp_set_hist_prob} 5192@item @ref{funct:unur_distr_cemp_set_hist_domain,unur_distr_cemp_set_hist_domain} 5193@item @ref{funct:unur_distr_cemp_set_hist_bins,unur_distr_cemp_set_hist_bins} 5194@end itemize 5195@end ifhtml 5196 5197 5198@ifinfo 5199@anchor{funct:unur_distr_cemp_new} 5200@deftypefn Function {UNUR_DISTR*} unur_distr_cemp_new (void) 5201Create a new (empty) object for empirical univariate continuous distribution. 5202@end deftypefn 5203@end ifinfo 5204@ifnotinfo 5205@anchor{funct:unur_distr_cemp_new} 5206@deftypefn {} {UNUR_DISTR*} unur_distr_cemp_new (void) 5207Create a new (empty) object for empirical univariate continuous distribution. 5208@end deftypefn 5209@end ifnotinfo 5210 5211@subsubheading Essential parameters 5212 5213@ifinfo 5214@anchor{funct:unur_distr_cemp_set_data} 5215@deftypefn Function {int} unur_distr_cemp_set_data (UNUR_DISTR* @var{distribution}, const @var{double* sample}, int @var{n_sample}) 5216Set observed sample for empirical distribution. 5217@end deftypefn 5218@end ifinfo 5219@ifnotinfo 5220@anchor{funct:unur_distr_cemp_set_data} 5221@deftypefn {} {int} unur_distr_cemp_set_data (UNUR_DISTR* @var{distribution}, const @var{double* sample}, int @var{n_sample}) 5222Set observed sample for empirical distribution. 5223@end deftypefn 5224@end ifnotinfo 5225 5226@ifinfo 5227@anchor{funct:unur_distr_cemp_read_data} 5228@deftypefn Function {int} unur_distr_cemp_read_data (UNUR_DISTR* @var{distribution}, const @var{char* filename}) 5229Read data from file @file{filename}. 5230It reads the first number from each line. 5231Numbers are parsed by means of the C standard routine @command{strtod}. 5232Lines that do not start with @code{+}, @code{-}, @code{.}, or a 5233digit are ignored. (Beware of lines starting with a blank!) 5234 5235In case of an error (file cannot be opened, invalid string for 5236double in line) no data are copied into the distribution object 5237and an error code is returned. 5238@end deftypefn 5239@end ifinfo 5240@ifnotinfo 5241@anchor{funct:unur_distr_cemp_read_data} 5242@deftypefn {} {int} unur_distr_cemp_read_data (UNUR_DISTR* @var{distribution}, const @var{char* filename}) 5243Read data from file @file{filename}. 5244It reads the first number from each line. 5245Numbers are parsed by means of the C standard routine @command{strtod}. 5246Lines that do not start with @code{+}, @code{-}, @code{.}, or a 5247digit are ignored. (Beware of lines starting with a blank!) 5248 5249In case of an error (file cannot be opened, invalid string for 5250double in line) no data are copied into the distribution object 5251and an error code is returned. 5252@end deftypefn 5253@end ifnotinfo 5254 5255@ifinfo 5256@anchor{funct:unur_distr_cemp_get_data} 5257@deftypefn Function {int} unur_distr_cemp_get_data (const @var{UNUR_DISTR* distribution}, const @var{double** sample}) 5258Get number of samples and set pointer @var{sample} to array of 5259observations. If no sample has been given, an error code 5260is returned and @code{sample} is set to @code{NULL}. 5261 5262@emph{Important:} Do @strong{not} change the entries in @var{sample}! 5263@end deftypefn 5264@end ifinfo 5265@ifnotinfo 5266@anchor{funct:unur_distr_cemp_get_data} 5267@deftypefn {} {int} unur_distr_cemp_get_data (const @var{UNUR_DISTR* distribution}, const @var{double** sample}) 5268Get number of samples and set pointer @var{sample} to array of 5269observations. If no sample has been given, an error code 5270is returned and @code{sample} is set to @code{NULL}. 5271 5272@emph{Important:} Do @strong{not} change the entries in @var{sample}! 5273@end deftypefn 5274@end ifnotinfo 5275 5276@ifinfo 5277@anchor{funct:unur_distr_cemp_set_hist} 5278@deftypefn Function {int} unur_distr_cemp_set_hist (UNUR_DISTR* @var{distribution}, const @var{double* prob}, int @var{n_prob}, double @var{xmin}, double @var{xmax}) 5279Set a histogram with bins of equal width. @var{prob} is an array 5280of length @var{n_prob} that contains the probabilities for the bins 5281(in ascending order). @var{xmin} and @var{xmax} give the lower and 5282upper bound of the histogram, respectively. The bins are assumed to 5283have equal width. 5284 5285@emph{Remark:} This is shortcut for calling 5286@ifhtml 5287@ref{funct:unur_distr_cemp_set_hist_prob,@command{unur_distr_cemp_set_hist_prob}} 5288@end ifhtml 5289@ifnothtml 5290@command{unur_distr_cemp_set_hist_prob} 5291@end ifnothtml 5292and 5293@ifhtml 5294@ref{funct:unur_distr_cemp_set_hist_domain,@command{unur_distr_cemp_set_hist_domain}.} 5295@end ifhtml 5296@ifnothtml 5297@command{unur_distr_cemp_set_hist_domain}. 5298@end ifnothtml 5299@emph{Notice:} All sampling methods either use raw data or histogram. 5300It is possible to set both types of data; however, it is not 5301checked whether the given histogran corresponds to possibly given 5302raw data. 5303@end deftypefn 5304@end ifinfo 5305@ifnotinfo 5306@anchor{funct:unur_distr_cemp_set_hist} 5307@deftypefn {} {int} unur_distr_cemp_set_hist (UNUR_DISTR* @var{distribution}, const @var{double* prob}, int @var{n_prob}, double @var{xmin}, double @var{xmax}) 5308Set a histogram with bins of equal width. @var{prob} is an array 5309of length @var{n_prob} that contains the probabilities for the bins 5310(in ascending order). @var{xmin} and @var{xmax} give the lower and 5311upper bound of the histogram, respectively. The bins are assumed to 5312have equal width. 5313 5314@emph{Remark:} This is shortcut for calling 5315@ifhtml 5316@ref{funct:unur_distr_cemp_set_hist_prob,@command{unur_distr_cemp_set_hist_prob}} 5317@end ifhtml 5318@ifnothtml 5319@command{unur_distr_cemp_set_hist_prob} 5320@end ifnothtml 5321and 5322@ifhtml 5323@ref{funct:unur_distr_cemp_set_hist_domain,@command{unur_distr_cemp_set_hist_domain}.} 5324@end ifhtml 5325@ifnothtml 5326@command{unur_distr_cemp_set_hist_domain}. 5327@end ifnothtml 5328@emph{Notice:} All sampling methods either use raw data or histogram. 5329It is possible to set both types of data; however, it is not 5330checked whether the given histogran corresponds to possibly given 5331raw data. 5332@end deftypefn 5333@end ifnotinfo 5334 5335@ifinfo 5336@anchor{funct:unur_distr_cemp_set_hist_prob} 5337@deftypefn Function {int} unur_distr_cemp_set_hist_prob (UNUR_DISTR* @var{distribution}, const @var{double* prob}, int @var{n_prob}) 5338Set probabilities of a histogram with @var{n_prob} bins. 5339Hence @var{prob} must be an array of length @var{n_prob} that 5340contains the probabilities for the bins in ascending order. 5341It is important also to set the location of the bins either 5342with a 5343@ifhtml 5344@ref{funct:unur_distr_cemp_set_hist_domain,@command{unur_distr_cemp_set_hist_domain}} 5345@end ifhtml 5346@ifnothtml 5347@command{unur_distr_cemp_set_hist_domain} 5348@end ifnothtml 5349for bins of equal 5350width or 5351@ifhtml 5352@ref{funct:unur_distr_cemp_set_hist_bins,@command{unur_distr_cemp_set_hist_bins}} 5353@end ifhtml 5354@ifnothtml 5355@command{unur_distr_cemp_set_hist_bins} 5356@end ifnothtml 5357when the bins have 5358different width. 5359 5360@emph{Notice:} All sampling methods either use raw data or histogram. 5361It is possible to set both types of data; however, it is not 5362checked whether the given histogram corresponds to possibly given 5363raw data. 5364@end deftypefn 5365@end ifinfo 5366@ifnotinfo 5367@anchor{funct:unur_distr_cemp_set_hist_prob} 5368@deftypefn {} {int} unur_distr_cemp_set_hist_prob (UNUR_DISTR* @var{distribution}, const @var{double* prob}, int @var{n_prob}) 5369Set probabilities of a histogram with @var{n_prob} bins. 5370Hence @var{prob} must be an array of length @var{n_prob} that 5371contains the probabilities for the bins in ascending order. 5372It is important also to set the location of the bins either 5373with a 5374@ifhtml 5375@ref{funct:unur_distr_cemp_set_hist_domain,@command{unur_distr_cemp_set_hist_domain}} 5376@end ifhtml 5377@ifnothtml 5378@command{unur_distr_cemp_set_hist_domain} 5379@end ifnothtml 5380for bins of equal 5381width or 5382@ifhtml 5383@ref{funct:unur_distr_cemp_set_hist_bins,@command{unur_distr_cemp_set_hist_bins}} 5384@end ifhtml 5385@ifnothtml 5386@command{unur_distr_cemp_set_hist_bins} 5387@end ifnothtml 5388when the bins have 5389different width. 5390 5391@emph{Notice:} All sampling methods either use raw data or histogram. 5392It is possible to set both types of data; however, it is not 5393checked whether the given histogram corresponds to possibly given 5394raw data. 5395@end deftypefn 5396@end ifnotinfo 5397 5398@ifinfo 5399@anchor{funct:unur_distr_cemp_set_hist_domain} 5400@deftypefn Function {int} unur_distr_cemp_set_hist_domain (UNUR_DISTR* @var{distribution}, double @var{xmin}, double @var{xmax}) 5401Set a domain of a histogram with bins of equal width. 5402@var{xmin} and @var{xmax} give the lower and upper bound of the 5403histogram, respectively. 5404@end deftypefn 5405@end ifinfo 5406@ifnotinfo 5407@anchor{funct:unur_distr_cemp_set_hist_domain} 5408@deftypefn {} {int} unur_distr_cemp_set_hist_domain (UNUR_DISTR* @var{distribution}, double @var{xmin}, double @var{xmax}) 5409Set a domain of a histogram with bins of equal width. 5410@var{xmin} and @var{xmax} give the lower and upper bound of the 5411histogram, respectively. 5412@end deftypefn 5413@end ifnotinfo 5414 5415@ifinfo 5416@anchor{funct:unur_distr_cemp_set_hist_bins} 5417@deftypefn Function {int} unur_distr_cemp_set_hist_bins (UNUR_DISTR* @var{distribution}, const @var{double* bins}, int @var{n_bins}) 5418Set location of bins of a histogram with @var{n_bins} bins. 5419Hence @var{bins} must be an array of length @var{n_bins}. 5420The domain of the @var{distribution} is automatically set by 5421this call and overrides any calls to 5422@ifhtml 5423@ref{funct:unur_distr_cemp_set_hist_domain,@command{unur_distr_cemp_set_hist_domain}.} 5424@end ifhtml 5425@ifnothtml 5426@command{unur_distr_cemp_set_hist_domain}. 5427@end ifnothtml 5428@emph{Important:} 5429The probabilities of the bins of the @var{distribution} must be 5430already be set by a 5431@ifhtml 5432@ref{funct:unur_distr_cemp_set_hist_prob,@command{unur_distr_cemp_set_hist_prob}} 5433@end ifhtml 5434@ifnothtml 5435@command{unur_distr_cemp_set_hist_prob} 5436@end ifnothtml 5437(or a 5438@ifhtml 5439@ref{funct:unur_distr_cemp_set_hist,@command{unur_distr_cemp_set_hist}} 5440@end ifhtml 5441@ifnothtml 5442@command{unur_distr_cemp_set_hist} 5443@end ifnothtml 5444call) and the value of 5445@var{n_bins} must equal @var{n_prob}@code{+1} from the 5446corresponding value of the respective call. 5447@end deftypefn 5448@end ifinfo 5449@ifnotinfo 5450@anchor{funct:unur_distr_cemp_set_hist_bins} 5451@deftypefn {} {int} unur_distr_cemp_set_hist_bins (UNUR_DISTR* @var{distribution}, const @var{double* bins}, int @var{n_bins}) 5452Set location of bins of a histogram with @var{n_bins} bins. 5453Hence @var{bins} must be an array of length @var{n_bins}. 5454The domain of the @var{distribution} is automatically set by 5455this call and overrides any calls to 5456@ifhtml 5457@ref{funct:unur_distr_cemp_set_hist_domain,@command{unur_distr_cemp_set_hist_domain}.} 5458@end ifhtml 5459@ifnothtml 5460@command{unur_distr_cemp_set_hist_domain}. 5461@end ifnothtml 5462@emph{Important:} 5463The probabilities of the bins of the @var{distribution} must be 5464already be set by a 5465@ifhtml 5466@ref{funct:unur_distr_cemp_set_hist_prob,@command{unur_distr_cemp_set_hist_prob}} 5467@end ifhtml 5468@ifnothtml 5469@command{unur_distr_cemp_set_hist_prob} 5470@end ifnothtml 5471(or a 5472@ifhtml 5473@ref{funct:unur_distr_cemp_set_hist,@command{unur_distr_cemp_set_hist}} 5474@end ifhtml 5475@ifnothtml 5476@command{unur_distr_cemp_set_hist} 5477@end ifnothtml 5478call) and the value of 5479@var{n_bins} must equal @var{n_prob}@code{+1} from the 5480corresponding value of the respective call. 5481@end deftypefn 5482@end ifnotinfo 5483 5484 5485 5486 5487@c 5488@c end of cemp.h 5489@c ------------------------------------- 5490@c ------------------------------------- 5491@c cvec.h 5492@c 5493 5494@page 5495@node CVEC 5496@section Continuous multivariate distributions 5497 5498 5499The following calls handle multivariate distributions. 5500However, the requirements of particular generation methods is not 5501as unique as for univariate distributions. Moreover, random vector 5502generation methods are still under development. 5503The below functions are a first attempt to handle this situation. 5504 5505Notice that some of the parameters -- when given carelessly -- might 5506contradict to others. For example: Some methods require the 5507marginal distribution and some methods need a standardized form of 5508the marginal distributions, where the actual mean and variance is 5509stored in the mean vector and the covariance matrix, respectively. 5510 5511We also have to mention that some methods might abuse some of the 5512parameters. Please read the discription of the chosen sampling 5513method carfully. 5514 5515The following kind of calls exists: 5516 5517@itemize @minus 5518@item Create a @command{new} instance of a continuous multivariate 5519distribution; 5520 5521@item Handle and evaluate 5522probability density function (PDF, @command{pdf}) and the 5523gradient of the density function (@command{dpdf}). 5524The following is important: 5525@itemize . 5526@item @command{pdf} need not be normalized, i.e., 5527any integrable nonnegative function can be used. 5528@item @command{dpdf} must the derivate of the function provided 5529as @command{pdf}. 5530@end itemize 5531 5532@item Handle and evaluate 5533the logarithm of the probability density function (logPDF, 5534@command{logpdf}) and the gradient of the logarithm of the 5535density function (@command{dlogpdf}). 5536 5537Some methods use the logarithm of the density if available. 5538 5539@item Set (and change) parameters (@command{pdfparams}) and the 5540volume below the graph (@command{pdfvol}) of the given density. 5541 5542@item Set @command{mode} and @command{mean} of the distribution. 5543 5544@item Set the @command{center} of the distribution. 5545It is used by some generation methods to adjust the parameters 5546of the generation algorithms to gain better performance. It can 5547be seens as the location of the ``central part'' of the 5548distribution. 5549 5550@item Handle the @command{covar}iance matrix of the distribution and 5551its @command{cholesky} and @command{inv}verse matrices. 5552 5553@item Set the @command{rankcorr}elation matrix of the distribution. 5554 5555@item Deal with @command{marginal} distributions. 5556 5557@item Set domain of the distribution. 5558 5559@end itemize 5560 5561 5562@subheading Function reference 5563 5564@ifhtml 5565@itemize 5566@item @ref{funct:unur_distr_cvec_new,unur_distr_cvec_new} 5567@item @ref{funct:unur_distr_cvec_set_pdf,unur_distr_cvec_set_pdf} 5568@item @ref{funct:unur_distr_cvec_set_dpdf,unur_distr_cvec_set_dpdf} 5569@item @ref{funct:unur_distr_cvec_set_pdpdf,unur_distr_cvec_set_pdpdf} 5570@item @ref{funct:unur_distr_cvec_get_pdf,unur_distr_cvec_get_pdf} 5571@item @ref{funct:unur_distr_cvec_get_dpdf,unur_distr_cvec_get_dpdf} 5572@item @ref{funct:unur_distr_cvec_eval_pdf,unur_distr_cvec_eval_pdf} 5573@item @ref{funct:unur_distr_cvec_eval_dpdf,unur_distr_cvec_eval_dpdf} 5574@item @ref{funct:unur_distr_cvec_eval_pdpdf,unur_distr_cvec_eval_pdpdf} 5575@item @ref{funct:unur_distr_cvec_set_logpdf,unur_distr_cvec_set_logpdf} 5576@item @ref{funct:unur_distr_cvec_set_dlogpdf,unur_distr_cvec_set_dlogpdf} 5577@item @ref{funct:unur_distr_cvec_set_pdlogpdf,unur_distr_cvec_set_pdlogpdf} 5578@item @ref{funct:unur_distr_cvec_get_logpdf,unur_distr_cvec_get_logpdf} 5579@item @ref{funct:unur_distr_cvec_get_dlogpdf,unur_distr_cvec_get_dlogpdf} 5580@item @ref{funct:unur_distr_cvec_eval_logpdf,unur_distr_cvec_eval_logpdf} 5581@item @ref{funct:unur_distr_cvec_eval_dlogpdf,unur_distr_cvec_eval_dlogpdf} 5582@item @ref{funct:unur_distr_cvec_eval_pdlogpdf,unur_distr_cvec_eval_pdlogpdf} 5583@item @ref{funct:unur_distr_cvec_set_mean,unur_distr_cvec_set_mean} 5584@item @ref{funct:unur_distr_cvec_get_mean,unur_distr_cvec_get_mean} 5585@item @ref{funct:unur_distr_cvec_set_covar,unur_distr_cvec_set_covar} 5586@item @ref{funct:unur_distr_cvec_set_covar_inv,unur_distr_cvec_set_covar_inv} 5587@item @ref{funct:unur_distr_cvec_get_covar,unur_distr_cvec_get_covar} 5588@item @ref{funct:unur_distr_cvec_get_cholesky,unur_distr_cvec_get_cholesky} 5589@item @ref{funct:unur_distr_cvec_get_covar_inv,unur_distr_cvec_get_covar_inv} 5590@item @ref{funct:unur_distr_cvec_set_rankcorr,unur_distr_cvec_set_rankcorr} 5591@item @ref{funct:unur_distr_cvec_get_rankcorr,unur_distr_cvec_get_rankcorr} 5592@item @ref{funct:unur_distr_cvec_get_rk_cholesky,unur_distr_cvec_get_rk_cholesky} 5593@item @ref{funct:unur_distr_cvec_set_marginals,unur_distr_cvec_set_marginals} 5594@item @ref{funct:unur_distr_cvec_set_marginal_array,unur_distr_cvec_set_marginal_array} 5595@item @ref{funct:unur_distr_cvec_set_marginal_list,unur_distr_cvec_set_marginal_list} 5596@item @ref{funct:unur_distr_cvec_get_marginal,unur_distr_cvec_get_marginal} 5597@item @ref{funct:unur_distr_cvec_set_pdfparams,unur_distr_cvec_set_pdfparams} 5598@item @ref{funct:unur_distr_cvec_get_pdfparams,unur_distr_cvec_get_pdfparams} 5599@item @ref{funct:unur_distr_cvec_set_pdfparams_vec,unur_distr_cvec_set_pdfparams_vec} 5600@item @ref{funct:unur_distr_cvec_get_pdfparams_vec,unur_distr_cvec_get_pdfparams_vec} 5601@item @ref{funct:unur_distr_cvec_set_domain_rect,unur_distr_cvec_set_domain_rect} 5602@item @ref{funct:unur_distr_cvec_is_indomain,unur_distr_cvec_is_indomain} 5603@item @ref{funct:unur_distr_cvec_set_mode,unur_distr_cvec_set_mode} 5604@item @ref{funct:unur_distr_cvec_upd_mode,unur_distr_cvec_upd_mode} 5605@item @ref{funct:unur_distr_cvec_get_mode,unur_distr_cvec_get_mode} 5606@item @ref{funct:unur_distr_cvec_set_center,unur_distr_cvec_set_center} 5607@item @ref{funct:unur_distr_cvec_get_center,unur_distr_cvec_get_center} 5608@item @ref{funct:unur_distr_cvec_set_pdfvol,unur_distr_cvec_set_pdfvol} 5609@item @ref{funct:unur_distr_cvec_upd_pdfvol,unur_distr_cvec_upd_pdfvol} 5610@item @ref{funct:unur_distr_cvec_get_pdfvol,unur_distr_cvec_get_pdfvol} 5611@end itemize 5612@end ifhtml 5613 5614 5615@ifinfo 5616@anchor{funct:unur_distr_cvec_new} 5617@deftypefn Function {UNUR_DISTR*} unur_distr_cvec_new (int @var{dim}) 5618Create a new (empty) object for multivariate continuous 5619distribution. @var{dim} is the number of components of the random 5620vector (i.e. its dimension). It is also possible to use dimension 1. 5621Notice, however, that this is treated as a distribution of random 5622vectors with only one component and not as a distribution of 5623real numbers. For the latter 5624@ifhtml 5625@ref{funct:unur_distr_cont_new,@command{unur_distr_cont_new}} 5626@end ifhtml 5627@ifnothtml 5628@command{unur_distr_cont_new} 5629@end ifnothtml 5630should be used 5631to create an object for a univariate distribution. 5632@end deftypefn 5633@end ifinfo 5634@ifnotinfo 5635@anchor{funct:unur_distr_cvec_new} 5636@deftypefn {} {UNUR_DISTR*} unur_distr_cvec_new (int @var{dim}) 5637Create a new (empty) object for multivariate continuous 5638distribution. @var{dim} is the number of components of the random 5639vector (i.e. its dimension). It is also possible to use dimension 1. 5640Notice, however, that this is treated as a distribution of random 5641vectors with only one component and not as a distribution of 5642real numbers. For the latter 5643@ifhtml 5644@ref{funct:unur_distr_cont_new,@command{unur_distr_cont_new}} 5645@end ifhtml 5646@ifnothtml 5647@command{unur_distr_cont_new} 5648@end ifnothtml 5649should be used 5650to create an object for a univariate distribution. 5651@end deftypefn 5652@end ifnotinfo 5653 5654@subsubheading Essential parameters 5655 5656@ifinfo 5657@anchor{funct:unur_distr_cvec_set_pdf} 5658@deftypefn Function {int} unur_distr_cvec_set_pdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CVEC* @var{pdf}) 5659Set respective pointer to the PDF of the @var{distribution}. 5660This function must be of type 5661@code{double funct(const double *x, UNUR_DISTR *distr)}, 5662where @var{x} must be a pointer to a double array of appropriate 5663size (i.e. of the same size as given to the 5664@ifhtml 5665@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5666@end ifhtml 5667@ifnothtml 5668@command{unur_distr_cvec_new} 5669@end ifnothtml 5670call). 5671 5672It is not necessary that the given PDF is normalized, i.e. the 5673integral need not be 1. 5674Nevertheless the volume below the PDF can be provided by a 5675@ifhtml 5676@ref{funct:unur_distr_cvec_set_pdfvol,@command{unur_distr_cvec_set_pdfvol}} 5677@end ifhtml 5678@ifnothtml 5679@command{unur_distr_cvec_set_pdfvol} 5680@end ifnothtml 5681call. 5682 5683It is not possible to change the PDF. Once the PDF is set it cannot 5684be overwritten. This also holds when the logPDF is given. 5685A new distribution object has to be used instead. 5686@end deftypefn 5687@end ifinfo 5688@ifnotinfo 5689@anchor{funct:unur_distr_cvec_set_pdf} 5690@deftypefn {} {int} unur_distr_cvec_set_pdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CVEC* @var{pdf}) 5691Set respective pointer to the PDF of the @var{distribution}. 5692This function must be of type 5693@code{double funct(const double *x, UNUR_DISTR *distr)}, 5694where @var{x} must be a pointer to a double array of appropriate 5695size (i.e. of the same size as given to the 5696@ifhtml 5697@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5698@end ifhtml 5699@ifnothtml 5700@command{unur_distr_cvec_new} 5701@end ifnothtml 5702call). 5703 5704It is not necessary that the given PDF is normalized, i.e. the 5705integral need not be 1. 5706Nevertheless the volume below the PDF can be provided by a 5707@ifhtml 5708@ref{funct:unur_distr_cvec_set_pdfvol,@command{unur_distr_cvec_set_pdfvol}} 5709@end ifhtml 5710@ifnothtml 5711@command{unur_distr_cvec_set_pdfvol} 5712@end ifnothtml 5713call. 5714 5715It is not possible to change the PDF. Once the PDF is set it cannot 5716be overwritten. This also holds when the logPDF is given. 5717A new distribution object has to be used instead. 5718@end deftypefn 5719@end ifnotinfo 5720 5721@ifinfo 5722@anchor{funct:unur_distr_cvec_set_dpdf} 5723@deftypefn Function {int} unur_distr_cvec_set_dpdf (UNUR_DISTR* @var{distribution}, UNUR_VFUNCT_CVEC* @var{dpdf}) 5724Set pointer to the gradient of the PDF. The type of this function must be 5725@code{int funct(double *result, const double *x, UNUR_DISTR *distr)}, 5726where @var{result} and @var{x} must be pointers to double arrays of 5727appropriate size (i.e. of the same size as given to the 5728@ifhtml 5729@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5730@end ifhtml 5731@ifnothtml 5732@command{unur_distr_cvec_new} 5733@end ifnothtml 5734call). 5735The gradient of the PDF is stored in the array @var{result}. 5736The function should return an error code in case of an error and must 5737return @code{UNUR_SUCCESS} otherwise. 5738 5739The given function must be the gradient of the function 5740given by a 5741@ifhtml 5742@ref{funct:unur_distr_cvec_set_pdf,@command{unur_distr_cvec_set_pdf}} 5743@end ifhtml 5744@ifnothtml 5745@command{unur_distr_cvec_set_pdf} 5746@end ifnothtml 5747call. 5748 5749It is not possible to change the gradient of the PDF. Once the dPDF 5750is set it cannot be overwritten. This also holds when the gradient 5751of the logPDF is given. 5752A new distribution object has to be used instead. 5753@end deftypefn 5754@end ifinfo 5755@ifnotinfo 5756@anchor{funct:unur_distr_cvec_set_dpdf} 5757@deftypefn {} {int} unur_distr_cvec_set_dpdf (UNUR_DISTR* @var{distribution}, UNUR_VFUNCT_CVEC* @var{dpdf}) 5758Set pointer to the gradient of the PDF. The type of this function must be 5759@code{int funct(double *result, const double *x, UNUR_DISTR *distr)}, 5760where @var{result} and @var{x} must be pointers to double arrays of 5761appropriate size (i.e. of the same size as given to the 5762@ifhtml 5763@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5764@end ifhtml 5765@ifnothtml 5766@command{unur_distr_cvec_new} 5767@end ifnothtml 5768call). 5769The gradient of the PDF is stored in the array @var{result}. 5770The function should return an error code in case of an error and must 5771return @code{UNUR_SUCCESS} otherwise. 5772 5773The given function must be the gradient of the function 5774given by a 5775@ifhtml 5776@ref{funct:unur_distr_cvec_set_pdf,@command{unur_distr_cvec_set_pdf}} 5777@end ifhtml 5778@ifnothtml 5779@command{unur_distr_cvec_set_pdf} 5780@end ifnothtml 5781call. 5782 5783It is not possible to change the gradient of the PDF. Once the dPDF 5784is set it cannot be overwritten. This also holds when the gradient 5785of the logPDF is given. 5786A new distribution object has to be used instead. 5787@end deftypefn 5788@end ifnotinfo 5789 5790@ifinfo 5791@anchor{funct:unur_distr_cvec_set_pdpdf} 5792@deftypefn Function {int} unur_distr_cvec_set_pdpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCTD_CVEC* @var{pdpdf}) 5793Set pointer to partial derivatives of the PDF. The type of this function must be 5794@code{double funct(const double *x, int coord, UNUR_DISTR *distr)}, 5795where @var{x} must be a pointer to a double array of appropriate 5796size (i.e. of the same size as given to the 5797@ifhtml 5798@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5799@end ifhtml 5800@ifnothtml 5801@command{unur_distr_cvec_new} 5802@end ifnothtml 5803call). @var{coord} is the coordinate for which the partial dervative should be 5804computed. 5805 5806Notice that @var{coord} must be an integer from @{0,@dots{},dim-1@}. 5807 5808It is not possible to change the partial derivative of the PDF. Once the pdPDF 5809is set it cannot be overwritten. This also holds when the partial derivative 5810of the logPDF is given. 5811A new distribution object has to be used instead. 5812@end deftypefn 5813@end ifinfo 5814@ifnotinfo 5815@anchor{funct:unur_distr_cvec_set_pdpdf} 5816@deftypefn {} {int} unur_distr_cvec_set_pdpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCTD_CVEC* @var{pdpdf}) 5817Set pointer to partial derivatives of the PDF. The type of this function must be 5818@code{double funct(const double *x, int coord, UNUR_DISTR *distr)}, 5819where @var{x} must be a pointer to a double array of appropriate 5820size (i.e. of the same size as given to the 5821@ifhtml 5822@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5823@end ifhtml 5824@ifnothtml 5825@command{unur_distr_cvec_new} 5826@end ifnothtml 5827call). @var{coord} is the coordinate for which the partial dervative should be 5828computed. 5829 5830Notice that @var{coord} must be an integer from @{0,@dots{},dim-1@}. 5831 5832It is not possible to change the partial derivative of the PDF. Once the pdPDF 5833is set it cannot be overwritten. This also holds when the partial derivative 5834of the logPDF is given. 5835A new distribution object has to be used instead. 5836@end deftypefn 5837@end ifnotinfo 5838 5839@ifinfo 5840@anchor{funct:unur_distr_cvec_get_pdf} 5841@deftypefn Function {UNUR_FUNCT_CVEC*} unur_distr_cvec_get_pdf (const @var{UNUR_DISTR* distribution}) 5842Get the pointer to the PDF of the @var{distribution}. The 5843pointer is of type 5844@code{double funct(const double *x, UNUR_DISTR *distr)}. 5845If the corresponding function is not available for the 5846@var{distribution}, the @code{NULL} pointer is returned. 5847@end deftypefn 5848@end ifinfo 5849@ifnotinfo 5850@anchor{funct:unur_distr_cvec_get_pdf} 5851@deftypefn {} {UNUR_FUNCT_CVEC*} unur_distr_cvec_get_pdf (const @var{UNUR_DISTR* distribution}) 5852Get the pointer to the PDF of the @var{distribution}. The 5853pointer is of type 5854@code{double funct(const double *x, UNUR_DISTR *distr)}. 5855If the corresponding function is not available for the 5856@var{distribution}, the @code{NULL} pointer is returned. 5857@end deftypefn 5858@end ifnotinfo 5859 5860@ifinfo 5861@anchor{funct:unur_distr_cvec_get_dpdf} 5862@deftypefn Function {UNUR_VFUNCT_CVEC*} unur_distr_cvec_get_dpdf (const @var{UNUR_DISTR* distribution}) 5863Get the pointer to the gradient of the PDF of the 5864@var{distribution}. The pointer is of type 5865@code{int double funct(double *result, const double *x, UNUR_DISTR *distr)}. 5866If the corresponding function is not available for the 5867@var{distribution}, the @code{NULL} pointer is returned. 5868@end deftypefn 5869@end ifinfo 5870@ifnotinfo 5871@anchor{funct:unur_distr_cvec_get_dpdf} 5872@deftypefn {} {UNUR_VFUNCT_CVEC*} unur_distr_cvec_get_dpdf (const @var{UNUR_DISTR* distribution}) 5873Get the pointer to the gradient of the PDF of the 5874@var{distribution}. The pointer is of type 5875@code{int double funct(double *result, const double *x, UNUR_DISTR *distr)}. 5876If the corresponding function is not available for the 5877@var{distribution}, the @code{NULL} pointer is returned. 5878@end deftypefn 5879@end ifnotinfo 5880 5881@ifinfo 5882@anchor{funct:unur_distr_cvec_eval_pdf} 5883@deftypefn Function {double} unur_distr_cvec_eval_pdf (const @var{double* x}, UNUR_DISTR* @var{distribution}) 5884Evaluate the PDF of the @var{distribution} at @var{x}. 5885@var{x} must be a pointer to a double array of appropriate size 5886(i.e. of the same size as given to the 5887@ifhtml 5888@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5889@end ifhtml 5890@ifnothtml 5891@command{unur_distr_cvec_new} 5892@end ifnothtml 5893call) 5894that contains the vector for which the function has to be evaluated. 5895 5896Notice that @var{distribution} must not be the @code{NULL} pointer. 5897If the corresponding function is not available for the 5898@var{distribution}, @code{UNUR_INFINITY} is returned and 5899@code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 5900@end deftypefn 5901@end ifinfo 5902@ifnotinfo 5903@anchor{funct:unur_distr_cvec_eval_pdf} 5904@deftypefn {} {double} unur_distr_cvec_eval_pdf (const @var{double* x}, UNUR_DISTR* @var{distribution}) 5905Evaluate the PDF of the @var{distribution} at @var{x}. 5906@var{x} must be a pointer to a double array of appropriate size 5907(i.e. of the same size as given to the 5908@ifhtml 5909@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5910@end ifhtml 5911@ifnothtml 5912@command{unur_distr_cvec_new} 5913@end ifnothtml 5914call) 5915that contains the vector for which the function has to be evaluated. 5916 5917Notice that @var{distribution} must not be the @code{NULL} pointer. 5918If the corresponding function is not available for the 5919@var{distribution}, @code{UNUR_INFINITY} is returned and 5920@code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 5921@end deftypefn 5922@end ifnotinfo 5923 5924@ifinfo 5925@anchor{funct:unur_distr_cvec_eval_dpdf} 5926@deftypefn Function {int} unur_distr_cvec_eval_dpdf (double* @var{result}, const @var{double* x}, UNUR_DISTR* @var{distribution}) 5927Evaluate the gradient of the PDF of the @var{distribution} at 5928@var{x}. 5929The result is stored in the double array @var{result}. 5930Both @var{result} and @var{x} must be pointer to double arrays of 5931appropriate size (i.e. of the same size as given to the 5932@ifhtml 5933@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5934@end ifhtml 5935@ifnothtml 5936@command{unur_distr_cvec_new} 5937@end ifnothtml 5938call). 5939 5940Notice that @var{distribution} must not be the @code{NULL} pointer. 5941If the corresponding function is not available for the 5942@var{distribution}, an error code is returned and @code{unur_errno} 5943is set to @code{UNUR_ERR_DISTR_DATA} (@var{result} is left unmodified). 5944@end deftypefn 5945@end ifinfo 5946@ifnotinfo 5947@anchor{funct:unur_distr_cvec_eval_dpdf} 5948@deftypefn {} {int} unur_distr_cvec_eval_dpdf (double* @var{result}, const @var{double* x}, UNUR_DISTR* @var{distribution}) 5949Evaluate the gradient of the PDF of the @var{distribution} at 5950@var{x}. 5951The result is stored in the double array @var{result}. 5952Both @var{result} and @var{x} must be pointer to double arrays of 5953appropriate size (i.e. of the same size as given to the 5954@ifhtml 5955@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5956@end ifhtml 5957@ifnothtml 5958@command{unur_distr_cvec_new} 5959@end ifnothtml 5960call). 5961 5962Notice that @var{distribution} must not be the @code{NULL} pointer. 5963If the corresponding function is not available for the 5964@var{distribution}, an error code is returned and @code{unur_errno} 5965is set to @code{UNUR_ERR_DISTR_DATA} (@var{result} is left unmodified). 5966@end deftypefn 5967@end ifnotinfo 5968 5969@ifinfo 5970@anchor{funct:unur_distr_cvec_eval_pdpdf} 5971@deftypefn Function {double} unur_distr_cvec_eval_pdpdf (const @var{double* x}, int @var{coord}, UNUR_DISTR* @var{distribution}) 5972Evaluate the partial derivative of the PDF of the @var{distribution} 5973at @var{x} for the coordinate @var{coord}. 5974@var{x} must be a pointer to a double array of appropriate size 5975(i.e. of the same size as given to the 5976@ifhtml 5977@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 5978@end ifhtml 5979@ifnothtml 5980@command{unur_distr_cvec_new} 5981@end ifnothtml 5982call) 5983that contains the vector for which the function has to be evaluated. 5984 5985Notice that @var{coord} must be an integer from @{0,@dots{},dim-1@}. 5986 5987Notice that @var{distribution} must not be the @code{NULL} pointer. 5988If the corresponding function is not available for the 5989@var{distribution}, @code{UNUR_INFINITY} is returned and 5990@code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 5991@end deftypefn 5992@end ifinfo 5993@ifnotinfo 5994@anchor{funct:unur_distr_cvec_eval_pdpdf} 5995@deftypefn {} {double} unur_distr_cvec_eval_pdpdf (const @var{double* x}, int @var{coord}, UNUR_DISTR* @var{distribution}) 5996Evaluate the partial derivative of the PDF of the @var{distribution} 5997at @var{x} for the coordinate @var{coord}. 5998@var{x} must be a pointer to a double array of appropriate size 5999(i.e. of the same size as given to the 6000@ifhtml 6001@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 6002@end ifhtml 6003@ifnothtml 6004@command{unur_distr_cvec_new} 6005@end ifnothtml 6006call) 6007that contains the vector for which the function has to be evaluated. 6008 6009Notice that @var{coord} must be an integer from @{0,@dots{},dim-1@}. 6010 6011Notice that @var{distribution} must not be the @code{NULL} pointer. 6012If the corresponding function is not available for the 6013@var{distribution}, @code{UNUR_INFINITY} is returned and 6014@code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 6015@end deftypefn 6016@end ifnotinfo 6017 6018@ifinfo 6019@anchor{funct:unur_distr_cvec_set_logpdf} 6020@deftypefn Function {int} unur_distr_cvec_set_logpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CVEC* @var{logpdf}) 6021@anchor{funct:unur_distr_cvec_set_dlogpdf} 6022@deftypefnx Function {int} unur_distr_cvec_set_dlogpdf (UNUR_DISTR* @var{distribution}, UNUR_VFUNCT_CVEC* @var{dlogpdf}) 6023@anchor{funct:unur_distr_cvec_set_pdlogpdf} 6024@deftypefnx Function {int} unur_distr_cvec_set_pdlogpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCTD_CVEC* @var{pdlogpdf}) 6025@anchor{funct:unur_distr_cvec_get_logpdf} 6026@deftypefnx Function {UNUR_FUNCT_CVEC*} unur_distr_cvec_get_logpdf (const @var{UNUR_DISTR* distribution}) 6027@anchor{funct:unur_distr_cvec_get_dlogpdf} 6028@deftypefnx Function {UNUR_VFUNCT_CVEC*} unur_distr_cvec_get_dlogpdf (const @var{UNUR_DISTR* distribution}) 6029@anchor{funct:unur_distr_cvec_eval_logpdf} 6030@deftypefnx Function {double} unur_distr_cvec_eval_logpdf (const @var{double* x}, UNUR_DISTR* @var{distribution}) 6031@anchor{funct:unur_distr_cvec_eval_dlogpdf} 6032@deftypefnx Function {int} unur_distr_cvec_eval_dlogpdf (double* @var{result}, const @var{double* x}, UNUR_DISTR* @var{distribution}) 6033@anchor{funct:unur_distr_cvec_eval_pdlogpdf} 6034@deftypefnx Function {double} unur_distr_cvec_eval_pdlogpdf (const @var{double* x}, int @var{coord}, UNUR_DISTR* @var{distribution}) 6035Analogous calls for the logarithm of the density function. 6036@end deftypefn 6037@end ifinfo 6038@ifnotinfo 6039@anchor{funct:unur_distr_cvec_set_logpdf} 6040@deftypefn {} {int} unur_distr_cvec_set_logpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_CVEC* @var{logpdf}) 6041@anchor{funct:unur_distr_cvec_set_dlogpdf} 6042@deftypefnx {} {int} unur_distr_cvec_set_dlogpdf (UNUR_DISTR* @var{distribution}, UNUR_VFUNCT_CVEC* @var{dlogpdf}) 6043@anchor{funct:unur_distr_cvec_set_pdlogpdf} 6044@deftypefnx {} {int} unur_distr_cvec_set_pdlogpdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCTD_CVEC* @var{pdlogpdf}) 6045@anchor{funct:unur_distr_cvec_get_logpdf} 6046@deftypefnx {} {UNUR_FUNCT_CVEC*} unur_distr_cvec_get_logpdf (const @var{UNUR_DISTR* distribution}) 6047@anchor{funct:unur_distr_cvec_get_dlogpdf} 6048@deftypefnx {} {UNUR_VFUNCT_CVEC*} unur_distr_cvec_get_dlogpdf (const @var{UNUR_DISTR* distribution}) 6049@anchor{funct:unur_distr_cvec_eval_logpdf} 6050@deftypefnx {} {double} unur_distr_cvec_eval_logpdf (const @var{double* x}, UNUR_DISTR* @var{distribution}) 6051@anchor{funct:unur_distr_cvec_eval_dlogpdf} 6052@deftypefnx {} {int} unur_distr_cvec_eval_dlogpdf (double* @var{result}, const @var{double* x}, UNUR_DISTR* @var{distribution}) 6053@anchor{funct:unur_distr_cvec_eval_pdlogpdf} 6054@deftypefnx {} {double} unur_distr_cvec_eval_pdlogpdf (const @var{double* x}, int @var{coord}, UNUR_DISTR* @var{distribution}) 6055Analogous calls for the logarithm of the density function. 6056@end deftypefn 6057@end ifnotinfo 6058 6059@ifinfo 6060@anchor{funct:unur_distr_cvec_set_mean} 6061@deftypefn Function {int} unur_distr_cvec_set_mean (UNUR_DISTR* @var{distribution}, const @var{double* mean}) 6062Set mean vector for multivariate @var{distribution}. 6063@var{mean} must be a pointer to an array of size @code{dim}, where 6064@code{dim} is the dimension returned by 6065@ifhtml 6066@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6067@end ifhtml 6068@ifnothtml 6069@command{unur_distr_get_dim}. 6070@end ifnothtml 6071A @code{NULL} pointer for @var{mean} is interpreted as the zero 6072vector (0,@dots{},0). 6073 6074@strong{Important:} If the parameters of a distribution from the 6075UNU.RAN library of standard distributions 6076(@pxref{Stddist,,Standard distributions}) 6077are changed, then neither its mode nor the normalization 6078constant are updated. Please use the respective calls 6079@ifhtml 6080@ref{funct:unur_distr_cvec_upd_mode,@command{unur_distr_cvec_upd_mode}} 6081@end ifhtml 6082@ifnothtml 6083@command{unur_distr_cvec_upd_mode} 6084@end ifnothtml 6085and 6086@ifhtml 6087@ref{funct:unur_distr_cvec_upd_pdfvol,@command{unur_distr_cvec_upd_pdfvol}.} 6088@end ifhtml 6089@ifnothtml 6090@command{unur_distr_cvec_upd_pdfvol}. 6091@end ifnothtml 6092@end deftypefn 6093@end ifinfo 6094@ifnotinfo 6095@anchor{funct:unur_distr_cvec_set_mean} 6096@deftypefn {} {int} unur_distr_cvec_set_mean (UNUR_DISTR* @var{distribution}, const @var{double* mean}) 6097Set mean vector for multivariate @var{distribution}. 6098@var{mean} must be a pointer to an array of size @code{dim}, where 6099@code{dim} is the dimension returned by 6100@ifhtml 6101@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6102@end ifhtml 6103@ifnothtml 6104@command{unur_distr_get_dim}. 6105@end ifnothtml 6106A @code{NULL} pointer for @var{mean} is interpreted as the zero 6107vector (0,@dots{},0). 6108 6109@strong{Important:} If the parameters of a distribution from the 6110UNU.RAN library of standard distributions 6111(@pxref{Stddist,,Standard distributions}) 6112are changed, then neither its mode nor the normalization 6113constant are updated. Please use the respective calls 6114@ifhtml 6115@ref{funct:unur_distr_cvec_upd_mode,@command{unur_distr_cvec_upd_mode}} 6116@end ifhtml 6117@ifnothtml 6118@command{unur_distr_cvec_upd_mode} 6119@end ifnothtml 6120and 6121@ifhtml 6122@ref{funct:unur_distr_cvec_upd_pdfvol,@command{unur_distr_cvec_upd_pdfvol}.} 6123@end ifhtml 6124@ifnothtml 6125@command{unur_distr_cvec_upd_pdfvol}. 6126@end ifnothtml 6127@end deftypefn 6128@end ifnotinfo 6129 6130@ifinfo 6131@anchor{funct:unur_distr_cvec_get_mean} 6132@deftypefn Function {const double*} unur_distr_cvec_get_mean (const @var{UNUR_DISTR* distribution}) 6133Get the mean vector of the @var{distribution}. The function returns a 6134pointer to an array of size @code{dim}. 6135If the mean vector is not marked as known the @code{NULL} pointer is 6136returned and @code{unur_errno} is set to 6137@code{UNUR_ERR_DISTR_GET}. 6138 6139@emph{Important:} Do @strong{not} modify the array that holds the 6140mean vector! 6141@end deftypefn 6142@end ifinfo 6143@ifnotinfo 6144@anchor{funct:unur_distr_cvec_get_mean} 6145@deftypefn {} {const double*} unur_distr_cvec_get_mean (const @var{UNUR_DISTR* distribution}) 6146Get the mean vector of the @var{distribution}. The function returns a 6147pointer to an array of size @code{dim}. 6148If the mean vector is not marked as known the @code{NULL} pointer is 6149returned and @code{unur_errno} is set to 6150@code{UNUR_ERR_DISTR_GET}. 6151 6152@emph{Important:} Do @strong{not} modify the array that holds the 6153mean vector! 6154@end deftypefn 6155@end ifnotinfo 6156 6157@ifinfo 6158@anchor{funct:unur_distr_cvec_set_covar} 6159@deftypefn Function {int} unur_distr_cvec_set_covar (UNUR_DISTR* @var{distribution}, const @var{double* covar}) 6160Set covariance matrix for multivariate @var{distribution}. 6161@var{covar} must be a pointer to an array of size 6162@code{dim} x @code{dim}, where @code{dim} is the dimension returned 6163by 6164@ifhtml 6165@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6166@end ifhtml 6167@ifnothtml 6168@command{unur_distr_get_dim}. 6169@end ifnothtml 6170The rows of the matrix have to be stored 6171consecutively in this array. 6172 6173@var{covar} must be a variance-covariance matrix of the 6174@var{distribution}, i.e. it must be symmetric and positive definit and 6175its diagonal entries (i.e. the variance of the components of the 6176random vector) must be strictly positive. 6177The Cholesky factor is computed (and stored) to verify the positive 6178definiteness condition. 6179Notice that the inverse of the given covariance matrix is 6180automatically computed when it is requested by some routine. 6181Notice that the computation of this inverse matrix is unstable in 6182case of high correlations and/or high dimensions. Thus it might 6183fail and methods that require this inverse cannot be used. 6184As an alternative the inverse of the covariance matrix can be 6185directly set by a 6186@ifhtml 6187@ref{funct:unur_distr_cvec_set_covar_inv,@command{unur_distr_cvec_set_covar_inv}} 6188@end ifhtml 6189@ifnothtml 6190@command{unur_distr_cvec_set_covar_inv} 6191@end ifnothtml 6192call. 6193 6194A @code{NULL} pointer for @var{covar} is interpreted as the 6195identity matrix. 6196 6197@emph{Important:} This entry is abused in some methods which do not 6198require the covariance matrix. It is then used to perform some 6199transformation to obtain better performance. 6200 6201@emph{Important:} In case of an error (e.g. because @var{covar} is 6202not a valid covariance matrix) an error code is returned. 6203Moreover, the covariance matrix is not set and is marked as 6204unknown. A previously set covariance matrix is then no longer 6205available. 6206 6207@strong{Important:} If the parameters of a distribution from the 6208UNU.RAN library of standard distributions 6209(@pxref{Stddist,,Standard distributions}) 6210are changed, then neither its mode nor the normalization 6211constant are updated. Please use the respective calls 6212@ifhtml 6213@ref{funct:unur_distr_cvec_upd_mode,@command{unur_distr_cvec_upd_mode}} 6214@end ifhtml 6215@ifnothtml 6216@command{unur_distr_cvec_upd_mode} 6217@end ifnothtml 6218and 6219@ifhtml 6220@ref{funct:unur_distr_cvec_upd_pdfvol,@command{unur_distr_cvec_upd_pdfvol}.} 6221@end ifhtml 6222@ifnothtml 6223@command{unur_distr_cvec_upd_pdfvol}. 6224@end ifnothtml 6225@emph{Remark:} UNU.RAN does not check whether the an eventually 6226set covariance matrix and a rank-correlation matrix do not 6227contradict each other. 6228@end deftypefn 6229@end ifinfo 6230@ifnotinfo 6231@anchor{funct:unur_distr_cvec_set_covar} 6232@deftypefn {} {int} unur_distr_cvec_set_covar (UNUR_DISTR* @var{distribution}, const @var{double* covar}) 6233Set covariance matrix for multivariate @var{distribution}. 6234@var{covar} must be a pointer to an array of size 6235@code{dim} x @code{dim}, where @code{dim} is the dimension returned 6236by 6237@ifhtml 6238@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6239@end ifhtml 6240@ifnothtml 6241@command{unur_distr_get_dim}. 6242@end ifnothtml 6243The rows of the matrix have to be stored 6244consecutively in this array. 6245 6246@var{covar} must be a variance-covariance matrix of the 6247@var{distribution}, i.e. it must be symmetric and positive definit and 6248its diagonal entries (i.e. the variance of the components of the 6249random vector) must be strictly positive. 6250The Cholesky factor is computed (and stored) to verify the positive 6251definiteness condition. 6252Notice that the inverse of the given covariance matrix is 6253automatically computed when it is requested by some routine. 6254Notice that the computation of this inverse matrix is unstable in 6255case of high correlations and/or high dimensions. Thus it might 6256fail and methods that require this inverse cannot be used. 6257As an alternative the inverse of the covariance matrix can be 6258directly set by a 6259@ifhtml 6260@ref{funct:unur_distr_cvec_set_covar_inv,@command{unur_distr_cvec_set_covar_inv}} 6261@end ifhtml 6262@ifnothtml 6263@command{unur_distr_cvec_set_covar_inv} 6264@end ifnothtml 6265call. 6266 6267A @code{NULL} pointer for @var{covar} is interpreted as the 6268identity matrix. 6269 6270@emph{Important:} This entry is abused in some methods which do not 6271require the covariance matrix. It is then used to perform some 6272transformation to obtain better performance. 6273 6274@emph{Important:} In case of an error (e.g. because @var{covar} is 6275not a valid covariance matrix) an error code is returned. 6276Moreover, the covariance matrix is not set and is marked as 6277unknown. A previously set covariance matrix is then no longer 6278available. 6279 6280@strong{Important:} If the parameters of a distribution from the 6281UNU.RAN library of standard distributions 6282(@pxref{Stddist,,Standard distributions}) 6283are changed, then neither its mode nor the normalization 6284constant are updated. Please use the respective calls 6285@ifhtml 6286@ref{funct:unur_distr_cvec_upd_mode,@command{unur_distr_cvec_upd_mode}} 6287@end ifhtml 6288@ifnothtml 6289@command{unur_distr_cvec_upd_mode} 6290@end ifnothtml 6291and 6292@ifhtml 6293@ref{funct:unur_distr_cvec_upd_pdfvol,@command{unur_distr_cvec_upd_pdfvol}.} 6294@end ifhtml 6295@ifnothtml 6296@command{unur_distr_cvec_upd_pdfvol}. 6297@end ifnothtml 6298@emph{Remark:} UNU.RAN does not check whether the an eventually 6299set covariance matrix and a rank-correlation matrix do not 6300contradict each other. 6301@end deftypefn 6302@end ifnotinfo 6303 6304@ifinfo 6305@anchor{funct:unur_distr_cvec_set_covar_inv} 6306@deftypefn Function {int} unur_distr_cvec_set_covar_inv (UNUR_DISTR* @var{distribution}, const @var{double* covar_inv}) 6307Set inverse of the covariance matrix for multivariate @var{distribution}. 6308@var{covar_inv} must be a pointer to an array of size 6309@code{dim} x @code{dim}, where @code{dim} is the dimension returned 6310by 6311@ifhtml 6312@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6313@end ifhtml 6314@ifnothtml 6315@command{unur_distr_get_dim}. 6316@end ifnothtml 6317The rows of the matrix have to be stored 6318consecutively in this array. 6319 6320@var{covar_inv} must be symmetric and positive definit. Only the 6321symmetry of the matrix is checked. 6322 6323A @code{NULL} pointer for @var{covar_inv} is interpreted as the identity matrix. 6324 6325@emph{Important:} In case of an error (because @var{covar_inv} is 6326not symetric) an error code is returned. 6327Moreover, the inverse of the covariance matrix is not set and is 6328marked as unknown. A previously set inverse matrix is then no longer 6329available. 6330 6331@emph{Remark:} UNU.RAN does not check whether the given matrix is 6332positive definit. 6333 6334@emph{Remark:} UNU.RAN does not check whether the matrix 6335@var{covar_inv} is the inverse of the eventually set covariance 6336matrix. 6337@end deftypefn 6338@end ifinfo 6339@ifnotinfo 6340@anchor{funct:unur_distr_cvec_set_covar_inv} 6341@deftypefn {} {int} unur_distr_cvec_set_covar_inv (UNUR_DISTR* @var{distribution}, const @var{double* covar_inv}) 6342Set inverse of the covariance matrix for multivariate @var{distribution}. 6343@var{covar_inv} must be a pointer to an array of size 6344@code{dim} x @code{dim}, where @code{dim} is the dimension returned 6345by 6346@ifhtml 6347@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6348@end ifhtml 6349@ifnothtml 6350@command{unur_distr_get_dim}. 6351@end ifnothtml 6352The rows of the matrix have to be stored 6353consecutively in this array. 6354 6355@var{covar_inv} must be symmetric and positive definit. Only the 6356symmetry of the matrix is checked. 6357 6358A @code{NULL} pointer for @var{covar_inv} is interpreted as the identity matrix. 6359 6360@emph{Important:} In case of an error (because @var{covar_inv} is 6361not symetric) an error code is returned. 6362Moreover, the inverse of the covariance matrix is not set and is 6363marked as unknown. A previously set inverse matrix is then no longer 6364available. 6365 6366@emph{Remark:} UNU.RAN does not check whether the given matrix is 6367positive definit. 6368 6369@emph{Remark:} UNU.RAN does not check whether the matrix 6370@var{covar_inv} is the inverse of the eventually set covariance 6371matrix. 6372@end deftypefn 6373@end ifnotinfo 6374 6375@ifinfo 6376@anchor{funct:unur_distr_cvec_get_covar} 6377@deftypefn Function {const double*} unur_distr_cvec_get_covar (const @var{UNUR_DISTR* distribution}) 6378@anchor{funct:unur_distr_cvec_get_cholesky} 6379@deftypefnx Function {const double*} unur_distr_cvec_get_cholesky (const @var{UNUR_DISTR* distribution}) 6380@anchor{funct:unur_distr_cvec_get_covar_inv} 6381@deftypefnx Function {const double*} unur_distr_cvec_get_covar_inv (UNUR_DISTR* @var{distribution}) 6382Get covariance matrix of @var{distribution}, its Cholesky factor, 6383and its inverse, respectively. The function returns a 6384pointer to an array of size @code{dim} x @code{dim}. 6385The rows of the matrix are stored consecutively in this array. 6386If the requested matrix is not marked as known the @code{NULL} 6387pointer is returned and @code{unur_errno} is set to 6388@code{UNUR_ERR_DISTR_GET}. 6389 6390@emph{Important:} Do @strong{not} modify the array that holds the 6391covariance matrix! 6392 6393@emph{Remark:} The inverse of the covariance matrix is computed 6394if it is not already stored. 6395@end deftypefn 6396@end ifinfo 6397@ifnotinfo 6398@anchor{funct:unur_distr_cvec_get_covar} 6399@deftypefn {} {const double*} unur_distr_cvec_get_covar (const @var{UNUR_DISTR* distribution}) 6400@anchor{funct:unur_distr_cvec_get_cholesky} 6401@deftypefnx {} {const double*} unur_distr_cvec_get_cholesky (const @var{UNUR_DISTR* distribution}) 6402@anchor{funct:unur_distr_cvec_get_covar_inv} 6403@deftypefnx {} {const double*} unur_distr_cvec_get_covar_inv (UNUR_DISTR* @var{distribution}) 6404Get covariance matrix of @var{distribution}, its Cholesky factor, 6405and its inverse, respectively. The function returns a 6406pointer to an array of size @code{dim} x @code{dim}. 6407The rows of the matrix are stored consecutively in this array. 6408If the requested matrix is not marked as known the @code{NULL} 6409pointer is returned and @code{unur_errno} is set to 6410@code{UNUR_ERR_DISTR_GET}. 6411 6412@emph{Important:} Do @strong{not} modify the array that holds the 6413covariance matrix! 6414 6415@emph{Remark:} The inverse of the covariance matrix is computed 6416if it is not already stored. 6417@end deftypefn 6418@end ifnotinfo 6419 6420@ifinfo 6421@anchor{funct:unur_distr_cvec_set_rankcorr} 6422@deftypefn Function {int} unur_distr_cvec_set_rankcorr (UNUR_DISTR* @var{distribution}, const @var{double* rankcorr}) 6423Set rank-correlation matrix (Spearman's correlation) for 6424multivariate @var{distribution}. 6425@var{rankcorr} must be a pointer to an array of size 6426@code{dim} x @code{dim}, where @code{dim} is the dimension returned 6427by 6428@ifhtml 6429@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6430@end ifhtml 6431@ifnothtml 6432@command{unur_distr_get_dim}. 6433@end ifnothtml 6434The rows of the matrix have to be stored 6435consecutively in this array. 6436 6437@var{rankcorr} must be a rank-correlation matrix of the 6438@var{distribution}, i.e. it must be symmetric and positive definite 6439and its diagonal entries must be equal to @code{1}. 6440 6441The Cholesky factor is computed (and stored) to verify the 6442positive definiteness condition. 6443 6444A @code{NULL} pointer for @var{rankcorr} is interpreted as the identity matrix. 6445 6446@emph{Important:} In case of an error (e.g. because @var{rankcorr} is 6447not a valid rank-correlation matrix) an error code is returned. 6448Moreover, the rank-correlation matrix is not set and is marked as 6449unknown. A previously set rank-correlation matrix is then no longer 6450available. 6451 6452@emph{Remark:} UNU.RAN does not check whether the an eventually 6453set covariance matrix and a rank-correlation matrix do not 6454contradict each other. 6455@end deftypefn 6456@end ifinfo 6457@ifnotinfo 6458@anchor{funct:unur_distr_cvec_set_rankcorr} 6459@deftypefn {} {int} unur_distr_cvec_set_rankcorr (UNUR_DISTR* @var{distribution}, const @var{double* rankcorr}) 6460Set rank-correlation matrix (Spearman's correlation) for 6461multivariate @var{distribution}. 6462@var{rankcorr} must be a pointer to an array of size 6463@code{dim} x @code{dim}, where @code{dim} is the dimension returned 6464by 6465@ifhtml 6466@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6467@end ifhtml 6468@ifnothtml 6469@command{unur_distr_get_dim}. 6470@end ifnothtml 6471The rows of the matrix have to be stored 6472consecutively in this array. 6473 6474@var{rankcorr} must be a rank-correlation matrix of the 6475@var{distribution}, i.e. it must be symmetric and positive definite 6476and its diagonal entries must be equal to @code{1}. 6477 6478The Cholesky factor is computed (and stored) to verify the 6479positive definiteness condition. 6480 6481A @code{NULL} pointer for @var{rankcorr} is interpreted as the identity matrix. 6482 6483@emph{Important:} In case of an error (e.g. because @var{rankcorr} is 6484not a valid rank-correlation matrix) an error code is returned. 6485Moreover, the rank-correlation matrix is not set and is marked as 6486unknown. A previously set rank-correlation matrix is then no longer 6487available. 6488 6489@emph{Remark:} UNU.RAN does not check whether the an eventually 6490set covariance matrix and a rank-correlation matrix do not 6491contradict each other. 6492@end deftypefn 6493@end ifnotinfo 6494 6495@ifinfo 6496@anchor{funct:unur_distr_cvec_get_rankcorr} 6497@deftypefn Function {const double*} unur_distr_cvec_get_rankcorr (const @var{UNUR_DISTR* distribution}) 6498@anchor{funct:unur_distr_cvec_get_rk_cholesky} 6499@deftypefnx Function {const double*} unur_distr_cvec_get_rk_cholesky (const @var{UNUR_DISTR* distribution}) 6500Get rank-correlation matrix and its cholesky factor, respectively, 6501of @var{distribution}. The function 6502returns a pointer to an array of size @code{dim} x @code{dim}. 6503The rows of the matrix are stored consecutively in this array. 6504If the requested matrix is not marked as known the @code{NULL} 6505pointer is returned and @code{unur_errno} is set to 6506@code{UNUR_ERR_DISTR_GET}. 6507 6508@emph{Important:} Do @strong{not} modify the array that holds the 6509rank-correlation matrix! 6510@end deftypefn 6511@end ifinfo 6512@ifnotinfo 6513@anchor{funct:unur_distr_cvec_get_rankcorr} 6514@deftypefn {} {const double*} unur_distr_cvec_get_rankcorr (const @var{UNUR_DISTR* distribution}) 6515@anchor{funct:unur_distr_cvec_get_rk_cholesky} 6516@deftypefnx {} {const double*} unur_distr_cvec_get_rk_cholesky (const @var{UNUR_DISTR* distribution}) 6517Get rank-correlation matrix and its cholesky factor, respectively, 6518of @var{distribution}. The function 6519returns a pointer to an array of size @code{dim} x @code{dim}. 6520The rows of the matrix are stored consecutively in this array. 6521If the requested matrix is not marked as known the @code{NULL} 6522pointer is returned and @code{unur_errno} is set to 6523@code{UNUR_ERR_DISTR_GET}. 6524 6525@emph{Important:} Do @strong{not} modify the array that holds the 6526rank-correlation matrix! 6527@end deftypefn 6528@end ifnotinfo 6529 6530@ifinfo 6531@anchor{funct:unur_distr_cvec_set_marginals} 6532@deftypefn Function {int} unur_distr_cvec_set_marginals (UNUR_DISTR* @var{distribution}, UNUR_DISTR* @var{marginal}) 6533Sets marginal distributions of the given @var{distribution} to the 6534same @var{marginal} distribution object. The @var{marginal} 6535distribution must be an instance of a continuous univariate 6536distribution object. Notice that the marginal distribution is 6537copied into the @var{distribution} object. 6538@end deftypefn 6539@end ifinfo 6540@ifnotinfo 6541@anchor{funct:unur_distr_cvec_set_marginals} 6542@deftypefn {} {int} unur_distr_cvec_set_marginals (UNUR_DISTR* @var{distribution}, UNUR_DISTR* @var{marginal}) 6543Sets marginal distributions of the given @var{distribution} to the 6544same @var{marginal} distribution object. The @var{marginal} 6545distribution must be an instance of a continuous univariate 6546distribution object. Notice that the marginal distribution is 6547copied into the @var{distribution} object. 6548@end deftypefn 6549@end ifnotinfo 6550 6551@ifinfo 6552@anchor{funct:unur_distr_cvec_set_marginal_array} 6553@deftypefn Function {int} unur_distr_cvec_set_marginal_array (UNUR_DISTR* @var{distribution}, UNUR_DISTR** @var{marginals}) 6554Analogously to the above 6555@ifhtml 6556@ref{funct:unur_distr_cvec_set_marginals,@command{unur_distr_cvec_set_marginals}} 6557@end ifhtml 6558@ifnothtml 6559@command{unur_distr_cvec_set_marginals} 6560@end ifnothtml 6561call. 6562However, now an array @var{marginals} of the pointers to each of 6563the marginal distributions must be given. It @strong{must} be an 6564array of size @code{dim}, where @code{dim} is the dimension 6565returned by 6566@ifhtml 6567@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6568@end ifhtml 6569@ifnothtml 6570@command{unur_distr_get_dim}. 6571@end ifnothtml 6572@emph{Notice}: Local copies for each of the entries are stored in 6573the @var{distribution} object. If some of these entries are 6574identical (i.e. contain the same pointer), then for each of these a 6575new copy is made. 6576@end deftypefn 6577@end ifinfo 6578@ifnotinfo 6579@anchor{funct:unur_distr_cvec_set_marginal_array} 6580@deftypefn {} {int} unur_distr_cvec_set_marginal_array (UNUR_DISTR* @var{distribution}, UNUR_DISTR** @var{marginals}) 6581Analogously to the above 6582@ifhtml 6583@ref{funct:unur_distr_cvec_set_marginals,@command{unur_distr_cvec_set_marginals}} 6584@end ifhtml 6585@ifnothtml 6586@command{unur_distr_cvec_set_marginals} 6587@end ifnothtml 6588call. 6589However, now an array @var{marginals} of the pointers to each of 6590the marginal distributions must be given. It @strong{must} be an 6591array of size @code{dim}, where @code{dim} is the dimension 6592returned by 6593@ifhtml 6594@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6595@end ifhtml 6596@ifnothtml 6597@command{unur_distr_get_dim}. 6598@end ifnothtml 6599@emph{Notice}: Local copies for each of the entries are stored in 6600the @var{distribution} object. If some of these entries are 6601identical (i.e. contain the same pointer), then for each of these a 6602new copy is made. 6603@end deftypefn 6604@end ifnotinfo 6605 6606@ifinfo 6607@anchor{funct:unur_distr_cvec_set_marginal_list} 6608@deftypefn Function {int} unur_distr_cvec_set_marginal_list (UNUR_DISTR* @var{distribution}, ...) 6609Similar to the above 6610@ifhtml 6611@ref{funct:unur_distr_cvec_set_marginal_array,@command{unur_distr_cvec_set_marginal_array}} 6612@end ifhtml 6613@ifnothtml 6614@command{unur_distr_cvec_set_marginal_array} 6615@end ifnothtml 6616call. 6617However, now the pointers to the particular marginal distributions 6618can be given as parameter and does not require an array of 6619pointers. Additionally the given distribution objects are 6620immediately destroyed. Thus calls like 6621@ifhtml 6622@ref{funct:unur_distr_normal,@command{unur_distr_normal}} 6623@end ifhtml 6624@ifnothtml 6625@command{unur_distr_normal} 6626@end ifnothtml 6627can be 6628used as arguments. 6629(With 6630@ifhtml 6631@ref{funct:unur_distr_cvec_set_marginal_array,@command{unur_distr_cvec_set_marginal_array}} 6632@end ifhtml 6633@ifnothtml 6634@command{unur_distr_cvec_set_marginal_array} 6635@end ifnothtml 6636the result of such call 6637has to be stored in a pointer since it has to be freed afterwarts 6638to avoid memory leaks!) 6639 6640The number of pointers to in the list of function arguments 6641@strong{must} be equal to the dimension of the @var{distribution}, 6642i.e. the dimension returned by 6643@ifhtml 6644@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6645@end ifhtml 6646@ifnothtml 6647@command{unur_distr_get_dim}. 6648@end ifnothtml 6649If one of the given pointer to marginal distributions is the @code{NULL} 6650pointer then the marginal distributions of @var{distribution} are 6651not set (or previous settings are not changed) and an error code is 6652returned. 6653 6654@strong{Important:} All distribution objects given in the argument 6655list are destroyed! 6656@end deftypefn 6657@end ifinfo 6658@ifnotinfo 6659@anchor{funct:unur_distr_cvec_set_marginal_list} 6660@deftypefn {} {int} unur_distr_cvec_set_marginal_list (UNUR_DISTR* @var{distribution}, ...) 6661Similar to the above 6662@ifhtml 6663@ref{funct:unur_distr_cvec_set_marginal_array,@command{unur_distr_cvec_set_marginal_array}} 6664@end ifhtml 6665@ifnothtml 6666@command{unur_distr_cvec_set_marginal_array} 6667@end ifnothtml 6668call. 6669However, now the pointers to the particular marginal distributions 6670can be given as parameter and does not require an array of 6671pointers. Additionally the given distribution objects are 6672immediately destroyed. Thus calls like 6673@ifhtml 6674@ref{funct:unur_distr_normal,@command{unur_distr_normal}} 6675@end ifhtml 6676@ifnothtml 6677@command{unur_distr_normal} 6678@end ifnothtml 6679can be 6680used as arguments. 6681(With 6682@ifhtml 6683@ref{funct:unur_distr_cvec_set_marginal_array,@command{unur_distr_cvec_set_marginal_array}} 6684@end ifhtml 6685@ifnothtml 6686@command{unur_distr_cvec_set_marginal_array} 6687@end ifnothtml 6688the result of such call 6689has to be stored in a pointer since it has to be freed afterwarts 6690to avoid memory leaks!) 6691 6692The number of pointers to in the list of function arguments 6693@strong{must} be equal to the dimension of the @var{distribution}, 6694i.e. the dimension returned by 6695@ifhtml 6696@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6697@end ifhtml 6698@ifnothtml 6699@command{unur_distr_get_dim}. 6700@end ifnothtml 6701If one of the given pointer to marginal distributions is the @code{NULL} 6702pointer then the marginal distributions of @var{distribution} are 6703not set (or previous settings are not changed) and an error code is 6704returned. 6705 6706@strong{Important:} All distribution objects given in the argument 6707list are destroyed! 6708@end deftypefn 6709@end ifnotinfo 6710 6711@ifinfo 6712@anchor{funct:unur_distr_cvec_get_marginal} 6713@deftypefn Function {const UNUR_DISTR*} unur_distr_cvec_get_marginal (const @var{UNUR_DISTR* distribution}, int @var{n}) 6714Get pointer to the @var{n}-th marginal distribution 6715object from the given multivariate @var{distribution}. 6716If this does not exist, @code{NULL} is returned. 6717The marginal distributions are enumerated from @code{1} 6718to @code{dim}, where @code{dim} is the dimension 6719returned by 6720@ifhtml 6721@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6722@end ifhtml 6723@ifnothtml 6724@command{unur_distr_get_dim}. 6725@end ifnothtml 6726@end deftypefn 6727@end ifinfo 6728@ifnotinfo 6729@anchor{funct:unur_distr_cvec_get_marginal} 6730@deftypefn {} {const UNUR_DISTR*} unur_distr_cvec_get_marginal (const @var{UNUR_DISTR* distribution}, int @var{n}) 6731Get pointer to the @var{n}-th marginal distribution 6732object from the given multivariate @var{distribution}. 6733If this does not exist, @code{NULL} is returned. 6734The marginal distributions are enumerated from @code{1} 6735to @code{dim}, where @code{dim} is the dimension 6736returned by 6737@ifhtml 6738@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6739@end ifhtml 6740@ifnothtml 6741@command{unur_distr_get_dim}. 6742@end ifnothtml 6743@end deftypefn 6744@end ifnotinfo 6745 6746@ifinfo 6747@anchor{funct:unur_distr_cvec_set_pdfparams} 6748@deftypefn Function {int} unur_distr_cvec_set_pdfparams (UNUR_DISTR* @var{distribution}, const @var{double* params}, int @var{n_params}) 6749Sets array of parameters for @var{distribution}. There is an upper limit 6750for the number of parameters @code{n_params}. It is given by the 6751macro @code{UNUR_DISTR_MAXPARAMS} in @file{unuran_config.h}. (It is set to 67525 by default but can be changed to any appropriate nonnegative number.) 6753If @var{n_params} is negative or exceeds this limit no parameters 6754are copied into the distribution object and @code{unur_errno} is set to 6755@code{UNUR_ERR_DISTR_NPARAMS}. 6756 6757For standard distributions from the UNU.RAN library the parameters 6758are checked. Moreover, the domain is updated automatically. 6759If the given parameters are invalid for the standard distribution, 6760then no parameters are set and an error code is returned. 6761Notice that the given parameter list for such a distribution is 6762handled in the same way as in the corresponding @command{new} 6763calls, i.e. optional parameters for the PDF that are not present in 6764the given list are (re-)set to their default values. 6765 6766@strong{Important:} If the parameters of a distribution from the 6767UNU.RAN library of standard distributions 6768(@pxref{Stddist,,Standard distributions}) 6769are changed, then neither its mode nor the normalization 6770constant are updated. Please use the respective calls 6771@ifhtml 6772@ref{funct:unur_distr_cvec_upd_mode,@command{unur_distr_cvec_upd_mode}} 6773@end ifhtml 6774@ifnothtml 6775@command{unur_distr_cvec_upd_mode} 6776@end ifnothtml 6777and 6778@ifhtml 6779@ref{funct:unur_distr_cvec_upd_pdfvol,@command{unur_distr_cvec_upd_pdfvol}.} 6780@end ifhtml 6781@ifnothtml 6782@command{unur_distr_cvec_upd_pdfvol}. 6783@end ifnothtml 6784@end deftypefn 6785@end ifinfo 6786@ifnotinfo 6787@anchor{funct:unur_distr_cvec_set_pdfparams} 6788@deftypefn {} {int} unur_distr_cvec_set_pdfparams (UNUR_DISTR* @var{distribution}, const @var{double* params}, int @var{n_params}) 6789Sets array of parameters for @var{distribution}. There is an upper limit 6790for the number of parameters @code{n_params}. It is given by the 6791macro @code{UNUR_DISTR_MAXPARAMS} in @file{unuran_config.h}. (It is set to 67925 by default but can be changed to any appropriate nonnegative number.) 6793If @var{n_params} is negative or exceeds this limit no parameters 6794are copied into the distribution object and @code{unur_errno} is set to 6795@code{UNUR_ERR_DISTR_NPARAMS}. 6796 6797For standard distributions from the UNU.RAN library the parameters 6798are checked. Moreover, the domain is updated automatically. 6799If the given parameters are invalid for the standard distribution, 6800then no parameters are set and an error code is returned. 6801Notice that the given parameter list for such a distribution is 6802handled in the same way as in the corresponding @command{new} 6803calls, i.e. optional parameters for the PDF that are not present in 6804the given list are (re-)set to their default values. 6805 6806@strong{Important:} If the parameters of a distribution from the 6807UNU.RAN library of standard distributions 6808(@pxref{Stddist,,Standard distributions}) 6809are changed, then neither its mode nor the normalization 6810constant are updated. Please use the respective calls 6811@ifhtml 6812@ref{funct:unur_distr_cvec_upd_mode,@command{unur_distr_cvec_upd_mode}} 6813@end ifhtml 6814@ifnothtml 6815@command{unur_distr_cvec_upd_mode} 6816@end ifnothtml 6817and 6818@ifhtml 6819@ref{funct:unur_distr_cvec_upd_pdfvol,@command{unur_distr_cvec_upd_pdfvol}.} 6820@end ifhtml 6821@ifnothtml 6822@command{unur_distr_cvec_upd_pdfvol}. 6823@end ifnothtml 6824@end deftypefn 6825@end ifnotinfo 6826 6827@ifinfo 6828@anchor{funct:unur_distr_cvec_get_pdfparams} 6829@deftypefn Function {int} unur_distr_cvec_get_pdfparams (const @var{UNUR_DISTR* distribution}, const @var{double** params}) 6830Get number of parameters of the PDF and set pointer @var{params} to 6831array of parameters. If no parameters are stored in the object, an 6832error code is returned and @code{params} is set to @code{NULL}. 6833 6834@emph{Important:} Do @strong{not} change the entries in @var{params}! 6835@end deftypefn 6836@end ifinfo 6837@ifnotinfo 6838@anchor{funct:unur_distr_cvec_get_pdfparams} 6839@deftypefn {} {int} unur_distr_cvec_get_pdfparams (const @var{UNUR_DISTR* distribution}, const @var{double** params}) 6840Get number of parameters of the PDF and set pointer @var{params} to 6841array of parameters. If no parameters are stored in the object, an 6842error code is returned and @code{params} is set to @code{NULL}. 6843 6844@emph{Important:} Do @strong{not} change the entries in @var{params}! 6845@end deftypefn 6846@end ifnotinfo 6847 6848@ifinfo 6849@anchor{funct:unur_distr_cvec_set_pdfparams_vec} 6850@deftypefn Function {int} unur_distr_cvec_set_pdfparams_vec (UNUR_DISTR* @var{distribution}, int @var{par}, const @var{double* param_vec}, int @var{n_params}) 6851This function provides an interface for additional vector parameters for a 6852multivariate @var{distribution} besides mean vector and covariance 6853matrix which have their own calls. 6854 6855It sets the parameter with number @var{par}. 6856@var{par} indicates directly which of the parameters is set and 6857must be a number between @code{0} and @code{UNUR_DISTR_MAXPARAMS}-1 6858(the upper limit of possible parameters defined in 6859@file{unuran_config.h}; it is set to 5 but can be changed to any 6860appropriate nonnegative number.) 6861 6862The entries of a this parameter are given by the array @var{param_vec} 6863of size @var{n_params}. Notice that using this interface an 6864An (@i{n} x @i{m})-matrix has to be stored in an array of length 6865@var{n_params} = @i{n} times @i{m}; where the rows of the matrix 6866are stored consecutively in this array. 6867 6868Due to great variety of possible parameters for a multivariate 6869@var{distribution} there is no simpler interface. 6870 6871If @var{param_vec} is @code{NULL} then the corresponding entry is cleared. 6872 6873@strong{Important:} If the parameters of a distribution from the 6874UNU.RAN library of standard distributions 6875(@pxref{Stddist,,Standard distributions}) 6876are changed, then neither its mode nor the normalization 6877constant are updated. Please use the respective calls 6878@ifhtml 6879@ref{funct:unur_distr_cvec_upd_mode,@command{unur_distr_cvec_upd_mode}} 6880@end ifhtml 6881@ifnothtml 6882@command{unur_distr_cvec_upd_mode} 6883@end ifnothtml 6884and 6885@ifhtml 6886@ref{funct:unur_distr_cvec_upd_pdfvol,@command{unur_distr_cvec_upd_pdfvol}.} 6887@end ifhtml 6888@ifnothtml 6889@command{unur_distr_cvec_upd_pdfvol}. 6890@end ifnothtml 6891If an error occurs no parameters are copied into the parameter 6892object @code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 6893@end deftypefn 6894@end ifinfo 6895@ifnotinfo 6896@anchor{funct:unur_distr_cvec_set_pdfparams_vec} 6897@deftypefn {} {int} unur_distr_cvec_set_pdfparams_vec (UNUR_DISTR* @var{distribution}, int @var{par}, const @var{double* param_vec}, int @var{n_params}) 6898This function provides an interface for additional vector parameters for a 6899multivariate @var{distribution} besides mean vector and covariance 6900matrix which have their own calls. 6901 6902It sets the parameter with number @var{par}. 6903@var{par} indicates directly which of the parameters is set and 6904must be a number between @code{0} and @code{UNUR_DISTR_MAXPARAMS}-1 6905(the upper limit of possible parameters defined in 6906@file{unuran_config.h}; it is set to 5 but can be changed to any 6907appropriate nonnegative number.) 6908 6909The entries of a this parameter are given by the array @var{param_vec} 6910of size @var{n_params}. Notice that using this interface an 6911An (@i{n} x @i{m})-matrix has to be stored in an array of length 6912@var{n_params} = @i{n} times @i{m}; where the rows of the matrix 6913are stored consecutively in this array. 6914 6915Due to great variety of possible parameters for a multivariate 6916@var{distribution} there is no simpler interface. 6917 6918If @var{param_vec} is @code{NULL} then the corresponding entry is cleared. 6919 6920@strong{Important:} If the parameters of a distribution from the 6921UNU.RAN library of standard distributions 6922(@pxref{Stddist,,Standard distributions}) 6923are changed, then neither its mode nor the normalization 6924constant are updated. Please use the respective calls 6925@ifhtml 6926@ref{funct:unur_distr_cvec_upd_mode,@command{unur_distr_cvec_upd_mode}} 6927@end ifhtml 6928@ifnothtml 6929@command{unur_distr_cvec_upd_mode} 6930@end ifnothtml 6931and 6932@ifhtml 6933@ref{funct:unur_distr_cvec_upd_pdfvol,@command{unur_distr_cvec_upd_pdfvol}.} 6934@end ifhtml 6935@ifnothtml 6936@command{unur_distr_cvec_upd_pdfvol}. 6937@end ifnothtml 6938If an error occurs no parameters are copied into the parameter 6939object @code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 6940@end deftypefn 6941@end ifnotinfo 6942 6943@ifinfo 6944@anchor{funct:unur_distr_cvec_get_pdfparams_vec} 6945@deftypefn Function {int} unur_distr_cvec_get_pdfparams_vec (const @var{UNUR_DISTR* distribution}, int @var{par}, const @var{double** param_vecs}) 6946Get parameter of the PDF with number @var{par}. 6947The pointer to the parameter array is stored in @var{param_vecs}, its 6948size is returned by the function. 6949If the requested parameter is not set, then an error code is returned 6950and @code{params} is set to @code{NULL}. 6951 6952@emph{Important:} Do @strong{not} change the entries in @var{param_vecs}! 6953@end deftypefn 6954@end ifinfo 6955@ifnotinfo 6956@anchor{funct:unur_distr_cvec_get_pdfparams_vec} 6957@deftypefn {} {int} unur_distr_cvec_get_pdfparams_vec (const @var{UNUR_DISTR* distribution}, int @var{par}, const @var{double** param_vecs}) 6958Get parameter of the PDF with number @var{par}. 6959The pointer to the parameter array is stored in @var{param_vecs}, its 6960size is returned by the function. 6961If the requested parameter is not set, then an error code is returned 6962and @code{params} is set to @code{NULL}. 6963 6964@emph{Important:} Do @strong{not} change the entries in @var{param_vecs}! 6965@end deftypefn 6966@end ifnotinfo 6967 6968@ifinfo 6969@anchor{funct:unur_distr_cvec_set_domain_rect} 6970@deftypefn Function {int} unur_distr_cvec_set_domain_rect (UNUR_DISTR* @var{distribution}, const @var{double* lowerleft}, const @var{double* upperright}) 6971Set rectangular domain for @var{distribution} with @var{lowerleft} 6972and @var{upperright} vertices. Both must be pointer to an 6973array of the size returned by 6974@ifhtml 6975@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 6976@end ifhtml 6977@ifnothtml 6978@command{unur_distr_get_dim}. 6979@end ifnothtml 6980A @code{NULL} pointer is interpreted as the zero vector (0,@dots{},0). 6981For setting a coordinate of the boundary to 6982@math{+/- infinity} 6983use @code{+/- UNUR_INFINITY}. 6984The @var{lowerleft} vertex must be strictly smaller than 6985@var{upperright} in each component. Otherwise no domain 6986is set and @code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 6987 6988By default the domain of a distribution is unbounded. Thus one can 6989use this call to truncate an existing distribution. 6990 6991@emph{Important:} Changing the domain of @var{distribution} 6992marks derived parameters like the mode or the center as unknown and 6993must be set @emph{after} changing the domain. This is important for 6994the already set (or default) value for the center does not 6995fall into the given domain. 6996Notice that calls of the PDF and derived functions return @code{0.} 6997when the parameter is not contained in the domain. 6998@end deftypefn 6999@end ifinfo 7000@ifnotinfo 7001@anchor{funct:unur_distr_cvec_set_domain_rect} 7002@deftypefn {} {int} unur_distr_cvec_set_domain_rect (UNUR_DISTR* @var{distribution}, const @var{double* lowerleft}, const @var{double* upperright}) 7003Set rectangular domain for @var{distribution} with @var{lowerleft} 7004and @var{upperright} vertices. Both must be pointer to an 7005array of the size returned by 7006@ifhtml 7007@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7008@end ifhtml 7009@ifnothtml 7010@command{unur_distr_get_dim}. 7011@end ifnothtml 7012A @code{NULL} pointer is interpreted as the zero vector (0,@dots{},0). 7013For setting a coordinate of the boundary to 7014@iftex 7015@math{\pm\infty} 7016@end iftex 7017@ifhtml 7018@html 7019+/- infinity 7020@end html 7021@end ifhtml 7022use @code{+/- UNUR_INFINITY}. 7023The @var{lowerleft} vertex must be strictly smaller than 7024@var{upperright} in each component. Otherwise no domain 7025is set and @code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 7026 7027By default the domain of a distribution is unbounded. Thus one can 7028use this call to truncate an existing distribution. 7029 7030@emph{Important:} Changing the domain of @var{distribution} 7031marks derived parameters like the mode or the center as unknown and 7032must be set @emph{after} changing the domain. This is important for 7033the already set (or default) value for the center does not 7034fall into the given domain. 7035Notice that calls of the PDF and derived functions return @code{0.} 7036when the parameter is not contained in the domain. 7037@end deftypefn 7038@end ifnotinfo 7039 7040@ifinfo 7041@anchor{funct:unur_distr_cvec_is_indomain} 7042@deftypefn Function {int} unur_distr_cvec_is_indomain (const @var{double* x}, const @var{UNUR_DISTR* distribution}) 7043Check whether @var{x} falls into the domain of @var{distribution}. 7044@end deftypefn 7045@end ifinfo 7046@ifnotinfo 7047@anchor{funct:unur_distr_cvec_is_indomain} 7048@deftypefn {} {int} unur_distr_cvec_is_indomain (const @var{double* x}, const @var{UNUR_DISTR* distribution}) 7049Check whether @var{x} falls into the domain of @var{distribution}. 7050@end deftypefn 7051@end ifnotinfo 7052 7053@subsubheading Derived parameters 7054 7055The following paramters @strong{must} be set whenever one of the 7056essential parameters has been set or changed (and the parameter is 7057required for the chosen method). 7058 7059@ifinfo 7060@anchor{funct:unur_distr_cvec_set_mode} 7061@deftypefn Function {int} unur_distr_cvec_set_mode (UNUR_DISTR* @var{distribution}, const @var{double* mode}) 7062Set mode of the @var{distribution}. @var{mode} must be a pointer to an 7063array of the size returned by 7064@ifhtml 7065@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7066@end ifhtml 7067@ifnothtml 7068@command{unur_distr_get_dim}. 7069@end ifnothtml 7070A @code{NULL} pointer for @var{mode} is interpreted as the zero 7071vector (0,@dots{},0). 7072@end deftypefn 7073@end ifinfo 7074@ifnotinfo 7075@anchor{funct:unur_distr_cvec_set_mode} 7076@deftypefn {} {int} unur_distr_cvec_set_mode (UNUR_DISTR* @var{distribution}, const @var{double* mode}) 7077Set mode of the @var{distribution}. @var{mode} must be a pointer to an 7078array of the size returned by 7079@ifhtml 7080@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7081@end ifhtml 7082@ifnothtml 7083@command{unur_distr_get_dim}. 7084@end ifnothtml 7085A @code{NULL} pointer for @var{mode} is interpreted as the zero 7086vector (0,@dots{},0). 7087@end deftypefn 7088@end ifnotinfo 7089 7090@ifinfo 7091@anchor{funct:unur_distr_cvec_upd_mode} 7092@deftypefn Function {int} unur_distr_cvec_upd_mode (UNUR_DISTR* @var{distribution}) 7093Recompute the mode of the @var{distribution}. This call works 7094properly for distribution objects from the UNU.RAN library of 7095standard distributions when the corresponding function is 7096available. If it failes @code{unur_errno} is set to 7097@code{UNUR_ERR_DISTR_DATA}. 7098@end deftypefn 7099@end ifinfo 7100@ifnotinfo 7101@anchor{funct:unur_distr_cvec_upd_mode} 7102@deftypefn {} {int} unur_distr_cvec_upd_mode (UNUR_DISTR* @var{distribution}) 7103Recompute the mode of the @var{distribution}. This call works 7104properly for distribution objects from the UNU.RAN library of 7105standard distributions when the corresponding function is 7106available. If it failes @code{unur_errno} is set to 7107@code{UNUR_ERR_DISTR_DATA}. 7108@end deftypefn 7109@end ifnotinfo 7110 7111@ifinfo 7112@anchor{funct:unur_distr_cvec_get_mode} 7113@deftypefn Function {const double*} unur_distr_cvec_get_mode (UNUR_DISTR* @var{distribution}) 7114Get mode of the @var{distribution}. The function returns a pointer to 7115an array of the size returned by 7116@ifhtml 7117@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7118@end ifhtml 7119@ifnothtml 7120@command{unur_distr_get_dim}. 7121@end ifnothtml 7122If the mode is not marked as known the @code{NULL} pointer is returned and 7123@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 7124(There is no difference between the case where no routine for 7125computing the mode is available and the case where no mode exists 7126for the @var{distribution} at all.) 7127 7128@emph{Important:} Do @strong{not} modify the array that holds the mode! 7129@end deftypefn 7130@end ifinfo 7131@ifnotinfo 7132@anchor{funct:unur_distr_cvec_get_mode} 7133@deftypefn {} {const double*} unur_distr_cvec_get_mode (UNUR_DISTR* @var{distribution}) 7134Get mode of the @var{distribution}. The function returns a pointer to 7135an array of the size returned by 7136@ifhtml 7137@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7138@end ifhtml 7139@ifnothtml 7140@command{unur_distr_get_dim}. 7141@end ifnothtml 7142If the mode is not marked as known the @code{NULL} pointer is returned and 7143@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 7144(There is no difference between the case where no routine for 7145computing the mode is available and the case where no mode exists 7146for the @var{distribution} at all.) 7147 7148@emph{Important:} Do @strong{not} modify the array that holds the mode! 7149@end deftypefn 7150@end ifnotinfo 7151 7152@ifinfo 7153@anchor{funct:unur_distr_cvec_set_center} 7154@deftypefn Function {int} unur_distr_cvec_set_center (UNUR_DISTR* @var{distribution}, const @var{double* center}) 7155Set center of the @var{distribution}. @var{center} must be a pointer to an 7156array of the size returned by 7157@ifhtml 7158@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7159@end ifhtml 7160@ifnothtml 7161@command{unur_distr_get_dim}. 7162@end ifnothtml 7163A @code{NULL} pointer for @var{center} is interpreted as the zero 7164vector (0,@dots{},0). 7165 7166The center is used by some methods to shift the distribution in 7167order to decrease numerical round-off error. 7168If not given explicitly a default is used. 7169Moreover, it is used as starting point for several numerical search 7170algorithm (e.g. for the mode). Then @var{center} must be a pointer 7171where the call to the PDF returns a non-zero value. 7172In particular @var{center} must contained in the domain of the distribution. 7173 7174Default: The mode, if given by a 7175@ifhtml 7176@ref{funct:unur_distr_cvec_set_mode,@command{unur_distr_cvec_set_mode}} 7177@end ifhtml 7178@ifnothtml 7179@command{unur_distr_cvec_set_mode} 7180@end ifnothtml 7181call; 7182else the mean, if given by a 7183@ifhtml 7184@ref{funct:unur_distr_cvec_set_mean,@command{unur_distr_cvec_set_mean}} 7185@end ifhtml 7186@ifnothtml 7187@command{unur_distr_cvec_set_mean} 7188@end ifnothtml 7189call; 7190otherwise the null vector (0,@dots{},0). 7191@end deftypefn 7192@end ifinfo 7193@ifnotinfo 7194@anchor{funct:unur_distr_cvec_set_center} 7195@deftypefn {} {int} unur_distr_cvec_set_center (UNUR_DISTR* @var{distribution}, const @var{double* center}) 7196Set center of the @var{distribution}. @var{center} must be a pointer to an 7197array of the size returned by 7198@ifhtml 7199@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7200@end ifhtml 7201@ifnothtml 7202@command{unur_distr_get_dim}. 7203@end ifnothtml 7204A @code{NULL} pointer for @var{center} is interpreted as the zero 7205vector (0,@dots{},0). 7206 7207The center is used by some methods to shift the distribution in 7208order to decrease numerical round-off error. 7209If not given explicitly a default is used. 7210Moreover, it is used as starting point for several numerical search 7211algorithm (e.g. for the mode). Then @var{center} must be a pointer 7212where the call to the PDF returns a non-zero value. 7213In particular @var{center} must contained in the domain of the distribution. 7214 7215Default: The mode, if given by a 7216@ifhtml 7217@ref{funct:unur_distr_cvec_set_mode,@command{unur_distr_cvec_set_mode}} 7218@end ifhtml 7219@ifnothtml 7220@command{unur_distr_cvec_set_mode} 7221@end ifnothtml 7222call; 7223else the mean, if given by a 7224@ifhtml 7225@ref{funct:unur_distr_cvec_set_mean,@command{unur_distr_cvec_set_mean}} 7226@end ifhtml 7227@ifnothtml 7228@command{unur_distr_cvec_set_mean} 7229@end ifnothtml 7230call; 7231otherwise the null vector (0,@dots{},0). 7232@end deftypefn 7233@end ifnotinfo 7234 7235@ifinfo 7236@anchor{funct:unur_distr_cvec_get_center} 7237@deftypefn Function {const double*} unur_distr_cvec_get_center (UNUR_DISTR* @var{distribution}) 7238Get center of the @var{distribution}. The function returns a pointer to 7239an array of the size returned by 7240@ifhtml 7241@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7242@end ifhtml 7243@ifnothtml 7244@command{unur_distr_get_dim}. 7245@end ifnothtml 7246It always returns some point as there always exists a default for 7247the center, see 7248@ifhtml 7249@ref{funct:unur_distr_cvec_set_center,@command{unur_distr_cvec_set_center}.} 7250@end ifhtml 7251@ifnothtml 7252@command{unur_distr_cvec_set_center}. 7253@end ifnothtml 7254@emph{Important:} Do @strong{not} modify the array that holds the center! 7255@end deftypefn 7256@end ifinfo 7257@ifnotinfo 7258@anchor{funct:unur_distr_cvec_get_center} 7259@deftypefn {} {const double*} unur_distr_cvec_get_center (UNUR_DISTR* @var{distribution}) 7260Get center of the @var{distribution}. The function returns a pointer to 7261an array of the size returned by 7262@ifhtml 7263@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7264@end ifhtml 7265@ifnothtml 7266@command{unur_distr_get_dim}. 7267@end ifnothtml 7268It always returns some point as there always exists a default for 7269the center, see 7270@ifhtml 7271@ref{funct:unur_distr_cvec_set_center,@command{unur_distr_cvec_set_center}.} 7272@end ifhtml 7273@ifnothtml 7274@command{unur_distr_cvec_set_center}. 7275@end ifnothtml 7276@emph{Important:} Do @strong{not} modify the array that holds the center! 7277@end deftypefn 7278@end ifnotinfo 7279 7280@ifinfo 7281@anchor{funct:unur_distr_cvec_set_pdfvol} 7282@deftypefn Function {int} unur_distr_cvec_set_pdfvol (UNUR_DISTR* @var{distribution}, double @var{volume}) 7283Set the volume below the PDF. If @var{vol} is non-positive, no 7284volume is set and @code{unur_errno} is set to 7285@code{UNUR_ERR_DISTR_SET}. 7286@end deftypefn 7287@end ifinfo 7288@ifnotinfo 7289@anchor{funct:unur_distr_cvec_set_pdfvol} 7290@deftypefn {} {int} unur_distr_cvec_set_pdfvol (UNUR_DISTR* @var{distribution}, double @var{volume}) 7291Set the volume below the PDF. If @var{vol} is non-positive, no 7292volume is set and @code{unur_errno} is set to 7293@code{UNUR_ERR_DISTR_SET}. 7294@end deftypefn 7295@end ifnotinfo 7296 7297@ifinfo 7298@anchor{funct:unur_distr_cvec_upd_pdfvol} 7299@deftypefn Function {int} unur_distr_cvec_upd_pdfvol (UNUR_DISTR* @var{distribution}) 7300Recompute the volume below the PDF of the distribution. 7301It only works for distribution objects from the 7302UNU.RAN library of standard distributions when the 7303corresponding function is available. Otherwise @code{unur_errno} is 7304set to @code{UNUR_ERR_DISTR_DATA}. 7305 7306This call also sets the normalization constant such that the given 7307PDF is the derivative of a given CDF, i.e. the volume is 1. 7308@end deftypefn 7309@end ifinfo 7310@ifnotinfo 7311@anchor{funct:unur_distr_cvec_upd_pdfvol} 7312@deftypefn {} {int} unur_distr_cvec_upd_pdfvol (UNUR_DISTR* @var{distribution}) 7313Recompute the volume below the PDF of the distribution. 7314It only works for distribution objects from the 7315UNU.RAN library of standard distributions when the 7316corresponding function is available. Otherwise @code{unur_errno} is 7317set to @code{UNUR_ERR_DISTR_DATA}. 7318 7319This call also sets the normalization constant such that the given 7320PDF is the derivative of a given CDF, i.e. the volume is 1. 7321@end deftypefn 7322@end ifnotinfo 7323 7324@ifinfo 7325@anchor{funct:unur_distr_cvec_get_pdfvol} 7326@deftypefn Function {double} unur_distr_cvec_get_pdfvol (UNUR_DISTR* @var{distribution}) 7327Get the volume below the PDF of the @var{distribution}. If this volume is 7328not known,@* 7329@ifhtml 7330@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 7331@end ifhtml 7332@ifnothtml 7333@command{unur_distr_cont_upd_pdfarea} 7334@end ifnothtml 7335is called to compute 7336it. If this is not successful @code{UNUR_INFINITY} is returned and 7337@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 7338@end deftypefn 7339@end ifinfo 7340@ifnotinfo 7341@anchor{funct:unur_distr_cvec_get_pdfvol} 7342@deftypefn {} {double} unur_distr_cvec_get_pdfvol (UNUR_DISTR* @var{distribution}) 7343Get the volume below the PDF of the @var{distribution}. If this volume is 7344not known,@* 7345@ifhtml 7346@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 7347@end ifhtml 7348@ifnothtml 7349@command{unur_distr_cont_upd_pdfarea} 7350@end ifnothtml 7351is called to compute 7352it. If this is not successful @code{UNUR_INFINITY} is returned and 7353@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 7354@end deftypefn 7355@end ifnotinfo 7356 7357 7358 7359 7360@c 7361@c end of cvec.h 7362@c ------------------------------------- 7363@c ------------------------------------- 7364@c condi.h 7365@c 7366 7367@page 7368@node CONDI 7369@section Continuous univariate full conditional distribution 7370 7371 7372Full conditional distribution for a given continuous 7373multivariate distributiion. The condition is a position vector 7374and either a variable that is variated or a vector that 7375indicates the direction on which the random vector can variate. 7376 7377There is a subtle difference between using direction 7378vector and using the @var{k}-th variable. 7379When a direction vector is given the PDF of the conditional 7380distribution is defined by 7381@iftex 7382@math{f(t) = PDF(pos + t\cdot dir).} 7383@end iftex 7384@ifhtml 7385@html 7386<I>f</I>(<I>t</I>) = <I>PDF</I>(<I>pos</I> + <I>t</I> * <I>dir</I>). 7387@end html 7388@end ifhtml 7389@ifinfo 7390@math{f(t) = PDF(pos + t * dir).} 7391@end ifinfo 7392When a variable is selected the full conditional distribution 7393with all other variables fixed is used. 7394 7395This is a special case of a continuous univariate distribution 7396and thus they have most of these parameters (with the exception 7397that functions cannot be changed). Additionally, 7398 7399@itemize @minus 7400@item there is a call to extract the underlying multivariate 7401distribution, 7402 7403@item and a call to handle the variables that are fixed and the 7404direction for changing the random vector. 7405 7406@end itemize 7407 7408This distibution type is primarily used for evaluation the 7409conditional distribution and its derivative (as required for, 7410e.g., the Gibbs sampler). The density is not normalized (i.e. does 7411not integrate to one). Mode and area are not available and it 7412does not make sense to use any call to set or change parameters 7413except the ones given below. 7414 7415 7416@subheading Function reference 7417 7418@ifhtml 7419@itemize 7420@item @ref{funct:unur_distr_condi_new,unur_distr_condi_new} 7421@item @ref{funct:unur_distr_condi_set_condition,unur_distr_condi_set_condition} 7422@item @ref{funct:unur_distr_condi_get_condition,unur_distr_condi_get_condition} 7423@item @ref{funct:unur_distr_condi_get_distribution,unur_distr_condi_get_distribution} 7424@end itemize 7425@end ifhtml 7426 7427 7428@ifinfo 7429@anchor{funct:unur_distr_condi_new} 7430@deftypefn Function {UNUR_DISTR*} unur_distr_condi_new (const @var{UNUR_DISTR* distribution}, const @var{double* pos}, const @var{double* dir}, int @var{k}) 7431Create an object for full conditional distribution for the given 7432@var{distribution}. The condition is given by a position vector 7433@var{pos} and either the @var{k}-th variable that is variated or 7434the vector @var{dir} that contains the direction on which the 7435random vector can variate. 7436 7437@var{distribution} must be a pointer to a multivariate continuous 7438distribution. 7439@var{pos} must be a pointer to an array of size @code{dim}, where 7440@code{dim} is the dimension of the underlying distribution object. 7441@var{dir} must be a pointer to an array if size @code{dim} or @code{NULL}. 7442@var{k} must be in the range @code{0, @dots{}, dim-1}. 7443If the @var{k}-th variable is used, @var{dir} must be set to @code{NULL}. 7444 7445@emph{Notice:} There is a subtle difference between using direction 7446vector @var{dir} and using the @var{k}-th variable. 7447When @var{dir} is given, the current position @var{pos} is mapped into 74480 of the conditional distribution and the derivative is taken from 7449the function PDF(@var{pos}+t*@var{dir}) w.r.t. @i{t}. 7450On the other hand, when the coordinate @var{k} is used (i.e., when 7451@var{dir} is set to @code{NULL}), the full conditional distribution of the 7452distribution is considered (as used for the Gibbs sampler). 7453In particular, the current point is just projected into the 7454one-dimensional subspace without mapping it into the point 0. 7455 7456@emph{Notice:} If a coordinate @var{k} is used, then the @var{k}-th 7457partial derivative is used if it as available. Otherwise the 7458gradient is computed and the @var{k}-th component is returned. 7459 7460The resulting generator object is of the same type as of a 7461@ifhtml 7462@ref{funct:unur_distr_cont_new,@command{unur_distr_cont_new}} 7463@end ifhtml 7464@ifnothtml 7465@command{unur_distr_cont_new} 7466@end ifnothtml 7467call. 7468@end deftypefn 7469@end ifinfo 7470@ifnotinfo 7471@anchor{funct:unur_distr_condi_new} 7472@deftypefn {} {UNUR_DISTR*} unur_distr_condi_new (const @var{UNUR_DISTR* distribution}, const @var{double* pos}, const @var{double* dir}, int @var{k}) 7473Create an object for full conditional distribution for the given 7474@var{distribution}. The condition is given by a position vector 7475@var{pos} and either the @var{k}-th variable that is variated or 7476the vector @var{dir} that contains the direction on which the 7477random vector can variate. 7478 7479@var{distribution} must be a pointer to a multivariate continuous 7480distribution. 7481@var{pos} must be a pointer to an array of size @code{dim}, where 7482@code{dim} is the dimension of the underlying distribution object. 7483@var{dir} must be a pointer to an array if size @code{dim} or @code{NULL}. 7484@var{k} must be in the range @code{0, @dots{}, dim-1}. 7485If the @var{k}-th variable is used, @var{dir} must be set to @code{NULL}. 7486 7487@emph{Notice:} There is a subtle difference between using direction 7488vector @var{dir} and using the @var{k}-th variable. 7489When @var{dir} is given, the current position @var{pos} is mapped into 74900 of the conditional distribution and the derivative is taken from 7491the function PDF(@var{pos}+t*@var{dir}) w.r.t. @i{t}. 7492On the other hand, when the coordinate @var{k} is used (i.e., when 7493@var{dir} is set to @code{NULL}), the full conditional distribution of the 7494distribution is considered (as used for the Gibbs sampler). 7495In particular, the current point is just projected into the 7496one-dimensional subspace without mapping it into the point 0. 7497 7498@emph{Notice:} If a coordinate @var{k} is used, then the @var{k}-th 7499partial derivative is used if it as available. Otherwise the 7500gradient is computed and the @var{k}-th component is returned. 7501 7502The resulting generator object is of the same type as of a 7503@ifhtml 7504@ref{funct:unur_distr_cont_new,@command{unur_distr_cont_new}} 7505@end ifhtml 7506@ifnothtml 7507@command{unur_distr_cont_new} 7508@end ifnothtml 7509call. 7510@end deftypefn 7511@end ifnotinfo 7512 7513@ifinfo 7514@anchor{funct:unur_distr_condi_set_condition} 7515@deftypefn Function {int} unur_distr_condi_set_condition (struct @var{unur_distr* distribution}, const @var{double* pos}, const @var{double* dir}, int @var{k}) 7516Set/change condition for conditional @var{distribution}. 7517Change values of fixed variables to @var{pos} and use direction 7518@var{dir} or @var{k}-th variable of conditional @var{distribution}. 7519 7520@var{pos} must be a pointer to an array of size @code{dim}, where 7521@code{dim} is the dimension of the underlying distribution object. 7522@var{dir} must be a pointer to an array if size @code{dim} or @code{NULL}. 7523@var{k} must be in the range @code{0, @dots{}, dim-1}. 7524If the @var{k}-th variable is used, @var{dir} must be set to @code{NULL}. 7525 7526@emph{Notice:} There is a subtle difference between using direction 7527vector @var{dir} and using the @var{k}-th variable. 7528When @var{dir} is given, the current position @var{pos} is mapped into 75290 of the conditional distribution and the derivative is taken from 7530the function PDF(@var{pos}+t*@var{dir}) w.r.t. @i{t}. 7531On the other hand, when the coordinate @var{k} is used (i.e., when 7532@var{dir} is set to @code{NULL}), the full conditional distribution of the 7533distribution is considered (as used for the Gibbs sampler). 7534In particular, the current point is just projected into the 7535one-dimensional subspace without mapping it into the point 0. 7536@end deftypefn 7537@end ifinfo 7538@ifnotinfo 7539@anchor{funct:unur_distr_condi_set_condition} 7540@deftypefn {} {int} unur_distr_condi_set_condition (struct @var{unur_distr* distribution}, const @var{double* pos}, const @var{double* dir}, int @var{k}) 7541Set/change condition for conditional @var{distribution}. 7542Change values of fixed variables to @var{pos} and use direction 7543@var{dir} or @var{k}-th variable of conditional @var{distribution}. 7544 7545@var{pos} must be a pointer to an array of size @code{dim}, where 7546@code{dim} is the dimension of the underlying distribution object. 7547@var{dir} must be a pointer to an array if size @code{dim} or @code{NULL}. 7548@var{k} must be in the range @code{0, @dots{}, dim-1}. 7549If the @var{k}-th variable is used, @var{dir} must be set to @code{NULL}. 7550 7551@emph{Notice:} There is a subtle difference between using direction 7552vector @var{dir} and using the @var{k}-th variable. 7553When @var{dir} is given, the current position @var{pos} is mapped into 75540 of the conditional distribution and the derivative is taken from 7555the function PDF(@var{pos}+t*@var{dir}) w.r.t. @i{t}. 7556On the other hand, when the coordinate @var{k} is used (i.e., when 7557@var{dir} is set to @code{NULL}), the full conditional distribution of the 7558distribution is considered (as used for the Gibbs sampler). 7559In particular, the current point is just projected into the 7560one-dimensional subspace without mapping it into the point 0. 7561@end deftypefn 7562@end ifnotinfo 7563 7564@ifinfo 7565@anchor{funct:unur_distr_condi_get_condition} 7566@deftypefn Function {int} unur_distr_condi_get_condition (struct @var{unur_distr* distribution}, const @var{double** pos}, const @var{double** dir}, int* @var{k}) 7567Get condition for conditional @var{distribution}. 7568The values for the fixed variables are stored in @var{pos}, which 7569must be a pointer to an array of size @code{dim}. 7570The condition is stored in @var{dir} and @var{k}, respectively. 7571 7572@emph{Important:} Do @strong{not} change the entries in @var{pos} 7573and @var{dir}! 7574@end deftypefn 7575@end ifinfo 7576@ifnotinfo 7577@anchor{funct:unur_distr_condi_get_condition} 7578@deftypefn {} {int} unur_distr_condi_get_condition (struct @var{unur_distr* distribution}, const @var{double** pos}, const @var{double** dir}, int* @var{k}) 7579Get condition for conditional @var{distribution}. 7580The values for the fixed variables are stored in @var{pos}, which 7581must be a pointer to an array of size @code{dim}. 7582The condition is stored in @var{dir} and @var{k}, respectively. 7583 7584@emph{Important:} Do @strong{not} change the entries in @var{pos} 7585and @var{dir}! 7586@end deftypefn 7587@end ifnotinfo 7588 7589@ifinfo 7590@anchor{funct:unur_distr_condi_get_distribution} 7591@deftypefn Function {const UNUR_DISTR*} unur_distr_condi_get_distribution (const @var{UNUR_DISTR* distribution}) 7592Get pointer to distribution object for underlying distribution. 7593@end deftypefn 7594@end ifinfo 7595@ifnotinfo 7596@anchor{funct:unur_distr_condi_get_distribution} 7597@deftypefn {} {const UNUR_DISTR*} unur_distr_condi_get_distribution (const @var{UNUR_DISTR* distribution}) 7598Get pointer to distribution object for underlying distribution. 7599@end deftypefn 7600@end ifnotinfo 7601 7602 7603 7604 7605@c 7606@c end of condi.h 7607@c ------------------------------------- 7608@c ------------------------------------- 7609@c cvemp.h 7610@c 7611 7612@page 7613@node CVEMP 7614@section Continuous empirical multivariate distributions 7615 7616 7617Empirical multivariate distributions are just lists of vectors 7618(with the same dimension). 7619Thus there are only calls to insert these data. 7620How these data are used to sample from the empirical distribution 7621depends from the chosen generation method. 7622 7623 7624@subheading Function reference 7625 7626@ifhtml 7627@itemize 7628@item @ref{funct:unur_distr_cvemp_new,unur_distr_cvemp_new} 7629@item @ref{funct:unur_distr_cvemp_set_data,unur_distr_cvemp_set_data} 7630@item @ref{funct:unur_distr_cvemp_read_data,unur_distr_cvemp_read_data} 7631@item @ref{funct:unur_distr_cvemp_get_data,unur_distr_cvemp_get_data} 7632@end itemize 7633@end ifhtml 7634 7635 7636@ifinfo 7637@anchor{funct:unur_distr_cvemp_new} 7638@deftypefn Function {UNUR_DISTR*} unur_distr_cvemp_new (int @var{dim}) 7639Create a new (empty) object for an empirical multivariate 7640continuous distribution. @var{dim} is the number of components of 7641the random vector (i.e. its dimension). It must be at least 2; 7642otherwise 7643@ifhtml 7644@ref{funct:unur_distr_cemp_new,@command{unur_distr_cemp_new}} 7645@end ifhtml 7646@ifnothtml 7647@command{unur_distr_cemp_new} 7648@end ifnothtml 7649should be used to create an object 7650for an empirical univariate distribution. 7651@end deftypefn 7652@end ifinfo 7653@ifnotinfo 7654@anchor{funct:unur_distr_cvemp_new} 7655@deftypefn {} {UNUR_DISTR*} unur_distr_cvemp_new (int @var{dim}) 7656Create a new (empty) object for an empirical multivariate 7657continuous distribution. @var{dim} is the number of components of 7658the random vector (i.e. its dimension). It must be at least 2; 7659otherwise 7660@ifhtml 7661@ref{funct:unur_distr_cemp_new,@command{unur_distr_cemp_new}} 7662@end ifhtml 7663@ifnothtml 7664@command{unur_distr_cemp_new} 7665@end ifnothtml 7666should be used to create an object 7667for an empirical univariate distribution. 7668@end deftypefn 7669@end ifnotinfo 7670 7671@subsubheading Essential parameters 7672 7673@ifinfo 7674@anchor{funct:unur_distr_cvemp_set_data} 7675@deftypefn Function {int} unur_distr_cvemp_set_data (UNUR_DISTR* @var{distribution}, const @var{double* sample}, int @var{n_sample}) 7676Set observed sample for empirical @var{distribution}. 7677@var{sample} is an array of doubles of size 7678@code{dim} x @var{n_sample}, where 7679@code{dim} is the dimension of the @var{distribution} returned by 7680@ifhtml 7681@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7682@end ifhtml 7683@ifnothtml 7684@command{unur_distr_get_dim}. 7685@end ifnothtml 7686The data points must be stored consecutively in @var{sample}, i.e., 7687data points (x1, y1), (x2, y2), @dots{} are given as an array 7688@{x1, y1, x2, y2, @dots{}@}. 7689@end deftypefn 7690@end ifinfo 7691@ifnotinfo 7692@anchor{funct:unur_distr_cvemp_set_data} 7693@deftypefn {} {int} unur_distr_cvemp_set_data (UNUR_DISTR* @var{distribution}, const @var{double* sample}, int @var{n_sample}) 7694Set observed sample for empirical @var{distribution}. 7695@var{sample} is an array of doubles of size 7696@code{dim} x @var{n_sample}, where 7697@code{dim} is the dimension of the @var{distribution} returned by 7698@ifhtml 7699@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7700@end ifhtml 7701@ifnothtml 7702@command{unur_distr_get_dim}. 7703@end ifnothtml 7704The data points must be stored consecutively in @var{sample}, i.e., 7705data points (x1, y1), (x2, y2), @dots{} are given as an array 7706@{x1, y1, x2, y2, @dots{}@}. 7707@end deftypefn 7708@end ifnotinfo 7709 7710@ifinfo 7711@anchor{funct:unur_distr_cvemp_read_data} 7712@deftypefn Function {int} unur_distr_cvemp_read_data (UNUR_DISTR* @var{distribution}, const @var{char* filename}) 7713Read data from file @file{filename}. 7714It reads the first @code{dim} numbers from each line, where 7715@code{dim} is the dimension of the @var{distribution} returned by 7716@ifhtml 7717@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7718@end ifhtml 7719@ifnothtml 7720@command{unur_distr_get_dim}. 7721@end ifnothtml 7722Numbers are parsed by means of the C standard routine @command{strtod}. 7723Lines that do not start with @code{+}, @code{-}, @code{.}, or a 7724digit are ignored. (Beware of lines starting with a blank!) 7725 7726In case of an error (file cannot be opened, too few entries in a 7727line, invalid string for double in line) no data are copied into 7728the distribution object and an error code is returned. 7729@end deftypefn 7730@end ifinfo 7731@ifnotinfo 7732@anchor{funct:unur_distr_cvemp_read_data} 7733@deftypefn {} {int} unur_distr_cvemp_read_data (UNUR_DISTR* @var{distribution}, const @var{char* filename}) 7734Read data from file @file{filename}. 7735It reads the first @code{dim} numbers from each line, where 7736@code{dim} is the dimension of the @var{distribution} returned by 7737@ifhtml 7738@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}.} 7739@end ifhtml 7740@ifnothtml 7741@command{unur_distr_get_dim}. 7742@end ifnothtml 7743Numbers are parsed by means of the C standard routine @command{strtod}. 7744Lines that do not start with @code{+}, @code{-}, @code{.}, or a 7745digit are ignored. (Beware of lines starting with a blank!) 7746 7747In case of an error (file cannot be opened, too few entries in a 7748line, invalid string for double in line) no data are copied into 7749the distribution object and an error code is returned. 7750@end deftypefn 7751@end ifnotinfo 7752 7753@ifinfo 7754@anchor{funct:unur_distr_cvemp_get_data} 7755@deftypefn Function {int} unur_distr_cvemp_get_data (const @var{UNUR_DISTR* distribution}, const @var{double** sample}) 7756Get number of samples and set pointer @var{sample} to array of 7757observations. If no sample has been given, an error code 7758is returned and @var{sample} is set to @code{NULL}. 7759If successful @var{sample} points to an array of length 7760@code{dim} x @code{n_sample}, where 7761@code{dim} is the dimension of the distribution returned by 7762@ifhtml 7763@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}} 7764@end ifhtml 7765@ifnothtml 7766@command{unur_distr_get_dim} 7767@end ifnothtml 7768and @code{n_sample} the return value of the 7769function. 7770 7771@emph{Important:} Do @strong{not} modify the array @var{sample}. 7772@end deftypefn 7773@end ifinfo 7774@ifnotinfo 7775@anchor{funct:unur_distr_cvemp_get_data} 7776@deftypefn {} {int} unur_distr_cvemp_get_data (const @var{UNUR_DISTR* distribution}, const @var{double** sample}) 7777Get number of samples and set pointer @var{sample} to array of 7778observations. If no sample has been given, an error code 7779is returned and @var{sample} is set to @code{NULL}. 7780If successful @var{sample} points to an array of length 7781@code{dim} x @code{n_sample}, where 7782@code{dim} is the dimension of the distribution returned by 7783@ifhtml 7784@ref{funct:unur_distr_get_dim,@command{unur_distr_get_dim}} 7785@end ifhtml 7786@ifnothtml 7787@command{unur_distr_get_dim} 7788@end ifnothtml 7789and @code{n_sample} the return value of the 7790function. 7791 7792@emph{Important:} Do @strong{not} modify the array @var{sample}. 7793@end deftypefn 7794@end ifnotinfo 7795 7796 7797 7798 7799@c 7800@c end of cvemp.h 7801@c ------------------------------------- 7802@c ------------------------------------- 7803@c matr.h 7804@c 7805 7806@page 7807@node MATR 7808@section MATRix distributions 7809 7810 7811Distributions for random matrices. Notice that UNU.RAN uses 7812arrays of @code{double}s to handle matrices. The rows of 7813the matrix are stored consecutively. 7814 7815 7816@subheading Function reference 7817 7818@ifhtml 7819@itemize 7820@item @ref{funct:unur_distr_matr_new,unur_distr_matr_new} 7821@item @ref{funct:unur_distr_matr_get_dim,unur_distr_matr_get_dim} 7822@end itemize 7823@end ifhtml 7824 7825 7826@ifinfo 7827@anchor{funct:unur_distr_matr_new} 7828@deftypefn Function {UNUR_DISTR*} unur_distr_matr_new (int @var{n_rows}, int @var{n_cols}) 7829Create a new (empty) object for a matrix distribution. @var{n_rows} 7830and @var{n_cols} are the respective numbers of rows and columns of 7831the random matrix (i.e. its dimensions). It is also possible to 7832have only one number or rows and/or columns. 7833Notice, however, that this is treated as a distribution of random 7834matrices with only one row or column or component and not as a 7835distribution of vectors or real numbers. For the latter 7836@ifhtml 7837@ref{funct:unur_distr_cont_new,@command{unur_distr_cont_new}} 7838@end ifhtml 7839@ifnothtml 7840@command{unur_distr_cont_new} 7841@end ifnothtml 7842or 7843@ifhtml 7844@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 7845@end ifhtml 7846@ifnothtml 7847@command{unur_distr_cvec_new} 7848@end ifnothtml 7849should be 7850used to create an object for a univariate distribution and a 7851multivariate (vector) distribution, respectively. 7852@end deftypefn 7853@end ifinfo 7854@ifnotinfo 7855@anchor{funct:unur_distr_matr_new} 7856@deftypefn {} {UNUR_DISTR*} unur_distr_matr_new (int @var{n_rows}, int @var{n_cols}) 7857Create a new (empty) object for a matrix distribution. @var{n_rows} 7858and @var{n_cols} are the respective numbers of rows and columns of 7859the random matrix (i.e. its dimensions). It is also possible to 7860have only one number or rows and/or columns. 7861Notice, however, that this is treated as a distribution of random 7862matrices with only one row or column or component and not as a 7863distribution of vectors or real numbers. For the latter 7864@ifhtml 7865@ref{funct:unur_distr_cont_new,@command{unur_distr_cont_new}} 7866@end ifhtml 7867@ifnothtml 7868@command{unur_distr_cont_new} 7869@end ifnothtml 7870or 7871@ifhtml 7872@ref{funct:unur_distr_cvec_new,@command{unur_distr_cvec_new}} 7873@end ifhtml 7874@ifnothtml 7875@command{unur_distr_cvec_new} 7876@end ifnothtml 7877should be 7878used to create an object for a univariate distribution and a 7879multivariate (vector) distribution, respectively. 7880@end deftypefn 7881@end ifnotinfo 7882 7883@subsubheading Essential parameters 7884 7885@ifinfo 7886@anchor{funct:unur_distr_matr_get_dim} 7887@deftypefn Function {int} unur_distr_matr_get_dim (const @var{UNUR_DISTR* distribution}, int* @var{n_rows}, int* @var{n_cols}) 7888Get number of rows and columns of random matrix (its dimension). 7889It returns the total number of components. If successfull 7890@code{UNUR_SUCCESS} is returned. 7891@end deftypefn 7892@end ifinfo 7893@ifnotinfo 7894@anchor{funct:unur_distr_matr_get_dim} 7895@deftypefn {} {int} unur_distr_matr_get_dim (const @var{UNUR_DISTR* distribution}, int* @var{n_rows}, int* @var{n_cols}) 7896Get number of rows and columns of random matrix (its dimension). 7897It returns the total number of components. If successfull 7898@code{UNUR_SUCCESS} is returned. 7899@end deftypefn 7900@end ifnotinfo 7901 7902 7903 7904 7905@c 7906@c end of matr.h 7907@c ------------------------------------- 7908@c ------------------------------------- 7909@c discr.h 7910@c 7911 7912@page 7913@node DISCR 7914@section Discrete univariate distributions 7915 7916 7917The calls in this section can be applied to discrete 7918univariate distributions. 7919 7920@itemize @minus 7921@item Create a @command{new} instance of a discrete univariate 7922distribution. 7923 7924@item Handle and evaluate 7925distribution function (CDF, @command{cdf}) and 7926probability mass function (PMF, @command{pmf}). 7927The following is important: 7928@itemize . 7929@item @command{pmf} need not be normalized, i.e., 7930any summable nonnegative function on the set of intergers can be 7931used. 7932@item @command{cdf} must be a distribution function, i.e. it 7933must be monotonically increasing with range [0,1]. 7934@item If @command{cdf} and @command{pdf} are used together for a 7935pariticular generation method, then @command{pmf} must be 7936normalized, i.e. it must sum to 1. 7937@end itemize 7938 7939@item Alternatively, @command{cdf} and @command{pdf} can be 7940provided as @command{str}ings instead of function pointers. 7941 7942@item Some generation methods require a (finite) probability 7943vector (PV, @command{pv}), i.e. an array of @code{double}s. 7944It can be automatically computed if the @command{pmf} is 7945given but @command{pv} is not. 7946 7947@item Set (and change) parameters (@command{pmfparams}) and the 7948total sum (@command{pmfsum}) of the given PMF or PV. 7949 7950@item Set the @command{mode} of the distribution. 7951 7952@item Set the @command{domain} of the distribution. 7953 7954@end itemize 7955 7956 7957@subheading Function reference 7958 7959@ifhtml 7960@itemize 7961@item @ref{funct:unur_distr_discr_new,unur_distr_discr_new} 7962@item @ref{funct:unur_distr_discr_set_pv,unur_distr_discr_set_pv} 7963@item @ref{funct:unur_distr_discr_make_pv,unur_distr_discr_make_pv} 7964@item @ref{funct:unur_distr_discr_get_pv,unur_distr_discr_get_pv} 7965@item @ref{funct:unur_distr_discr_set_pmf,unur_distr_discr_set_pmf} 7966@item @ref{funct:unur_distr_discr_set_cdf,unur_distr_discr_set_cdf} 7967@item @ref{funct:unur_distr_discr_set_invcdf,unur_distr_discr_set_invcdf} 7968@item @ref{funct:unur_distr_discr_eval_pv,unur_distr_discr_eval_pv} 7969@item @ref{funct:unur_distr_discr_eval_pmf,unur_distr_discr_eval_pmf} 7970@item @ref{funct:unur_distr_discr_eval_cdf,unur_distr_discr_eval_cdf} 7971@item @ref{funct:unur_distr_discr_eval_invcdf,unur_distr_discr_eval_invcdf} 7972@item @ref{funct:unur_distr_discr_set_pmfstr,unur_distr_discr_set_pmfstr} 7973@item @ref{funct:unur_distr_discr_set_cdfstr,unur_distr_discr_set_cdfstr} 7974@item @ref{funct:unur_distr_discr_get_pmfstr,unur_distr_discr_get_pmfstr} 7975@item @ref{funct:unur_distr_discr_get_cdfstr,unur_distr_discr_get_cdfstr} 7976@item @ref{funct:unur_distr_discr_set_pmfparams,unur_distr_discr_set_pmfparams} 7977@item @ref{funct:unur_distr_discr_get_pmfparams,unur_distr_discr_get_pmfparams} 7978@item @ref{funct:unur_distr_discr_set_domain,unur_distr_discr_set_domain} 7979@item @ref{funct:unur_distr_discr_get_domain,unur_distr_discr_get_domain} 7980@item @ref{funct:unur_distr_discr_set_mode,unur_distr_discr_set_mode} 7981@item @ref{funct:unur_distr_discr_upd_mode,unur_distr_discr_upd_mode} 7982@item @ref{funct:unur_distr_discr_get_mode,unur_distr_discr_get_mode} 7983@item @ref{funct:unur_distr_discr_set_pmfsum,unur_distr_discr_set_pmfsum} 7984@item @ref{funct:unur_distr_discr_upd_pmfsum,unur_distr_discr_upd_pmfsum} 7985@item @ref{funct:unur_distr_discr_get_pmfsum,unur_distr_discr_get_pmfsum} 7986@end itemize 7987@end ifhtml 7988 7989 7990@ifinfo 7991@anchor{funct:unur_distr_discr_new} 7992@deftypefn Function {UNUR_DISTR*} unur_distr_discr_new (void) 7993Create a new (empty) object for a univariate discrete distribution. 7994@end deftypefn 7995@end ifinfo 7996@ifnotinfo 7997@anchor{funct:unur_distr_discr_new} 7998@deftypefn {} {UNUR_DISTR*} unur_distr_discr_new (void) 7999Create a new (empty) object for a univariate discrete distribution. 8000@end deftypefn 8001@end ifnotinfo 8002 8003@subsubheading Essential parameters 8004 8005There are two interfaces for discrete univariate distributions: 8006Either provide a (finite) probability vector (PV). 8007Or provide a probability mass function (PMF). For the latter 8008case there are also a couple of derived parameters that are not 8009required when a PV is given. 8010 8011It is not possible to set both a PMF and a PV directly. However, the 8012PV can be computed from the PMF (or the CDF if no PMF is available) 8013by means of a 8014@ifhtml 8015@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 8016@end ifhtml 8017@ifnothtml 8018@command{unur_distr_discr_make_pv} 8019@end ifnothtml 8020call. 8021If both the PV and the PMF are given in the distribution object it 8022depends on the generation method which of these is used. 8023 8024@ifinfo 8025@anchor{funct:unur_distr_discr_set_pv} 8026@deftypefn Function {int} unur_distr_discr_set_pv (UNUR_DISTR* @var{distribution}, const @var{double* pv}, int @var{n_pv}) 8027Set finite probability vector (PV) for the @var{distribution}. It is not 8028necessary that the entries in the given PV sum to 1. 8029@var{n_pv} must be positive. However, there is no testing 8030whether all entries in @var{pv} are non-negative. 8031 8032If no domain has been set, then the left boundary is set to 8033@code{0}, by default. If @var{n_pv} is too large, e.g. because 8034left boundary + @var{n_pv} exceeds the range of integers, 8035then the call fails. 8036 8037Notice that it is not possible to set both a PV and a PMF or CDF. 8038If the PMF or CDF is set first one cannot set the PV. 8039If the PMF or CDF is set first after a PV is set, the latter is 8040removed (and recomputed using 8041@ifhtml 8042@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 8043@end ifhtml 8044@ifnothtml 8045@command{unur_distr_discr_make_pv} 8046@end ifnothtml 8047when required). 8048@end deftypefn 8049@end ifinfo 8050@ifnotinfo 8051@anchor{funct:unur_distr_discr_set_pv} 8052@deftypefn {} {int} unur_distr_discr_set_pv (UNUR_DISTR* @var{distribution}, const @var{double* pv}, int @var{n_pv}) 8053Set finite probability vector (PV) for the @var{distribution}. It is not 8054necessary that the entries in the given PV sum to 1. 8055@var{n_pv} must be positive. However, there is no testing 8056whether all entries in @var{pv} are non-negative. 8057 8058If no domain has been set, then the left boundary is set to 8059@code{0}, by default. If @var{n_pv} is too large, e.g. because 8060left boundary + @var{n_pv} exceeds the range of integers, 8061then the call fails. 8062 8063Notice that it is not possible to set both a PV and a PMF or CDF. 8064If the PMF or CDF is set first one cannot set the PV. 8065If the PMF or CDF is set first after a PV is set, the latter is 8066removed (and recomputed using 8067@ifhtml 8068@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 8069@end ifhtml 8070@ifnothtml 8071@command{unur_distr_discr_make_pv} 8072@end ifnothtml 8073when required). 8074@end deftypefn 8075@end ifnotinfo 8076 8077@ifinfo 8078@anchor{funct:unur_distr_discr_make_pv} 8079@deftypefn Function {int} unur_distr_discr_make_pv (UNUR_DISTR* @var{distribution}) 8080Compute a PV when a PMF or CDF is given. However, when the 8081domain is not given or is too large and the sum over the PMF is given 8082then the (right) tail of the @var{distribution} is chopped off such that 8083the probability for the tail region is less than 1.e-8. 8084If the sum over the PMF is not given a PV of maximal length is 8085computed. 8086 8087The maximal size of the created PV is bounded by the macro 8088@code{UNUR_MAX_AUTO_PV} that is defined in @file{unuran_config.h}. 8089 8090If successful, the length of the generated PV is returned. 8091If the sum over the PMF on the chopped tail is not neglible small 8092(i.e. greater than 1.e-8 or unknown) than the 8093negative of the length of the PV is returned and 8094@code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 8095 8096Notice that the left boundary of the PV is set to @code{0} by 8097default when a discrete distribution object is created from 8098scratch. 8099 8100If computing a PV fails for some reasons, an error code is returned and 8101@code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 8102@end deftypefn 8103@end ifinfo 8104@ifnotinfo 8105@anchor{funct:unur_distr_discr_make_pv} 8106@deftypefn {} {int} unur_distr_discr_make_pv (UNUR_DISTR* @var{distribution}) 8107Compute a PV when a PMF or CDF is given. However, when the 8108domain is not given or is too large and the sum over the PMF is given 8109then the (right) tail of the @var{distribution} is chopped off such that 8110the probability for the tail region is less than 1.e-8. 8111If the sum over the PMF is not given a PV of maximal length is 8112computed. 8113 8114The maximal size of the created PV is bounded by the macro 8115@code{UNUR_MAX_AUTO_PV} that is defined in @file{unuran_config.h}. 8116 8117If successful, the length of the generated PV is returned. 8118If the sum over the PMF on the chopped tail is not neglible small 8119(i.e. greater than 1.e-8 or unknown) than the 8120negative of the length of the PV is returned and 8121@code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 8122 8123Notice that the left boundary of the PV is set to @code{0} by 8124default when a discrete distribution object is created from 8125scratch. 8126 8127If computing a PV fails for some reasons, an error code is returned and 8128@code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 8129@end deftypefn 8130@end ifnotinfo 8131 8132@ifinfo 8133@anchor{funct:unur_distr_discr_get_pv} 8134@deftypefn Function {int} unur_distr_discr_get_pv (const @var{UNUR_DISTR* distribution}, const @var{double** pv}) 8135Get length of PV of the @var{distribution} and set pointer 8136@var{pv} to array of probabilities. If no PV is given, 8137an error code is returned and @var{pv} is set to @code{NULL}.@* 8138(It does not call 8139@ifhtml 8140@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 8141@end ifhtml 8142@ifnothtml 8143@command{unur_distr_discr_make_pv} 8144@end ifnothtml 8145!) 8146@end deftypefn 8147@end ifinfo 8148@ifnotinfo 8149@anchor{funct:unur_distr_discr_get_pv} 8150@deftypefn {} {int} unur_distr_discr_get_pv (const @var{UNUR_DISTR* distribution}, const @var{double** pv}) 8151Get length of PV of the @var{distribution} and set pointer 8152@var{pv} to array of probabilities. If no PV is given, 8153an error code is returned and @var{pv} is set to @code{NULL}.@* 8154(It does not call 8155@ifhtml 8156@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 8157@end ifhtml 8158@ifnothtml 8159@command{unur_distr_discr_make_pv} 8160@end ifnothtml 8161!) 8162@end deftypefn 8163@end ifnotinfo 8164 8165@ifinfo 8166@anchor{funct:unur_distr_discr_set_pmf} 8167@deftypefn Function {int} unur_distr_discr_set_pmf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_DISCR* @var{pmf}) 8168@anchor{funct:unur_distr_discr_set_cdf} 8169@deftypefnx Function {int} unur_distr_discr_set_cdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_DISCR* @var{cdf}) 8170Set respective pointer to the PMF and the CDF of the @var{distribution}. 8171These functions must be of type 8172@code{double funct(int k, const UNUR_DISTR *distr)}. 8173 8174It is important to note that all these functions must return a 8175result for all integers @var{k}. E.g., if the domain of a given 8176PMF is the interval @{1,2,3,@dots{},100@}, than the given function 8177must return @code{0.0} for all points outside this interval. 8178 8179The default domain for the PMF or CDF is [@code{0}, @code{INT_MAX}]. 8180The domain can be changed using a 8181@ifhtml 8182@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 8183@end ifhtml 8184@ifnothtml 8185@command{unur_distr_discr_set_domain} 8186@end ifnothtml 8187call. 8188 8189It is not possible to change such a function. Once the PMF or 8190CDF is set it cannot be overwritten. A new distribution object 8191has to be used instead. 8192 8193Notice that it is not possible to set both a PV and a PMF or CDF. 8194If the PMF or CDF is set first one cannot set the PV. 8195If the PMF or CDF is set first after a PV is set, the latter is 8196removed (and recomputed using 8197@ifhtml 8198@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 8199@end ifhtml 8200@ifnothtml 8201@command{unur_distr_discr_make_pv} 8202@end ifnothtml 8203when required). 8204@end deftypefn 8205@end ifinfo 8206@ifnotinfo 8207@anchor{funct:unur_distr_discr_set_pmf} 8208@deftypefn {} {int} unur_distr_discr_set_pmf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_DISCR* @var{pmf}) 8209@anchor{funct:unur_distr_discr_set_cdf} 8210@deftypefnx {} {int} unur_distr_discr_set_cdf (UNUR_DISTR* @var{distribution}, UNUR_FUNCT_DISCR* @var{cdf}) 8211Set respective pointer to the PMF and the CDF of the @var{distribution}. 8212These functions must be of type 8213@code{double funct(int k, const UNUR_DISTR *distr)}. 8214 8215It is important to note that all these functions must return a 8216result for all integers @var{k}. E.g., if the domain of a given 8217PMF is the interval @{1,2,3,@dots{},100@}, than the given function 8218must return @code{0.0} for all points outside this interval. 8219 8220The default domain for the PMF or CDF is [@code{0}, @code{INT_MAX}]. 8221The domain can be changed using a 8222@ifhtml 8223@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 8224@end ifhtml 8225@ifnothtml 8226@command{unur_distr_discr_set_domain} 8227@end ifnothtml 8228call. 8229 8230It is not possible to change such a function. Once the PMF or 8231CDF is set it cannot be overwritten. A new distribution object 8232has to be used instead. 8233 8234Notice that it is not possible to set both a PV and a PMF or CDF. 8235If the PMF or CDF is set first one cannot set the PV. 8236If the PMF or CDF is set first after a PV is set, the latter is 8237removed (and recomputed using 8238@ifhtml 8239@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 8240@end ifhtml 8241@ifnothtml 8242@command{unur_distr_discr_make_pv} 8243@end ifnothtml 8244when required). 8245@end deftypefn 8246@end ifnotinfo 8247 8248@ifinfo 8249@anchor{funct:unur_distr_discr_set_invcdf} 8250@deftypefn Function {int} unur_distr_discr_set_invcdf (UNUR_DISTR* @var{distribution}, UNUR_IFUNCT_DISCR* @var{invcdf}) 8251Set inverse CDF of the @var{distribution}. 8252@var{invcdf} must be a pointer must be of type 8253@code{int funct(double x, const UNUR_DISTR *distr)}, 8254i.e., it should return a @code{double}. 8255@end deftypefn 8256@end ifinfo 8257@ifnotinfo 8258@anchor{funct:unur_distr_discr_set_invcdf} 8259@deftypefn {} {int} unur_distr_discr_set_invcdf (UNUR_DISTR* @var{distribution}, UNUR_IFUNCT_DISCR* @var{invcdf}) 8260Set inverse CDF of the @var{distribution}. 8261@var{invcdf} must be a pointer must be of type 8262@code{int funct(double x, const UNUR_DISTR *distr)}, 8263i.e., it should return a @code{double}. 8264@end deftypefn 8265@end ifnotinfo 8266 8267@ifinfo 8268@anchor{funct:unur_distr_discr_eval_pv} 8269@deftypefn Function {double} unur_distr_discr_eval_pv (int @var{k}, const @var{UNUR_DISTR* distribution}) 8270@anchor{funct:unur_distr_discr_eval_pmf} 8271@deftypefnx Function {double} unur_distr_discr_eval_pmf (int @var{k}, const @var{UNUR_DISTR* distribution}) 8272@anchor{funct:unur_distr_discr_eval_cdf} 8273@deftypefnx Function {double} unur_distr_discr_eval_cdf (int @var{k}, const @var{UNUR_DISTR* distribution}) 8274Evaluate the PV, PMF, and the CDF, respectively, at k. 8275Notice that @var{distribution} must not be the @code{NULL} pointer. 8276If no PV is set for the @var{distribution}, then 8277@ifhtml 8278@ref{funct:unur_distr_discr_eval_pv,@command{unur_distr_discr_eval_pv}} 8279@end ifhtml 8280@ifnothtml 8281@command{unur_distr_discr_eval_pv} 8282@end ifnothtml 8283behaves like 8284@ifhtml 8285@ref{funct:unur_distr_discr_eval_pmf,@command{unur_distr_discr_eval_pmf}.} 8286@end ifhtml 8287@ifnothtml 8288@command{unur_distr_discr_eval_pmf}. 8289@end ifnothtml 8290If the corresponding function is not available for the @var{distribution}, 8291@code{UNUR_INFINITY} is returned and @code{unur_errno} is set to 8292@code{UNUR_ERR_DISTR_DATA}. 8293 8294@emph{IMPORTANT:} 8295In the case of a truncated standard distribution these calls always 8296return the respective values of the @emph{untruncated} distribution! 8297@end deftypefn 8298@end ifinfo 8299@ifnotinfo 8300@anchor{funct:unur_distr_discr_eval_pv} 8301@deftypefn {} {double} unur_distr_discr_eval_pv (int @var{k}, const @var{UNUR_DISTR* distribution}) 8302@anchor{funct:unur_distr_discr_eval_pmf} 8303@deftypefnx {} {double} unur_distr_discr_eval_pmf (int @var{k}, const @var{UNUR_DISTR* distribution}) 8304@anchor{funct:unur_distr_discr_eval_cdf} 8305@deftypefnx {} {double} unur_distr_discr_eval_cdf (int @var{k}, const @var{UNUR_DISTR* distribution}) 8306Evaluate the PV, PMF, and the CDF, respectively, at k. 8307Notice that @var{distribution} must not be the @code{NULL} pointer. 8308If no PV is set for the @var{distribution}, then 8309@ifhtml 8310@ref{funct:unur_distr_discr_eval_pv,@command{unur_distr_discr_eval_pv}} 8311@end ifhtml 8312@ifnothtml 8313@command{unur_distr_discr_eval_pv} 8314@end ifnothtml 8315behaves like 8316@ifhtml 8317@ref{funct:unur_distr_discr_eval_pmf,@command{unur_distr_discr_eval_pmf}.} 8318@end ifhtml 8319@ifnothtml 8320@command{unur_distr_discr_eval_pmf}. 8321@end ifnothtml 8322If the corresponding function is not available for the @var{distribution}, 8323@code{UNUR_INFINITY} is returned and @code{unur_errno} is set to 8324@code{UNUR_ERR_DISTR_DATA}. 8325 8326@emph{IMPORTANT:} 8327In the case of a truncated standard distribution these calls always 8328return the respective values of the @emph{untruncated} distribution! 8329@end deftypefn 8330@end ifnotinfo 8331 8332@ifinfo 8333@anchor{funct:unur_distr_discr_eval_invcdf} 8334@deftypefn Function {int} unur_distr_discr_eval_invcdf (double @var{u}, const @var{UNUR_DISTR* distribution}) 8335Evaluate the inverse CDF at @var{u}. 8336Notice that @var{distribution} must not be the @code{NULL} pointer. 8337If the corresponding function is not available for the distribution, 8338@code{INT_MAX} is returned and @code{unur_errno} is set to 8339@code{UNUR_ERR_DISTR_DATA}. 8340 8341@emph{IMPORTANT:} 8342In the case of a truncated standard distribution these calls always 8343return the respective values of the @emph{untruncated} distribution! 8344@end deftypefn 8345@end ifinfo 8346@ifnotinfo 8347@anchor{funct:unur_distr_discr_eval_invcdf} 8348@deftypefn {} {int} unur_distr_discr_eval_invcdf (double @var{u}, const @var{UNUR_DISTR* distribution}) 8349Evaluate the inverse CDF at @var{u}. 8350Notice that @var{distribution} must not be the @code{NULL} pointer. 8351If the corresponding function is not available for the distribution, 8352@code{INT_MAX} is returned and @code{unur_errno} is set to 8353@code{UNUR_ERR_DISTR_DATA}. 8354 8355@emph{IMPORTANT:} 8356In the case of a truncated standard distribution these calls always 8357return the respective values of the @emph{untruncated} distribution! 8358@end deftypefn 8359@end ifnotinfo 8360 8361@ifinfo 8362@anchor{funct:unur_distr_discr_set_pmfstr} 8363@deftypefn Function {int} unur_distr_discr_set_pmfstr (UNUR_DISTR* @var{distribution}, const @var{char* pmfstr}) 8364This function provides an alternative way to set a PMF of the 8365@var{distribution}. 8366@var{pmfstr} is a character string that contains the formula 8367for the PMF, see @ref{StringFunct,,Function String}, for details. 8368See also the remarks for the 8369@ifhtml 8370@ref{funct:unur_distr_discr_set_pmf,@command{unur_distr_discr_set_pmf}} 8371@end ifhtml 8372@ifnothtml 8373@command{unur_distr_discr_set_pmf} 8374@end ifnothtml 8375call. 8376 8377It is not possible to call this funtion twice or to call this 8378function after a 8379@ifhtml 8380@ref{funct:unur_distr_discr_set_pmf,@command{unur_distr_discr_set_pmf}} 8381@end ifhtml 8382@ifnothtml 8383@command{unur_distr_discr_set_pmf} 8384@end ifnothtml 8385call. 8386@end deftypefn 8387@end ifinfo 8388@ifnotinfo 8389@anchor{funct:unur_distr_discr_set_pmfstr} 8390@deftypefn {} {int} unur_distr_discr_set_pmfstr (UNUR_DISTR* @var{distribution}, const @var{char* pmfstr}) 8391This function provides an alternative way to set a PMF of the 8392@var{distribution}. 8393@var{pmfstr} is a character string that contains the formula 8394for the PMF, see @ref{StringFunct,,Function String}, for details. 8395See also the remarks for the 8396@ifhtml 8397@ref{funct:unur_distr_discr_set_pmf,@command{unur_distr_discr_set_pmf}} 8398@end ifhtml 8399@ifnothtml 8400@command{unur_distr_discr_set_pmf} 8401@end ifnothtml 8402call. 8403 8404It is not possible to call this funtion twice or to call this 8405function after a 8406@ifhtml 8407@ref{funct:unur_distr_discr_set_pmf,@command{unur_distr_discr_set_pmf}} 8408@end ifhtml 8409@ifnothtml 8410@command{unur_distr_discr_set_pmf} 8411@end ifnothtml 8412call. 8413@end deftypefn 8414@end ifnotinfo 8415 8416@ifinfo 8417@anchor{funct:unur_distr_discr_set_cdfstr} 8418@deftypefn Function {int} unur_distr_discr_set_cdfstr (UNUR_DISTR* @var{distribution}, const @var{char* cdfstr}) 8419This function provides an alternative way to set a CDF; analogously 8420to the 8421@ifhtml 8422@ref{funct:unur_distr_discr_set_pmfstr,@command{unur_distr_discr_set_pmfstr}} 8423@end ifhtml 8424@ifnothtml 8425@command{unur_distr_discr_set_pmfstr} 8426@end ifnothtml 8427call. 8428@end deftypefn 8429@end ifinfo 8430@ifnotinfo 8431@anchor{funct:unur_distr_discr_set_cdfstr} 8432@deftypefn {} {int} unur_distr_discr_set_cdfstr (UNUR_DISTR* @var{distribution}, const @var{char* cdfstr}) 8433This function provides an alternative way to set a CDF; analogously 8434to the 8435@ifhtml 8436@ref{funct:unur_distr_discr_set_pmfstr,@command{unur_distr_discr_set_pmfstr}} 8437@end ifhtml 8438@ifnothtml 8439@command{unur_distr_discr_set_pmfstr} 8440@end ifnothtml 8441call. 8442@end deftypefn 8443@end ifnotinfo 8444 8445@ifinfo 8446@anchor{funct:unur_distr_discr_get_pmfstr} 8447@deftypefn Function {char*} unur_distr_discr_get_pmfstr (const @var{UNUR_DISTR* distribution}) 8448@anchor{funct:unur_distr_discr_get_cdfstr} 8449@deftypefnx Function {char*} unur_distr_discr_get_cdfstr (const @var{UNUR_DISTR* distribution}) 8450Get pointer to respective string for PMF and CDF 8451of @var{distribution} that is given via the string interface. 8452This call allocates memory to produce this string. It should be 8453freed when it is not used any more. 8454@end deftypefn 8455@end ifinfo 8456@ifnotinfo 8457@anchor{funct:unur_distr_discr_get_pmfstr} 8458@deftypefn {} {char*} unur_distr_discr_get_pmfstr (const @var{UNUR_DISTR* distribution}) 8459@anchor{funct:unur_distr_discr_get_cdfstr} 8460@deftypefnx {} {char*} unur_distr_discr_get_cdfstr (const @var{UNUR_DISTR* distribution}) 8461Get pointer to respective string for PMF and CDF 8462of @var{distribution} that is given via the string interface. 8463This call allocates memory to produce this string. It should be 8464freed when it is not used any more. 8465@end deftypefn 8466@end ifnotinfo 8467 8468@ifinfo 8469@anchor{funct:unur_distr_discr_set_pmfparams} 8470@deftypefn Function {int} unur_distr_discr_set_pmfparams (UNUR_DISTR* @var{distribution}, const @var{double* params}, int @var{n_params}) 8471Set array of parameters for @var{distribution}. There is an upper limit 8472for the number of parameters @var{n_params}. It is given by the 8473macro @code{UNUR_DISTR_MAXPARAMS} in @file{unuran_config.h}. (It is set to 84745 but can be changed to any appropriate nonnegative number.) 8475If @var{n_params} is negative or exceeds this limit no parameters 8476are copied into the @var{distribution} object and @code{unur_errno} 8477is set to @code{UNUR_ERR_DISTR_NPARAMS}. 8478 8479For standard distributions from the UNU.RAN library the parameters 8480are checked. Moreover, the domain is updated automatically unless it 8481has been changed before by a 8482@ifhtml 8483@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 8484@end ifhtml 8485@ifnothtml 8486@command{unur_distr_discr_set_domain} 8487@end ifnothtml 8488call. 8489If the given parameters are invalid for the standard distribution, 8490then no parameters are set and an error code is returned. 8491Notice that the given parameter list for such a distribution is 8492handled in the same way as in the corresponding @command{new} 8493calls, i.e. optional parameters for the PDF that are not present in 8494the given list are (re-)set to their default values. 8495 8496@emph{Important:} Integer parameter must be given as @code{double}s. 8497@end deftypefn 8498@end ifinfo 8499@ifnotinfo 8500@anchor{funct:unur_distr_discr_set_pmfparams} 8501@deftypefn {} {int} unur_distr_discr_set_pmfparams (UNUR_DISTR* @var{distribution}, const @var{double* params}, int @var{n_params}) 8502Set array of parameters for @var{distribution}. There is an upper limit 8503for the number of parameters @var{n_params}. It is given by the 8504macro @code{UNUR_DISTR_MAXPARAMS} in @file{unuran_config.h}. (It is set to 85055 but can be changed to any appropriate nonnegative number.) 8506If @var{n_params} is negative or exceeds this limit no parameters 8507are copied into the @var{distribution} object and @code{unur_errno} 8508is set to @code{UNUR_ERR_DISTR_NPARAMS}. 8509 8510For standard distributions from the UNU.RAN library the parameters 8511are checked. Moreover, the domain is updated automatically unless it 8512has been changed before by a 8513@ifhtml 8514@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 8515@end ifhtml 8516@ifnothtml 8517@command{unur_distr_discr_set_domain} 8518@end ifnothtml 8519call. 8520If the given parameters are invalid for the standard distribution, 8521then no parameters are set and an error code is returned. 8522Notice that the given parameter list for such a distribution is 8523handled in the same way as in the corresponding @command{new} 8524calls, i.e. optional parameters for the PDF that are not present in 8525the given list are (re-)set to their default values. 8526 8527@emph{Important:} Integer parameter must be given as @code{double}s. 8528@end deftypefn 8529@end ifnotinfo 8530 8531@ifinfo 8532@anchor{funct:unur_distr_discr_get_pmfparams} 8533@deftypefn Function {int} unur_distr_discr_get_pmfparams (const @var{UNUR_DISTR* distribution}, const @var{double** params}) 8534Get number of parameters of the PMF and set pointer 8535@var{params} to array of parameters. If no parameters are stored 8536in the object, an error code is returned and @code{params} is set to 8537@code{NULL}. 8538@end deftypefn 8539@end ifinfo 8540@ifnotinfo 8541@anchor{funct:unur_distr_discr_get_pmfparams} 8542@deftypefn {} {int} unur_distr_discr_get_pmfparams (const @var{UNUR_DISTR* distribution}, const @var{double** params}) 8543Get number of parameters of the PMF and set pointer 8544@var{params} to array of parameters. If no parameters are stored 8545in the object, an error code is returned and @code{params} is set to 8546@code{NULL}. 8547@end deftypefn 8548@end ifnotinfo 8549 8550@ifinfo 8551@anchor{funct:unur_distr_discr_set_domain} 8552@deftypefn Function {int} unur_distr_discr_set_domain (UNUR_DISTR* @var{distribution}, int @var{left}, int @var{right}) 8553Set the left and right borders of the domain of the 8554@var{distribution}. This can also be used to truncate an existing 8555distribution. For setting the boundary to 8556@math{+/- infinity} 8557use 8558@code{INT_MIN} and @code{INT_MAX}, respectively. 8559If @var{right} is not strictly greater than @var{left} no domain 8560is set and @code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 8561It is allowed to use this call to increase the domain. 8562If the PV of the discrete distribution is used, 8563than the right boudary is ignored (and internally set to 8564@var{left} + size of PV @math{- 1}). 8565Notice that @code{INT_MIN} and @code{INT_MAX} are interpreted as 8566(minus/plus) infinity. 8567 8568Default: [@code{0}, @code{INT_MAX}]. 8569@end deftypefn 8570@end ifinfo 8571@ifnotinfo 8572@anchor{funct:unur_distr_discr_set_domain} 8573@deftypefn {} {int} unur_distr_discr_set_domain (UNUR_DISTR* @var{distribution}, int @var{left}, int @var{right}) 8574Set the left and right borders of the domain of the 8575@var{distribution}. This can also be used to truncate an existing 8576distribution. For setting the boundary to 8577@iftex 8578@math{\pm\infty} 8579@end iftex 8580@ifhtml 8581@html 8582+/- infinity 8583@end html 8584@end ifhtml 8585use 8586@code{INT_MIN} and @code{INT_MAX}, respectively. 8587If @var{right} is not strictly greater than @var{left} no domain 8588is set and @code{unur_errno} is set to @code{UNUR_ERR_DISTR_SET}. 8589It is allowed to use this call to increase the domain. 8590If the PV of the discrete distribution is used, 8591than the right boudary is ignored (and internally set to 8592@var{left} + size of PV @math{- 1}). 8593Notice that @code{INT_MIN} and @code{INT_MAX} are interpreted as 8594(minus/plus) infinity. 8595 8596Default: [@code{0}, @code{INT_MAX}]. 8597@end deftypefn 8598@end ifnotinfo 8599 8600@ifinfo 8601@anchor{funct:unur_distr_discr_get_domain} 8602@deftypefn Function {int} unur_distr_discr_get_domain (const @var{UNUR_DISTR* distribution}, int* @var{left}, int* @var{right}) 8603Get the left and right borders of the domain of the 8604@var{distribution}. If the domain is not set explicitly 8605the interval [@code{INT_MIN}, @code{INT_MAX}] is assumed and returned. 8606When a PV is given then the domain is set automatically to 8607[@code{0},size of PV @math{- 1}]. 8608@end deftypefn 8609@end ifinfo 8610@ifnotinfo 8611@anchor{funct:unur_distr_discr_get_domain} 8612@deftypefn {} {int} unur_distr_discr_get_domain (const @var{UNUR_DISTR* distribution}, int* @var{left}, int* @var{right}) 8613Get the left and right borders of the domain of the 8614@var{distribution}. If the domain is not set explicitly 8615the interval [@code{INT_MIN}, @code{INT_MAX}] is assumed and returned. 8616When a PV is given then the domain is set automatically to 8617[@code{0},size of PV @math{- 1}]. 8618@end deftypefn 8619@end ifnotinfo 8620 8621@subsubheading Derived parameters 8622 8623The following paramters @strong{must} be set whenever one of the essential 8624parameters has been set or changed (and the parameter is required 8625for the chosen method). 8626 8627@ifinfo 8628@anchor{funct:unur_distr_discr_set_mode} 8629@deftypefn Function {int} unur_distr_discr_set_mode (UNUR_DISTR* @var{distribution}, int @var{mode}) 8630Set mode of @var{distribution}. 8631@end deftypefn 8632@end ifinfo 8633@ifnotinfo 8634@anchor{funct:unur_distr_discr_set_mode} 8635@deftypefn {} {int} unur_distr_discr_set_mode (UNUR_DISTR* @var{distribution}, int @var{mode}) 8636Set mode of @var{distribution}. 8637@end deftypefn 8638@end ifnotinfo 8639 8640@ifinfo 8641@anchor{funct:unur_distr_discr_upd_mode} 8642@deftypefn Function {int} unur_distr_discr_upd_mode (UNUR_DISTR* @var{distribution}) 8643Recompute the mode of the @var{distribution}. This call works properly 8644for distribution objects from the 8645UNU.RAN library of standard distributions 8646when the corresponding function is available. 8647Otherwise a (slow) numerical mode finder is used. It only works properly 8648for unimodal probability mass functions. If it failes 8649@code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 8650@end deftypefn 8651@end ifinfo 8652@ifnotinfo 8653@anchor{funct:unur_distr_discr_upd_mode} 8654@deftypefn {} {int} unur_distr_discr_upd_mode (UNUR_DISTR* @var{distribution}) 8655Recompute the mode of the @var{distribution}. This call works properly 8656for distribution objects from the 8657UNU.RAN library of standard distributions 8658when the corresponding function is available. 8659Otherwise a (slow) numerical mode finder is used. It only works properly 8660for unimodal probability mass functions. If it failes 8661@code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 8662@end deftypefn 8663@end ifnotinfo 8664 8665@ifinfo 8666@anchor{funct:unur_distr_discr_get_mode} 8667@deftypefn Function {int} unur_distr_discr_get_mode (UNUR_DISTR* @var{distribution}) 8668Get mode of @var{distribution}. If the mode is not marked as known, 8669@ifhtml 8670@ref{funct:unur_distr_discr_upd_mode,@command{unur_distr_discr_upd_mode}} 8671@end ifhtml 8672@ifnothtml 8673@command{unur_distr_discr_upd_mode} 8674@end ifnothtml 8675is called to compute the mode. If this 8676is not successful @code{INT_MAX} is returned and 8677@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 8678(There is no difference between the case where no routine for 8679computing the mode is available and the case where no mode exists 8680for the distribution at all.) 8681@end deftypefn 8682@end ifinfo 8683@ifnotinfo 8684@anchor{funct:unur_distr_discr_get_mode} 8685@deftypefn {} {int} unur_distr_discr_get_mode (UNUR_DISTR* @var{distribution}) 8686Get mode of @var{distribution}. If the mode is not marked as known, 8687@ifhtml 8688@ref{funct:unur_distr_discr_upd_mode,@command{unur_distr_discr_upd_mode}} 8689@end ifhtml 8690@ifnothtml 8691@command{unur_distr_discr_upd_mode} 8692@end ifnothtml 8693is called to compute the mode. If this 8694is not successful @code{INT_MAX} is returned and 8695@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 8696(There is no difference between the case where no routine for 8697computing the mode is available and the case where no mode exists 8698for the distribution at all.) 8699@end deftypefn 8700@end ifnotinfo 8701 8702@ifinfo 8703@anchor{funct:unur_distr_discr_set_pmfsum} 8704@deftypefn Function {int} unur_distr_discr_set_pmfsum (UNUR_DISTR* @var{distribution}, double @var{sum}) 8705Set the sum over the PMF. If @code{sum} is non-positive, no 8706sum is set and @code{unur_errno} is set to 8707@code{UNUR_ERR_DISTR_SET}. 8708 8709For a distribution object created by the 8710UNU.RAN library of standard distributions you always should use 8711the 8712@ifhtml 8713@ref{funct:unur_distr_discr_upd_pmfsum,@command{unur_distr_discr_upd_pmfsum}.} 8714@end ifhtml 8715@ifnothtml 8716@command{unur_distr_discr_upd_pmfsum}. 8717@end ifnothtml 8718Otherwise there might be 8719ambiguous side-effects. 8720@end deftypefn 8721@end ifinfo 8722@ifnotinfo 8723@anchor{funct:unur_distr_discr_set_pmfsum} 8724@deftypefn {} {int} unur_distr_discr_set_pmfsum (UNUR_DISTR* @var{distribution}, double @var{sum}) 8725Set the sum over the PMF. If @code{sum} is non-positive, no 8726sum is set and @code{unur_errno} is set to 8727@code{UNUR_ERR_DISTR_SET}. 8728 8729For a distribution object created by the 8730UNU.RAN library of standard distributions you always should use 8731the 8732@ifhtml 8733@ref{funct:unur_distr_discr_upd_pmfsum,@command{unur_distr_discr_upd_pmfsum}.} 8734@end ifhtml 8735@ifnothtml 8736@command{unur_distr_discr_upd_pmfsum}. 8737@end ifnothtml 8738Otherwise there might be 8739ambiguous side-effects. 8740@end deftypefn 8741@end ifnotinfo 8742 8743@ifinfo 8744@anchor{funct:unur_distr_discr_upd_pmfsum} 8745@deftypefn Function {int} unur_distr_discr_upd_pmfsum (UNUR_DISTR* @var{distribution}) 8746Recompute the sum over the PMF of the @var{distribution}. 8747In most cases the normalization constant is recomputed and thus the 8748sum is 1. This call works for distribution objects from the UNU.RAN 8749library of standard distributions when the corresponding function 8750is available. When a PV, a PMF with finite domain, or a CDF is 8751given, a simple generic function which uses a naive summation loop 8752is used. If this computation is not possible, an error code is 8753returned and @code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 8754 8755The call does not work for distributions from the 8756UNU.RAN library of standard distributions with truncated 8757domain when the CDF is not available. 8758@end deftypefn 8759@end ifinfo 8760@ifnotinfo 8761@anchor{funct:unur_distr_discr_upd_pmfsum} 8762@deftypefn {} {int} unur_distr_discr_upd_pmfsum (UNUR_DISTR* @var{distribution}) 8763Recompute the sum over the PMF of the @var{distribution}. 8764In most cases the normalization constant is recomputed and thus the 8765sum is 1. This call works for distribution objects from the UNU.RAN 8766library of standard distributions when the corresponding function 8767is available. When a PV, a PMF with finite domain, or a CDF is 8768given, a simple generic function which uses a naive summation loop 8769is used. If this computation is not possible, an error code is 8770returned and @code{unur_errno} is set to @code{UNUR_ERR_DISTR_DATA}. 8771 8772The call does not work for distributions from the 8773UNU.RAN library of standard distributions with truncated 8774domain when the CDF is not available. 8775@end deftypefn 8776@end ifnotinfo 8777 8778@ifinfo 8779@anchor{funct:unur_distr_discr_get_pmfsum} 8780@deftypefn Function {double} unur_distr_discr_get_pmfsum (UNUR_DISTR* @var{distribution}) 8781Get the sum over the PMF of the @var{distribution}. If this sum is 8782not known, 8783@ifhtml 8784@ref{funct:unur_distr_discr_upd_pmfsum,@command{unur_distr_discr_upd_pmfsum}} 8785@end ifhtml 8786@ifnothtml 8787@command{unur_distr_discr_upd_pmfsum} 8788@end ifnothtml 8789is called to compute 8790it. If this is not successful @code{UNUR_INFINITY} is returned and 8791@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 8792@end deftypefn 8793@end ifinfo 8794@ifnotinfo 8795@anchor{funct:unur_distr_discr_get_pmfsum} 8796@deftypefn {} {double} unur_distr_discr_get_pmfsum (UNUR_DISTR* @var{distribution}) 8797Get the sum over the PMF of the @var{distribution}. If this sum is 8798not known, 8799@ifhtml 8800@ref{funct:unur_distr_discr_upd_pmfsum,@command{unur_distr_discr_upd_pmfsum}} 8801@end ifhtml 8802@ifnothtml 8803@command{unur_distr_discr_upd_pmfsum} 8804@end ifnothtml 8805is called to compute 8806it. If this is not successful @code{UNUR_INFINITY} is returned and 8807@code{unur_errno} is set to @code{UNUR_ERR_DISTR_GET}. 8808@end deftypefn 8809@end ifnotinfo 8810 8811 8812 8813 8814@c 8815@c end of discr.h 8816@c ------------------------------------- 8817@c ------------------------------------- 8818@c methods.dh 8819@c 8820 8821@node Methods 8822@chapter Methods for generating non-uniform random variates 8823 8824@menu 8825* Methods_all:: Routines for all generator objects 8826* AUTO:: Select method automatically 8827* Methods_for_CONT:: Methods for continuous univariate distributions 8828* Methods_for_CEMP:: Methods for continuous empirical univariate distributions 8829* Methods_for_CVEC:: Methods for continuous multivariate distributions 8830* MCMC_Methods_for_CVEC:: Markov chain samplers for continuous multivariate distributions 8831* Methods_for_CVEMP:: Methods for continuous empirical multivariate distributions 8832* Methods_for_DISCR:: Methods for discrete univariate distributions 8833* Methods_for_MATR:: Methods for random matrices 8834* Methods_for_UNID:: Methods for uniform univariate distributions 8835* Meta_Methods:: Meta Methods for univariate distributions 8836@end menu 8837 8838 8839 8840Sampling from a particular distribution with UNU.RAN requires the 8841following steps: 8842 8843@enumerate 8844@item 8845Create a distribution object 8846(@pxref{Distribution_objects,,Handling distribution objects}). 8847 8848@item 8849Select a method and create a parameter object. 8850 8851@item 8852Initizialize the generator object using 8853@ifhtml 8854@ref{funct:unur_init,@command{unur_init}.} 8855@end ifhtml 8856@ifnothtml 8857@command{unur_init}. 8858@end ifnothtml 8859@sp 1 8860@emph{Important}: Initialization of the generator object might fail. 8861@ifhtml 8862@ref{funct:unur_init,@command{unur_init}} 8863@end ifhtml 8864@ifnothtml 8865@command{unur_init} 8866@end ifnothtml 8867returns a @code{NULL} pointer then, which @strong{must} not be 8868used for sampling. 8869 8870@item 8871Draw a sample from the generator object using the 8872corresponding sampling function (depending on the type of 8873distribution: 8874univariate continuous, univariate discrete, multivariate 8875continuous, and random matrix). 8876 8877@item 8878It is possible for a generator object to change the parameters and the 8879domain of the underlying distribution. This must be done by extracting 8880this object by means of a 8881@ifhtml 8882@ref{funct:unur_get_distr,@command{unur_get_distr}} 8883@end ifhtml 8884@ifnothtml 8885@command{unur_get_distr} 8886@end ifnothtml 8887call and 8888changing the distribution using the correspondig set calls, 8889see @ref{Distribution_objects,,Handling distribution objects}. 8890The generator object @strong{must} then be reinitialized by means of 8891the 8892@ifhtml 8893@ref{funct:unur_reinit,@command{unur_reinit}} 8894@end ifhtml 8895@ifnothtml 8896@command{unur_reinit} 8897@end ifnothtml 8898call. 8899 8900@emph{Important}: Currently not all methods allow reinitialization, 8901see the description of the particular method (keyword @i{Reinit}). 8902 8903@emph{Important}: Reinitialization of the generator object might fail. 8904Thus one @strong{must} check the return code of the 8905@ifhtml 8906@ref{funct:unur_reinit,@command{unur_reinit}} 8907@end ifhtml 8908@ifnothtml 8909@command{unur_reinit} 8910@end ifnothtml 8911call. 8912 8913@emph{Important}: When reinitialization fails then sampling routines 8914always return INFINITY (for continuous distributions) or @code{0} (for 8915discrete distributions), respectively. 8916However, it is still possible to change the underlying distribution 8917and try to reinitialize again. 8918 8919@end enumerate 8920 8921 8922 8923@c 8924@c end of methods.dh 8925@c ------------------------------------- 8926@c ------------------------------------- 8927@c x_gen.h 8928@c 8929 8930@node Methods_all 8931@section Routines for all generator objects 8932 8933 8934Routines for all generator objects. 8935 8936 8937@subheading Function reference 8938 8939@ifhtml 8940@itemize 8941@item @ref{funct:unur_init,unur_init} 8942@item @ref{funct:unur_reinit,unur_reinit} 8943@item @ref{funct:unur_sample_discr,unur_sample_discr} 8944@item @ref{funct:unur_sample_cont,unur_sample_cont} 8945@item @ref{funct:unur_sample_vec,unur_sample_vec} 8946@item @ref{funct:unur_sample_matr,unur_sample_matr} 8947@item @ref{funct:unur_quantile,unur_quantile} 8948@item @ref{funct:unur_free,unur_free} 8949@item @ref{funct:unur_gen_info,unur_gen_info} 8950@item @ref{funct:unur_get_dimension,unur_get_dimension} 8951@item @ref{funct:unur_get_genid,unur_get_genid} 8952@item @ref{funct:unur_get_distr,unur_get_distr} 8953@item @ref{funct:unur_set_use_distr_privatecopy,unur_set_use_distr_privatecopy} 8954@end itemize 8955@end ifhtml 8956 8957 8958@ifinfo 8959@anchor{funct:unur_init} 8960@deftypefn Function {UNUR_GEN*} unur_init (UNUR_PAR* @var{parameters}) 8961Initialize a generator object. All necessary information must be 8962stored in the parameter object. 8963 8964@strong{Important:} If an error has occurred a @code{NULL} pointer is 8965return. This must not be used for the sampling routines (this causes a 8966segmentation fault). 8967 8968@strong{Always} check whether the call was successful or not! 8969 8970@emph{Important:} This call destroys the @var{parameter} object 8971automatically. Thus it is not necessary/allowed to free it. 8972@end deftypefn 8973@end ifinfo 8974@ifnotinfo 8975@anchor{funct:unur_init} 8976@deftypefn {} {UNUR_GEN*} unur_init (UNUR_PAR* @var{parameters}) 8977Initialize a generator object. All necessary information must be 8978stored in the parameter object. 8979 8980@strong{Important:} If an error has occurred a @code{NULL} pointer is 8981return. This must not be used for the sampling routines (this causes a 8982segmentation fault). 8983 8984@strong{Always} check whether the call was successful or not! 8985 8986@emph{Important:} This call destroys the @var{parameter} object 8987automatically. Thus it is not necessary/allowed to free it. 8988@end deftypefn 8989@end ifnotinfo 8990 8991@ifinfo 8992@anchor{funct:unur_reinit} 8993@deftypefn Function {int} unur_reinit (UNUR_GEN* @var{generator}) 8994Update an existing generator object after the underlying 8995distribution has been modified (using 8996@ifhtml 8997@ref{funct:unur_get_distr,@command{unur_get_distr}} 8998@end ifhtml 8999@ifnothtml 9000@command{unur_get_distr} 9001@end ifnothtml 9002together 9003with corresponding set calls. 9004It @strong{must} be executed before sampling using this generator 9005object is continued as otherwise it produces an invalid sample or 9006might even cause a segmentation fault. 9007 9008@emph{Important}: Currently not all methods allow reinitialization, 9009see the description of the particular method (keyword @i{Reinit}). 9010 9011@emph{Important}: Reinitialization of the generator object might fail. 9012Thus one @strong{must} check the return code: 9013 9014@table @asis 9015@item @code{UNUR_SUCCESS (0x0u)} 9016success (no error) 9017@item @code{UNUR_ERR_NO_REINIT} 9018reinit routine not implemented. 9019@item other values 9020some error has occured while trying to reinitialize the generator 9021object. 9022@end table 9023 9024@emph{Important}: When reinitialization fails then sampling routines 9025always return INFINITY (for continuous distributions) or @code{0} (for 9026discrete distributions), respectively. 9027However, it is still possible to change the underlying distribution 9028and try to reinitialize again. 9029 9030@emph{Important}: When one tries to run 9031@ifhtml 9032@ref{funct:unur_reinit,@command{unur_reinit},} 9033@end ifhtml 9034@ifnothtml 9035@command{unur_reinit}, 9036@end ifnothtml 9037but reinitialization 9038is not implemented, then the generator object cannot be used any more 9039and must be destroyed and a new one has to be built from scratch. 9040@end deftypefn 9041@end ifinfo 9042@ifnotinfo 9043@anchor{funct:unur_reinit} 9044@deftypefn {} {int} unur_reinit (UNUR_GEN* @var{generator}) 9045Update an existing generator object after the underlying 9046distribution has been modified (using 9047@ifhtml 9048@ref{funct:unur_get_distr,@command{unur_get_distr}} 9049@end ifhtml 9050@ifnothtml 9051@command{unur_get_distr} 9052@end ifnothtml 9053together 9054with corresponding set calls. 9055It @strong{must} be executed before sampling using this generator 9056object is continued as otherwise it produces an invalid sample or 9057might even cause a segmentation fault. 9058 9059@emph{Important}: Currently not all methods allow reinitialization, 9060see the description of the particular method (keyword @i{Reinit}). 9061 9062@emph{Important}: Reinitialization of the generator object might fail. 9063Thus one @strong{must} check the return code: 9064 9065@table @asis 9066@item @code{UNUR_SUCCESS (0x0u)} 9067success (no error) 9068@item @code{UNUR_ERR_NO_REINIT} 9069reinit routine not implemented. 9070@item other values 9071some error has occured while trying to reinitialize the generator 9072object. 9073@end table 9074 9075@emph{Important}: When reinitialization fails then sampling routines 9076always return INFINITY (for continuous distributions) or @code{0} (for 9077discrete distributions), respectively. 9078However, it is still possible to change the underlying distribution 9079and try to reinitialize again. 9080 9081@emph{Important}: When one tries to run 9082@ifhtml 9083@ref{funct:unur_reinit,@command{unur_reinit},} 9084@end ifhtml 9085@ifnothtml 9086@command{unur_reinit}, 9087@end ifnothtml 9088but reinitialization 9089is not implemented, then the generator object cannot be used any more 9090and must be destroyed and a new one has to be built from scratch. 9091@end deftypefn 9092@end ifnotinfo 9093 9094@ifinfo 9095@anchor{funct:unur_sample_discr} 9096@deftypefn Function {int } unur_sample_discr (UNUR_GEN* @var{generator}) 9097@anchor{funct:unur_sample_cont} 9098@deftypefnx Function {double} unur_sample_cont (UNUR_GEN* @var{generator}) 9099@anchor{funct:unur_sample_vec} 9100@deftypefnx Function {int } unur_sample_vec (UNUR_GEN* @var{generator}, double* @var{vector}) 9101@anchor{funct:unur_sample_matr} 9102@deftypefnx Function {int } unur_sample_matr (UNUR_GEN* @var{generator}, double* @var{matrix}) 9103Sample from generator object. The three routines depend on the type 9104of the generator object (discrete or continuous univariate 9105distribution, multivariate distribution, or random matrix). 9106 9107@emph{Notice:} UNU.RAN uses arrays of @code{double}s to handle 9108matrices. There the rows of the matrix are stored consecutively. 9109 9110@emph{Notice:} The routines 9111@ifhtml 9112@ref{funct:unur_sample_vec,@command{unur_sample_vec}} 9113@end ifhtml 9114@ifnothtml 9115@command{unur_sample_vec} 9116@end ifnothtml 9117and 9118@ifhtml 9119@ref{funct:unur_sample_matr,@command{unur_sample_matr}} 9120@end ifhtml 9121@ifnothtml 9122@command{unur_sample_matr} 9123@end ifnothtml 9124return @code{UNUR_SUCCESS} if generation was successful and 9125some error code otherwise. 9126 9127@strong{Important:} These routines do @strong{not} check whether 9128@var{generator} is an invalid @code{NULL} pointer. 9129@end deftypefn 9130@end ifinfo 9131@ifnotinfo 9132@anchor{funct:unur_sample_discr} 9133@deftypefn {} {int } unur_sample_discr (UNUR_GEN* @var{generator}) 9134@anchor{funct:unur_sample_cont} 9135@deftypefnx {} {double} unur_sample_cont (UNUR_GEN* @var{generator}) 9136@anchor{funct:unur_sample_vec} 9137@deftypefnx {} {int } unur_sample_vec (UNUR_GEN* @var{generator}, double* @var{vector}) 9138@anchor{funct:unur_sample_matr} 9139@deftypefnx {} {int } unur_sample_matr (UNUR_GEN* @var{generator}, double* @var{matrix}) 9140Sample from generator object. The three routines depend on the type 9141of the generator object (discrete or continuous univariate 9142distribution, multivariate distribution, or random matrix). 9143 9144@emph{Notice:} UNU.RAN uses arrays of @code{double}s to handle 9145matrices. There the rows of the matrix are stored consecutively. 9146 9147@emph{Notice:} The routines 9148@ifhtml 9149@ref{funct:unur_sample_vec,@command{unur_sample_vec}} 9150@end ifhtml 9151@ifnothtml 9152@command{unur_sample_vec} 9153@end ifnothtml 9154and 9155@ifhtml 9156@ref{funct:unur_sample_matr,@command{unur_sample_matr}} 9157@end ifhtml 9158@ifnothtml 9159@command{unur_sample_matr} 9160@end ifnothtml 9161return @code{UNUR_SUCCESS} if generation was successful and 9162some error code otherwise. 9163 9164@strong{Important:} These routines do @strong{not} check whether 9165@var{generator} is an invalid @code{NULL} pointer. 9166@end deftypefn 9167@end ifnotinfo 9168 9169@ifinfo 9170@anchor{funct:unur_quantile} 9171@deftypefn Function {double} unur_quantile (UNUR_GEN* @var{generator}, double @var{U}) 9172Compute the @var{U} quantile of a continuous distribution using a 9173@var{generator} object that implements an (approximate) inversion 9174methods. 9175 9176The following methods are currently available: 9177@itemize 9178@item 9179HINV, @pxref{HINV}. 9180@item 9181NINV, @pxref{NINV}. 9182@item 9183PINV, @pxref{PINV}. 9184@item 9185CSTD, @pxref{CSTD}. @* 9186This requires that @var{generator} implements an inversion method. 9187@item 9188DGT, @pxref{DGT}. @* 9189The return value is (of course) type casted to @code{double}. 9190@end itemize 9191 9192@strong{Important:} This routine does @strong{not} check whether 9193@var{generator} is an invalid @code{NULL} pointer. 9194 9195In case of an error UNUR_INFINITY or INT_MAX 9196(depending on the type of @var{generator}) is returned. 9197@end deftypefn 9198@end ifinfo 9199@ifnotinfo 9200@anchor{funct:unur_quantile} 9201@deftypefn {} {double} unur_quantile (UNUR_GEN* @var{generator}, double @var{U}) 9202Compute the @var{U} quantile of a continuous distribution using a 9203@var{generator} object that implements an (approximate) inversion 9204methods. 9205 9206The following methods are currently available: 9207@itemize 9208@item 9209HINV, @pxref{HINV}. 9210@item 9211NINV, @pxref{NINV}. 9212@item 9213PINV, @pxref{PINV}. 9214@item 9215CSTD, @pxref{CSTD}. @* 9216This requires that @var{generator} implements an inversion method. 9217@item 9218DGT, @pxref{DGT}. @* 9219The return value is (of course) type casted to @code{double}. 9220@end itemize 9221 9222@strong{Important:} This routine does @strong{not} check whether 9223@var{generator} is an invalid @code{NULL} pointer. 9224 9225In case of an error UNUR_INFINITY or INT_MAX 9226(depending on the type of @var{generator}) is returned. 9227@end deftypefn 9228@end ifnotinfo 9229 9230@ifinfo 9231@anchor{funct:unur_free} 9232@deftypefn Function {void } unur_free (UNUR_GEN* @var{generator}) 9233Destroy (free) the given generator object. 9234@end deftypefn 9235@end ifinfo 9236@ifnotinfo 9237@anchor{funct:unur_free} 9238@deftypefn {} {void } unur_free (UNUR_GEN* @var{generator}) 9239Destroy (free) the given generator object. 9240@end deftypefn 9241@end ifnotinfo 9242 9243@ifinfo 9244@anchor{funct:unur_gen_info} 9245@deftypefn Function {const char*} unur_gen_info (UNUR_GEN* @var{generator}, int @var{help}) 9246Get a string with informations about the given @var{generator}. 9247These informations allow some fine tuning of the generation method. 9248If @var{help} is @code{TRUE}, some hints on setting parameters are given. 9249 9250This function is intented for using in interactive environments 9251(like @t{R}). 9252 9253If an error occurs, then @code{NULL} is returned. 9254@end deftypefn 9255@end ifinfo 9256@ifnotinfo 9257@anchor{funct:unur_gen_info} 9258@deftypefn {} {const char*} unur_gen_info (UNUR_GEN* @var{generator}, int @var{help}) 9259Get a string with informations about the given @var{generator}. 9260These informations allow some fine tuning of the generation method. 9261If @var{help} is @code{TRUE}, some hints on setting parameters are given. 9262 9263This function is intented for using in interactive environments 9264(like @t{R}). 9265 9266If an error occurs, then @code{NULL} is returned. 9267@end deftypefn 9268@end ifnotinfo 9269 9270@ifinfo 9271@anchor{funct:unur_get_dimension} 9272@deftypefn Function {int} unur_get_dimension (const @var{UNUR_GEN* generator}) 9273Get the number of dimension of a (multivariate) distribution. 9274For a univariate distribution @code{1} is return. 9275@end deftypefn 9276@end ifinfo 9277@ifnotinfo 9278@anchor{funct:unur_get_dimension} 9279@deftypefn {} {int} unur_get_dimension (const @var{UNUR_GEN* generator}) 9280Get the number of dimension of a (multivariate) distribution. 9281For a univariate distribution @code{1} is return. 9282@end deftypefn 9283@end ifnotinfo 9284 9285@ifinfo 9286@anchor{funct:unur_get_genid} 9287@deftypefn Function {const char*} unur_get_genid (const @var{UNUR_GEN* generator}) 9288Get identifier string for generator. 9289@end deftypefn 9290@end ifinfo 9291@ifnotinfo 9292@anchor{funct:unur_get_genid} 9293@deftypefn {} {const char*} unur_get_genid (const @var{UNUR_GEN* generator}) 9294Get identifier string for generator. 9295@end deftypefn 9296@end ifnotinfo 9297 9298@ifinfo 9299@anchor{funct:unur_get_distr} 9300@deftypefn Function {UNUR_DISTR*} unur_get_distr (const @var{UNUR_GEN* generator}) 9301Get pointer to distribution object from generator object. 9302This function can be used to change the parameters of the distribution 9303and reinitialize the generator object. 9304Notice that currently @strong{not all} generating methods have a 9305reinitialize routine. 9306This function should be used with extreme care. Changing the distribution 9307is changed and using the generator object without reinitializing 9308might cause wrong samples or segmentation faults. 9309Moreover, if the corresponding generator object is freed, the 9310pointer must not be used. 9311 9312@strong{Important:} The returned distribution object must not 9313be freed. If the distribution object is changed then one @strong{must} 9314run 9315@ifhtml 9316@ref{funct:unur_reinit,@command{unur_reinit}} 9317@end ifhtml 9318@ifnothtml 9319@command{unur_reinit} 9320@end ifnothtml 9321! 9322@end deftypefn 9323@end ifinfo 9324@ifnotinfo 9325@anchor{funct:unur_get_distr} 9326@deftypefn {} {UNUR_DISTR*} unur_get_distr (const @var{UNUR_GEN* generator}) 9327Get pointer to distribution object from generator object. 9328This function can be used to change the parameters of the distribution 9329and reinitialize the generator object. 9330Notice that currently @strong{not all} generating methods have a 9331reinitialize routine. 9332This function should be used with extreme care. Changing the distribution 9333is changed and using the generator object without reinitializing 9334might cause wrong samples or segmentation faults. 9335Moreover, if the corresponding generator object is freed, the 9336pointer must not be used. 9337 9338@strong{Important:} The returned distribution object must not 9339be freed. If the distribution object is changed then one @strong{must} 9340run 9341@ifhtml 9342@ref{funct:unur_reinit,@command{unur_reinit}} 9343@end ifhtml 9344@ifnothtml 9345@command{unur_reinit} 9346@end ifnothtml 9347! 9348@end deftypefn 9349@end ifnotinfo 9350 9351@ifinfo 9352@anchor{funct:unur_set_use_distr_privatecopy} 9353@deftypefn Function {int} unur_set_use_distr_privatecopy (UNUR_PAR* @var{parameters}, int @var{use_privatecopy}) 9354Set flag whether the generator object should make a private copy of 9355the given distribution object or just stores the pointer to this 9356distribution object. Values for @var{use_privatecopy}: 9357@table @code 9358@item @code{TRUE} 9359make a private copy (default) 9360@item @code{FALSE} 9361do not make a private copy and store pointer to given (external) 9362distribution object. 9363@end table 9364 9365By default, generator objects keep their own private copy of the 9366given distribution object. Thus the generator object can be handled 9367independently from other UNU.RAN objects (with uniform random number 9368generators as the only exception). When the generator object is 9369initialized the given distribution object is cloned and stored. 9370 9371However, in some rare situations it can be useful when only the 9372pointer to the given distribution object is stored without making a 9373private copy. A possible example is when only one random variate has 9374to be drawn from the distribution. 9375This behavior can be achieved when @var{use_localcopy} is set to 9376@code{FALSE}. 9377 9378@strong{Warning!} 9379Using a pointer to the external distribution object instead of a 9380private copy must be done with @strong{extreme care}! 9381When the distrubtion object is changed or freed then the generator 9382object does not work any more, might case a segmentation fault, or 9383(even worse) produces garbage. 9384On the other hand, when the generator object is initialized or used 9385to draw a random sampling the distribution object may be changed. 9386 9387@emph{Notice:} 9388The prototypes of all @code{unur_<method>_new} calls use a 9389@code{const} qualifier for the distribution argument. 9390However, if @var{use_privatecopy} is set to @code{FALSE} this qualifier is 9391discarded and the distribution might be changed. 9392 9393@strong{Important!} 9394If @var{use_localcopy} is set to @code{FALSE} and the corresponding 9395distribution object is changed then one must run 9396@ifhtml 9397@ref{funct:unur_reinit,@command{unur_reinit}} 9398@end ifhtml 9399@ifnothtml 9400@command{unur_reinit} 9401@end ifnothtml 9402on the generator object. 9403(Notice that currently not all generation methods support 9404reinitialization.) 9405 9406Default: @var{use_privatecopy} is @code{TRUE}. 9407@end deftypefn 9408@end ifinfo 9409@ifnotinfo 9410@anchor{funct:unur_set_use_distr_privatecopy} 9411@deftypefn {} {int} unur_set_use_distr_privatecopy (UNUR_PAR* @var{parameters}, int @var{use_privatecopy}) 9412Set flag whether the generator object should make a private copy of 9413the given distribution object or just stores the pointer to this 9414distribution object. Values for @var{use_privatecopy}: 9415@table @code 9416@item @code{TRUE} 9417make a private copy (default) 9418@item @code{FALSE} 9419do not make a private copy and store pointer to given (external) 9420distribution object. 9421@end table 9422 9423By default, generator objects keep their own private copy of the 9424given distribution object. Thus the generator object can be handled 9425independently from other UNU.RAN objects (with uniform random number 9426generators as the only exception). When the generator object is 9427initialized the given distribution object is cloned and stored. 9428 9429However, in some rare situations it can be useful when only the 9430pointer to the given distribution object is stored without making a 9431private copy. A possible example is when only one random variate has 9432to be drawn from the distribution. 9433This behavior can be achieved when @var{use_localcopy} is set to 9434@code{FALSE}. 9435 9436@strong{Warning!} 9437Using a pointer to the external distribution object instead of a 9438private copy must be done with @strong{extreme care}! 9439When the distrubtion object is changed or freed then the generator 9440object does not work any more, might case a segmentation fault, or 9441(even worse) produces garbage. 9442On the other hand, when the generator object is initialized or used 9443to draw a random sampling the distribution object may be changed. 9444 9445@emph{Notice:} 9446The prototypes of all @code{unur_<method>_new} calls use a 9447@code{const} qualifier for the distribution argument. 9448However, if @var{use_privatecopy} is set to @code{FALSE} this qualifier is 9449discarded and the distribution might be changed. 9450 9451@strong{Important!} 9452If @var{use_localcopy} is set to @code{FALSE} and the corresponding 9453distribution object is changed then one must run 9454@ifhtml 9455@ref{funct:unur_reinit,@command{unur_reinit}} 9456@end ifhtml 9457@ifnothtml 9458@command{unur_reinit} 9459@end ifnothtml 9460on the generator object. 9461(Notice that currently not all generation methods support 9462reinitialization.) 9463 9464Default: @var{use_privatecopy} is @code{TRUE}. 9465@end deftypefn 9466@end ifnotinfo 9467 9468 9469 9470 9471@c 9472@c end of x_gen.h 9473@c ------------------------------------- 9474@c ------------------------------------- 9475@c auto.h 9476@c 9477 9478@page 9479@node AUTO 9480@section AUTO -- Select method automatically 9481 9482 9483AUTO selects a an appropriate method for the given distribution 9484object automatically. There are no parameters for this method, 9485yet. But it is planned to give some parameter to describe the 9486task for which the random variate generator is used for and thus 9487make the choice of the generating method more appropriate. 9488Notice that the required sampling routine for the generator 9489object depends on the type of the given distribution object. 9490 9491The chosen method also depends on the sample size for which the 9492generator object will be used. If only a few random variates 9493the order of magnitude of the sample size should be set via a 9494@ifhtml 9495@ref{funct:unur_auto_set_logss,@command{unur_auto_set_logss}} 9496@end ifhtml 9497@ifnothtml 9498@command{unur_auto_set_logss} 9499@end ifnothtml 9500call. 9501 9502IMPORTANT: This is an experimental version and the method chosen 9503may change in future releases of UNU.RAN. 9504 9505For an example see @ref{Example_0,As short as possible,Example: As short as possible}. 9506 9507 9508@subsubheading How To Use 9509 9510 9511Create a generator object for the given distribution object. 9512 9513 9514 9515 9516@subheading Function reference 9517 9518@ifhtml 9519@itemize 9520@item @ref{funct:unur_auto_new,unur_auto_new} 9521@item @ref{funct:unur_auto_set_logss,unur_auto_set_logss} 9522@end itemize 9523@end ifhtml 9524 9525 9526@ifinfo 9527@anchor{funct:unur_auto_new} 9528@deftypefn Function {UNUR_PAR*} unur_auto_new (const @var{UNUR_DISTR* distribution}) 9529Get default parameters for generator. 9530@end deftypefn 9531@end ifinfo 9532@ifnotinfo 9533@anchor{funct:unur_auto_new} 9534@deftypefn {} {UNUR_PAR*} unur_auto_new (const @var{UNUR_DISTR* distribution}) 9535Get default parameters for generator. 9536@end deftypefn 9537@end ifnotinfo 9538 9539@ifinfo 9540@anchor{funct:unur_auto_set_logss} 9541@deftypefn Function {int} unur_auto_set_logss (UNUR_PAR* @var{parameters}, int @var{logss}) 9542Set the order of magnitude for the size of the sample that will be 9543generated by the generator, i.e., the the common logarithm of the 9544sample size. 9545 9546Default is 10. 9547 9548Notice: This feature will be used in future releases of UNU.RAN only. 9549@end deftypefn 9550@end ifinfo 9551@ifnotinfo 9552@anchor{funct:unur_auto_set_logss} 9553@deftypefn {} {int} unur_auto_set_logss (UNUR_PAR* @var{parameters}, int @var{logss}) 9554Set the order of magnitude for the size of the sample that will be 9555generated by the generator, i.e., the the common logarithm of the 9556sample size. 9557 9558Default is 10. 9559 9560Notice: This feature will be used in future releases of UNU.RAN only. 9561@end deftypefn 9562@end ifnotinfo 9563 9564 9565 9566 9567@c 9568@c end of auto.h 9569@c ------------------------------------- 9570@c ------------------------------------- 9571@c methods.dh 9572@c 9573 9574@page 9575@node Methods_for_CONT 9576@section Methods for continuous univariate distributions 9577 9578@menu 9579* AROU:: Automatic Ratio-Of-Uniforms method 9580* ARS:: Adaptive Rejection Sampling 9581* CEXT:: wrapper for Continuous EXTernal generators 9582* CSTD:: Continuous STandarD distributions 9583* HINV:: Hermite interpolation based INVersion of CDF 9584* HRB:: Hazard Rate Bounded 9585* HRD:: Hazard Rate Decreasing 9586* HRI:: Hazard Rate Increasing 9587* ITDR:: Inverse Transformed Density Rejection 9588* NINV:: Numerical INVersion 9589* NROU:: Naive Ratio-Of-Uniforms method 9590* PINV:: Polynomial interpolation based INVersion of CDF 9591* SROU:: Simple Ratio-Of-Uniforms method 9592* SSR:: Simple Setup Rejection 9593* TABL:: a TABLe method with piecewise constant hats 9594* TDR:: Transformed Density Rejection 9595* UTDR:: Universal Transformed Density Rejection 9596@end menu 9597 9598 9599 9600@subheading Overview of methods 9601 9602@include methods_cont.texi 9603 9604@subheading Example 9605 9606@smallexample 9607@include ref_example_cont.texi 9608@end smallexample 9609 9610@subheading Example (String API) 9611 9612@smallexample 9613@include ref_example_cont_str.texi 9614@end smallexample 9615 9616 9617 9618@c 9619@c end of methods.dh 9620@c ------------------------------------- 9621@c ------------------------------------- 9622@c arou.h 9623@c 9624 9625@page 9626@node AROU 9627@subsection AROU -- Automatic Ratio-Of-Uniforms method 9628 9629@table @i 9630@item Required: 9631T-concave PDF, dPDF 9632@item Optional: 9633mode 9634@item Speed: 9635Set-up: slow, Sampling: fast 9636@item Reinit: 9637not implemented 9638@item Reference: 9639@ifhtml 9640@ref{bib:LJa00,, [LJa00]} 9641@end ifhtml 9642@ifnothtml 9643[LJa00] 9644@end ifnothtml 9645 9646@end table 9647@sp 1 9648 9649 9650AROU is a variant of the ratio-of-uniforms method that uses the 9651fact that the transformed region is convex for many distributions. 9652It works for all T-concave distributions with T(x) = -1/sqrt(x). 9653 9654It is possible to use this method for correlation induction by 9655setting an auxiliary uniform random number generator via the 9656@ifhtml 9657@ref{funct:unur_set_urng_aux,@command{unur_set_urng_aux}} 9658@end ifhtml 9659@ifnothtml 9660@command{unur_set_urng_aux} 9661@end ifnothtml 9662call. (Notice that this must be done after a 9663possible 9664@ifhtml 9665@ref{funct:unur_set_urng,@command{unur_set_urng}} 9666@end ifhtml 9667@ifnothtml 9668@command{unur_set_urng} 9669@end ifnothtml 9670call.) 9671When an auxiliary generator is used then the number of used 9672uniform random numbers that is used up for one generated random 9673variate is constant and equal to 1. 9674 9675There exists a test mode that verifies whether the conditions for 9676the method are satisfied or not while sampling. It can be 9677switched on by calling 9678@ifhtml 9679@ref{funct:unur_arou_set_verify,@command{unur_arou_set_verify}} 9680@end ifhtml 9681@ifnothtml 9682@command{unur_arou_set_verify} 9683@end ifnothtml 9684and 9685@ifhtml 9686@ref{funct:unur_arou_chg_verify,@command{unur_arou_chg_verify},} 9687@end ifhtml 9688@ifnothtml 9689@command{unur_arou_chg_verify}, 9690@end ifnothtml 9691respectively. 9692Notice however that sampling is (much) slower then. 9693 9694For densities with modes not close to 0 it is suggested to set 9695either the mode or the center of the distribution by the 9696@ifhtml 9697@ref{funct:unur_distr_cont_set_mode,@command{unur_distr_cont_set_mode}} 9698@end ifhtml 9699@ifnothtml 9700@command{unur_distr_cont_set_mode} 9701@end ifnothtml 9702or 9703@ifhtml 9704@ref{funct:unur_distr_cont_set_center,@command{unur_distr_cont_set_center}} 9705@end ifhtml 9706@ifnothtml 9707@command{unur_distr_cont_set_center} 9708@end ifnothtml 9709call. 9710The latter is the approximate location of the mode or the mean 9711of the distribution. This location provides some information 9712about the main part of the PDF and is used to avoid numerical 9713problems. 9714 9715 9716@subheading Function reference 9717 9718@ifhtml 9719@itemize 9720@item @ref{funct:unur_arou_new,unur_arou_new} 9721@item @ref{funct:unur_arou_set_usedars,unur_arou_set_usedars} 9722@item @ref{funct:unur_arou_set_darsfactor,unur_arou_set_darsfactor} 9723@item @ref{funct:unur_arou_set_max_sqhratio,unur_arou_set_max_sqhratio} 9724@item @ref{funct:unur_arou_get_sqhratio,unur_arou_get_sqhratio} 9725@item @ref{funct:unur_arou_get_hatarea,unur_arou_get_hatarea} 9726@item @ref{funct:unur_arou_get_squeezearea,unur_arou_get_squeezearea} 9727@item @ref{funct:unur_arou_set_max_segments,unur_arou_set_max_segments} 9728@item @ref{funct:unur_arou_set_cpoints,unur_arou_set_cpoints} 9729@item @ref{funct:unur_arou_set_usecenter,unur_arou_set_usecenter} 9730@item @ref{funct:unur_arou_set_guidefactor,unur_arou_set_guidefactor} 9731@item @ref{funct:unur_arou_set_verify,unur_arou_set_verify} 9732@item @ref{funct:unur_arou_chg_verify,unur_arou_chg_verify} 9733@item @ref{funct:unur_arou_set_pedantic,unur_arou_set_pedantic} 9734@end itemize 9735@end ifhtml 9736 9737 9738@ifinfo 9739@anchor{funct:unur_arou_new} 9740@deftypefn Function {UNUR_PAR*} unur_arou_new (const @var{UNUR_DISTR* distribution}) 9741Get default parameters for generator. 9742@end deftypefn 9743@end ifinfo 9744@ifnotinfo 9745@anchor{funct:unur_arou_new} 9746@deftypefn {} {UNUR_PAR*} unur_arou_new (const @var{UNUR_DISTR* distribution}) 9747Get default parameters for generator. 9748@end deftypefn 9749@end ifnotinfo 9750 9751@ifinfo 9752@anchor{funct:unur_arou_set_usedars} 9753@deftypefn Function {int} unur_arou_set_usedars (UNUR_PAR* @var{parameters}, int @var{usedars}) 9754If @var{usedars} is set to @code{TRUE}, ``derandomized adaptive rejection 9755sampling'' (DARS) is used in setup. 9756Segments where the area between hat and squeeze is too 9757large compared to the average area between hat and squeeze 9758over all intervals are split. 9759This procedure is repeated until the ratio between area below squeeze 9760and area below hat exceeds the bound given by 9761@ifhtml 9762@ref{funct:unur_arou_set_max_sqhratio,@command{unur_arou_set_max_sqhratio}} 9763@end ifhtml 9764@ifnothtml 9765@command{unur_arou_set_max_sqhratio} 9766@end ifnothtml 9767call or the maximum number of segments is 9768reached. Moreover, it also aborts when no more segments can be 9769found for splitting. 9770 9771Segments are split such that the angle of the segments are halved 9772(corresponds to arc-mean rule of method TDR (@pxref{TDR})). 9773 9774Default is @code{TRUE}. 9775@end deftypefn 9776@end ifinfo 9777@ifnotinfo 9778@anchor{funct:unur_arou_set_usedars} 9779@deftypefn {} {int} unur_arou_set_usedars (UNUR_PAR* @var{parameters}, int @var{usedars}) 9780If @var{usedars} is set to @code{TRUE}, ``derandomized adaptive rejection 9781sampling'' (DARS) is used in setup. 9782Segments where the area between hat and squeeze is too 9783large compared to the average area between hat and squeeze 9784over all intervals are split. 9785This procedure is repeated until the ratio between area below squeeze 9786and area below hat exceeds the bound given by 9787@ifhtml 9788@ref{funct:unur_arou_set_max_sqhratio,@command{unur_arou_set_max_sqhratio}} 9789@end ifhtml 9790@ifnothtml 9791@command{unur_arou_set_max_sqhratio} 9792@end ifnothtml 9793call or the maximum number of segments is 9794reached. Moreover, it also aborts when no more segments can be 9795found for splitting. 9796 9797Segments are split such that the angle of the segments are halved 9798(corresponds to arc-mean rule of method TDR (@pxref{TDR})). 9799 9800Default is @code{TRUE}. 9801@end deftypefn 9802@end ifnotinfo 9803 9804@ifinfo 9805@anchor{funct:unur_arou_set_darsfactor} 9806@deftypefn Function {int} unur_arou_set_darsfactor (UNUR_PAR* @var{parameters}, double @var{factor}) 9807Set factor for ``derandomized adaptive rejection sampling''. 9808This factor is used to determine the segments that are ``too 9809large'', that is, all segments where the area between squeeze and 9810hat is larger than @var{factor} times the average area over all 9811intervals between squeeze and hat. 9812Notice that all segments are split when @var{factor} is set to 9813@code{0.}, and that there is no splitting at all when @var{factor} 9814is set to @code{UNUR_INFINITY}. 9815 9816Default is @code{0.99}. There is no need to change this parameter. 9817@end deftypefn 9818@end ifinfo 9819@ifnotinfo 9820@anchor{funct:unur_arou_set_darsfactor} 9821@deftypefn {} {int} unur_arou_set_darsfactor (UNUR_PAR* @var{parameters}, double @var{factor}) 9822Set factor for ``derandomized adaptive rejection sampling''. 9823This factor is used to determine the segments that are ``too 9824large'', that is, all segments where the area between squeeze and 9825hat is larger than @var{factor} times the average area over all 9826intervals between squeeze and hat. 9827Notice that all segments are split when @var{factor} is set to 9828@code{0.}, and that there is no splitting at all when @var{factor} 9829is set to @code{UNUR_INFINITY}. 9830 9831Default is @code{0.99}. There is no need to change this parameter. 9832@end deftypefn 9833@end ifnotinfo 9834 9835@ifinfo 9836@anchor{funct:unur_arou_set_max_sqhratio} 9837@deftypefn Function {int} unur_arou_set_max_sqhratio (UNUR_PAR* @var{parameters}, double @var{max_ratio}) 9838Set upper bound for the 9839ratio (area inside squeeze) / (area inside envelope). 9840It must be a number between 0 and 1. 9841When the ratio exceeds the given number no further construction 9842points are inserted via adaptive rejection sampling. 9843Use @code{0} if no construction points should be added after the 9844setup. 9845Use @code{1} if adding new construction points should not be 9846stopped until the maximum number of construction points is reached. 9847 9848Default is @code{0.99}. 9849@end deftypefn 9850@end ifinfo 9851@ifnotinfo 9852@anchor{funct:unur_arou_set_max_sqhratio} 9853@deftypefn {} {int} unur_arou_set_max_sqhratio (UNUR_PAR* @var{parameters}, double @var{max_ratio}) 9854Set upper bound for the 9855ratio (area inside squeeze) / (area inside envelope). 9856It must be a number between 0 and 1. 9857When the ratio exceeds the given number no further construction 9858points are inserted via adaptive rejection sampling. 9859Use @code{0} if no construction points should be added after the 9860setup. 9861Use @code{1} if adding new construction points should not be 9862stopped until the maximum number of construction points is reached. 9863 9864Default is @code{0.99}. 9865@end deftypefn 9866@end ifnotinfo 9867 9868@ifinfo 9869@anchor{funct:unur_arou_get_sqhratio} 9870@deftypefn Function {double} unur_arou_get_sqhratio (const @var{UNUR_GEN* generator}) 9871Get the current ratio (area inside squeeze) / (area inside envelope) 9872for the generator. 9873(In case of an error @code{UNUR_INFINITY} is returned.) 9874@end deftypefn 9875@end ifinfo 9876@ifnotinfo 9877@anchor{funct:unur_arou_get_sqhratio} 9878@deftypefn {} {double} unur_arou_get_sqhratio (const @var{UNUR_GEN* generator}) 9879Get the current ratio (area inside squeeze) / (area inside envelope) 9880for the generator. 9881(In case of an error @code{UNUR_INFINITY} is returned.) 9882@end deftypefn 9883@end ifnotinfo 9884 9885@ifinfo 9886@anchor{funct:unur_arou_get_hatarea} 9887@deftypefn Function {double} unur_arou_get_hatarea (const @var{UNUR_GEN* generator}) 9888Get the area below the hat for the generator. 9889(In case of an error @code{UNUR_INFINITY} is returned.) 9890@end deftypefn 9891@end ifinfo 9892@ifnotinfo 9893@anchor{funct:unur_arou_get_hatarea} 9894@deftypefn {} {double} unur_arou_get_hatarea (const @var{UNUR_GEN* generator}) 9895Get the area below the hat for the generator. 9896(In case of an error @code{UNUR_INFINITY} is returned.) 9897@end deftypefn 9898@end ifnotinfo 9899 9900@ifinfo 9901@anchor{funct:unur_arou_get_squeezearea} 9902@deftypefn Function {double} unur_arou_get_squeezearea (const @var{UNUR_GEN* generator}) 9903Get the area below the squeeze for the generator. 9904(In case of an error @code{UNUR_INFINITY} is returned.) 9905@end deftypefn 9906@end ifinfo 9907@ifnotinfo 9908@anchor{funct:unur_arou_get_squeezearea} 9909@deftypefn {} {double} unur_arou_get_squeezearea (const @var{UNUR_GEN* generator}) 9910Get the area below the squeeze for the generator. 9911(In case of an error @code{UNUR_INFINITY} is returned.) 9912@end deftypefn 9913@end ifnotinfo 9914 9915@ifinfo 9916@anchor{funct:unur_arou_set_max_segments} 9917@deftypefn Function {int} unur_arou_set_max_segments (UNUR_PAR* @var{parameters}, int @var{max_segs}) 9918Set maximum number of segements. 9919No construction points are added @emph{after} the setup when the 9920number of segments succeeds @var{max_segs}. 9921 9922Default is @code{100}. 9923@end deftypefn 9924@end ifinfo 9925@ifnotinfo 9926@anchor{funct:unur_arou_set_max_segments} 9927@deftypefn {} {int} unur_arou_set_max_segments (UNUR_PAR* @var{parameters}, int @var{max_segs}) 9928Set maximum number of segements. 9929No construction points are added @emph{after} the setup when the 9930number of segments succeeds @var{max_segs}. 9931 9932Default is @code{100}. 9933@end deftypefn 9934@end ifnotinfo 9935 9936@ifinfo 9937@anchor{funct:unur_arou_set_cpoints} 9938@deftypefn Function {int} unur_arou_set_cpoints (UNUR_PAR* @var{parameters}, int @var{n_stp}, const @var{double* stp}) 9939Set construction points for enveloping polygon. 9940If @var{stp} is @code{NULL}, then a heuristical rule of thumb is used to 9941get @var{n_stp} construction points. 9942This is the default behavior when this routine is not called. 9943The (default) number of construction points is @code{30}, then. 9944@end deftypefn 9945@end ifinfo 9946@ifnotinfo 9947@anchor{funct:unur_arou_set_cpoints} 9948@deftypefn {} {int} unur_arou_set_cpoints (UNUR_PAR* @var{parameters}, int @var{n_stp}, const @var{double* stp}) 9949Set construction points for enveloping polygon. 9950If @var{stp} is @code{NULL}, then a heuristical rule of thumb is used to 9951get @var{n_stp} construction points. 9952This is the default behavior when this routine is not called. 9953The (default) number of construction points is @code{30}, then. 9954@end deftypefn 9955@end ifnotinfo 9956 9957@ifinfo 9958@anchor{funct:unur_arou_set_usecenter} 9959@deftypefn Function {int} unur_arou_set_usecenter (UNUR_PAR* @var{parameters}, int @var{usecenter}) 9960Use the center as construction point. 9961Default is @code{TRUE}. 9962@end deftypefn 9963@end ifinfo 9964@ifnotinfo 9965@anchor{funct:unur_arou_set_usecenter} 9966@deftypefn {} {int} unur_arou_set_usecenter (UNUR_PAR* @var{parameters}, int @var{usecenter}) 9967Use the center as construction point. 9968Default is @code{TRUE}. 9969@end deftypefn 9970@end ifnotinfo 9971 9972@ifinfo 9973@anchor{funct:unur_arou_set_guidefactor} 9974@deftypefn Function {int} unur_arou_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 9975Set factor for relative size of the guide table for indexed search 9976(see also method DGT @ref{DGT}). It must be greater than or equal 9977to @code{0}. 9978When set to @code{0}, then sequential search is used. 9979 9980Default is @code{2}. 9981@end deftypefn 9982@end ifinfo 9983@ifnotinfo 9984@anchor{funct:unur_arou_set_guidefactor} 9985@deftypefn {} {int} unur_arou_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 9986Set factor for relative size of the guide table for indexed search 9987(see also method DGT @ref{DGT}). It must be greater than or equal 9988to @code{0}. 9989When set to @code{0}, then sequential search is used. 9990 9991Default is @code{2}. 9992@end deftypefn 9993@end ifnotinfo 9994 9995@ifinfo 9996@anchor{funct:unur_arou_set_verify} 9997@deftypefn Function {int} unur_arou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 9998@anchor{funct:unur_arou_chg_verify} 9999@deftypefnx Function {int} unur_arou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 10000Turn verifying of algorithm while sampling on/off. 10001If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 10002violated for some @i{x} then @code{unur_errno} is set to 10003@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 10004happen due to round-off errors for a few values of 10005@i{x} (less than 1%). 10006 10007Default is @code{FALSE}. 10008@end deftypefn 10009@end ifinfo 10010@ifnotinfo 10011@anchor{funct:unur_arou_set_verify} 10012@deftypefn {} {int} unur_arou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 10013@anchor{funct:unur_arou_chg_verify} 10014@deftypefnx {} {int} unur_arou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 10015Turn verifying of algorithm while sampling on/off. 10016If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 10017violated for some @i{x} then @code{unur_errno} is set to 10018@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 10019happen due to round-off errors for a few values of 10020@i{x} (less than 1%). 10021 10022Default is @code{FALSE}. 10023@end deftypefn 10024@end ifnotinfo 10025 10026@ifinfo 10027@anchor{funct:unur_arou_set_pedantic} 10028@deftypefn Function {int} unur_arou_set_pedantic (UNUR_PAR* @var{parameters}, int @var{pedantic}) 10029Sometimes it might happen that 10030@ifhtml 10031@ref{funct:unur_init,@command{unur_init}} 10032@end ifhtml 10033@ifnothtml 10034@command{unur_init} 10035@end ifnothtml 10036has been executed 10037successfully. But when additional construction points are added by 10038adaptive rejection sampling, the algorithm detects that the 10039PDF is not T-concave. 10040 10041With @var{pedantic} being @code{TRUE}, the 10042sampling routine is then exchanged by a routine that simply returns 10043@code{UNUR_INFINITY}. Otherwise the new point is not added to the 10044list of construction points. At least the hat function remains 10045T-concave. 10046 10047Setting @var{pedantic} to @code{FALSE} allows sampling from a 10048distribution which is ``almost'' T-concave and small errors are 10049tolerated. However it might happen that the hat function cannot be 10050improved significantly. When the hat function that has been 10051constructed by the 10052@ifhtml 10053@ref{funct:unur_init,@command{unur_init}} 10054@end ifhtml 10055@ifnothtml 10056@command{unur_init} 10057@end ifnothtml 10058call is extremely large then it 10059might happen that the generation times are extremely high 10060(even hours are possible in extremely rare cases). 10061 10062Default is @code{FALSE}. 10063@end deftypefn 10064@end ifinfo 10065@ifnotinfo 10066@anchor{funct:unur_arou_set_pedantic} 10067@deftypefn {} {int} unur_arou_set_pedantic (UNUR_PAR* @var{parameters}, int @var{pedantic}) 10068Sometimes it might happen that 10069@ifhtml 10070@ref{funct:unur_init,@command{unur_init}} 10071@end ifhtml 10072@ifnothtml 10073@command{unur_init} 10074@end ifnothtml 10075has been executed 10076successfully. But when additional construction points are added by 10077adaptive rejection sampling, the algorithm detects that the 10078PDF is not T-concave. 10079 10080With @var{pedantic} being @code{TRUE}, the 10081sampling routine is then exchanged by a routine that simply returns 10082@code{UNUR_INFINITY}. Otherwise the new point is not added to the 10083list of construction points. At least the hat function remains 10084T-concave. 10085 10086Setting @var{pedantic} to @code{FALSE} allows sampling from a 10087distribution which is ``almost'' T-concave and small errors are 10088tolerated. However it might happen that the hat function cannot be 10089improved significantly. When the hat function that has been 10090constructed by the 10091@ifhtml 10092@ref{funct:unur_init,@command{unur_init}} 10093@end ifhtml 10094@ifnothtml 10095@command{unur_init} 10096@end ifnothtml 10097call is extremely large then it 10098might happen that the generation times are extremely high 10099(even hours are possible in extremely rare cases). 10100 10101Default is @code{FALSE}. 10102@end deftypefn 10103@end ifnotinfo 10104 10105 10106 10107 10108@c 10109@c end of arou.h 10110@c ------------------------------------- 10111@c ------------------------------------- 10112@c ars.h 10113@c 10114 10115@page 10116@node ARS 10117@subsection ARS -- Adaptive Rejection Sampling 10118 10119@table @i 10120@item Required: 10121concave logPDF, derivative of logPDF 10122@item Optional: 10123mode 10124@item Speed: 10125Set-up: fast, Sampling: slow 10126@item Reinit: 10127supported 10128@item Reference: 10129@ifhtml 10130@ref{bib:GWa92,, [GWa92]} 10131@end ifhtml 10132@ifnothtml 10133[GWa92] 10134@end ifnothtml 10135@ifhtml 10136@ref{bib:HLD04,, [HLD04: Cha.4]} 10137@end ifhtml 10138@ifnothtml 10139[HLD04: Cha.4] 10140@end ifnothtml 10141 10142@end table 10143@sp 1 10144 10145 10146ARS is an acceptance/rejection method that uses the concavity 10147of the log-density function to construct hat function and 10148squeezes automatically. 10149It is very similar to method TDR (@pxref{TDR}) with variant GW, 10150parameter @code{c = 0}, and DARS switched off. 10151Moreover, method ARS requires the logPDF and its derivative 10152dlogPDF to run. On the other hand, it is designed to draw only a 10153(very) small samples and it is much more robust against 10154densities with very large or small areas below the PDF as 10155it occurs, for example, in conditional distributions of 10156(high dimensional) multivariate distributions. 10157Additionally, it can be re-initialized when the underlying 10158distribution has been modified. 10159Thus it is well suited for Gibbs sampling. 10160 10161Notice, that method ARS is a restricted version of TDR. If the 10162full functionally of Transformed Density Rejection is needed use 10163method @ref{TDR}. 10164 10165 10166@subsubheading How To Use 10167 10168 10169Method ARS is designed for distributions with log-concave 10170densities. To use this method you need a distribution object 10171with the logarithm of the PDF and its derivative given. 10172 10173The number of construction points as well as a set of such 10174points can be provided using 10175@ifhtml 10176@ref{funct:unur_ars_set_cpoints,@command{unur_ars_set_cpoints}.} 10177@end ifhtml 10178@ifnothtml 10179@command{unur_ars_set_cpoints}. 10180@end ifnothtml 10181Notice that addition construction points are added by means of 10182adaptive rejection sampling until the maximal number of 10183intervals given by 10184@ifhtml 10185@ref{funct:unur_ars_set_max_intervals,@command{unur_ars_set_max_intervals}} 10186@end ifhtml 10187@ifnothtml 10188@command{unur_ars_set_max_intervals} 10189@end ifnothtml 10190is reached. 10191 10192A generated distribution object can be reinitialized using the 10193@ifhtml 10194@ref{funct:unur_reinit,@command{unur_reinit}} 10195@end ifhtml 10196@ifnothtml 10197@command{unur_reinit} 10198@end ifnothtml 10199call. When 10200@ifhtml 10201@ref{funct:unur_reinit,@command{unur_reinit}} 10202@end ifhtml 10203@ifnothtml 10204@command{unur_reinit} 10205@end ifnothtml 10206is called construction 10207points for the new generator are necessary. There are two options: 10208Either the same construction points as for the initial generator 10209(given by a 10210@ifhtml 10211@ref{funct:unur_ars_set_cpoints,@command{unur_ars_set_cpoints}} 10212@end ifhtml 10213@ifnothtml 10214@command{unur_ars_set_cpoints} 10215@end ifnothtml 10216call) are used (this is the 10217default), or percentiles of the old hat function can be used. 10218This can be set or changed using 10219@ifhtml 10220@ref{funct:unur_ars_set_reinit_percentiles,@command{unur_ars_set_reinit_percentiles}} 10221@end ifhtml 10222@ifnothtml 10223@command{unur_ars_set_reinit_percentiles} 10224@end ifnothtml 10225and 10226@ifhtml 10227@ref{funct:unur_ars_chg_reinit_percentiles,@command{unur_ars_chg_reinit_percentiles}.} 10228@end ifhtml 10229@ifnothtml 10230@command{unur_ars_chg_reinit_percentiles}. 10231@end ifnothtml 10232This feature is usefull when the underlying distribution object 10233is only moderately changed. (An example is Gibbs sampling with 10234small correlations.) 10235 10236There exists a test mode that verifies whether the conditions for 10237the method are satisfied or not. It can be switched on by calling 10238@ifhtml 10239@ref{funct:unur_ars_set_verify,@command{unur_ars_set_verify}} 10240@end ifhtml 10241@ifnothtml 10242@command{unur_ars_set_verify} 10243@end ifnothtml 10244and 10245@ifhtml 10246@ref{funct:unur_ars_chg_verify,@command{unur_ars_chg_verify},} 10247@end ifhtml 10248@ifnothtml 10249@command{unur_ars_chg_verify}, 10250@end ifnothtml 10251respectively. 10252Notice however that sampling is (much) slower then. 10253 10254Method ARS aborts after a given number of iterations and return 10255UNUR_INFINITY to prevent (almost) infinite loops. This might 10256happen when the starting hat is much too large and it is not 10257possible to insert new construction points due to severe 10258numerical errors or (more likely) the given PDF is not 10259log-concave. This maximum number of iterations can be set by 10260means of a 10261@ifhtml 10262@ref{funct:unur_ars_set_max_iter,@command{unur_ars_set_max_iter}} 10263@end ifhtml 10264@ifnothtml 10265@command{unur_ars_set_max_iter} 10266@end ifnothtml 10267call. 10268 10269 10270 10271 10272@subheading Function reference 10273 10274@ifhtml 10275@itemize 10276@item @ref{funct:unur_ars_new,unur_ars_new} 10277@item @ref{funct:unur_ars_set_max_intervals,unur_ars_set_max_intervals} 10278@item @ref{funct:unur_ars_set_cpoints,unur_ars_set_cpoints} 10279@item @ref{funct:unur_ars_set_reinit_percentiles,unur_ars_set_reinit_percentiles} 10280@item @ref{funct:unur_ars_chg_reinit_percentiles,unur_ars_chg_reinit_percentiles} 10281@item @ref{funct:unur_ars_set_reinit_ncpoints,unur_ars_set_reinit_ncpoints} 10282@item @ref{funct:unur_ars_chg_reinit_ncpoints,unur_ars_chg_reinit_ncpoints} 10283@item @ref{funct:unur_ars_set_max_iter,unur_ars_set_max_iter} 10284@item @ref{funct:unur_ars_set_verify,unur_ars_set_verify} 10285@item @ref{funct:unur_ars_chg_verify,unur_ars_chg_verify} 10286@item @ref{funct:unur_ars_set_pedantic,unur_ars_set_pedantic} 10287@item @ref{funct:unur_ars_get_loghatarea,unur_ars_get_loghatarea} 10288@item @ref{funct:unur_ars_eval_invcdfhat,unur_ars_eval_invcdfhat} 10289@end itemize 10290@end ifhtml 10291 10292 10293@ifinfo 10294@anchor{funct:unur_ars_new} 10295@deftypefn Function {UNUR_PAR*} unur_ars_new (const @var{UNUR_DISTR* distribution}) 10296Get default parameters for generator. 10297@end deftypefn 10298@end ifinfo 10299@ifnotinfo 10300@anchor{funct:unur_ars_new} 10301@deftypefn {} {UNUR_PAR*} unur_ars_new (const @var{UNUR_DISTR* distribution}) 10302Get default parameters for generator. 10303@end deftypefn 10304@end ifnotinfo 10305 10306@ifinfo 10307@anchor{funct:unur_ars_set_max_intervals} 10308@deftypefn Function {int} unur_ars_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 10309Set maximum number of intervals. 10310No construction points are added after the setup when the number of 10311intervals suceeds @var{max_ivs}. 10312It is increased automatically to twice the number of construction 10313points if this is larger. 10314 10315Default is @code{200}. 10316@end deftypefn 10317@end ifinfo 10318@ifnotinfo 10319@anchor{funct:unur_ars_set_max_intervals} 10320@deftypefn {} {int} unur_ars_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 10321Set maximum number of intervals. 10322No construction points are added after the setup when the number of 10323intervals suceeds @var{max_ivs}. 10324It is increased automatically to twice the number of construction 10325points if this is larger. 10326 10327Default is @code{200}. 10328@end deftypefn 10329@end ifnotinfo 10330 10331@ifinfo 10332@anchor{funct:unur_ars_set_cpoints} 10333@deftypefn Function {int} unur_ars_set_cpoints (UNUR_PAR* @var{parameters}, int @var{n_cpoints}, const @var{double* cpoints}) 10334Set construction points for the hat function. If @var{cpoints} is 10335@code{NULL} then a heuristic rule of thumb is used to get @var{n_cpoints} 10336construction points. This is the default behavior. 10337@var{n_cpoints} should be at least @code{2}, otherwise defaults are used. 10338 10339The default number of construction points is 2. 10340@end deftypefn 10341@end ifinfo 10342@ifnotinfo 10343@anchor{funct:unur_ars_set_cpoints} 10344@deftypefn {} {int} unur_ars_set_cpoints (UNUR_PAR* @var{parameters}, int @var{n_cpoints}, const @var{double* cpoints}) 10345Set construction points for the hat function. If @var{cpoints} is 10346@code{NULL} then a heuristic rule of thumb is used to get @var{n_cpoints} 10347construction points. This is the default behavior. 10348@var{n_cpoints} should be at least @code{2}, otherwise defaults are used. 10349 10350The default number of construction points is 2. 10351@end deftypefn 10352@end ifnotinfo 10353 10354@ifinfo 10355@anchor{funct:unur_ars_set_reinit_percentiles} 10356@deftypefn Function {int} unur_ars_set_reinit_percentiles (UNUR_PAR* @var{parameters}, int @var{n_percentiles}, const @var{double* percentiles}) 10357@anchor{funct:unur_ars_chg_reinit_percentiles} 10358@deftypefnx Function {int} unur_ars_chg_reinit_percentiles (UNUR_GEN* @var{generator}, int @var{n_percentiles}, const @var{double* percentiles}) 10359By default, when the @var{generator} object is reinitialized, it 10360used the same construction points as for the initialization 10361procedure. 10362Often the underlying distribution object has been changed only 10363moderately. For example, the full conditional distribution of a 10364multivariate distribution. 10365In this case it might be more appropriate to use 10366percentilesm of the hat function for the last (unchanged) 10367distribution. @var{percentiles} must then be a pointer to an 10368ordered array of numbers between @code{0.01} and @code{0.99}. 10369If @var{percentiles} is @code{NULL}, then a heuristic rule of thumb is 10370used to get @var{n_percentiles} values for these percentiles. 10371Notice that @var{n_percentiles} must be at least @code{2}, 10372otherwise defaults are used. 10373(Then the first and third quartiles are used by default.) 10374@end deftypefn 10375@end ifinfo 10376@ifnotinfo 10377@anchor{funct:unur_ars_set_reinit_percentiles} 10378@deftypefn {} {int} unur_ars_set_reinit_percentiles (UNUR_PAR* @var{parameters}, int @var{n_percentiles}, const @var{double* percentiles}) 10379@anchor{funct:unur_ars_chg_reinit_percentiles} 10380@deftypefnx {} {int} unur_ars_chg_reinit_percentiles (UNUR_GEN* @var{generator}, int @var{n_percentiles}, const @var{double* percentiles}) 10381By default, when the @var{generator} object is reinitialized, it 10382used the same construction points as for the initialization 10383procedure. 10384Often the underlying distribution object has been changed only 10385moderately. For example, the full conditional distribution of a 10386multivariate distribution. 10387In this case it might be more appropriate to use 10388percentilesm of the hat function for the last (unchanged) 10389distribution. @var{percentiles} must then be a pointer to an 10390ordered array of numbers between @code{0.01} and @code{0.99}. 10391If @var{percentiles} is @code{NULL}, then a heuristic rule of thumb is 10392used to get @var{n_percentiles} values for these percentiles. 10393Notice that @var{n_percentiles} must be at least @code{2}, 10394otherwise defaults are used. 10395(Then the first and third quartiles are used by default.) 10396@end deftypefn 10397@end ifnotinfo 10398 10399@ifinfo 10400@anchor{funct:unur_ars_set_reinit_ncpoints} 10401@deftypefn Function {int} unur_ars_set_reinit_ncpoints (UNUR_PAR* @var{parameters}, int @var{ncpoints}) 10402@anchor{funct:unur_ars_chg_reinit_ncpoints} 10403@deftypefnx Function {int} unur_ars_chg_reinit_ncpoints (UNUR_GEN* @var{generator}, int @var{ncpoints}) 10404When reinit fails with the given construction points or the percentiles 10405of the old hat function, another trial is undertaken with @var{ncpoints} 10406construction points. @var{ncpoints} must be at least @code{10}. 10407 10408Default: @code{30} 10409@end deftypefn 10410@end ifinfo 10411@ifnotinfo 10412@anchor{funct:unur_ars_set_reinit_ncpoints} 10413@deftypefn {} {int} unur_ars_set_reinit_ncpoints (UNUR_PAR* @var{parameters}, int @var{ncpoints}) 10414@anchor{funct:unur_ars_chg_reinit_ncpoints} 10415@deftypefnx {} {int} unur_ars_chg_reinit_ncpoints (UNUR_GEN* @var{generator}, int @var{ncpoints}) 10416When reinit fails with the given construction points or the percentiles 10417of the old hat function, another trial is undertaken with @var{ncpoints} 10418construction points. @var{ncpoints} must be at least @code{10}. 10419 10420Default: @code{30} 10421@end deftypefn 10422@end ifnotinfo 10423 10424@ifinfo 10425@anchor{funct:unur_ars_set_max_iter} 10426@deftypefn Function {int} unur_ars_set_max_iter (UNUR_PAR* @var{parameters}, int @var{max_iter}) 10427The rejection loop stops after @var{max_iter} iterations and return 10428UNUR_INFINITY. 10429 10430Default: @code{10000} 10431@end deftypefn 10432@end ifinfo 10433@ifnotinfo 10434@anchor{funct:unur_ars_set_max_iter} 10435@deftypefn {} {int} unur_ars_set_max_iter (UNUR_PAR* @var{parameters}, int @var{max_iter}) 10436The rejection loop stops after @var{max_iter} iterations and return 10437UNUR_INFINITY. 10438 10439Default: @code{10000} 10440@end deftypefn 10441@end ifnotinfo 10442 10443@ifinfo 10444@anchor{funct:unur_ars_set_verify} 10445@deftypefn Function {int} unur_ars_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 10446@anchor{funct:unur_ars_chg_verify} 10447@deftypefnx Function {int} unur_ars_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 10448Turn verifying of algorithm while sampling on/off. 10449If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 10450violated for some @i{x} then @code{unur_errno} is set to 10451@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 10452happen due to round-off errors for a few values of 10453@i{x} (less than 1%). 10454 10455Default is @code{FALSE}. 10456@end deftypefn 10457@end ifinfo 10458@ifnotinfo 10459@anchor{funct:unur_ars_set_verify} 10460@deftypefn {} {int} unur_ars_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 10461@anchor{funct:unur_ars_chg_verify} 10462@deftypefnx {} {int} unur_ars_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 10463Turn verifying of algorithm while sampling on/off. 10464If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 10465violated for some @i{x} then @code{unur_errno} is set to 10466@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 10467happen due to round-off errors for a few values of 10468@i{x} (less than 1%). 10469 10470Default is @code{FALSE}. 10471@end deftypefn 10472@end ifnotinfo 10473 10474@ifinfo 10475@anchor{funct:unur_ars_set_pedantic} 10476@deftypefn Function {int} unur_ars_set_pedantic (UNUR_PAR* @var{parameters}, int @var{pedantic}) 10477Sometimes it might happen that 10478@ifhtml 10479@ref{funct:unur_init,@command{unur_init}} 10480@end ifhtml 10481@ifnothtml 10482@command{unur_init} 10483@end ifnothtml 10484has been executed 10485successfully. But when additional construction points are added by 10486adaptive rejection sampling, the algorithm detects that the 10487PDF is not log-concave. 10488 10489With @var{pedantic} being @code{TRUE}, the 10490sampling routine is exchanged by a routine that simply returns 10491@code{UNUR_INFINITY}. Otherwise the new point is not added to the 10492list of construction points. At least the hat function remains 10493log-concave. 10494 10495Setting @var{pedantic} to @code{FALSE} allows sampling from a 10496distribution which is ``almost'' log-concave and small errors are 10497tolerated. However it might happen that the hat function cannot be 10498improved significantly. When the hat functions that has been 10499constructed by the 10500@ifhtml 10501@ref{funct:unur_init,@command{unur_init}} 10502@end ifhtml 10503@ifnothtml 10504@command{unur_init} 10505@end ifnothtml 10506call is extremely large then it 10507might happen that the generation times are extremely high 10508(even hours are possible in extremely rare cases). 10509 10510Default is @code{FALSE}. 10511@end deftypefn 10512@end ifinfo 10513@ifnotinfo 10514@anchor{funct:unur_ars_set_pedantic} 10515@deftypefn {} {int} unur_ars_set_pedantic (UNUR_PAR* @var{parameters}, int @var{pedantic}) 10516Sometimes it might happen that 10517@ifhtml 10518@ref{funct:unur_init,@command{unur_init}} 10519@end ifhtml 10520@ifnothtml 10521@command{unur_init} 10522@end ifnothtml 10523has been executed 10524successfully. But when additional construction points are added by 10525adaptive rejection sampling, the algorithm detects that the 10526PDF is not log-concave. 10527 10528With @var{pedantic} being @code{TRUE}, the 10529sampling routine is exchanged by a routine that simply returns 10530@code{UNUR_INFINITY}. Otherwise the new point is not added to the 10531list of construction points. At least the hat function remains 10532log-concave. 10533 10534Setting @var{pedantic} to @code{FALSE} allows sampling from a 10535distribution which is ``almost'' log-concave and small errors are 10536tolerated. However it might happen that the hat function cannot be 10537improved significantly. When the hat functions that has been 10538constructed by the 10539@ifhtml 10540@ref{funct:unur_init,@command{unur_init}} 10541@end ifhtml 10542@ifnothtml 10543@command{unur_init} 10544@end ifnothtml 10545call is extremely large then it 10546might happen that the generation times are extremely high 10547(even hours are possible in extremely rare cases). 10548 10549Default is @code{FALSE}. 10550@end deftypefn 10551@end ifnotinfo 10552 10553@ifinfo 10554@anchor{funct:unur_ars_get_loghatarea} 10555@deftypefn Function {double} unur_ars_get_loghatarea (const @var{UNUR_GEN* generator}) 10556Get the logarithm of area below the hat for the generator. 10557(In case of an error @code{UNUR_INFINITY} is returned.) 10558@end deftypefn 10559@end ifinfo 10560@ifnotinfo 10561@anchor{funct:unur_ars_get_loghatarea} 10562@deftypefn {} {double} unur_ars_get_loghatarea (const @var{UNUR_GEN* generator}) 10563Get the logarithm of area below the hat for the generator. 10564(In case of an error @code{UNUR_INFINITY} is returned.) 10565@end deftypefn 10566@end ifnotinfo 10567 10568@ifinfo 10569@anchor{funct:unur_ars_eval_invcdfhat} 10570@deftypefn Function {double} unur_ars_eval_invcdfhat (const @var{UNUR_GEN* generator}, double @var{u}) 10571Evaluate the inverse of the CDF of the hat distribution at @var{u}. 10572 10573If @var{u} is out of the domain [0,1] then @code{unur_errno} is set 10574to @code{UNUR_ERR_DOMAIN} and the respective bound of 10575the domain of the distribution are returned (which is 10576@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 10577unbounded domains). 10578@end deftypefn 10579@end ifinfo 10580@ifnotinfo 10581@anchor{funct:unur_ars_eval_invcdfhat} 10582@deftypefn {} {double} unur_ars_eval_invcdfhat (const @var{UNUR_GEN* generator}, double @var{u}) 10583Evaluate the inverse of the CDF of the hat distribution at @var{u}. 10584 10585If @var{u} is out of the domain [0,1] then @code{unur_errno} is set 10586to @code{UNUR_ERR_DOMAIN} and the respective bound of 10587the domain of the distribution are returned (which is 10588@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 10589unbounded domains). 10590@end deftypefn 10591@end ifnotinfo 10592 10593 10594 10595 10596@c 10597@c end of ars.h 10598@c ------------------------------------- 10599@c ------------------------------------- 10600@c cext.h 10601@c 10602 10603@page 10604@node CEXT 10605@subsection CEXT -- wrapper for Continuous EXTernal generators 10606 10607@table @i 10608@item Required: 10609routine for sampling continuous random variates 10610@item Speed: 10611depends on external generator 10612@item Reinit: 10613supported 10614@end table 10615@sp 1 10616 10617 10618Method CEXT is a wrapper for external generators for continuous 10619univariate distributions. It allows the usage of external 10620random variate generators within the UNU.RAN framework. 10621 10622 10623@subsubheading How To Use 10624 10625 10626The following steps are required to use some external generator 10627within the UNU.RAN framework (some of these are optional): 10628 10629@enumerate 10630@item 10631Make an empty generator object using a 10632@ifhtml 10633@ref{funct:unur_cext_new,@command{unur_cext_new}} 10634@end ifhtml 10635@ifnothtml 10636@command{unur_cext_new} 10637@end ifnothtml 10638call. 10639The argument @var{distribution} is optional and can be replaced 10640by @code{NULL}. However, it is required if you want to pass 10641parameters of the generated distribution to the external 10642generator or for running some validation tests provided by 10643UNU.RAN. 10644 10645@item 10646Create an initialization routine of type 10647@code{int (*init)(UNUR_GEN *gen)} and plug it into the generator 10648object using the 10649@ifhtml 10650@ref{funct:unur_cext_set_init,@command{unur_cext_set_init}} 10651@end ifhtml 10652@ifnothtml 10653@command{unur_cext_set_init} 10654@end ifnothtml 10655call. Notice that the 10656@var{init} routine must return @code{UNUR_SUCCESS} when it has 10657been executed successfully and @code{UNUR_FAILURE} otherwise. 10658It is possible to get the size of and the pointer to the array 10659of parameters of the underlying distribution object by the 10660respective calls 10661@ifhtml 10662@ref{funct:unur_cext_get_ndistrparams,@command{unur_cext_get_ndistrparams}} 10663@end ifhtml 10664@ifnothtml 10665@command{unur_cext_get_ndistrparams} 10666@end ifnothtml 10667and 10668@ifhtml 10669@ref{funct:unur_cext_get_distrparams,@command{unur_cext_get_distrparams}.} 10670@end ifhtml 10671@ifnothtml 10672@command{unur_cext_get_distrparams}. 10673@end ifnothtml 10674Parameters for the external generator that are computed in the 10675@var{init} routine can be stored in a single array or structure 10676which is available by the 10677@ifhtml 10678@ref{funct:unur_cext_get_params,@command{unur_cext_get_params}} 10679@end ifhtml 10680@ifnothtml 10681@command{unur_cext_get_params} 10682@end ifnothtml 10683call. 10684 10685Using an @var{init} routine is optional and can be omitted. 10686 10687@item 10688Create a sampling routine of type 10689@code{double (*sample)(UNUR_GEN *gen)} and plug it into the 10690generator object using the 10691@ifhtml 10692@ref{funct:unur_cext_set_sample,@command{unur_cext_set_sample}} 10693@end ifhtml 10694@ifnothtml 10695@command{unur_cext_set_sample} 10696@end ifnothtml 10697call. 10698 10699Uniform random numbers are provided by the 10700@ifhtml 10701@ref{funct:unur_sample_urng,@command{unur_sample_urng}} 10702@end ifhtml 10703@ifnothtml 10704@command{unur_sample_urng} 10705@end ifnothtml 10706call. Do not use your own implementation of a uniform random 10707number generator directly. If you want to use your own random 10708number generator we recommend to use the UNU.RAN interface (see 10709@pxref{URNG,,Using uniform random number generators}). 10710 10711The array or structure that contains parameters for the external 10712generator that are computed in the @var{init} routine are 10713available using the 10714@ifhtml 10715@ref{funct:unur_cext_get_params,@command{unur_cext_get_params}} 10716@end ifhtml 10717@ifnothtml 10718@command{unur_cext_get_params} 10719@end ifnothtml 10720call. 10721 10722Using a @var{sample} routine is of course obligatory. 10723@end enumerate 10724 10725It is possible to change the parameters and the domain of the 10726chosen distribution and run 10727@ifhtml 10728@ref{funct:unur_reinit,@command{unur_reinit}} 10729@end ifhtml 10730@ifnothtml 10731@command{unur_reinit} 10732@end ifnothtml 10733to reinitialize the 10734generator object. The @var{init} routine is then called again. 10735 10736Here is a short example that demonstrates the application of 10737this method by means of the exponential distribution: 10738 10739@smallexample 10740@include ref_example_cext.texi 10741@end smallexample 10742 10743 10744 10745 10746@subheading Function reference 10747 10748@ifhtml 10749@itemize 10750@item @ref{funct:unur_cext_new,unur_cext_new} 10751@item @ref{funct:unur_cext_set_init,unur_cext_set_init} 10752@item @ref{funct:unur_cext_set_sample,unur_cext_set_sample} 10753@item @ref{funct:unur_cext_get_params,unur_cext_get_params} 10754@item @ref{funct:unur_cext_get_distrparams,unur_cext_get_distrparams} 10755@item @ref{funct:unur_cext_get_ndistrparams,unur_cext_get_ndistrparams} 10756@end itemize 10757@end ifhtml 10758 10759 10760@ifinfo 10761@anchor{funct:unur_cext_new} 10762@deftypefn Function {UNUR_PAR*} unur_cext_new (const @var{UNUR_DISTR* distribution}) 10763Get default parameters for new generator. 10764@end deftypefn 10765@end ifinfo 10766@ifnotinfo 10767@anchor{funct:unur_cext_new} 10768@deftypefn {} {UNUR_PAR*} unur_cext_new (const @var{UNUR_DISTR* distribution}) 10769Get default parameters for new generator. 10770@end deftypefn 10771@end ifnotinfo 10772 10773@ifinfo 10774@anchor{funct:unur_cext_set_init} 10775@deftypefn Function {int} unur_cext_set_init (UNUR_PAR* @var{parameters}, int (* @var{init})(UNUR_GEN* gen )) 10776Set initialization routine for external generator. Inside the 10777 10778@emph{Important:} The routine @var{init} must return 10779@code{UNUR_SUCCESS} when the generator was initialized successfully 10780and @code{UNUR_FAILURE} otherwise. 10781 10782Parameters that are computed in the @var{init} routine can be 10783stored in an array or structure that is avaiable by means of the 10784@ifhtml 10785@ref{funct:unur_cext_get_params,@command{unur_cext_get_params}} 10786@end ifhtml 10787@ifnothtml 10788@command{unur_cext_get_params} 10789@end ifnothtml 10790call. Parameters of the underlying 10791distribution object can be obtained by the 10792@ifhtml 10793@ref{funct:unur_cext_get_distrparams,@command{unur_cext_get_distrparams}} 10794@end ifhtml 10795@ifnothtml 10796@command{unur_cext_get_distrparams} 10797@end ifnothtml 10798call. 10799@end deftypefn 10800@end ifinfo 10801@ifnotinfo 10802@anchor{funct:unur_cext_set_init} 10803@deftypefn {} {int} unur_cext_set_init (UNUR_PAR* @var{parameters}, int (* @var{init})(UNUR_GEN* gen )) 10804Set initialization routine for external generator. Inside the 10805 10806@emph{Important:} The routine @var{init} must return 10807@code{UNUR_SUCCESS} when the generator was initialized successfully 10808and @code{UNUR_FAILURE} otherwise. 10809 10810Parameters that are computed in the @var{init} routine can be 10811stored in an array or structure that is avaiable by means of the 10812@ifhtml 10813@ref{funct:unur_cext_get_params,@command{unur_cext_get_params}} 10814@end ifhtml 10815@ifnothtml 10816@command{unur_cext_get_params} 10817@end ifnothtml 10818call. Parameters of the underlying 10819distribution object can be obtained by the 10820@ifhtml 10821@ref{funct:unur_cext_get_distrparams,@command{unur_cext_get_distrparams}} 10822@end ifhtml 10823@ifnothtml 10824@command{unur_cext_get_distrparams} 10825@end ifnothtml 10826call. 10827@end deftypefn 10828@end ifnotinfo 10829 10830@ifinfo 10831@anchor{funct:unur_cext_set_sample} 10832@deftypefn Function {int} unur_cext_set_sample (UNUR_PAR* @var{parameters}, double (* @var{sample})(UNUR_GEN* gen )) 10833Set sampling routine for external generator. 10834 10835@emph{Important:} 10836Use @code{unur_sample_urng(gen)} to get a uniform random number. 10837The pointer to the array or structure that contains the parameters 10838that are precomputed in the @var{init} routine are available by 10839@code{unur_cext_get_params(gen,0)}. 10840Additionally one can use the 10841@ifhtml 10842@ref{funct:unur_cext_get_distrparams,@command{unur_cext_get_distrparams}} 10843@end ifhtml 10844@ifnothtml 10845@command{unur_cext_get_distrparams} 10846@end ifnothtml 10847call. 10848@end deftypefn 10849@end ifinfo 10850@ifnotinfo 10851@anchor{funct:unur_cext_set_sample} 10852@deftypefn {} {int} unur_cext_set_sample (UNUR_PAR* @var{parameters}, double (* @var{sample})(UNUR_GEN* gen )) 10853Set sampling routine for external generator. 10854 10855@emph{Important:} 10856Use @code{unur_sample_urng(gen)} to get a uniform random number. 10857The pointer to the array or structure that contains the parameters 10858that are precomputed in the @var{init} routine are available by 10859@code{unur_cext_get_params(gen,0)}. 10860Additionally one can use the 10861@ifhtml 10862@ref{funct:unur_cext_get_distrparams,@command{unur_cext_get_distrparams}} 10863@end ifhtml 10864@ifnothtml 10865@command{unur_cext_get_distrparams} 10866@end ifnothtml 10867call. 10868@end deftypefn 10869@end ifnotinfo 10870 10871@ifinfo 10872@anchor{funct:unur_cext_get_params} 10873@deftypefn Function {void*} unur_cext_get_params (UNUR_GEN* @var{generator}, size_t @var{size}) 10874Get pointer to memory block for storing parameters of external 10875generator. A memory block of size @var{size} is automatically (re-) 10876allocated if necessary and the pointer to this block is stored in 10877the @var{generator} object. If one only needs the pointer to this 10878memory block set @var{size} to @code{0}. 10879 10880Notice, that @var{size} is the size of the memory block and not the 10881length of an array. 10882 10883@emph{Important:} This rountine should only be used in the 10884initialization and sampling routine of the external generator. 10885@end deftypefn 10886@end ifinfo 10887@ifnotinfo 10888@anchor{funct:unur_cext_get_params} 10889@deftypefn {} {void*} unur_cext_get_params (UNUR_GEN* @var{generator}, size_t @var{size}) 10890Get pointer to memory block for storing parameters of external 10891generator. A memory block of size @var{size} is automatically (re-) 10892allocated if necessary and the pointer to this block is stored in 10893the @var{generator} object. If one only needs the pointer to this 10894memory block set @var{size} to @code{0}. 10895 10896Notice, that @var{size} is the size of the memory block and not the 10897length of an array. 10898 10899@emph{Important:} This rountine should only be used in the 10900initialization and sampling routine of the external generator. 10901@end deftypefn 10902@end ifnotinfo 10903 10904@ifinfo 10905@anchor{funct:unur_cext_get_distrparams} 10906@deftypefn Function {double*} unur_cext_get_distrparams (UNUR_GEN* @var{generator}) 10907@anchor{funct:unur_cext_get_ndistrparams} 10908@deftypefnx Function {int} unur_cext_get_ndistrparams (UNUR_GEN* @var{generator}) 10909Get size of and pointer to array of parameters of underlying 10910distribution in @var{generator} object. 10911 10912@emph{Important:} These rountines should only be used in the 10913initialization and sampling routine of the external generator. 10914@end deftypefn 10915@end ifinfo 10916@ifnotinfo 10917@anchor{funct:unur_cext_get_distrparams} 10918@deftypefn {} {double*} unur_cext_get_distrparams (UNUR_GEN* @var{generator}) 10919@anchor{funct:unur_cext_get_ndistrparams} 10920@deftypefnx {} {int} unur_cext_get_ndistrparams (UNUR_GEN* @var{generator}) 10921Get size of and pointer to array of parameters of underlying 10922distribution in @var{generator} object. 10923 10924@emph{Important:} These rountines should only be used in the 10925initialization and sampling routine of the external generator. 10926@end deftypefn 10927@end ifnotinfo 10928 10929 10930 10931 10932@c 10933@c end of cext.h 10934@c ------------------------------------- 10935@c ------------------------------------- 10936@c cstd.h 10937@c 10938 10939@page 10940@node CSTD 10941@subsection CSTD -- Continuous STandarD distributions 10942 10943@table @i 10944@item Required: 10945standard distribution from UNU.RAN library (@pxref{Stddist,,Standard distributions}) or continuous distribution with inverse CDF. 10946@item Speed: 10947Set-up: fast, Sampling: depends on distribution and generator 10948@item Reinit: 10949supported 10950@end table 10951@sp 1 10952 10953 10954CSTD is a wrapper for special generators for continuous 10955univariate standard distributions. It only works for 10956distributions in the UNU.RAN library of standard distributions 10957(@pxref{Stddist,,Standard distributions}) 10958or for continuous distributions where the inverse CDF is given. 10959If a distribution object is provided that is build from scratch, 10960it must provide the inverse CDF. Then CSTD implements the 10961inversion method. Otherwise, the @code{NULL} pointer is returned. 10962 10963For some distributions more than one special generator 10964is possible. 10965 10966 10967@subsubheading How To Use 10968 10969 10970Create a distribution object for a standard distribution 10971from the UNU.RAN library 10972(@pxref{Stddist,,Standard distributions}), 10973or create a continuous distribution object and set the function 10974for the inverse CDF using 10975@ifhtml 10976@ref{funct:unur_distr_cont_set_invcdf,@command{unur_distr_cont_set_invcdf}.} 10977@end ifhtml 10978@ifnothtml 10979@command{unur_distr_cont_set_invcdf}. 10980@end ifnothtml 10981For some distributions more than one special generator 10982(@emph{variants}) is possible. These can be choosen by a 10983@ifhtml 10984@ref{funct:unur_cstd_set_variant,@command{unur_cstd_set_variant}} 10985@end ifhtml 10986@ifnothtml 10987@command{unur_cstd_set_variant} 10988@end ifnothtml 10989call. For possible variants 10990@pxref{Stddist,,Standard distributions}. 10991However the following are common to all distributions: 10992 10993@table @code 10994@item UNUR_STDGEN_DEFAULT 10995the default generator. 10996@item UNUR_STDGEN_FAST 10997the fastest available special generator. 10998@item UNUR_STDGEN_INVERSION 10999the inversion method (if available). 11000@end table 11001 11002Notice that the variant @code{UNUR_STDGEN_FAST} for a special 11003generator may be slower than one of the universal algorithms! 11004Additional variants may exist for particular distributions. 11005 11006Sampling from truncated distributions (which can be constructed by 11007changing the default domain of a distribution by means of 11008@ifhtml 11009@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 11010@end ifhtml 11011@ifnothtml 11012@command{unur_distr_cont_set_domain} 11013@end ifnothtml 11014or 11015@ifhtml 11016@ref{funct:unur_cstd_chg_truncated,@command{unur_cstd_chg_truncated}} 11017@end ifhtml 11018@ifnothtml 11019@command{unur_cstd_chg_truncated} 11020@end ifnothtml 11021calls) 11022is possible but requires the inversion method. Moreover the CDF 11023of the distribution must be implemented. 11024 11025It is possible to change the parameters and the domain of the chosen 11026distribution and run 11027@ifhtml 11028@ref{funct:unur_reinit,@command{unur_reinit}} 11029@end ifhtml 11030@ifnothtml 11031@command{unur_reinit} 11032@end ifnothtml 11033to reinitialize the generator object. 11034 11035 11036 11037 11038@subheading Function reference 11039 11040@ifhtml 11041@itemize 11042@item @ref{funct:unur_cstd_new,unur_cstd_new} 11043@item @ref{funct:unur_cstd_set_variant,unur_cstd_set_variant} 11044@item @ref{funct:unur_cstd_chg_truncated,unur_cstd_chg_truncated} 11045@end itemize 11046@end ifhtml 11047 11048 11049@ifinfo 11050@anchor{funct:unur_cstd_new} 11051@deftypefn Function {UNUR_PAR*} unur_cstd_new (const @var{UNUR_DISTR* distribution}) 11052Get default parameters for new generator. It requires a distribution object 11053for a continuous univariant distribution from the 11054UNU.RAN library of standard distributions 11055(@pxref{Stddist,,Standard distributions}). 11056 11057Using a truncated distribution is allowed only if the inversion method 11058is available and selected by the 11059@ifhtml 11060@ref{funct:unur_cstd_set_variant,@command{unur_cstd_set_variant}} 11061@end ifhtml 11062@ifnothtml 11063@command{unur_cstd_set_variant} 11064@end ifnothtml 11065call immediately 11066after creating the parameter object. 11067Use a 11068@ifhtml 11069@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 11070@end ifhtml 11071@ifnothtml 11072@command{unur_distr_cont_set_domain} 11073@end ifnothtml 11074call to get a truncated distribution. 11075To change the domain of a (truncated) distribution of a generator use the 11076@ifhtml 11077@ref{funct:unur_cstd_chg_truncated,@command{unur_cstd_chg_truncated}} 11078@end ifhtml 11079@ifnothtml 11080@command{unur_cstd_chg_truncated} 11081@end ifnothtml 11082call. 11083@end deftypefn 11084@end ifinfo 11085@ifnotinfo 11086@anchor{funct:unur_cstd_new} 11087@deftypefn {} {UNUR_PAR*} unur_cstd_new (const @var{UNUR_DISTR* distribution}) 11088Get default parameters for new generator. It requires a distribution object 11089for a continuous univariant distribution from the 11090UNU.RAN library of standard distributions 11091(@pxref{Stddist,,Standard distributions}). 11092 11093Using a truncated distribution is allowed only if the inversion method 11094is available and selected by the 11095@ifhtml 11096@ref{funct:unur_cstd_set_variant,@command{unur_cstd_set_variant}} 11097@end ifhtml 11098@ifnothtml 11099@command{unur_cstd_set_variant} 11100@end ifnothtml 11101call immediately 11102after creating the parameter object. 11103Use a 11104@ifhtml 11105@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 11106@end ifhtml 11107@ifnothtml 11108@command{unur_distr_cont_set_domain} 11109@end ifnothtml 11110call to get a truncated distribution. 11111To change the domain of a (truncated) distribution of a generator use the 11112@ifhtml 11113@ref{funct:unur_cstd_chg_truncated,@command{unur_cstd_chg_truncated}} 11114@end ifhtml 11115@ifnothtml 11116@command{unur_cstd_chg_truncated} 11117@end ifnothtml 11118call. 11119@end deftypefn 11120@end ifnotinfo 11121 11122@ifinfo 11123@anchor{funct:unur_cstd_set_variant} 11124@deftypefn Function {int} unur_cstd_set_variant (UNUR_PAR* @var{parameters}, unsigned @var{variant}) 11125Set variant (special generator) for sampling from a given distribution. 11126For possible variants 11127@pxref{Stddist,,Standard distributions}. 11128 11129Common variants are @code{UNUR_STDGEN_DEFAULT} for the default generator, 11130@code{UNUR_STDGEN_FAST} for (one of the) fastest implemented 11131special generators, and @code{UNUR_STDGEN_INVERSION} for the 11132inversion method (if available). 11133If the selected variant number is not implemented, then an error code is 11134returned and the variant is not changed. 11135@end deftypefn 11136@end ifinfo 11137@ifnotinfo 11138@anchor{funct:unur_cstd_set_variant} 11139@deftypefn {} {int} unur_cstd_set_variant (UNUR_PAR* @var{parameters}, unsigned @var{variant}) 11140Set variant (special generator) for sampling from a given distribution. 11141For possible variants 11142@pxref{Stddist,,Standard distributions}. 11143 11144Common variants are @code{UNUR_STDGEN_DEFAULT} for the default generator, 11145@code{UNUR_STDGEN_FAST} for (one of the) fastest implemented 11146special generators, and @code{UNUR_STDGEN_INVERSION} for the 11147inversion method (if available). 11148If the selected variant number is not implemented, then an error code is 11149returned and the variant is not changed. 11150@end deftypefn 11151@end ifnotinfo 11152 11153@ifinfo 11154@anchor{funct:unur_cstd_chg_truncated} 11155@deftypefn Function {int} unur_cstd_chg_truncated (UNUR_GEN* @var{generator}, double @var{left}, double @var{right}) 11156Change left and right border of the domain of the (truncated) distribution. 11157This is only possible if the inversion method is used. 11158Otherwise this call has no effect and an error code is returned. 11159 11160Notice that the given truncated domain must be a subset of the 11161domain of the given distribution. The generator always uses the 11162intersection of the domain of the distribution and the truncated 11163domain given by this call. 11164 11165It is not required to run 11166@ifhtml 11167@ref{funct:unur_reinit,@command{unur_reinit}} 11168@end ifhtml 11169@ifnothtml 11170@command{unur_reinit} 11171@end ifnothtml 11172after this call has been used. 11173 11174@emph{Important:} If the CDF is (almost) the same for @var{left} and 11175@var{right} and (almost) equal to @code{0} or @code{1}, then the truncated 11176domain is not chanced and the call returns an error code. 11177 11178@emph{Notice:} If the parameters of the distribution has been changed 11179it is recommended to set the truncated domain again, since the 11180former call might change the domain of the distribution but not 11181update the values for the boundaries of the truncated 11182distribution. 11183@end deftypefn 11184@end ifinfo 11185@ifnotinfo 11186@anchor{funct:unur_cstd_chg_truncated} 11187@deftypefn {} {int} unur_cstd_chg_truncated (UNUR_GEN* @var{generator}, double @var{left}, double @var{right}) 11188Change left and right border of the domain of the (truncated) distribution. 11189This is only possible if the inversion method is used. 11190Otherwise this call has no effect and an error code is returned. 11191 11192Notice that the given truncated domain must be a subset of the 11193domain of the given distribution. The generator always uses the 11194intersection of the domain of the distribution and the truncated 11195domain given by this call. 11196 11197It is not required to run 11198@ifhtml 11199@ref{funct:unur_reinit,@command{unur_reinit}} 11200@end ifhtml 11201@ifnothtml 11202@command{unur_reinit} 11203@end ifnothtml 11204after this call has been used. 11205 11206@emph{Important:} If the CDF is (almost) the same for @var{left} and 11207@var{right} and (almost) equal to @code{0} or @code{1}, then the truncated 11208domain is not chanced and the call returns an error code. 11209 11210@emph{Notice:} If the parameters of the distribution has been changed 11211it is recommended to set the truncated domain again, since the 11212former call might change the domain of the distribution but not 11213update the values for the boundaries of the truncated 11214distribution. 11215@end deftypefn 11216@end ifnotinfo 11217 11218 11219 11220 11221@c 11222@c end of cstd.h 11223@c ------------------------------------- 11224@c ------------------------------------- 11225@c hinv.h 11226@c 11227 11228@page 11229@node HINV 11230@subsection HINV -- Hermite interpolation based INVersion of CDF 11231 11232@table @i 11233@item Required: 11234CDF 11235@item Optional: 11236PDF, dPDF 11237@item Speed: 11238Set-up: (very) slow, Sampling: (very) fast 11239@item Reinit: 11240supported 11241@item Reference: 11242@ifhtml 11243@ref{bib:HLa03,, [HLa03]} 11244@end ifhtml 11245@ifnothtml 11246[HLa03] 11247@end ifnothtml 11248@ifhtml 11249@ref{bib:HLD04,, [HLD04: Sect.7.2; Alg.7.1]} 11250@end ifhtml 11251@ifnothtml 11252[HLD04: Sect.7.2; Alg.7.1] 11253@end ifnothtml 11254 11255@end table 11256@sp 1 11257 11258 11259HINV is a variant of numerical inversion, where the inverse CDF 11260is approximated using Hermite interpolation, i.e., the interval 11261[0,1] is split into several intervals and in each interval the 11262inverse CDF is approximated by polynomials constructed by means 11263of values of the CDF and PDF at interval boundaries. This makes 11264it possible to improve the accuracy by splitting a particular 11265interval without recomputations in unaffected intervals. Three 11266types of splines are implemented: linear, cubic, and quintic 11267interpolation. For linear interpolation only the CDF is 11268required. Cubic interpolation also requires PDF and quintic 11269interpolation PDF and its derivative. 11270 11271These splines have to be computed in a setup step. However, it 11272only works for distributions with bounded domain; for 11273distributions with unbounded domain the tails are chopped off 11274such that the probability for the tail regions is small compared 11275to the given u-resolution. 11276 11277The method is not exact, as it only produces random variates of 11278the approximated distribution. Nevertheless, the maximal 11279numerical error in "u-direction" (i.e. |U-CDF(X)|, for 11280X = "approximate inverse CDF"(U) |U-CDF(X)|) can be set to the 11281required resolution (within machine precision). 11282Notice that very small values of the u-resolution are possible 11283but may increase the cost for the setup step. 11284 11285As the possible maximal error is only estimated in the setup it 11286may be necessary to set some special design points for computing 11287the Hermite interpolation to guarantee that the maximal u-error 11288can not be bigger than desired. Such points are points where the 11289density is not differentiable or has a local extremum. Notice 11290that there is no necessity to do so. However, if you do not 11291provide these points to the algorithm there might be a small 11292chance that the approximation error is larger than the given 11293u-resolution, or that the required number of intervals is larger 11294than necessary. 11295 11296 11297@subsubheading How To Use 11298 11299 11300HINV works for continuous univariate distribution objects with 11301given CDF and (optional) PDF. It uses Hermite interpolation of 11302order 1, 3 [default] or 5. The order can be set by means of 11303@ifhtml 11304@ref{funct:unur_hinv_set_order,@command{unur_hinv_set_order}.} 11305@end ifhtml 11306@ifnothtml 11307@command{unur_hinv_set_order}. 11308@end ifnothtml 11309For distributions with unbounded domains the tails are chopped 11310off such that the probability for the tail regions is small 11311compared to the given u-resulution. For finding these cut points 11312the algorithm starts with the region @code{[-1.e20,1.e20]}. For 11313the exceptional case where this might be too small (or one knows 11314this region and wants to avoid this search heuristics) it can be 11315directly set via a 11316@ifhtml 11317@ref{funct:unur_hinv_set_boundary,@command{unur_hinv_set_boundary}} 11318@end ifhtml 11319@ifnothtml 11320@command{unur_hinv_set_boundary} 11321@end ifnothtml 11322call. 11323 11324It is possible to use this method for generating from truncated 11325distributions. It even can be changed for an existing generator 11326object by an 11327@ifhtml 11328@ref{funct:unur_hinv_chg_truncated,@command{unur_hinv_chg_truncated}} 11329@end ifhtml 11330@ifnothtml 11331@command{unur_hinv_chg_truncated} 11332@end ifnothtml 11333call. 11334 11335This method is not exact, as it only produces random variates of 11336the approximated distribution. Nevertheless, the numerical error 11337in "u-direction" (i.e. |U-CDF(X)|, for 11338X = "approximate inverse CDF"(U) |U-CDF(X)|) can be controlled 11339by means of 11340@ifhtml 11341@ref{funct:unur_hinv_set_u_resolution,@command{unur_hinv_set_u_resolution}.} 11342@end ifhtml 11343@ifnothtml 11344@command{unur_hinv_set_u_resolution}. 11345@end ifnothtml 11346The possible maximal error is only estimated in the setup. Thus 11347it might be necessary to set some special design points for 11348computing the Hermite interpolation to guarantee that the 11349maximal u-error can not be bigger than desired. Such points 11350(e.g. extremal points of the PDF, points with infinite 11351derivative) can be set using using the 11352@ifhtml 11353@ref{funct:unur_hinv_set_cpoints,@command{unur_hinv_set_cpoints}} 11354@end ifhtml 11355@ifnothtml 11356@command{unur_hinv_set_cpoints} 11357@end ifnothtml 11358call. 11359If the mode for a unimodal distribution is set in the distribution 11360object this mode is automatically used as design-point if the 11361@ifhtml 11362@ref{funct:unur_hinv_set_cpoints,@command{unur_hinv_set_cpoints}} 11363@end ifhtml 11364@ifnothtml 11365@command{unur_hinv_set_cpoints} 11366@end ifnothtml 11367call is not used. 11368 11369As already mentioned the maximal error of this approximation is 11370only estimated. If this error is crucial for an application we 11371recommend to compute this error using 11372@ifhtml 11373@ref{funct:unur_hinv_estimate_error,@command{unur_hinv_estimate_error}} 11374@end ifhtml 11375@ifnothtml 11376@command{unur_hinv_estimate_error} 11377@end ifnothtml 11378which runs a small Monte Carlo simulation. 11379 11380It is possible to change the parameters and the domain of the chosen 11381distribution and run 11382@ifhtml 11383@ref{funct:unur_reinit,@command{unur_reinit}} 11384@end ifhtml 11385@ifnothtml 11386@command{unur_reinit} 11387@end ifnothtml 11388to reinitialize the generator object. 11389The values given by the last 11390@ifhtml 11391@ref{funct:unur_hinv_chg_truncated,@command{unur_hinv_chg_truncated}} 11392@end ifhtml 11393@ifnothtml 11394@command{unur_hinv_chg_truncated} 11395@end ifnothtml 11396call will be 11397then changed to the values of the domain of the underlying distribution 11398object. Moreover, starting construction points (nodes) that are given by 11399a 11400@ifhtml 11401@ref{funct:unur_hinv_set_cpoints,@command{unur_hinv_set_cpoints}} 11402@end ifhtml 11403@ifnothtml 11404@command{unur_hinv_set_cpoints} 11405@end ifnothtml 11406call are ignored when 11407@ifhtml 11408@ref{funct:unur_reinit,@command{unur_reinit}} 11409@end ifhtml 11410@ifnothtml 11411@command{unur_reinit} 11412@end ifnothtml 11413is 11414called. 11415It is important to note that for a distribution from the 11416UNU.RAN library of standard distributions 11417(@pxref{Stddist,,Standard distributions}) 11418the normalization constant has to be updated using the 11419@ifhtml 11420@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 11421@end ifhtml 11422@ifnothtml 11423@command{unur_distr_cont_upd_pdfarea} 11424@end ifnothtml 11425call whenever its parameters have been 11426changed by means of a 11427@ifhtml 11428@ref{funct:unur_distr_cont_set_pdfparams,@command{unur_distr_cont_set_pdfparams}} 11429@end ifhtml 11430@ifnothtml 11431@command{unur_distr_cont_set_pdfparams} 11432@end ifnothtml 11433call. 11434 11435 11436 11437 11438@subheading Function reference 11439 11440@ifhtml 11441@itemize 11442@item @ref{funct:unur_hinv_new,unur_hinv_new} 11443@item @ref{funct:unur_hinv_set_order,unur_hinv_set_order} 11444@item @ref{funct:unur_hinv_set_u_resolution,unur_hinv_set_u_resolution} 11445@item @ref{funct:unur_hinv_set_cpoints,unur_hinv_set_cpoints} 11446@item @ref{funct:unur_hinv_set_boundary,unur_hinv_set_boundary} 11447@item @ref{funct:unur_hinv_set_guidefactor,unur_hinv_set_guidefactor} 11448@item @ref{funct:unur_hinv_set_max_intervals,unur_hinv_set_max_intervals} 11449@item @ref{funct:unur_hinv_get_n_intervals,unur_hinv_get_n_intervals} 11450@item @ref{funct:unur_hinv_eval_approxinvcdf,unur_hinv_eval_approxinvcdf} 11451@item @ref{funct:unur_hinv_chg_truncated,unur_hinv_chg_truncated} 11452@item @ref{funct:unur_hinv_estimate_error,unur_hinv_estimate_error} 11453@end itemize 11454@end ifhtml 11455 11456 11457@ifinfo 11458@anchor{funct:unur_hinv_new} 11459@deftypefn Function {UNUR_PAR*} unur_hinv_new (const @var{UNUR_DISTR* distribution}) 11460Get default parameters for generator. 11461@end deftypefn 11462@end ifinfo 11463@ifnotinfo 11464@anchor{funct:unur_hinv_new} 11465@deftypefn {} {UNUR_PAR*} unur_hinv_new (const @var{UNUR_DISTR* distribution}) 11466Get default parameters for generator. 11467@end deftypefn 11468@end ifnotinfo 11469 11470@ifinfo 11471@anchor{funct:unur_hinv_set_order} 11472@deftypefn Function {int} unur_hinv_set_order (UNUR_PAR* @var{parameters}, int @var{order}) 11473Set order of Hermite interpolation. Valid orders are 11474@code{1}, @code{3}, and @code{5}. 11475Notice that @var{order} greater than @code{1} requires the density 11476of the distribution, and @var{order} greater than @code{3} even 11477requires the derivative of the density. Using @var{order} @code{1} 11478results for most distributions in a huge number of intervals 11479and is therefore not recommended. If the maximal error in 11480u-direction is very small (say smaller than @code{1.e-10}), 11481@var{order} @code{5} is recommended as it leads to considerably 11482fewer design points, as long there are no poles or heavy tails. 11483 11484@emph{Remark:} When the target distribution has poles or (very) heavy 11485tails @var{order} @code{5} (i.e., quintic interpolation) is 11486numerically less stable and more sensitive to round-off errors than 11487@var{order} @code{3} (i.e., cubic interpolation). 11488 11489Default is @code{3} if the density is given and @code{1} otherwise. 11490@end deftypefn 11491@end ifinfo 11492@ifnotinfo 11493@anchor{funct:unur_hinv_set_order} 11494@deftypefn {} {int} unur_hinv_set_order (UNUR_PAR* @var{parameters}, int @var{order}) 11495Set order of Hermite interpolation. Valid orders are 11496@code{1}, @code{3}, and @code{5}. 11497Notice that @var{order} greater than @code{1} requires the density 11498of the distribution, and @var{order} greater than @code{3} even 11499requires the derivative of the density. Using @var{order} @code{1} 11500results for most distributions in a huge number of intervals 11501and is therefore not recommended. If the maximal error in 11502u-direction is very small (say smaller than @code{1.e-10}), 11503@var{order} @code{5} is recommended as it leads to considerably 11504fewer design points, as long there are no poles or heavy tails. 11505 11506@emph{Remark:} When the target distribution has poles or (very) heavy 11507tails @var{order} @code{5} (i.e., quintic interpolation) is 11508numerically less stable and more sensitive to round-off errors than 11509@var{order} @code{3} (i.e., cubic interpolation). 11510 11511Default is @code{3} if the density is given and @code{1} otherwise. 11512@end deftypefn 11513@end ifnotinfo 11514 11515@ifinfo 11516@anchor{funct:unur_hinv_set_u_resolution} 11517@deftypefn Function {int} unur_hinv_set_u_resolution (UNUR_PAR* @var{parameters}, double @var{u_resolution}) 11518Set maximal error in u-direction. However, the given u-error must not 11519be smaller than machine epsilon (@code{DBL_EPSILON}) and should not be 11520too close to this value. As the resolution of most uniform random 11521number sources is 2^(-32) = @code{2.3e-10}, a value of @code{1.e-10} 11522leads to an inversion algorithm that could be called exact. For most 11523simulations slightly bigger values for the maximal error are enough 11524as well. 11525 11526Remark: The u-error might become larger than @var{u_resolution} due 11527to rescaling of floating point numbers when the domain of the 11528distribution is truncated by a 11529@ifhtml 11530@ref{funct:unur_hinv_chg_truncated,@command{unur_hinv_chg_truncated}} 11531@end ifhtml 11532@ifnothtml 11533@command{unur_hinv_chg_truncated} 11534@end ifnothtml 11535call. 11536 11537Default is @code{1.e-10}. 11538@end deftypefn 11539@end ifinfo 11540@ifnotinfo 11541@anchor{funct:unur_hinv_set_u_resolution} 11542@deftypefn {} {int} unur_hinv_set_u_resolution (UNUR_PAR* @var{parameters}, double @var{u_resolution}) 11543Set maximal error in u-direction. However, the given u-error must not 11544be smaller than machine epsilon (@code{DBL_EPSILON}) and should not be 11545too close to this value. As the resolution of most uniform random 11546number sources is 2^(-32) = @code{2.3e-10}, a value of @code{1.e-10} 11547leads to an inversion algorithm that could be called exact. For most 11548simulations slightly bigger values for the maximal error are enough 11549as well. 11550 11551Remark: The u-error might become larger than @var{u_resolution} due 11552to rescaling of floating point numbers when the domain of the 11553distribution is truncated by a 11554@ifhtml 11555@ref{funct:unur_hinv_chg_truncated,@command{unur_hinv_chg_truncated}} 11556@end ifhtml 11557@ifnothtml 11558@command{unur_hinv_chg_truncated} 11559@end ifnothtml 11560call. 11561 11562Default is @code{1.e-10}. 11563@end deftypefn 11564@end ifnotinfo 11565 11566@ifinfo 11567@anchor{funct:unur_hinv_set_cpoints} 11568@deftypefn Function {int} unur_hinv_set_cpoints (UNUR_PAR* @var{parameters}, const @var{double* stp}, int @var{n_stp}) 11569Set starting construction points (nodes) for Hermite interpolation. 11570 11571As the possible maximal error is only estimated in the setup 11572it may be necessary to set some special design points for 11573computing the Hermite interpolation to guarantee that the 11574maximal u-error can not be bigger than desired. We suggest to 11575include as special design points all local extrema of the density, 11576all points where the density is not differentiable, and isolated 11577points inside of the domain with density 0. 11578If there is an interval with density constant equal to 0 inside of 11579the given domain of the density, both endpoints of this interval 11580should be included as special design points. Notice that there is no 11581necessity to do so. However, if these points are not provided to 11582the algorithm the approximation error might be larger than the 11583given u-resolution, or the required number of intervals could be 11584larger than necessary. 11585 11586@emph{Important}: Notice that the given points must be in 11587increasing order and they must be disjoint. 11588 11589@emph{Important}: The boundary point of the computational region 11590must not be given in this list! 11591Points outside the boundary of the computational region are ignored. 11592 11593Default is for unimodal densities - if known - the mode of the 11594density, if it is not equal to the border of the domain. 11595@end deftypefn 11596@end ifinfo 11597@ifnotinfo 11598@anchor{funct:unur_hinv_set_cpoints} 11599@deftypefn {} {int} unur_hinv_set_cpoints (UNUR_PAR* @var{parameters}, const @var{double* stp}, int @var{n_stp}) 11600Set starting construction points (nodes) for Hermite interpolation. 11601 11602As the possible maximal error is only estimated in the setup 11603it may be necessary to set some special design points for 11604computing the Hermite interpolation to guarantee that the 11605maximal u-error can not be bigger than desired. We suggest to 11606include as special design points all local extrema of the density, 11607all points where the density is not differentiable, and isolated 11608points inside of the domain with density 0. 11609If there is an interval with density constant equal to 0 inside of 11610the given domain of the density, both endpoints of this interval 11611should be included as special design points. Notice that there is no 11612necessity to do so. However, if these points are not provided to 11613the algorithm the approximation error might be larger than the 11614given u-resolution, or the required number of intervals could be 11615larger than necessary. 11616 11617@emph{Important}: Notice that the given points must be in 11618increasing order and they must be disjoint. 11619 11620@emph{Important}: The boundary point of the computational region 11621must not be given in this list! 11622Points outside the boundary of the computational region are ignored. 11623 11624Default is for unimodal densities - if known - the mode of the 11625density, if it is not equal to the border of the domain. 11626@end deftypefn 11627@end ifnotinfo 11628 11629@ifinfo 11630@anchor{funct:unur_hinv_set_boundary} 11631@deftypefn Function {int} unur_hinv_set_boundary (UNUR_PAR* @var{parameters}, double @var{left}, double @var{right}) 11632Set the left and right boundary of the computational interval. 11633Of course @code{+/- UNUR_INFINITY} is not allowed. 11634If the CDF at @var{left} and @var{right} is not close to the 11635respective values @code{0.} and @code{1.} then this interval is 11636increased by a (rather slow) search algorithm. 11637 11638@emph{Important}: This call does not change the domain of the 11639given distribution itself. But it restricts the domain for the 11640resulting random variates. 11641 11642Default is @code{1.e20}. 11643@end deftypefn 11644@end ifinfo 11645@ifnotinfo 11646@anchor{funct:unur_hinv_set_boundary} 11647@deftypefn {} {int} unur_hinv_set_boundary (UNUR_PAR* @var{parameters}, double @var{left}, double @var{right}) 11648Set the left and right boundary of the computational interval. 11649Of course @code{+/- UNUR_INFINITY} is not allowed. 11650If the CDF at @var{left} and @var{right} is not close to the 11651respective values @code{0.} and @code{1.} then this interval is 11652increased by a (rather slow) search algorithm. 11653 11654@emph{Important}: This call does not change the domain of the 11655given distribution itself. But it restricts the domain for the 11656resulting random variates. 11657 11658Default is @code{1.e20}. 11659@end deftypefn 11660@end ifnotinfo 11661 11662@ifinfo 11663@anchor{funct:unur_hinv_set_guidefactor} 11664@deftypefn Function {int} unur_hinv_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 11665Set factor for relative size of the guide table for indexed search 11666(see also method DGT @ref{DGT}). It must be greater than or equal 11667to @code{0}. 11668When set to @code{0}, then sequential search is used. 11669 11670Default is @code{1}. 11671@end deftypefn 11672@end ifinfo 11673@ifnotinfo 11674@anchor{funct:unur_hinv_set_guidefactor} 11675@deftypefn {} {int} unur_hinv_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 11676Set factor for relative size of the guide table for indexed search 11677(see also method DGT @ref{DGT}). It must be greater than or equal 11678to @code{0}. 11679When set to @code{0}, then sequential search is used. 11680 11681Default is @code{1}. 11682@end deftypefn 11683@end ifnotinfo 11684 11685@ifinfo 11686@anchor{funct:unur_hinv_set_max_intervals} 11687@deftypefn Function {int} unur_hinv_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 11688Set maximum number of intervals. No generator object is created if 11689the necessary number of intervals for the Hermite interpolation 11690exceeds @var{max_ivs}. It is used to prevent the algorithm to eat up 11691all memory for very badly shaped CDFs. 11692 11693Default is @code{1000000} (1.e6). 11694@end deftypefn 11695@end ifinfo 11696@ifnotinfo 11697@anchor{funct:unur_hinv_set_max_intervals} 11698@deftypefn {} {int} unur_hinv_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 11699Set maximum number of intervals. No generator object is created if 11700the necessary number of intervals for the Hermite interpolation 11701exceeds @var{max_ivs}. It is used to prevent the algorithm to eat up 11702all memory for very badly shaped CDFs. 11703 11704Default is @code{1000000} (1.e6). 11705@end deftypefn 11706@end ifnotinfo 11707 11708@ifinfo 11709@anchor{funct:unur_hinv_get_n_intervals} 11710@deftypefn Function {int} unur_hinv_get_n_intervals (const @var{UNUR_GEN* generator}) 11711Get number of nodes (design points) used for Hermite interpolation in 11712the generator object. The number of intervals is the number of 11713nodes minus 1. 11714It returns an error code in case of an error. 11715@end deftypefn 11716@end ifinfo 11717@ifnotinfo 11718@anchor{funct:unur_hinv_get_n_intervals} 11719@deftypefn {} {int} unur_hinv_get_n_intervals (const @var{UNUR_GEN* generator}) 11720Get number of nodes (design points) used for Hermite interpolation in 11721the generator object. The number of intervals is the number of 11722nodes minus 1. 11723It returns an error code in case of an error. 11724@end deftypefn 11725@end ifnotinfo 11726 11727@ifinfo 11728@anchor{funct:unur_hinv_eval_approxinvcdf} 11729@deftypefn Function {double} unur_hinv_eval_approxinvcdf (const @var{UNUR_GEN* generator}, double @var{u}) 11730Evaluate Hermite interpolation of inverse CDF at @var{u}. 11731If @var{u} is out of the domain [0,1] then @code{unur_errno} is set 11732to @code{UNUR_ERR_DOMAIN} and the respective bound of 11733the domain of the distribution are returned (which is 11734@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 11735unbounded domains). 11736 11737@emph{Notice}: When the domain has been truncated by a 11738@ifhtml 11739@ref{funct:unur_hinv_chg_truncated,@command{unur_hinv_chg_truncated}} 11740@end ifhtml 11741@ifnothtml 11742@command{unur_hinv_chg_truncated} 11743@end ifnothtml 11744call then the inverse CDF of the 11745truncated distribution is returned. 11746@end deftypefn 11747@end ifinfo 11748@ifnotinfo 11749@anchor{funct:unur_hinv_eval_approxinvcdf} 11750@deftypefn {} {double} unur_hinv_eval_approxinvcdf (const @var{UNUR_GEN* generator}, double @var{u}) 11751Evaluate Hermite interpolation of inverse CDF at @var{u}. 11752If @var{u} is out of the domain [0,1] then @code{unur_errno} is set 11753to @code{UNUR_ERR_DOMAIN} and the respective bound of 11754the domain of the distribution are returned (which is 11755@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 11756unbounded domains). 11757 11758@emph{Notice}: When the domain has been truncated by a 11759@ifhtml 11760@ref{funct:unur_hinv_chg_truncated,@command{unur_hinv_chg_truncated}} 11761@end ifhtml 11762@ifnothtml 11763@command{unur_hinv_chg_truncated} 11764@end ifnothtml 11765call then the inverse CDF of the 11766truncated distribution is returned. 11767@end deftypefn 11768@end ifnotinfo 11769 11770@ifinfo 11771@anchor{funct:unur_hinv_chg_truncated} 11772@deftypefn Function {int} unur_hinv_chg_truncated (UNUR_GEN* @var{generator}, double @var{left}, double @var{right}) 11773Changes the borders of the domain of the (truncated) distribution. 11774 11775Notice that the given truncated domain must be a subset of the 11776domain of the given distribution. The generator always uses the 11777intersection of the domain of the distribution and the truncated 11778domain given by this call. The tables of splines are not recomputed. 11779Thus it might happen that the relative error for the generated variates 11780from the truncated distribution is greater than the bound for the 11781non-truncated distribution. This call also fails when the CDF values 11782of the boundary points are too close, i.e. when only a few different 11783floating point numbers would be computed due to round-off errors 11784with floating point arithmetic. 11785 11786Remark: The u-error might become larger than the @var{u_resolution} 11787given by a 11788@ifhtml 11789@ref{funct:unur_hinv_set_u_resolution,@command{unur_hinv_set_u_resolution}} 11790@end ifhtml 11791@ifnothtml 11792@command{unur_hinv_set_u_resolution} 11793@end ifnothtml 11794call due to rescaling of 11795floating point numbers when the domain of the distribution is 11796truncated. 11797 11798When failed an error code is returned. 11799 11800@emph{Important}: Always check the return code since the domain is 11801not changed in case of an error. 11802@end deftypefn 11803@end ifinfo 11804@ifnotinfo 11805@anchor{funct:unur_hinv_chg_truncated} 11806@deftypefn {} {int} unur_hinv_chg_truncated (UNUR_GEN* @var{generator}, double @var{left}, double @var{right}) 11807Changes the borders of the domain of the (truncated) distribution. 11808 11809Notice that the given truncated domain must be a subset of the 11810domain of the given distribution. The generator always uses the 11811intersection of the domain of the distribution and the truncated 11812domain given by this call. The tables of splines are not recomputed. 11813Thus it might happen that the relative error for the generated variates 11814from the truncated distribution is greater than the bound for the 11815non-truncated distribution. This call also fails when the CDF values 11816of the boundary points are too close, i.e. when only a few different 11817floating point numbers would be computed due to round-off errors 11818with floating point arithmetic. 11819 11820Remark: The u-error might become larger than the @var{u_resolution} 11821given by a 11822@ifhtml 11823@ref{funct:unur_hinv_set_u_resolution,@command{unur_hinv_set_u_resolution}} 11824@end ifhtml 11825@ifnothtml 11826@command{unur_hinv_set_u_resolution} 11827@end ifnothtml 11828call due to rescaling of 11829floating point numbers when the domain of the distribution is 11830truncated. 11831 11832When failed an error code is returned. 11833 11834@emph{Important}: Always check the return code since the domain is 11835not changed in case of an error. 11836@end deftypefn 11837@end ifnotinfo 11838 11839@ifinfo 11840@anchor{funct:unur_hinv_estimate_error} 11841@deftypefn Function {int} unur_hinv_estimate_error (const @var{UNUR_GEN* generator}, int @var{samplesize}, double* @var{max_error}, double* @var{MAE}) 11842Estimate maximal u-error and mean absolute error (MAE) for 11843@var{generator} by means of a (quasi-) Monte-Carlo simulation with 11844sample size @var{samplesize}. 11845The results are stored in @var{max_error} and @var{MAE}, respectively. 11846 11847It returns @code{UNUR_SUCCESS} if successful. 11848@end deftypefn 11849@end ifinfo 11850@ifnotinfo 11851@anchor{funct:unur_hinv_estimate_error} 11852@deftypefn {} {int} unur_hinv_estimate_error (const @var{UNUR_GEN* generator}, int @var{samplesize}, double* @var{max_error}, double* @var{MAE}) 11853Estimate maximal u-error and mean absolute error (MAE) for 11854@var{generator} by means of a (quasi-) Monte-Carlo simulation with 11855sample size @var{samplesize}. 11856The results are stored in @var{max_error} and @var{MAE}, respectively. 11857 11858It returns @code{UNUR_SUCCESS} if successful. 11859@end deftypefn 11860@end ifnotinfo 11861 11862 11863 11864 11865@c 11866@c end of hinv.h 11867@c ------------------------------------- 11868@c ------------------------------------- 11869@c hrb.h 11870@c 11871 11872@page 11873@node HRB 11874@subsection HRB -- Hazard Rate Bounded 11875 11876@table @i 11877@item Required: 11878bounded hazard rate 11879@item Optional: 11880upper bound for hazard rate 11881@item Speed: 11882Set-up: fast, Sampling: slow 11883@item Reinit: 11884supported 11885@item Reference: 11886@ifhtml 11887@ref{bib:HLD04,, [HLD04: Sect.9.1.4; Alg.9.4]} 11888@end ifhtml 11889@ifnothtml 11890[HLD04: Sect.9.1.4; Alg.9.4] 11891@end ifnothtml 11892 11893@end table 11894@sp 1 11895 11896 11897Generates random variate with given hazard rate which must be 11898bounded from above. It uses the thinning method with a constant 11899dominating hazard function. 11900 11901 11902@subsubheading How To Use 11903 11904 11905HRB requires a hazard function for a continuous distribution 11906together with an upper bound. The latter has to be set using the 11907@ifhtml 11908@ref{funct:unur_hrb_set_upperbound,@command{unur_hrb_set_upperbound}} 11909@end ifhtml 11910@ifnothtml 11911@command{unur_hrb_set_upperbound} 11912@end ifnothtml 11913call. If no such upper bound is given 11914it is assumed that the upper bound can be achieved by evaluating 11915the hazard rate at the left hand boundary of the domain of the 11916distribution. Notice, however, that for decreasing hazard rate 11917the method HRD (@pxref{HRD,,Hazard Rate Decreasing}) is much 11918faster and thus the prefered method. 11919 11920It is important to note that the domain of the distribution can 11921be set via a 11922@ifhtml 11923@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 11924@end ifhtml 11925@ifnothtml 11926@command{unur_distr_cont_set_domain} 11927@end ifnothtml 11928call. 11929However, the left border must not be negative. Otherwise it is 11930set to @code{0}. This is also the default if no domain is 11931given at all. For computational reasons the right border is 11932always set to @code{UNUR_INFINITY} independently of the given 11933domain. Thus for domains bounded from right the function for 11934computing the hazard rate should return @code{UNUR_INFINITY} 11935right of this domain. 11936 11937For distributions with increasing hazard rate method HRI 11938(@pxref{HRI,,Hazard Rate Increasing}) is required. 11939 11940It is possible to change the parameters and the domain of the chosen 11941distribution and run 11942@ifhtml 11943@ref{funct:unur_reinit,@command{unur_reinit}} 11944@end ifhtml 11945@ifnothtml 11946@command{unur_reinit} 11947@end ifnothtml 11948to reinitialize the generator object. 11949Notice, that the upper bound given by the 11950@ifhtml 11951@ref{funct:unur_hrb_set_upperbound,@command{unur_hrb_set_upperbound}} 11952@end ifhtml 11953@ifnothtml 11954@command{unur_hrb_set_upperbound} 11955@end ifnothtml 11956call 11957cannot be changed and must be valid for the changed distribution. 11958 11959 11960 11961@subheading Function reference 11962 11963@ifhtml 11964@itemize 11965@item @ref{funct:unur_hrb_new,unur_hrb_new} 11966@item @ref{funct:unur_hrb_set_upperbound,unur_hrb_set_upperbound} 11967@item @ref{funct:unur_hrb_set_verify,unur_hrb_set_verify} 11968@item @ref{funct:unur_hrb_chg_verify,unur_hrb_chg_verify} 11969@end itemize 11970@end ifhtml 11971 11972 11973@ifinfo 11974@anchor{funct:unur_hrb_new} 11975@deftypefn Function {UNUR_PAR*} unur_hrb_new (const @var{UNUR_DISTR* distribution}) 11976Get default parameters for generator. 11977@end deftypefn 11978@end ifinfo 11979@ifnotinfo 11980@anchor{funct:unur_hrb_new} 11981@deftypefn {} {UNUR_PAR*} unur_hrb_new (const @var{UNUR_DISTR* distribution}) 11982Get default parameters for generator. 11983@end deftypefn 11984@end ifnotinfo 11985 11986@ifinfo 11987@anchor{funct:unur_hrb_set_upperbound} 11988@deftypefn Function {int} unur_hrb_set_upperbound (UNUR_PAR* @var{parameters}, double @var{upperbound}) 11989Set upper bound for hazard rate. If this call is not used it is 11990assumed that the the maximum of the hazard rate is achieved at the 11991left hand boundary of the domain of the distribution. 11992@end deftypefn 11993@end ifinfo 11994@ifnotinfo 11995@anchor{funct:unur_hrb_set_upperbound} 11996@deftypefn {} {int} unur_hrb_set_upperbound (UNUR_PAR* @var{parameters}, double @var{upperbound}) 11997Set upper bound for hazard rate. If this call is not used it is 11998assumed that the the maximum of the hazard rate is achieved at the 11999left hand boundary of the domain of the distribution. 12000@end deftypefn 12001@end ifnotinfo 12002 12003@ifinfo 12004@anchor{funct:unur_hrb_set_verify} 12005@deftypefn Function {int} unur_hrb_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 12006@anchor{funct:unur_hrb_chg_verify} 12007@deftypefnx Function {int} unur_hrb_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 12008Turn verifying of algorithm while sampling on/off. 12009If the hazard rate is not bounded by the given bound, then 12010@code{unur_errno} is set to @code{UNUR_ERR_GEN_CONDITION}. 12011 12012Default is @code{FALSE}. 12013@end deftypefn 12014@end ifinfo 12015@ifnotinfo 12016@anchor{funct:unur_hrb_set_verify} 12017@deftypefn {} {int} unur_hrb_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 12018@anchor{funct:unur_hrb_chg_verify} 12019@deftypefnx {} {int} unur_hrb_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 12020Turn verifying of algorithm while sampling on/off. 12021If the hazard rate is not bounded by the given bound, then 12022@code{unur_errno} is set to @code{UNUR_ERR_GEN_CONDITION}. 12023 12024Default is @code{FALSE}. 12025@end deftypefn 12026@end ifnotinfo 12027 12028 12029 12030 12031@c 12032@c end of hrb.h 12033@c ------------------------------------- 12034@c ------------------------------------- 12035@c hrd.h 12036@c 12037 12038@page 12039@node HRD 12040@subsection HRD -- Hazard Rate Decreasing 12041 12042@table @i 12043@item Required: 12044decreasing (non-increasing) hazard rate 12045@item Speed: 12046Set-up: fast, Sampling: slow 12047@item Reinit: 12048supported 12049@item Reference: 12050@ifhtml 12051@ref{bib:HLD04,, [HLD04: Sect.9.1.5; Alg.9.5]} 12052@end ifhtml 12053@ifnothtml 12054[HLD04: Sect.9.1.5; Alg.9.5] 12055@end ifnothtml 12056 12057@end table 12058@sp 1 12059 12060 12061Generates random variate with given non-increasing hazard rate. 12062It is necessary that the distribution object contains this 12063hazard rate. Decreasing hazard rate implies that the 12064corresponding PDF of the distribution has heavier tails than the 12065exponential distribution (which has constant hazard rate). 12066 12067 12068@subsubheading How To Use 12069 12070 12071HRD requires a hazard function for a continuous distribution 12072with non-increasing hazard rate. There are no parameters for 12073this method. 12074 12075It is important to note that the domain of the distribution can 12076be set via a 12077@ifhtml 12078@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 12079@end ifhtml 12080@ifnothtml 12081@command{unur_distr_cont_set_domain} 12082@end ifnothtml 12083call. However, only 12084the left hand boundary is used. For computational reasons the 12085right hand boundary is always reset to @code{UNUR_INFINITY}. 12086If no domain is given by the user then the left hand boundary is 12087set to @code{0}. 12088 12089For distributions which do not have decreasing hazard rates but 12090are bounded from above use method HRB 12091(@pxref{HRB,,Hazard Rate Bounded}). 12092For distributions with increasing hazard rate method HRI 12093(@pxref{HRI,,Hazard Rate Increasing}) is required. 12094 12095It is possible to change the parameters and the domain of the chosen 12096distribution and run 12097@ifhtml 12098@ref{funct:unur_reinit,@command{unur_reinit}} 12099@end ifhtml 12100@ifnothtml 12101@command{unur_reinit} 12102@end ifnothtml 12103to reinitialize the generator object. 12104 12105 12106 12107 12108@subheading Function reference 12109 12110@ifhtml 12111@itemize 12112@item @ref{funct:unur_hrd_new,unur_hrd_new} 12113@item @ref{funct:unur_hrd_set_verify,unur_hrd_set_verify} 12114@item @ref{funct:unur_hrd_chg_verify,unur_hrd_chg_verify} 12115@end itemize 12116@end ifhtml 12117 12118 12119@ifinfo 12120@anchor{funct:unur_hrd_new} 12121@deftypefn Function {UNUR_PAR*} unur_hrd_new (const @var{UNUR_DISTR* distribution}) 12122Get default parameters for generator. 12123@end deftypefn 12124@end ifinfo 12125@ifnotinfo 12126@anchor{funct:unur_hrd_new} 12127@deftypefn {} {UNUR_PAR*} unur_hrd_new (const @var{UNUR_DISTR* distribution}) 12128Get default parameters for generator. 12129@end deftypefn 12130@end ifnotinfo 12131 12132@ifinfo 12133@anchor{funct:unur_hrd_set_verify} 12134@deftypefn Function {int} unur_hrd_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 12135@anchor{funct:unur_hrd_chg_verify} 12136@deftypefnx Function {int} unur_hrd_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 12137Turn verifying of algorithm while sampling on/off. 12138If the hazard rate is not bounded by the given bound, then 12139@code{unur_errno} is set to @code{UNUR_ERR_GEN_CONDITION}. 12140 12141Default is @code{FALSE}. 12142@end deftypefn 12143@end ifinfo 12144@ifnotinfo 12145@anchor{funct:unur_hrd_set_verify} 12146@deftypefn {} {int} unur_hrd_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 12147@anchor{funct:unur_hrd_chg_verify} 12148@deftypefnx {} {int} unur_hrd_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 12149Turn verifying of algorithm while sampling on/off. 12150If the hazard rate is not bounded by the given bound, then 12151@code{unur_errno} is set to @code{UNUR_ERR_GEN_CONDITION}. 12152 12153Default is @code{FALSE}. 12154@end deftypefn 12155@end ifnotinfo 12156 12157 12158 12159 12160@c 12161@c end of hrd.h 12162@c ------------------------------------- 12163@c ------------------------------------- 12164@c hri.h 12165@c 12166 12167@page 12168@node HRI 12169@subsection HRI -- Hazard Rate Increasing 12170 12171@table @i 12172@item Required: 12173increasing (non-decreasing) hazard rate 12174@item Speed: 12175Set-up: fast, Sampling: slow 12176@item Reinit: 12177supported 12178@item Reference: 12179@ifhtml 12180@ref{bib:HLD04,, [HLD04: Sect.9.1.6; Alg.9.6]} 12181@end ifhtml 12182@ifnothtml 12183[HLD04: Sect.9.1.6; Alg.9.6] 12184@end ifnothtml 12185 12186@end table 12187@sp 1 12188 12189 12190Generates random variate with given non-increasing hazard rate. 12191It is necessary that the distribution object contains this hazard rate. 12192Increasing hazard rate implies that the corresponding PDF of the 12193distribution has heavier tails than the exponential distribution 12194(which has constant hazard rate). 12195 12196The method uses a decomposition of the hazard rate into a main 12197part which is constant for all @i{x} beyond some point @i{p0} 12198and a remaining part. From both of these parts points are 12199sampled using the thinning method and the minimum of both is 12200returned. Sampling from the first part is easier as we have a 12201constant dominating hazard rate. Thus @i{p0} should be large. On 12202the other hand, if @i{p0} is large than the thinning algorithm 12203needs many iteration. Thus the performance of the the algorithm 12204deponds on the choice of @i{p0}. We found that values close to 12205the expectation of the generated distribution result in good 12206performance. 12207 12208 12209@subsubheading How To Use 12210 12211 12212HRI requires a hazard function for a continuous distribution 12213with non-decreasing hazard rate. 12214The parameter @i{p0} should be set to a value close to the 12215expectation of the required distribution using 12216@ifhtml 12217@ref{funct:unur_hri_set_p0,@command{unur_hri_set_p0}.} 12218@end ifhtml 12219@ifnothtml 12220@command{unur_hri_set_p0}. 12221@end ifnothtml 12222If performance is crucial one may try other 12223values as well. 12224 12225It is important to note that the domain of the distribution can 12226be set via a 12227@ifhtml 12228@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 12229@end ifhtml 12230@ifnothtml 12231@command{unur_distr_cont_set_domain} 12232@end ifnothtml 12233call. However, only 12234the left hand boundary is used. For computational reasons the 12235right hand boundary is always reset to @code{UNUR_INFINITY}. 12236If no domain is given by the user then the left hand boundary is 12237set to @code{0}. 12238 12239For distributions with decreasing hazard rate method HRD 12240(@pxref{HRI,,Hazard Rate Decreasing}) is required. 12241For distributions which do not have increasing or decreasing 12242hazard rates but are bounded from above use method HRB 12243(@pxref{HRB,,Hazard Rate Bounded}). 12244 12245It is possible to change the parameters and the domain of the chosen 12246distribution and run 12247@ifhtml 12248@ref{funct:unur_reinit,@command{unur_reinit}} 12249@end ifhtml 12250@ifnothtml 12251@command{unur_reinit} 12252@end ifnothtml 12253to reinitialize the generator object. 12254 12255 12256Notice, that the upper bound given by the 12257@ifhtml 12258@ref{funct:unur_hrb_set_upperbound,@command{unur_hrb_set_upperbound}} 12259@end ifhtml 12260@ifnothtml 12261@command{unur_hrb_set_upperbound} 12262@end ifnothtml 12263call 12264cannot be changed and must be valid for the changed distribution. 12265Notice that the parameter @i{p0} which has been set by a 12266@ifhtml 12267@ref{funct:unur_hri_set_p0,@command{unur_hri_set_p0}} 12268@end ifhtml 12269@ifnothtml 12270@command{unur_hri_set_p0} 12271@end ifnothtml 12272call cannot be changed and must be valid for the changed distribution. 12273 12274 12275 12276 12277@subheading Function reference 12278 12279@ifhtml 12280@itemize 12281@item @ref{funct:unur_hri_new,unur_hri_new} 12282@item @ref{funct:unur_hri_set_p0,unur_hri_set_p0} 12283@item @ref{funct:unur_hri_set_verify,unur_hri_set_verify} 12284@item @ref{funct:unur_hri_chg_verify,unur_hri_chg_verify} 12285@end itemize 12286@end ifhtml 12287 12288 12289@ifinfo 12290@anchor{funct:unur_hri_new} 12291@deftypefn Function {UNUR_PAR*} unur_hri_new (const @var{UNUR_DISTR* distribution}) 12292Get default parameters for generator. 12293@end deftypefn 12294@end ifinfo 12295@ifnotinfo 12296@anchor{funct:unur_hri_new} 12297@deftypefn {} {UNUR_PAR*} unur_hri_new (const @var{UNUR_DISTR* distribution}) 12298Get default parameters for generator. 12299@end deftypefn 12300@end ifnotinfo 12301 12302@ifinfo 12303@anchor{funct:unur_hri_set_p0} 12304@deftypefn Function {int} unur_hri_set_p0 (UNUR_PAR* @var{parameters}, double @var{p0}) 12305Set design point for algorithm. It is used to split the domain of the 12306distribution. Values for @var{p0} close to the expectation of the 12307distribution results in a relatively good performance of the algorithm. 12308It is important that the hazard rate at this point must be greater 12309than @code{0} and less than @code{UNUR_INFINITY}. 12310 12311Default: left boundary of domain + @code{1.} 12312@end deftypefn 12313@end ifinfo 12314@ifnotinfo 12315@anchor{funct:unur_hri_set_p0} 12316@deftypefn {} {int} unur_hri_set_p0 (UNUR_PAR* @var{parameters}, double @var{p0}) 12317Set design point for algorithm. It is used to split the domain of the 12318distribution. Values for @var{p0} close to the expectation of the 12319distribution results in a relatively good performance of the algorithm. 12320It is important that the hazard rate at this point must be greater 12321than @code{0} and less than @code{UNUR_INFINITY}. 12322 12323Default: left boundary of domain + @code{1.} 12324@end deftypefn 12325@end ifnotinfo 12326 12327@ifinfo 12328@anchor{funct:unur_hri_set_verify} 12329@deftypefn Function {int} unur_hri_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 12330@anchor{funct:unur_hri_chg_verify} 12331@deftypefnx Function {int} unur_hri_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 12332Turn verifying of algorithm while sampling on/off. 12333If the hazard rate is not bounded by the given bound, then 12334@code{unur_errno} is set to @code{UNUR_ERR_GEN_CONDITION}. 12335 12336Default is @code{FALSE}. 12337@end deftypefn 12338@end ifinfo 12339@ifnotinfo 12340@anchor{funct:unur_hri_set_verify} 12341@deftypefn {} {int} unur_hri_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 12342@anchor{funct:unur_hri_chg_verify} 12343@deftypefnx {} {int} unur_hri_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 12344Turn verifying of algorithm while sampling on/off. 12345If the hazard rate is not bounded by the given bound, then 12346@code{unur_errno} is set to @code{UNUR_ERR_GEN_CONDITION}. 12347 12348Default is @code{FALSE}. 12349@end deftypefn 12350@end ifnotinfo 12351 12352 12353 12354 12355@c 12356@c end of hri.h 12357@c ------------------------------------- 12358@c ------------------------------------- 12359@c itdr.h 12360@c 12361 12362@page 12363@node ITDR 12364@subsection ITDR -- Inverse Transformed Density Rejection 12365 12366@table @i 12367@item Required: 12368monotone PDF, dPDF, pole 12369@item Optional: 12370splitting point between pole and tail region, c-values 12371@item Speed: 12372Set-up: moderate, Sampling: moderate 12373@item Reinit: 12374supported 12375@item Reference: 12376@ifhtml 12377@ref{bib:HLDa07,, [HLDa07]} 12378@end ifhtml 12379@ifnothtml 12380[HLDa07] 12381@end ifnothtml 12382 12383@end table 12384@sp 1 12385 12386 12387ITDR is an acceptance/rejection method that works for monotone 12388densities. It is especially designed for PDFs with a single 12389pole. It uses different hat functions for the pole region and 12390for the tail region. For the tail region @emph{Transformed Density 12391Rejection} with a single construction point is used. 12392For the pole region a variant called @emph{Inverse Transformed 12393Density Rejection} is used. The optimal splitting point between 12394the two regions and the respective maximum local concavity and 12395inverse local concavity (@pxref{Glossary}) that guarantee valid 12396hat functions for each regions are estimated. 12397This splitting point is set to the intersection point of local 12398concavity and inverse local concavity. 12399However, it is assumed that both, the local concavity and the 12400inverse local concavity do not have a local minimum in the 12401interior of the domain (which is the case for all standard 12402distributions with a single pole). 12403In other cases (or when the built-in search routines do not 12404compute non-optimal values) one can provide the splitting point, 12405and the @i{c}-values. 12406 12407 12408@subsubheading How To Use 12409 12410 12411Method ITDR requires a distribution object with given PDF 12412and its derivative and the location of the pole (or mode). 12413The PDF must be monotone and may contain a pole. 12414It must be set via the 12415@ifhtml 12416@ref{funct:unur_distr_cont_set_pdf,@command{unur_distr_cont_set_pdf}} 12417@end ifhtml 12418@ifnothtml 12419@command{unur_distr_cont_set_pdf} 12420@end ifnothtml 12421and 12422@ifhtml 12423@ref{funct:unur_distr_cont_set_dpdf,@command{unur_distr_cont_set_dpdf}} 12424@end ifhtml 12425@ifnothtml 12426@command{unur_distr_cont_set_dpdf} 12427@end ifnothtml 12428calls. The PDF should return 12429UNUR_INFINITY for the pole. Alternatively, one can also 12430set the logarithm of the PDF and its derivative via the 12431@ifhtml 12432@ref{funct:unur_distr_cont_set_logpdf,@command{unur_distr_cont_set_logpdf}} 12433@end ifhtml 12434@ifnothtml 12435@command{unur_distr_cont_set_logpdf} 12436@end ifnothtml 12437and 12438@ifhtml 12439@ref{funct:unur_distr_cont_set_dlogpdf,@command{unur_distr_cont_set_dlogpdf}} 12440@end ifhtml 12441@ifnothtml 12442@command{unur_distr_cont_set_dlogpdf} 12443@end ifnothtml 12444calls. This is in especially useful since then the setup and 12445search routines are numerically more stable. Moreover, for many 12446distributions computing the logarithm of the PDF is less 12447expensive then computing the PDF directly. 12448 12449The pole of the distribution is given by a 12450@ifhtml 12451@ref{funct:unur_distr_cont_set_mode,@command{unur_distr_cont_set_mode}} 12452@end ifhtml 12453@ifnothtml 12454@command{unur_distr_cont_set_mode} 12455@end ifnothtml 12456call. Notice that distributions with 12457``heavy'' poles may have numerical problems caused by the 12458resultion of the floating point numbers used by computers. 12459While the minimal distance between two different floating point 12460numbers is about @code{1.e-320} near @code{0.} it increases 12461to @code{1.e-16} near @code{1.} Thus any random variate 12462generator implemented on a digital computer in fact draws samples 12463from a discrete distribution that approximates the desired 12464continuous distribution. For distributions with ``heavy'' poles 12465not at 0 this approximation may be too crude and thus every 12466goodness-of-fit test will fail. 12467Besides this theoretic problem that cannot be resolved we 12468have to take into consideration that round-off errors occur more 12469frequently when we have PDFs with poles far away from 12470@code{0.} Method ITDR tries to handles this situation as good as 12471possible by moving the pole into @code{0.} 12472Thus do not use a wrapper for your PDF that hides this shift 12473since the information about the resolution of the floating point 12474numbers near the pole gets lost. 12475 12476Method ITDR uses different hats for the pole region and for the 12477tail region. The splitting point between these two regions, the 12478optimal @i{c}-value and design points for constructing the hats 12479using Transformed Density Rejection are computed automatically. 12480(The results of these computations can be read using the 12481respective calls 12482@ifhtml 12483@ref{funct:unur_itdr_get_xi,@command{unur_itdr_get_xi},} 12484@end ifhtml 12485@ifnothtml 12486@command{unur_itdr_get_xi}, 12487@end ifnothtml 12488@ifhtml 12489@ref{funct:unur_itdr_get_cp,@command{unur_itdr_get_cp}} 12490@end ifhtml 12491@ifnothtml 12492@command{unur_itdr_get_cp} 12493@end ifnothtml 12494, and 12495@ifhtml 12496@ref{funct:unur_itdr_get_ct,@command{unur_itdr_get_ct}} 12497@end ifhtml 12498@ifnothtml 12499@command{unur_itdr_get_ct} 12500@end ifnothtml 12501for the intersection point between local 12502concavity and inverse local concavity, the @i{c}-value for the 12503pole and the tail region.) 12504However, one can also analyze the local concavity and inverse 12505local concavity set the corresponding values using 12506@ifhtml 12507@ref{funct:unur_itdr_set_xi,@command{unur_itdr_set_xi},} 12508@end ifhtml 12509@ifnothtml 12510@command{unur_itdr_set_xi}, 12511@end ifnothtml 12512@ifhtml 12513@ref{funct:unur_itdr_set_cp,@command{unur_itdr_set_cp}} 12514@end ifhtml 12515@ifnothtml 12516@command{unur_itdr_set_cp} 12517@end ifnothtml 12518, and 12519@ifhtml 12520@ref{funct:unur_itdr_set_ct,@command{unur_itdr_set_ct}} 12521@end ifhtml 12522@ifnothtml 12523@command{unur_itdr_set_ct} 12524@end ifnothtml 12525calls. 12526Notice, that @i{c}-values greater than -1/2 can be set to 12527@code{-0.5}. Although this results in smaller acceptance 12528probabities sampling from the hat distribution is much faster 12529than for other values of @i{c}. Depending on the expenses of 12530evaluating the PDF the resulting algorithm is usually faster. 12531 12532It is possible to change the parameters and the domain of the chosen 12533distribution and run 12534@ifhtml 12535@ref{funct:unur_reinit,@command{unur_reinit}} 12536@end ifhtml 12537@ifnothtml 12538@command{unur_reinit} 12539@end ifnothtml 12540to reinitialize the generator object. 12541However, the values given by 12542@ifhtml 12543@ref{funct:unur_itdr_set_xi,@command{unur_itdr_set_xi},} 12544@end ifhtml 12545@ifnothtml 12546@command{unur_itdr_set_xi}, 12547@end ifnothtml 12548@ifhtml 12549@ref{funct:unur_itdr_set_cp,@command{unur_itdr_set_cp}} 12550@end ifhtml 12551@ifnothtml 12552@command{unur_itdr_set_cp} 12553@end ifnothtml 12554, 12555or 12556@ifhtml 12557@ref{funct:unur_itdr_set_ct,@command{unur_itdr_set_ct}} 12558@end ifhtml 12559@ifnothtml 12560@command{unur_itdr_set_ct} 12561@end ifnothtml 12562calls are then ignored when 12563@ifhtml 12564@ref{funct:unur_reinit,@command{unur_reinit}} 12565@end ifhtml 12566@ifnothtml 12567@command{unur_reinit} 12568@end ifnothtml 12569is 12570called. 12571 12572 12573 12574@subheading Function reference 12575 12576@ifhtml 12577@itemize 12578@item @ref{funct:unur_itdr_new,unur_itdr_new} 12579@item @ref{funct:unur_itdr_set_xi,unur_itdr_set_xi} 12580@item @ref{funct:unur_itdr_set_cp,unur_itdr_set_cp} 12581@item @ref{funct:unur_itdr_set_ct,unur_itdr_set_ct} 12582@item @ref{funct:unur_itdr_get_xi,unur_itdr_get_xi} 12583@item @ref{funct:unur_itdr_get_cp,unur_itdr_get_cp} 12584@item @ref{funct:unur_itdr_get_ct,unur_itdr_get_ct} 12585@item @ref{funct:unur_itdr_get_area,unur_itdr_get_area} 12586@item @ref{funct:unur_itdr_set_verify,unur_itdr_set_verify} 12587@item @ref{funct:unur_itdr_chg_verify,unur_itdr_chg_verify} 12588@end itemize 12589@end ifhtml 12590 12591 12592@ifinfo 12593@anchor{funct:unur_itdr_new} 12594@deftypefn Function {UNUR_PAR*} unur_itdr_new (const @var{UNUR_DISTR* distribution}) 12595Get default parameters for generator. 12596@end deftypefn 12597@end ifinfo 12598@ifnotinfo 12599@anchor{funct:unur_itdr_new} 12600@deftypefn {} {UNUR_PAR*} unur_itdr_new (const @var{UNUR_DISTR* distribution}) 12601Get default parameters for generator. 12602@end deftypefn 12603@end ifnotinfo 12604 12605@ifinfo 12606@anchor{funct:unur_itdr_set_xi} 12607@deftypefn Function {int} unur_itdr_set_xi (UNUR_PAR* @var{parameters}, double @var{xi}) 12608Sets points where local concavity and inverse local concavity 12609are (almost) equal. It is used to estimate the respective c-values 12610for pole region and hat regions and to determine the splitting point @i{bx} 12611between pole and tail region. 12612If no such point is provided it will be computed automatically. 12613 12614Default: not set. 12615@end deftypefn 12616@end ifinfo 12617@ifnotinfo 12618@anchor{funct:unur_itdr_set_xi} 12619@deftypefn {} {int} unur_itdr_set_xi (UNUR_PAR* @var{parameters}, double @var{xi}) 12620Sets points where local concavity and inverse local concavity 12621are (almost) equal. It is used to estimate the respective c-values 12622for pole region and hat regions and to determine the splitting point @i{bx} 12623between pole and tail region. 12624If no such point is provided it will be computed automatically. 12625 12626Default: not set. 12627@end deftypefn 12628@end ifnotinfo 12629 12630@ifinfo 12631@anchor{funct:unur_itdr_set_cp} 12632@deftypefn Function {int} unur_itdr_set_cp (UNUR_PAR* @var{parameters}, double @var{cp}) 12633Sets parameter @var{cp} for transformation T for inverse 12634density in pole region. 12635It must be at most 0 and greater than -1. 12636A value of @code{-0.5} is treated separately and usually results in 12637faster marginal generation time (at the expense of smaller 12638acceptance probabilities. 12639If no @var{cp}-value is given it is estimated automatically. 12640 12641Default: not set. 12642@end deftypefn 12643@end ifinfo 12644@ifnotinfo 12645@anchor{funct:unur_itdr_set_cp} 12646@deftypefn {} {int} unur_itdr_set_cp (UNUR_PAR* @var{parameters}, double @var{cp}) 12647Sets parameter @var{cp} for transformation T for inverse 12648density in pole region. 12649It must be at most 0 and greater than -1. 12650A value of @code{-0.5} is treated separately and usually results in 12651faster marginal generation time (at the expense of smaller 12652acceptance probabilities. 12653If no @var{cp}-value is given it is estimated automatically. 12654 12655Default: not set. 12656@end deftypefn 12657@end ifnotinfo 12658 12659@ifinfo 12660@anchor{funct:unur_itdr_set_ct} 12661@deftypefn Function {int} unur_itdr_set_ct (UNUR_PAR* @var{parameters}, double @var{ct}) 12662Sets parameter @var{ct} for transformation T for 12663density in tail region. 12664It must be at most 0. For densities with unbounded domain 12665it must be greater than -1. 12666A value of @code{-0.5} is treated separately and usually results in 12667faster marginal generation time (at the expense of smaller 12668acceptance probabilities. 12669If no @var{ct}-value is given it is estimated automatically. 12670 12671Default: not set. 12672@end deftypefn 12673@end ifinfo 12674@ifnotinfo 12675@anchor{funct:unur_itdr_set_ct} 12676@deftypefn {} {int} unur_itdr_set_ct (UNUR_PAR* @var{parameters}, double @var{ct}) 12677Sets parameter @var{ct} for transformation T for 12678density in tail region. 12679It must be at most 0. For densities with unbounded domain 12680it must be greater than -1. 12681A value of @code{-0.5} is treated separately and usually results in 12682faster marginal generation time (at the expense of smaller 12683acceptance probabilities. 12684If no @var{ct}-value is given it is estimated automatically. 12685 12686Default: not set. 12687@end deftypefn 12688@end ifnotinfo 12689 12690@ifinfo 12691@anchor{funct:unur_itdr_get_xi} 12692@deftypefn Function {double} unur_itdr_get_xi (UNUR_GEN* @var{generator}) 12693@anchor{funct:unur_itdr_get_cp} 12694@deftypefnx Function {double} unur_itdr_get_cp (UNUR_GEN* @var{generator}) 12695@anchor{funct:unur_itdr_get_ct} 12696@deftypefnx Function {double} unur_itdr_get_ct (UNUR_GEN* @var{generator}) 12697Get intersection point @var{xi}, and c-values @var{cp} and @var{ct}, 12698respectively. 12699(In case of an error @code{UNUR_INFINITY} is returned.) 12700@end deftypefn 12701@end ifinfo 12702@ifnotinfo 12703@anchor{funct:unur_itdr_get_xi} 12704@deftypefn {} {double} unur_itdr_get_xi (UNUR_GEN* @var{generator}) 12705@anchor{funct:unur_itdr_get_cp} 12706@deftypefnx {} {double} unur_itdr_get_cp (UNUR_GEN* @var{generator}) 12707@anchor{funct:unur_itdr_get_ct} 12708@deftypefnx {} {double} unur_itdr_get_ct (UNUR_GEN* @var{generator}) 12709Get intersection point @var{xi}, and c-values @var{cp} and @var{ct}, 12710respectively. 12711(In case of an error @code{UNUR_INFINITY} is returned.) 12712@end deftypefn 12713@end ifnotinfo 12714 12715@ifinfo 12716@anchor{funct:unur_itdr_get_area} 12717@deftypefn Function {double} unur_itdr_get_area (UNUR_GEN* @var{generator}) 12718Get area below hat. 12719(In case of an error @code{UNUR_INFINITY} is returned.) 12720@end deftypefn 12721@end ifinfo 12722@ifnotinfo 12723@anchor{funct:unur_itdr_get_area} 12724@deftypefn {} {double} unur_itdr_get_area (UNUR_GEN* @var{generator}) 12725Get area below hat. 12726(In case of an error @code{UNUR_INFINITY} is returned.) 12727@end deftypefn 12728@end ifnotinfo 12729 12730@ifinfo 12731@anchor{funct:unur_itdr_set_verify} 12732@deftypefn Function {int} unur_itdr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 12733Turn verifying of algorithm while sampling on/off. 12734 12735If the condition 12736@math{PDF(x) <= hat(x)} 12737is 12738violated for some @i{x} then @code{unur_errno} is set to 12739@code{UNUR_ERR_GEN_CONDITION}. However, notice that this might 12740happen due to round-off errors for a few values of 12741@i{x} (less than 1%). 12742 12743Default is @code{FALSE}. 12744@end deftypefn 12745@end ifinfo 12746@ifnotinfo 12747@anchor{funct:unur_itdr_set_verify} 12748@deftypefn {} {int} unur_itdr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 12749Turn verifying of algorithm while sampling on/off. 12750 12751If the condition 12752@iftex 12753@math{PDF(x) \leq hat(x)} 12754@end iftex 12755@ifhtml 12756@html 12757<I>PDF</I>(<I>x</I>) <= <I>hat</I>(<I>x</I>) 12758@end html 12759@end ifhtml 12760is 12761violated for some @i{x} then @code{unur_errno} is set to 12762@code{UNUR_ERR_GEN_CONDITION}. However, notice that this might 12763happen due to round-off errors for a few values of 12764@i{x} (less than 1%). 12765 12766Default is @code{FALSE}. 12767@end deftypefn 12768@end ifnotinfo 12769 12770@ifinfo 12771@anchor{funct:unur_itdr_chg_verify} 12772@deftypefn Function {int} unur_itdr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 12773Change the verifying of algorithm while sampling on/off. 12774@end deftypefn 12775@end ifinfo 12776@ifnotinfo 12777@anchor{funct:unur_itdr_chg_verify} 12778@deftypefn {} {int} unur_itdr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 12779Change the verifying of algorithm while sampling on/off. 12780@end deftypefn 12781@end ifnotinfo 12782 12783 12784 12785 12786@c 12787@c end of itdr.h 12788@c ------------------------------------- 12789@c ------------------------------------- 12790@c ninv.h 12791@c 12792 12793@page 12794@node NINV 12795@subsection NINV -- Numerical INVersion 12796 12797@table @i 12798@item Required: 12799CDF 12800@item Optional: 12801PDF 12802@item Speed: 12803Set-up: optional, Sampling: (very) slow 12804@item Reinit: 12805supported 12806@end table 12807@sp 1 12808 12809 12810NINV implementations of some methods for numerical inversion: 12811Newton's method, regula falsi (combined with interval 12812bisectioning), and bisection method. 12813Regula falsi and bisection method require only the CDF while 12814Newton's method also requires the PDF. 12815To speed up marginal generation times a table with suitable 12816starting points can be created during the setup. 12817The performance of the algorithm can adjusted by the desired 12818accuracy of the method. 12819It is possible to use this method for generating from truncated 12820distributions. The truncated domain can be changed for an 12821existing generator object. 12822 12823 12824@subsubheading How To Use 12825 12826 12827Method NINV generates random variates by numerical 12828inversion and requires a continuous univariate distribution 12829objects with given CDF. Three variants are available: 12830 12831@itemize @minus 12832@item Regula falsi [default] 12833@item Newton's method 12834@item Interval bisectioning 12835@end itemize 12836 12837Newton's method additionally requires the PDF of the 12838distribution and cannot be used otherwise (NINV automatically 12839switches to regula falsi then). 12840Default algorithm is regula falsi. It is slightly slower but 12841numerically much more stable than Newton's algorithm. 12842Interval bisectioning is the slowest method and should only be 12843considered as a last resort when the other methods fails. 12844 12845It is possible to draw samples from truncated distributions. 12846The truncated domain can even be changed for an existing generator 12847object by an 12848@ifhtml 12849@ref{funct:unur_ninv_chg_truncated,@command{unur_ninv_chg_truncated}} 12850@end ifhtml 12851@ifnothtml 12852@command{unur_ninv_chg_truncated} 12853@end ifnothtml 12854call. 12855 12856Marginal generation times can be sped up by means of a table 12857with suitable starting points which can be created during the 12858setup. Using such a table can be switched on by means of a 12859@ifhtml 12860@ref{funct:unur_ninv_set_table,@command{unur_ninv_set_table}} 12861@end ifhtml 12862@ifnothtml 12863@command{unur_ninv_set_table} 12864@end ifnothtml 12865call where the table size is given as a 12866parameter. The table is still useful when the (truncated) domain 12867is changed often, since it is computed for the 12868domain of the given distribution. (It is not possible to enlarge 12869this domain.) If it is necessary to recalculate the table during 12870sampling, the command 12871@ifhtml 12872@ref{funct:unur_ninv_chg_table,@command{unur_ninv_chg_table}} 12873@end ifhtml 12874@ifnothtml 12875@command{unur_ninv_chg_table} 12876@end ifnothtml 12877can be used. 12878As a rule of thumb using such a table is appropriate when the 12879number of generated points exceeds the table size by a factor of 12880100. 12881 12882The default number of iterations of NINV should be enough for all 12883reasonable cases. Nevertheless, it is possible to adjust the maximal 12884number of iterations with the commands 12885@ifhtml 12886@ref{funct:unur_ninv_set_max_iter,@command{unur_ninv_set_max_iter}} 12887@end ifhtml 12888@ifnothtml 12889@command{unur_ninv_set_max_iter} 12890@end ifnothtml 12891and 12892@ifhtml 12893@ref{funct:unur_ninv_chg_max_iter,@command{unur_ninv_chg_max_iter}.} 12894@end ifhtml 12895@ifnothtml 12896@command{unur_ninv_chg_max_iter}. 12897@end ifnothtml 12898In particular this might be necessary when the PDF has a pole or 12899the distribution has extremely heavy tails. 12900 12901It is also possible to set/change the accuracy of the method 12902(which also heavily influencies the generation time). 12903We use two measures for the approximation error which can be 12904used independently: x-error and u-error 12905(@pxref{Inversion} for more details). 12906It is possible to set the maximal tolerated error using 12907with 12908@ifhtml 12909@ref{funct:unur_ninv_set_x_resolution,@command{unur_ninv_set_x_resolution}} 12910@end ifhtml 12911@ifnothtml 12912@command{unur_ninv_set_x_resolution} 12913@end ifnothtml 12914and 12915with 12916@ifhtml 12917@ref{funct:unur_ninv_set_u_resolution,@command{unur_ninv_set_u_resolution},} 12918@end ifhtml 12919@ifnothtml 12920@command{unur_ninv_set_u_resolution}, 12921@end ifnothtml 12922resp., and change it with the 12923respective calls 12924@ifhtml 12925@ref{funct:unur_ninv_chg_x_resolution,@command{unur_ninv_chg_x_resolution}} 12926@end ifhtml 12927@ifnothtml 12928@command{unur_ninv_chg_x_resolution} 12929@end ifnothtml 12930and 12931@ifhtml 12932@ref{funct:unur_ninv_chg_x_resolution,@command{unur_ninv_chg_x_resolution}.} 12933@end ifhtml 12934@ifnothtml 12935@command{unur_ninv_chg_x_resolution}. 12936@end ifnothtml 12937The algorithm tries to satisfy @emph{both} accuracy goals (and 12938raises an error flag it this fails). 12939One of these accuracy checks can be disabled by setting the 12940accuracy goal to a negative value. 12941 12942NINV tries to use proper starting values for both the regula 12943falsi and bisection method, and for Newton's method. Of course 12944the user might have more knowledge about the properties of the 12945target distribution and is able to share his wisdom with NINV 12946using the respective commands 12947@ifhtml 12948@ref{funct:unur_ninv_set_start,@command{unur_ninv_set_start}} 12949@end ifhtml 12950@ifnothtml 12951@command{unur_ninv_set_start} 12952@end ifnothtml 12953and 12954@ifhtml 12955@ref{funct:unur_ninv_chg_start,@command{unur_ninv_chg_start}.} 12956@end ifhtml 12957@ifnothtml 12958@command{unur_ninv_chg_start}. 12959@end ifnothtml 12960It is possible to change the parameters and the domain of the chosen 12961distribution and run 12962@ifhtml 12963@ref{funct:unur_reinit,@command{unur_reinit}} 12964@end ifhtml 12965@ifnothtml 12966@command{unur_reinit} 12967@end ifnothtml 12968to reinitialize the generator object. 12969The values given by the last 12970@ifhtml 12971@ref{funct:unur_ninv_chg_truncated,@command{unur_ninv_chg_truncated}} 12972@end ifhtml 12973@ifnothtml 12974@command{unur_ninv_chg_truncated} 12975@end ifnothtml 12976call will be 12977then changed to the values of the domain of the underlying distribution 12978object. It is important to note that for a distribution from the 12979UNU.RAN library of standard distributions 12980(@pxref{Stddist,,Standard distributions}) 12981the normalization constant has to be updated using the 12982@ifhtml 12983@ref{funct:unur_distr_cont_upd_pdfarea,@command{unur_distr_cont_upd_pdfarea}} 12984@end ifhtml 12985@ifnothtml 12986@command{unur_distr_cont_upd_pdfarea} 12987@end ifnothtml 12988call whenever its parameters have been 12989changed by means of a 12990@ifhtml 12991@ref{funct:unur_distr_cont_set_pdfparams,@command{unur_distr_cont_set_pdfparams}} 12992@end ifhtml 12993@ifnothtml 12994@command{unur_distr_cont_set_pdfparams} 12995@end ifnothtml 12996call. 12997 12998It might happen that NINV aborts 12999@ifhtml 13000@ref{funct:unur_sample_cont,@command{unur_sample_cont}} 13001@end ifhtml 13002@ifnothtml 13003@command{unur_sample_cont} 13004@end ifnothtml 13005without 13006computing the correct value (because the maximal number 13007iterations has been exceeded). Then the last approximate value 13008for @i{x} is returned (with might be fairly false) and 13009@code{unur_error} is set to @code{UNUR_ERR_GEN_SAMPLING}. 13010 13011 13012 13013 13014@subheading Function reference 13015 13016@ifhtml 13017@itemize 13018@item @ref{funct:unur_ninv_new,unur_ninv_new} 13019@item @ref{funct:unur_ninv_set_useregula,unur_ninv_set_useregula} 13020@item @ref{funct:unur_ninv_set_usenewton,unur_ninv_set_usenewton} 13021@item @ref{funct:unur_ninv_set_usebisect,unur_ninv_set_usebisect} 13022@item @ref{funct:unur_ninv_set_max_iter,unur_ninv_set_max_iter} 13023@item @ref{funct:unur_ninv_chg_max_iter,unur_ninv_chg_max_iter} 13024@item @ref{funct:unur_ninv_set_x_resolution,unur_ninv_set_x_resolution} 13025@item @ref{funct:unur_ninv_chg_x_resolution,unur_ninv_chg_x_resolution} 13026@item @ref{funct:unur_ninv_set_u_resolution,unur_ninv_set_u_resolution} 13027@item @ref{funct:unur_ninv_chg_u_resolution,unur_ninv_chg_u_resolution} 13028@item @ref{funct:unur_ninv_set_start,unur_ninv_set_start} 13029@item @ref{funct:unur_ninv_chg_start,unur_ninv_chg_start} 13030@item @ref{funct:unur_ninv_set_table,unur_ninv_set_table} 13031@item @ref{funct:unur_ninv_chg_table,unur_ninv_chg_table} 13032@item @ref{funct:unur_ninv_chg_truncated,unur_ninv_chg_truncated} 13033@item @ref{funct:unur_ninv_eval_approxinvcdf,unur_ninv_eval_approxinvcdf} 13034@end itemize 13035@end ifhtml 13036 13037 13038@ifinfo 13039@anchor{funct:unur_ninv_new} 13040@deftypefn Function {UNUR_PAR*} unur_ninv_new (const @var{UNUR_DISTR* distribution}) 13041Get default parameters for generator. 13042@end deftypefn 13043@end ifinfo 13044@ifnotinfo 13045@anchor{funct:unur_ninv_new} 13046@deftypefn {} {UNUR_PAR*} unur_ninv_new (const @var{UNUR_DISTR* distribution}) 13047Get default parameters for generator. 13048@end deftypefn 13049@end ifnotinfo 13050 13051@ifinfo 13052@anchor{funct:unur_ninv_set_useregula} 13053@deftypefn Function {int} unur_ninv_set_useregula (UNUR_PAR* @var{parameters}) 13054Switch to regula falsi combined with interval bisectioning. 13055(This the default.) 13056@end deftypefn 13057@end ifinfo 13058@ifnotinfo 13059@anchor{funct:unur_ninv_set_useregula} 13060@deftypefn {} {int} unur_ninv_set_useregula (UNUR_PAR* @var{parameters}) 13061Switch to regula falsi combined with interval bisectioning. 13062(This the default.) 13063@end deftypefn 13064@end ifnotinfo 13065 13066@ifinfo 13067@anchor{funct:unur_ninv_set_usenewton} 13068@deftypefn Function {int} unur_ninv_set_usenewton (UNUR_PAR* @var{parameters}) 13069Switch to Newton's method. 13070Notice that it is numerically less stable than regula falsi. 13071It it is not possible to invert the CDF for a particular uniform random 13072number @i{U} when calling 13073@ifhtml 13074@ref{funct:unur_sample_cont,@command{unur_sample_cont},} 13075@end ifhtml 13076@ifnothtml 13077@command{unur_sample_cont}, 13078@end ifnothtml 13079@code{unur_error} is set 13080to @code{UNUR_ERR_GEN_SAMPLING}. 13081Thus it is recommended to check @code{unur_error} before 13082using the result of the sampling routine. 13083@end deftypefn 13084@end ifinfo 13085@ifnotinfo 13086@anchor{funct:unur_ninv_set_usenewton} 13087@deftypefn {} {int} unur_ninv_set_usenewton (UNUR_PAR* @var{parameters}) 13088Switch to Newton's method. 13089Notice that it is numerically less stable than regula falsi. 13090It it is not possible to invert the CDF for a particular uniform random 13091number @i{U} when calling 13092@ifhtml 13093@ref{funct:unur_sample_cont,@command{unur_sample_cont},} 13094@end ifhtml 13095@ifnothtml 13096@command{unur_sample_cont}, 13097@end ifnothtml 13098@code{unur_error} is set 13099to @code{UNUR_ERR_GEN_SAMPLING}. 13100Thus it is recommended to check @code{unur_error} before 13101using the result of the sampling routine. 13102@end deftypefn 13103@end ifnotinfo 13104 13105@ifinfo 13106@anchor{funct:unur_ninv_set_usebisect} 13107@deftypefn Function {int} unur_ninv_set_usebisect (UNUR_PAR* @var{parameters}) 13108Switch to bisection method. This is a slow algorithm and should 13109only be used as a last resort. 13110@end deftypefn 13111@end ifinfo 13112@ifnotinfo 13113@anchor{funct:unur_ninv_set_usebisect} 13114@deftypefn {} {int} unur_ninv_set_usebisect (UNUR_PAR* @var{parameters}) 13115Switch to bisection method. This is a slow algorithm and should 13116only be used as a last resort. 13117@end deftypefn 13118@end ifnotinfo 13119 13120@ifinfo 13121@anchor{funct:unur_ninv_set_max_iter} 13122@deftypefn Function {int} unur_ninv_set_max_iter (UNUR_PAR* @var{parameters}, int @var{max_iter}) 13123@anchor{funct:unur_ninv_chg_max_iter} 13124@deftypefnx Function {int} unur_ninv_chg_max_iter (UNUR_GEN* @var{generator}, int @var{max_iter}) 13125Set and change number of maximal iterations. 13126Default is @code{100}. 13127@end deftypefn 13128@end ifinfo 13129@ifnotinfo 13130@anchor{funct:unur_ninv_set_max_iter} 13131@deftypefn {} {int} unur_ninv_set_max_iter (UNUR_PAR* @var{parameters}, int @var{max_iter}) 13132@anchor{funct:unur_ninv_chg_max_iter} 13133@deftypefnx {} {int} unur_ninv_chg_max_iter (UNUR_GEN* @var{generator}, int @var{max_iter}) 13134Set and change number of maximal iterations. 13135Default is @code{100}. 13136@end deftypefn 13137@end ifnotinfo 13138 13139@ifinfo 13140@anchor{funct:unur_ninv_set_x_resolution} 13141@deftypefn Function {int} unur_ninv_set_x_resolution (UNUR_PAR* @var{parameters}, double @var{x_resolution}) 13142@anchor{funct:unur_ninv_chg_x_resolution} 13143@deftypefnx Function {int} unur_ninv_chg_x_resolution (UNUR_GEN* @var{generator}, double @var{x_resolution}) 13144Set and change the maximal tolerated relative x-error. 13145If @var{x_resolution} is negative then checking of the x-error is 13146disabled. 13147 13148Default is @code{1.e-8}. 13149@end deftypefn 13150@end ifinfo 13151@ifnotinfo 13152@anchor{funct:unur_ninv_set_x_resolution} 13153@deftypefn {} {int} unur_ninv_set_x_resolution (UNUR_PAR* @var{parameters}, double @var{x_resolution}) 13154@anchor{funct:unur_ninv_chg_x_resolution} 13155@deftypefnx {} {int} unur_ninv_chg_x_resolution (UNUR_GEN* @var{generator}, double @var{x_resolution}) 13156Set and change the maximal tolerated relative x-error. 13157If @var{x_resolution} is negative then checking of the x-error is 13158disabled. 13159 13160Default is @code{1.e-8}. 13161@end deftypefn 13162@end ifnotinfo 13163 13164@ifinfo 13165@anchor{funct:unur_ninv_set_u_resolution} 13166@deftypefn Function {int} unur_ninv_set_u_resolution (UNUR_PAR* @var{parameters}, double @var{u_resolution}) 13167@anchor{funct:unur_ninv_chg_u_resolution} 13168@deftypefnx Function {int} unur_ninv_chg_u_resolution (UNUR_GEN* @var{generator}, double @var{u_resolution}) 13169Set and change the maximal tolerated (abolute) u-error. 13170If @var{u_resolution} is negative then checking of the u-error is 13171disabled. 13172 13173Default is @code{-1} (disabled). 13174@end deftypefn 13175@end ifinfo 13176@ifnotinfo 13177@anchor{funct:unur_ninv_set_u_resolution} 13178@deftypefn {} {int} unur_ninv_set_u_resolution (UNUR_PAR* @var{parameters}, double @var{u_resolution}) 13179@anchor{funct:unur_ninv_chg_u_resolution} 13180@deftypefnx {} {int} unur_ninv_chg_u_resolution (UNUR_GEN* @var{generator}, double @var{u_resolution}) 13181Set and change the maximal tolerated (abolute) u-error. 13182If @var{u_resolution} is negative then checking of the u-error is 13183disabled. 13184 13185Default is @code{-1} (disabled). 13186@end deftypefn 13187@end ifnotinfo 13188 13189@ifinfo 13190@anchor{funct:unur_ninv_set_start} 13191@deftypefn Function {int} unur_ninv_set_start (UNUR_PAR* @var{parameters}, double @var{left}, double @var{right}) 13192Set starting points. 13193If not set, suitable values are chosen automatically. 13194 13195@multitable @columnfractions 0.2 0.2 0.6 13196@item Newton: @tab @var{left}: @tab starting point 13197@item Regula falsi: @tab @var{left}, @var{right}: @tab boundary of starting interval 13198@end multitable 13199 13200If the starting points are not set then the follwing points are used by 13201default: 13202@multitable @columnfractions 0.2 0.2 0.6 13203@item Newton: @tab @var{left}: @tab CDF(@var{left}) = 0.5 13204@item Regula falsi: @tab @var{left}: @tab CDF(@var{left}) = 0.1 13205@item @tab @var{right}: @tab CDF(@var{right}) = 0.9 13206@end multitable 13207 13208If @var{left} == @var{right}, then UNU.RAN always uses the default 13209starting points! 13210@end deftypefn 13211@end ifinfo 13212@ifnotinfo 13213@anchor{funct:unur_ninv_set_start} 13214@deftypefn {} {int} unur_ninv_set_start (UNUR_PAR* @var{parameters}, double @var{left}, double @var{right}) 13215Set starting points. 13216If not set, suitable values are chosen automatically. 13217 13218@multitable @columnfractions 0.2 0.2 0.6 13219@item Newton: @tab @var{left}: @tab starting point 13220@item Regula falsi: @tab @var{left}, @var{right}: @tab boundary of starting interval 13221@end multitable 13222 13223If the starting points are not set then the follwing points are used by 13224default: 13225@multitable @columnfractions 0.2 0.2 0.6 13226@item Newton: @tab @var{left}: @tab CDF(@var{left}) = 0.5 13227@item Regula falsi: @tab @var{left}: @tab CDF(@var{left}) = 0.1 13228@item @tab @var{right}: @tab CDF(@var{right}) = 0.9 13229@end multitable 13230 13231If @var{left} == @var{right}, then UNU.RAN always uses the default 13232starting points! 13233@end deftypefn 13234@end ifnotinfo 13235 13236@ifinfo 13237@anchor{funct:unur_ninv_chg_start} 13238@deftypefn Function {int} unur_ninv_chg_start (UNUR_GEN* @var{gen}, double @var{left}, double @var{right}) 13239Change the starting points for numerical inversion. 13240If left==right, then UNU.RAN uses the default starting points 13241(see 13242@ifhtml 13243@ref{funct:unur_ninv_set_start,@command{unur_ninv_set_start}} 13244@end ifhtml 13245@ifnothtml 13246@command{unur_ninv_set_start} 13247@end ifnothtml 13248). 13249@end deftypefn 13250@end ifinfo 13251@ifnotinfo 13252@anchor{funct:unur_ninv_chg_start} 13253@deftypefn {} {int} unur_ninv_chg_start (UNUR_GEN* @var{gen}, double @var{left}, double @var{right}) 13254Change the starting points for numerical inversion. 13255If left==right, then UNU.RAN uses the default starting points 13256(see 13257@ifhtml 13258@ref{funct:unur_ninv_set_start,@command{unur_ninv_set_start}} 13259@end ifhtml 13260@ifnothtml 13261@command{unur_ninv_set_start} 13262@end ifnothtml 13263). 13264@end deftypefn 13265@end ifnotinfo 13266 13267@ifinfo 13268@anchor{funct:unur_ninv_set_table} 13269@deftypefn Function {int} unur_ninv_set_table (UNUR_PAR* @var{parameters}, int @var{no_of_points}) 13270Generates a table with @var{no_of_points} points containing 13271suitable starting values for the iteration. The value of 13272@var{no_of_points} must be at least 10 (otherwise it will be set 13273to 10 automatically). 13274 13275The table points are chosen such that the CDF at these points 13276form an equidistance sequence in the interval (0,1). 13277 13278If a table is used, then the starting points given by 13279@ifhtml 13280@ref{funct:unur_ninv_set_start,@command{unur_ninv_set_start}} 13281@end ifhtml 13282@ifnothtml 13283@command{unur_ninv_set_start} 13284@end ifnothtml 13285are ignored. 13286 13287No table is used by default. 13288@end deftypefn 13289@end ifinfo 13290@ifnotinfo 13291@anchor{funct:unur_ninv_set_table} 13292@deftypefn {} {int} unur_ninv_set_table (UNUR_PAR* @var{parameters}, int @var{no_of_points}) 13293Generates a table with @var{no_of_points} points containing 13294suitable starting values for the iteration. The value of 13295@var{no_of_points} must be at least 10 (otherwise it will be set 13296to 10 automatically). 13297 13298The table points are chosen such that the CDF at these points 13299form an equidistance sequence in the interval (0,1). 13300 13301If a table is used, then the starting points given by 13302@ifhtml 13303@ref{funct:unur_ninv_set_start,@command{unur_ninv_set_start}} 13304@end ifhtml 13305@ifnothtml 13306@command{unur_ninv_set_start} 13307@end ifnothtml 13308are ignored. 13309 13310No table is used by default. 13311@end deftypefn 13312@end ifnotinfo 13313 13314@ifinfo 13315@anchor{funct:unur_ninv_chg_table} 13316@deftypefn Function {int} unur_ninv_chg_table (UNUR_GEN* @var{gen}, int @var{no_of_points}) 13317Recomputes a table as described in 13318@ifhtml 13319@ref{funct:unur_ninv_set_table,@command{unur_ninv_set_table}.} 13320@end ifhtml 13321@ifnothtml 13322@command{unur_ninv_set_table}. 13323@end ifnothtml 13324@end deftypefn 13325@end ifinfo 13326@ifnotinfo 13327@anchor{funct:unur_ninv_chg_table} 13328@deftypefn {} {int} unur_ninv_chg_table (UNUR_GEN* @var{gen}, int @var{no_of_points}) 13329Recomputes a table as described in 13330@ifhtml 13331@ref{funct:unur_ninv_set_table,@command{unur_ninv_set_table}.} 13332@end ifhtml 13333@ifnothtml 13334@command{unur_ninv_set_table}. 13335@end ifnothtml 13336@end deftypefn 13337@end ifnotinfo 13338 13339@ifinfo 13340@anchor{funct:unur_ninv_chg_truncated} 13341@deftypefn Function {int} unur_ninv_chg_truncated (UNUR_GEN* @var{gen}, double @var{left}, double @var{right}) 13342Changes the borders of the domain of the (truncated) distribution. 13343 13344Notice that the given truncated domain must be a subset of the 13345domain of the given distribution. The generator always uses the 13346intersection of the domain of the distribution and the truncated 13347domain given by this call. 13348Moreover the starting point(s) will not be changed. 13349 13350@emph{Important:} If the CDF is (almost) the same for @var{left} and 13351@var{right} and (almost) equal to @code{0} or @code{1}, then the truncated 13352domain is @emph{not} chanced and the call returns an error code. 13353 13354@emph{Notice:} If the parameters of the distribution has been changed by a 13355@ifhtml 13356@ref{funct:unur_distr_cont_set_pdfparams,@command{unur_distr_cont_set_pdfparams}} 13357@end ifhtml 13358@ifnothtml 13359@command{unur_distr_cont_set_pdfparams} 13360@end ifnothtml 13361call it is recommended to set the 13362truncated domain again, since the former call might change the 13363domain of the distribution but not update the values for the 13364boundaries of the truncated distribution. 13365@end deftypefn 13366@end ifinfo 13367@ifnotinfo 13368@anchor{funct:unur_ninv_chg_truncated} 13369@deftypefn {} {int} unur_ninv_chg_truncated (UNUR_GEN* @var{gen}, double @var{left}, double @var{right}) 13370Changes the borders of the domain of the (truncated) distribution. 13371 13372Notice that the given truncated domain must be a subset of the 13373domain of the given distribution. The generator always uses the 13374intersection of the domain of the distribution and the truncated 13375domain given by this call. 13376Moreover the starting point(s) will not be changed. 13377 13378@emph{Important:} If the CDF is (almost) the same for @var{left} and 13379@var{right} and (almost) equal to @code{0} or @code{1}, then the truncated 13380domain is @emph{not} chanced and the call returns an error code. 13381 13382@emph{Notice:} If the parameters of the distribution has been changed by a 13383@ifhtml 13384@ref{funct:unur_distr_cont_set_pdfparams,@command{unur_distr_cont_set_pdfparams}} 13385@end ifhtml 13386@ifnothtml 13387@command{unur_distr_cont_set_pdfparams} 13388@end ifnothtml 13389call it is recommended to set the 13390truncated domain again, since the former call might change the 13391domain of the distribution but not update the values for the 13392boundaries of the truncated distribution. 13393@end deftypefn 13394@end ifnotinfo 13395 13396@ifinfo 13397@anchor{funct:unur_ninv_eval_approxinvcdf} 13398@deftypefn Function {double} unur_ninv_eval_approxinvcdf (const @var{UNUR_GEN* generator}, double @var{u}) 13399Get approximate approximate value of inverse CDF at @var{u}. 13400If @var{u} is out of the domain [0,1] then @code{unur_errno} is set 13401to @code{UNUR_ERR_DOMAIN} and the respective bound of 13402the domain of the distribution are returned (which is 13403@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 13404unbounded domains). 13405 13406@emph{Notice}: This function always evaluates the inverse CDF of 13407the given distribution. A call to 13408@ifhtml 13409@ref{funct:unur_ninv_chg_truncated,@command{unur_ninv_chg_truncated}} 13410@end ifhtml 13411@ifnothtml 13412@command{unur_ninv_chg_truncated} 13413@end ifnothtml 13414call 13415has no effect. 13416@end deftypefn 13417@end ifinfo 13418@ifnotinfo 13419@anchor{funct:unur_ninv_eval_approxinvcdf} 13420@deftypefn {} {double} unur_ninv_eval_approxinvcdf (const @var{UNUR_GEN* generator}, double @var{u}) 13421Get approximate approximate value of inverse CDF at @var{u}. 13422If @var{u} is out of the domain [0,1] then @code{unur_errno} is set 13423to @code{UNUR_ERR_DOMAIN} and the respective bound of 13424the domain of the distribution are returned (which is 13425@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 13426unbounded domains). 13427 13428@emph{Notice}: This function always evaluates the inverse CDF of 13429the given distribution. A call to 13430@ifhtml 13431@ref{funct:unur_ninv_chg_truncated,@command{unur_ninv_chg_truncated}} 13432@end ifhtml 13433@ifnothtml 13434@command{unur_ninv_chg_truncated} 13435@end ifnothtml 13436call 13437has no effect. 13438@end deftypefn 13439@end ifnotinfo 13440 13441 13442 13443 13444@c 13445@c end of ninv.h 13446@c ------------------------------------- 13447@c ------------------------------------- 13448@c nrou.h 13449@c 13450 13451@page 13452@node NROU 13453@subsection NROU -- Naive Ratio-Of-Uniforms method 13454 13455@table @i 13456@item Required: 13457PDF 13458@item Optional: 13459mode, center, bounding rectangle for acceptance region 13460@item Speed: 13461Set-up: slow or fast, Sampling: moderate 13462@item Reinit: 13463supported 13464@item Reference: 13465@ifhtml 13466@ref{bib:HLD04,, [HLD04: Sect.2.4 and Sect.6.4]} 13467@end ifhtml 13468@ifnothtml 13469[HLD04: Sect.2.4 and Sect.6.4] 13470@end ifnothtml 13471 13472@end table 13473@sp 1 13474 13475 13476NROU is an implementation of the (generalized) ratio-of-uniforms 13477method which uses (minimal) bounding rectangles, see 13478@ref{Ratio-of-Uniforms}. It uses a positive control parameter 13479@i{r} for adjusting the algorithm to the given distribution to 13480improve performance and/or to make this method applicable. 13481Larger values of @i{r} increase the class of distributions 13482for which the method works at the expense of a higher rejection 13483constant. For computational reasons @i{r=1} should be used if 13484possible (this is the default). 13485Moreover, this implementation uses the center 13486@iftex 13487@math{\mu} 13488@end iftex 13489@ifhtml 13490@html 13491mu 13492@end html 13493@end ifhtml 13494@ifinfo 13495@math{mu} 13496@end ifinfo 13497of 13498the distribution (see 13499@ifhtml 13500@ref{funct:unur_distr_cont_get_center,@command{unur_distr_cont_get_center}} 13501@end ifhtml 13502@ifnothtml 13503@command{unur_distr_cont_get_center} 13504@end ifnothtml 13505for 13506details of its default values). 13507 13508For the special case with 13509@iftex 13510@math{r=1} 13511@end iftex 13512@ifhtml 13513@html 13514<I>r</I>=1 13515@end html 13516@end ifhtml 13517@ifinfo 13518@math{r=1} 13519@end ifinfo 13520the coordinates of the 13521minimal bounding rectangles are given by 13522@iftex 13523 13524@quotation 13525@math{ v^+ = \sup\limits_{x} \sqrt{PDF(x)}, \hfil\break u^- = \inf\limits_{x} (x-\mu) \sqrt{PDF(x)}, \hfil\break u^+ = \sup\limits_{x} (x-\mu) \sqrt{PDF(x)}, } 13526@end quotation 13527 13528@end iftex 13529@ifhtml 13530@quotation 13531@html 13532<I>v</I><SUP>+</SUP> = sup_<I>x</I> sqrt(<I>PDF</I>(<I>x</I>)), @*<I>u</I><SUP>-</SUP> = inf_<I>x</I> (<I>x</I>- mu) sqrt(<I>PDF</I>(<I>x</I>)), @*<I>u</I><SUP>+</SUP> = sup_<I>x</I> (<I>x</I>- mu) sqrt(<I>PDF</I>(<I>x</I>)), 13533@end html 13534@end quotation 13535@end ifhtml 13536@ifinfo 13537@quotation 13538@math{v^+ = sup_(x) sqrt(PDF(x)), @*u^- = inf_(x) (x- mu) sqrt(PDF(x)), @*u^+ = sup_(x) (x- mu) sqrt(PDF(x)),} 13539@end quotation 13540@end ifinfo 13541 13542@noindent 13543where 13544@iftex 13545@math{\mu} 13546@end iftex 13547@ifhtml 13548@html 13549mu 13550@end html 13551@end ifhtml 13552@ifinfo 13553@math{mu} 13554@end ifinfo 13555is the center of the distribution. 13556For other values of @i{r} we have 13557@iftex 13558 13559@quotation 13560@math{ v^+ = \sup\limits_{x} (PDF(x))^{1/(r+1)}, \hfil\break u^- = \inf\limits_{x} (x-\mu) (PDF(x))^{r/(r+1)}, \hfil\break u^+ = \sup\limits_{x} (x-\mu) (PDF(x))^{r/(r+1)}. } 13561@end quotation 13562 13563@end iftex 13564@ifhtml 13565@quotation 13566@html 13567<I>v</I><SUP>+</SUP> = sup_<I>x</I> (<I>PDF</I>(<I>x</I>))<SUP>1/(<I>r</I>+1)</SUP>, @*<I>u</I><SUP>-</SUP> = inf_<I>x</I> (<I>x</I>- mu) (<I>PDF</I>(<I>x</I>))<SUP><I>r</I>/(<I>r</I>+1)</SUP>, @*<I>u</I><SUP>+</SUP> = sup_<I>x</I> (<I>x</I>- mu) (<I>PDF</I>(<I>x</I>))<SUP><I>r</I>/(<I>r</I>+1)</SUP>. 13568@end html 13569@end quotation 13570@end ifhtml 13571@ifinfo 13572@quotation 13573@math{v^+ = sup_(x) (PDF(x))^(1/(r+1)), @*u^- = inf_(x) (x- mu) (PDF(x))^(r/(r+1)), @*u^+ = sup_(x) (x- mu) (PDF(x))^(r/(r+1)).} 13574@end quotation 13575@end ifinfo 13576 13577@noindent 13578These bounds can be given directly. Otherwise they are computed 13579automatically by means of a (slow) numerical routine. 13580Of course this routine can fail, especially when this rectangle 13581is not bounded. 13582 13583It is important to note that the algorithm works with 13584@iftex 13585@math{PDF(x-\mu)} 13586@end iftex 13587@ifhtml 13588@html 13589<I>PDF</I>(<I>x</I>- mu) 13590@end html 13591@end ifhtml 13592@ifinfo 13593@math{PDF(x- mu)} 13594@end ifinfo 13595instead of 13596@iftex 13597@math{PDF(x).} 13598@end iftex 13599@ifhtml 13600@html 13601<I>PDF</I>(<I>x</I>). 13602@end html 13603@end ifhtml 13604@ifinfo 13605@math{PDF(x).} 13606@end ifinfo 13607This is important as otherwise the acceptance region can become 13608a very long and skinny ellipsoid along a diagonal of the (huge) 13609bounding rectangle. 13610 13611 13612@subsubheading How To Use 13613 13614 13615For using the NROU method UNU.RAN needs the PDF of the 13616distribution. Additionally, the parameter @i{r} can be set via 13617a 13618@ifhtml 13619@ref{funct:unur_vnrou_set_r,@command{unur_vnrou_set_r}} 13620@end ifhtml 13621@ifnothtml 13622@command{unur_vnrou_set_r} 13623@end ifnothtml 13624call. Notice that the acceptance 13625probability decreases when @i{r} is increased. On the other 13626hand is is more unlikely that the bounding rectangle does not 13627exist if @i{r} is small. 13628 13629A bounding rectangle can be given by the 13630@ifhtml 13631@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 13632@end ifhtml 13633@ifnothtml 13634@command{unur_vnrou_set_u} 13635@end ifnothtml 13636and 13637@ifhtml 13638@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 13639@end ifhtml 13640@ifnothtml 13641@command{unur_vnrou_set_v} 13642@end ifnothtml 13643calls. 13644 13645@emph{Important:} The bounding rectangle has to be 13646provided for the function 13647@iftex 13648@math{PDF(x-center)!} 13649@end iftex 13650@ifhtml 13651@html 13652<I>PDF</I>(<I>x</I>-<I>center</I>)! 13653@end html 13654@end ifhtml 13655@ifinfo 13656@math{PDF(x-center)!} 13657@end ifinfo 13658Notice that @code{center} is the center of the given 13659distribution, see 13660@ifhtml 13661@ref{funct:unur_distr_cont_set_center,@command{unur_distr_cont_set_center}.} 13662@end ifhtml 13663@ifnothtml 13664@command{unur_distr_cont_set_center}. 13665@end ifnothtml 13666If in doubt or if this value is not optimal, it can be changed 13667(overridden) by a 13668@ifhtml 13669@ref{funct:unur_nrou_set_center,@command{unur_nrou_set_center}} 13670@end ifhtml 13671@ifnothtml 13672@command{unur_nrou_set_center} 13673@end ifnothtml 13674call. 13675 13676If the coordinates of the bounding rectangle are not provided by 13677the user then the minimal bounding rectangle is computed 13678automatically. 13679 13680By means of 13681@ifhtml 13682@ref{funct:unur_vnrou_set_verify,@command{unur_vnrou_set_verify}} 13683@end ifhtml 13684@ifnothtml 13685@command{unur_vnrou_set_verify} 13686@end ifnothtml 13687and 13688@ifhtml 13689@ref{funct:unur_vnrou_chg_verify,@command{unur_vnrou_chg_verify}} 13690@end ifhtml 13691@ifnothtml 13692@command{unur_vnrou_chg_verify} 13693@end ifnothtml 13694one can run the sampling algorithm in a checking mode, i.e., in 13695every cycle of the rejection loop it is checked whether the used 13696rectangle indeed enclosed the acceptance region of the 13697distribution. When in doubt (e.g., when it is not clear whether 13698the numerical routine has worked correctly) this can be used to 13699run a small Monte Carlo study. 13700 13701It is possible to change the parameters and the domain of the chosen 13702distribution and run 13703@ifhtml 13704@ref{funct:unur_reinit,@command{unur_reinit}} 13705@end ifhtml 13706@ifnothtml 13707@command{unur_reinit} 13708@end ifnothtml 13709to reinitialize the generator object. 13710Notice, that derived parameters like the mode must also be (re-) set 13711if the parameters or the domain has be changed. 13712Notice, however, that then the values that has been set by 13713@ifhtml 13714@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 13715@end ifhtml 13716@ifnothtml 13717@command{unur_vnrou_set_u} 13718@end ifnothtml 13719and 13720@ifhtml 13721@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 13722@end ifhtml 13723@ifnothtml 13724@command{unur_vnrou_set_v} 13725@end ifnothtml 13726calls are removed and 13727the coordinates of the bounding box are computed numerically. 13728 13729 13730 13731 13732@subheading Function reference 13733 13734@ifhtml 13735@itemize 13736@item @ref{funct:unur_nrou_new,unur_nrou_new} 13737@item @ref{funct:unur_nrou_set_u,unur_nrou_set_u} 13738@item @ref{funct:unur_nrou_set_v,unur_nrou_set_v} 13739@item @ref{funct:unur_nrou_set_r,unur_nrou_set_r} 13740@item @ref{funct:unur_nrou_set_center,unur_nrou_set_center} 13741@item @ref{funct:unur_nrou_set_verify,unur_nrou_set_verify} 13742@item @ref{funct:unur_nrou_chg_verify,unur_nrou_chg_verify} 13743@end itemize 13744@end ifhtml 13745 13746 13747@ifinfo 13748@anchor{funct:unur_nrou_new} 13749@deftypefn Function {UNUR_PAR*} unur_nrou_new (const @var{UNUR_DISTR* distribution}) 13750Get default parameters for generator. 13751@end deftypefn 13752@end ifinfo 13753@ifnotinfo 13754@anchor{funct:unur_nrou_new} 13755@deftypefn {} {UNUR_PAR*} unur_nrou_new (const @var{UNUR_DISTR* distribution}) 13756Get default parameters for generator. 13757@end deftypefn 13758@end ifnotinfo 13759 13760@ifinfo 13761@anchor{funct:unur_nrou_set_u} 13762@deftypefn Function {int} unur_nrou_set_u (UNUR_PAR* @var{parameters}, double @var{umin}, double @var{umax}) 13763Sets left and right boundary of bounding rectangle. 13764If no values are given, the boundary of the minimal bounding 13765rectangle is computed numerically. 13766 13767@emph{Notice}: Computing the minimal bounding rectangle may fail 13768under some circumstances. Moreover, for multimodal distributions 13769the bounds might be too small as only local extrema are computed. 13770Nevertheless, for 13771@math{T_c} 13772-concave distributions with 13773@math{c=-1/2} 13774it should work. 13775 13776@emph{Important:} The bounding rectangle that has to be 13777provided is for the function 13778@math{PDF(x-center)!} 13779 13780Default: not set. 13781@end deftypefn 13782@end ifinfo 13783@ifnotinfo 13784@anchor{funct:unur_nrou_set_u} 13785@deftypefn {} {int} unur_nrou_set_u (UNUR_PAR* @var{parameters}, double @var{umin}, double @var{umax}) 13786Sets left and right boundary of bounding rectangle. 13787If no values are given, the boundary of the minimal bounding 13788rectangle is computed numerically. 13789 13790@emph{Notice}: Computing the minimal bounding rectangle may fail 13791under some circumstances. Moreover, for multimodal distributions 13792the bounds might be too small as only local extrema are computed. 13793Nevertheless, for 13794@iftex 13795@math{T_c} 13796@end iftex 13797@ifhtml 13798@html 13799<I>T</I>_<I>c</I> 13800@end html 13801@end ifhtml 13802-concave distributions with 13803@iftex 13804@math{c=-1/2} 13805@end iftex 13806@ifhtml 13807@html 13808<I>c</I>=-1/2 13809@end html 13810@end ifhtml 13811it should work. 13812 13813@emph{Important:} The bounding rectangle that has to be 13814provided is for the function 13815@iftex 13816@math{PDF(x-center)!} 13817@end iftex 13818@ifhtml 13819@html 13820<I>PDF</I>(<I>x</I>-<I>center</I>)! 13821@end html 13822@end ifhtml 13823 13824Default: not set. 13825@end deftypefn 13826@end ifnotinfo 13827 13828@ifinfo 13829@anchor{funct:unur_nrou_set_v} 13830@deftypefn Function {int} unur_nrou_set_v (UNUR_PAR* @var{parameters}, double @var{vmax}) 13831Set upper boundary for bounding rectangle. If this value is not 13832given then 13833@math{sqrt(PDF(mode))} 13834is used instead. 13835 13836@emph{Notice}: When the mode is not given for the distribution 13837object, then it will be computed numerically. 13838 13839Default: not set. 13840@end deftypefn 13841@end ifinfo 13842@ifnotinfo 13843@anchor{funct:unur_nrou_set_v} 13844@deftypefn {} {int} unur_nrou_set_v (UNUR_PAR* @var{parameters}, double @var{vmax}) 13845Set upper boundary for bounding rectangle. If this value is not 13846given then 13847@iftex 13848@math{\sqrt{PDF(mode)}} 13849@end iftex 13850@ifhtml 13851@html 13852sqrt(<I>PDF</I>(<I>mode</I>)) 13853@end html 13854@end ifhtml 13855is used instead. 13856 13857@emph{Notice}: When the mode is not given for the distribution 13858object, then it will be computed numerically. 13859 13860Default: not set. 13861@end deftypefn 13862@end ifnotinfo 13863 13864@ifinfo 13865@anchor{funct:unur_nrou_set_r} 13866@deftypefn Function {int} unur_nrou_set_r (UNUR_PAR* @var{parameters}, double @var{r}) 13867Sets the parameter @var{r} of the generalized ratio-of-uniforms 13868method. 13869 13870@emph{Notice}: This parameter must satisfy @var{r}>0. 13871 13872Default: @code{1}. 13873@end deftypefn 13874@end ifinfo 13875@ifnotinfo 13876@anchor{funct:unur_nrou_set_r} 13877@deftypefn {} {int} unur_nrou_set_r (UNUR_PAR* @var{parameters}, double @var{r}) 13878Sets the parameter @var{r} of the generalized ratio-of-uniforms 13879method. 13880 13881@emph{Notice}: This parameter must satisfy @var{r}>0. 13882 13883Default: @code{1}. 13884@end deftypefn 13885@end ifnotinfo 13886 13887@ifinfo 13888@anchor{funct:unur_nrou_set_center} 13889@deftypefn Function {int} unur_nrou_set_center (UNUR_PAR* @var{parameters}, double @var{center}) 13890Set the center (@math{mu} 13891) of the PDF. 13892If not set the center of the given distribution object is used. 13893 13894Default: see 13895@ifhtml 13896@ref{funct:unur_distr_cont_set_center,@command{unur_distr_cont_set_center}.} 13897@end ifhtml 13898@ifnothtml 13899@command{unur_distr_cont_set_center}. 13900@end ifnothtml 13901@end deftypefn 13902@end ifinfo 13903@ifnotinfo 13904@anchor{funct:unur_nrou_set_center} 13905@deftypefn {} {int} unur_nrou_set_center (UNUR_PAR* @var{parameters}, double @var{center}) 13906Set the center (@iftex 13907@math{\mu} 13908@end iftex 13909@ifhtml 13910@html 13911mu 13912@end html 13913@end ifhtml 13914) of the PDF. 13915If not set the center of the given distribution object is used. 13916 13917Default: see 13918@ifhtml 13919@ref{funct:unur_distr_cont_set_center,@command{unur_distr_cont_set_center}.} 13920@end ifhtml 13921@ifnothtml 13922@command{unur_distr_cont_set_center}. 13923@end ifnothtml 13924@end deftypefn 13925@end ifnotinfo 13926 13927@ifinfo 13928@anchor{funct:unur_nrou_set_verify} 13929@deftypefn Function {int} unur_nrou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 13930Turn verifying of algorithm while sampling on/off. 13931 13932If the condition 13933@math{PDF(x) <= hat(x)} 13934is 13935violated for some @i{x} then @code{unur_errno} is set to 13936@code{UNUR_ERR_GEN_CONDITION}. However, notice that this might 13937happen due to round-off errors for a few values of 13938@i{x} (less than 1%). 13939 13940Default is @code{FALSE}. 13941@end deftypefn 13942@end ifinfo 13943@ifnotinfo 13944@anchor{funct:unur_nrou_set_verify} 13945@deftypefn {} {int} unur_nrou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 13946Turn verifying of algorithm while sampling on/off. 13947 13948If the condition 13949@iftex 13950@math{PDF(x) \leq hat(x)} 13951@end iftex 13952@ifhtml 13953@html 13954<I>PDF</I>(<I>x</I>) <= <I>hat</I>(<I>x</I>) 13955@end html 13956@end ifhtml 13957is 13958violated for some @i{x} then @code{unur_errno} is set to 13959@code{UNUR_ERR_GEN_CONDITION}. However, notice that this might 13960happen due to round-off errors for a few values of 13961@i{x} (less than 1%). 13962 13963Default is @code{FALSE}. 13964@end deftypefn 13965@end ifnotinfo 13966 13967@ifinfo 13968@anchor{funct:unur_nrou_chg_verify} 13969@deftypefn Function {int} unur_nrou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 13970Change the verifying of algorithm while sampling on/off. 13971@end deftypefn 13972@end ifinfo 13973@ifnotinfo 13974@anchor{funct:unur_nrou_chg_verify} 13975@deftypefn {} {int} unur_nrou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 13976Change the verifying of algorithm while sampling on/off. 13977@end deftypefn 13978@end ifnotinfo 13979 13980 13981 13982 13983@c 13984@c end of nrou.h 13985@c ------------------------------------- 13986@c ------------------------------------- 13987@c pinv.h 13988@c 13989 13990@page 13991@node PINV 13992@subsection PINV -- Polynomial interpolation based INVersion of CDF 13993 13994@table @i 13995@item Required: 13996PDF 13997@item Optional: 13998domain, center, CDF, derivative of PDF 13999@item Speed: 14000Set-up: (very) slow, Sampling: (very) fast 14001@item Reinit: 14002not implemented 14003@item Reference: 14004@ifhtml 14005@ref{bib:DHLa08,, [DHLa08]} 14006@end ifhtml 14007@ifnothtml 14008[DHLa08] 14009@end ifnothtml 14010 14011@end table 14012@sp 1 14013 14014 14015PINV is a variant of numerical inversion, where the inverse CDF 14016is approximated using Newton's interpolating formula. 14017The interval [0,1] is split into several subintervals. In each 14018of these the inverse CDF is constructed at nodes 14019@iftex 14020@math{(CDF(x),x)} 14021@end iftex 14022@ifhtml 14023@html 14024(<I>CDF</I>(<I>x</I>),<I>x</I>) 14025@end html 14026@end ifhtml 14027@ifinfo 14028@math{(CDF(x),x)} 14029@end ifinfo 14030for some points @i{x} in this subinterval. 14031If the PDF is given, then the CDF is computed numerically 14032from the given PDF using adaptive Gauss-Lobatto 14033integration with 5 points. Subintervals are split until the 14034requested accuracy goal is reached. 14035 14036The method is not exact, as it only produces random variates of 14037the approximated distribution. Nevertheless, the maximal 14038tolerated approximation error can be set to be the resolution 14039(but of course is bounded by the machine precision). 14040We use the u-error 14041@iftex 14042@math{|U-CDF(X)|} 14043@end iftex 14044@ifhtml 14045@html 14046|<I>U</I>-<I>CDF</I>(<I>X</I>)| 14047@end html 14048@end ifhtml 14049@ifinfo 14050@math{|U-CDF(X)|} 14051@end ifinfo 14052to measure the error 14053for @i{X} = "approximate inverse CDF"(@i{U}). 14054Notice that very small values of the u-resolution are possible 14055but increase the cost for the setup step. 14056We call the maximal tolerated u-error the @emph{u-resolution} of 14057the algorithm in the sequel. 14058 14059Both the order of the interpolating polynomial and the 14060u-resolution can be selected. 14061 14062The interpolating polynomials have to be computed in a setup 14063step. However, it only works for distributions with bounded 14064domain; for distributions with unbounded domain the tails are 14065cut off such that the probability for the tail regions is 14066small compared to the given u-resolution. 14067 14068The construction of the interpolation polynomial only works when 14069the PDF is unimodal or when the PDF does not vanish between two 14070modes. 14071 14072There are some restrictions for the given distribution: 14073@itemize 14074@item 14075The support of the distribution (i.e., the region where the PDF 14076is strictly positive) must be connected. In practice this means, 14077that the region where PDF is "not too small" must be connected. 14078Unimodal densities satisfy this condition. 14079If this condition is violated then the domain of the 14080distribution might be truncated. 14081@item 14082When the PDF is integrated numerically, then the given PDF must 14083be continuous and should be smooth. 14084@item 14085The PDF must be bounded. 14086@item 14087The algorithm has problems when the distribution has heavy tails 14088(as then the inverse CDF becomes very steep at 0 or 1) 14089and the requested u-resolution is very small. 14090E.g., the Cauchy distribution is likely to show this problem 14091when the requested u-resolution is less then @code{1.e-12}. 14092@end itemize 14093Regions with very small PDF values or heavy tails might lead to 14094an abortion of the set-up or (even worse) the approximation 14095error might become larger than requested, since the (computation of the) 14096interpolating polynomial becomes numerically unstable. 14097 14098@emph{Remark:} 14099We also have implemented experimental variants. 14100However, we observed that these variants are more sensitive to 14101round-off errors, especially in the right hand tail and we 14102@emph{do not recommend} their usage unless there are severe 14103reasons. 14104 14105@itemize @minus 14106@item 14107Use a function that implements the CDF instead of numerical 14108integration of the PDF. 14109 14110@item 14111Use Hermite interpolation instead of Newton interpolation. 14112Thus the first (and second) derivative of the interpolating 14113polynomial coincides with that of the inverse CDF. 14114Consequently the interpolant is also (twice) differentiable even 14115at the interval boundaries. 14116This variant can be seen as limiting case of Newton 14117interpolation with double (or triple) points as nodes. 14118 14119We have used a @emph{smoothness} parameter to control this 14120feature. However, besides numerical problems we observed that 14121this variant requires more intervals and thus larger setup times 14122and higher memory consumptions. 14123@end itemize 14124 14125 14126 14127@subsubheading How To Use 14128 14129 14130PINV works for continuous univariate distribution objects with 14131given PDF. The corresponding distribution object should contain a 14132typical point of the distribution, i.e., a point where the PDF 14133is not too small, e.g., (a point near) the mode. 14134However, it is important that the center is @strong{not} the 14135pole of the distribution (or a point too close to the pole). 14136It can be set using a 14137@ifhtml 14138@ref{funct:unur_distr_cont_set_center,@command{unur_distr_cont_set_center}} 14139@end ifhtml 14140@ifnothtml 14141@command{unur_distr_cont_set_center} 14142@end ifnothtml 14143or 14144a 14145@ifhtml 14146@ref{funct:unur_distr_cont_set_mode,@command{unur_distr_cont_set_mode}} 14147@end ifhtml 14148@ifnothtml 14149@command{unur_distr_cont_set_mode} 14150@end ifnothtml 14151call. If neither is set, or if the 14152given center cannot be used, then a simple search routine tries 14153to find an appropriate point for the center. 14154 14155It is recommended that the domain of the distribution with 14156bounded domain is specified using a 14157@ifhtml 14158@ref{funct:unur_distr_cont_set_domain,@command{unur_distr_cont_set_domain}} 14159@end ifhtml 14160@ifnothtml 14161@command{unur_distr_cont_set_domain} 14162@end ifnothtml 14163call. Otherwise, the boundary is searched numerically which 14164might be rather expensive, especially when this boundary point 14165is @code{0}. 14166 14167When sampling from truncated distributions with extreme 14168truncation points, it is recommended to provide the log-density 14169using 14170@ifhtml 14171@ref{funct:unur_distr_cont_set_logpdf,@command{unur_distr_cont_set_logpdf}} 14172@end ifhtml 14173@ifnothtml 14174@command{unur_distr_cont_set_logpdf} 14175@end ifnothtml 14176and the mode. 14177Then the PDF is rescaled such that the PDF at the mode is 1. 14178Thus the algorithm is numerically more stable. 14179 14180The inverse CDF is interpolated using Newton polynomials. 14181The order of this polynomial can be set by means of a 14182@ifhtml 14183@ref{funct:unur_pinv_set_order,@command{unur_pinv_set_order}} 14184@end ifhtml 14185@ifnothtml 14186@command{unur_pinv_set_order} 14187@end ifnothtml 14188call. 14189 14190The smoothness of the interpolant at interval boundaries can be 14191controlled using a 14192@ifhtml 14193@ref{funct:unur_pinv_set_smoothness,@command{unur_pinv_set_smoothness}} 14194@end ifhtml 14195@ifnothtml 14196@command{unur_pinv_set_smoothness} 14197@end ifnothtml 14198call. 14199Then Hermite interpolation instead of Newton interpolation is 14200used. (The former can be seen as a limiting case of Newton 14201interpolation with double (or triple) points.) 14202However, using higher smoothness is @emph{not recommended} 14203unless differentiability at the interval boundaries is 14204important. 14205 14206For distributions with unbounded domains the tails are cut 14207off such that the probability for the tail regions is small 14208compared to the given u-resolution. For finding these cut points 14209the algorithm starts with the region @code{[-1.e100,1.e100]}. For 14210the exceptional case where this does not work these starting 14211points can be changed via a 14212@ifhtml 14213@ref{funct:unur_pinv_set_boundary,@command{unur_pinv_set_boundary}} 14214@end ifhtml 14215@ifnothtml 14216@command{unur_pinv_set_boundary} 14217@end ifnothtml 14218call. 14219 14220This method is not exact, as it only produces random variates of 14221the approximated distribution. Nevertheless, the numerical error 14222in "u-direction" (i.e., |U-CDF(X)|, for 14223X = "approximate inverse CDF"(U) |U-CDF(X)|) can be controlled 14224by means of 14225@ifhtml 14226@ref{funct:unur_pinv_set_u_resolution,@command{unur_pinv_set_u_resolution}.} 14227@end ifhtml 14228@ifnothtml 14229@command{unur_pinv_set_u_resolution}. 14230@end ifnothtml 14231However, the maximal error of this approximation is only 14232estimated. For very small u-resolutions the actual approximation 14233error might be (slightly) larger than the requested u-resolution. 14234(Of course the size of this value depends on the given PDF.) 14235If this error is crucial for an application we recommend to 14236compute this error using 14237@ifhtml 14238@ref{funct:unur_pinv_estimate_error,@command{unur_pinv_estimate_error}} 14239@end ifhtml 14240@ifnothtml 14241@command{unur_pinv_estimate_error} 14242@end ifnothtml 14243which runs a 14244small Monte Carlo simulation. 14245See also the documentation for function 14246@ifhtml 14247@ref{funct:unur_pinv_set_u_resolution,@command{unur_pinv_set_u_resolution}} 14248@end ifhtml 14249@ifnothtml 14250@command{unur_pinv_set_u_resolution} 14251@end ifnothtml 14252and the remark given there. 14253 14254The number of required subintervals heavily depends on the order 14255of the interpolating polynomial and the requested u-resolution: 14256it increases when order or u-resolution are decreased. 14257It can be checked using a 14258@ifhtml 14259@ref{funct:unur_pinv_get_n_intervals,@command{unur_pinv_get_n_intervals}} 14260@end ifhtml 14261@ifnothtml 14262@command{unur_pinv_get_n_intervals} 14263@end ifnothtml 14264call. 14265The maximum number of such subintervals is fixed but can be 14266increased using a 14267@ifhtml 14268@ref{funct:unur_pinv_set_max_intervals,@command{unur_pinv_set_max_intervals}} 14269@end ifhtml 14270@ifnothtml 14271@command{unur_pinv_set_max_intervals} 14272@end ifnothtml 14273call. 14274If this maximum number is too small then the set-up aborts with 14275a corresponding error message. 14276 14277It is also possible to use the CDF of the distribution instead 14278of the PDF. Then the distribution object must contain a pointer 14279to the CDF. Moreover, this variant of the algorithm has to be 14280switched on using an 14281@ifhtml 14282@ref{funct:unur_pinv_set_usecdf,@command{unur_pinv_set_usecdf}} 14283@end ifhtml 14284@ifnothtml 14285@command{unur_pinv_set_usecdf} 14286@end ifnothtml 14287call. 14288Notice, however, that the setup for this variant is numerically 14289less stable than using integration of the PDF (the default 14290variant). Thus using the CDF is @emph{not recommended}. 14291 14292 14293 14294 14295@subheading Function reference 14296 14297@ifhtml 14298@itemize 14299@item @ref{funct:unur_pinv_new,unur_pinv_new} 14300@item @ref{funct:unur_pinv_set_order,unur_pinv_set_order} 14301@item @ref{funct:unur_pinv_set_smoothness,unur_pinv_set_smoothness} 14302@item @ref{funct:unur_pinv_set_u_resolution,unur_pinv_set_u_resolution} 14303@item @ref{funct:unur_pinv_set_use_upoints,unur_pinv_set_use_upoints} 14304@item @ref{funct:unur_pinv_set_usepdf,unur_pinv_set_usepdf} 14305@item @ref{funct:unur_pinv_set_usecdf,unur_pinv_set_usecdf} 14306@item @ref{funct:unur_pinv_set_boundary,unur_pinv_set_boundary} 14307@item @ref{funct:unur_pinv_set_searchboundary,unur_pinv_set_searchboundary} 14308@item @ref{funct:unur_pinv_set_max_intervals,unur_pinv_set_max_intervals} 14309@item @ref{funct:unur_pinv_get_n_intervals,unur_pinv_get_n_intervals} 14310@item @ref{funct:unur_pinv_set_keepcdf,unur_pinv_set_keepcdf} 14311@item @ref{funct:unur_pinv_eval_approxinvcdf,unur_pinv_eval_approxinvcdf} 14312@item @ref{funct:unur_pinv_eval_approxcdf,unur_pinv_eval_approxcdf} 14313@item @ref{funct:unur_pinv_estimate_error,unur_pinv_estimate_error} 14314@end itemize 14315@end ifhtml 14316 14317 14318@ifinfo 14319@anchor{funct:unur_pinv_new} 14320@deftypefn Function {UNUR_PAR*} unur_pinv_new (const @var{UNUR_DISTR* distribution}) 14321Get default parameters for generator. 14322@end deftypefn 14323@end ifinfo 14324@ifnotinfo 14325@anchor{funct:unur_pinv_new} 14326@deftypefn {} {UNUR_PAR*} unur_pinv_new (const @var{UNUR_DISTR* distribution}) 14327Get default parameters for generator. 14328@end deftypefn 14329@end ifnotinfo 14330 14331@ifinfo 14332@anchor{funct:unur_pinv_set_order} 14333@deftypefn Function {int} unur_pinv_set_order (UNUR_PAR* @var{parameters}, int @var{order}) 14334Set order of interpolation. Valid orders are between @code{3} and 14335@code{17}. Higher orders result in fewer intervals for the 14336approximations. 14337 14338Default: @code{5}. 14339@end deftypefn 14340@end ifinfo 14341@ifnotinfo 14342@anchor{funct:unur_pinv_set_order} 14343@deftypefn {} {int} unur_pinv_set_order (UNUR_PAR* @var{parameters}, int @var{order}) 14344Set order of interpolation. Valid orders are between @code{3} and 14345@code{17}. Higher orders result in fewer intervals for the 14346approximations. 14347 14348Default: @code{5}. 14349@end deftypefn 14350@end ifnotinfo 14351 14352@ifinfo 14353@anchor{funct:unur_pinv_set_smoothness} 14354@deftypefn Function {int} unur_pinv_set_smoothness (UNUR_PAR* @var{parameters}, int @var{smoothness}) 14355Set smoothness of interpolant. By construction the interpolant is 14356piecewise polynomial and thus smooth on each of the intervals 14357where these polynomials are constructed. At the interval 14358boundaries, however, it usually not be differentiable. 14359Method PINV also implements variants of Newton interpolation where 14360the first (or second) derivative of the interpolating 14361polynomial coincides with the respective derivative of the inverse 14362CDF at the nodes. The the interpolant is (twice) differentiable 14363even at the interval boundaries. 14364These variants can be seen as limiting case of Newton interpolation 14365with double (or triple) points as nodes and are known as Hermite 14366interpolation. 14367 14368Possible values for @var{smoothness}: 14369 14370@multitable @columnfractions .1 .25 .60 14371@headitem Value @tab Effect @tab Requirements 14372@item @code{0} 14373@tab continuous 14374@tab requires PDF (or CDF) 14375 14376@item @code{1} 14377@tab differentiable 14378@tab requires PDF (optional: CDF), @* 14379order of polynomial must be odd 14380 14381@item @code{2} 14382@tab twice differentiable 14383@tab requires PDF and its derivative (optional: CDF), @* 14384order must be 5, 8, 11, 14 or 17 14385@end multitable 14386 14387If the order of the polynomial does not satisfy the given 14388condition, then it is increased to the next larger possible value. 14389 14390@emph{Remark:} 14391A higher smoothness parameter usually results in a higher number of 14392intervals and thus a higher setup time and memory consumption. 14393We also observed that higher smoothness parameters make the 14394algorithm more sensible for round-off error. Then the setup fails. 14395 14396@emph{Remark:} 14397If the interpolating polynomial cannot be constructed for the 14398requested smoothness on a particular interval, 14399then the smoothness parameter is reduced for that interval. 14400 14401@emph{Remark:} 14402For order @code{3} and smoothness @code{1} (cubic Hermite 14403interpolation) monotonicity is guaranteed by checking a simple 14404monotonicity condition for the coefficients of the polynomials. 14405 14406@emph{Remark:} 14407Using @var{smoothness} larger than @code{0} is 14408@emph{not recommended} unless differentiability at the interval 14409boundaries is important for ones application. 14410 14411Default: @code{0}. 14412@end deftypefn 14413@end ifinfo 14414@ifnotinfo 14415@anchor{funct:unur_pinv_set_smoothness} 14416@deftypefn {} {int} unur_pinv_set_smoothness (UNUR_PAR* @var{parameters}, int @var{smoothness}) 14417Set smoothness of interpolant. By construction the interpolant is 14418piecewise polynomial and thus smooth on each of the intervals 14419where these polynomials are constructed. At the interval 14420boundaries, however, it usually not be differentiable. 14421Method PINV also implements variants of Newton interpolation where 14422the first (or second) derivative of the interpolating 14423polynomial coincides with the respective derivative of the inverse 14424CDF at the nodes. The the interpolant is (twice) differentiable 14425even at the interval boundaries. 14426These variants can be seen as limiting case of Newton interpolation 14427with double (or triple) points as nodes and are known as Hermite 14428interpolation. 14429 14430Possible values for @var{smoothness}: 14431 14432@multitable @columnfractions .1 .25 .60 14433@headitem Value @tab Effect @tab Requirements 14434@item @code{0} 14435@tab continuous 14436@tab requires PDF (or CDF) 14437 14438@item @code{1} 14439@tab differentiable 14440@tab requires PDF (optional: CDF), @* 14441order of polynomial must be odd 14442 14443@item @code{2} 14444@tab twice differentiable 14445@tab requires PDF and its derivative (optional: CDF), @* 14446order must be 5, 8, 11, 14 or 17 14447@end multitable 14448 14449If the order of the polynomial does not satisfy the given 14450condition, then it is increased to the next larger possible value. 14451 14452@emph{Remark:} 14453A higher smoothness parameter usually results in a higher number of 14454intervals and thus a higher setup time and memory consumption. 14455We also observed that higher smoothness parameters make the 14456algorithm more sensible for round-off error. Then the setup fails. 14457 14458@emph{Remark:} 14459If the interpolating polynomial cannot be constructed for the 14460requested smoothness on a particular interval, 14461then the smoothness parameter is reduced for that interval. 14462 14463@emph{Remark:} 14464For order @code{3} and smoothness @code{1} (cubic Hermite 14465interpolation) monotonicity is guaranteed by checking a simple 14466monotonicity condition for the coefficients of the polynomials. 14467 14468@emph{Remark:} 14469Using @var{smoothness} larger than @code{0} is 14470@emph{not recommended} unless differentiability at the interval 14471boundaries is important for ones application. 14472 14473Default: @code{0}. 14474@end deftypefn 14475@end ifnotinfo 14476 14477@ifinfo 14478@anchor{funct:unur_pinv_set_u_resolution} 14479@deftypefn Function {int} unur_pinv_set_u_resolution (UNUR_PAR* @var{parameters}, double @var{u_resolution}) 14480Set maximal tolerated u-error. Values of @var{u_resolution} must 14481at least @code{1.e-15} and @code{1.e-5} at most. 14482Notice that the resolution of most uniform random number sources is 14483@math{2^(-32)} 14484= @code{2.3e-10}. Thus a value of @code{1.e-10} 14485leads to an inversion algorithm that could be called exact. For most 14486simulations slightly bigger values for the maximal error are enough 14487as well. 14488 14489Smaller values for @var{u_resolution} increase the number of 14490subinterval that are necessary for the approximation of the inverse 14491CDF. For very small values (less then @code{1.e-12}) this number 14492might exceed the maximum number of such intervals. However, this 14493number can be increased using a 14494@ifhtml 14495@ref{funct:unur_pinv_set_max_intervals,@command{unur_pinv_set_max_intervals}} 14496@end ifhtml 14497@ifnothtml 14498@command{unur_pinv_set_max_intervals} 14499@end ifnothtml 14500call. 14501 14502@emph{Remark:} 14503We ran many experiments and found that the observed u-error was 14504always smaller than the given @var{u_resolution} whenever this 14505value was @code{1.e-12}. For values smaller than @code{1e-13} the 14506maximal observed u-error was slightly larger. One use @code{1.e-15} 14507if best approximation is required. However, then the actual u-error 14508can be as large as @code{1.e-14}. 14509 14510@strong{Warning!} 14511These figures are based on our experiments (with some tolerance 14512added to be on the safe side). There is no guarantee for these error 14513estimates for a particular distribution. 14514 14515Default is @code{1.e-10}. 14516@end deftypefn 14517@end ifinfo 14518@ifnotinfo 14519@anchor{funct:unur_pinv_set_u_resolution} 14520@deftypefn {} {int} unur_pinv_set_u_resolution (UNUR_PAR* @var{parameters}, double @var{u_resolution}) 14521Set maximal tolerated u-error. Values of @var{u_resolution} must 14522at least @code{1.e-15} and @code{1.e-5} at most. 14523Notice that the resolution of most uniform random number sources is 14524@iftex 14525@math{2^{-32}} 14526@end iftex 14527@ifhtml 14528@html 145292<SUP>-32</SUP> 14530@end html 14531@end ifhtml 14532= @code{2.3e-10}. Thus a value of @code{1.e-10} 14533leads to an inversion algorithm that could be called exact. For most 14534simulations slightly bigger values for the maximal error are enough 14535as well. 14536 14537Smaller values for @var{u_resolution} increase the number of 14538subinterval that are necessary for the approximation of the inverse 14539CDF. For very small values (less then @code{1.e-12}) this number 14540might exceed the maximum number of such intervals. However, this 14541number can be increased using a 14542@ifhtml 14543@ref{funct:unur_pinv_set_max_intervals,@command{unur_pinv_set_max_intervals}} 14544@end ifhtml 14545@ifnothtml 14546@command{unur_pinv_set_max_intervals} 14547@end ifnothtml 14548call. 14549 14550@emph{Remark:} 14551We ran many experiments and found that the observed u-error was 14552always smaller than the given @var{u_resolution} whenever this 14553value was @code{1.e-12}. For values smaller than @code{1e-13} the 14554maximal observed u-error was slightly larger. One use @code{1.e-15} 14555if best approximation is required. However, then the actual u-error 14556can be as large as @code{1.e-14}. 14557 14558@strong{Warning!} 14559These figures are based on our experiments (with some tolerance 14560added to be on the safe side). There is no guarantee for these error 14561estimates for a particular distribution. 14562 14563Default is @code{1.e-10}. 14564@end deftypefn 14565@end ifnotinfo 14566 14567@ifinfo 14568@anchor{funct:unur_pinv_set_use_upoints} 14569@deftypefn Function {int} unur_pinv_set_use_upoints (UNUR_PAR* @var{parameters}, int @var{use_upoints}) 14570If @var{use_upoints} is @code{TRUE}, then the nodes of the interpolating 14571polynomial are constructed by means of Chebyshev points in u-scale 14572not in x-scale. This results is a better approximation but almost 14573doubles the number of PDF or CDF evaluations during the setup. 14574(This is an experimental feature.) 14575 14576Default: @code{FALSE} 14577@end deftypefn 14578@end ifinfo 14579@ifnotinfo 14580@anchor{funct:unur_pinv_set_use_upoints} 14581@deftypefn {} {int} unur_pinv_set_use_upoints (UNUR_PAR* @var{parameters}, int @var{use_upoints}) 14582If @var{use_upoints} is @code{TRUE}, then the nodes of the interpolating 14583polynomial are constructed by means of Chebyshev points in u-scale 14584not in x-scale. This results is a better approximation but almost 14585doubles the number of PDF or CDF evaluations during the setup. 14586(This is an experimental feature.) 14587 14588Default: @code{FALSE} 14589@end deftypefn 14590@end ifnotinfo 14591 14592@ifinfo 14593@anchor{funct:unur_pinv_set_usepdf} 14594@deftypefn Function {int} unur_pinv_set_usepdf (UNUR_PAR* @var{parameters}) 14595Use PDF (if available) to compute approximate inverse CDF. 14596 14597This is the default. 14598@end deftypefn 14599@end ifinfo 14600@ifnotinfo 14601@anchor{funct:unur_pinv_set_usepdf} 14602@deftypefn {} {int} unur_pinv_set_usepdf (UNUR_PAR* @var{parameters}) 14603Use PDF (if available) to compute approximate inverse CDF. 14604 14605This is the default. 14606@end deftypefn 14607@end ifnotinfo 14608 14609@ifinfo 14610@anchor{funct:unur_pinv_set_usecdf} 14611@deftypefn Function {int} unur_pinv_set_usecdf (UNUR_PAR* @var{parameters}) 14612Use CDF (if available) to compute approximate inverse CDF. 14613This variant is intend for running experiments with method PINV. 14614 14615@emph{Remark:} 14616We ran many experiments and found that for small values of the 14617given @var{u_resolution} (less than @code{1.e-12}) the setup fails 14618for distributions with heavy tails. We found that using the PDF 14619(instead of the CDF) is numerically more stable. 14620This is especially the case when the smoothness parameter is set 14621to @code{1} or @code{2}. 14622 14623Using the CDF is @strong{not recommended}. 14624@end deftypefn 14625@end ifinfo 14626@ifnotinfo 14627@anchor{funct:unur_pinv_set_usecdf} 14628@deftypefn {} {int} unur_pinv_set_usecdf (UNUR_PAR* @var{parameters}) 14629Use CDF (if available) to compute approximate inverse CDF. 14630This variant is intend for running experiments with method PINV. 14631 14632@emph{Remark:} 14633We ran many experiments and found that for small values of the 14634given @var{u_resolution} (less than @code{1.e-12}) the setup fails 14635for distributions with heavy tails. We found that using the PDF 14636(instead of the CDF) is numerically more stable. 14637This is especially the case when the smoothness parameter is set 14638to @code{1} or @code{2}. 14639 14640Using the CDF is @strong{not recommended}. 14641@end deftypefn 14642@end ifnotinfo 14643 14644@ifinfo 14645@anchor{funct:unur_pinv_set_boundary} 14646@deftypefn Function {int} unur_pinv_set_boundary (UNUR_PAR* @var{parameters}, double @var{left}, double @var{right}) 14647Set @var{left} and @var{right} point for finding the cut-off points 14648for the "computational domain", i.e., the domain that covers the 14649essential part of the distribution. 14650The cut-off points are computed such that the tail probabilities 14651are smaller than given by 14652@ifhtml 14653@ref{funct:unur_pinv_set_u_resolution,@command{unur_pinv_set_u_resolution}.} 14654@end ifhtml 14655@ifnothtml 14656@command{unur_pinv_set_u_resolution}. 14657@end ifnothtml 14658It is usually safe to use a large interval. 14659However, @code{+/- UNUR_INFINITY} is not allowed. 14660 14661@emph{Important}: This call does not change the domain of the 14662given distribution itself. But it restricts the domain for the 14663resulting random variates. 14664 14665Default: intersection of @code{[-1.e100,+1.e100]} and the given 14666domain of the distribution. 14667@end deftypefn 14668@end ifinfo 14669@ifnotinfo 14670@anchor{funct:unur_pinv_set_boundary} 14671@deftypefn {} {int} unur_pinv_set_boundary (UNUR_PAR* @var{parameters}, double @var{left}, double @var{right}) 14672Set @var{left} and @var{right} point for finding the cut-off points 14673for the "computational domain", i.e., the domain that covers the 14674essential part of the distribution. 14675The cut-off points are computed such that the tail probabilities 14676are smaller than given by 14677@ifhtml 14678@ref{funct:unur_pinv_set_u_resolution,@command{unur_pinv_set_u_resolution}.} 14679@end ifhtml 14680@ifnothtml 14681@command{unur_pinv_set_u_resolution}. 14682@end ifnothtml 14683It is usually safe to use a large interval. 14684However, @code{+/- UNUR_INFINITY} is not allowed. 14685 14686@emph{Important}: This call does not change the domain of the 14687given distribution itself. But it restricts the domain for the 14688resulting random variates. 14689 14690Default: intersection of @code{[-1.e100,+1.e100]} and the given 14691domain of the distribution. 14692@end deftypefn 14693@end ifnotinfo 14694 14695@ifinfo 14696@anchor{funct:unur_pinv_set_searchboundary} 14697@deftypefn Function {int} unur_pinv_set_searchboundary (UNUR_PAR* @var{parameters}, int @var{left}, int @var{right}) 14698If @var{left} or @var{right} is set to @code{FALSE} then the respective 14699boundary as given by a 14700@ifhtml 14701@ref{funct:unur_pinv_set_boundary,@command{unur_pinv_set_boundary}} 14702@end ifhtml 14703@ifnothtml 14704@command{unur_pinv_set_boundary} 14705@end ifnothtml 14706call is used 14707without any further computations. 14708However, these boundary points might cause numerical problems 14709during the setup when PDF returns @code{0} ``almost everywhere''. 14710If set to @code{TRUE} (the default) then the computational interval is 14711shortened to a more sensible region by means of a search algorithm. 14712Switching off this search is useful, e.g., for the Gamma(2) 14713distribution where the left border @code{0} is fixed and finite. 14714 14715@emph{Remark:} 14716The searching algorithm assumes that the support of the distribution 14717is connected. 14718 14719@emph{Remark:} 14720Do not set this parameter to @code{FALSE} except when searching for 14721cut-off points fails and one wants to try with precomputed values. 14722 14723Default: @code{TRUE}. 14724@end deftypefn 14725@end ifinfo 14726@ifnotinfo 14727@anchor{funct:unur_pinv_set_searchboundary} 14728@deftypefn {} {int} unur_pinv_set_searchboundary (UNUR_PAR* @var{parameters}, int @var{left}, int @var{right}) 14729If @var{left} or @var{right} is set to @code{FALSE} then the respective 14730boundary as given by a 14731@ifhtml 14732@ref{funct:unur_pinv_set_boundary,@command{unur_pinv_set_boundary}} 14733@end ifhtml 14734@ifnothtml 14735@command{unur_pinv_set_boundary} 14736@end ifnothtml 14737call is used 14738without any further computations. 14739However, these boundary points might cause numerical problems 14740during the setup when PDF returns @code{0} ``almost everywhere''. 14741If set to @code{TRUE} (the default) then the computational interval is 14742shortened to a more sensible region by means of a search algorithm. 14743Switching off this search is useful, e.g., for the Gamma(2) 14744distribution where the left border @code{0} is fixed and finite. 14745 14746@emph{Remark:} 14747The searching algorithm assumes that the support of the distribution 14748is connected. 14749 14750@emph{Remark:} 14751Do not set this parameter to @code{FALSE} except when searching for 14752cut-off points fails and one wants to try with precomputed values. 14753 14754Default: @code{TRUE}. 14755@end deftypefn 14756@end ifnotinfo 14757 14758@ifinfo 14759@anchor{funct:unur_pinv_set_max_intervals} 14760@deftypefn Function {int} unur_pinv_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 14761Set maximum number of intervals. @var{max_ivs} must be at least 14762@code{100} and at most @code{1000000}. 14763 14764Default is @code{10000}. 14765@end deftypefn 14766@end ifinfo 14767@ifnotinfo 14768@anchor{funct:unur_pinv_set_max_intervals} 14769@deftypefn {} {int} unur_pinv_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 14770Set maximum number of intervals. @var{max_ivs} must be at least 14771@code{100} and at most @code{1000000}. 14772 14773Default is @code{10000}. 14774@end deftypefn 14775@end ifnotinfo 14776 14777@ifinfo 14778@anchor{funct:unur_pinv_get_n_intervals} 14779@deftypefn Function {int} unur_pinv_get_n_intervals (const @var{UNUR_GEN* generator}) 14780Get number of intervals used for interpolation in 14781the generator object. 14782It returns @code{0} in case of an error. 14783@end deftypefn 14784@end ifinfo 14785@ifnotinfo 14786@anchor{funct:unur_pinv_get_n_intervals} 14787@deftypefn {} {int} unur_pinv_get_n_intervals (const @var{UNUR_GEN* generator}) 14788Get number of intervals used for interpolation in 14789the generator object. 14790It returns @code{0} in case of an error. 14791@end deftypefn 14792@end ifnotinfo 14793 14794@ifinfo 14795@anchor{funct:unur_pinv_set_keepcdf} 14796@deftypefn Function {int} unur_pinv_set_keepcdf (UNUR_PAR* @var{parameters}, int @var{keepcdf}) 14797If the PDF is given, then the CDF is computed numerically 14798from the given PDF using adaptive Gauss-Lobatto integration. 14799Thus a table of CDF points is stored to keep the number of 14800evaluations of the PDF minimal. Usually this table is discarded 14801when the setup is completed. 14802If @var{keepcdf} is @code{TRUE}, then this table is kept and can be used 14803to compute the CDF of the underlying distribution by means of 14804function 14805@ifhtml 14806@ref{funct:unur_pinv_eval_approxcdf,@command{unur_pinv_eval_approxcdf}.} 14807@end ifhtml 14808@ifnothtml 14809@command{unur_pinv_eval_approxcdf}. 14810@end ifnothtml 14811This option is ignored when 14812@ifhtml 14813@ref{funct:unur_pinv_set_usecdf,@command{unur_pinv_set_usecdf}} 14814@end ifhtml 14815@ifnothtml 14816@command{unur_pinv_set_usecdf} 14817@end ifnothtml 14818is called. 14819 14820Default: @code{FALSE} 14821@end deftypefn 14822@end ifinfo 14823@ifnotinfo 14824@anchor{funct:unur_pinv_set_keepcdf} 14825@deftypefn {} {int} unur_pinv_set_keepcdf (UNUR_PAR* @var{parameters}, int @var{keepcdf}) 14826If the PDF is given, then the CDF is computed numerically 14827from the given PDF using adaptive Gauss-Lobatto integration. 14828Thus a table of CDF points is stored to keep the number of 14829evaluations of the PDF minimal. Usually this table is discarded 14830when the setup is completed. 14831If @var{keepcdf} is @code{TRUE}, then this table is kept and can be used 14832to compute the CDF of the underlying distribution by means of 14833function 14834@ifhtml 14835@ref{funct:unur_pinv_eval_approxcdf,@command{unur_pinv_eval_approxcdf}.} 14836@end ifhtml 14837@ifnothtml 14838@command{unur_pinv_eval_approxcdf}. 14839@end ifnothtml 14840This option is ignored when 14841@ifhtml 14842@ref{funct:unur_pinv_set_usecdf,@command{unur_pinv_set_usecdf}} 14843@end ifhtml 14844@ifnothtml 14845@command{unur_pinv_set_usecdf} 14846@end ifnothtml 14847is called. 14848 14849Default: @code{FALSE} 14850@end deftypefn 14851@end ifnotinfo 14852 14853@ifinfo 14854@anchor{funct:unur_pinv_eval_approxinvcdf} 14855@deftypefn Function {double} unur_pinv_eval_approxinvcdf (const @var{UNUR_GEN* generator}, double @var{u}) 14856Evaluate interpolation of inverse CDF at @var{u}. 14857If @var{u} is out of the domain (0,1) then @code{unur_errno} is set 14858to @code{UNUR_ERR_DOMAIN} and the respective bound of 14859the domain of the distribution are returned (which is 14860@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 14861unbounded domains). 14862@end deftypefn 14863@end ifinfo 14864@ifnotinfo 14865@anchor{funct:unur_pinv_eval_approxinvcdf} 14866@deftypefn {} {double} unur_pinv_eval_approxinvcdf (const @var{UNUR_GEN* generator}, double @var{u}) 14867Evaluate interpolation of inverse CDF at @var{u}. 14868If @var{u} is out of the domain (0,1) then @code{unur_errno} is set 14869to @code{UNUR_ERR_DOMAIN} and the respective bound of 14870the domain of the distribution are returned (which is 14871@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 14872unbounded domains). 14873@end deftypefn 14874@end ifnotinfo 14875 14876@ifinfo 14877@anchor{funct:unur_pinv_eval_approxcdf} 14878@deftypefn Function {double} unur_pinv_eval_approxcdf (const @var{UNUR_GEN* generator}, double @var{x}) 14879Evaluate (approximate) CDF at @var{x}. If the PDF of the 14880distribution is given, then adaptive Gauss-Lobatto integration is 14881used to compute the CDF. 14882If the PDF is used to create the generator object, then the 14883table of integral values must not removed at the end of setup and thus 14884@ifhtml 14885@ref{funct:unur_pinv_set_keepcdf,@command{unur_pinv_set_keepcdf}} 14886@end ifhtml 14887@ifnothtml 14888@command{unur_pinv_set_keepcdf} 14889@end ifnothtml 14890must be called. 14891@end deftypefn 14892@end ifinfo 14893@ifnotinfo 14894@anchor{funct:unur_pinv_eval_approxcdf} 14895@deftypefn {} {double} unur_pinv_eval_approxcdf (const @var{UNUR_GEN* generator}, double @var{x}) 14896Evaluate (approximate) CDF at @var{x}. If the PDF of the 14897distribution is given, then adaptive Gauss-Lobatto integration is 14898used to compute the CDF. 14899If the PDF is used to create the generator object, then the 14900table of integral values must not removed at the end of setup and thus 14901@ifhtml 14902@ref{funct:unur_pinv_set_keepcdf,@command{unur_pinv_set_keepcdf}} 14903@end ifhtml 14904@ifnothtml 14905@command{unur_pinv_set_keepcdf} 14906@end ifnothtml 14907must be called. 14908@end deftypefn 14909@end ifnotinfo 14910 14911@ifinfo 14912@anchor{funct:unur_pinv_estimate_error} 14913@deftypefn Function {int} unur_pinv_estimate_error (const @var{UNUR_GEN* generator}, int @var{samplesize}, double* @var{max_error}, double* @var{MAE}) 14914Estimate maximal u-error and mean absolute error (MAE) for @var{generator} 14915by means of Monte-Carlo simulation with sample size @var{samplesize}. 14916The results are stored in @var{max_error} and @var{MAE}, respectively. 14917 14918It returns @code{UNUR_SUCCESS} if successful. 14919@end deftypefn 14920@end ifinfo 14921@ifnotinfo 14922@anchor{funct:unur_pinv_estimate_error} 14923@deftypefn {} {int} unur_pinv_estimate_error (const @var{UNUR_GEN* generator}, int @var{samplesize}, double* @var{max_error}, double* @var{MAE}) 14924Estimate maximal u-error and mean absolute error (MAE) for @var{generator} 14925by means of Monte-Carlo simulation with sample size @var{samplesize}. 14926The results are stored in @var{max_error} and @var{MAE}, respectively. 14927 14928It returns @code{UNUR_SUCCESS} if successful. 14929@end deftypefn 14930@end ifnotinfo 14931 14932 14933 14934 14935@c 14936@c end of pinv.h 14937@c ------------------------------------- 14938@c ------------------------------------- 14939@c srou.h 14940@c 14941 14942@page 14943@node SROU 14944@subsection SROU -- Simple Ratio-Of-Uniforms method 14945 14946@table @i 14947@item Required: 14948T-concave PDF, mode, area 14949@item Speed: 14950Set-up: fast, Sampling: slow 14951@item Reinit: 14952supported 14953@item Reference: 14954@ifhtml 14955@ref{bib:LJa01,, [LJa01]} 14956@end ifhtml 14957@ifnothtml 14958[LJa01] 14959@end ifnothtml 14960@ifhtml 14961@ref{bib:LJa02,, [LJa02]} 14962@end ifhtml 14963@ifnothtml 14964[LJa02] 14965@end ifnothtml 14966@ifhtml 14967@ref{bib:HLD04,, [HLD04: Sect.6.3.1; Sect.6.3.2; Sect.6.4.1; Alg.6.4; Alg.6.5; Alg.6.7]} 14968@end ifhtml 14969@ifnothtml 14970[HLD04: Sect.6.3.1; Sect.6.3.2; Sect.6.4.1; Alg.6.4; Alg.6.5; Alg.6.7] 14971@end ifnothtml 14972 14973@end table 14974@sp 1 14975 14976 14977SROU is based on the ratio-of-uniforms method 14978(@pxref{Ratio-of-Uniforms}) that uses universal inequalities for 14979constructing a (universal) bounding rectangle. 14980It works for all @i{T}-concave distributions, including 14981log-concave and @i{T}-concave distributions with 14982@iftex 14983@math{T(x) = -1/\sqrt{x}.} 14984@end iftex 14985@ifhtml 14986@html 14987<I>T</I>(<I>x</I>) = -1/sqrt(<I>x</I>). 14988@end html 14989@end ifhtml 14990@ifinfo 14991@math{T(x) = -1/sqrt(x).} 14992@end ifinfo 14993 14994Moreover an (optional) parameter @code{r} can be given, to 14995adjust the generator to the given distribution. This parameter 14996is strongly related to the parameter @code{c} for transformed 14997density rejection (@pxref{TDR}) via the formula 14998@i{c = -r/(r+1)}. The rejection constant increases with higher 14999values for @code{r}. On the other hand, the given density must 15000be 15001@iftex 15002@math{T_c} 15003@end iftex 15004@ifhtml 15005@html 15006<I>T</I>_<I>c</I> 15007@end html 15008@end ifhtml 15009@ifinfo 15010@math{T_c} 15011@end ifinfo 15012-concave for the corresponding @i{c}. 15013The default setting for @code{r} is 1 which results in a very 15014simple code. (For other settings, sampling uniformly from the 15015acceptance region is more complicated.) 15016 15017Optionally the CDF at the mode can be given to increase the 15018performance of the algorithm. Then the rejection constant is 15019reduced by 1/2 and (if @code{r=1}) even a universal squeeze can 15020(but need not be) used. 15021A way to increase the performance of the algorithm when the 15022CDF at the mode is not provided is the usage of the mirror 15023principle (only if @code{r=1}). However, using squeezes and using 15024the mirror principle is only recommended when the PDF is 15025expensive to compute. 15026 15027The exact location of the mode and/or the area below the PDF can 15028be replace by appropriate bounds. Then the algorithm still works 15029but has larger rejection constants. 15030 15031 15032@subsubheading How To Use 15033 15034 15035SROU works for any continuous univariate distribution object with 15036given 15037@iftex 15038@math{T_c} 15039@end iftex 15040@ifhtml 15041@html 15042<I>T</I>_<I>c</I> 15043@end html 15044@end ifhtml 15045@ifinfo 15046@math{T_c} 15047@end ifinfo 15048-concave PDF with 15049@iftex 15050@math{c<1,} 15051@end iftex 15052@ifhtml 15053@html 15054<I>c</I><1, 15055@end html 15056@end ifhtml 15057@ifinfo 15058@math{c<1,} 15059@end ifinfo 15060) 15061mode and area below PDF. Optional the CDF at the mode 15062can be given to increase the performance of the algorithm by 15063means of the 15064@ifhtml 15065@ref{funct:unur_srou_set_cdfatmode,@command{unur_srou_set_cdfatmode}} 15066@end ifhtml 15067@ifnothtml 15068@command{unur_srou_set_cdfatmode} 15069@end ifnothtml 15070call. Additionally 15071squeezes can be used and switched on via 15072@ifhtml 15073@ref{funct:unur_srou_set_usesqueeze,@command{unur_srou_set_usesqueeze}} 15074@end ifhtml 15075@ifnothtml 15076@command{unur_srou_set_usesqueeze} 15077@end ifnothtml 15078(only if @code{r=1}). 15079A way to increase the performance of the algorithm when the 15080CDF at the mode is not provided is the usage of the mirror 15081principle which can be swithced on by means of a 15082@ifhtml 15083@ref{funct:unur_srou_set_usemirror,@command{unur_srou_set_usemirror}} 15084@end ifhtml 15085@ifnothtml 15086@command{unur_srou_set_usemirror} 15087@end ifnothtml 15088call (only if @code{r=1}) . 15089However using squeezes and using 15090the mirror principle is only recommended when the PDF is 15091expensive to compute. 15092 15093The parameter @code{r} can be given, to adjust the generator to 15094the given distribution. This parameter is strongly related 15095parameter @code{c} for transformed density rejection via the 15096formula @i{c = -r/(r+1)}. 15097The parameter @code{r} can be any value larger than or equal to 150981. Values less then 1 are automatically set to 1. 15099The rejection constant depends on the chosen parameter 15100@code{r} but not on the particular distribution. It is 4 for 15101@code{r} equal to 1 and higher for higher values of @code{r}. 15102It is important to note that different algorithms for different 15103values of @code{r}: If @code{r} equal to 1 this is much faster 15104than the algorithm for @code{r} greater than 1. 15105The default setting for @code{r} is 1. 15106 15107If the (exact) area below the PDF is not known, then an upper 15108bound can be used instead (which of course increases the rejection 15109constant). But then the squeeze flag must not be set and 15110@ifhtml 15111@ref{funct:unur_srou_set_cdfatmode,@command{unur_srou_set_cdfatmode}} 15112@end ifhtml 15113@ifnothtml 15114@command{unur_srou_set_cdfatmode} 15115@end ifnothtml 15116must not be used. 15117 15118If the exact location of the mode is not known, then use the 15119approximate location and provide the (exact) value of the PDF at 15120the mode by means of the 15121@ifhtml 15122@ref{funct:unur_srou_set_pdfatmode,@command{unur_srou_set_pdfatmode}} 15123@end ifhtml 15124@ifnothtml 15125@command{unur_srou_set_pdfatmode} 15126@end ifnothtml 15127call. But then 15128@ifhtml 15129@ref{funct:unur_srou_set_cdfatmode,@command{unur_srou_set_cdfatmode}} 15130@end ifhtml 15131@ifnothtml 15132@command{unur_srou_set_cdfatmode} 15133@end ifnothtml 15134must not be used. Notice, that a (slow) 15135numerical mode finder will be used if no mode is given at all. 15136It is even possible to give an upper bound for the PDF only. 15137However, then the (upper bound for the) area below the PDF has to be 15138multiplied by the ratio between the upper bound and the lower bound of 15139the PDF at the mode. Again setting the squeeze flag and using 15140@ifhtml 15141@ref{funct:unur_srou_set_cdfatmode,@command{unur_srou_set_cdfatmode}} 15142@end ifhtml 15143@ifnothtml 15144@command{unur_srou_set_cdfatmode} 15145@end ifnothtml 15146is not allowed. 15147 15148It is possible to change the parameters and the domain of the chosen 15149distribution and run 15150@ifhtml 15151@ref{funct:unur_reinit,@command{unur_reinit}} 15152@end ifhtml 15153@ifnothtml 15154@command{unur_reinit} 15155@end ifnothtml 15156to reinitialize the generator object. 15157Notice, that derived parameters like the mode must also be (re-) set 15158if the parameters or the domain has be changed. 15159Moreover, if the PDF at the mode has been provided by a 15160@ifhtml 15161@ref{funct:unur_srou_set_pdfatmode,@command{unur_srou_set_pdfatmode}} 15162@end ifhtml 15163@ifnothtml 15164@command{unur_srou_set_pdfatmode} 15165@end ifnothtml 15166call, additionally 15167@ifhtml 15168@ref{funct:unur_srou_chg_pdfatmode,@command{unur_srou_chg_pdfatmode}} 15169@end ifhtml 15170@ifnothtml 15171@command{unur_srou_chg_pdfatmode} 15172@end ifnothtml 15173must be used (otherwise this call is 15174not necessary since then this figure is computed directly from 15175the PDF). 15176 15177There exists a test mode that verifies whether the conditions 15178for the method are satisfied or not while sampling. It can be 15179switched on by calling 15180@ifhtml 15181@ref{funct:unur_srou_set_verify,@command{unur_srou_set_verify}} 15182@end ifhtml 15183@ifnothtml 15184@command{unur_srou_set_verify} 15185@end ifnothtml 15186and 15187@ifhtml 15188@ref{funct:unur_srou_chg_verify,@command{unur_srou_chg_verify},} 15189@end ifhtml 15190@ifnothtml 15191@command{unur_srou_chg_verify}, 15192@end ifnothtml 15193respectively. Notice however that 15194sampling is (a little bit) slower then. 15195 15196 15197 15198 15199@subheading Function reference 15200 15201@ifhtml 15202@itemize 15203@item @ref{funct:unur_srou_new,unur_srou_new} 15204@item @ref{funct:unur_srou_set_r,unur_srou_set_r} 15205@item @ref{funct:unur_srou_set_cdfatmode,unur_srou_set_cdfatmode} 15206@item @ref{funct:unur_srou_set_pdfatmode,unur_srou_set_pdfatmode} 15207@item @ref{funct:unur_srou_set_usesqueeze,unur_srou_set_usesqueeze} 15208@item @ref{funct:unur_srou_set_usemirror,unur_srou_set_usemirror} 15209@item @ref{funct:unur_srou_set_verify,unur_srou_set_verify} 15210@item @ref{funct:unur_srou_chg_verify,unur_srou_chg_verify} 15211@item @ref{funct:unur_srou_chg_cdfatmode,unur_srou_chg_cdfatmode} 15212@item @ref{funct:unur_srou_chg_pdfatmode,unur_srou_chg_pdfatmode} 15213@end itemize 15214@end ifhtml 15215 15216 15217@ifinfo 15218@anchor{funct:unur_srou_new} 15219@deftypefn Function {UNUR_PAR*} unur_srou_new (const @var{UNUR_DISTR* distribution}) 15220Get default parameters for generator. 15221@end deftypefn 15222@end ifinfo 15223@ifnotinfo 15224@anchor{funct:unur_srou_new} 15225@deftypefn {} {UNUR_PAR*} unur_srou_new (const @var{UNUR_DISTR* distribution}) 15226Get default parameters for generator. 15227@end deftypefn 15228@end ifnotinfo 15229 15230@ifinfo 15231@anchor{funct:unur_srou_set_r} 15232@deftypefn Function {int} unur_srou_set_r (UNUR_PAR* @var{parameters}, double @var{r}) 15233Set parameter @var{r} for transformation. 15234Only values greater than or equal to 1 are allowed. 15235The performance of the generator decreases when @var{r} is 15236increased. On the other hand @var{r} must not be set to small, 15237since the given density must be T_c-concave for 15238@i{c = -r/(r+1)}. 15239 15240@emph{Notice:} If @var{r} is set to @code{1} a simpler and much 15241faster algorithm is used then for @var{r} greater than one. 15242 15243For computational reasons values of @var{r} that are greater than 15244@code{1} but less than @code{1.01} are always set to @code{1.01}. 15245 15246Default is @code{1}. 15247@end deftypefn 15248@end ifinfo 15249@ifnotinfo 15250@anchor{funct:unur_srou_set_r} 15251@deftypefn {} {int} unur_srou_set_r (UNUR_PAR* @var{parameters}, double @var{r}) 15252Set parameter @var{r} for transformation. 15253Only values greater than or equal to 1 are allowed. 15254The performance of the generator decreases when @var{r} is 15255increased. On the other hand @var{r} must not be set to small, 15256since the given density must be T_c-concave for 15257@i{c = -r/(r+1)}. 15258 15259@emph{Notice:} If @var{r} is set to @code{1} a simpler and much 15260faster algorithm is used then for @var{r} greater than one. 15261 15262For computational reasons values of @var{r} that are greater than 15263@code{1} but less than @code{1.01} are always set to @code{1.01}. 15264 15265Default is @code{1}. 15266@end deftypefn 15267@end ifnotinfo 15268 15269@ifinfo 15270@anchor{funct:unur_srou_set_cdfatmode} 15271@deftypefn Function {int} unur_srou_set_cdfatmode (UNUR_PAR* @var{parameters}, double @var{Fmode}) 15272Set CDF at mode. 15273When set, the performance of the algorithm is increased by factor 2. 15274However, when the parameters of the distribution are changed 15275@ifhtml 15276@ref{funct:unur_srou_chg_cdfatmode,@command{unur_srou_chg_cdfatmode}} 15277@end ifhtml 15278@ifnothtml 15279@command{unur_srou_chg_cdfatmode} 15280@end ifnothtml 15281has to be used to update this value. 15282 15283Default: not set. 15284@end deftypefn 15285@end ifinfo 15286@ifnotinfo 15287@anchor{funct:unur_srou_set_cdfatmode} 15288@deftypefn {} {int} unur_srou_set_cdfatmode (UNUR_PAR* @var{parameters}, double @var{Fmode}) 15289Set CDF at mode. 15290When set, the performance of the algorithm is increased by factor 2. 15291However, when the parameters of the distribution are changed 15292@ifhtml 15293@ref{funct:unur_srou_chg_cdfatmode,@command{unur_srou_chg_cdfatmode}} 15294@end ifhtml 15295@ifnothtml 15296@command{unur_srou_chg_cdfatmode} 15297@end ifnothtml 15298has to be used to update this value. 15299 15300Default: not set. 15301@end deftypefn 15302@end ifnotinfo 15303 15304@ifinfo 15305@anchor{funct:unur_srou_set_pdfatmode} 15306@deftypefn Function {int} unur_srou_set_pdfatmode (UNUR_PAR* @var{parameters}, double @var{fmode}) 15307Set pdf at mode. 15308When set, the PDF at the mode is never changed. 15309This is to avoid additional computations, when the PDF does not 15310change when parameters of the distributions vary. 15311It is only useful when the PDF at the mode does not change with 15312changing parameters of the distribution. 15313 15314@emph{IMPORTANT:} 15315This call has to be executed after a possible call of 15316@ifhtml 15317@ref{funct:unur_srou_set_r,@command{unur_srou_set_r}.} 15318@end ifhtml 15319@ifnothtml 15320@command{unur_srou_set_r}. 15321@end ifnothtml 15322Default: not set. 15323@end deftypefn 15324@end ifinfo 15325@ifnotinfo 15326@anchor{funct:unur_srou_set_pdfatmode} 15327@deftypefn {} {int} unur_srou_set_pdfatmode (UNUR_PAR* @var{parameters}, double @var{fmode}) 15328Set pdf at mode. 15329When set, the PDF at the mode is never changed. 15330This is to avoid additional computations, when the PDF does not 15331change when parameters of the distributions vary. 15332It is only useful when the PDF at the mode does not change with 15333changing parameters of the distribution. 15334 15335@emph{IMPORTANT:} 15336This call has to be executed after a possible call of 15337@ifhtml 15338@ref{funct:unur_srou_set_r,@command{unur_srou_set_r}.} 15339@end ifhtml 15340@ifnothtml 15341@command{unur_srou_set_r}. 15342@end ifnothtml 15343Default: not set. 15344@end deftypefn 15345@end ifnotinfo 15346 15347@ifinfo 15348@anchor{funct:unur_srou_set_usesqueeze} 15349@deftypefn Function {int} unur_srou_set_usesqueeze (UNUR_PAR* @var{parameters}, int @var{usesqueeze}) 15350Set flag for using universal squeeze (default: off). 15351Using squeezes is only useful when the evaluation of the PDF is 15352(extremely) expensive. 15353Using squeezes is automatically disabled when the CDF at the mode 15354is not given (then no universal squeezes exist). 15355 15356Squeezes can only be used if @code{r=1}. 15357 15358Default is @code{FALSE}. 15359@end deftypefn 15360@end ifinfo 15361@ifnotinfo 15362@anchor{funct:unur_srou_set_usesqueeze} 15363@deftypefn {} {int} unur_srou_set_usesqueeze (UNUR_PAR* @var{parameters}, int @var{usesqueeze}) 15364Set flag for using universal squeeze (default: off). 15365Using squeezes is only useful when the evaluation of the PDF is 15366(extremely) expensive. 15367Using squeezes is automatically disabled when the CDF at the mode 15368is not given (then no universal squeezes exist). 15369 15370Squeezes can only be used if @code{r=1}. 15371 15372Default is @code{FALSE}. 15373@end deftypefn 15374@end ifnotinfo 15375 15376@ifinfo 15377@anchor{funct:unur_srou_set_usemirror} 15378@deftypefn Function {int} unur_srou_set_usemirror (UNUR_PAR* @var{parameters}, int @var{usemirror}) 15379Set flag for using mirror principle (default: off). 15380Using the mirror principle is only useful when the CDF at the 15381mode is not known and the evaluation of the PDF is rather cheap compared 15382to the marginal generation time of the underlying uniform random 15383number generator. 15384It is automatically disabled when the CDF at the mode is given. 15385(Then there is no necessity to use the mirror principle. However disabling 15386is only done during the initialization step but not at a re-initialization 15387step.) 15388 15389The mirror principle can only be used if @code{r=1}. 15390 15391Default is @code{FALSE}. 15392@end deftypefn 15393@end ifinfo 15394@ifnotinfo 15395@anchor{funct:unur_srou_set_usemirror} 15396@deftypefn {} {int} unur_srou_set_usemirror (UNUR_PAR* @var{parameters}, int @var{usemirror}) 15397Set flag for using mirror principle (default: off). 15398Using the mirror principle is only useful when the CDF at the 15399mode is not known and the evaluation of the PDF is rather cheap compared 15400to the marginal generation time of the underlying uniform random 15401number generator. 15402It is automatically disabled when the CDF at the mode is given. 15403(Then there is no necessity to use the mirror principle. However disabling 15404is only done during the initialization step but not at a re-initialization 15405step.) 15406 15407The mirror principle can only be used if @code{r=1}. 15408 15409Default is @code{FALSE}. 15410@end deftypefn 15411@end ifnotinfo 15412 15413@ifinfo 15414@anchor{funct:unur_srou_set_verify} 15415@deftypefn Function {int} unur_srou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 15416@anchor{funct:unur_srou_chg_verify} 15417@deftypefnx Function {int} unur_srou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 15418Turn verifying of algorithm while sampling on/off. 15419If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 15420violated for some @i{x} then @code{unur_errno} is set to 15421@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 15422happen due to round-off errors for a few values of 15423@i{x} (less than 1%). 15424 15425Default is @code{FALSE}. 15426@end deftypefn 15427@end ifinfo 15428@ifnotinfo 15429@anchor{funct:unur_srou_set_verify} 15430@deftypefn {} {int} unur_srou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 15431@anchor{funct:unur_srou_chg_verify} 15432@deftypefnx {} {int} unur_srou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 15433Turn verifying of algorithm while sampling on/off. 15434If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 15435violated for some @i{x} then @code{unur_errno} is set to 15436@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 15437happen due to round-off errors for a few values of 15438@i{x} (less than 1%). 15439 15440Default is @code{FALSE}. 15441@end deftypefn 15442@end ifnotinfo 15443 15444@ifinfo 15445@anchor{funct:unur_srou_chg_cdfatmode} 15446@deftypefn Function {int} unur_srou_chg_cdfatmode (UNUR_GEN* @var{generator}, double @var{Fmode}) 15447Change CDF at mode of distribution. 15448@ifhtml 15449@ref{funct:unur_reinit,@command{unur_reinit}} 15450@end ifhtml 15451@ifnothtml 15452@command{unur_reinit} 15453@end ifnothtml 15454must be executed before sampling from the 15455generator again. 15456@end deftypefn 15457@end ifinfo 15458@ifnotinfo 15459@anchor{funct:unur_srou_chg_cdfatmode} 15460@deftypefn {} {int} unur_srou_chg_cdfatmode (UNUR_GEN* @var{generator}, double @var{Fmode}) 15461Change CDF at mode of distribution. 15462@ifhtml 15463@ref{funct:unur_reinit,@command{unur_reinit}} 15464@end ifhtml 15465@ifnothtml 15466@command{unur_reinit} 15467@end ifnothtml 15468must be executed before sampling from the 15469generator again. 15470@end deftypefn 15471@end ifnotinfo 15472 15473@ifinfo 15474@anchor{funct:unur_srou_chg_pdfatmode} 15475@deftypefn Function {int} unur_srou_chg_pdfatmode (UNUR_GEN* @var{generator}, double @var{fmode}) 15476Change PDF at mode of distribution. 15477@ifhtml 15478@ref{funct:unur_reinit,@command{unur_reinit}} 15479@end ifhtml 15480@ifnothtml 15481@command{unur_reinit} 15482@end ifnothtml 15483must be executed before sampling from the 15484generator again. 15485@end deftypefn 15486@end ifinfo 15487@ifnotinfo 15488@anchor{funct:unur_srou_chg_pdfatmode} 15489@deftypefn {} {int} unur_srou_chg_pdfatmode (UNUR_GEN* @var{generator}, double @var{fmode}) 15490Change PDF at mode of distribution. 15491@ifhtml 15492@ref{funct:unur_reinit,@command{unur_reinit}} 15493@end ifhtml 15494@ifnothtml 15495@command{unur_reinit} 15496@end ifnothtml 15497must be executed before sampling from the 15498generator again. 15499@end deftypefn 15500@end ifnotinfo 15501 15502 15503 15504 15505@c 15506@c end of srou.h 15507@c ------------------------------------- 15508@c ------------------------------------- 15509@c ssr.h 15510@c 15511 15512@page 15513@node SSR 15514@subsection SSR -- Simple Setup Rejection 15515 15516@table @i 15517@item Required: 15518T-concave PDF, mode, area 15519@item Speed: 15520Set-up: fast, Sampling: slow 15521@item Reinit: 15522supported 15523@item Reference: 15524@ifhtml 15525@ref{bib:LJa01,, [LJa01]} 15526@end ifhtml 15527@ifnothtml 15528[LJa01] 15529@end ifnothtml 15530@ifhtml 15531@ref{bib:HLD04,, [HLD04: Sect.6.3.3; Alg.6.6]} 15532@end ifhtml 15533@ifnothtml 15534[HLD04: Sect.6.3.3; Alg.6.6] 15535@end ifnothtml 15536 15537@end table 15538@sp 1 15539 15540 15541SSR is an acceptance/rejection method that uses universal 15542inequalities for constructing (universal) hats and squeezes 15543(@pxref{Rejection}). 15544It works for all @i{T}-concave distributions with 15545@iftex 15546@math{T(x) = -1/\sqrt{x}.} 15547@end iftex 15548@ifhtml 15549@html 15550<I>T</I>(<I>x</I>) = -1/sqrt(<I>x</I>). 15551@end html 15552@end ifhtml 15553@ifinfo 15554@math{T(x) = -1/sqrt(x).} 15555@end ifinfo 15556 15557It requires the PDF, the (exact) location of the mode and the 15558area below the given PDF. The rejection constant is 4 for all 15559@i{T}-concave distributions with unbounded domain and is less 15560than 4 when the domain is bounded. Optionally the CDF at the 15561mode can be given to increase the performance of the algorithm. 15562Then the rejection constant is at most 2 and a universal squeeze 15563can (but need not be) used. However, using squeezes is not 15564recommended unless the evaluation of the PDF is expensive. 15565 15566The exact location of the mode and/or the area below the PDF can 15567be replace by appropriate bounds. Then the algorithm still works 15568but has larger rejection constants. 15569 15570 15571@subsubheading How To Use 15572 15573 15574SSR works for any continuous univariate distribution object with 15575given @i{T}-concave PDF (with 15576@iftex 15577@math{T(x) = -1/\sqrt{x},)} 15578@end iftex 15579@ifhtml 15580@html 15581<I>T</I>(<I>x</I>) = -1/sqrt(<I>x</I>),) 15582@end html 15583@end ifhtml 15584@ifinfo 15585@math{T(x) = -1/sqrt(x),)} 15586@end ifinfo 15587mode and area below PDF. Optional the CDF at the mode 15588can be given to increase the performance of the algorithm by 15589means of the 15590@ifhtml 15591@ref{funct:unur_ssr_set_cdfatmode,@command{unur_ssr_set_cdfatmode}} 15592@end ifhtml 15593@ifnothtml 15594@command{unur_ssr_set_cdfatmode} 15595@end ifnothtml 15596call. Additionally 15597squeezes can be used and switched on via 15598@ifhtml 15599@ref{funct:unur_ssr_set_usesqueeze,@command{unur_ssr_set_usesqueeze}.} 15600@end ifhtml 15601@ifnothtml 15602@command{unur_ssr_set_usesqueeze}. 15603@end ifnothtml 15604If the (exact) area below the PDF is not known, then an upper 15605bound can be used instead (which of course increases the rejection 15606constant). But then the squeeze flag must not be set and 15607@ifhtml 15608@ref{funct:unur_ssr_set_cdfatmode,@command{unur_ssr_set_cdfatmode}} 15609@end ifhtml 15610@ifnothtml 15611@command{unur_ssr_set_cdfatmode} 15612@end ifnothtml 15613must not be used. 15614 15615If the exact location of the mode is not known, then use the 15616approximate location and provide the (exact) value of the PDF at 15617the mode by means of the 15618@ifhtml 15619@ref{funct:unur_ssr_set_pdfatmode,@command{unur_ssr_set_pdfatmode}} 15620@end ifhtml 15621@ifnothtml 15622@command{unur_ssr_set_pdfatmode} 15623@end ifnothtml 15624call. But then 15625@ifhtml 15626@ref{funct:unur_ssr_set_cdfatmode,@command{unur_ssr_set_cdfatmode}} 15627@end ifhtml 15628@ifnothtml 15629@command{unur_ssr_set_cdfatmode} 15630@end ifnothtml 15631must not be used. Notice, that a (slow) 15632numerical mode finder will be used if no mode is given at all. 15633It is even possible to give an upper bound for the PDF only. 15634However, then the (upper bound for the) area below the PDF has to be 15635multiplied by the ratio between the upper bound and the lower bound of 15636the PDF at the mode. Again setting the squeeze flag and using 15637@ifhtml 15638@ref{funct:unur_ssr_set_cdfatmode,@command{unur_ssr_set_cdfatmode}} 15639@end ifhtml 15640@ifnothtml 15641@command{unur_ssr_set_cdfatmode} 15642@end ifnothtml 15643is not allowed. 15644 15645It is possible to change the parameters and the domain of the chosen 15646distribution and run 15647@ifhtml 15648@ref{funct:unur_reinit,@command{unur_reinit}} 15649@end ifhtml 15650@ifnothtml 15651@command{unur_reinit} 15652@end ifnothtml 15653to reinitialize the generator object. 15654Notice, that derived parameters like the mode must also be (re-) set 15655if the parameters or the domain has be changed. 15656Moreover, if the PDF at the mode has been provided by a 15657@ifhtml 15658@ref{funct:unur_ssr_set_pdfatmode,@command{unur_ssr_set_pdfatmode}} 15659@end ifhtml 15660@ifnothtml 15661@command{unur_ssr_set_pdfatmode} 15662@end ifnothtml 15663call, additionally 15664@ifhtml 15665@ref{funct:unur_ssr_chg_pdfatmode,@command{unur_ssr_chg_pdfatmode}} 15666@end ifhtml 15667@ifnothtml 15668@command{unur_ssr_chg_pdfatmode} 15669@end ifnothtml 15670must be used (otherwise this call is 15671not necessary since then this figure is computed directly from 15672the PDF). 15673 15674@emph{Important:} 15675If any of mode, PDF or CDF at the mode, or the area below the mode 15676has been changed, then 15677@ifhtml 15678@ref{funct:unur_reinit,@command{unur_reinit}} 15679@end ifhtml 15680@ifnothtml 15681@command{unur_reinit} 15682@end ifnothtml 15683must be executed. 15684(Otherwise the generator produces garbage). 15685 15686There exists a test mode that verifies whether the conditions for 15687the method are satisfied or not while sampling. It can be 15688switched on/off by calling 15689@ifhtml 15690@ref{funct:unur_ssr_set_verify,@command{unur_ssr_set_verify}} 15691@end ifhtml 15692@ifnothtml 15693@command{unur_ssr_set_verify} 15694@end ifnothtml 15695and 15696@ifhtml 15697@ref{funct:unur_ssr_chg_verify,@command{unur_ssr_chg_verify},} 15698@end ifhtml 15699@ifnothtml 15700@command{unur_ssr_chg_verify}, 15701@end ifnothtml 15702respectively. 15703Notice, however, that sampling is (a little bit) slower then. 15704 15705 15706 15707 15708@subheading Function reference 15709 15710@ifhtml 15711@itemize 15712@item @ref{funct:unur_ssr_new,unur_ssr_new} 15713@item @ref{funct:unur_ssr_set_cdfatmode,unur_ssr_set_cdfatmode} 15714@item @ref{funct:unur_ssr_set_pdfatmode,unur_ssr_set_pdfatmode} 15715@item @ref{funct:unur_ssr_set_usesqueeze,unur_ssr_set_usesqueeze} 15716@item @ref{funct:unur_ssr_set_verify,unur_ssr_set_verify} 15717@item @ref{funct:unur_ssr_chg_verify,unur_ssr_chg_verify} 15718@item @ref{funct:unur_ssr_chg_cdfatmode,unur_ssr_chg_cdfatmode} 15719@item @ref{funct:unur_ssr_chg_pdfatmode,unur_ssr_chg_pdfatmode} 15720@end itemize 15721@end ifhtml 15722 15723 15724@ifinfo 15725@anchor{funct:unur_ssr_new} 15726@deftypefn Function {UNUR_PAR*} unur_ssr_new (const @var{UNUR_DISTR* distribution}) 15727Get default parameters for generator. 15728@end deftypefn 15729@end ifinfo 15730@ifnotinfo 15731@anchor{funct:unur_ssr_new} 15732@deftypefn {} {UNUR_PAR*} unur_ssr_new (const @var{UNUR_DISTR* distribution}) 15733Get default parameters for generator. 15734@end deftypefn 15735@end ifnotinfo 15736 15737@ifinfo 15738@anchor{funct:unur_ssr_set_cdfatmode} 15739@deftypefn Function {int} unur_ssr_set_cdfatmode (UNUR_PAR* @var{parameters}, double @var{Fmode}) 15740Set CDF at mode. 15741When set, the performance of the algorithm is increased by factor 2. 15742However, when the parameters of the distribution are changed 15743@ifhtml 15744@ref{funct:unur_ssr_chg_cdfatmode,@command{unur_ssr_chg_cdfatmode}} 15745@end ifhtml 15746@ifnothtml 15747@command{unur_ssr_chg_cdfatmode} 15748@end ifnothtml 15749has to be used to update this value. 15750 15751Default: not set. 15752@end deftypefn 15753@end ifinfo 15754@ifnotinfo 15755@anchor{funct:unur_ssr_set_cdfatmode} 15756@deftypefn {} {int} unur_ssr_set_cdfatmode (UNUR_PAR* @var{parameters}, double @var{Fmode}) 15757Set CDF at mode. 15758When set, the performance of the algorithm is increased by factor 2. 15759However, when the parameters of the distribution are changed 15760@ifhtml 15761@ref{funct:unur_ssr_chg_cdfatmode,@command{unur_ssr_chg_cdfatmode}} 15762@end ifhtml 15763@ifnothtml 15764@command{unur_ssr_chg_cdfatmode} 15765@end ifnothtml 15766has to be used to update this value. 15767 15768Default: not set. 15769@end deftypefn 15770@end ifnotinfo 15771 15772@ifinfo 15773@anchor{funct:unur_ssr_set_pdfatmode} 15774@deftypefn Function {int} unur_ssr_set_pdfatmode (UNUR_PAR* @var{parameters}, double @var{fmode}) 15775Set pdf at mode. 15776When set, the PDF at the mode is never changed. 15777This is to avoid additional computations, when the PDF does not 15778change when parameters of the distributions vary. 15779It is only useful when the PDF at the mode does not change with 15780changing parameters for the distribution. 15781 15782Default: not set. 15783@end deftypefn 15784@end ifinfo 15785@ifnotinfo 15786@anchor{funct:unur_ssr_set_pdfatmode} 15787@deftypefn {} {int} unur_ssr_set_pdfatmode (UNUR_PAR* @var{parameters}, double @var{fmode}) 15788Set pdf at mode. 15789When set, the PDF at the mode is never changed. 15790This is to avoid additional computations, when the PDF does not 15791change when parameters of the distributions vary. 15792It is only useful when the PDF at the mode does not change with 15793changing parameters for the distribution. 15794 15795Default: not set. 15796@end deftypefn 15797@end ifnotinfo 15798 15799@ifinfo 15800@anchor{funct:unur_ssr_set_usesqueeze} 15801@deftypefn Function {int} unur_ssr_set_usesqueeze (UNUR_PAR* @var{parameters}, int @var{usesqueeze}) 15802Set flag for using universal squeeze (default: off). 15803Using squeezes is only useful when the evaluation of the PDF is 15804(extremely) expensive. 15805Using squeezes is automatically disabled when the CDF at the mode 15806is not given (then no universal squeezes exist). 15807 15808Default is @code{FALSE}. 15809@end deftypefn 15810@end ifinfo 15811@ifnotinfo 15812@anchor{funct:unur_ssr_set_usesqueeze} 15813@deftypefn {} {int} unur_ssr_set_usesqueeze (UNUR_PAR* @var{parameters}, int @var{usesqueeze}) 15814Set flag for using universal squeeze (default: off). 15815Using squeezes is only useful when the evaluation of the PDF is 15816(extremely) expensive. 15817Using squeezes is automatically disabled when the CDF at the mode 15818is not given (then no universal squeezes exist). 15819 15820Default is @code{FALSE}. 15821@end deftypefn 15822@end ifnotinfo 15823 15824@ifinfo 15825@anchor{funct:unur_ssr_set_verify} 15826@deftypefn Function {int} unur_ssr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 15827@anchor{funct:unur_ssr_chg_verify} 15828@deftypefnx Function {int} unur_ssr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 15829Turn verifying of algorithm while sampling on/off. 15830If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 15831violated for some @i{x} then @code{unur_errno} is set to 15832@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 15833happen due to round-off errors for a few values of 15834@i{x} (less than 1%). 15835 15836Default is @code{FALSE}. 15837@end deftypefn 15838@end ifinfo 15839@ifnotinfo 15840@anchor{funct:unur_ssr_set_verify} 15841@deftypefn {} {int} unur_ssr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 15842@anchor{funct:unur_ssr_chg_verify} 15843@deftypefnx {} {int} unur_ssr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 15844Turn verifying of algorithm while sampling on/off. 15845If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 15846violated for some @i{x} then @code{unur_errno} is set to 15847@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 15848happen due to round-off errors for a few values of 15849@i{x} (less than 1%). 15850 15851Default is @code{FALSE}. 15852@end deftypefn 15853@end ifnotinfo 15854 15855@ifinfo 15856@anchor{funct:unur_ssr_chg_cdfatmode} 15857@deftypefn Function {int} unur_ssr_chg_cdfatmode (UNUR_GEN* @var{generator}, double @var{Fmode}) 15858Change CDF at mode of distribution. 15859@ifhtml 15860@ref{funct:unur_reinit,@command{unur_reinit}} 15861@end ifhtml 15862@ifnothtml 15863@command{unur_reinit} 15864@end ifnothtml 15865must be executed before sampling from the 15866generator again. 15867@end deftypefn 15868@end ifinfo 15869@ifnotinfo 15870@anchor{funct:unur_ssr_chg_cdfatmode} 15871@deftypefn {} {int} unur_ssr_chg_cdfatmode (UNUR_GEN* @var{generator}, double @var{Fmode}) 15872Change CDF at mode of distribution. 15873@ifhtml 15874@ref{funct:unur_reinit,@command{unur_reinit}} 15875@end ifhtml 15876@ifnothtml 15877@command{unur_reinit} 15878@end ifnothtml 15879must be executed before sampling from the 15880generator again. 15881@end deftypefn 15882@end ifnotinfo 15883 15884@ifinfo 15885@anchor{funct:unur_ssr_chg_pdfatmode} 15886@deftypefn Function {int} unur_ssr_chg_pdfatmode (UNUR_GEN* @var{generator}, double @var{fmode}) 15887Change PDF at mode of distribution. 15888@ifhtml 15889@ref{funct:unur_reinit,@command{unur_reinit}} 15890@end ifhtml 15891@ifnothtml 15892@command{unur_reinit} 15893@end ifnothtml 15894must be executed before sampling from the 15895generator again. 15896@end deftypefn 15897@end ifinfo 15898@ifnotinfo 15899@anchor{funct:unur_ssr_chg_pdfatmode} 15900@deftypefn {} {int} unur_ssr_chg_pdfatmode (UNUR_GEN* @var{generator}, double @var{fmode}) 15901Change PDF at mode of distribution. 15902@ifhtml 15903@ref{funct:unur_reinit,@command{unur_reinit}} 15904@end ifhtml 15905@ifnothtml 15906@command{unur_reinit} 15907@end ifnothtml 15908must be executed before sampling from the 15909generator again. 15910@end deftypefn 15911@end ifnotinfo 15912 15913 15914 15915 15916@c 15917@c end of ssr.h 15918@c ------------------------------------- 15919@c ------------------------------------- 15920@c tabl.h 15921@c 15922 15923@page 15924@node TABL 15925@subsection TABL -- a TABLe method with piecewise constant hats 15926 15927@table @i 15928@item Required: 15929PDF, all local extrema, cut-off values for the tails 15930@item Optional: 15931approximate area 15932@item Speed: 15933Set-up: (very) slow, Sampling: fast 15934@item Reinit: 15935not implemented 15936@item Reference: 15937@ifhtml 15938@ref{bib:AJa93,, [AJa93]} 15939@end ifhtml 15940@ifnothtml 15941[AJa93] 15942@end ifnothtml 15943@ifhtml 15944@ref{bib:AJa95,, [AJa95]} 15945@end ifhtml 15946@ifnothtml 15947[AJa95] 15948@end ifnothtml 15949@ifhtml 15950@ref{bib:HLD04,, [HLD04: Cha.5.1]} 15951@end ifhtml 15952@ifnothtml 15953[HLD04: Cha.5.1] 15954@end ifnothtml 15955 15956@end table 15957@sp 1 15958 15959 15960TABL (called Ahrens method in 15961@ifhtml 15962@ref{bib:HLD04,, [HLD04]} 15963@end ifhtml 15964@ifnothtml 15965[HLD04] 15966@end ifnothtml 15967) 15968is an acceptance/rejection method (@pxref{Rejection}) that uses 15969a decomposition of the domain of the distribution into many 15970short subintervals. Inside of these subintervals constant hat 15971and squeeze functions are utilized. Thus it is easy to use the 15972idea of immediate acceptance for points below the squeeze. This 15973reduces the expected number of uniform random numbers per 15974generated random variate to less than two. Using a large number 15975of subintervals only little more than one random number is 15976necessary on average. Thus this method becomes very fast. 15977 15978Due to the constant hat function this method only works for 15979distributions with bounded domains. Thus for unbounded domains 15980the left and right tails have to be cut off. This is no problem 15981when the probability of falling into these tail regions is 15982beyond computational relevance (e.g. smaller than @code{1.e-12}). 15983 15984For easy construction of hat and squeeze functions it is necessary 15985to know the regions of monotonicity (called @emph{slopes}) or 15986equivalently all local maxima and minima of the density. 15987The main problem for this method in the setup is the choice of the 15988subintervals. A simple and close to optimal approach is the 15989"equal area rule" 15990@ifhtml 15991@ref{bib:HLD04,, [HLD04: Cha.5.1]} 15992@end ifhtml 15993@ifnothtml 15994[HLD04: Cha.5.1] 15995@end ifnothtml 15996. There the subintervals are 15997selected such that the area below the hat is the same for 15998each subinterval which can be realized with a simple recursion. 15999If more subintervals are necessary it is possible to split 16000either randomly chosen intervals (adaptive rejection sampling, ARS) 16001or those intervals, where the ratio between squeeze and hat is 16002smallest. This version of the setup is called derandomized ARS 16003(DARS). With the default settings TABL is first calculating 16004approximately 30 subintervals with the equal area rule. Then 16005DARS is used till the desired fit of the hat is reached. 16006 16007A convenient measure to control the quality of the fit of hat 16008and squeeze is the ratio (area below squeeze)/(area below hat) 16009called @code{sqhratio} which must be smaller or equal to one. 16010The expected number of iterations in the rejection algorithm 16011is known to be smaller than 1/sqhratio and the expected number 16012of evaluations of the density is bounded by @code{1/sqhratio - 1}. 16013So values of the sqhratio close to one (e.g. @code{0.95} or 16014@code{0.99}) lead to many subintervals. Thus a better fitting 16015hat is constructed and the sampling algorithm becomes fast; on 16016the other hand large tables are needed and the setup is very 16017slow. For moderate values of sqhratio (e.g. @code{0.9} or 16018@code{0.8}) the sampling is slower but the required tables are 16019smaller and the setup is not so slow. 16020 16021It follows from the above explanations that TABL is always 16022requiring a slow setup and that it is not very well suited for 16023heavy-tailed distributions. 16024 16025 16026@subsubheading How To Use 16027 16028 16029 16030For using the TABL method UNU.RAN needs a bounded interval to 16031which the generated variates can be restricted and information 16032about all local extrema of the distribution. For unimodal 16033densities it is sufficient to provide the mode of the 16034distribution. For the case of a built-in unimodal distribution 16035with bounded domain all these information is present in the 16036distribution object and thus no extra input is necessary (see 16037example_TABL1 below). 16038 16039For a built-in unimodal distribution with unbounded domain we 16040should specify the cut-off values for the tails. This can be 16041done with the 16042@ifhtml 16043@ref{funct:unur_tabl_set_boundary,@command{unur_tabl_set_boundary}} 16044@end ifhtml 16045@ifnothtml 16046@command{unur_tabl_set_boundary} 16047@end ifnothtml 16048call (see example_TABL2 16049below). For the case that we do not set these boundaries the 16050default values of @code{+/- 1.e20} are used. We can see in 16051example_TABL1 that this still works fine for many standard 16052distributions. 16053 16054For the case of a multimodal distribution we have to set the 16055regions of monotonicity (called slopes) explicitly using the 16056@ifhtml 16057@ref{funct:unur_tabl_set_slopes,@command{unur_tabl_set_slopes}} 16058@end ifhtml 16059@ifnothtml 16060@command{unur_tabl_set_slopes} 16061@end ifnothtml 16062command (see example_TABL3 below). 16063 16064To controll the fit of the hat and the size of the tables and 16065thus the speed of the setup and the sampling it is most 16066convenient to use the 16067@ifhtml 16068@ref{funct:unur_tabl_set_max_sqhratio,@command{unur_tabl_set_max_sqhratio}} 16069@end ifhtml 16070@ifnothtml 16071@command{unur_tabl_set_max_sqhratio} 16072@end ifnothtml 16073call. The 16074default is @code{0.9} which is a sensible value for most 16075distributions and applications. If very large samples of a 16076distribution are required or the evaluation of a density is very 16077slow it may be useful to increase the sqhratio to 16078eg. @code{0.95} or even @code{0.99}. With the 16079@ifhtml 16080@ref{funct:unur_tabl_get_sqhratio,@command{unur_tabl_get_sqhratio}} 16081@end ifhtml 16082@ifnothtml 16083@command{unur_tabl_get_sqhratio} 16084@end ifnothtml 16085call we can check which sqhratio was 16086really reached. If that value is below the desired value it is 16087necessary to increase the maximal number of subintervals, which 16088defaults to @code{1000}, using the 16089@ifhtml 16090@ref{funct:unur_tabl_set_max_intervals,@command{unur_tabl_set_max_intervals}} 16091@end ifhtml 16092@ifnothtml 16093@command{unur_tabl_set_max_intervals} 16094@end ifnothtml 16095call. 16096The 16097@ifhtml 16098@ref{funct:unur_tabl_get_n_intervals,@command{unur_tabl_get_n_intervals}} 16099@end ifhtml 16100@ifnothtml 16101@command{unur_tabl_get_n_intervals} 16102@end ifnothtml 16103call can be used to find out the 16104number of subintervals the setup calculated. 16105 16106It is also possible to set the number of intervals and their 16107respective boundaries by means of the 16108@ifhtml 16109@ref{funct:unur_tabl_set_cpoints,@command{unur_tabl_set_cpoints}} 16110@end ifhtml 16111@ifnothtml 16112@command{unur_tabl_set_cpoints} 16113@end ifnothtml 16114call. 16115 16116It is also possible to use method TABL for correlation induction 16117(variance reduction) by setting of an auxiliary uniform random 16118number generator via the 16119@ifhtml 16120@ref{funct:unur_set_urng_aux,@command{unur_set_urng_aux}} 16121@end ifhtml 16122@ifnothtml 16123@command{unur_set_urng_aux} 16124@end ifnothtml 16125call. (Notice that 16126this must be done after a possible 16127@ifhtml 16128@ref{funct:unur_set_urng,@command{unur_set_urng}} 16129@end ifhtml 16130@ifnothtml 16131@command{unur_set_urng} 16132@end ifnothtml 16133call.) 16134However, this only works when immediate acceptance is switched 16135of by a 16136@ifhtml 16137@ref{funct:unur_tabl_set_variant_ia,@command{unur_tabl_set_variant_ia}} 16138@end ifhtml 16139@ifnothtml 16140@command{unur_tabl_set_variant_ia} 16141@end ifnothtml 16142call. 16143 16144 16145 16146 16147@subheading Function reference 16148 16149@ifhtml 16150@itemize 16151@item @ref{funct:unur_tabl_new,unur_tabl_new} 16152@item @ref{funct:unur_tabl_set_variant_ia,unur_tabl_set_variant_ia} 16153@item @ref{funct:unur_tabl_set_cpoints,unur_tabl_set_cpoints} 16154@item @ref{funct:unur_tabl_set_nstp,unur_tabl_set_nstp} 16155@item @ref{funct:unur_tabl_set_useear,unur_tabl_set_useear} 16156@item @ref{funct:unur_tabl_set_areafraction,unur_tabl_set_areafraction} 16157@item @ref{funct:unur_tabl_set_usedars,unur_tabl_set_usedars} 16158@item @ref{funct:unur_tabl_set_darsfactor,unur_tabl_set_darsfactor} 16159@item @ref{funct:unur_tabl_set_variant_splitmode,unur_tabl_set_variant_splitmode} 16160@item @ref{funct:unur_tabl_set_max_sqhratio,unur_tabl_set_max_sqhratio} 16161@item @ref{funct:unur_tabl_get_sqhratio,unur_tabl_get_sqhratio} 16162@item @ref{funct:unur_tabl_get_hatarea,unur_tabl_get_hatarea} 16163@item @ref{funct:unur_tabl_get_squeezearea,unur_tabl_get_squeezearea} 16164@item @ref{funct:unur_tabl_set_max_intervals,unur_tabl_set_max_intervals} 16165@item @ref{funct:unur_tabl_get_n_intervals,unur_tabl_get_n_intervals} 16166@item @ref{funct:unur_tabl_set_slopes,unur_tabl_set_slopes} 16167@item @ref{funct:unur_tabl_set_guidefactor,unur_tabl_set_guidefactor} 16168@item @ref{funct:unur_tabl_set_boundary,unur_tabl_set_boundary} 16169@item @ref{funct:unur_tabl_chg_truncated,unur_tabl_chg_truncated} 16170@item @ref{funct:unur_tabl_set_verify,unur_tabl_set_verify} 16171@item @ref{funct:unur_tabl_chg_verify,unur_tabl_chg_verify} 16172@item @ref{funct:unur_tabl_set_pedantic,unur_tabl_set_pedantic} 16173@end itemize 16174@end ifhtml 16175 16176 16177@ifinfo 16178@anchor{funct:unur_tabl_new} 16179@deftypefn Function {UNUR_PAR*} unur_tabl_new (const @var{UNUR_DISTR* distribution}) 16180Get default parameters for generator. 16181@end deftypefn 16182@end ifinfo 16183@ifnotinfo 16184@anchor{funct:unur_tabl_new} 16185@deftypefn {} {UNUR_PAR*} unur_tabl_new (const @var{UNUR_DISTR* distribution}) 16186Get default parameters for generator. 16187@end deftypefn 16188@end ifnotinfo 16189 16190@ifinfo 16191@anchor{funct:unur_tabl_set_variant_ia} 16192@deftypefn Function {int} unur_tabl_set_variant_ia (UNUR_PAR* @var{parameters}, int @var{use_ia}) 16193Use immediate acceptance when @var{use_ia} is set to @code{TRUE}. 16194This technique requires less uniform. If it is set to @code{FALSE}, 16195``classical'' acceptance/rejection from hat distribution 16196is used. 16197 16198@emph{Notice:} Auxiliary uniform random number generators for 16199correlation induction (variance reduction) can only be used when 16200``classical'' acceptance/rejection is used. 16201 16202Default: @code{TRUE}. 16203@end deftypefn 16204@end ifinfo 16205@ifnotinfo 16206@anchor{funct:unur_tabl_set_variant_ia} 16207@deftypefn {} {int} unur_tabl_set_variant_ia (UNUR_PAR* @var{parameters}, int @var{use_ia}) 16208Use immediate acceptance when @var{use_ia} is set to @code{TRUE}. 16209This technique requires less uniform. If it is set to @code{FALSE}, 16210``classical'' acceptance/rejection from hat distribution 16211is used. 16212 16213@emph{Notice:} Auxiliary uniform random number generators for 16214correlation induction (variance reduction) can only be used when 16215``classical'' acceptance/rejection is used. 16216 16217Default: @code{TRUE}. 16218@end deftypefn 16219@end ifnotinfo 16220 16221@ifinfo 16222@anchor{funct:unur_tabl_set_cpoints} 16223@deftypefn Function {int} unur_tabl_set_cpoints (UNUR_PAR* @var{parameters}, int @var{n_cpoints}, const @var{double* cpoints}) 16224Set construction points for the hat function. If @var{stp} is @code{NULL} 16225than a heuristic rule of thumb is used to get @var{n_stp} 16226construction points. This is the default behavior. 16227 16228The default number of construction points is @code{30}. 16229@end deftypefn 16230@end ifinfo 16231@ifnotinfo 16232@anchor{funct:unur_tabl_set_cpoints} 16233@deftypefn {} {int} unur_tabl_set_cpoints (UNUR_PAR* @var{parameters}, int @var{n_cpoints}, const @var{double* cpoints}) 16234Set construction points for the hat function. If @var{stp} is @code{NULL} 16235than a heuristic rule of thumb is used to get @var{n_stp} 16236construction points. This is the default behavior. 16237 16238The default number of construction points is @code{30}. 16239@end deftypefn 16240@end ifnotinfo 16241 16242@ifinfo 16243@anchor{funct:unur_tabl_set_nstp} 16244@deftypefn Function {int} unur_tabl_set_nstp (UNUR_PAR* @var{parameters}, int @var{n_stp}) 16245Set number of construction points for the hat function. @var{n_stp} 16246must be greater than zero. After the setup there are about 16247@var{n_stp} construction points. However it might be larger when a 16248small fraction is given by the 16249@ifhtml 16250@ref{funct:unur_tabl_set_areafraction,@command{unur_tabl_set_areafraction}} 16251@end ifhtml 16252@ifnothtml 16253@command{unur_tabl_set_areafraction} 16254@end ifnothtml 16255call. 16256It also might be smaller for some variants. 16257 16258Default is @code{30}. 16259@end deftypefn 16260@end ifinfo 16261@ifnotinfo 16262@anchor{funct:unur_tabl_set_nstp} 16263@deftypefn {} {int} unur_tabl_set_nstp (UNUR_PAR* @var{parameters}, int @var{n_stp}) 16264Set number of construction points for the hat function. @var{n_stp} 16265must be greater than zero. After the setup there are about 16266@var{n_stp} construction points. However it might be larger when a 16267small fraction is given by the 16268@ifhtml 16269@ref{funct:unur_tabl_set_areafraction,@command{unur_tabl_set_areafraction}} 16270@end ifhtml 16271@ifnothtml 16272@command{unur_tabl_set_areafraction} 16273@end ifnothtml 16274call. 16275It also might be smaller for some variants. 16276 16277Default is @code{30}. 16278@end deftypefn 16279@end ifnotinfo 16280 16281@ifinfo 16282@anchor{funct:unur_tabl_set_useear} 16283@deftypefn Function {int} unur_tabl_set_useear (UNUR_PAR* @var{parameters}, int @var{useear}) 16284If @var{useear} is set to @code{TRUE}, the ``equal area rule'' is used, 16285the given slopes are partitioned in such a way that the area below 16286the hat function in each subinterval (``stripe'') has the same 16287area (except the last the last interval which can be smaller). 16288The area can be set by means of the 16289@ifhtml 16290@ref{funct:unur_tabl_set_areafraction,@command{unur_tabl_set_areafraction}} 16291@end ifhtml 16292@ifnothtml 16293@command{unur_tabl_set_areafraction} 16294@end ifnothtml 16295call. 16296 16297Default is @code{TRUE}. 16298@end deftypefn 16299@end ifinfo 16300@ifnotinfo 16301@anchor{funct:unur_tabl_set_useear} 16302@deftypefn {} {int} unur_tabl_set_useear (UNUR_PAR* @var{parameters}, int @var{useear}) 16303If @var{useear} is set to @code{TRUE}, the ``equal area rule'' is used, 16304the given slopes are partitioned in such a way that the area below 16305the hat function in each subinterval (``stripe'') has the same 16306area (except the last the last interval which can be smaller). 16307The area can be set by means of the 16308@ifhtml 16309@ref{funct:unur_tabl_set_areafraction,@command{unur_tabl_set_areafraction}} 16310@end ifhtml 16311@ifnothtml 16312@command{unur_tabl_set_areafraction} 16313@end ifnothtml 16314call. 16315 16316Default is @code{TRUE}. 16317@end deftypefn 16318@end ifnotinfo 16319 16320@ifinfo 16321@anchor{funct:unur_tabl_set_areafraction} 16322@deftypefn Function {int} unur_tabl_set_areafraction (UNUR_PAR* @var{parameters}, double @var{fraction}) 16323Set parameter for the equal area rule. During the setup a piecewise 16324constant hat is constructed, such that the area below each of these 16325pieces (strips) is the same and equal to the (given) area below the 16326PDF times @var{fraction} (which must be greater than 16327zero). 16328 16329@emph{Important:} If the area below the PDF is not set in the 16330distribution object, then 1 is assumed. 16331 16332Default is @code{0.1}. 16333@end deftypefn 16334@end ifinfo 16335@ifnotinfo 16336@anchor{funct:unur_tabl_set_areafraction} 16337@deftypefn {} {int} unur_tabl_set_areafraction (UNUR_PAR* @var{parameters}, double @var{fraction}) 16338Set parameter for the equal area rule. During the setup a piecewise 16339constant hat is constructed, such that the area below each of these 16340pieces (strips) is the same and equal to the (given) area below the 16341PDF times @var{fraction} (which must be greater than 16342zero). 16343 16344@emph{Important:} If the area below the PDF is not set in the 16345distribution object, then 1 is assumed. 16346 16347Default is @code{0.1}. 16348@end deftypefn 16349@end ifnotinfo 16350 16351@ifinfo 16352@anchor{funct:unur_tabl_set_usedars} 16353@deftypefn Function {int} unur_tabl_set_usedars (UNUR_PAR* @var{parameters}, int @var{usedars}) 16354If @var{usedars} is set to @code{TRUE}, ``derandomized adaptive rejection 16355sampling'' (DARS) is used in the setup. 16356Intervals, where the area between hat and squeeze is too 16357large compared to the average area between hat and squeeze 16358over all intervals, are split. 16359This procedure is repeated until the ratio between squeeze and hat 16360exceeds the bound given by 16361@ifhtml 16362@ref{funct:unur_tabl_set_max_sqhratio,@command{unur_tabl_set_max_sqhratio}} 16363@end ifhtml 16364@ifnothtml 16365@command{unur_tabl_set_max_sqhratio} 16366@end ifnothtml 16367call or the 16368maximum number of intervals is reached. Moreover, it also aborts 16369when no more intervals can be found for splitting. 16370 16371For finding splitting points the arc-mean rule (a mixture of 16372arithmetic mean and harmonic mean) is used. 16373 16374Default is @code{TRUE}. 16375@end deftypefn 16376@end ifinfo 16377@ifnotinfo 16378@anchor{funct:unur_tabl_set_usedars} 16379@deftypefn {} {int} unur_tabl_set_usedars (UNUR_PAR* @var{parameters}, int @var{usedars}) 16380If @var{usedars} is set to @code{TRUE}, ``derandomized adaptive rejection 16381sampling'' (DARS) is used in the setup. 16382Intervals, where the area between hat and squeeze is too 16383large compared to the average area between hat and squeeze 16384over all intervals, are split. 16385This procedure is repeated until the ratio between squeeze and hat 16386exceeds the bound given by 16387@ifhtml 16388@ref{funct:unur_tabl_set_max_sqhratio,@command{unur_tabl_set_max_sqhratio}} 16389@end ifhtml 16390@ifnothtml 16391@command{unur_tabl_set_max_sqhratio} 16392@end ifnothtml 16393call or the 16394maximum number of intervals is reached. Moreover, it also aborts 16395when no more intervals can be found for splitting. 16396 16397For finding splitting points the arc-mean rule (a mixture of 16398arithmetic mean and harmonic mean) is used. 16399 16400Default is @code{TRUE}. 16401@end deftypefn 16402@end ifnotinfo 16403 16404@ifinfo 16405@anchor{funct:unur_tabl_set_darsfactor} 16406@deftypefn Function {int} unur_tabl_set_darsfactor (UNUR_PAR* @var{parameters}, double @var{factor}) 16407Set factor for ``derandomized adaptive rejection sampling''. 16408This factor is used to determine the segments that are ``too 16409large'', that is, all segments where the area between squeeze and 16410hat is larger than @var{factor} times the average area over all 16411intervals between squeeze and hat. 16412Notice that all segments are split when @var{factor} is set to 16413@code{0.}, and that there is no splitting at all when @var{factor} 16414is set to @code{UNUR_INFINITY}. 16415 16416Default is @code{0.99}. There is no need to change this parameter. 16417@end deftypefn 16418@end ifinfo 16419@ifnotinfo 16420@anchor{funct:unur_tabl_set_darsfactor} 16421@deftypefn {} {int} unur_tabl_set_darsfactor (UNUR_PAR* @var{parameters}, double @var{factor}) 16422Set factor for ``derandomized adaptive rejection sampling''. 16423This factor is used to determine the segments that are ``too 16424large'', that is, all segments where the area between squeeze and 16425hat is larger than @var{factor} times the average area over all 16426intervals between squeeze and hat. 16427Notice that all segments are split when @var{factor} is set to 16428@code{0.}, and that there is no splitting at all when @var{factor} 16429is set to @code{UNUR_INFINITY}. 16430 16431Default is @code{0.99}. There is no need to change this parameter. 16432@end deftypefn 16433@end ifnotinfo 16434 16435@ifinfo 16436@anchor{funct:unur_tabl_set_variant_splitmode} 16437@deftypefn Function {int} unur_tabl_set_variant_splitmode (UNUR_PAR* @var{parameters}, unsigned @var{splitmode}) 16438There are three variants for adaptive rejection sampling. These 16439differ in the way how an interval is split: 16440@table @r 16441@item splitmode @code{1} 16442use the generated point to split the interval. 16443@item splitmode @code{2} 16444use the mean point of the interval. 16445@item splitmode @code{3} 16446use the arcmean point; 16447suggested for distributions with heavy tails. 16448 16449@end table 16450Default is splitmode @code{2}. 16451@end deftypefn 16452@end ifinfo 16453@ifnotinfo 16454@anchor{funct:unur_tabl_set_variant_splitmode} 16455@deftypefn {} {int} unur_tabl_set_variant_splitmode (UNUR_PAR* @var{parameters}, unsigned @var{splitmode}) 16456There are three variants for adaptive rejection sampling. These 16457differ in the way how an interval is split: 16458@table @r 16459@item splitmode @code{1} 16460use the generated point to split the interval. 16461@item splitmode @code{2} 16462use the mean point of the interval. 16463@item splitmode @code{3} 16464use the arcmean point; 16465suggested for distributions with heavy tails. 16466 16467@end table 16468Default is splitmode @code{2}. 16469@end deftypefn 16470@end ifnotinfo 16471 16472@ifinfo 16473@anchor{funct:unur_tabl_set_max_sqhratio} 16474@deftypefn Function {int} unur_tabl_set_max_sqhratio (UNUR_PAR* @var{parameters}, double @var{max_ratio}) 16475Set upper bound for the 16476ratio (area below squeeze) / (area below hat). 16477It must be a number between 0 and 1. 16478When the ratio exceeds the given number no further construction 16479points are inserted via DARS in the setup. 16480 16481For the case of ARS (unur_tabl_set_usedars() must be set to @code{FALSE}): 16482Use @code{0} if no construction points should be added after the setup. 16483Use @code{1} if added new construction points should not be stopped 16484until the maximum number of construction points is reached. 16485If @var{max_ratio} is close to one, many construction points are used. 16486 16487Default is @code{0.9}. 16488@end deftypefn 16489@end ifinfo 16490@ifnotinfo 16491@anchor{funct:unur_tabl_set_max_sqhratio} 16492@deftypefn {} {int} unur_tabl_set_max_sqhratio (UNUR_PAR* @var{parameters}, double @var{max_ratio}) 16493Set upper bound for the 16494ratio (area below squeeze) / (area below hat). 16495It must be a number between 0 and 1. 16496When the ratio exceeds the given number no further construction 16497points are inserted via DARS in the setup. 16498 16499For the case of ARS (unur_tabl_set_usedars() must be set to @code{FALSE}): 16500Use @code{0} if no construction points should be added after the setup. 16501Use @code{1} if added new construction points should not be stopped 16502until the maximum number of construction points is reached. 16503If @var{max_ratio} is close to one, many construction points are used. 16504 16505Default is @code{0.9}. 16506@end deftypefn 16507@end ifnotinfo 16508 16509@ifinfo 16510@anchor{funct:unur_tabl_get_sqhratio} 16511@deftypefn Function {double} unur_tabl_get_sqhratio (const @var{UNUR_GEN* generator}) 16512Get the current ratio (area below squeeze) / (area below hat) 16513for the generator. 16514(In case of an error @code{UNUR_INFINITY} is returned.) 16515@end deftypefn 16516@end ifinfo 16517@ifnotinfo 16518@anchor{funct:unur_tabl_get_sqhratio} 16519@deftypefn {} {double} unur_tabl_get_sqhratio (const @var{UNUR_GEN* generator}) 16520Get the current ratio (area below squeeze) / (area below hat) 16521for the generator. 16522(In case of an error @code{UNUR_INFINITY} is returned.) 16523@end deftypefn 16524@end ifnotinfo 16525 16526@ifinfo 16527@anchor{funct:unur_tabl_get_hatarea} 16528@deftypefn Function {double} unur_tabl_get_hatarea (const @var{UNUR_GEN* generator}) 16529Get the area below the hat for the generator. 16530(In case of an error @code{UNUR_INFINITY} is returned.) 16531@end deftypefn 16532@end ifinfo 16533@ifnotinfo 16534@anchor{funct:unur_tabl_get_hatarea} 16535@deftypefn {} {double} unur_tabl_get_hatarea (const @var{UNUR_GEN* generator}) 16536Get the area below the hat for the generator. 16537(In case of an error @code{UNUR_INFINITY} is returned.) 16538@end deftypefn 16539@end ifnotinfo 16540 16541@ifinfo 16542@anchor{funct:unur_tabl_get_squeezearea} 16543@deftypefn Function {double} unur_tabl_get_squeezearea (const @var{UNUR_GEN* generator}) 16544Get the area below the squeeze for the generator. 16545(In case of an error @code{UNUR_INFINITY} is returned.) 16546@end deftypefn 16547@end ifinfo 16548@ifnotinfo 16549@anchor{funct:unur_tabl_get_squeezearea} 16550@deftypefn {} {double} unur_tabl_get_squeezearea (const @var{UNUR_GEN* generator}) 16551Get the area below the squeeze for the generator. 16552(In case of an error @code{UNUR_INFINITY} is returned.) 16553@end deftypefn 16554@end ifnotinfo 16555 16556@ifinfo 16557@anchor{funct:unur_tabl_set_max_intervals} 16558@deftypefn Function {int} unur_tabl_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 16559Set maximum number of intervals. 16560No construction points are added in or after the setup when the 16561number of intervals suceeds @var{max_ivs}. 16562 16563Default is @code{1000}. 16564@end deftypefn 16565@end ifinfo 16566@ifnotinfo 16567@anchor{funct:unur_tabl_set_max_intervals} 16568@deftypefn {} {int} unur_tabl_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 16569Set maximum number of intervals. 16570No construction points are added in or after the setup when the 16571number of intervals suceeds @var{max_ivs}. 16572 16573Default is @code{1000}. 16574@end deftypefn 16575@end ifnotinfo 16576 16577@ifinfo 16578@anchor{funct:unur_tabl_get_n_intervals} 16579@deftypefn Function {int} unur_tabl_get_n_intervals (const @var{UNUR_GEN* generator}) 16580Get the current number of intervals. 16581(In case of an error 0 is returned.) 16582@end deftypefn 16583@end ifinfo 16584@ifnotinfo 16585@anchor{funct:unur_tabl_get_n_intervals} 16586@deftypefn {} {int} unur_tabl_get_n_intervals (const @var{UNUR_GEN* generator}) 16587Get the current number of intervals. 16588(In case of an error 0 is returned.) 16589@end deftypefn 16590@end ifnotinfo 16591 16592@ifinfo 16593@anchor{funct:unur_tabl_set_slopes} 16594@deftypefn Function {int} unur_tabl_set_slopes (UNUR_PAR* @var{parameters}, const @var{double* slopes}, int @var{n_slopes}) 16595Set slopes for the PDF. 16596A slope <a,b> is an interval [a,b] or [b,a] where the PDF is 16597monotone and PDF(a) >= PDF(b). 16598The list of slopes is given by an array @var{slopes} where each 16599consecutive tuple (i.e. @code{(slopes[0], slopes[1])}, 16600@code{(slopes[2], slopes[3])}, etc.) defines one slope. 16601Slopes must be sorted (i.e. both @code{slopes[0]} and 16602@code{slopes[1]} must not be greater than any entry of the slope 16603@code{(slopes[2], slopes[3])}, etc.) 16604and must not be overlapping. Otherwise no slopes are set and 16605@var{unur_errno} is set to @code{UNUR_ERR_PAR_SET}. 16606 16607@emph{Notice:} @var{n_slopes} is the number of slopes (and not the 16608length of the array @var{slopes}). 16609 16610@emph{Notice} that setting slopes resets the given domain for the 16611distribution. However, in case of a standard distribution the area 16612below the PDF is not updated. 16613@end deftypefn 16614@end ifinfo 16615@ifnotinfo 16616@anchor{funct:unur_tabl_set_slopes} 16617@deftypefn {} {int} unur_tabl_set_slopes (UNUR_PAR* @var{parameters}, const @var{double* slopes}, int @var{n_slopes}) 16618Set slopes for the PDF. 16619A slope <a,b> is an interval [a,b] or [b,a] where the PDF is 16620monotone and PDF(a) >= PDF(b). 16621The list of slopes is given by an array @var{slopes} where each 16622consecutive tuple (i.e. @code{(slopes[0], slopes[1])}, 16623@code{(slopes[2], slopes[3])}, etc.) defines one slope. 16624Slopes must be sorted (i.e. both @code{slopes[0]} and 16625@code{slopes[1]} must not be greater than any entry of the slope 16626@code{(slopes[2], slopes[3])}, etc.) 16627and must not be overlapping. Otherwise no slopes are set and 16628@var{unur_errno} is set to @code{UNUR_ERR_PAR_SET}. 16629 16630@emph{Notice:} @var{n_slopes} is the number of slopes (and not the 16631length of the array @var{slopes}). 16632 16633@emph{Notice} that setting slopes resets the given domain for the 16634distribution. However, in case of a standard distribution the area 16635below the PDF is not updated. 16636@end deftypefn 16637@end ifnotinfo 16638 16639@ifinfo 16640@anchor{funct:unur_tabl_set_guidefactor} 16641@deftypefn Function {int} unur_tabl_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 16642Set factor for relative size of the guide table for indexed search 16643(see also method DGT @ref{DGT}). It must be greater than or equal 16644to @code{0}. 16645When set to @code{0}, then sequential search is used. 16646 16647Default is @code{1}. 16648@end deftypefn 16649@end ifinfo 16650@ifnotinfo 16651@anchor{funct:unur_tabl_set_guidefactor} 16652@deftypefn {} {int} unur_tabl_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 16653Set factor for relative size of the guide table for indexed search 16654(see also method DGT @ref{DGT}). It must be greater than or equal 16655to @code{0}. 16656When set to @code{0}, then sequential search is used. 16657 16658Default is @code{1}. 16659@end deftypefn 16660@end ifnotinfo 16661 16662@ifinfo 16663@anchor{funct:unur_tabl_set_boundary} 16664@deftypefn Function {int} unur_tabl_set_boundary (UNUR_PAR* @var{parameters}, double @var{left}, double @var{right}) 16665Set the left and right boundary of the computation interval. 16666The piecewise hat is only constructed inside this interval. The 16667probability outside of this region must not be of 16668computational relevance. 16669Of course @code{+/- UNUR_INFINITY} is not allowed. 16670 16671Default is @code{-1.e20,1.e20}. 16672@end deftypefn 16673@end ifinfo 16674@ifnotinfo 16675@anchor{funct:unur_tabl_set_boundary} 16676@deftypefn {} {int} unur_tabl_set_boundary (UNUR_PAR* @var{parameters}, double @var{left}, double @var{right}) 16677Set the left and right boundary of the computation interval. 16678The piecewise hat is only constructed inside this interval. The 16679probability outside of this region must not be of 16680computational relevance. 16681Of course @code{+/- UNUR_INFINITY} is not allowed. 16682 16683Default is @code{-1.e20,1.e20}. 16684@end deftypefn 16685@end ifnotinfo 16686 16687@ifinfo 16688@anchor{funct:unur_tabl_chg_truncated} 16689@deftypefn Function {int} unur_tabl_chg_truncated (UNUR_GEN* @var{gen}, double @var{left}, double @var{right}) 16690Change the borders of the domain of the (truncated) distribution. 16691 16692Notice that the given truncated domain must be a subset of the 16693domain of the given distribution. The generator always uses the 16694intersection of the domain of the distribution and the truncated 16695domain given by this call. The hat function will not be changed. 16696 16697@emph{Important:} 16698The ratio between the area below the hat and the area below the 16699squeeze changes when the sampling region is restricted. In particalur 16700it becomes (very) large when sampling from the (far) tail of the 16701distribution. Then it is better to create a generator object for the 16702tail of distribution only. 16703 16704@emph{Important:} 16705This call does not work for variant @code{IA} (immediate 16706acceptance). In this case UNU.RAN switches @emph{automatically} to 16707variant @code{RH} (use ``classical'' acceptance/rejection from hat 16708distribution) and does revert to the variant originally set by the 16709user. 16710 16711@emph{Important:} 16712It is not a good idea to use adaptave rejection sampling while 16713sampling from a domain that is a strict subset of the domain that 16714has been used to construct the hat. 16715For that reason adaptive adding of construction points is 16716@emph{automatically disabled} by this call. 16717 16718@emph{Important:} If the CDF of the hat is (almost) the same 16719for @var{left} and @var{right} and (almost) equal to @code{0} or 16720@code{1}, then the truncated domain is not changed and the call 16721returns an error code. 16722@end deftypefn 16723@end ifinfo 16724@ifnotinfo 16725@anchor{funct:unur_tabl_chg_truncated} 16726@deftypefn {} {int} unur_tabl_chg_truncated (UNUR_GEN* @var{gen}, double @var{left}, double @var{right}) 16727Change the borders of the domain of the (truncated) distribution. 16728 16729Notice that the given truncated domain must be a subset of the 16730domain of the given distribution. The generator always uses the 16731intersection of the domain of the distribution and the truncated 16732domain given by this call. The hat function will not be changed. 16733 16734@emph{Important:} 16735The ratio between the area below the hat and the area below the 16736squeeze changes when the sampling region is restricted. In particalur 16737it becomes (very) large when sampling from the (far) tail of the 16738distribution. Then it is better to create a generator object for the 16739tail of distribution only. 16740 16741@emph{Important:} 16742This call does not work for variant @code{IA} (immediate 16743acceptance). In this case UNU.RAN switches @emph{automatically} to 16744variant @code{RH} (use ``classical'' acceptance/rejection from hat 16745distribution) and does revert to the variant originally set by the 16746user. 16747 16748@emph{Important:} 16749It is not a good idea to use adaptave rejection sampling while 16750sampling from a domain that is a strict subset of the domain that 16751has been used to construct the hat. 16752For that reason adaptive adding of construction points is 16753@emph{automatically disabled} by this call. 16754 16755@emph{Important:} If the CDF of the hat is (almost) the same 16756for @var{left} and @var{right} and (almost) equal to @code{0} or 16757@code{1}, then the truncated domain is not changed and the call 16758returns an error code. 16759@end deftypefn 16760@end ifnotinfo 16761 16762@ifinfo 16763@anchor{funct:unur_tabl_set_verify} 16764@deftypefn Function {int} unur_tabl_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 16765@anchor{funct:unur_tabl_chg_verify} 16766@deftypefnx Function {int} unur_tabl_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 16767Turn verifying of algorithm while sampling on/off. 16768If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 16769violated for some @i{x} then @code{unur_errno} is set to 16770@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 16771happen due to round-off errors for a few values of 16772@i{x} (less than 1%). 16773 16774Default is @code{FALSE}. 16775@end deftypefn 16776@end ifinfo 16777@ifnotinfo 16778@anchor{funct:unur_tabl_set_verify} 16779@deftypefn {} {int} unur_tabl_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 16780@anchor{funct:unur_tabl_chg_verify} 16781@deftypefnx {} {int} unur_tabl_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 16782Turn verifying of algorithm while sampling on/off. 16783If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 16784violated for some @i{x} then @code{unur_errno} is set to 16785@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 16786happen due to round-off errors for a few values of 16787@i{x} (less than 1%). 16788 16789Default is @code{FALSE}. 16790@end deftypefn 16791@end ifnotinfo 16792 16793@ifinfo 16794@anchor{funct:unur_tabl_set_pedantic} 16795@deftypefn Function {int} unur_tabl_set_pedantic (UNUR_PAR* @var{parameters}, int @var{pedantic}) 16796Sometimes it might happen that 16797@ifhtml 16798@ref{funct:unur_init,@command{unur_init}} 16799@end ifhtml 16800@ifnothtml 16801@command{unur_init} 16802@end ifnothtml 16803has been executed 16804successfully. But when additional construction points are added by 16805adaptive rejection sampling, the algorithm detects that the 16806PDF is not monotone in the given slopes. 16807 16808With @var{pedantic} being @code{TRUE}, the sampling routine is exchanged 16809by a routine that simply returns @code{UNUR_INFINITY} indicating an 16810error. 16811 16812Default is @code{FALSE}. 16813@end deftypefn 16814@end ifinfo 16815@ifnotinfo 16816@anchor{funct:unur_tabl_set_pedantic} 16817@deftypefn {} {int} unur_tabl_set_pedantic (UNUR_PAR* @var{parameters}, int @var{pedantic}) 16818Sometimes it might happen that 16819@ifhtml 16820@ref{funct:unur_init,@command{unur_init}} 16821@end ifhtml 16822@ifnothtml 16823@command{unur_init} 16824@end ifnothtml 16825has been executed 16826successfully. But when additional construction points are added by 16827adaptive rejection sampling, the algorithm detects that the 16828PDF is not monotone in the given slopes. 16829 16830With @var{pedantic} being @code{TRUE}, the sampling routine is exchanged 16831by a routine that simply returns @code{UNUR_INFINITY} indicating an 16832error. 16833 16834Default is @code{FALSE}. 16835@end deftypefn 16836@end ifnotinfo 16837 16838 16839 16840 16841@c 16842@c end of tabl.h 16843@c ------------------------------------- 16844@c ------------------------------------- 16845@c tdr.h 16846@c 16847 16848@page 16849@node TDR 16850@subsection TDR -- Transformed Density Rejection 16851 16852@table @i 16853@item Required: 16854T-concave PDF, dPDF 16855@item Optional: 16856mode 16857@item Speed: 16858Set-up: slow, Sampling: fast 16859@item Reinit: 16860supported 16861@item Reference: 16862@ifhtml 16863@ref{bib:GWa92,, [GWa92]} 16864@end ifhtml 16865@ifnothtml 16866[GWa92] 16867@end ifnothtml 16868@ifhtml 16869@ref{bib:HWa95,, [HWa95]} 16870@end ifhtml 16871@ifnothtml 16872[HWa95] 16873@end ifnothtml 16874@ifhtml 16875@ref{bib:HLD04,, [HLD04: Cha.4]} 16876@end ifhtml 16877@ifnothtml 16878[HLD04: Cha.4] 16879@end ifnothtml 16880 16881@end table 16882@sp 1 16883 16884 16885TDR is an acceptance/rejection method that uses the concavity of a 16886transformed density to construct hat function and squeezes 16887automatically. Such PDFs are called T-concave. Currently the 16888following transformations are implemented and can be selected by 16889setting their @code{c}-values by a 16890@ifhtml 16891@ref{funct:unur_tdr_set_c,@command{unur_tdr_set_c}} 16892@end ifhtml 16893@ifnothtml 16894@command{unur_tdr_set_c} 16895@end ifnothtml 16896call: 16897 16898@table @code 16899@item c = 0 16900T(x) = log(x) 16901@item c = -0.5 16902T(x) = -1/sqrt(x) @ @ @ @ @ (Default) 16903@end table 16904 16905In future releases the transformations T(x) = -(x)^c will be 16906available for any c with 0 > c > -1. 16907Notice that if a PDF is T-concave for a c then it also T-concave 16908for every c'<c. However the performance decreases when c' is 16909smaller than c. For computational reasons we suggest the usage of 16910c = -0.5 (this is the default). 16911For c <= -1 the hat is not bounded any more if the domain of the 16912PDF is unbounded. But in the case of a bounded domain using 16913method TABL is preferred to a TDR with c < -1 (except in a few 16914special cases). 16915 16916We offer three variants of the algorithm. 16917 16918@table @code 16919@item GW 16920squeezes between construction points 16921@item PS 16922squeezes proportional to hat function @ @ @ @ @ (Default) 16923@item IA 16924same as variant PS but uses a compositon method with 16925``immediate acceptance'' in the region below the squeeze. 16926@end table 16927 16928@code{GW} has a slightly faster setup but higher marginal generation 16929times. 16930@code{PS} is faster than @code{GW}. @code{IA} uses less uniform 16931random numbers and is therefore faster than @code{PS}. 16932 16933It is also possible to evaluate the inverse of the CDF of the hat distribution 16934directly using the 16935@ifhtml 16936@ref{funct:unur_tdr_eval_invcdfhat,@command{unur_tdr_eval_invcdfhat}} 16937@end ifhtml 16938@ifnothtml 16939@command{unur_tdr_eval_invcdfhat} 16940@end ifnothtml 16941call. 16942 16943There are lots of parameters for these methods, see below. 16944 16945It is possible to use this method for correlation induction by 16946setting an auxiliary uniform random number generator via the 16947@ifhtml 16948@ref{funct:unur_set_urng_aux,@command{unur_set_urng_aux}} 16949@end ifhtml 16950@ifnothtml 16951@command{unur_set_urng_aux} 16952@end ifnothtml 16953call. (Notice that this must be done after a 16954possible 16955@ifhtml 16956@ref{funct:unur_set_urng,@command{unur_set_urng}} 16957@end ifhtml 16958@ifnothtml 16959@command{unur_set_urng} 16960@end ifnothtml 16961call.) 16962When an auxiliary generator is used then the number of 16963uniform random numbers from the first URNG that are used for one 16964generated random variate is constant and given in the following table: 16965 16966@table @code 16967@item GW ... 2 16968@item PS ... 2 16969@item IA ... 1 16970@end table 16971 16972There exists a test mode that verifies whether the conditions for 16973the method are satisfied or not. It can be switched on by calling 16974@ifhtml 16975@ref{funct:unur_tdr_set_verify,@command{unur_tdr_set_verify}} 16976@end ifhtml 16977@ifnothtml 16978@command{unur_tdr_set_verify} 16979@end ifnothtml 16980and 16981@ifhtml 16982@ref{funct:unur_tdr_chg_verify,@command{unur_tdr_chg_verify},} 16983@end ifhtml 16984@ifnothtml 16985@command{unur_tdr_chg_verify}, 16986@end ifnothtml 16987respectively. 16988Notice however that sampling is (much) slower then. 16989 16990For densities with modes not close to 0 it is suggested to set 16991either the mode or the center of the distribution by the 16992@ifhtml 16993@ref{funct:unur_distr_cont_set_mode,@command{unur_distr_cont_set_mode}} 16994@end ifhtml 16995@ifnothtml 16996@command{unur_distr_cont_set_mode} 16997@end ifnothtml 16998or 16999@ifhtml 17000@ref{funct:unur_distr_cont_set_center,@command{unur_distr_cont_set_center}} 17001@end ifhtml 17002@ifnothtml 17003@command{unur_distr_cont_set_center} 17004@end ifnothtml 17005call. 17006The latter is the approximate location of the mode or the mean 17007of the distribution. This location provides some information 17008about the main part of the PDF and is used to avoid numerical 17009problems. 17010 17011It is possible to use this method for generating from truncated 17012distributions. It even can be changed for an existing generator 17013object by an 17014@ifhtml 17015@ref{funct:unur_tdr_chg_truncated,@command{unur_tdr_chg_truncated}} 17016@end ifhtml 17017@ifnothtml 17018@command{unur_tdr_chg_truncated} 17019@end ifnothtml 17020call. 17021 17022It is possible to change the parameters and the domain of the chosen 17023distribution and run 17024@ifhtml 17025@ref{funct:unur_reinit,@command{unur_reinit}} 17026@end ifhtml 17027@ifnothtml 17028@command{unur_reinit} 17029@end ifnothtml 17030to reinitialize the generator object. 17031 17032@emph{Important:} The ratio between the area below the hat and 17033the area below the squeeze changes when the sampling region is 17034restricted. Especially it becomes (very) small when sampling 17035from the (far) tail of the distribution. Then it is better to 17036create a new generator object for the tail of the distribution 17037only. 17038 17039 17040@subheading Function reference 17041 17042@ifhtml 17043@itemize 17044@item @ref{funct:unur_tdr_new,unur_tdr_new} 17045@item @ref{funct:unur_tdr_set_c,unur_tdr_set_c} 17046@item @ref{funct:unur_tdr_set_variant_gw,unur_tdr_set_variant_gw} 17047@item @ref{funct:unur_tdr_set_variant_ps,unur_tdr_set_variant_ps} 17048@item @ref{funct:unur_tdr_set_variant_ia,unur_tdr_set_variant_ia} 17049@item @ref{funct:unur_tdr_set_usedars,unur_tdr_set_usedars} 17050@item @ref{funct:unur_tdr_set_darsfactor,unur_tdr_set_darsfactor} 17051@item @ref{funct:unur_tdr_set_cpoints,unur_tdr_set_cpoints} 17052@item @ref{funct:unur_tdr_set_reinit_percentiles,unur_tdr_set_reinit_percentiles} 17053@item @ref{funct:unur_tdr_chg_reinit_percentiles,unur_tdr_chg_reinit_percentiles} 17054@item @ref{funct:unur_tdr_set_reinit_ncpoints,unur_tdr_set_reinit_ncpoints} 17055@item @ref{funct:unur_tdr_chg_reinit_ncpoints,unur_tdr_chg_reinit_ncpoints} 17056@item @ref{funct:unur_tdr_chg_truncated,unur_tdr_chg_truncated} 17057@item @ref{funct:unur_tdr_set_max_sqhratio,unur_tdr_set_max_sqhratio} 17058@item @ref{funct:unur_tdr_get_sqhratio,unur_tdr_get_sqhratio} 17059@item @ref{funct:unur_tdr_get_hatarea,unur_tdr_get_hatarea} 17060@item @ref{funct:unur_tdr_get_squeezearea,unur_tdr_get_squeezearea} 17061@item @ref{funct:unur_tdr_set_max_intervals,unur_tdr_set_max_intervals} 17062@item @ref{funct:unur_tdr_set_usecenter,unur_tdr_set_usecenter} 17063@item @ref{funct:unur_tdr_set_usemode,unur_tdr_set_usemode} 17064@item @ref{funct:unur_tdr_set_guidefactor,unur_tdr_set_guidefactor} 17065@item @ref{funct:unur_tdr_set_verify,unur_tdr_set_verify} 17066@item @ref{funct:unur_tdr_chg_verify,unur_tdr_chg_verify} 17067@item @ref{funct:unur_tdr_set_pedantic,unur_tdr_set_pedantic} 17068@item @ref{funct:unur_tdr_eval_invcdfhat,unur_tdr_eval_invcdfhat} 17069@end itemize 17070@end ifhtml 17071 17072 17073@ifinfo 17074@anchor{funct:unur_tdr_new} 17075@deftypefn Function {UNUR_PAR*} unur_tdr_new (const @var{UNUR_DISTR* distribution}) 17076Get default parameters for generator. 17077@end deftypefn 17078@end ifinfo 17079@ifnotinfo 17080@anchor{funct:unur_tdr_new} 17081@deftypefn {} {UNUR_PAR*} unur_tdr_new (const @var{UNUR_DISTR* distribution}) 17082Get default parameters for generator. 17083@end deftypefn 17084@end ifnotinfo 17085 17086@ifinfo 17087@anchor{funct:unur_tdr_set_c} 17088@deftypefn Function {int} unur_tdr_set_c (UNUR_PAR* @var{parameters}, double @var{c}) 17089Set parameter @var{c} for transformation T. 17090Currently only values between 0 and -0.5 are allowed. 17091If @code{c} is between 0 and -0.5 it is set to -0.5. 17092 17093Default is @code{-0.5}. 17094@end deftypefn 17095@end ifinfo 17096@ifnotinfo 17097@anchor{funct:unur_tdr_set_c} 17098@deftypefn {} {int} unur_tdr_set_c (UNUR_PAR* @var{parameters}, double @var{c}) 17099Set parameter @var{c} for transformation T. 17100Currently only values between 0 and -0.5 are allowed. 17101If @code{c} is between 0 and -0.5 it is set to -0.5. 17102 17103Default is @code{-0.5}. 17104@end deftypefn 17105@end ifnotinfo 17106 17107@ifinfo 17108@anchor{funct:unur_tdr_set_variant_gw} 17109@deftypefn Function {int} unur_tdr_set_variant_gw (UNUR_PAR* @var{parameters}) 17110Use original version with squeezes between construction points as 17111proposed by Gilks & Wild (1992). 17112@end deftypefn 17113@end ifinfo 17114@ifnotinfo 17115@anchor{funct:unur_tdr_set_variant_gw} 17116@deftypefn {} {int} unur_tdr_set_variant_gw (UNUR_PAR* @var{parameters}) 17117Use original version with squeezes between construction points as 17118proposed by Gilks & Wild (1992). 17119@end deftypefn 17120@end ifnotinfo 17121 17122@ifinfo 17123@anchor{funct:unur_tdr_set_variant_ps} 17124@deftypefn Function {int} unur_tdr_set_variant_ps (UNUR_PAR* @var{parameters}) 17125Use squeezes proportional to the hat function. This is faster than 17126the original version. 17127This is the default. 17128@end deftypefn 17129@end ifinfo 17130@ifnotinfo 17131@anchor{funct:unur_tdr_set_variant_ps} 17132@deftypefn {} {int} unur_tdr_set_variant_ps (UNUR_PAR* @var{parameters}) 17133Use squeezes proportional to the hat function. This is faster than 17134the original version. 17135This is the default. 17136@end deftypefn 17137@end ifnotinfo 17138 17139@ifinfo 17140@anchor{funct:unur_tdr_set_variant_ia} 17141@deftypefn Function {int} unur_tdr_set_variant_ia (UNUR_PAR* @var{parameters}) 17142Use squeezes proportional to the hat function together with a 17143composition method that required less uniform random numbers. 17144@end deftypefn 17145@end ifinfo 17146@ifnotinfo 17147@anchor{funct:unur_tdr_set_variant_ia} 17148@deftypefn {} {int} unur_tdr_set_variant_ia (UNUR_PAR* @var{parameters}) 17149Use squeezes proportional to the hat function together with a 17150composition method that required less uniform random numbers. 17151@end deftypefn 17152@end ifnotinfo 17153 17154@ifinfo 17155@anchor{funct:unur_tdr_set_usedars} 17156@deftypefn Function {int} unur_tdr_set_usedars (UNUR_PAR* @var{parameters}, int @var{usedars}) 17157If @var{usedars} is set to @code{TRUE}, ``derandomized adaptive rejection 17158sampling'' (DARS) is used in setup. 17159Intervals where the area between hat and squeeze is too 17160large compared to the average area between hat and squeeze 17161over all intervals are split. 17162This procedure is repeated until the ratio between area below squeeze 17163and area below hat exceeds the bound given by 17164@ifhtml 17165@ref{funct:unur_tdr_set_max_sqhratio,@command{unur_tdr_set_max_sqhratio}} 17166@end ifhtml 17167@ifnothtml 17168@command{unur_tdr_set_max_sqhratio} 17169@end ifnothtml 17170call or the maximum number of intervals is 17171reached. Moreover, it also aborts when no more intervals can be 17172found for splitting. 17173 17174For finding splitting points the following rules are used (in 17175this order, i.e., is if the first rule cannot be applied, the next 17176one is used): 17177@enumerate 17178@item 17179Use the expected value of adaptive rejection sampling. 17180@item 17181Use the arc-mean rule (a mixture of arithmetic mean and harmonic 17182mean). 17183@item 17184Use the arithmetic mean of the interval boundaries. 17185@end enumerate 17186Notice, however, that for unbounded intervals neither rule 1 nor rule 171873 can be used. 17188 17189As an additional feature, it is possible to choose amoung these 17190rules. 17191If @var{usedars} is set to @code{1} or @code{TRUE} the expected point 17192(rule 1) is used (it switches to rule 2 for a particular 17193interval if rule 1 cannot be applied). 17194If it is set to @code{2} the arc-mean rule is used. 17195If it is set to @code{3} the mean is used. 17196Notice that rule 3 can only be used if the domain of the 17197distribution is bounded. It is faster than the other two methods 17198but for heavy-tailed distribution and large domain the hat 17199converges extremely slowly. 17200 17201The default depends on the given construction points. 17202If the user has provided such points via a 17203@ifhtml 17204@ref{funct:unur_tdr_set_cpoints,@command{unur_tdr_set_cpoints}} 17205@end ifhtml 17206@ifnothtml 17207@command{unur_tdr_set_cpoints} 17208@end ifnothtml 17209call, then @var{usedars} is set to @code{FALSE} by default, i.e., 17210there is no further splitting. 17211If the user has only given the number of construction points (or 17212only uses the default number), then @var{usedars} is set to @code{TRUE} 17213(i.e., use rule 1). 17214@end deftypefn 17215@end ifinfo 17216@ifnotinfo 17217@anchor{funct:unur_tdr_set_usedars} 17218@deftypefn {} {int} unur_tdr_set_usedars (UNUR_PAR* @var{parameters}, int @var{usedars}) 17219If @var{usedars} is set to @code{TRUE}, ``derandomized adaptive rejection 17220sampling'' (DARS) is used in setup. 17221Intervals where the area between hat and squeeze is too 17222large compared to the average area between hat and squeeze 17223over all intervals are split. 17224This procedure is repeated until the ratio between area below squeeze 17225and area below hat exceeds the bound given by 17226@ifhtml 17227@ref{funct:unur_tdr_set_max_sqhratio,@command{unur_tdr_set_max_sqhratio}} 17228@end ifhtml 17229@ifnothtml 17230@command{unur_tdr_set_max_sqhratio} 17231@end ifnothtml 17232call or the maximum number of intervals is 17233reached. Moreover, it also aborts when no more intervals can be 17234found for splitting. 17235 17236For finding splitting points the following rules are used (in 17237this order, i.e., is if the first rule cannot be applied, the next 17238one is used): 17239@enumerate 17240@item 17241Use the expected value of adaptive rejection sampling. 17242@item 17243Use the arc-mean rule (a mixture of arithmetic mean and harmonic 17244mean). 17245@item 17246Use the arithmetic mean of the interval boundaries. 17247@end enumerate 17248Notice, however, that for unbounded intervals neither rule 1 nor rule 172493 can be used. 17250 17251As an additional feature, it is possible to choose amoung these 17252rules. 17253If @var{usedars} is set to @code{1} or @code{TRUE} the expected point 17254(rule 1) is used (it switches to rule 2 for a particular 17255interval if rule 1 cannot be applied). 17256If it is set to @code{2} the arc-mean rule is used. 17257If it is set to @code{3} the mean is used. 17258Notice that rule 3 can only be used if the domain of the 17259distribution is bounded. It is faster than the other two methods 17260but for heavy-tailed distribution and large domain the hat 17261converges extremely slowly. 17262 17263The default depends on the given construction points. 17264If the user has provided such points via a 17265@ifhtml 17266@ref{funct:unur_tdr_set_cpoints,@command{unur_tdr_set_cpoints}} 17267@end ifhtml 17268@ifnothtml 17269@command{unur_tdr_set_cpoints} 17270@end ifnothtml 17271call, then @var{usedars} is set to @code{FALSE} by default, i.e., 17272there is no further splitting. 17273If the user has only given the number of construction points (or 17274only uses the default number), then @var{usedars} is set to @code{TRUE} 17275(i.e., use rule 1). 17276@end deftypefn 17277@end ifnotinfo 17278 17279@ifinfo 17280@anchor{funct:unur_tdr_set_darsfactor} 17281@deftypefn Function {int} unur_tdr_set_darsfactor (UNUR_PAR* @var{parameters}, double @var{factor}) 17282Set factor for ``derandomized adaptive rejection sampling''. 17283This factor is used to determine the intervals that are ``too 17284large'', that is, all intervals where the area between squeeze and 17285hat is larger than @var{factor} times the average area over all 17286intervals between squeeze and hat. 17287Notice that all intervals are split when @var{factor} is set to 17288@code{0.}, and that there is no splitting at all when @var{factor} 17289is set to @code{UNUR_INFINITY}. 17290 17291Default is @code{0.99}. There is no need to change this parameter. 17292@end deftypefn 17293@end ifinfo 17294@ifnotinfo 17295@anchor{funct:unur_tdr_set_darsfactor} 17296@deftypefn {} {int} unur_tdr_set_darsfactor (UNUR_PAR* @var{parameters}, double @var{factor}) 17297Set factor for ``derandomized adaptive rejection sampling''. 17298This factor is used to determine the intervals that are ``too 17299large'', that is, all intervals where the area between squeeze and 17300hat is larger than @var{factor} times the average area over all 17301intervals between squeeze and hat. 17302Notice that all intervals are split when @var{factor} is set to 17303@code{0.}, and that there is no splitting at all when @var{factor} 17304is set to @code{UNUR_INFINITY}. 17305 17306Default is @code{0.99}. There is no need to change this parameter. 17307@end deftypefn 17308@end ifnotinfo 17309 17310@ifinfo 17311@anchor{funct:unur_tdr_set_cpoints} 17312@deftypefn Function {int} unur_tdr_set_cpoints (UNUR_PAR* @var{parameters}, int @var{n_stp}, const @var{double* stp}) 17313Set construction points for the hat function. If @var{stp} is @code{NULL} 17314than a heuristic rule of thumb is used to get @var{n_stp} 17315construction points. This is the default behavior. 17316 17317The default number of construction points is 30. 17318@end deftypefn 17319@end ifinfo 17320@ifnotinfo 17321@anchor{funct:unur_tdr_set_cpoints} 17322@deftypefn {} {int} unur_tdr_set_cpoints (UNUR_PAR* @var{parameters}, int @var{n_stp}, const @var{double* stp}) 17323Set construction points for the hat function. If @var{stp} is @code{NULL} 17324than a heuristic rule of thumb is used to get @var{n_stp} 17325construction points. This is the default behavior. 17326 17327The default number of construction points is 30. 17328@end deftypefn 17329@end ifnotinfo 17330 17331@ifinfo 17332@anchor{funct:unur_tdr_set_reinit_percentiles} 17333@deftypefn Function {int} unur_tdr_set_reinit_percentiles (UNUR_PAR* @var{parameters}, int @var{n_percentiles}, const @var{double* percentiles}) 17334@anchor{funct:unur_tdr_chg_reinit_percentiles} 17335@deftypefnx Function {int} unur_tdr_chg_reinit_percentiles (UNUR_GEN* @var{generator}, int @var{n_percentiles}, const @var{double* percentiles}) 17336By default, when the @var{generator} object is reinitialized, it 17337used the same construction points as for the initialization 17338procedure. 17339Often the underlying distribution object has been changed only 17340moderately. For example, the full conditional distribution of a 17341multivariate distribution. 17342In this case it might be more appropriate to use 17343percentilesm of the hat function for the last (unchanged) 17344distribution. @var{percentiles} must then be a pointer to an 17345ordered array of numbers between @code{0.01} and @code{0.99}. 17346If @var{percentiles} is @code{NULL}, then a heuristic rule of thumb is 17347used to get @var{n_percentiles} values for these percentiles. 17348Notice that @var{n_percentiles} must be at least @code{2}, 17349otherwise defaults are used. 17350(Then the first and third quartiles are used by default.) 17351@end deftypefn 17352@end ifinfo 17353@ifnotinfo 17354@anchor{funct:unur_tdr_set_reinit_percentiles} 17355@deftypefn {} {int} unur_tdr_set_reinit_percentiles (UNUR_PAR* @var{parameters}, int @var{n_percentiles}, const @var{double* percentiles}) 17356@anchor{funct:unur_tdr_chg_reinit_percentiles} 17357@deftypefnx {} {int} unur_tdr_chg_reinit_percentiles (UNUR_GEN* @var{generator}, int @var{n_percentiles}, const @var{double* percentiles}) 17358By default, when the @var{generator} object is reinitialized, it 17359used the same construction points as for the initialization 17360procedure. 17361Often the underlying distribution object has been changed only 17362moderately. For example, the full conditional distribution of a 17363multivariate distribution. 17364In this case it might be more appropriate to use 17365percentilesm of the hat function for the last (unchanged) 17366distribution. @var{percentiles} must then be a pointer to an 17367ordered array of numbers between @code{0.01} and @code{0.99}. 17368If @var{percentiles} is @code{NULL}, then a heuristic rule of thumb is 17369used to get @var{n_percentiles} values for these percentiles. 17370Notice that @var{n_percentiles} must be at least @code{2}, 17371otherwise defaults are used. 17372(Then the first and third quartiles are used by default.) 17373@end deftypefn 17374@end ifnotinfo 17375 17376@ifinfo 17377@anchor{funct:unur_tdr_set_reinit_ncpoints} 17378@deftypefn Function {int} unur_tdr_set_reinit_ncpoints (UNUR_PAR* @var{parameters}, int @var{ncpoints}) 17379@anchor{funct:unur_tdr_chg_reinit_ncpoints} 17380@deftypefnx Function {int} unur_tdr_chg_reinit_ncpoints (UNUR_GEN* @var{generator}, int @var{ncpoints}) 17381When reinit fails with the given construction points or the percentiles 17382of the old hat function, another trial is undertaken with @var{ncpoints} 17383construction points. @var{ncpoints} must be at least @code{10}. 17384 17385Default: @code{50} 17386@end deftypefn 17387@end ifinfo 17388@ifnotinfo 17389@anchor{funct:unur_tdr_set_reinit_ncpoints} 17390@deftypefn {} {int} unur_tdr_set_reinit_ncpoints (UNUR_PAR* @var{parameters}, int @var{ncpoints}) 17391@anchor{funct:unur_tdr_chg_reinit_ncpoints} 17392@deftypefnx {} {int} unur_tdr_chg_reinit_ncpoints (UNUR_GEN* @var{generator}, int @var{ncpoints}) 17393When reinit fails with the given construction points or the percentiles 17394of the old hat function, another trial is undertaken with @var{ncpoints} 17395construction points. @var{ncpoints} must be at least @code{10}. 17396 17397Default: @code{50} 17398@end deftypefn 17399@end ifnotinfo 17400 17401@ifinfo 17402@anchor{funct:unur_tdr_chg_truncated} 17403@deftypefn Function {int} unur_tdr_chg_truncated (UNUR_GEN* @var{gen}, double @var{left}, double @var{right}) 17404Change the borders of the domain of the (truncated) distribution. 17405 17406Notice that the given truncated domain must be a subset of the 17407domain of the given distribution. The generator always uses the 17408intersection of the domain of the distribution and the truncated 17409domain given by this call. The hat function will not be changed and 17410there is no need to run 17411@ifhtml 17412@ref{funct:unur_reinit,@command{unur_reinit}.} 17413@end ifhtml 17414@ifnothtml 17415@command{unur_reinit}. 17416@end ifnothtml 17417@emph{Important:} 17418The ratio between the area below the hat and the area below the 17419squeeze changes when the sampling region is restricted. In particular 17420it becomes (very) large when sampling from the (far) tail of the 17421distribution. Then it is better to create a generator object for the 17422tail of distribution only. 17423 17424@emph{Important:} 17425This call does not work for variant @code{IA} (immediate 17426acceptance). In this case UNU.RAN switches @emph{automatically} to 17427variant @code{PS}. 17428 17429@emph{Important:} 17430It is not a good idea to use adaptave rejection sampling while 17431sampling from a domain that is a strict subset of the domain that 17432has been used to construct the hat. 17433For that reason adaptive adding of construction points is 17434@emph{automatically disabled} by this call. 17435 17436@emph{Important:} If the CDF of the hat is (almost) the same 17437for @var{left} and @var{right} and (almost) equal to @code{0} or 17438@code{1}, then the truncated domain is not changed and the call 17439returns an error code. 17440@end deftypefn 17441@end ifinfo 17442@ifnotinfo 17443@anchor{funct:unur_tdr_chg_truncated} 17444@deftypefn {} {int} unur_tdr_chg_truncated (UNUR_GEN* @var{gen}, double @var{left}, double @var{right}) 17445Change the borders of the domain of the (truncated) distribution. 17446 17447Notice that the given truncated domain must be a subset of the 17448domain of the given distribution. The generator always uses the 17449intersection of the domain of the distribution and the truncated 17450domain given by this call. The hat function will not be changed and 17451there is no need to run 17452@ifhtml 17453@ref{funct:unur_reinit,@command{unur_reinit}.} 17454@end ifhtml 17455@ifnothtml 17456@command{unur_reinit}. 17457@end ifnothtml 17458@emph{Important:} 17459The ratio between the area below the hat and the area below the 17460squeeze changes when the sampling region is restricted. In particular 17461it becomes (very) large when sampling from the (far) tail of the 17462distribution. Then it is better to create a generator object for the 17463tail of distribution only. 17464 17465@emph{Important:} 17466This call does not work for variant @code{IA} (immediate 17467acceptance). In this case UNU.RAN switches @emph{automatically} to 17468variant @code{PS}. 17469 17470@emph{Important:} 17471It is not a good idea to use adaptave rejection sampling while 17472sampling from a domain that is a strict subset of the domain that 17473has been used to construct the hat. 17474For that reason adaptive adding of construction points is 17475@emph{automatically disabled} by this call. 17476 17477@emph{Important:} If the CDF of the hat is (almost) the same 17478for @var{left} and @var{right} and (almost) equal to @code{0} or 17479@code{1}, then the truncated domain is not changed and the call 17480returns an error code. 17481@end deftypefn 17482@end ifnotinfo 17483 17484@ifinfo 17485@anchor{funct:unur_tdr_set_max_sqhratio} 17486@deftypefn Function {int} unur_tdr_set_max_sqhratio (UNUR_PAR* @var{parameters}, double @var{max_ratio}) 17487Set upper bound for the 17488ratio (area below squeeze) / (area below hat). 17489It must be a number between 0 and 1. 17490When the ratio exceeds the given number no further construction 17491points are inserted via adaptive rejection sampling. 17492Use 0 if no construction points should be added after the setup. 17493Use 1 if added new construction points should not be stopped until 17494the maximum number of construction points is reached. 17495 17496Default is @code{0.99}. 17497@end deftypefn 17498@end ifinfo 17499@ifnotinfo 17500@anchor{funct:unur_tdr_set_max_sqhratio} 17501@deftypefn {} {int} unur_tdr_set_max_sqhratio (UNUR_PAR* @var{parameters}, double @var{max_ratio}) 17502Set upper bound for the 17503ratio (area below squeeze) / (area below hat). 17504It must be a number between 0 and 1. 17505When the ratio exceeds the given number no further construction 17506points are inserted via adaptive rejection sampling. 17507Use 0 if no construction points should be added after the setup. 17508Use 1 if added new construction points should not be stopped until 17509the maximum number of construction points is reached. 17510 17511Default is @code{0.99}. 17512@end deftypefn 17513@end ifnotinfo 17514 17515@ifinfo 17516@anchor{funct:unur_tdr_get_sqhratio} 17517@deftypefn Function {double} unur_tdr_get_sqhratio (const @var{UNUR_GEN* generator}) 17518Get the current ratio (area below squeeze) / (area below hat) 17519for the generator. 17520(In case of an error @code{UNUR_INFINITY} is returned.) 17521@end deftypefn 17522@end ifinfo 17523@ifnotinfo 17524@anchor{funct:unur_tdr_get_sqhratio} 17525@deftypefn {} {double} unur_tdr_get_sqhratio (const @var{UNUR_GEN* generator}) 17526Get the current ratio (area below squeeze) / (area below hat) 17527for the generator. 17528(In case of an error @code{UNUR_INFINITY} is returned.) 17529@end deftypefn 17530@end ifnotinfo 17531 17532@ifinfo 17533@anchor{funct:unur_tdr_get_hatarea} 17534@deftypefn Function {double} unur_tdr_get_hatarea (const @var{UNUR_GEN* generator}) 17535Get the area below the hat for the generator. 17536(In case of an error @code{UNUR_INFINITY} is returned.) 17537@end deftypefn 17538@end ifinfo 17539@ifnotinfo 17540@anchor{funct:unur_tdr_get_hatarea} 17541@deftypefn {} {double} unur_tdr_get_hatarea (const @var{UNUR_GEN* generator}) 17542Get the area below the hat for the generator. 17543(In case of an error @code{UNUR_INFINITY} is returned.) 17544@end deftypefn 17545@end ifnotinfo 17546 17547@ifinfo 17548@anchor{funct:unur_tdr_get_squeezearea} 17549@deftypefn Function {double} unur_tdr_get_squeezearea (const @var{UNUR_GEN* generator}) 17550Get the area below the squeeze for the generator. 17551(In case of an error @code{UNUR_INFINITY} is returned.) 17552@end deftypefn 17553@end ifinfo 17554@ifnotinfo 17555@anchor{funct:unur_tdr_get_squeezearea} 17556@deftypefn {} {double} unur_tdr_get_squeezearea (const @var{UNUR_GEN* generator}) 17557Get the area below the squeeze for the generator. 17558(In case of an error @code{UNUR_INFINITY} is returned.) 17559@end deftypefn 17560@end ifnotinfo 17561 17562@ifinfo 17563@anchor{funct:unur_tdr_set_max_intervals} 17564@deftypefn Function {int} unur_tdr_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 17565Set maximum number of intervals. 17566No construction points are added after the setup when the number of 17567intervals suceeds @var{max_ivs}. 17568It is increased automatically to twice the number of construction 17569points if this is larger. 17570 17571Default is @code{100}. 17572@end deftypefn 17573@end ifinfo 17574@ifnotinfo 17575@anchor{funct:unur_tdr_set_max_intervals} 17576@deftypefn {} {int} unur_tdr_set_max_intervals (UNUR_PAR* @var{parameters}, int @var{max_ivs}) 17577Set maximum number of intervals. 17578No construction points are added after the setup when the number of 17579intervals suceeds @var{max_ivs}. 17580It is increased automatically to twice the number of construction 17581points if this is larger. 17582 17583Default is @code{100}. 17584@end deftypefn 17585@end ifnotinfo 17586 17587@ifinfo 17588@anchor{funct:unur_tdr_set_usecenter} 17589@deftypefn Function {int} unur_tdr_set_usecenter (UNUR_PAR* @var{parameters}, int @var{usecenter}) 17590Use the center as construction point. Default is @code{TRUE}. 17591@end deftypefn 17592@end ifinfo 17593@ifnotinfo 17594@anchor{funct:unur_tdr_set_usecenter} 17595@deftypefn {} {int} unur_tdr_set_usecenter (UNUR_PAR* @var{parameters}, int @var{usecenter}) 17596Use the center as construction point. Default is @code{TRUE}. 17597@end deftypefn 17598@end ifnotinfo 17599 17600@ifinfo 17601@anchor{funct:unur_tdr_set_usemode} 17602@deftypefn Function {int} unur_tdr_set_usemode (UNUR_PAR* @var{parameters}, int @var{usemode}) 17603Use the (exact!) mode as construction point. 17604Notice that the behavior of the algorithm is different to simply 17605adding the mode in the list of construction points via a 17606@ifhtml 17607@ref{funct:unur_tdr_set_cpoints,@command{unur_tdr_set_cpoints}} 17608@end ifhtml 17609@ifnothtml 17610@command{unur_tdr_set_cpoints} 17611@end ifnothtml 17612call. In the latter case the mode is treated 17613just like any other point. However, when @code{usemode} is @code{TRUE}, the 17614tangent in the mode is always set to 0. Then the hat of the 17615transformed density can never cut the x-axis which must never 17616happen if c < 0, since otherwise the hat would not be bounded. 17617 17618Default is @code{TRUE}. 17619@end deftypefn 17620@end ifinfo 17621@ifnotinfo 17622@anchor{funct:unur_tdr_set_usemode} 17623@deftypefn {} {int} unur_tdr_set_usemode (UNUR_PAR* @var{parameters}, int @var{usemode}) 17624Use the (exact!) mode as construction point. 17625Notice that the behavior of the algorithm is different to simply 17626adding the mode in the list of construction points via a 17627@ifhtml 17628@ref{funct:unur_tdr_set_cpoints,@command{unur_tdr_set_cpoints}} 17629@end ifhtml 17630@ifnothtml 17631@command{unur_tdr_set_cpoints} 17632@end ifnothtml 17633call. In the latter case the mode is treated 17634just like any other point. However, when @code{usemode} is @code{TRUE}, the 17635tangent in the mode is always set to 0. Then the hat of the 17636transformed density can never cut the x-axis which must never 17637happen if c < 0, since otherwise the hat would not be bounded. 17638 17639Default is @code{TRUE}. 17640@end deftypefn 17641@end ifnotinfo 17642 17643@ifinfo 17644@anchor{funct:unur_tdr_set_guidefactor} 17645@deftypefn Function {int} unur_tdr_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 17646Set factor for relative size of the guide table for indexed search 17647(see also method DGT @ref{DGT}). It must be greater than or equal 17648to @code{0}. 17649When set to @code{0}, then sequential search is used. 17650 17651Default is 2. 17652@end deftypefn 17653@end ifinfo 17654@ifnotinfo 17655@anchor{funct:unur_tdr_set_guidefactor} 17656@deftypefn {} {int} unur_tdr_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 17657Set factor for relative size of the guide table for indexed search 17658(see also method DGT @ref{DGT}). It must be greater than or equal 17659to @code{0}. 17660When set to @code{0}, then sequential search is used. 17661 17662Default is 2. 17663@end deftypefn 17664@end ifnotinfo 17665 17666@ifinfo 17667@anchor{funct:unur_tdr_set_verify} 17668@deftypefn Function {int} unur_tdr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 17669@anchor{funct:unur_tdr_chg_verify} 17670@deftypefnx Function {int} unur_tdr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 17671Turn verifying of algorithm while sampling on/off. 17672If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 17673violated for some @i{x} then @code{unur_errno} is set to 17674@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 17675happen due to round-off errors for a few values of 17676@i{x} (less than 1%). 17677 17678Default is @code{FALSE}. 17679@end deftypefn 17680@end ifinfo 17681@ifnotinfo 17682@anchor{funct:unur_tdr_set_verify} 17683@deftypefn {} {int} unur_tdr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 17684@anchor{funct:unur_tdr_chg_verify} 17685@deftypefnx {} {int} unur_tdr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 17686Turn verifying of algorithm while sampling on/off. 17687If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 17688violated for some @i{x} then @code{unur_errno} is set to 17689@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 17690happen due to round-off errors for a few values of 17691@i{x} (less than 1%). 17692 17693Default is @code{FALSE}. 17694@end deftypefn 17695@end ifnotinfo 17696 17697@ifinfo 17698@anchor{funct:unur_tdr_set_pedantic} 17699@deftypefn Function {int} unur_tdr_set_pedantic (UNUR_PAR* @var{parameters}, int @var{pedantic}) 17700Sometimes it might happen that 17701@ifhtml 17702@ref{funct:unur_init,@command{unur_init}} 17703@end ifhtml 17704@ifnothtml 17705@command{unur_init} 17706@end ifnothtml 17707has been executed 17708successfully. But when additional construction points are added by 17709adaptive rejection sampling, the algorithm detects that the 17710PDF is not T-concave. 17711 17712With @var{pedantic} being @code{TRUE}, the 17713sampling routine is exchanged by a routine that simply returns 17714@code{UNUR_INFINITY}. Otherwise the new point is not added to the 17715list of construction points. At least the hat function remains 17716T-concave. 17717 17718Setting @var{pedantic} to @code{FALSE} allows sampling from a 17719distribution which is ``almost'' T-concave and small errors are 17720tolerated. However it might happen that the hat function cannot be 17721improved significantly. When the hat functions that has been 17722constructed by the 17723@ifhtml 17724@ref{funct:unur_init,@command{unur_init}} 17725@end ifhtml 17726@ifnothtml 17727@command{unur_init} 17728@end ifnothtml 17729call is extremely large then it 17730might happen that the generation times are extremely high 17731(even hours are possible in extremely rare cases). 17732 17733Default is @code{FALSE}. 17734@end deftypefn 17735@end ifinfo 17736@ifnotinfo 17737@anchor{funct:unur_tdr_set_pedantic} 17738@deftypefn {} {int} unur_tdr_set_pedantic (UNUR_PAR* @var{parameters}, int @var{pedantic}) 17739Sometimes it might happen that 17740@ifhtml 17741@ref{funct:unur_init,@command{unur_init}} 17742@end ifhtml 17743@ifnothtml 17744@command{unur_init} 17745@end ifnothtml 17746has been executed 17747successfully. But when additional construction points are added by 17748adaptive rejection sampling, the algorithm detects that the 17749PDF is not T-concave. 17750 17751With @var{pedantic} being @code{TRUE}, the 17752sampling routine is exchanged by a routine that simply returns 17753@code{UNUR_INFINITY}. Otherwise the new point is not added to the 17754list of construction points. At least the hat function remains 17755T-concave. 17756 17757Setting @var{pedantic} to @code{FALSE} allows sampling from a 17758distribution which is ``almost'' T-concave and small errors are 17759tolerated. However it might happen that the hat function cannot be 17760improved significantly. When the hat functions that has been 17761constructed by the 17762@ifhtml 17763@ref{funct:unur_init,@command{unur_init}} 17764@end ifhtml 17765@ifnothtml 17766@command{unur_init} 17767@end ifnothtml 17768call is extremely large then it 17769might happen that the generation times are extremely high 17770(even hours are possible in extremely rare cases). 17771 17772Default is @code{FALSE}. 17773@end deftypefn 17774@end ifnotinfo 17775 17776@ifinfo 17777@anchor{funct:unur_tdr_eval_invcdfhat} 17778@deftypefn Function {double} unur_tdr_eval_invcdfhat (const @var{UNUR_GEN* generator}, double @var{u}, double* @var{hx}, double* @var{fx}, double* @var{sqx}) 17779Evaluate the inverse of the CDF of the hat distribution at @var{u}. 17780As a side effect the values of the hat, the density, and the squeeze 17781at the computed point @i{x} are stored in @var{hx}, @var{fx}, and 17782@var{sqx}, respectively. However, these computations are suppressed 17783if the corresponding variable is set to @code{NULL}. 17784 17785If @var{u} is out of the domain [0,1] then @code{unur_errno} is set 17786to @code{UNUR_ERR_DOMAIN} and the respective bound of 17787the domain of the distribution are returned (which is 17788@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 17789unbounded domains). 17790 17791@emph{Important:} 17792This call does not work for variant @code{IA} (immediate 17793acceptance). In this case the hat CDF is evaluated as if 17794variant @code{PS} is used. 17795 17796@emph{Notice}: This function always evaluates the inverse CDF of 17797the hat distribution. A call to 17798@ifhtml 17799@ref{funct:unur_tdr_chg_truncated,@command{unur_tdr_chg_truncated}} 17800@end ifhtml 17801@ifnothtml 17802@command{unur_tdr_chg_truncated} 17803@end ifnothtml 17804call 17805has no effect. 17806@end deftypefn 17807@end ifinfo 17808@ifnotinfo 17809@anchor{funct:unur_tdr_eval_invcdfhat} 17810@deftypefn {} {double} unur_tdr_eval_invcdfhat (const @var{UNUR_GEN* generator}, double @var{u}, double* @var{hx}, double* @var{fx}, double* @var{sqx}) 17811Evaluate the inverse of the CDF of the hat distribution at @var{u}. 17812As a side effect the values of the hat, the density, and the squeeze 17813at the computed point @i{x} are stored in @var{hx}, @var{fx}, and 17814@var{sqx}, respectively. However, these computations are suppressed 17815if the corresponding variable is set to @code{NULL}. 17816 17817If @var{u} is out of the domain [0,1] then @code{unur_errno} is set 17818to @code{UNUR_ERR_DOMAIN} and the respective bound of 17819the domain of the distribution are returned (which is 17820@code{-UNUR_INFINITY} or @code{UNUR_INFINITY} in the case of 17821unbounded domains). 17822 17823@emph{Important:} 17824This call does not work for variant @code{IA} (immediate 17825acceptance). In this case the hat CDF is evaluated as if 17826variant @code{PS} is used. 17827 17828@emph{Notice}: This function always evaluates the inverse CDF of 17829the hat distribution. A call to 17830@ifhtml 17831@ref{funct:unur_tdr_chg_truncated,@command{unur_tdr_chg_truncated}} 17832@end ifhtml 17833@ifnothtml 17834@command{unur_tdr_chg_truncated} 17835@end ifnothtml 17836call 17837has no effect. 17838@end deftypefn 17839@end ifnotinfo 17840 17841 17842 17843 17844@c 17845@c end of tdr.h 17846@c ------------------------------------- 17847@c ------------------------------------- 17848@c utdr.h 17849@c 17850 17851@page 17852@node UTDR 17853@subsection UTDR -- Universal Transformed Density Rejection 17854 17855@table @i 17856@item Required: 17857T-concave PDF, mode, approximate area 17858@item Speed: 17859Set-up: moderate, Sampling: Moderate 17860@item Reinit: 17861supported 17862@item Reference: 17863@ifhtml 17864@ref{bib:HWa95,, [HWa95]} 17865@end ifhtml 17866@ifnothtml 17867[HWa95] 17868@end ifnothtml 17869@ifhtml 17870@ref{bib:HLD04,, [HLD04: Sect.4.5.4; Alg.4.4]} 17871@end ifhtml 17872@ifnothtml 17873[HLD04: Sect.4.5.4; Alg.4.4] 17874@end ifnothtml 17875 17876@end table 17877@sp 1 17878 17879 17880UTDR is based on the transformed density rejection and uses 17881three almost optimal points for constructing hat and squeezes. 17882It works for all @i{T}-concave distributions with 17883@iftex 17884@math{T(x) = -1/\sqrt(x).} 17885@end iftex 17886@ifhtml 17887@html 17888<I>T</I>(<I>x</I>) = -1/sqrt(()<I>x</I>). 17889@end html 17890@end ifhtml 17891@ifinfo 17892@math{T(x) = -1/sqrt(x).} 17893@end ifinfo 17894 17895It requires the PDF and the (exact) location of the mode. 17896Notice that if no mode is given at all, a (slow) numerical mode 17897finder will be used. 17898Moreover the approximate area below the given PDF is used. 17899(If no area is given for the distribution the algorithm assumes that it 17900is approximately 1.) 17901The rejection constant is bounded from above by 4 17902for all @i{T}-concave distributions. 17903 17904 17905@subsubheading How To Use 17906 17907 17908UTDR works for any continuous univariate distribution object with 17909given @i{T}-concave PDF (with 17910@iftex 17911@math{T(x) = -1/\sqrt{x},)} 17912@end iftex 17913@ifhtml 17914@html 17915<I>T</I>(<I>x</I>) = -1/sqrt(<I>x</I>),) 17916@end html 17917@end ifhtml 17918@ifinfo 17919@math{T(x) = -1/sqrt(x),)} 17920@end ifinfo 17921mode and approximate area below PDF. 17922 17923When the PDF does not change at the mode for varying parameters, then 17924this value can be set with 17925@ifhtml 17926@ref{funct:unur_utdr_set_pdfatmode,@command{unur_utdr_set_pdfatmode}} 17927@end ifhtml 17928@ifnothtml 17929@command{unur_utdr_set_pdfatmode} 17930@end ifnothtml 17931to avoid some 17932computations. Since this value will not be updated any more when the 17933parameters of the distribution are changed, 17934the 17935@ifhtml 17936@ref{funct:unur_utdr_chg_pdfatmode,@command{unur_utdr_chg_pdfatmode}} 17937@end ifhtml 17938@ifnothtml 17939@command{unur_utdr_chg_pdfatmode} 17940@end ifnothtml 17941call is necessary to do this manually. 17942 17943It is possible to change the parameters and the domain of the chosen 17944distribution and run 17945@ifhtml 17946@ref{funct:unur_reinit,@command{unur_reinit}} 17947@end ifhtml 17948@ifnothtml 17949@command{unur_reinit} 17950@end ifnothtml 17951to reinitialize the generator object. 17952Notice, that derived parameters like the mode must also be (re-) set 17953if the parameters or the domain has be changed. 17954Moreover, if the PDF at the mode has been provided by a 17955@ifhtml 17956@ref{funct:unur_utdr_set_pdfatmode,@command{unur_utdr_set_pdfatmode}} 17957@end ifhtml 17958@ifnothtml 17959@command{unur_utdr_set_pdfatmode} 17960@end ifnothtml 17961call, additionally 17962@ifhtml 17963@ref{funct:unur_utdr_chg_pdfatmode,@command{unur_utdr_chg_pdfatmode}} 17964@end ifhtml 17965@ifnothtml 17966@command{unur_utdr_chg_pdfatmode} 17967@end ifnothtml 17968must be used (otherwise this call is 17969not necessary since then this figure is computed directly from 17970the PDF). 17971 17972There exists a test mode that verifies whether the conditions for 17973the method are satisfied or not. It can be switched on by calling 17974@ifhtml 17975@ref{funct:unur_utdr_set_verify,@command{unur_utdr_set_verify}} 17976@end ifhtml 17977@ifnothtml 17978@command{unur_utdr_set_verify} 17979@end ifnothtml 17980and 17981@ifhtml 17982@ref{funct:unur_utdr_chg_verify,@command{unur_utdr_chg_verify},} 17983@end ifhtml 17984@ifnothtml 17985@command{unur_utdr_chg_verify}, 17986@end ifnothtml 17987respectively. 17988Notice however that sampling is slower then. 17989 17990 17991 17992 17993@subheading Function reference 17994 17995@ifhtml 17996@itemize 17997@item @ref{funct:unur_utdr_new,unur_utdr_new} 17998@item @ref{funct:unur_utdr_set_pdfatmode,unur_utdr_set_pdfatmode} 17999@item @ref{funct:unur_utdr_set_cpfactor,unur_utdr_set_cpfactor} 18000@item @ref{funct:unur_utdr_set_deltafactor,unur_utdr_set_deltafactor} 18001@item @ref{funct:unur_utdr_set_verify,unur_utdr_set_verify} 18002@item @ref{funct:unur_utdr_chg_verify,unur_utdr_chg_verify} 18003@item @ref{funct:unur_utdr_chg_pdfatmode,unur_utdr_chg_pdfatmode} 18004@end itemize 18005@end ifhtml 18006 18007 18008@ifinfo 18009@anchor{funct:unur_utdr_new} 18010@deftypefn Function {UNUR_PAR*} unur_utdr_new (const @var{UNUR_DISTR* distribution}) 18011Get default parameters for generator. 18012@end deftypefn 18013@end ifinfo 18014@ifnotinfo 18015@anchor{funct:unur_utdr_new} 18016@deftypefn {} {UNUR_PAR*} unur_utdr_new (const @var{UNUR_DISTR* distribution}) 18017Get default parameters for generator. 18018@end deftypefn 18019@end ifnotinfo 18020 18021@ifinfo 18022@anchor{funct:unur_utdr_set_pdfatmode} 18023@deftypefn Function {int} unur_utdr_set_pdfatmode (UNUR_PAR* @var{parameters}, double @var{fmode}) 18024Set pdf at mode. 18025When set, the PDF at the mode is never changed. 18026This is to avoid additional computations, when the PDF does not 18027change when parameters of the distributions vary. 18028It is only useful when the PDF at the mode does not change with 18029changing parameters for the distribution. 18030 18031Default: not set. 18032@end deftypefn 18033@end ifinfo 18034@ifnotinfo 18035@anchor{funct:unur_utdr_set_pdfatmode} 18036@deftypefn {} {int} unur_utdr_set_pdfatmode (UNUR_PAR* @var{parameters}, double @var{fmode}) 18037Set pdf at mode. 18038When set, the PDF at the mode is never changed. 18039This is to avoid additional computations, when the PDF does not 18040change when parameters of the distributions vary. 18041It is only useful when the PDF at the mode does not change with 18042changing parameters for the distribution. 18043 18044Default: not set. 18045@end deftypefn 18046@end ifnotinfo 18047 18048@ifinfo 18049@anchor{funct:unur_utdr_set_cpfactor} 18050@deftypefn Function {int} unur_utdr_set_cpfactor (UNUR_PAR* @var{parameters}, double @var{cp_factor}) 18051Set factor for position of left and right construction point. 18052The @var{cp_factor} is used to find almost optimal construction 18053points for the hat function. 18054There is no need to change this factor in almost all situations. 18055 18056Default is @code{0.664}. 18057@end deftypefn 18058@end ifinfo 18059@ifnotinfo 18060@anchor{funct:unur_utdr_set_cpfactor} 18061@deftypefn {} {int} unur_utdr_set_cpfactor (UNUR_PAR* @var{parameters}, double @var{cp_factor}) 18062Set factor for position of left and right construction point. 18063The @var{cp_factor} is used to find almost optimal construction 18064points for the hat function. 18065There is no need to change this factor in almost all situations. 18066 18067Default is @code{0.664}. 18068@end deftypefn 18069@end ifnotinfo 18070 18071@ifinfo 18072@anchor{funct:unur_utdr_set_deltafactor} 18073@deftypefn Function {int} unur_utdr_set_deltafactor (UNUR_PAR* @var{parameters}, double @var{delta}) 18074Set factor for replacing tangents by secants. 18075higher factors increase the rejection constant but reduces the risk of 18076serious round-off errors. 18077There is no need to change this factor it almost all situations. 18078 18079Default is @code{1.e-5}. 18080@end deftypefn 18081@end ifinfo 18082@ifnotinfo 18083@anchor{funct:unur_utdr_set_deltafactor} 18084@deftypefn {} {int} unur_utdr_set_deltafactor (UNUR_PAR* @var{parameters}, double @var{delta}) 18085Set factor for replacing tangents by secants. 18086higher factors increase the rejection constant but reduces the risk of 18087serious round-off errors. 18088There is no need to change this factor it almost all situations. 18089 18090Default is @code{1.e-5}. 18091@end deftypefn 18092@end ifnotinfo 18093 18094@ifinfo 18095@anchor{funct:unur_utdr_set_verify} 18096@deftypefn Function {int} unur_utdr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 18097@anchor{funct:unur_utdr_chg_verify} 18098@deftypefnx Function {int} unur_utdr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 18099Turn verifying of algorithm while sampling on/off. 18100If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 18101violated for some @i{x} then @code{unur_errno} is set to 18102@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 18103happen due to round-off errors for a few values of 18104@i{x} (less than 1%). 18105 18106Default is @code{FALSE}. 18107@end deftypefn 18108@end ifinfo 18109@ifnotinfo 18110@anchor{funct:unur_utdr_set_verify} 18111@deftypefn {} {int} unur_utdr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 18112@anchor{funct:unur_utdr_chg_verify} 18113@deftypefnx {} {int} unur_utdr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 18114Turn verifying of algorithm while sampling on/off. 18115If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 18116violated for some @i{x} then @code{unur_errno} is set to 18117@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 18118happen due to round-off errors for a few values of 18119@i{x} (less than 1%). 18120 18121Default is @code{FALSE}. 18122@end deftypefn 18123@end ifnotinfo 18124 18125@ifinfo 18126@anchor{funct:unur_utdr_chg_pdfatmode} 18127@deftypefn Function {int} unur_utdr_chg_pdfatmode (UNUR_GEN* @var{generator}, double @var{fmode}) 18128Change PDF at mode of distribution. 18129@ifhtml 18130@ref{funct:unur_reinit,@command{unur_reinit}} 18131@end ifhtml 18132@ifnothtml 18133@command{unur_reinit} 18134@end ifnothtml 18135must be executed before sampling from the 18136generator again. 18137@end deftypefn 18138@end ifinfo 18139@ifnotinfo 18140@anchor{funct:unur_utdr_chg_pdfatmode} 18141@deftypefn {} {int} unur_utdr_chg_pdfatmode (UNUR_GEN* @var{generator}, double @var{fmode}) 18142Change PDF at mode of distribution. 18143@ifhtml 18144@ref{funct:unur_reinit,@command{unur_reinit}} 18145@end ifhtml 18146@ifnothtml 18147@command{unur_reinit} 18148@end ifnothtml 18149must be executed before sampling from the 18150generator again. 18151@end deftypefn 18152@end ifnotinfo 18153 18154 18155 18156 18157@c 18158@c end of utdr.h 18159@c ------------------------------------- 18160@c ------------------------------------- 18161@c methods.dh 18162@c 18163 18164@page 18165@node Methods_for_CEMP 18166@section Methods for continuous empirical univariate distributions 18167 18168@menu 18169* EMPK:: EMPirical distribution with Kernel smoothing 18170* EMPL:: EMPirical distribution with Linear interpolation 18171* HIST:: HISTogramm of empirical distribution 18172@end menu 18173 18174 18175 18176@subheading Overview of methods 18177 18178@include methods_cemp.texi 18179 18180@subheading Example 18181 18182@smallexample 18183@include ref_example_emp.texi 18184@end smallexample 18185 18186@subheading Example (String API) 18187 18188@smallexample 18189@include ref_example_emp_str.texi 18190@end smallexample 18191 18192 18193 18194@c 18195@c end of methods.dh 18196@c ------------------------------------- 18197@c ------------------------------------- 18198@c empk.h 18199@c 18200 18201@page 18202@node EMPK 18203@subsection EMPK -- EMPirical distribution with Kernel smoothing 18204 18205@table @i 18206@item Required: 18207observed sample 18208@item Speed: 18209Set-up: slow (as sample is sorted), Sampling: fast (depends on kernel) 18210@item Reinit: 18211not implemented 18212@item Reference: 18213@ifhtml 18214@ref{bib:HLa00,, [HLa00]} 18215@end ifhtml 18216@ifnothtml 18217[HLa00] 18218@end ifnothtml 18219@ifhtml 18220@ref{bib:HLD04,, [HLD04: Sect.12.1.2]} 18221@end ifhtml 18222@ifnothtml 18223[HLD04: Sect.12.1.2] 18224@end ifnothtml 18225 18226@end table 18227@sp 1 18228 18229 18230EMPK generates random variates from an empirical distribution that is 18231given by an observed sample. The idea is that simply choosing a random 18232point from the sample and to return it with some added noise results 18233in a method that has very nice properties, as it can be seen as sampling 18234from a kernel density estimate. If the underlying distribution is 18235continuous, especially the fine structur of the resulting empirical 18236distribution is much better than using only resampling without noise. 18237 18238Clearly we have to decide about the density of the noise (called kernel) 18239and about the standard deviation of the noise. 18240The mathematical theory of kernel density estimation shows us that we 18241are comparatively free in choosing the kernel. It also supplies us with 18242a simple formula to compute the optimal standarddeviation of the noise, 18243called bandwidth (or window width) of the kernel. 18244 18245The variance of the estimated density is slightly larger than 18246that of the observed sample. However, this can be easily 18247corrected if required. 18248 18249There is also a correction (mirroring technique) for 18250distributions with non-negative support. 18251 18252A simple robust reference method is implemented to find a good 18253standard deviation of the noise (i.e. the bandwidth of 18254kernel density estimation). For some cases 18255(e.g. densities with two or more sharp distinct peaks) there 18256kernel density estimation can be adjusted by changing the 18257smoothness factor and the so called beta factor. 18258 18259 18260@subsubheading How To Use 18261 18262 18263EMPK uses empirical distributions. The main parameter is the 18264choice if of kernel density. The most important kernels can be 18265set by 18266@ifhtml 18267@ref{funct:unur_empk_set_kernel,@command{unur_empk_set_kernel}.} 18268@end ifhtml 18269@ifnothtml 18270@command{unur_empk_set_kernel}. 18271@end ifnothtml 18272Additionally generators for other 18273kernels can be used by using 18274@ifhtml 18275@ref{funct:unur_empk_set_kernelgen,@command{unur_empk_set_kernelgen}} 18276@end ifhtml 18277@ifnothtml 18278@command{unur_empk_set_kernelgen} 18279@end ifnothtml 18280instead. 18281Additionally variance correction and a correction for 18282non-negative variates can be switched on. 18283 18284The two other parameters (smoothing factor and beta factor) are 18285only useful for people knowing the theory of kernel density 18286estimation. It is not necessary to change them if 18287the true underlying distribution is somehow comparable with a 18288bell-shaped curve, even skewed or with some not too sharp extra peaks. 18289In all these cases the simple robust reference method implemented to 18290find a good standard deviation of the noise (i.e. the bandwidth of 18291kernel density estimation) should give sensible results. 18292However, it might be necessary to overwrite this automatic method 18293to find the bandwidth eg. when resampling from data with 18294two or more sharp distinct peaks. Then the distribution has nearly 18295discrete components as well and our automatic method may 18296easily choose too large a bandwidth which results in an 18297empirical distribution which is oversmoothed (i.e. it has 18298lower peaks than the original distribution). Then it 18299is recommended to decrease the bandwidth using the 18300@ifhtml 18301@ref{funct:unur_empk_set_smoothing,@command{unur_empk_set_smoothing}} 18302@end ifhtml 18303@ifnothtml 18304@command{unur_empk_set_smoothing} 18305@end ifnothtml 18306call. A smoothing factor of @code{1} 18307is the default. A smoothing factor of @code{0} leads to naive 18308resampling of the data. Thus an appropriate value between these 18309extremes should be choosen. We recommend to consult a reference 18310on kernel smoothing when doing so; but it is not a simple problem 18311to determine an optimal bandwidth for distributions with sharp peaks. 18312 18313In general, for most applications it is perfectly ok to use the 18314default values offered. Unless you have some knowledge on 18315density estimation we do not recommend to change anything. 18316There are two exceptions: 18317 18318@enumerate A 18319@item 18320In the case that the unknown underlying distribution is not continuous 18321but discrete you should "turn off" the adding of the noise by setting: 18322@smallexample 18323unur_empk_set_smoothing(par, 0.) 18324@end smallexample 18325 18326@item 18327In the case that you are especially 18328interested in a fast sampling algorithm use the call 18329@smallexample 18330unur_empk_set_kernel(par, UNUR_DISTR_BOXCAR); 18331@end smallexample 18332to change the used noise distribution from the default Gaussian 18333distribution to the uniform distribution. 18334@end enumerate 18335 18336 18337 18338 18339@subheading Function reference 18340 18341@ifhtml 18342@itemize 18343@item @ref{funct:unur_empk_new,unur_empk_new} 18344@item @ref{funct:unur_empk_set_kernel,unur_empk_set_kernel} 18345@item @ref{funct:unur_empk_set_kernelgen,unur_empk_set_kernelgen} 18346@item @ref{funct:unur_empk_set_beta,unur_empk_set_beta} 18347@item @ref{funct:unur_empk_set_smoothing,unur_empk_set_smoothing} 18348@item @ref{funct:unur_empk_chg_smoothing,unur_empk_chg_smoothing} 18349@item @ref{funct:unur_empk_set_varcor,unur_empk_set_varcor} 18350@item @ref{funct:unur_empk_chg_varcor,unur_empk_chg_varcor} 18351@item @ref{funct:unur_empk_set_positive,unur_empk_set_positive} 18352@end itemize 18353@end ifhtml 18354 18355 18356@ifinfo 18357@anchor{funct:unur_empk_new} 18358@deftypefn Function {UNUR_PAR*} unur_empk_new (const @var{UNUR_DISTR* distribution}) 18359Get default parameters for generator. 18360@end deftypefn 18361@end ifinfo 18362@ifnotinfo 18363@anchor{funct:unur_empk_new} 18364@deftypefn {} {UNUR_PAR*} unur_empk_new (const @var{UNUR_DISTR* distribution}) 18365Get default parameters for generator. 18366@end deftypefn 18367@end ifnotinfo 18368 18369@ifinfo 18370@anchor{funct:unur_empk_set_kernel} 18371@deftypefn Function {int} unur_empk_set_kernel (UNUR_PAR* @var{parameters}, unsigned @var{kernel}) 18372Select one of the supported kernel distributions. Currently the following 18373kernels are supported: 18374 18375@table @code 18376@item UNUR_DISTR_GAUSSIAN 18377Gaussian (normal) kernel 18378@item UNUR_DISTR_EPANECHNIKOV 18379Epanechnikov kernel 18380@item UNUR_DISTR_BOXCAR 18381Boxcar (uniform, rectangular) kernel 18382@item UNUR_DISTR_STUDENT 18383t3 kernel (Student's distribution with 3 degrees of freedom) 18384@item UNUR_DISTR_LOGISTIC 18385logistic kernel 18386@end table 18387 18388For other kernels (including kernels with Student's distribution 18389with other than 3 degrees of freedom) use the 18390@ifhtml 18391@ref{funct:unur_empk_set_kernelgen,@command{unur_empk_set_kernelgen}} 18392@end ifhtml 18393@ifnothtml 18394@command{unur_empk_set_kernelgen} 18395@end ifnothtml 18396call. 18397 18398It is not possible to call 18399@ifhtml 18400@ref{funct:unur_empk_set_kernel,@command{unur_empk_set_kernel}} 18401@end ifhtml 18402@ifnothtml 18403@command{unur_empk_set_kernel} 18404@end ifnothtml 18405twice. 18406 18407Default is the Gaussian kernel. 18408@end deftypefn 18409@end ifinfo 18410@ifnotinfo 18411@anchor{funct:unur_empk_set_kernel} 18412@deftypefn {} {int} unur_empk_set_kernel (UNUR_PAR* @var{parameters}, unsigned @var{kernel}) 18413Select one of the supported kernel distributions. Currently the following 18414kernels are supported: 18415 18416@table @code 18417@item UNUR_DISTR_GAUSSIAN 18418Gaussian (normal) kernel 18419@item UNUR_DISTR_EPANECHNIKOV 18420Epanechnikov kernel 18421@item UNUR_DISTR_BOXCAR 18422Boxcar (uniform, rectangular) kernel 18423@item UNUR_DISTR_STUDENT 18424t3 kernel (Student's distribution with 3 degrees of freedom) 18425@item UNUR_DISTR_LOGISTIC 18426logistic kernel 18427@end table 18428 18429For other kernels (including kernels with Student's distribution 18430with other than 3 degrees of freedom) use the 18431@ifhtml 18432@ref{funct:unur_empk_set_kernelgen,@command{unur_empk_set_kernelgen}} 18433@end ifhtml 18434@ifnothtml 18435@command{unur_empk_set_kernelgen} 18436@end ifnothtml 18437call. 18438 18439It is not possible to call 18440@ifhtml 18441@ref{funct:unur_empk_set_kernel,@command{unur_empk_set_kernel}} 18442@end ifhtml 18443@ifnothtml 18444@command{unur_empk_set_kernel} 18445@end ifnothtml 18446twice. 18447 18448Default is the Gaussian kernel. 18449@end deftypefn 18450@end ifnotinfo 18451 18452@ifinfo 18453@anchor{funct:unur_empk_set_kernelgen} 18454@deftypefn Function {int} unur_empk_set_kernelgen (UNUR_PAR* @var{parameters}, const @var{UNUR_GEN* kernelgen}, double @var{alpha}, double @var{kernelvar}) 18455Set generator for the kernel used for density estimation. 18456 18457@var{alpha} is used to compute the optimal bandwidth from the point of 18458view of minimizing the mean integrated square error (MISE). 18459It depends on the kernel K and is given by 18460@smallexample 18461alpha(K) = Var(K)^(-2/5)@{ \int K(t)^2 dt@}^(1/5) 18462@end smallexample 18463For standard kernels (see above) alpha is computed by the algorithm. 18464 18465@var{kernvar} is the variance of the used kernel. It is only required 18466for the variance corrected version of density estimation (which is 18467used by default); otherwise it is ignored. 18468If @var{kernelvar} is nonpositive, variance correction is disabled. 18469For standard kernels (see above) @var{kernvar} is computed by the 18470algorithm. 18471 18472It is not possible to call 18473@ifhtml 18474@ref{funct:unur_empk_set_kernelgen,@command{unur_empk_set_kernelgen}} 18475@end ifhtml 18476@ifnothtml 18477@command{unur_empk_set_kernelgen} 18478@end ifnothtml 18479after a standard kernel 18480has been selected by a 18481@ifhtml 18482@ref{funct:unur_empk_set_kernel,@command{unur_empk_set_kernel}} 18483@end ifhtml 18484@ifnothtml 18485@command{unur_empk_set_kernel} 18486@end ifnothtml 18487call. 18488 18489Notice that the uniform random number generator of the kernel 18490generator is overwritten during the 18491@ifhtml 18492@ref{funct:unur_init,@command{unur_init}} 18493@end ifhtml 18494@ifnothtml 18495@command{unur_init} 18496@end ifnothtml 18497call and at each 18498@ifhtml 18499@ref{funct:unur_chg_urng,@command{unur_chg_urng}} 18500@end ifhtml 18501@ifnothtml 18502@command{unur_chg_urng} 18503@end ifnothtml 18504call with the uniform generator used for the empirical 18505distribution. 18506 18507Default is the Gaussian kernel. 18508@end deftypefn 18509@end ifinfo 18510@ifnotinfo 18511@anchor{funct:unur_empk_set_kernelgen} 18512@deftypefn {} {int} unur_empk_set_kernelgen (UNUR_PAR* @var{parameters}, const @var{UNUR_GEN* kernelgen}, double @var{alpha}, double @var{kernelvar}) 18513Set generator for the kernel used for density estimation. 18514 18515@var{alpha} is used to compute the optimal bandwidth from the point of 18516view of minimizing the mean integrated square error (MISE). 18517It depends on the kernel K and is given by 18518@smallexample 18519alpha(K) = Var(K)^(-2/5)@{ \int K(t)^2 dt@}^(1/5) 18520@end smallexample 18521For standard kernels (see above) alpha is computed by the algorithm. 18522 18523@var{kernvar} is the variance of the used kernel. It is only required 18524for the variance corrected version of density estimation (which is 18525used by default); otherwise it is ignored. 18526If @var{kernelvar} is nonpositive, variance correction is disabled. 18527For standard kernels (see above) @var{kernvar} is computed by the 18528algorithm. 18529 18530It is not possible to call 18531@ifhtml 18532@ref{funct:unur_empk_set_kernelgen,@command{unur_empk_set_kernelgen}} 18533@end ifhtml 18534@ifnothtml 18535@command{unur_empk_set_kernelgen} 18536@end ifnothtml 18537after a standard kernel 18538has been selected by a 18539@ifhtml 18540@ref{funct:unur_empk_set_kernel,@command{unur_empk_set_kernel}} 18541@end ifhtml 18542@ifnothtml 18543@command{unur_empk_set_kernel} 18544@end ifnothtml 18545call. 18546 18547Notice that the uniform random number generator of the kernel 18548generator is overwritten during the 18549@ifhtml 18550@ref{funct:unur_init,@command{unur_init}} 18551@end ifhtml 18552@ifnothtml 18553@command{unur_init} 18554@end ifnothtml 18555call and at each 18556@ifhtml 18557@ref{funct:unur_chg_urng,@command{unur_chg_urng}} 18558@end ifhtml 18559@ifnothtml 18560@command{unur_chg_urng} 18561@end ifnothtml 18562call with the uniform generator used for the empirical 18563distribution. 18564 18565Default is the Gaussian kernel. 18566@end deftypefn 18567@end ifnotinfo 18568 18569@ifinfo 18570@anchor{funct:unur_empk_set_beta} 18571@deftypefn Function {int} unur_empk_set_beta (UNUR_PAR* @var{parameters}, double @var{beta}) 18572@var{beta} is used to compute the optimal bandwidth from the point 18573of view of minimizing the mean integrated square error (MISE). 18574@var{beta} depends on the (unknown) distribution of the sampled data 18575points. 18576By default Gaussian distribution is assumed for the sample 18577(@var{beta} = 1.3637439). There is no requirement to change 18578@var{beta}. 18579 18580Default: @code{1.3637439} 18581@end deftypefn 18582@end ifinfo 18583@ifnotinfo 18584@anchor{funct:unur_empk_set_beta} 18585@deftypefn {} {int} unur_empk_set_beta (UNUR_PAR* @var{parameters}, double @var{beta}) 18586@var{beta} is used to compute the optimal bandwidth from the point 18587of view of minimizing the mean integrated square error (MISE). 18588@var{beta} depends on the (unknown) distribution of the sampled data 18589points. 18590By default Gaussian distribution is assumed for the sample 18591(@var{beta} = 1.3637439). There is no requirement to change 18592@var{beta}. 18593 18594Default: @code{1.3637439} 18595@end deftypefn 18596@end ifnotinfo 18597 18598@ifinfo 18599@anchor{funct:unur_empk_set_smoothing} 18600@deftypefn Function {int} unur_empk_set_smoothing (UNUR_PAR* @var{parameters}, double @var{smoothing}) 18601@anchor{funct:unur_empk_chg_smoothing} 18602@deftypefnx Function {int} unur_empk_chg_smoothing (UNUR_GEN* @var{generator}, double @var{smoothing}) 18603Set and change the smoothing factor. 18604The smoothing factor controlles how ``smooth'' the resulting density 18605estimation will be. A smoothing factor equal to @code{0} results in naive 18606resampling. A very large smoothing factor (together with the 18607variance correction) results in a density which is approximately 18608equal to the kernel. 18609Default is 1 which results in a smoothing parameter minimising 18610the MISE (mean integrated squared error) if the data are not too 18611far away from normal. If a large smoothing factor is used, then 18612variance correction must be switched on. 18613 18614Default: @code{1} 18615@end deftypefn 18616@end ifinfo 18617@ifnotinfo 18618@anchor{funct:unur_empk_set_smoothing} 18619@deftypefn {} {int} unur_empk_set_smoothing (UNUR_PAR* @var{parameters}, double @var{smoothing}) 18620@anchor{funct:unur_empk_chg_smoothing} 18621@deftypefnx {} {int} unur_empk_chg_smoothing (UNUR_GEN* @var{generator}, double @var{smoothing}) 18622Set and change the smoothing factor. 18623The smoothing factor controlles how ``smooth'' the resulting density 18624estimation will be. A smoothing factor equal to @code{0} results in naive 18625resampling. A very large smoothing factor (together with the 18626variance correction) results in a density which is approximately 18627equal to the kernel. 18628Default is 1 which results in a smoothing parameter minimising 18629the MISE (mean integrated squared error) if the data are not too 18630far away from normal. If a large smoothing factor is used, then 18631variance correction must be switched on. 18632 18633Default: @code{1} 18634@end deftypefn 18635@end ifnotinfo 18636 18637@ifinfo 18638@anchor{funct:unur_empk_set_varcor} 18639@deftypefn Function {int} unur_empk_set_varcor (UNUR_PAR* @var{parameters}, int @var{varcor}) 18640@anchor{funct:unur_empk_chg_varcor} 18641@deftypefnx Function {int} unur_empk_chg_varcor (UNUR_GEN* @var{generator}, int @var{varcor}) 18642Switch variance correction in generator on/off. 18643If @var{varcor} is @code{TRUE} then the variance of the used 18644density estimation is the same as the sample variance. However this 18645increases the MISE of the estimation a little bit. 18646 18647Default is @code{FALSE}. 18648@end deftypefn 18649@end ifinfo 18650@ifnotinfo 18651@anchor{funct:unur_empk_set_varcor} 18652@deftypefn {} {int} unur_empk_set_varcor (UNUR_PAR* @var{parameters}, int @var{varcor}) 18653@anchor{funct:unur_empk_chg_varcor} 18654@deftypefnx {} {int} unur_empk_chg_varcor (UNUR_GEN* @var{generator}, int @var{varcor}) 18655Switch variance correction in generator on/off. 18656If @var{varcor} is @code{TRUE} then the variance of the used 18657density estimation is the same as the sample variance. However this 18658increases the MISE of the estimation a little bit. 18659 18660Default is @code{FALSE}. 18661@end deftypefn 18662@end ifnotinfo 18663 18664@ifinfo 18665@anchor{funct:unur_empk_set_positive} 18666@deftypefn Function {int} unur_empk_set_positive (UNUR_PAR* @var{parameters}, int @var{positive}) 18667If @var{positive} is @code{TRUE} then only nonnegative random variates are 18668generated. This is done by means of a mirroring technique. 18669 18670Default is @code{FALSE}. 18671@end deftypefn 18672@end ifinfo 18673@ifnotinfo 18674@anchor{funct:unur_empk_set_positive} 18675@deftypefn {} {int} unur_empk_set_positive (UNUR_PAR* @var{parameters}, int @var{positive}) 18676If @var{positive} is @code{TRUE} then only nonnegative random variates are 18677generated. This is done by means of a mirroring technique. 18678 18679Default is @code{FALSE}. 18680@end deftypefn 18681@end ifnotinfo 18682 18683 18684 18685 18686@c 18687@c end of empk.h 18688@c ------------------------------------- 18689@c ------------------------------------- 18690@c empl.h 18691@c 18692 18693@page 18694@node EMPL 18695@subsection EMPL -- EMPirical distribution with Linear interpolation 18696 18697@table @i 18698@item Required: 18699observed sample 18700@item Speed: 18701Set-up: slow (as sample is sorted), Sampling: very fast (inversion) 18702@item Reinit: 18703not implemented 18704@item Reference: 18705@ifhtml 18706@ref{bib:HLa00,, [HLa00]} 18707@end ifhtml 18708@ifnothtml 18709[HLa00] 18710@end ifnothtml 18711@ifhtml 18712@ref{bib:HLD04,, [HLD04: Sect.12.1.3]} 18713@end ifhtml 18714@ifnothtml 18715[HLD04: Sect.12.1.3] 18716@end ifnothtml 18717 18718@end table 18719@sp 1 18720 18721 18722EMPL generates random variates from an empirical distribution 18723that is given by an observed sample. This is done by linear 18724interpolation of the empirical CDF. Although this 18725method is suggested in the books of Law and Kelton (2000) and 18726Bratly, Fox, and Schrage (1987) we do not recommend this method at 18727all since it has many theoretical drawbacks: 18728The variance of empirical distribution function does not 18729coincide with the variance of the given sample. Moreover, 18730when the sample increases the empirical density function 18731does not converge to the density of the underlying random 18732variate. Notice that the range of the generated point set is 18733always given by the range of the given sample. 18734 18735This method is provided in UNU.RAN for the sake of 18736completeness. We always recommend to use method EMPK 18737(@pxref{EMPK,,EMPirical distribution with Kernel smoothing}). 18738 18739If the data seem to be far away from having a bell shaped 18740histogram, then we think that naive resampling is still better 18741than linear interpolation. 18742 18743 18744@subsubheading How To Use 18745 18746 18747EMPL creates and samples from an empiral distribution by linear 18748interpolation of the empirical CDF. There are no parameters to 18749set. 18750 18751@noindent 18752@emph{Important}: We do not recommend to use this method! Use 18753method EMPK 18754(@pxref{EMPK,,EMPirical distribution with Kernel smoothing}) 18755instead. 18756 18757 18758 18759 18760@subheading Function reference 18761 18762@ifhtml 18763@itemize 18764@item @ref{funct:unur_empl_new,unur_empl_new} 18765@end itemize 18766@end ifhtml 18767 18768 18769@ifinfo 18770@anchor{funct:unur_empl_new} 18771@deftypefn Function {UNUR_PAR*} unur_empl_new (const @var{UNUR_DISTR* distribution}) 18772Get default parameters for generator. 18773@end deftypefn 18774@end ifinfo 18775@ifnotinfo 18776@anchor{funct:unur_empl_new} 18777@deftypefn {} {UNUR_PAR*} unur_empl_new (const @var{UNUR_DISTR* distribution}) 18778Get default parameters for generator. 18779@end deftypefn 18780@end ifnotinfo 18781 18782 18783 18784 18785@c 18786@c end of empl.h 18787@c ------------------------------------- 18788@c ------------------------------------- 18789@c hist.h 18790@c 18791 18792@page 18793@node HIST 18794@subsection HIST -- HISTogramm of empirical distribution 18795 18796@table @i 18797@item Required: 18798histogram 18799@item Speed: 18800Set-up: moderate, Sampling: fast 18801@item Reinit: 18802not implemented 18803@end table 18804@sp 1 18805 18806 18807Method HIST generates random variates from an empirical distribution 18808that is given as histogram. Sampling is done using the inversion 18809method. 18810 18811If observed (raw) data are provided we recommend method EMPK 18812(@pxref{EMPK,,EMPirical distribution with Kernel smoothing}) 18813instead of compting a histogram as this reduces information. 18814 18815 18816@subsubheading How To Use 18817 18818 18819Method HIST uses empirical distributions that are given as a 18820histgram. There are no optional parameters. 18821 18822 18823 18824 18825@subheading Function reference 18826 18827@ifhtml 18828@itemize 18829@item @ref{funct:unur_hist_new,unur_hist_new} 18830@end itemize 18831@end ifhtml 18832 18833 18834@ifinfo 18835@anchor{funct:unur_hist_new} 18836@deftypefn Function {UNUR_PAR*} unur_hist_new (const @var{UNUR_DISTR* distribution}) 18837Get default parameters for generator. 18838@end deftypefn 18839@end ifinfo 18840@ifnotinfo 18841@anchor{funct:unur_hist_new} 18842@deftypefn {} {UNUR_PAR*} unur_hist_new (const @var{UNUR_DISTR* distribution}) 18843Get default parameters for generator. 18844@end deftypefn 18845@end ifnotinfo 18846 18847 18848 18849 18850@c 18851@c end of hist.h 18852@c ------------------------------------- 18853@c ------------------------------------- 18854@c methods.dh 18855@c 18856 18857@page 18858@node Methods_for_CVEC 18859@section Methods for continuous multivariate distributions 18860 18861@menu 18862* MVSTD:: MultiVariate continuous STandarD distributions 18863* MVTDR:: Multi-Variate Transformed Density Rejection 18864* NORTA:: NORmal To Anything 18865* VNROU:: Multivariate Naive Ratio-Of-Uniforms method 18866@end menu 18867 18868 18869 18870@subheading Overview of methods 18871 18872@include methods_cvec.texi 18873 18874 18875 18876@c 18877@c end of methods.dh 18878@c ------------------------------------- 18879@c ------------------------------------- 18880@c mvstd.h 18881@c 18882 18883@page 18884@node MVSTD 18885@subsection MVSTD -- MultiVariate continuous STandarD distributions 18886 18887@table @i 18888@item Required: 18889standard distribution from UNU.RAN library (@pxref{Stddist,,Standard distributions}). 18890@item Speed: 18891depends on distribution and generator 18892@item Reinit: 18893supported 18894@end table 18895@sp 1 18896 18897 18898MVSTD is a wrapper for special generators for multivariate 18899continuous standard distributions. It only works for 18900distributions in the UNU.RAN library of standard distributions 18901(@pxref{Stddist,,Standard distributions}). 18902If a distribution object is provided that is build from scratch, 18903or if no special generator for the given standard distribution is 18904provided, the @code{NULL} pointer is returned. 18905 18906 18907@subsubheading How To Use 18908 18909 18910Create a distribution object for a standard distribution 18911from the UNU.RAN library (@pxref{Stddist,,Standard distributions}). 18912 18913Sampling from truncated distributions (which can be constructed by 18914changing the default domain of a distribution by means of 18915@ifhtml 18916@ref{funct:unur_distr_cvec_set_domain_rect,@command{unur_distr_cvec_set_domain_rect}} 18917@end ifhtml 18918@ifnothtml 18919@command{unur_distr_cvec_set_domain_rect} 18920@end ifnothtml 18921call) is not possible. 18922 18923It is possible to change the parameters and the domain of the chosen 18924distribution and run 18925@ifhtml 18926@ref{funct:unur_reinit,@command{unur_reinit}} 18927@end ifhtml 18928@ifnothtml 18929@command{unur_reinit} 18930@end ifnothtml 18931to reinitialize the generator object. 18932 18933 18934 18935 18936@subheading Function reference 18937 18938@ifhtml 18939@itemize 18940@item @ref{funct:unur_mvstd_new,unur_mvstd_new} 18941@end itemize 18942@end ifhtml 18943 18944 18945@ifinfo 18946@anchor{funct:unur_mvstd_new} 18947@deftypefn Function {UNUR_PAR*} unur_mvstd_new (const @var{UNUR_DISTR* distribution}) 18948Get default parameters for new generator. It requires a distribution object 18949for a multivariate continuous distribution from the 18950UNU.RAN library of standard distributions 18951(@pxref{Stddist,,Standard distributions}). 18952Using a truncated distribution is not possible. 18953@end deftypefn 18954@end ifinfo 18955@ifnotinfo 18956@anchor{funct:unur_mvstd_new} 18957@deftypefn {} {UNUR_PAR*} unur_mvstd_new (const @var{UNUR_DISTR* distribution}) 18958Get default parameters for new generator. It requires a distribution object 18959for a multivariate continuous distribution from the 18960UNU.RAN library of standard distributions 18961(@pxref{Stddist,,Standard distributions}). 18962Using a truncated distribution is not possible. 18963@end deftypefn 18964@end ifnotinfo 18965 18966 18967 18968 18969@c 18970@c end of mvstd.h 18971@c ------------------------------------- 18972@c ------------------------------------- 18973@c mvtdr.h 18974@c 18975 18976@page 18977@node MVTDR 18978@subsection MVTDR -- Multi-Variate Transformed Density Rejection 18979 18980@table @i 18981@item Required: 18982log-concave (log)PDF, gradient of (log)PDF 18983@item Optional: 18984mode 18985@item Speed: 18986Set-up: slow, Sampling: depends on dimension 18987@item Reinit: 18988not implemented 18989@item Reference: 18990@ifhtml 18991@ref{bib:HLD04,, [HLD04: Sect.11.3.4; Alg.11.15.]} 18992@end ifhtml 18993@ifnothtml 18994[HLD04: Sect.11.3.4; Alg.11.15.] 18995@end ifnothtml 18996@ifhtml 18997@ref{bib:LJa98,, [LJa98]} 18998@end ifhtml 18999@ifnothtml 19000[LJa98] 19001@end ifnothtml 19002 19003@end table 19004@sp 1 19005 19006 19007MVTDR a multivariate version of the Transformed Density Rection 19008(@pxref{TDR}) that works for log-concave densities. 19009For this method the domain of the distribution is partitioned 19010into cones with the mode (or the center) of the distribution as 19011their (common) vertex. The hat function is then constructed as 19012tangent planes of the transformed density in each of these 19013cones. The respective construction points lie on the central 19014lines in the cones through the vertex. The point is chosen such 19015that the hat is minimal among all such points (see the given 19016references for more details). 19017 19018The cones are created by starting with the orthants of the reals 19019space. These are then iteratively split when the volume below 19020the hat in such cones is too large. Thus an increasing number of 19021cones results in a better fitting hat function. 19022Notice however, that the required number of cones increases 19023exponentially with the number of dimension. 19024Moreover, due to the construction the rejection does not 19025converge to 1 and remains strictly larger than 1. 19026 19027For distributions with bounded domains the cones are cut to 19028pyramids that cover the domain. 19029 19030 19031@subsubheading How To Use 19032 19033 19034Create a multivariate generator object that contains the PDF and 19035its gradient. This object also should contain the mode of the 19036distribution (or a point nearby should be provided as center of 19037the distribution). 19038 19039The method has three parameter to adjust the method for the given 19040distribution: 19041 19042@table @code 19043@item stepsmin 19044Minimal number of iterations for splitting cones. 19045Notice that we start with 2^dim initial cones and that we arrive 19046at 2^(dim+stepsmin) cones after these splits. So this number 19047must be set with care. It can be set by a 19048@ifhtml 19049@ref{funct:unur_mvtdr_set_stepsmin,@command{unur_mvtdr_set_stepsmin}} 19050@end ifhtml 19051@ifnothtml 19052@command{unur_mvtdr_set_stepsmin} 19053@end ifnothtml 19054call. 19055 19056@item boundsplitting 19057Cones where the volume below the hat is relatively large 19058(i.e. larger than the average volume over all cones times 19059@code{boundsplitting} are further split. 19060This parameter can set via a 19061@ifhtml 19062@ref{funct:unur_mvtdr_set_boundsplitting,@command{unur_mvtdr_set_boundsplitting}} 19063@end ifhtml 19064@ifnothtml 19065@command{unur_mvtdr_set_boundsplitting} 19066@end ifnothtml 19067call. 19068 19069@item maxcones 19070The maximum number of generated cones. When this number is 19071reached, the initialization routine is stopped. Notice that the 19072rejection constant can be still prohibitive large. 19073This parameter can set via a 19074@ifhtml 19075@ref{funct:unur_mvtdr_set_maxcones,@command{unur_mvtdr_set_maxcones}} 19076@end ifhtml 19077@ifnothtml 19078@command{unur_mvtdr_set_maxcones} 19079@end ifnothtml 19080call. 19081 19082@end table 19083 19084Setting of these parameter can be quite tricky. The default 19085settings lead to hat functions where the volume below the hat is 19086similar in each cone. However, there might be some problems with 19087distributions with higher correlations, since then too few cones 19088are created. Then it might be necessary to increase the values 19089for @code{stepsmin} and @code{maxcones} and to set 19090@code{boundsplitting} to @code{0}. 19091 19092The number of cones and the total volume below the hat can be 19093controlled using the respective calls 19094@ifhtml 19095@ref{funct:unur_mvtdr_get_ncones,@command{unur_mvtdr_get_ncones}} 19096@end ifhtml 19097@ifnothtml 19098@command{unur_mvtdr_get_ncones} 19099@end ifnothtml 19100and 19101@ifhtml 19102@ref{funct:unur_mvtdr_get_hatvol,@command{unur_mvtdr_get_hatvol}.} 19103@end ifhtml 19104@ifnothtml 19105@command{unur_mvtdr_get_hatvol}. 19106@end ifnothtml 19107Notice, that the rejection constant is 19108bounded from below by some figure (larger than 1) that depends 19109on the dimension. 19110 19111Unfortunately, the algorithm cannot detect the quality of the 19112constructed hat. 19113 19114 19115 19116 19117@subheading Function reference 19118 19119@ifhtml 19120@itemize 19121@item @ref{funct:unur_mvtdr_new,unur_mvtdr_new} 19122@item @ref{funct:unur_mvtdr_set_stepsmin,unur_mvtdr_set_stepsmin} 19123@item @ref{funct:unur_mvtdr_set_boundsplitting,unur_mvtdr_set_boundsplitting} 19124@item @ref{funct:unur_mvtdr_set_maxcones,unur_mvtdr_set_maxcones} 19125@item @ref{funct:unur_mvtdr_get_ncones,unur_mvtdr_get_ncones} 19126@item @ref{funct:unur_mvtdr_get_hatvol,unur_mvtdr_get_hatvol} 19127@item @ref{funct:unur_mvtdr_set_verify,unur_mvtdr_set_verify} 19128@item @ref{funct:unur_mvtdr_chg_verify,unur_mvtdr_chg_verify} 19129@end itemize 19130@end ifhtml 19131 19132 19133@ifinfo 19134@anchor{funct:unur_mvtdr_new} 19135@deftypefn Function {UNUR_PAR*} unur_mvtdr_new (const @var{UNUR_DISTR* distribution}) 19136Get parameters for generator. 19137@end deftypefn 19138@end ifinfo 19139@ifnotinfo 19140@anchor{funct:unur_mvtdr_new} 19141@deftypefn {} {UNUR_PAR*} unur_mvtdr_new (const @var{UNUR_DISTR* distribution}) 19142Get parameters for generator. 19143@end deftypefn 19144@end ifnotinfo 19145 19146@ifinfo 19147@anchor{funct:unur_mvtdr_set_stepsmin} 19148@deftypefn Function {int} unur_mvtdr_set_stepsmin (UNUR_PAR* @var{parameters}, int @var{stepsmin}) 19149Set minimum number of triangulation step for each starting cone. 19150@var{stepsmin} must be nonnegative. 19151 19152Default: @code{5}. 19153@end deftypefn 19154@end ifinfo 19155@ifnotinfo 19156@anchor{funct:unur_mvtdr_set_stepsmin} 19157@deftypefn {} {int} unur_mvtdr_set_stepsmin (UNUR_PAR* @var{parameters}, int @var{stepsmin}) 19158Set minimum number of triangulation step for each starting cone. 19159@var{stepsmin} must be nonnegative. 19160 19161Default: @code{5}. 19162@end deftypefn 19163@end ifnotinfo 19164 19165@ifinfo 19166@anchor{funct:unur_mvtdr_set_boundsplitting} 19167@deftypefn Function {int} unur_mvtdr_set_boundsplitting (UNUR_PAR* @var{parameters}, double @var{boundsplitting}) 19168Set bound for splitting cones. All cones are split which have a 19169volume below the hat that is greater than @var{bound_splitting} times 19170the average over all volumes. However, the number given by the 19171@ifhtml 19172@ref{funct:unur_mvtdr_set_maxcones,@command{unur_mvtdr_set_maxcones}} 19173@end ifhtml 19174@ifnothtml 19175@command{unur_mvtdr_set_maxcones} 19176@end ifnothtml 19177is not exceeded. 19178Notice that the later number is always reached 19179if @var{bound_splitting} is less than 1. 19180 19181Default: @code{1.5} 19182@end deftypefn 19183@end ifinfo 19184@ifnotinfo 19185@anchor{funct:unur_mvtdr_set_boundsplitting} 19186@deftypefn {} {int} unur_mvtdr_set_boundsplitting (UNUR_PAR* @var{parameters}, double @var{boundsplitting}) 19187Set bound for splitting cones. All cones are split which have a 19188volume below the hat that is greater than @var{bound_splitting} times 19189the average over all volumes. However, the number given by the 19190@ifhtml 19191@ref{funct:unur_mvtdr_set_maxcones,@command{unur_mvtdr_set_maxcones}} 19192@end ifhtml 19193@ifnothtml 19194@command{unur_mvtdr_set_maxcones} 19195@end ifnothtml 19196is not exceeded. 19197Notice that the later number is always reached 19198if @var{bound_splitting} is less than 1. 19199 19200Default: @code{1.5} 19201@end deftypefn 19202@end ifnotinfo 19203 19204@ifinfo 19205@anchor{funct:unur_mvtdr_set_maxcones} 19206@deftypefn Function {int} unur_mvtdr_set_maxcones (UNUR_PAR* @var{parameters}, int @var{maxcones}) 19207Set maximum number of cones. 19208 19209Notice that this number is always increased to 19210@math{2^(dim+stepsmin)} 19211where @i{dim} is the dimension of the 19212distribution object and @i{stepsmin} the given mimimum number of 19213triangulation steps. 19214 19215Notice: For higher dimensions and/or higher correlations between the 19216coordinates of the random vector the required number of cones can 19217be very high. A too small maximum number of cones can lead to 19218a very high rejection constant. 19219 19220Default: @code{10000}. 19221@end deftypefn 19222@end ifinfo 19223@ifnotinfo 19224@anchor{funct:unur_mvtdr_set_maxcones} 19225@deftypefn {} {int} unur_mvtdr_set_maxcones (UNUR_PAR* @var{parameters}, int @var{maxcones}) 19226Set maximum number of cones. 19227 19228Notice that this number is always increased to 19229@iftex 19230@math{2^{dim+stepsmin}} 19231@end iftex 19232@ifhtml 19233@html 192342<SUP><I>dim</I>+<I>stepsmin</I></SUP> 19235@end html 19236@end ifhtml 19237where @i{dim} is the dimension of the 19238distribution object and @i{stepsmin} the given mimimum number of 19239triangulation steps. 19240 19241Notice: For higher dimensions and/or higher correlations between the 19242coordinates of the random vector the required number of cones can 19243be very high. A too small maximum number of cones can lead to 19244a very high rejection constant. 19245 19246Default: @code{10000}. 19247@end deftypefn 19248@end ifnotinfo 19249 19250@ifinfo 19251@anchor{funct:unur_mvtdr_get_ncones} 19252@deftypefn Function {int} unur_mvtdr_get_ncones (const @var{UNUR_GEN* generator}) 19253Get the number of cones used for the hat function of the 19254@var{generator}. 19255(In case of an error @code{0} is returned.) 19256@end deftypefn 19257@end ifinfo 19258@ifnotinfo 19259@anchor{funct:unur_mvtdr_get_ncones} 19260@deftypefn {} {int} unur_mvtdr_get_ncones (const @var{UNUR_GEN* generator}) 19261Get the number of cones used for the hat function of the 19262@var{generator}. 19263(In case of an error @code{0} is returned.) 19264@end deftypefn 19265@end ifnotinfo 19266 19267@ifinfo 19268@anchor{funct:unur_mvtdr_get_hatvol} 19269@deftypefn Function {double} unur_mvtdr_get_hatvol (const @var{UNUR_GEN* generator}) 19270Get the volume below the hat for the @var{generator}. 19271(In case of an error @code{UNUR_INFINITY} is returned.) 19272@end deftypefn 19273@end ifinfo 19274@ifnotinfo 19275@anchor{funct:unur_mvtdr_get_hatvol} 19276@deftypefn {} {double} unur_mvtdr_get_hatvol (const @var{UNUR_GEN* generator}) 19277Get the volume below the hat for the @var{generator}. 19278(In case of an error @code{UNUR_INFINITY} is returned.) 19279@end deftypefn 19280@end ifnotinfo 19281 19282@ifinfo 19283@anchor{funct:unur_mvtdr_set_verify} 19284@deftypefn Function {int} unur_mvtdr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 19285@anchor{funct:unur_mvtdr_chg_verify} 19286@deftypefnx Function {int} unur_mvtdr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 19287Turn verifying of algorithm while sampling on/off. 19288If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 19289violated for some @i{x} then @code{unur_errno} is set to 19290@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 19291happen due to round-off errors for a few values of 19292@i{x} (less than 1%). 19293 19294Default is @code{FALSE}. 19295@end deftypefn 19296@end ifinfo 19297@ifnotinfo 19298@anchor{funct:unur_mvtdr_set_verify} 19299@deftypefn {} {int} unur_mvtdr_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 19300@anchor{funct:unur_mvtdr_chg_verify} 19301@deftypefnx {} {int} unur_mvtdr_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 19302Turn verifying of algorithm while sampling on/off. 19303If the condition squeeze(@i{x}) <= PDF(@i{x}) <= hat(@i{x}) is 19304violated for some @i{x} then @code{unur_errno} is set to 19305@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 19306happen due to round-off errors for a few values of 19307@i{x} (less than 1%). 19308 19309Default is @code{FALSE}. 19310@end deftypefn 19311@end ifnotinfo 19312 19313 19314 19315 19316@c 19317@c end of mvtdr.h 19318@c ------------------------------------- 19319@c ------------------------------------- 19320@c norta.h 19321@c 19322 19323@page 19324@node NORTA 19325@subsection NORTA -- NORmal To Anything 19326 19327@table @i 19328@item Required: 19329rank correlation matrix, marginal distributions 19330@item Speed: 19331Set-up: slow, Sampling: depends on dimension 19332@item Reinit: 19333not implemented 19334@item Reference: 19335@ifhtml 19336@ref{bib:HLD04,, [HLD04: Sect.12.5.2; Alg.12.11.]} 19337@end ifhtml 19338@ifnothtml 19339[HLD04: Sect.12.5.2; Alg.12.11.] 19340@end ifnothtml 19341 19342@end table 19343@sp 1 19344 19345 19346NORTA (NORmal to anything) is a model to get random vectors with 19347given marginal distributions and rank correlation. 19348 19349@strong{Important:} Notice that marginal distribution and (rank) 19350correlation structure do not uniquely define a multivariate 19351distribution. Thus there are many other (more or less sensible) 19352models. 19353 19354In the NORTA model multinormal random variates with the given 19355(Spearman's) rank correlations are generated. 19356In a second step the (standard normal distributed) marginal variates 19357are transformed by means of the CDF of the normal distribution to get 19358uniform marginals. The resulting random vectors have uniform 19359marginals and the desired rank correlation between its components. 19360Such a random vector is called 'copula'. 19361 19362By means of the inverse CDF the uniform marginals are then 19363transformed into the target marginal distributions. This 19364transformation does not change the rank correlation. 19365 19366For the generation of the multinormal distribution the 19367(Spearman's) rank correlation matrix is transformed into the 19368corresponding (Pearson) correlation matrix. Samples from the 19369resulting multinormal distribution are generated by means of the 19370Cholesky decomposition of the covariance matrix. 19371 19372It can happen that the desired rank correlation matrix is not 19373feasible, i.e., it cannot occur as rank correlation matrix of a 19374multinormal distribution. The resulting "covariance" matrix is 19375not positive definite. In this case an eigenvector correction 19376method is used. Then all non-positive eigenvalues are set to a 19377small positive value and hence the rank correlation matrix of the 19378generated random vectors is "close" to the desired matrix. 19379 19380 19381@subsubheading How To Use 19382 19383 19384Create a multivariate generator object and set marginal 19385distributions using 19386@ifhtml 19387@ref{funct:unur_distr_cvec_set_marginals,@command{unur_distr_cvec_set_marginals},} 19388@end ifhtml 19389@ifnothtml 19390@command{unur_distr_cvec_set_marginals}, 19391@end ifnothtml 19392@ifhtml 19393@ref{funct:unur_distr_cvec_set_marginal_array,@command{unur_distr_cvec_set_marginal_array}} 19394@end ifhtml 19395@ifnothtml 19396@command{unur_distr_cvec_set_marginal_array} 19397@end ifnothtml 19398, or 19399@ifhtml 19400@ref{funct:unur_distr_cvec_set_marginal_list,@command{unur_distr_cvec_set_marginal_list}.} 19401@end ifhtml 19402@ifnothtml 19403@command{unur_distr_cvec_set_marginal_list}. 19404@end ifnothtml 19405(Do not use the corresponding calls for the standard 19406marginal distributions). 19407 19408When the domain of the multivariate distribution is set by of a 19409@ifhtml 19410@ref{funct:unur_distr_cvec_set_domain_rect,@command{unur_distr_cvec_set_domain_rect}} 19411@end ifhtml 19412@ifnothtml 19413@command{unur_distr_cvec_set_domain_rect} 19414@end ifnothtml 19415call then the domain of each 19416of the marginal distributions is truncated by the respective 19417coordinates of the given rectangle. 19418 19419If copulae are required (i.e. multivariate distributions with 19420uniform marginals) such a generator object can be created by 19421means of 19422@ifhtml 19423@ref{funct:unur_distr_copula,@command{unur_distr_copula}} 19424@end ifhtml 19425@ifnothtml 19426@command{unur_distr_copula} 19427@end ifnothtml 19428. 19429 19430There are no optional parameters for this method. 19431 19432 19433 19434@subheading Function reference 19435 19436@ifhtml 19437@itemize 19438@item @ref{funct:unur_norta_new,unur_norta_new} 19439@end itemize 19440@end ifhtml 19441 19442 19443@ifinfo 19444@anchor{funct:unur_norta_new} 19445@deftypefn Function {UNUR_PAR*} unur_norta_new (const @var{UNUR_DISTR* distribution}) 19446Get default parameters for generator. 19447@end deftypefn 19448@end ifinfo 19449@ifnotinfo 19450@anchor{funct:unur_norta_new} 19451@deftypefn {} {UNUR_PAR*} unur_norta_new (const @var{UNUR_DISTR* distribution}) 19452Get default parameters for generator. 19453@end deftypefn 19454@end ifnotinfo 19455 19456 19457 19458 19459@c 19460@c end of norta.h 19461@c ------------------------------------- 19462@c ------------------------------------- 19463@c vnrou.h 19464@c 19465 19466@page 19467@node VNROU 19468@subsection VNROU -- Multivariate Naive Ratio-Of-Uniforms method 19469 19470@table @i 19471@item Required: 19472PDF 19473@item Optional: 19474mode, center, bounding rectangle for acceptance region 19475@item Speed: 19476Set-up: fast or slow, Sampling: slow 19477@item Reinit: 19478supported 19479@item Reference: 19480@ifhtml 19481@ref{bib:WGS91,, [WGS91]} 19482@end ifhtml 19483@ifnothtml 19484[WGS91] 19485@end ifnothtml 19486 19487@end table 19488@sp 1 19489 19490 19491VNROU is an implementation of the multivariate 19492ratio-of-uniforms method which uses a (minimal) bounding 19493hyper-rectangle, see also @ref{Ratio-of-Uniforms}. It uses an 19494additional parameter @i{r} that can be used for adjusting the 19495algorithm to the given distribution to improve performance 19496and/or to make this method applicable. Larger values of 19497@i{r} increase the class of distributions for which the 19498method works at the expense of higher rejection 19499constants. Moreover, this implementation uses the center 19500@iftex 19501@math{\mu} 19502@end iftex 19503@ifhtml 19504@html 19505mu 19506@end html 19507@end ifhtml 19508@ifinfo 19509@math{mu} 19510@end ifinfo 19511of the distribution (which is set to the mode or 19512mean by default, see 19513@ifhtml 19514@ref{funct:unur_distr_cvec_get_center,@command{unur_distr_cvec_get_center}} 19515@end ifhtml 19516@ifnothtml 19517@command{unur_distr_cvec_get_center} 19518@end ifnothtml 19519for details of 19520its default values). 19521 19522The minimal bounding has then the coordinates 19523@iftex 19524 19525@quotation 19526@math{ v^+ = \sup\limits_{x} (f(x))^{1/r\,d+1}, \hfil\break u^-_i = \inf\limits_{x_i} (x_i-\mu_i) (f(x))^{r/r\,d+1}, \hfil\break u^+_i = \sup\limits_{x_i} (x_i-\mu_i) (f(x))^{r/r\,d+1}, } 19527@end quotation 19528 19529@end iftex 19530@ifhtml 19531@quotation 19532@html 19533<I>v</I><SUP>+</SUP> = sup_<I>x</I> (<I>f</I>(<I>x</I>))<SUP>1/<I>r</I> <I>d</I>+1</SUP>, @*<I>u</I><SUP>-</SUP>_<I>i</I> = inf_<I>x</I>_<I>i</I> (<I>x</I>_<I>i</I>- mu_<I>i</I>) (<I>f</I>(<I>x</I>))<SUP><I>r</I>/<I>r</I> <I>d</I>+1</SUP>, @*<I>u</I><SUP>+</SUP>_<I>i</I> = sup_<I>x</I>_<I>i</I> (<I>x</I>_<I>i</I>- mu_<I>i</I>) (<I>f</I>(<I>x</I>))<SUP><I>r</I>/<I>r</I> <I>d</I>+1</SUP>, 19534@end html 19535@end quotation 19536@end ifhtml 19537@ifinfo 19538@quotation 19539@math{v^+ = sup_(x) (f(x))^(1/r d+1), @*u^-_i = inf_(x_i) (x_i- mu_i) (f(x))^(r/r d+1), @*u^+_i = sup_(x_i) (x_i- mu_i) (f(x))^(r/r d+1),} 19540@end quotation 19541@end ifinfo 19542 19543@noindent 19544where 19545@iftex 19546@math{x_i} 19547@end iftex 19548@ifhtml 19549@html 19550<I>x</I>_<I>i</I> 19551@end html 19552@end ifhtml 19553@ifinfo 19554@math{x_i} 19555@end ifinfo 19556is the @i{i}-th coordinate of point @i{x}; 19557@iftex 19558@math{\mu_i} 19559@end iftex 19560@ifhtml 19561@html 19562mu_<I>i</I> 19563@end html 19564@end ifhtml 19565@ifinfo 19566@math{mu_i} 19567@end ifinfo 19568is the @i{i}-th coordinate of the center 19569@iftex 19570@math{\mu.} 19571@end iftex 19572@ifhtml 19573@html 19574mu. 19575@end html 19576@end ifhtml 19577@ifinfo 19578@math{mu.} 19579@end ifinfo 19580@iftex 19581@math{d} 19582@end iftex 19583@ifhtml 19584@html 19585<I>d</I> 19586@end html 19587@end ifhtml 19588@ifinfo 19589@math{d} 19590@end ifinfo 19591denotes the dimension of the distribution. 19592These bounds can either be given directly, or are computed 19593automatically by means of an numerical routine 19594by Hooke and Jeeves 19595@ifhtml 19596@ref{bib:HJa61,, [HJa61]} 19597@end ifhtml 19598@ifnothtml 19599[HJa61] 19600@end ifnothtml 19601called direct search 19602(see @file{src/utils/hooke.c} for further references and 19603details). Of course this algorithm can fail, especially when 19604this rectangle is not bounded. 19605 19606It is important to note that the algorithm works with 19607@iftex 19608@math{PDF(x-center)} 19609@end iftex 19610@ifhtml 19611@html 19612<I>PDF</I>(<I>x</I>-<I>center</I>) 19613@end html 19614@end ifhtml 19615@ifinfo 19616@math{PDF(x-center)} 19617@end ifinfo 19618instead of 19619@iftex 19620@math{PDF(x),} 19621@end iftex 19622@ifhtml 19623@html 19624<I>PDF</I>(<I>x</I>), 19625@end html 19626@end ifhtml 19627@ifinfo 19628@math{PDF(x),} 19629@end ifinfo 19630i.e. the bounding rectangle has to be 19631provided for 19632@iftex 19633@math{PDF(x-center).} 19634@end iftex 19635@ifhtml 19636@html 19637<I>PDF</I>(<I>x</I>-<I>center</I>). 19638@end html 19639@end ifhtml 19640@ifinfo 19641@math{PDF(x-center).} 19642@end ifinfo 19643This is important as otherwise the acceptance region can become 19644a very long and skinny ellipsoid along a diagonal of the (huge) 19645bounding rectangle. 19646 19647VNROU is based on the rejection method (@pxref{Rejection}), 19648and it is important to note that the acceptance probability 19649decreases exponentially with dimension. Thus even for moderately 19650many dimensions (e.g. 5) the number of repetitions to get one 19651random vector can be prohibitively large and the algorithm seems 19652to stay in an infinite loop. 19653 19654 19655@subsubheading How To Use 19656 19657 19658For using the VNROU method UNU.RAN needs the PDF of the 19659distribution. Additionally, the parameter @i{r} can be set via 19660a 19661@ifhtml 19662@ref{funct:unur_vnrou_set_r,@command{unur_vnrou_set_r}} 19663@end ifhtml 19664@ifnothtml 19665@command{unur_vnrou_set_r} 19666@end ifnothtml 19667call. Notice that the acceptance 19668probability decreases when @i{r} is increased. On the other 19669hand is is more unlikely that the bounding rectangle does not 19670exist if @i{r} is small. 19671 19672A bounding rectangle can be given by the 19673@ifhtml 19674@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 19675@end ifhtml 19676@ifnothtml 19677@command{unur_vnrou_set_u} 19678@end ifnothtml 19679and 19680@ifhtml 19681@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 19682@end ifhtml 19683@ifnothtml 19684@command{unur_vnrou_set_v} 19685@end ifnothtml 19686calls. 19687 19688@emph{Important:} The bounding rectangle has to be 19689provided for the function 19690@iftex 19691@math{PDF(x-center)!} 19692@end iftex 19693@ifhtml 19694@html 19695<I>PDF</I>(<I>x</I>-<I>center</I>)! 19696@end html 19697@end ifhtml 19698@ifinfo 19699@math{PDF(x-center)!} 19700@end ifinfo 19701Notice that @code{center} is the center of the given 19702distribution, see 19703@ifhtml 19704@ref{funct:unur_distr_cvec_set_center,@command{unur_distr_cvec_set_center}.} 19705@end ifhtml 19706@ifnothtml 19707@command{unur_distr_cvec_set_center}. 19708@end ifnothtml 19709If in doubt or if this value is not optimal, it can be changed 19710(overridden) by a 19711@ifhtml 19712@ref{funct:unur_distr_cvec_set_center,@command{unur_distr_cvec_set_center}} 19713@end ifhtml 19714@ifnothtml 19715@command{unur_distr_cvec_set_center} 19716@end ifnothtml 19717call. 19718 19719If the coordinates of the bounding rectangle are not provided by 19720the user then the minimal bounding rectangle is computed 19721automatically. 19722 19723By means of 19724@ifhtml 19725@ref{funct:unur_vnrou_set_verify,@command{unur_vnrou_set_verify}} 19726@end ifhtml 19727@ifnothtml 19728@command{unur_vnrou_set_verify} 19729@end ifnothtml 19730and 19731@ifhtml 19732@ref{funct:unur_vnrou_chg_verify,@command{unur_vnrou_chg_verify}} 19733@end ifhtml 19734@ifnothtml 19735@command{unur_vnrou_chg_verify} 19736@end ifnothtml 19737one can run the sampling algorithm in a checking mode, i.e., in 19738every cycle of the rejection loop it is checked whether the used 19739rectangle indeed enclosed the acceptance region of the 19740distribution. When in doubt (e.g., when it is not clear whether 19741the numerical routine has worked correctly) this can be used to 19742run a small Monte Carlo study. 19743 19744@strong{Important:} 19745The rejection constant (i.e. the expected number of iterations 19746for generationg one random vector) can be extremely high, in 19747particular when the dimension is 4 or higher. 19748Then the algorithm will perform almost infinite loops. 19749Thus it is recommended to read the volume below the hat function 19750by means of the 19751@ifhtml 19752@ref{funct:unur_vnrou_get_volumehat,@command{unur_vnrou_get_volumehat}} 19753@end ifhtml 19754@ifnothtml 19755@command{unur_vnrou_get_volumehat} 19756@end ifnothtml 19757call. The returned 19758number divided by the volume below the PDF (which is 1 in case 19759of a normalized PDF) gives the rejection constant. 19760 19761It is possible to change the parameters and the domain of the chosen 19762distribution and run 19763@ifhtml 19764@ref{funct:unur_reinit,@command{unur_reinit}} 19765@end ifhtml 19766@ifnothtml 19767@command{unur_reinit} 19768@end ifnothtml 19769to reinitialize the generator object. 19770Notice, that the coordinates of a bounding rectangle given by 19771@ifhtml 19772@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 19773@end ifhtml 19774@ifnothtml 19775@command{unur_vnrou_set_u} 19776@end ifnothtml 19777and 19778@ifhtml 19779@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 19780@end ifhtml 19781@ifnothtml 19782@command{unur_vnrou_set_v} 19783@end ifnothtml 19784calls are used also 19785when the generator is reused. These can be changed by means of 19786@ifhtml 19787@ref{funct:unur_vnrou_chg_u,@command{unur_vnrou_chg_u}} 19788@end ifhtml 19789@ifnothtml 19790@command{unur_vnrou_chg_u} 19791@end ifnothtml 19792and 19793@ifhtml 19794@ref{funct:unur_vnrou_chg_v,@command{unur_vnrou_chg_v}} 19795@end ifhtml 19796@ifnothtml 19797@command{unur_vnrou_chg_v} 19798@end ifnothtml 19799calls. 19800(If no such coordinates have been given, then they are computed 19801numerically during the reinitialization proceedure.) 19802 19803 19804 19805 19806@subheading Function reference 19807 19808@ifhtml 19809@itemize 19810@item @ref{funct:unur_vnrou_new,unur_vnrou_new} 19811@item @ref{funct:unur_vnrou_set_u,unur_vnrou_set_u} 19812@item @ref{funct:unur_vnrou_chg_u,unur_vnrou_chg_u} 19813@item @ref{funct:unur_vnrou_set_v,unur_vnrou_set_v} 19814@item @ref{funct:unur_vnrou_chg_v,unur_vnrou_chg_v} 19815@item @ref{funct:unur_vnrou_set_r,unur_vnrou_set_r} 19816@item @ref{funct:unur_vnrou_set_verify,unur_vnrou_set_verify} 19817@item @ref{funct:unur_vnrou_chg_verify,unur_vnrou_chg_verify} 19818@item @ref{funct:unur_vnrou_get_volumehat,unur_vnrou_get_volumehat} 19819@end itemize 19820@end ifhtml 19821 19822 19823@ifinfo 19824@anchor{funct:unur_vnrou_new} 19825@deftypefn Function {UNUR_PAR*} unur_vnrou_new (const @var{UNUR_DISTR* distribution}) 19826Get default parameters for generator. 19827@end deftypefn 19828@end ifinfo 19829@ifnotinfo 19830@anchor{funct:unur_vnrou_new} 19831@deftypefn {} {UNUR_PAR*} unur_vnrou_new (const @var{UNUR_DISTR* distribution}) 19832Get default parameters for generator. 19833@end deftypefn 19834@end ifnotinfo 19835 19836@ifinfo 19837@anchor{funct:unur_vnrou_set_u} 19838@deftypefn Function {int} unur_vnrou_set_u (UNUR_PAR* @var{parameters}, double* @var{umin}, double* @var{umax}) 19839Sets left and right boundaries of bounding hyper-rectangle. 19840If no values are given, the boundary of the minimal bounding 19841hyper-rectangle is computed numerically. 19842 19843@strong{Important}: The boundaries are those of the density shifted 19844by the center of the distribution, i.e., for the 19845function 19846@math{PDF(x-center)!} 19847 19848@emph{Notice}: Computing the minimal bounding rectangle may fail 19849under some circumstances. Moreover, for multimodal distributions 19850the bounds might be too small as only local extrema are computed. 19851Nevertheless, for log-concave distributions it should work. 19852 19853Default: not set (i.e. computed automatically) 19854@end deftypefn 19855@end ifinfo 19856@ifnotinfo 19857@anchor{funct:unur_vnrou_set_u} 19858@deftypefn {} {int} unur_vnrou_set_u (UNUR_PAR* @var{parameters}, double* @var{umin}, double* @var{umax}) 19859Sets left and right boundaries of bounding hyper-rectangle. 19860If no values are given, the boundary of the minimal bounding 19861hyper-rectangle is computed numerically. 19862 19863@strong{Important}: The boundaries are those of the density shifted 19864by the center of the distribution, i.e., for the 19865function 19866@iftex 19867@math{PDF(x-center)!} 19868@end iftex 19869@ifhtml 19870@html 19871<I>PDF</I>(<I>x</I>-<I>center</I>)! 19872@end html 19873@end ifhtml 19874 19875@emph{Notice}: Computing the minimal bounding rectangle may fail 19876under some circumstances. Moreover, for multimodal distributions 19877the bounds might be too small as only local extrema are computed. 19878Nevertheless, for log-concave distributions it should work. 19879 19880Default: not set (i.e. computed automatically) 19881@end deftypefn 19882@end ifnotinfo 19883 19884@ifinfo 19885@anchor{funct:unur_vnrou_chg_u} 19886@deftypefn Function {int} unur_vnrou_chg_u (UNUR_GEN* @var{generator}, double* @var{umin}, double* @var{umax}) 19887Change left and right boundaries of bounding hyper-rectangle. 19888@end deftypefn 19889@end ifinfo 19890@ifnotinfo 19891@anchor{funct:unur_vnrou_chg_u} 19892@deftypefn {} {int} unur_vnrou_chg_u (UNUR_GEN* @var{generator}, double* @var{umin}, double* @var{umax}) 19893Change left and right boundaries of bounding hyper-rectangle. 19894@end deftypefn 19895@end ifnotinfo 19896 19897@ifinfo 19898@anchor{funct:unur_vnrou_set_v} 19899@deftypefn Function {int} unur_vnrou_set_v (UNUR_PAR* @var{parameters}, double @var{vmax}) 19900Set upper boundary for bounding hyper-rectangle. 19901If no values are given, the density at the mode is evaluated. 19902If no mode is given for the distribution it is computed 19903numerically (and might fail). 19904 19905Default: not set (i.e. computed automatically) 19906@end deftypefn 19907@end ifinfo 19908@ifnotinfo 19909@anchor{funct:unur_vnrou_set_v} 19910@deftypefn {} {int} unur_vnrou_set_v (UNUR_PAR* @var{parameters}, double @var{vmax}) 19911Set upper boundary for bounding hyper-rectangle. 19912If no values are given, the density at the mode is evaluated. 19913If no mode is given for the distribution it is computed 19914numerically (and might fail). 19915 19916Default: not set (i.e. computed automatically) 19917@end deftypefn 19918@end ifnotinfo 19919 19920@ifinfo 19921@anchor{funct:unur_vnrou_chg_v} 19922@deftypefn Function {int} unur_vnrou_chg_v (UNUR_GEN* @var{generator}, double @var{vmax}) 19923Change upper boundary for bounding hyper-rectangle. 19924@end deftypefn 19925@end ifinfo 19926@ifnotinfo 19927@anchor{funct:unur_vnrou_chg_v} 19928@deftypefn {} {int} unur_vnrou_chg_v (UNUR_GEN* @var{generator}, double @var{vmax}) 19929Change upper boundary for bounding hyper-rectangle. 19930@end deftypefn 19931@end ifnotinfo 19932 19933@ifinfo 19934@anchor{funct:unur_vnrou_set_r} 19935@deftypefn Function {int} unur_vnrou_set_r (UNUR_PAR* @var{parameters}, double @var{r}) 19936Sets the parameter @var{r} of the generalized multivariate 19937ratio-of-uniforms method. 19938 19939@emph{Notice}: This parameter must satisfy @var{r}>0. 19940 19941Default: @code{1}. 19942@end deftypefn 19943@end ifinfo 19944@ifnotinfo 19945@anchor{funct:unur_vnrou_set_r} 19946@deftypefn {} {int} unur_vnrou_set_r (UNUR_PAR* @var{parameters}, double @var{r}) 19947Sets the parameter @var{r} of the generalized multivariate 19948ratio-of-uniforms method. 19949 19950@emph{Notice}: This parameter must satisfy @var{r}>0. 19951 19952Default: @code{1}. 19953@end deftypefn 19954@end ifnotinfo 19955 19956@ifinfo 19957@anchor{funct:unur_vnrou_set_verify} 19958@deftypefn Function {int} unur_vnrou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 19959Turn verifying of algorithm while sampling on/off. 19960 19961If the condition PDF(@i{x}) <= hat(@i{x}) is 19962violated for some @i{x} then @code{unur_errno} is set to 19963@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 19964happen due to round-off errors for a few values of 19965@i{x} (less than 1%). 19966 19967Default is @code{FALSE}. 19968@end deftypefn 19969@end ifinfo 19970@ifnotinfo 19971@anchor{funct:unur_vnrou_set_verify} 19972@deftypefn {} {int} unur_vnrou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 19973Turn verifying of algorithm while sampling on/off. 19974 19975If the condition PDF(@i{x}) <= hat(@i{x}) is 19976violated for some @i{x} then @code{unur_errno} is set to 19977@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 19978happen due to round-off errors for a few values of 19979@i{x} (less than 1%). 19980 19981Default is @code{FALSE}. 19982@end deftypefn 19983@end ifnotinfo 19984 19985@ifinfo 19986@anchor{funct:unur_vnrou_chg_verify} 19987@deftypefn Function {int} unur_vnrou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 19988Change the verifying of algorithm while sampling on/off. 19989@end deftypefn 19990@end ifinfo 19991@ifnotinfo 19992@anchor{funct:unur_vnrou_chg_verify} 19993@deftypefn {} {int} unur_vnrou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 19994Change the verifying of algorithm while sampling on/off. 19995@end deftypefn 19996@end ifnotinfo 19997 19998@ifinfo 19999@anchor{funct:unur_vnrou_get_volumehat} 20000@deftypefn Function {double} unur_vnrou_get_volumehat (const @var{UNUR_GEN* generator}) 20001Get the volume of below the hat. 20002For normalized densities, i.e. when the volume below PDF is 1, 20003this value equals the rejection constant for the vnrou method. 20004 20005In case of an error UNUR_INFINITY is returned. 20006@end deftypefn 20007@end ifinfo 20008@ifnotinfo 20009@anchor{funct:unur_vnrou_get_volumehat} 20010@deftypefn {} {double} unur_vnrou_get_volumehat (const @var{UNUR_GEN* generator}) 20011Get the volume of below the hat. 20012For normalized densities, i.e. when the volume below PDF is 1, 20013this value equals the rejection constant for the vnrou method. 20014 20015In case of an error UNUR_INFINITY is returned. 20016@end deftypefn 20017@end ifnotinfo 20018 20019 20020 20021 20022@c 20023@c end of vnrou.h 20024@c ------------------------------------- 20025@c ------------------------------------- 20026@c methods.dh 20027@c 20028 20029@page 20030@node MCMC_Methods_for_CVEC 20031@section Markov chain samplers for continuous multivariate distributions 20032 20033@menu 20034* GIBBS:: Markov Chain - GIBBS sampler 20035* HITRO:: Markov Chain - HIT-and-run sampler with Ratio-Of-uniforms 20036@end menu 20037 20038 20039 20040Markov chain samplers generate sequences of random vectors which have 20041the target distribution as stationary distribution. 20042There generated vectors are (more or less) correlated and it might take a long 20043time until the sequence has converged to the given target distribution. 20044 20045@strong{Beware: MCMC sampling can be dangerous!} 20046 20047@subheading Overview of methods 20048 20049@include methods_mcmc.texi 20050 20051 20052 20053@c 20054@c end of methods.dh 20055@c ------------------------------------- 20056@c ------------------------------------- 20057@c gibbs.h 20058@c 20059 20060@page 20061@node GIBBS 20062@subsection GIBBS -- Markov Chain - GIBBS sampler 20063 20064@table @i 20065@item Required: 20066T-concave logPDF, derivatives of logPDF 20067@item Speed: 20068Set-up: fast, Sampling: moderate 20069@item Reinit: 20070not implemented 20071@item Reference: 20072@ifhtml 20073@ref{bib:HLD04,, [HLD04: Sect.14.1.2]} 20074@end ifhtml 20075@ifnothtml 20076[HLD04: Sect.14.1.2] 20077@end ifnothtml 20078 20079@end table 20080@sp 1 20081 20082 20083Method GIBBS implements a Gibbs sampler for a multivariate 20084distribution with given joint density and its gradient. 20085When running such a Markov chain all coordinates are updated 20086cyclically using full conditional distributions. After each step 20087the state of the chain is returned (i.e., a random point is 20088returned whenever a single coordinate has been updated). 20089It is also possible to return only points after all coordinates 20090have been updated by "thinning" the chain. 20091Moreover, to reduce autocorrelation this thinning factor can be 20092any integer. Notice, however, that the sampling time for a chain 20093of given length is increased by the same factor, too. 20094 20095GIBBS also provides a variant of the Gibbs sampler where in 20096each step a point from the full conditional distribution along 20097some random direction is sampled. This direction is chosen 20098uniformly from the sphere in each step. 20099This method is also known as Hit-and-Run algorithm for 20100non-uniform distributions. 20101 20102Our experiences shows that the original Gibbs sampler with 20103sampling along coordinate axes is superior to random direction 20104sampling as long as the correlations between the components of 20105the random vector are not too high. 20106 20107For both variants transformed density rejection (see methods 20108@pxref{TDR} and @pxref{ARS}) is used to 20109sample from the full conditional distributions. In opposition to 20110the univariate case, it is important that the factor @code{c} is 20111as large as possible. I.e., for a log-concave density @code{c} 20112must be set to @code{0.}, since otherwise numerical underflow 20113might stop the algorithm. 20114 20115@emph{Important:} GIBBS does not generate independent random 20116points. The starting point of the Gibbs chain must be in a 20117"typical" region of the target distribution. If such a point is 20118not known or would be too expensive, then the first part of the 20119chain should be discarded (burn-in of the chain). 20120 20121 20122@subsubheading How To Use 20123 20124 20125For using the GIBBS method UNU.RAN needs the logarithm of the 20126PDF of the multivariate joint distribution and its gradient or 20127partial derivatives. 20128 20129It provides two variants: 20130@table @emph 20131@item coordinate direction sampling (Gibbs sampling) [default] 20132The coordinates are updated cyclically. 20133It requires the partial derivatives of the (logarithm of the) 20134PDF of the target distribution, 20135see 20136@ifhtml 20137@ref{funct:unur_distr_cvec_set_pdlogpdf,@command{unur_distr_cvec_set_pdlogpdf}.} 20138@end ifhtml 20139@ifnothtml 20140@command{unur_distr_cvec_set_pdlogpdf}. 20141@end ifnothtml 20142Otherwise, the gradient of the logPDF 20143(see 20144@ifhtml 20145@ref{funct:unur_distr_cvec_set_dlogpdf,@command{unur_distr_cvec_set_dlogpdf}} 20146@end ifhtml 20147@ifnothtml 20148@command{unur_distr_cvec_set_dlogpdf} 20149@end ifnothtml 20150) 20151is used, which is more expensive. 20152 20153This variant can be selected using 20154@ifhtml 20155@ref{funct:unur_gibbs_set_variant_coordinate,@command{unur_gibbs_set_variant_coordinate}.} 20156@end ifhtml 20157@ifnothtml 20158@command{unur_gibbs_set_variant_coordinate}. 20159@end ifnothtml 20160@item random direction sampling (nonuniform Hit-and-Run algorithm) 20161In each step is a direction is sampled uniformly from the sphere 20162and the next point in the chain is sampled from the full 20163conditional distribution along this direction. 20164 20165It requires the gradient of the logPDF and thus each step is 20166more expensive than each step for coordinate direction sampling. 20167 20168This variant can be selected using 20169@ifhtml 20170@ref{funct:unur_gibbs_set_variant_random_direction,@command{unur_gibbs_set_variant_random_direction}.} 20171@end ifhtml 20172@ifnothtml 20173@command{unur_gibbs_set_variant_random_direction}. 20174@end ifnothtml 20175@end table 20176 20177It is important that the @code{c} parameter for the TDR method 20178is as large as possible. For logconcave distribution it must be 20179set to @code{0}, since otherwise numerical underflow can cause 20180the algorithm to stop. 20181 20182The starting point of the Gibbs chain must be "typical" for the 20183target distribution. If such a point is not known or would be 20184too expensive, then the first part of the chain should be 20185discarded (burn-in of the chain). When using the 20186@ifhtml 20187@ref{funct:unur_gibbs_set_burnin,@command{unur_gibbs_set_burnin}} 20188@end ifhtml 20189@ifnothtml 20190@command{unur_gibbs_set_burnin} 20191@end ifnothtml 20192call this is done during the setup 20193of the Gibbs sampler object. 20194 20195In case of a fatal error in the generator for conditional 20196distributions the methods generates points that contain 20197UNUR_INFINITY. 20198 20199@strong{Warning:} The algorithm requires that all full 20200conditionals for the given distribution object are 20201@i{T}-concave. However, this property is not checked. 20202If this property is not satisfied, then generation from the 20203conditional distributions becomes (very) slow and might fail or 20204(even worse) produces random vectors from an incorrect 20205distribution. 20206When using 20207@ifhtml 20208@ref{funct:unur_gibbs_set_burnin,@command{unur_gibbs_set_burnin}} 20209@end ifhtml 20210@ifnothtml 20211@command{unur_gibbs_set_burnin} 20212@end ifnothtml 20213then the setup already 20214might fail. Thus when in doubt whether GIBBS can be used for 20215the targent distribution it is a good idea to use a burn-in for 20216checking. 20217 20218@emph{Remark:} It might happen (very rarely) that the chain 20219becomes stuck due to numerical errors. (This is in particular the 20220case when the given PDF does not fulfill the condition of this 20221method.) 20222When this happens during burn-in then the setup is aborted 20223(i.e. it fails). Otherwise the chain restarts again from its 20224starting point. 20225 20226@strong{Warning:} Be carefull with debugging flags. If it 20227contains flag @code{0x01000000u} it produces a lot of output for 20228each step in the algorithm. 20229(This flag is switched of in the default debugging flags). 20230 20231 20232 20233 20234@subheading Function reference 20235 20236@ifhtml 20237@itemize 20238@item @ref{funct:unur_gibbs_new,unur_gibbs_new} 20239@item @ref{funct:unur_gibbs_set_variant_coordinate,unur_gibbs_set_variant_coordinate} 20240@item @ref{funct:unur_gibbs_set_variant_random_direction,unur_gibbs_set_variant_random_direction} 20241@item @ref{funct:unur_gibbs_set_c,unur_gibbs_set_c} 20242@item @ref{funct:unur_gibbs_set_startingpoint,unur_gibbs_set_startingpoint} 20243@item @ref{funct:unur_gibbs_set_thinning,unur_gibbs_set_thinning} 20244@item @ref{funct:unur_gibbs_set_burnin,unur_gibbs_set_burnin} 20245@item @ref{funct:unur_gibbs_get_state,unur_gibbs_get_state} 20246@item @ref{funct:unur_gibbs_chg_state,unur_gibbs_chg_state} 20247@item @ref{funct:unur_gibbs_reset_state,unur_gibbs_reset_state} 20248@end itemize 20249@end ifhtml 20250 20251 20252@ifinfo 20253@anchor{funct:unur_gibbs_new} 20254@deftypefn Function {UNUR_PAR*} unur_gibbs_new (const @var{UNUR_DISTR* distribution}) 20255........................................................................... 20256@end deftypefn 20257@end ifinfo 20258@ifnotinfo 20259@anchor{funct:unur_gibbs_new} 20260@deftypefn {} {UNUR_PAR*} unur_gibbs_new (const @var{UNUR_DISTR* distribution}) 20261........................................................................... 20262@end deftypefn 20263@end ifnotinfo 20264 20265@ifinfo 20266@anchor{funct:unur_gibbs_set_variant_coordinate} 20267@deftypefn Function {int} unur_gibbs_set_variant_coordinate (UNUR_PAR* @var{parameters}) 20268Coordinate Direction Sampling: 20269Sampling along the coordinate directions (cyclic). 20270 20271This is the default. 20272@end deftypefn 20273@end ifinfo 20274@ifnotinfo 20275@anchor{funct:unur_gibbs_set_variant_coordinate} 20276@deftypefn {} {int} unur_gibbs_set_variant_coordinate (UNUR_PAR* @var{parameters}) 20277Coordinate Direction Sampling: 20278Sampling along the coordinate directions (cyclic). 20279 20280This is the default. 20281@end deftypefn 20282@end ifnotinfo 20283 20284@ifinfo 20285@anchor{funct:unur_gibbs_set_variant_random_direction} 20286@deftypefn Function {int} unur_gibbs_set_variant_random_direction (UNUR_PAR* @var{parameters}) 20287Random Direction Sampling: 20288Sampling along the random directions. 20289@end deftypefn 20290@end ifinfo 20291@ifnotinfo 20292@anchor{funct:unur_gibbs_set_variant_random_direction} 20293@deftypefn {} {int} unur_gibbs_set_variant_random_direction (UNUR_PAR* @var{parameters}) 20294Random Direction Sampling: 20295Sampling along the random directions. 20296@end deftypefn 20297@end ifnotinfo 20298 20299@ifinfo 20300@anchor{funct:unur_gibbs_set_c} 20301@deftypefn Function {int} unur_gibbs_set_c (UNUR_PAR* @var{parameters}, double @var{c}) 20302Set parameter @var{c} for transformation 20303@math{T} 20304of the 20305transformed density rejection method. 20306Currently only values between @code{0} and @code{-0.5} are 20307allowed. If @code{c} is between @code{0} and @code{-0.5} it is set 20308to @code{-0.5}. 20309 20310For @var{c} @code{=0} (for logconcave densities) method ARS 20311(@pxref{ARS}) is used which is very robust against badly 20312normalized PDFs. For other values method TDR (@pxref{TDR}) is used. 20313 20314The value for @var{c} should be as large as possible to avoid 20315fatal numerical underflows. Thus for log-concave distributions 20316@var{c} must be set to @code{0.} 20317 20318Default is @code{0}. 20319@end deftypefn 20320@end ifinfo 20321@ifnotinfo 20322@anchor{funct:unur_gibbs_set_c} 20323@deftypefn {} {int} unur_gibbs_set_c (UNUR_PAR* @var{parameters}, double @var{c}) 20324Set parameter @var{c} for transformation 20325@iftex 20326@math{T} 20327@end iftex 20328@ifhtml 20329@html 20330<I>T</I> 20331@end html 20332@end ifhtml 20333of the 20334transformed density rejection method. 20335Currently only values between @code{0} and @code{-0.5} are 20336allowed. If @code{c} is between @code{0} and @code{-0.5} it is set 20337to @code{-0.5}. 20338 20339For @var{c} @code{=0} (for logconcave densities) method ARS 20340(@pxref{ARS}) is used which is very robust against badly 20341normalized PDFs. For other values method TDR (@pxref{TDR}) is used. 20342 20343The value for @var{c} should be as large as possible to avoid 20344fatal numerical underflows. Thus for log-concave distributions 20345@var{c} must be set to @code{0.} 20346 20347Default is @code{0}. 20348@end deftypefn 20349@end ifnotinfo 20350 20351@ifinfo 20352@anchor{funct:unur_gibbs_set_startingpoint} 20353@deftypefn Function {int} unur_gibbs_set_startingpoint (UNUR_PAR* @var{parameters}, const @var{double* x0}) 20354Sets the starting point of the Gibbs sampler. @var{x0} must be 20355a "typical" point of the given distribution. 20356If such a "typical" point is not known and a starting point is 20357merely guessed, the first part of the Gibbs chain should be 20358discarded (@emph{burn-in}), e.g.\ by mean of the 20359@ifhtml 20360@ref{funct:unur_gibbs_set_burnin,@command{unur_gibbs_set_burnin}} 20361@end ifhtml 20362@ifnothtml 20363@command{unur_gibbs_set_burnin} 20364@end ifnothtml 20365call. 20366 20367Default is the result of 20368@ifhtml 20369@ref{funct:unur_distr_cvec_get_center,@command{unur_distr_cvec_get_center}} 20370@end ifhtml 20371@ifnothtml 20372@command{unur_distr_cvec_get_center} 20373@end ifnothtml 20374for the 20375given distribution object. 20376@end deftypefn 20377@end ifinfo 20378@ifnotinfo 20379@anchor{funct:unur_gibbs_set_startingpoint} 20380@deftypefn {} {int} unur_gibbs_set_startingpoint (UNUR_PAR* @var{parameters}, const @var{double* x0}) 20381Sets the starting point of the Gibbs sampler. @var{x0} must be 20382a "typical" point of the given distribution. 20383If such a "typical" point is not known and a starting point is 20384merely guessed, the first part of the Gibbs chain should be 20385discarded (@emph{burn-in}), e.g.\ by mean of the 20386@ifhtml 20387@ref{funct:unur_gibbs_set_burnin,@command{unur_gibbs_set_burnin}} 20388@end ifhtml 20389@ifnothtml 20390@command{unur_gibbs_set_burnin} 20391@end ifnothtml 20392call. 20393 20394Default is the result of 20395@ifhtml 20396@ref{funct:unur_distr_cvec_get_center,@command{unur_distr_cvec_get_center}} 20397@end ifhtml 20398@ifnothtml 20399@command{unur_distr_cvec_get_center} 20400@end ifnothtml 20401for the 20402given distribution object. 20403@end deftypefn 20404@end ifnotinfo 20405 20406@ifinfo 20407@anchor{funct:unur_gibbs_set_thinning} 20408@deftypefn Function {int} unur_gibbs_set_thinning (UNUR_PAR* @var{parameters}, int @var{thinning}) 20409Sets the @var{thinning} parameter. When @var{thinning} is set to 20410@i{k} then every @i{k}-th point from the iteration is returned by 20411the sampling algorithm. 20412 20413@emph{Notice}: This parameter must satisfy @var{thinning}>=1. 20414 20415Default: @code{1}. 20416@end deftypefn 20417@end ifinfo 20418@ifnotinfo 20419@anchor{funct:unur_gibbs_set_thinning} 20420@deftypefn {} {int} unur_gibbs_set_thinning (UNUR_PAR* @var{parameters}, int @var{thinning}) 20421Sets the @var{thinning} parameter. When @var{thinning} is set to 20422@i{k} then every @i{k}-th point from the iteration is returned by 20423the sampling algorithm. 20424 20425@emph{Notice}: This parameter must satisfy @var{thinning}>=1. 20426 20427Default: @code{1}. 20428@end deftypefn 20429@end ifnotinfo 20430 20431@ifinfo 20432@anchor{funct:unur_gibbs_set_burnin} 20433@deftypefn Function {int} unur_gibbs_set_burnin (UNUR_PAR* @var{parameters}, int @var{burnin}) 20434If a "typical" point for the target distribution is not known but 20435merely guessed, the first part of the Gibbs chain should be 20436discarded (@emph{burn-in}). This can be done during the 20437initialization of the generator object. 20438The length of the burn-in can is then @var{burnin}. 20439 20440When method GIBBS is not applicable for the target distribution 20441then the initialization already might fail during the burn-in. 20442Thus this reduces the risk of running a generator that returns 20443UNUR_INFINITY cased by some fatal error during sampling. 20444 20445The thinning factor set by a 20446@ifhtml 20447@ref{funct:unur_gibbs_set_thinning,@command{unur_gibbs_set_thinning}} 20448@end ifhtml 20449@ifnothtml 20450@command{unur_gibbs_set_thinning} 20451@end ifnothtml 20452call has 20453no effect on the length of the burn-in, i.e., for the burn-in 20454always a thinning factor @code{1} is used. 20455 20456@emph{Notice}: This parameter must satisfy @var{thinning}>=0. 20457 20458Default: @code{0}. 20459@end deftypefn 20460@end ifinfo 20461@ifnotinfo 20462@anchor{funct:unur_gibbs_set_burnin} 20463@deftypefn {} {int} unur_gibbs_set_burnin (UNUR_PAR* @var{parameters}, int @var{burnin}) 20464If a "typical" point for the target distribution is not known but 20465merely guessed, the first part of the Gibbs chain should be 20466discarded (@emph{burn-in}). This can be done during the 20467initialization of the generator object. 20468The length of the burn-in can is then @var{burnin}. 20469 20470When method GIBBS is not applicable for the target distribution 20471then the initialization already might fail during the burn-in. 20472Thus this reduces the risk of running a generator that returns 20473UNUR_INFINITY cased by some fatal error during sampling. 20474 20475The thinning factor set by a 20476@ifhtml 20477@ref{funct:unur_gibbs_set_thinning,@command{unur_gibbs_set_thinning}} 20478@end ifhtml 20479@ifnothtml 20480@command{unur_gibbs_set_thinning} 20481@end ifnothtml 20482call has 20483no effect on the length of the burn-in, i.e., for the burn-in 20484always a thinning factor @code{1} is used. 20485 20486@emph{Notice}: This parameter must satisfy @var{thinning}>=0. 20487 20488Default: @code{0}. 20489@end deftypefn 20490@end ifnotinfo 20491 20492@ifinfo 20493@anchor{funct:unur_gibbs_get_state} 20494@deftypefn Function {const double*} unur_gibbs_get_state (UNUR_GEN* @var{generator}) 20495@anchor{funct:unur_gibbs_chg_state} 20496@deftypefnx Function {int} unur_gibbs_chg_state (UNUR_GEN* @var{generator}, const @var{double* state}) 20497Get and change the current state of the Gibbs chain. 20498@end deftypefn 20499@end ifinfo 20500@ifnotinfo 20501@anchor{funct:unur_gibbs_get_state} 20502@deftypefn {} {const double*} unur_gibbs_get_state (UNUR_GEN* @var{generator}) 20503@anchor{funct:unur_gibbs_chg_state} 20504@deftypefnx {} {int} unur_gibbs_chg_state (UNUR_GEN* @var{generator}, const @var{double* state}) 20505Get and change the current state of the Gibbs chain. 20506@end deftypefn 20507@end ifnotinfo 20508 20509@ifinfo 20510@anchor{funct:unur_gibbs_reset_state} 20511@deftypefn Function {int} unur_gibbs_reset_state (UNUR_GEN* @var{generator}) 20512Reset state of chain to starting point. 20513 20514@emph{Notice:} Currently this function does not reset 20515the generators for conditional distributions. Thus it is not 20516possible to get the same Gibbs chain even when the underlying 20517uniform random number generator is reset. 20518@end deftypefn 20519@end ifinfo 20520@ifnotinfo 20521@anchor{funct:unur_gibbs_reset_state} 20522@deftypefn {} {int} unur_gibbs_reset_state (UNUR_GEN* @var{generator}) 20523Reset state of chain to starting point. 20524 20525@emph{Notice:} Currently this function does not reset 20526the generators for conditional distributions. Thus it is not 20527possible to get the same Gibbs chain even when the underlying 20528uniform random number generator is reset. 20529@end deftypefn 20530@end ifnotinfo 20531 20532 20533 20534 20535@c 20536@c end of gibbs.h 20537@c ------------------------------------- 20538@c ------------------------------------- 20539@c hitro.h 20540@c 20541 20542@page 20543@node HITRO 20544@subsection HITRO -- Markov Chain - HIT-and-run sampler with Ratio-Of-uniforms 20545 20546@table @i 20547@item Required: 20548PDF 20549@item Optional: 20550mode, center, bounding rectangle for acceptance region 20551@item Speed: 20552Set-up: fast, Sampling: fast 20553@item Reinit: 20554not implemented 20555@item Reference: 20556@ifhtml 20557@ref{bib:KLPa05,, [KLPa05]} 20558@end ifhtml 20559@ifnothtml 20560[KLPa05] 20561@end ifnothtml 20562 20563@end table 20564@sp 1 20565 20566 20567HITRO is an implementation of a hit-and-run sampler that runs on 20568the acceptance region of the multivariate ratio-of-uniforms 20569method, see @ref{Ratio-of-Uniforms}. 20570 20571The Ratio-of-Uniforms transforms the region below the density 20572into some region that we call "region of acceptance" in the 20573following. The minimal bounding hyperrectangle of this region 20574is given by 20575@iftex 20576 20577@quotation 20578@math{ v^+ = \sup\limits_{x} (f(x))^{1/r\,d+1}, \hfil\break u^-_i = \inf\limits_{x_i} (x_i-\mu_i) (f(x))^{r/r\,d+1}, \hfil\break u^+_i = \sup\limits_{x_i} (x_i-\mu_i) (f(x))^{r/r\,d+1}, } 20579@end quotation 20580 20581@end iftex 20582@ifhtml 20583@quotation 20584@html 20585<I>v</I><SUP>+</SUP> = sup_<I>x</I> (<I>f</I>(<I>x</I>))<SUP>1/<I>r</I> <I>d</I>+1</SUP>, @*<I>u</I><SUP>-</SUP>_<I>i</I> = inf_<I>x</I>_<I>i</I> (<I>x</I>_<I>i</I>- mu_<I>i</I>) (<I>f</I>(<I>x</I>))<SUP><I>r</I>/<I>r</I> <I>d</I>+1</SUP>, @*<I>u</I><SUP>+</SUP>_<I>i</I> = sup_<I>x</I>_<I>i</I> (<I>x</I>_<I>i</I>- mu_<I>i</I>) (<I>f</I>(<I>x</I>))<SUP><I>r</I>/<I>r</I> <I>d</I>+1</SUP>, 20586@end html 20587@end quotation 20588@end ifhtml 20589@ifinfo 20590@quotation 20591@math{v^+ = sup_(x) (f(x))^(1/r d+1), @*u^-_i = inf_(x_i) (x_i- mu_i) (f(x))^(r/r d+1), @*u^+_i = sup_(x_i) (x_i- mu_i) (f(x))^(r/r d+1),} 20592@end quotation 20593@end ifinfo 20594 20595@noindent 20596where @i{d} denotes the dimension of the distribution; 20597@iftex 20598@math{x_i} 20599@end iftex 20600@ifhtml 20601@html 20602<I>x</I>_<I>i</I> 20603@end html 20604@end ifhtml 20605@ifinfo 20606@math{x_i} 20607@end ifinfo 20608is the @i{i}-th coordinate of point @i{x}; 20609@iftex 20610@math{\mu_i} 20611@end iftex 20612@ifhtml 20613@html 20614mu_<I>i</I> 20615@end html 20616@end ifhtml 20617@ifinfo 20618@math{mu_i} 20619@end ifinfo 20620is the @i{i}-th coordinate of the center 20621@iftex 20622@math{\mu} 20623@end iftex 20624@ifhtml 20625@html 20626mu 20627@end html 20628@end ifhtml 20629@ifinfo 20630@math{mu} 20631@end ifinfo 20632of the distribution, i.e., a point in the 20633"main region" of the distribution. 20634Using the center is important, since otherwise the acceptance 20635region can become a very long and skinny ellipsoid along a 20636diagonal of the (huge) bounding rectangle. 20637 20638For each step of the Hit-and-Run algorithm we have to choose 20639some direction. This direction together with the current point 20640of the chain determines a straight line. Then a point is sampled 20641uniformly on intersection of this line and the region of 20642acceptance. This is done by rejection from a uniform distribution 20643on a line segment that covers it. 20644Depending of the chosen variant the endpoints of this covering 20645line are computed either by means of a (not necessary minimal) 20646bounding hyper-rectangle, or just the "covering plate" of the 20647bounding hyper-rectangle. 20648 20649The required bounds of the hyper-rectable can be given directly 20650by the user. Otherwise, these are computed automatically by 20651means of a numerical routine by Hooke and Jeeves 20652@ifhtml 20653@ref{bib:HJa61,, [HJa61]} 20654@end ifhtml 20655@ifnothtml 20656[HJa61] 20657@end ifnothtml 20658called direct search (see 20659@file{src/utils/hooke.c} for further references and details). 20660However, this expensive computation can be avoided by determine 20661these bounds "on the fly" by the following adaptive algorithm: 20662Start with some (small) hyper-rectangle and enlarge it whenever 20663the endpoints of the covering line segment are not contained in 20664the acceptance region of the Ratio-of-Unfiorms method. 20665This approach works reliable as long as the region of acceptance 20666is convex. 20667 20668The performance of the uniform sampling from the line segment is 20669much improved if the covering line is adjusted (shortened) 20670whenever a point is rejected (adaptive sampling). This technique 20671reduces the expected number of iterations enormously. 20672 20673Method HITRO requires that the region of acceptance of the 20674Ratio-of-Uniforms method is bounded. The shape of this region 20675can be controlled by a parameter @i{r}. Higher values of @i{r} 20676result in larger classes of distributions with bounded region 20677of acceptance. (A distribution that has such a bounded region for 20678some @i{r} also has a bounded region for every @i{r'} greater 20679than @i{r}.) On the other hand the acceptance probability 20680decreases with increasing @i{r}. Moreover, round-off errors are 20681more likely and (for large values of @i{r}) might result in a 20682chain with a stationary distribution different from the target 20683distribution. 20684 20685Method HITRO works optimal for distributions whose region of 20686acceptance is convex. This is in particular the case for all 20687log-concave distributions when we set @i{r} = @code{1}. 20688For bounded but non-convex regions of acceptance convergence is 20689yet not guarenteed by mathematical theory. 20690 20691 20692 20693@subsubheading How To Use 20694 20695 20696Method HITRO requires the PDF of the target distribution 20697(derivatives are not necessary). 20698 20699The acceptance region of the Ratio-of-Uniforms transformation 20700must be bounded. Its shape is controlled by parameter @i{r}. 20701By default this parameter is set to @code{1} as this guarentees 20702a convex region of acceptance when the PDF of the given 20703distribution is log-concave. It should only be set to a 20704different (higher!) value using 20705@ifhtml 20706@ref{funct:unur_vnrou_set_r,@command{unur_vnrou_set_r}} 20707@end ifhtml 20708@ifnothtml 20709@command{unur_vnrou_set_r} 20710@end ifnothtml 20711if otherwise 20712@iftex 20713@math{x_i\,(f(x))^{r/r\,d+1}} 20714@end iftex 20715@ifhtml 20716@html 20717<I>x</I>_<I>i</I> (<I>f</I>(<I>x</I>))<SUP><I>r</I>/<I>r</I> <I>d</I>+1</SUP> 20718@end html 20719@end ifhtml 20720@ifinfo 20721@math{x_i (f(x))^(r/r d+1)} 20722@end ifinfo 20723were not 20724bounded for each coordinate. 20725 20726There are two variants of the HITRO sampler: 20727@table @emph 20728@item coordinate direction sampling. [default] 20729The coordinates are updated cyclically. 20730This can be seen as a Gibbs sampler running on the acceptance 20731region of the Ratio-of-Uniforms method. 20732This variant can be selected using 20733@ifhtml 20734@ref{funct:unur_hitro_set_variant_coordinate,@command{unur_hitro_set_variant_coordinate}.} 20735@end ifhtml 20736@ifnothtml 20737@command{unur_hitro_set_variant_coordinate}. 20738@end ifnothtml 20739@item random direction sampling. 20740In each step is a direction is sampled uniformly from the 20741sphere. 20742 20743This variant can be selected using 20744@ifhtml 20745@ref{funct:unur_hitro_set_variant_random_direction,@command{unur_hitro_set_variant_random_direction}.} 20746@end ifhtml 20747@ifnothtml 20748@command{unur_hitro_set_variant_random_direction}. 20749@end ifnothtml 20750@end table 20751 20752Notice that each iteration of the coordinate direction sampler is 20753cheaper than an iteration of the random direction sampler. 20754 20755Sampling uniformly from the line segment can be adjusted in 20756several ways: 20757 20758@table @emph 20759@item Adaptive line sampling vs. simple rejection. 20760When adaptive line sampling is switched on, the covering line is 20761shortened whenever a point is rejected. However, when the region 20762of acceptance is not convex the line segment from which we have 20763to sample might not be connected. We found that the algorithm 20764still works but at the time being there is no formal proof that 20765the generated Markov chain has the required stationary 20766distribution. 20767 20768Adaptive line sampling can switch on/off by means of the 20769@ifhtml 20770@ref{funct:unur_hitro_set_use_adaptiveline,@command{unur_hitro_set_use_adaptiveline}} 20771@end ifhtml 20772@ifnothtml 20773@command{unur_hitro_set_use_adaptiveline} 20774@end ifnothtml 20775call. 20776 20777@item Bounding hyper-rectangle vs. "covering plate". 20778For computing the covering line we can use the bounding 20779hyper-rectangle or just its upper bound. 20780The latter saves computing time during the setup and 20781when computing the covering during at each iteration step 20782at the expense of a longer covering line. When adaptive line 20783sampling is used the total generation time for the entire chain 20784is shorter when only the "covering plate" is used. 20785 20786@emph{Notice:} When coordinate sampling is used the entire 20787bounding rectangle is used. 20788 20789Using the entire bounding hyper-rectangle can be switched on/off 20790by means of the 20791@ifhtml 20792@ref{funct:unur_hitro_set_use_boundingrectangle,@command{unur_hitro_set_use_boundingrectangle}} 20793@end ifhtml 20794@ifnothtml 20795@command{unur_hitro_set_use_boundingrectangle} 20796@end ifnothtml 20797call. 20798 20799@item Deterministic vs. adaptive bounding hyper-rectangle. 20800A bounding rectangle can be given by the 20801@ifhtml 20802@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 20803@end ifhtml 20804@ifnothtml 20805@command{unur_vnrou_set_u} 20806@end ifnothtml 20807and 20808@ifhtml 20809@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 20810@end ifhtml 20811@ifnothtml 20812@command{unur_vnrou_set_v} 20813@end ifnothtml 20814calls. 20815Otherwise, the minimal bounding rectangle is computed 20816automatically during the setup by means of a numerical 20817algorithm. However, this is (very) slow especially in higher 20818dimensions and it might happen that this algorithm (like 20819any other numerical algorithm) does not return a correct result. 20820 20821Alternatively the bounding rectangle can be computed 20822adaptively. In the latter case 20823@ifhtml 20824@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 20825@end ifhtml 20826@ifnothtml 20827@command{unur_vnrou_set_u} 20828@end ifnothtml 20829and 20830@ifhtml 20831@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 20832@end ifhtml 20833@ifnothtml 20834@command{unur_vnrou_set_v} 20835@end ifnothtml 20836can be used to provide a starting rectangle 20837which must be sufficiently small. 20838Then both endpoints of the covering line segment are always 20839check whether they are outside the acceptance region of the 20840Ratio-of-Uniforms method. If they are not, then the line segment 20841and the ("bounding") rectangle are enlarged using a factor that 20842can be given using the 20843@ifhtml 20844@ref{funct:unur_hitro_set_adaptive_multiplier,@command{unur_hitro_set_adaptive_multiplier}} 20845@end ifhtml 20846@ifnothtml 20847@command{unur_hitro_set_adaptive_multiplier} 20848@end ifnothtml 20849call. 20850 20851Notice, that running this method in the adaptive rectangle 20852mode requires that the region of acceptance is convex when random 20853directions are used, or the given PDF is unimodal when 20854coordinate direction sampling is used. 20855Moreover, it requires two additional calls to the PDF in each 20856iteration step of the chain. 20857 20858Using addaptive bounding rectangles can be switched on/off 20859by means of the 20860@ifhtml 20861@ref{funct:unur_hitro_set_use_adaptiverectangle,@command{unur_hitro_set_use_adaptiverectangle}} 20862@end ifhtml 20863@ifnothtml 20864@command{unur_hitro_set_use_adaptiverectangle} 20865@end ifnothtml 20866call. 20867 20868@end table 20869 20870The algorithm takes of a bounded rectangular domain given by a 20871@ifhtml 20872@ref{funct:unur_distr_cvec_set_domain_rect,@command{unur_distr_cvec_set_domain_rect}} 20873@end ifhtml 20874@ifnothtml 20875@command{unur_distr_cvec_set_domain_rect} 20876@end ifnothtml 20877call, i.e. the PDF is set to 20878zero for every @i{x} outside the given domain. 20879However, it is only the coordinate direction sampler where the 20880boundary values are directly used to get the endpoins of the 20881coverline line for the line sampling step. 20882 20883 20884@emph{Important:} The bounding rectangle has to be 20885provided for the function 20886@iftex 20887@math{PDF(x-center)!} 20888@end iftex 20889@ifhtml 20890@html 20891<I>PDF</I>(<I>x</I>-<I>center</I>)! 20892@end html 20893@end ifhtml 20894@ifinfo 20895@math{PDF(x-center)!} 20896@end ifinfo 20897Notice that @code{center} is the center of the given 20898distribution, see 20899@ifhtml 20900@ref{funct:unur_distr_cvec_set_center,@command{unur_distr_cvec_set_center}.} 20901@end ifhtml 20902@ifnothtml 20903@command{unur_distr_cvec_set_center}. 20904@end ifnothtml 20905If in doubt or if this value is not optimal, it can be changed 20906(overridden) by a 20907@ifhtml 20908@ref{funct:unur_distr_cvec_set_center,@command{unur_distr_cvec_set_center}} 20909@end ifhtml 20910@ifnothtml 20911@command{unur_distr_cvec_set_center} 20912@end ifnothtml 20913call. 20914 20915 20916 20917 20918@subheading Function reference 20919 20920@ifhtml 20921@itemize 20922@item @ref{funct:unur_hitro_new,unur_hitro_new} 20923@item @ref{funct:unur_hitro_set_variant_coordinate,unur_hitro_set_variant_coordinate} 20924@item @ref{funct:unur_hitro_set_variant_random_direction,unur_hitro_set_variant_random_direction} 20925@item @ref{funct:unur_hitro_set_use_adaptiveline,unur_hitro_set_use_adaptiveline} 20926@item @ref{funct:unur_hitro_set_use_boundingrectangle,unur_hitro_set_use_boundingrectangle} 20927@item @ref{funct:unur_hitro_set_use_adaptiverectangle,unur_hitro_set_use_adaptiverectangle} 20928@item @ref{funct:unur_hitro_set_r,unur_hitro_set_r} 20929@item @ref{funct:unur_hitro_set_v,unur_hitro_set_v} 20930@item @ref{funct:unur_hitro_set_u,unur_hitro_set_u} 20931@item @ref{funct:unur_hitro_set_adaptive_multiplier,unur_hitro_set_adaptive_multiplier} 20932@item @ref{funct:unur_hitro_set_startingpoint,unur_hitro_set_startingpoint} 20933@item @ref{funct:unur_hitro_set_thinning,unur_hitro_set_thinning} 20934@item @ref{funct:unur_hitro_set_burnin,unur_hitro_set_burnin} 20935@item @ref{funct:unur_hitro_get_state,unur_hitro_get_state} 20936@item @ref{funct:unur_hitro_chg_state,unur_hitro_chg_state} 20937@item @ref{funct:unur_hitro_reset_state,unur_hitro_reset_state} 20938@end itemize 20939@end ifhtml 20940 20941 20942@ifinfo 20943@anchor{funct:unur_hitro_new} 20944@deftypefn Function {UNUR_PAR*} unur_hitro_new (const @var{UNUR_DISTR* distribution}) 20945Get default parameters for generator. 20946@end deftypefn 20947@end ifinfo 20948@ifnotinfo 20949@anchor{funct:unur_hitro_new} 20950@deftypefn {} {UNUR_PAR*} unur_hitro_new (const @var{UNUR_DISTR* distribution}) 20951Get default parameters for generator. 20952@end deftypefn 20953@end ifnotinfo 20954 20955@ifinfo 20956@anchor{funct:unur_hitro_set_variant_coordinate} 20957@deftypefn Function {int} unur_hitro_set_variant_coordinate (UNUR_PAR* @var{parameters}) 20958Coordinate Direction Sampling: 20959Sampling along the coordinate directions (cyclic). 20960 20961@emph{Notice:} For this variant the entire bounding rectangle is 20962always used independent of the 20963@ifhtml 20964@ref{funct:unur_hitro_set_use_boundingrectangle,@command{unur_hitro_set_use_boundingrectangle}} 20965@end ifhtml 20966@ifnothtml 20967@command{unur_hitro_set_use_boundingrectangle} 20968@end ifnothtml 20969call. 20970 20971This is the default. 20972@end deftypefn 20973@end ifinfo 20974@ifnotinfo 20975@anchor{funct:unur_hitro_set_variant_coordinate} 20976@deftypefn {} {int} unur_hitro_set_variant_coordinate (UNUR_PAR* @var{parameters}) 20977Coordinate Direction Sampling: 20978Sampling along the coordinate directions (cyclic). 20979 20980@emph{Notice:} For this variant the entire bounding rectangle is 20981always used independent of the 20982@ifhtml 20983@ref{funct:unur_hitro_set_use_boundingrectangle,@command{unur_hitro_set_use_boundingrectangle}} 20984@end ifhtml 20985@ifnothtml 20986@command{unur_hitro_set_use_boundingrectangle} 20987@end ifnothtml 20988call. 20989 20990This is the default. 20991@end deftypefn 20992@end ifnotinfo 20993 20994@ifinfo 20995@anchor{funct:unur_hitro_set_variant_random_direction} 20996@deftypefn Function {int} unur_hitro_set_variant_random_direction (UNUR_PAR* @var{parameters}) 20997Random Direction Sampling: 20998Sampling along the random directions. 20999@end deftypefn 21000@end ifinfo 21001@ifnotinfo 21002@anchor{funct:unur_hitro_set_variant_random_direction} 21003@deftypefn {} {int} unur_hitro_set_variant_random_direction (UNUR_PAR* @var{parameters}) 21004Random Direction Sampling: 21005Sampling along the random directions. 21006@end deftypefn 21007@end ifnotinfo 21008 21009@ifinfo 21010@anchor{funct:unur_hitro_set_use_adaptiveline} 21011@deftypefn Function {int} unur_hitro_set_use_adaptiveline (UNUR_PAR* @var{parameters}, int @var{adaptive}) 21012When @var{adaptive} is set to @code{TRUE} adaptive line sampling is 21013applied, otherwise simple rejection is used. 21014 21015@emph{Notice:} When adaptive line sampling is switched off, 21016the entire bounding rectangle must be used since otherwise the 21017sampling time can be arbitrarily slow. 21018 21019@emph{Warning:} When adaptive line sampling is switched off, 21020sampling can be arbitrarily slow. In particular this happens 21021when random direction sampling is used for distributions with 21022rectangular domains. Then the algorithm can be trapped into 21023a vertex (or even edge). 21024 21025Default is @code{TRUE}. 21026@end deftypefn 21027@end ifinfo 21028@ifnotinfo 21029@anchor{funct:unur_hitro_set_use_adaptiveline} 21030@deftypefn {} {int} unur_hitro_set_use_adaptiveline (UNUR_PAR* @var{parameters}, int @var{adaptive}) 21031When @var{adaptive} is set to @code{TRUE} adaptive line sampling is 21032applied, otherwise simple rejection is used. 21033 21034@emph{Notice:} When adaptive line sampling is switched off, 21035the entire bounding rectangle must be used since otherwise the 21036sampling time can be arbitrarily slow. 21037 21038@emph{Warning:} When adaptive line sampling is switched off, 21039sampling can be arbitrarily slow. In particular this happens 21040when random direction sampling is used for distributions with 21041rectangular domains. Then the algorithm can be trapped into 21042a vertex (or even edge). 21043 21044Default is @code{TRUE}. 21045@end deftypefn 21046@end ifnotinfo 21047 21048@ifinfo 21049@anchor{funct:unur_hitro_set_use_boundingrectangle} 21050@deftypefn Function {int} unur_hitro_set_use_boundingrectangle (UNUR_PAR* @var{parameters}, int @var{rectangle}) 21051When @var{rectangle} is set to @code{TRUE} the entire bounding rectangle is used 21052for computing the covering line. Otherwise, only an upper bound for the 21053acceptance region is used. 21054 21055@emph{Notice:} When coordinate sampling is used the entire 21056bounding rectangle has is always used and this call has no effect. 21057 21058Default: @code{FALSE} for random direction samplig, @code{TRUE} for coordinate 21059direction sampling. 21060@end deftypefn 21061@end ifinfo 21062@ifnotinfo 21063@anchor{funct:unur_hitro_set_use_boundingrectangle} 21064@deftypefn {} {int} unur_hitro_set_use_boundingrectangle (UNUR_PAR* @var{parameters}, int @var{rectangle}) 21065When @var{rectangle} is set to @code{TRUE} the entire bounding rectangle is used 21066for computing the covering line. Otherwise, only an upper bound for the 21067acceptance region is used. 21068 21069@emph{Notice:} When coordinate sampling is used the entire 21070bounding rectangle has is always used and this call has no effect. 21071 21072Default: @code{FALSE} for random direction samplig, @code{TRUE} for coordinate 21073direction sampling. 21074@end deftypefn 21075@end ifnotinfo 21076 21077@ifinfo 21078@anchor{funct:unur_hitro_set_use_adaptiverectangle} 21079@deftypefn Function {int} unur_hitro_set_use_adaptiverectangle (UNUR_PAR* @var{parameters}, int @var{adaptive}) 21080When @var{adaptive} is set to @code{FALSE} the bounding rectangle is 21081determined during the setup. Either, it is computed automatically by 21082a (slow) numerical method, or it must be provided by 21083@ifhtml 21084@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 21085@end ifhtml 21086@ifnothtml 21087@command{unur_vnrou_set_u} 21088@end ifnothtml 21089and 21090@ifhtml 21091@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 21092@end ifhtml 21093@ifnothtml 21094@command{unur_vnrou_set_v} 21095@end ifnothtml 21096calls. 21097 21098If @var{adaptive} is set to @code{TRUE} the bounding rectangle is computed 21099adaptively. In this case the 21100@ifhtml 21101@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 21102@end ifhtml 21103@ifnothtml 21104@command{unur_vnrou_set_u} 21105@end ifnothtml 21106and 21107@ifhtml 21108@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 21109@end ifhtml 21110@ifnothtml 21111@command{unur_vnrou_set_v} 21112@end ifnothtml 21113calls can be used to provide a starting 21114rectangle. This should be sufficiently small. 21115If not given then we assume 21116@math{v_(max) = 1,} 21117@math{u_(min)=(-0.001,-0.001,...,-0.001),} 21118and 21119@math{u_(max)=(0.001,0.001,...,0.001).} 21120Adaptive enlargements of the bounding hyperrectangle can be 21121controlled set setting an enlargement factor given 21122by a 21123@ifhtml 21124@ref{funct:unur_hitro_set_adaptive_multiplier,@command{unur_hitro_set_adaptive_multiplier}} 21125@end ifhtml 21126@ifnothtml 21127@command{unur_hitro_set_adaptive_multiplier} 21128@end ifnothtml 21129call. 21130 21131Using adaptive computation of the bounding rectangle reduces the 21132setup time significantly (when it is not given by the user) at the 21133expense of two additional PDF evaluations during each iteration 21134step. 21135 21136@emph{Important:} Using adaptive bounding rectangles requires that 21137the region of acceptance is convex when random directions are used, 21138or a unimodal PDF when coordinate direction sampling is used. 21139 21140Default: @code{FALSE} for random direction samplig, @code{TRUE} for coordinate 21141direction sampling. 21142@end deftypefn 21143@end ifinfo 21144@ifnotinfo 21145@anchor{funct:unur_hitro_set_use_adaptiverectangle} 21146@deftypefn {} {int} unur_hitro_set_use_adaptiverectangle (UNUR_PAR* @var{parameters}, int @var{adaptive}) 21147When @var{adaptive} is set to @code{FALSE} the bounding rectangle is 21148determined during the setup. Either, it is computed automatically by 21149a (slow) numerical method, or it must be provided by 21150@ifhtml 21151@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 21152@end ifhtml 21153@ifnothtml 21154@command{unur_vnrou_set_u} 21155@end ifnothtml 21156and 21157@ifhtml 21158@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 21159@end ifhtml 21160@ifnothtml 21161@command{unur_vnrou_set_v} 21162@end ifnothtml 21163calls. 21164 21165If @var{adaptive} is set to @code{TRUE} the bounding rectangle is computed 21166adaptively. In this case the 21167@ifhtml 21168@ref{funct:unur_vnrou_set_u,@command{unur_vnrou_set_u}} 21169@end ifhtml 21170@ifnothtml 21171@command{unur_vnrou_set_u} 21172@end ifnothtml 21173and 21174@ifhtml 21175@ref{funct:unur_vnrou_set_v,@command{unur_vnrou_set_v}} 21176@end ifhtml 21177@ifnothtml 21178@command{unur_vnrou_set_v} 21179@end ifnothtml 21180calls can be used to provide a starting 21181rectangle. This should be sufficiently small. 21182If not given then we assume 21183@iftex 21184@math{v_{max} = 1,} 21185@end iftex 21186@ifhtml 21187@html 21188<I>v</I>_<I>max</I> = 1, 21189@end html 21190@end ifhtml 21191@iftex 21192@math{u_{min}=(-0.001,-0.001,\ldots,-0.001),} 21193@end iftex 21194@ifhtml 21195@html 21196<I>u</I>_<I>min</I>=(-0.001,-0.001,...,-0.001), 21197@end html 21198@end ifhtml 21199and 21200@iftex 21201@math{u_{max}=(0.001,0.001,\ldots,0.001).} 21202@end iftex 21203@ifhtml 21204@html 21205<I>u</I>_<I>max</I>=(0.001,0.001,...,0.001). 21206@end html 21207@end ifhtml 21208Adaptive enlargements of the bounding hyperrectangle can be 21209controlled set setting an enlargement factor given 21210by a 21211@ifhtml 21212@ref{funct:unur_hitro_set_adaptive_multiplier,@command{unur_hitro_set_adaptive_multiplier}} 21213@end ifhtml 21214@ifnothtml 21215@command{unur_hitro_set_adaptive_multiplier} 21216@end ifnothtml 21217call. 21218 21219Using adaptive computation of the bounding rectangle reduces the 21220setup time significantly (when it is not given by the user) at the 21221expense of two additional PDF evaluations during each iteration 21222step. 21223 21224@emph{Important:} Using adaptive bounding rectangles requires that 21225the region of acceptance is convex when random directions are used, 21226or a unimodal PDF when coordinate direction sampling is used. 21227 21228Default: @code{FALSE} for random direction samplig, @code{TRUE} for coordinate 21229direction sampling. 21230@end deftypefn 21231@end ifnotinfo 21232 21233@ifinfo 21234@anchor{funct:unur_hitro_set_r} 21235@deftypefn Function {int} unur_hitro_set_r (UNUR_PAR* @var{parameters}, double @var{r}) 21236Sets the parameter @var{r} of the generalized multivariate 21237ratio-of-uniforms method. 21238 21239@emph{Notice}: This parameter must satisfy @var{r}>0. 21240 21241Default: @code{1}. 21242@end deftypefn 21243@end ifinfo 21244@ifnotinfo 21245@anchor{funct:unur_hitro_set_r} 21246@deftypefn {} {int} unur_hitro_set_r (UNUR_PAR* @var{parameters}, double @var{r}) 21247Sets the parameter @var{r} of the generalized multivariate 21248ratio-of-uniforms method. 21249 21250@emph{Notice}: This parameter must satisfy @var{r}>0. 21251 21252Default: @code{1}. 21253@end deftypefn 21254@end ifnotinfo 21255 21256@ifinfo 21257@anchor{funct:unur_hitro_set_v} 21258@deftypefn Function {int} unur_hitro_set_v (UNUR_PAR* @var{parameters}, double @var{vmax}) 21259Set upper boundary for bounding hyper-rectangle. 21260If not set not set the mode of the distribution is used. 21261 21262If adaptive bounding rectangles the value is used for the 21263starting rectangle. If not given (and the mode of the distribution 21264is not known) then @var{vmax}=@code{1e-3} is used. 21265 21266If deterministic bounding rectangles these values are the given 21267values are used for the rectangle. If no value is given 21268(and the mode of the distribution is not known), the upper 21269bound of the minimal bounding hyper-rectangle is computed 21270numerically (slow). 21271 21272Default: not set. 21273@end deftypefn 21274@end ifinfo 21275@ifnotinfo 21276@anchor{funct:unur_hitro_set_v} 21277@deftypefn {} {int} unur_hitro_set_v (UNUR_PAR* @var{parameters}, double @var{vmax}) 21278Set upper boundary for bounding hyper-rectangle. 21279If not set not set the mode of the distribution is used. 21280 21281If adaptive bounding rectangles the value is used for the 21282starting rectangle. If not given (and the mode of the distribution 21283is not known) then @var{vmax}=@code{1e-3} is used. 21284 21285If deterministic bounding rectangles these values are the given 21286values are used for the rectangle. If no value is given 21287(and the mode of the distribution is not known), the upper 21288bound of the minimal bounding hyper-rectangle is computed 21289numerically (slow). 21290 21291Default: not set. 21292@end deftypefn 21293@end ifnotinfo 21294 21295@ifinfo 21296@anchor{funct:unur_hitro_set_u} 21297@deftypefn Function {int} unur_hitro_set_u (UNUR_PAR* @var{parameters}, const @var{double* umin}, const @var{double* umax}) 21298Sets left and right boundaries of bounding hyper-rectangle. 21299 21300If adaptive bounding rectangles these values are used for the 21301starting rectangle. If not given then 21302@var{umin}=@code{@{-b,-b,@dots{},-b@}} and 21303@var{umax}=@code{@{b,b,@dots{},b@}} with @code{b=1.e-3} is used. 21304 21305If deterministic bounding rectangles these values are the given 21306values are used for the rectangle. If no values are given, the 21307boundary of the minimal bounding hyper-rectangle is computed 21308numerically (slow). 21309 21310@strong{Important}: The boundaries are those of the density shifted 21311by the center of the distribution, i.e., for the 21312function 21313@math{PDF(x-center)!} 21314 21315@emph{Notice}: Computing the minimal bounding rectangle may fail 21316under some circumstances. Moreover, for multimodal distributions 21317the bounds might be too small as only local extrema are computed. 21318Nevertheless, for log-concave distributions it should work. 21319 21320Default: not set. 21321@end deftypefn 21322@end ifinfo 21323@ifnotinfo 21324@anchor{funct:unur_hitro_set_u} 21325@deftypefn {} {int} unur_hitro_set_u (UNUR_PAR* @var{parameters}, const @var{double* umin}, const @var{double* umax}) 21326Sets left and right boundaries of bounding hyper-rectangle. 21327 21328If adaptive bounding rectangles these values are used for the 21329starting rectangle. If not given then 21330@var{umin}=@code{@{-b,-b,@dots{},-b@}} and 21331@var{umax}=@code{@{b,b,@dots{},b@}} with @code{b=1.e-3} is used. 21332 21333If deterministic bounding rectangles these values are the given 21334values are used for the rectangle. If no values are given, the 21335boundary of the minimal bounding hyper-rectangle is computed 21336numerically (slow). 21337 21338@strong{Important}: The boundaries are those of the density shifted 21339by the center of the distribution, i.e., for the 21340function 21341@iftex 21342@math{PDF(x-center)!} 21343@end iftex 21344@ifhtml 21345@html 21346<I>PDF</I>(<I>x</I>-<I>center</I>)! 21347@end html 21348@end ifhtml 21349 21350@emph{Notice}: Computing the minimal bounding rectangle may fail 21351under some circumstances. Moreover, for multimodal distributions 21352the bounds might be too small as only local extrema are computed. 21353Nevertheless, for log-concave distributions it should work. 21354 21355Default: not set. 21356@end deftypefn 21357@end ifnotinfo 21358 21359@ifinfo 21360@anchor{funct:unur_hitro_set_adaptive_multiplier} 21361@deftypefn Function {int} unur_hitro_set_adaptive_multiplier (UNUR_PAR* @var{parameters}, double @var{factor}) 21362Adaptive enlargements of the bounding hyperrectangle can be 21363controlled set setting the enlargement @var{factor}. 21364This must be greater than 1. Values close to 1 result in small 21365adaptive steps and thus reduce the risk of too large bounding 21366rectangles. On the other hand many adaptive steps might be 21367necessary. 21368 21369@emph{Notice:} For practical reasons this call does not accept 21370values for @var{factor} less than @code{1.0001}. If this value is 21371UNUR_INFINITY this results in infinite loops. 21372 21373Default: @code{1.1} 21374@end deftypefn 21375@end ifinfo 21376@ifnotinfo 21377@anchor{funct:unur_hitro_set_adaptive_multiplier} 21378@deftypefn {} {int} unur_hitro_set_adaptive_multiplier (UNUR_PAR* @var{parameters}, double @var{factor}) 21379Adaptive enlargements of the bounding hyperrectangle can be 21380controlled set setting the enlargement @var{factor}. 21381This must be greater than 1. Values close to 1 result in small 21382adaptive steps and thus reduce the risk of too large bounding 21383rectangles. On the other hand many adaptive steps might be 21384necessary. 21385 21386@emph{Notice:} For practical reasons this call does not accept 21387values for @var{factor} less than @code{1.0001}. If this value is 21388UNUR_INFINITY this results in infinite loops. 21389 21390Default: @code{1.1} 21391@end deftypefn 21392@end ifnotinfo 21393 21394@ifinfo 21395@anchor{funct:unur_hitro_set_startingpoint} 21396@deftypefn Function {int} unur_hitro_set_startingpoint (UNUR_PAR* @var{parameters}, const @var{double* x0}) 21397Sets the starting point of the HITRO sampler in the original 21398scale. @var{x0} must be a "typical" point of the given distribution. 21399If such a "typical" point is not known and a starting point is 21400merely guessed, the first part of the HITRO chain should be 21401discarded (@emph{burn-in}), e.g.\ by mean of the 21402@ifhtml 21403@ref{funct:unur_hitro_set_burnin,@command{unur_hitro_set_burnin}} 21404@end ifhtml 21405@ifnothtml 21406@command{unur_hitro_set_burnin} 21407@end ifnothtml 21408call. 21409 21410@emph{Important:} The PDF of the distribution must not vanish at 21411the given point @var{x0}. 21412 21413Default is the result of 21414@ifhtml 21415@ref{funct:unur_distr_cvec_get_center,@command{unur_distr_cvec_get_center}} 21416@end ifhtml 21417@ifnothtml 21418@command{unur_distr_cvec_get_center} 21419@end ifnothtml 21420for the 21421given distribution object. 21422@end deftypefn 21423@end ifinfo 21424@ifnotinfo 21425@anchor{funct:unur_hitro_set_startingpoint} 21426@deftypefn {} {int} unur_hitro_set_startingpoint (UNUR_PAR* @var{parameters}, const @var{double* x0}) 21427Sets the starting point of the HITRO sampler in the original 21428scale. @var{x0} must be a "typical" point of the given distribution. 21429If such a "typical" point is not known and a starting point is 21430merely guessed, the first part of the HITRO chain should be 21431discarded (@emph{burn-in}), e.g.\ by mean of the 21432@ifhtml 21433@ref{funct:unur_hitro_set_burnin,@command{unur_hitro_set_burnin}} 21434@end ifhtml 21435@ifnothtml 21436@command{unur_hitro_set_burnin} 21437@end ifnothtml 21438call. 21439 21440@emph{Important:} The PDF of the distribution must not vanish at 21441the given point @var{x0}. 21442 21443Default is the result of 21444@ifhtml 21445@ref{funct:unur_distr_cvec_get_center,@command{unur_distr_cvec_get_center}} 21446@end ifhtml 21447@ifnothtml 21448@command{unur_distr_cvec_get_center} 21449@end ifnothtml 21450for the 21451given distribution object. 21452@end deftypefn 21453@end ifnotinfo 21454 21455@ifinfo 21456@anchor{funct:unur_hitro_set_thinning} 21457@deftypefn Function {int} unur_hitro_set_thinning (UNUR_PAR* @var{parameters}, int @var{thinning}) 21458Sets the @var{thinning} parameter. When @var{thinning} is set to 21459@i{k} then every @i{k}-th point from the iteration is returned by 21460the sampling algorithm. 21461If thinning has to be set such that each coordinate is updated 21462when using coordinate direction sampling, then @var{thinning} 21463should be @code{dim+1} (or any multiple of it) where 21464@code{dim} is the dimension of the distribution object. 21465 21466@emph{Notice}: This parameter must satisfy @var{thinning}>=1. 21467 21468Default: @code{1}. 21469@end deftypefn 21470@end ifinfo 21471@ifnotinfo 21472@anchor{funct:unur_hitro_set_thinning} 21473@deftypefn {} {int} unur_hitro_set_thinning (UNUR_PAR* @var{parameters}, int @var{thinning}) 21474Sets the @var{thinning} parameter. When @var{thinning} is set to 21475@i{k} then every @i{k}-th point from the iteration is returned by 21476the sampling algorithm. 21477If thinning has to be set such that each coordinate is updated 21478when using coordinate direction sampling, then @var{thinning} 21479should be @code{dim+1} (or any multiple of it) where 21480@code{dim} is the dimension of the distribution object. 21481 21482@emph{Notice}: This parameter must satisfy @var{thinning}>=1. 21483 21484Default: @code{1}. 21485@end deftypefn 21486@end ifnotinfo 21487 21488@ifinfo 21489@anchor{funct:unur_hitro_set_burnin} 21490@deftypefn Function {int} unur_hitro_set_burnin (UNUR_PAR* @var{parameters}, int @var{burnin}) 21491If a "typical" point for the target distribution is not known but 21492merely guessed, the first part of the HITRO chain should be 21493discarded (@emph{burn-in}). This can be done during the 21494initialization of the generator object. 21495The length of the burn-in can is then @var{burnin}. 21496 21497The thinning factor set by a 21498@ifhtml 21499@ref{funct:unur_hitro_set_thinning,@command{unur_hitro_set_thinning}} 21500@end ifhtml 21501@ifnothtml 21502@command{unur_hitro_set_thinning} 21503@end ifnothtml 21504call has 21505no effect on the length of the burn-in, i.e., for the burn-in 21506always a thinning factor @code{1} is used. 21507 21508@emph{Notice}: This parameter must satisfy @var{thinning}>=0. 21509 21510Default: @code{0}. 21511@end deftypefn 21512@end ifinfo 21513@ifnotinfo 21514@anchor{funct:unur_hitro_set_burnin} 21515@deftypefn {} {int} unur_hitro_set_burnin (UNUR_PAR* @var{parameters}, int @var{burnin}) 21516If a "typical" point for the target distribution is not known but 21517merely guessed, the first part of the HITRO chain should be 21518discarded (@emph{burn-in}). This can be done during the 21519initialization of the generator object. 21520The length of the burn-in can is then @var{burnin}. 21521 21522The thinning factor set by a 21523@ifhtml 21524@ref{funct:unur_hitro_set_thinning,@command{unur_hitro_set_thinning}} 21525@end ifhtml 21526@ifnothtml 21527@command{unur_hitro_set_thinning} 21528@end ifnothtml 21529call has 21530no effect on the length of the burn-in, i.e., for the burn-in 21531always a thinning factor @code{1} is used. 21532 21533@emph{Notice}: This parameter must satisfy @var{thinning}>=0. 21534 21535Default: @code{0}. 21536@end deftypefn 21537@end ifnotinfo 21538 21539@ifinfo 21540@anchor{funct:unur_hitro_get_state} 21541@deftypefn Function {const double*} unur_hitro_get_state (UNUR_GEN* @var{generator}) 21542@anchor{funct:unur_hitro_chg_state} 21543@deftypefnx Function {int} unur_hitro_chg_state (UNUR_GEN* @var{generator}, const @var{double* state}) 21544Get and change the current state of the HITRO chain. 21545 21546@emph{Notice:} The state variable contains the point in the 21547@code{dim+1} dimensional point in the (tansformed) region of 21548acceptance of the Ratio-of-Uniforms method. Its coordinate 21549are stored in the following order: 21550@code{state[] = @{v, u1, u2, @dots{}, udim@}}. 21551 21552If the state can only be changed if the given @var{state} is inside 21553this region. 21554@end deftypefn 21555@end ifinfo 21556@ifnotinfo 21557@anchor{funct:unur_hitro_get_state} 21558@deftypefn {} {const double*} unur_hitro_get_state (UNUR_GEN* @var{generator}) 21559@anchor{funct:unur_hitro_chg_state} 21560@deftypefnx {} {int} unur_hitro_chg_state (UNUR_GEN* @var{generator}, const @var{double* state}) 21561Get and change the current state of the HITRO chain. 21562 21563@emph{Notice:} The state variable contains the point in the 21564@code{dim+1} dimensional point in the (tansformed) region of 21565acceptance of the Ratio-of-Uniforms method. Its coordinate 21566are stored in the following order: 21567@code{state[] = @{v, u1, u2, @dots{}, udim@}}. 21568 21569If the state can only be changed if the given @var{state} is inside 21570this region. 21571@end deftypefn 21572@end ifnotinfo 21573 21574@ifinfo 21575@anchor{funct:unur_hitro_reset_state} 21576@deftypefn Function {int} unur_hitro_reset_state (UNUR_GEN* @var{generator}) 21577Reset state of chain to starting point. 21578 21579@emph{Notice:} Currently this function does not reset 21580the generators for conditional distributions. Thus it is not 21581possible to get the same HITRO chain even when the underlying 21582uniform random number generator is reset. 21583@end deftypefn 21584@end ifinfo 21585@ifnotinfo 21586@anchor{funct:unur_hitro_reset_state} 21587@deftypefn {} {int} unur_hitro_reset_state (UNUR_GEN* @var{generator}) 21588Reset state of chain to starting point. 21589 21590@emph{Notice:} Currently this function does not reset 21591the generators for conditional distributions. Thus it is not 21592possible to get the same HITRO chain even when the underlying 21593uniform random number generator is reset. 21594@end deftypefn 21595@end ifnotinfo 21596 21597 21598 21599 21600@c 21601@c end of hitro.h 21602@c ------------------------------------- 21603@c ------------------------------------- 21604@c methods.dh 21605@c 21606 21607@page 21608@node Methods_for_CVEMP 21609@section Methods for continuous empirical multivariate distributions 21610 21611@menu 21612* VEMPK:: (Vector) EMPirical distribution with Kernel smoothing 21613@end menu 21614 21615 21616 21617@subheading Overview of methods 21618 21619@include methods_cvemp.texi 21620 21621@subheading Example 21622 21623@smallexample 21624@include ref_example_vemp.texi 21625@end smallexample 21626 21627@subheading Example (String API) 21628 21629(not implemented) 21630 21631 21632 21633@c 21634@c end of methods.dh 21635@c ------------------------------------- 21636@c ------------------------------------- 21637@c vempk.h 21638@c 21639 21640@page 21641@node VEMPK 21642@subsection VEMPK -- (Vector) EMPirical distribution with Kernel smoothing 21643 21644@table @i 21645@item Required: 21646observed sample 21647@item Speed: 21648Set-up: slow, Sampling: slow (depends on dimension) 21649@item Reinit: 21650not implemented 21651@item Reference: 21652@ifhtml 21653@ref{bib:HLa00,, [HLa00]} 21654@end ifhtml 21655@ifnothtml 21656[HLa00] 21657@end ifnothtml 21658@ifhtml 21659@ref{bib:HLD04,, [HLD04: Sect.12.2.1]} 21660@end ifhtml 21661@ifnothtml 21662[HLD04: Sect.12.2.1] 21663@end ifnothtml 21664 21665@end table 21666@sp 1 21667 21668 21669VEMPK generates random variates from a multivariate empirical 21670distribution that is given by an observed sample. The idea is 21671that simply choosing a random point from the sample and to 21672return it with some added noise results in a method that has 21673very nice properties, as it can be seen as sampling from a 21674kernel density estimate. 21675Clearly we have to decide about the density of the noise (called kernel) 21676and about the covariance matrix of the noise. 21677The mathematical theory of kernel density estimation shows us that we 21678are comparatively free in choosing the kernel. 21679It also supplies us with a simple formula to compute the optimal 21680standarddeviation of the noise, called bandwidth (or window 21681width) of the kernel. 21682 21683Currently only a Gaussian kernel with the same covariance matrix 21684as the given sample is implemented. 21685However it is possible to choose between a variance corrected 21686version or those with optimal MISE. 21687Additionally a smoothing factor can be set to adjust the 21688estimated density to non-bell-shaped data densities. 21689 21690 21691@subsubheading How To Use 21692 21693 21694VEMPK uses empirical distributions. The main parameter would be 21695the choice if of kernel density. However, currently only 21696Gaussian kernels are supported. The parameters for the density 21697are computed by a simple but robust method. However, it is 21698possible to control its behavior by changing the smoothing 21699factor. 21700Additionally, variance correction can be swithed on (at the 21701price of suboptimal MISE). 21702 21703 21704 21705 21706@subheading Function reference 21707 21708@ifhtml 21709@itemize 21710@item @ref{funct:unur_vempk_new,unur_vempk_new} 21711@item @ref{funct:unur_vempk_set_smoothing,unur_vempk_set_smoothing} 21712@item @ref{funct:unur_vempk_chg_smoothing,unur_vempk_chg_smoothing} 21713@item @ref{funct:unur_vempk_set_varcor,unur_vempk_set_varcor} 21714@item @ref{funct:unur_vempk_chg_varcor,unur_vempk_chg_varcor} 21715@end itemize 21716@end ifhtml 21717 21718 21719@ifinfo 21720@anchor{funct:unur_vempk_new} 21721@deftypefn Function {UNUR_PAR*} unur_vempk_new (const @var{UNUR_DISTR* distribution}) 21722Get default parameters for generator. 21723@end deftypefn 21724@end ifinfo 21725@ifnotinfo 21726@anchor{funct:unur_vempk_new} 21727@deftypefn {} {UNUR_PAR*} unur_vempk_new (const @var{UNUR_DISTR* distribution}) 21728Get default parameters for generator. 21729@end deftypefn 21730@end ifnotinfo 21731 21732@ifinfo 21733@anchor{funct:unur_vempk_set_smoothing} 21734@deftypefn Function {int} unur_vempk_set_smoothing (UNUR_PAR* @var{parameters}, double @var{smoothing}) 21735@anchor{funct:unur_vempk_chg_smoothing} 21736@deftypefnx Function {int} unur_vempk_chg_smoothing (UNUR_GEN* @var{generator}, double @var{smoothing}) 21737Set and change the smoothing factor. 21738The smoothing factor controlles how ``smooth'' the resulting density 21739estimation will be. A smoothing factor equal to 0 results in naive 21740resampling. A very large smoothing factor (together with the 21741variance correction) results in a density which is approximately 21742equal to the kernel. 21743Default is 1 which results in a smoothing parameter minimising 21744the MISE (mean integrated squared error) if the data are not too 21745far away from normal. If a large smoothing factor is used, then 21746variance correction must be switched on. 21747 21748Default: @code{1} 21749@end deftypefn 21750@end ifinfo 21751@ifnotinfo 21752@anchor{funct:unur_vempk_set_smoothing} 21753@deftypefn {} {int} unur_vempk_set_smoothing (UNUR_PAR* @var{parameters}, double @var{smoothing}) 21754@anchor{funct:unur_vempk_chg_smoothing} 21755@deftypefnx {} {int} unur_vempk_chg_smoothing (UNUR_GEN* @var{generator}, double @var{smoothing}) 21756Set and change the smoothing factor. 21757The smoothing factor controlles how ``smooth'' the resulting density 21758estimation will be. A smoothing factor equal to 0 results in naive 21759resampling. A very large smoothing factor (together with the 21760variance correction) results in a density which is approximately 21761equal to the kernel. 21762Default is 1 which results in a smoothing parameter minimising 21763the MISE (mean integrated squared error) if the data are not too 21764far away from normal. If a large smoothing factor is used, then 21765variance correction must be switched on. 21766 21767Default: @code{1} 21768@end deftypefn 21769@end ifnotinfo 21770 21771@ifinfo 21772@anchor{funct:unur_vempk_set_varcor} 21773@deftypefn Function {int} unur_vempk_set_varcor (UNUR_PAR* @var{parameters}, int @var{varcor}) 21774@anchor{funct:unur_vempk_chg_varcor} 21775@deftypefnx Function {int} unur_vempk_chg_varcor (UNUR_GEN* @var{generator}, int @var{varcor}) 21776Switch variance correction in generator on/off. 21777If @var{varcor} is @code{TRUE} then the variance of the used 21778density estimation is the same as the sample variance. However this 21779increases the MISE of the estimation a little bit. 21780 21781Default is @code{FALSE}. 21782@end deftypefn 21783@end ifinfo 21784@ifnotinfo 21785@anchor{funct:unur_vempk_set_varcor} 21786@deftypefn {} {int} unur_vempk_set_varcor (UNUR_PAR* @var{parameters}, int @var{varcor}) 21787@anchor{funct:unur_vempk_chg_varcor} 21788@deftypefnx {} {int} unur_vempk_chg_varcor (UNUR_GEN* @var{generator}, int @var{varcor}) 21789Switch variance correction in generator on/off. 21790If @var{varcor} is @code{TRUE} then the variance of the used 21791density estimation is the same as the sample variance. However this 21792increases the MISE of the estimation a little bit. 21793 21794Default is @code{FALSE}. 21795@end deftypefn 21796@end ifnotinfo 21797 21798 21799 21800 21801@c 21802@c end of vempk.h 21803@c ------------------------------------- 21804@c ------------------------------------- 21805@c methods.dh 21806@c 21807 21808@page 21809@node Methods_for_DISCR 21810@section Methods for discrete univariate distributions 21811 21812@menu 21813* DARI:: Discrete Automatic Rejection Inversion 21814* DAU:: (Discrete) Alias-Urn method 21815* DEXT:: wrapper for Discrete EXTernal generators 21816* DGT:: (Discrete) Guide Table method (indexed search) 21817* DSROU:: Discrete Simple Ratio-Of-Uniforms method 21818* DSS:: (Discrete) Sequential Search method 21819* DSTD:: Discrete STandarD distributions 21820@end menu 21821 21822 21823 21824@subheading Overview of methods 21825 21826@include methods_discr.texi 21827 21828@subheading Example 21829 21830@smallexample 21831@include ref_example_discr.texi 21832@end smallexample 21833 21834@subheading Example (String API) 21835 21836@smallexample 21837@include ref_example_discr_str.texi 21838@end smallexample 21839 21840 21841 21842@c 21843@c end of methods.dh 21844@c ------------------------------------- 21845@c ------------------------------------- 21846@c dari.h 21847@c 21848 21849@page 21850@node DARI 21851@subsection DARI -- Discrete Automatic Rejection Inversion 21852 21853@table @i 21854@item Required: 21855T-concave PMF, mode, approximate area 21856@item Speed: 21857Set-up: moderate, Sampling: fast 21858@item Reinit: 21859supported 21860@item Reference: 21861@ifhtml 21862@ref{bib:HDa96,, [HDa96]} 21863@end ifhtml 21864@ifnothtml 21865[HDa96] 21866@end ifnothtml 21867@ifhtml 21868@ref{bib:HLD04,, [HLD04: Sect.10.2; Alg.10.4]} 21869@end ifhtml 21870@ifnothtml 21871[HLD04: Sect.10.2; Alg.10.4] 21872@end ifnothtml 21873 21874@end table 21875@sp 1 21876 21877 21878DARI is based on rejection inversion, which can be seen as an 21879adaptation of transformed density rejection to discrete 21880distributions. The used transformation is 21881@iftex 21882@math{-1/\sqrt{x}} 21883@end iftex 21884@ifhtml 21885@html 21886-1/sqrt(<I>x</I>) 21887@end html 21888@end ifhtml 21889@ifinfo 21890@math{-1/sqrt(x)} 21891@end ifinfo 21892. 21893 21894DARI uses three almost optimal points for constructing the 21895(continuous) hat. Rejection is then done in horizontal 21896direction. Rejection inversion uses only one uniform random 21897variate per trial. 21898 21899DARI has moderate set-up times (the PMF is evaluated nine 21900times), and good marginal speed, especially if an auxiliary 21901array is used to store values during generation. 21902 21903DARI works for all 21904@iftex 21905@math{T_{-1/2}} 21906@end iftex 21907@ifhtml 21908@html 21909<I>T</I>_-1/2 21910@end html 21911@end ifhtml 21912@ifinfo 21913@math{T_(-1/2)} 21914@end ifinfo 21915-concave distributions. It requires the PMF 21916and the location of the mode. Moreover the approximate sum over the PMF 21917is used. (If no sum is given for the distribution the algorithm 21918assumes that it is approximately 1.) 21919The rejection constant is bounded from above by 4 for all @i{T}-concave 21920distributions. 21921 21922 21923@subsubheading How To Use 21924 21925 21926DARI works for discrete distribution object with given PMF. 21927The sum over probabilities should be approximately 21928one. Otherwise it must be set by a 21929@ifhtml 21930@ref{funct:unur_distr_discr_set_pmfsum,@command{unur_distr_discr_set_pmfsum}} 21931@end ifhtml 21932@ifnothtml 21933@command{unur_distr_discr_set_pmfsum} 21934@end ifnothtml 21935call to its (approximate) value. 21936 21937The size of an auxiliary table can be set by 21938@ifhtml 21939@ref{funct:unur_dari_set_tablesize,@command{unur_dari_set_tablesize}.} 21940@end ifhtml 21941@ifnothtml 21942@command{unur_dari_set_tablesize}. 21943@end ifnothtml 21944The expected number of evaluations can be reduced by switching 21945the use of squeezes by means of 21946@ifhtml 21947@ref{funct:unur_dari_set_squeeze,@command{unur_dari_set_squeeze}.} 21948@end ifhtml 21949@ifnothtml 21950@command{unur_dari_set_squeeze}. 21951@end ifnothtml 21952It is possible to change the parameters and the domain of the chosen 21953distribution and run 21954@ifhtml 21955@ref{funct:unur_reinit,@command{unur_reinit}} 21956@end ifhtml 21957@ifnothtml 21958@command{unur_reinit} 21959@end ifnothtml 21960to reinitialize the generator object. 21961Notice, that derived parameters like the mode must also be (re-) set 21962if the parameters or the domain has be changed. 21963 21964There exists a test mode that verifies whether the conditions for 21965the method are satisfied or not. It can be switched on by calling 21966@ifhtml 21967@ref{funct:unur_dari_set_verify,@command{unur_dari_set_verify}} 21968@end ifhtml 21969@ifnothtml 21970@command{unur_dari_set_verify} 21971@end ifnothtml 21972and 21973@ifhtml 21974@ref{funct:unur_dari_chg_verify,@command{unur_dari_chg_verify},} 21975@end ifhtml 21976@ifnothtml 21977@command{unur_dari_chg_verify}, 21978@end ifnothtml 21979respectively. 21980Notice however that sampling is (much) slower then. 21981 21982 21983 21984 21985@subheading Function reference 21986 21987@ifhtml 21988@itemize 21989@item @ref{funct:unur_dari_new,unur_dari_new} 21990@item @ref{funct:unur_dari_set_squeeze,unur_dari_set_squeeze} 21991@item @ref{funct:unur_dari_set_tablesize,unur_dari_set_tablesize} 21992@item @ref{funct:unur_dari_set_cpfactor,unur_dari_set_cpfactor} 21993@item @ref{funct:unur_dari_set_verify,unur_dari_set_verify} 21994@item @ref{funct:unur_dari_chg_verify,unur_dari_chg_verify} 21995@end itemize 21996@end ifhtml 21997 21998 21999@ifinfo 22000@anchor{funct:unur_dari_new} 22001@deftypefn Function {UNUR_PAR*} unur_dari_new (const @var{UNUR_DISTR* distribution}) 22002Get default parameters for generator. 22003@end deftypefn 22004@end ifinfo 22005@ifnotinfo 22006@anchor{funct:unur_dari_new} 22007@deftypefn {} {UNUR_PAR*} unur_dari_new (const @var{UNUR_DISTR* distribution}) 22008Get default parameters for generator. 22009@end deftypefn 22010@end ifnotinfo 22011 22012@ifinfo 22013@anchor{funct:unur_dari_set_squeeze} 22014@deftypefn Function {int} unur_dari_set_squeeze (UNUR_PAR* @var{parameters}, int @var{squeeze}) 22015Turn utilization of the squeeze of the algorithm on/off. 22016This squeeze does not resamble the squeeze of the continuous TDR 22017method. It was especially designed for rejection inversion. 22018 22019The squeeze is not necessary if the size of the auxiliary table is 22020big enough (for the given distribution). 22021Using a squeeze is suggested to speed up the algorithm if the 22022domain of the distribution is very big or if only small samples are 22023produced. 22024 22025Default: no squeeze. 22026@end deftypefn 22027@end ifinfo 22028@ifnotinfo 22029@anchor{funct:unur_dari_set_squeeze} 22030@deftypefn {} {int} unur_dari_set_squeeze (UNUR_PAR* @var{parameters}, int @var{squeeze}) 22031Turn utilization of the squeeze of the algorithm on/off. 22032This squeeze does not resamble the squeeze of the continuous TDR 22033method. It was especially designed for rejection inversion. 22034 22035The squeeze is not necessary if the size of the auxiliary table is 22036big enough (for the given distribution). 22037Using a squeeze is suggested to speed up the algorithm if the 22038domain of the distribution is very big or if only small samples are 22039produced. 22040 22041Default: no squeeze. 22042@end deftypefn 22043@end ifnotinfo 22044 22045@ifinfo 22046@anchor{funct:unur_dari_set_tablesize} 22047@deftypefn Function {int} unur_dari_set_tablesize (UNUR_PAR* @var{parameters}, int @var{size}) 22048Set the size for the auxiliary table, that stores constants 22049computed during generation. 22050If @var{size} is set to @code{0} no table is used. 22051The speed-up can be impressive if the PMF is expensive to 22052evaluate and the ``main part of the distribution'' is concentrated 22053in an interval shorter than the size of the table. 22054 22055Default is @code{100}. 22056@end deftypefn 22057@end ifinfo 22058@ifnotinfo 22059@anchor{funct:unur_dari_set_tablesize} 22060@deftypefn {} {int} unur_dari_set_tablesize (UNUR_PAR* @var{parameters}, int @var{size}) 22061Set the size for the auxiliary table, that stores constants 22062computed during generation. 22063If @var{size} is set to @code{0} no table is used. 22064The speed-up can be impressive if the PMF is expensive to 22065evaluate and the ``main part of the distribution'' is concentrated 22066in an interval shorter than the size of the table. 22067 22068Default is @code{100}. 22069@end deftypefn 22070@end ifnotinfo 22071 22072@ifinfo 22073@anchor{funct:unur_dari_set_cpfactor} 22074@deftypefn Function {int} unur_dari_set_cpfactor (UNUR_PAR* @var{parameters}, double @var{cp_factor}) 22075Set factor for position of the left and right construction point, 22076resp. 22077The @var{cp_factor} is used to find almost optimal construction 22078points for the hat function. 22079The @var{cp_factor} must be positive and should not exceed 2. 22080There is no need to change this factor in almost all situations. 22081 22082Default is @code{0.664}. 22083@end deftypefn 22084@end ifinfo 22085@ifnotinfo 22086@anchor{funct:unur_dari_set_cpfactor} 22087@deftypefn {} {int} unur_dari_set_cpfactor (UNUR_PAR* @var{parameters}, double @var{cp_factor}) 22088Set factor for position of the left and right construction point, 22089resp. 22090The @var{cp_factor} is used to find almost optimal construction 22091points for the hat function. 22092The @var{cp_factor} must be positive and should not exceed 2. 22093There is no need to change this factor in almost all situations. 22094 22095Default is @code{0.664}. 22096@end deftypefn 22097@end ifnotinfo 22098 22099@ifinfo 22100@anchor{funct:unur_dari_set_verify} 22101@deftypefn Function {int} unur_dari_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 22102@anchor{funct:unur_dari_chg_verify} 22103@deftypefnx Function {int} unur_dari_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 22104Turn verifying of algorithm while sampling on/off. 22105If the condition is violated for some @i{x} then @code{unur_errno} 22106is set to @code{UNUR_ERR_GEN_CONDITION}. However notice that this 22107might happen due to round-off errors for a few values of 22108@i{x} (less than 1%). 22109 22110Default is @code{FALSE}. 22111@end deftypefn 22112@end ifinfo 22113@ifnotinfo 22114@anchor{funct:unur_dari_set_verify} 22115@deftypefn {} {int} unur_dari_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 22116@anchor{funct:unur_dari_chg_verify} 22117@deftypefnx {} {int} unur_dari_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 22118Turn verifying of algorithm while sampling on/off. 22119If the condition is violated for some @i{x} then @code{unur_errno} 22120is set to @code{UNUR_ERR_GEN_CONDITION}. However notice that this 22121might happen due to round-off errors for a few values of 22122@i{x} (less than 1%). 22123 22124Default is @code{FALSE}. 22125@end deftypefn 22126@end ifnotinfo 22127 22128 22129 22130 22131@c 22132@c end of dari.h 22133@c ------------------------------------- 22134@c ------------------------------------- 22135@c dau.h 22136@c 22137 22138@page 22139@node DAU 22140@subsection DAU -- (Discrete) Alias-Urn method 22141 22142@table @i 22143@item Required: 22144probability vector (PV) 22145@item Speed: 22146Set-up: slow (linear with the vector-length), Sampling: very fast 22147@item Reinit: 22148supported 22149@item Reference: 22150@ifhtml 22151@ref{bib:WAa77,, [WAa77]} 22152@end ifhtml 22153@ifnothtml 22154[WAa77] 22155@end ifnothtml 22156@ifhtml 22157@ref{bib:HLD04,, [HLD04: Sect.3.2]} 22158@end ifhtml 22159@ifnothtml 22160[HLD04: Sect.3.2] 22161@end ifnothtml 22162 22163@end table 22164@sp 1 22165 22166 22167DAU samples from distributions with arbitrary but finite 22168probability vectors (PV) of length @i{N}. 22169The algorithmus is based on an ingeneous method by A.J. Walker 22170and requires a table of size (at least) @i{N}. 22171It needs one random numbers and only one comparison for each 22172generated random variate. The setup time for constructing the 22173tables is @i{O(N)}. 22174 22175By default the probability vector is indexed starting at 22176@code{0}. However this can be changed in the distribution object by 22177a 22178@ifhtml 22179@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 22180@end ifhtml 22181@ifnothtml 22182@command{unur_distr_discr_set_domain} 22183@end ifnothtml 22184call. 22185 22186The method also works when no probability vector but a PMF is 22187given. However then additionally a bounded (not too large) domain 22188must be given or the sum over the PMF (see 22189@ifhtml 22190@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 22191@end ifhtml 22192@ifnothtml 22193@command{unur_distr_discr_make_pv} 22194@end ifnothtml 22195for details). 22196 22197 22198@subsubheading How To Use 22199 22200 22201Create an object for a discrete distribution either by setting a 22202probability vector or a PMF. The performance can be slightly 22203influenced by setting the size of the used table which can be 22204changed by 22205@ifhtml 22206@ref{funct:unur_dau_set_urnfactor,@command{unur_dau_set_urnfactor}.} 22207@end ifhtml 22208@ifnothtml 22209@command{unur_dau_set_urnfactor}. 22210@end ifnothtml 22211It is possible to change the parameters and the domain of the chosen 22212distribution and run 22213@ifhtml 22214@ref{funct:unur_reinit,@command{unur_reinit}} 22215@end ifhtml 22216@ifnothtml 22217@command{unur_reinit} 22218@end ifnothtml 22219to reinitialize the generator object. 22220 22221 22222 22223@subheading Function reference 22224 22225@ifhtml 22226@itemize 22227@item @ref{funct:unur_dau_new,unur_dau_new} 22228@item @ref{funct:unur_dau_set_urnfactor,unur_dau_set_urnfactor} 22229@end itemize 22230@end ifhtml 22231 22232 22233@ifinfo 22234@anchor{funct:unur_dau_new} 22235@deftypefn Function {UNUR_PAR*} unur_dau_new (const @var{UNUR_DISTR* distribution}) 22236Get default parameters for generator. 22237@end deftypefn 22238@end ifinfo 22239@ifnotinfo 22240@anchor{funct:unur_dau_new} 22241@deftypefn {} {UNUR_PAR*} unur_dau_new (const @var{UNUR_DISTR* distribution}) 22242Get default parameters for generator. 22243@end deftypefn 22244@end ifnotinfo 22245 22246@ifinfo 22247@anchor{funct:unur_dau_set_urnfactor} 22248@deftypefn Function {int} unur_dau_set_urnfactor (UNUR_PAR* @var{parameters}, double @var{factor}) 22249Set size of urn table relative to length of the probability 22250vector. It must not be less than 1. Larger tables result in 22251(slightly) faster generation times but require a more expensive 22252setup. However sizes larger than 2 are not recommended. 22253 22254Default is @code{1}. 22255@end deftypefn 22256@end ifinfo 22257@ifnotinfo 22258@anchor{funct:unur_dau_set_urnfactor} 22259@deftypefn {} {int} unur_dau_set_urnfactor (UNUR_PAR* @var{parameters}, double @var{factor}) 22260Set size of urn table relative to length of the probability 22261vector. It must not be less than 1. Larger tables result in 22262(slightly) faster generation times but require a more expensive 22263setup. However sizes larger than 2 are not recommended. 22264 22265Default is @code{1}. 22266@end deftypefn 22267@end ifnotinfo 22268 22269 22270 22271 22272@c 22273@c end of dau.h 22274@c ------------------------------------- 22275@c ------------------------------------- 22276@c dext.h 22277@c 22278 22279@page 22280@node DEXT 22281@subsection DEXT -- wrapper for Discrete EXTernal generators 22282 22283@table @i 22284@item Required: 22285routine for sampling discrete random variates 22286@item Speed: 22287depends on external generator 22288@item Reinit: 22289supported 22290@end table 22291@sp 1 22292 22293 22294Method DEXT is a wrapper for external generators for discrete 22295univariate distributions. It allows the usage of external 22296random variate generators within the UNU.RAN framework. 22297 22298 22299@subsubheading How To Use 22300 22301 22302The following steps are required to use some external generator 22303within the UNU.RAN framework (some of these are optional): 22304 22305@enumerate 22306@item 22307Make an empty generator object using a 22308@ifhtml 22309@ref{funct:unur_dext_new,@command{unur_dext_new}} 22310@end ifhtml 22311@ifnothtml 22312@command{unur_dext_new} 22313@end ifnothtml 22314call. 22315The argument @var{distribution} is optional and can be replaced 22316by @code{NULL}. However, it is required if you want to pass 22317parameters of the generated distribution to the external 22318generator or for running some validation tests provided by 22319UNU.RAN. 22320 22321@item 22322Create an initialization routine of type 22323@code{int (*init)(UNUR_GEN *gen)} and plug it into the generator 22324object using the 22325@ifhtml 22326@ref{funct:unur_dext_set_init,@command{unur_dext_set_init}} 22327@end ifhtml 22328@ifnothtml 22329@command{unur_dext_set_init} 22330@end ifnothtml 22331call. Notice that the 22332@var{init} routine must return @code{UNUR_SUCCESS} when it has 22333been executed successfully and @code{UNUR_FAILURE} otherwise. 22334It is possible to get the size of and the pointer to the array 22335of parameters of the underlying distribution object by the 22336respective calls 22337@ifhtml 22338@ref{funct:unur_dext_get_ndistrparams,@command{unur_dext_get_ndistrparams}} 22339@end ifhtml 22340@ifnothtml 22341@command{unur_dext_get_ndistrparams} 22342@end ifnothtml 22343and 22344@ifhtml 22345@ref{funct:unur_dext_get_distrparams,@command{unur_dext_get_distrparams}.} 22346@end ifhtml 22347@ifnothtml 22348@command{unur_dext_get_distrparams}. 22349@end ifnothtml 22350Parameters for the external generator that are computed in the 22351@var{init} routine can be stored in a single array or structure 22352which is available by the 22353@ifhtml 22354@ref{funct:unur_dext_get_params,@command{unur_dext_get_params}} 22355@end ifhtml 22356@ifnothtml 22357@command{unur_dext_get_params} 22358@end ifnothtml 22359call. 22360 22361Using an @var{init} routine is optional and can be omitted. 22362 22363@item 22364Create a sampling routine of type 22365@code{int (*sample)(UNUR_GEN *gen)} and plug it into the 22366generator object using the 22367@ifhtml 22368@ref{funct:unur_dext_set_sample,@command{unur_dext_set_sample}} 22369@end ifhtml 22370@ifnothtml 22371@command{unur_dext_set_sample} 22372@end ifnothtml 22373call. 22374 22375Uniform random numbers are provided by the 22376@ifhtml 22377@ref{funct:unur_sample_urng,@command{unur_sample_urng}} 22378@end ifhtml 22379@ifnothtml 22380@command{unur_sample_urng} 22381@end ifnothtml 22382call. Do not use your own implementation of a uniform random 22383number generator directly. If you want to use your own random 22384number generator we recommend to use the UNU.RAN interface (see 22385@pxref{URNG,,Using uniform random number generators}). 22386 22387The array or structure that contains parameters for the external 22388generator that are computed in the @var{init} routine are 22389available using the 22390@ifhtml 22391@ref{funct:unur_dext_get_params,@command{unur_dext_get_params}} 22392@end ifhtml 22393@ifnothtml 22394@command{unur_dext_get_params} 22395@end ifnothtml 22396call. 22397 22398Using a @var{sample} routine is of course obligatory. 22399@end enumerate 22400 22401It is possible to change the parameters and the domain of the 22402chosen distribution and run 22403@ifhtml 22404@ref{funct:unur_reinit,@command{unur_reinit}} 22405@end ifhtml 22406@ifnothtml 22407@command{unur_reinit} 22408@end ifnothtml 22409to reinitialize the 22410generator object. The @var{init} routine is then called again. 22411 22412Here is a short example that demonstrates the application of 22413this method by means of the geometric distribution: 22414 22415@smallexample 22416@include ref_example_dext.texi 22417@end smallexample 22418 22419 22420 22421 22422@subheading Function reference 22423 22424@ifhtml 22425@itemize 22426@item @ref{funct:unur_dext_new,unur_dext_new} 22427@item @ref{funct:unur_dext_set_init,unur_dext_set_init} 22428@item @ref{funct:unur_dext_set_sample,unur_dext_set_sample} 22429@item @ref{funct:unur_dext_get_params,unur_dext_get_params} 22430@item @ref{funct:unur_dext_get_distrparams,unur_dext_get_distrparams} 22431@item @ref{funct:unur_dext_get_ndistrparams,unur_dext_get_ndistrparams} 22432@end itemize 22433@end ifhtml 22434 22435 22436@ifinfo 22437@anchor{funct:unur_dext_new} 22438@deftypefn Function {UNUR_PAR*} unur_dext_new (const @var{UNUR_DISTR* distribution}) 22439Get default parameters for new generator. 22440@end deftypefn 22441@end ifinfo 22442@ifnotinfo 22443@anchor{funct:unur_dext_new} 22444@deftypefn {} {UNUR_PAR*} unur_dext_new (const @var{UNUR_DISTR* distribution}) 22445Get default parameters for new generator. 22446@end deftypefn 22447@end ifnotinfo 22448 22449@ifinfo 22450@anchor{funct:unur_dext_set_init} 22451@deftypefn Function {int} unur_dext_set_init (UNUR_PAR* @var{parameters}, int (* @var{init})(UNUR_GEN* gen )) 22452Set initialization routine for external generator. Inside the 22453 22454@emph{Important:} The routine @var{init} must return 22455@code{UNUR_SUCCESS} when the generator was initialized successfully 22456and @code{UNUR_FAILURE} otherwise. 22457 22458Parameters that are computed in the @var{init} routine can be 22459stored in an array or structure that is avaiable by means of the 22460@ifhtml 22461@ref{funct:unur_dext_get_params,@command{unur_dext_get_params}} 22462@end ifhtml 22463@ifnothtml 22464@command{unur_dext_get_params} 22465@end ifnothtml 22466call. Parameters of the underlying 22467distribution object can be obtained by the 22468@ifhtml 22469@ref{funct:unur_dext_get_distrparams,@command{unur_dext_get_distrparams}} 22470@end ifhtml 22471@ifnothtml 22472@command{unur_dext_get_distrparams} 22473@end ifnothtml 22474call. 22475@end deftypefn 22476@end ifinfo 22477@ifnotinfo 22478@anchor{funct:unur_dext_set_init} 22479@deftypefn {} {int} unur_dext_set_init (UNUR_PAR* @var{parameters}, int (* @var{init})(UNUR_GEN* gen )) 22480Set initialization routine for external generator. Inside the 22481 22482@emph{Important:} The routine @var{init} must return 22483@code{UNUR_SUCCESS} when the generator was initialized successfully 22484and @code{UNUR_FAILURE} otherwise. 22485 22486Parameters that are computed in the @var{init} routine can be 22487stored in an array or structure that is avaiable by means of the 22488@ifhtml 22489@ref{funct:unur_dext_get_params,@command{unur_dext_get_params}} 22490@end ifhtml 22491@ifnothtml 22492@command{unur_dext_get_params} 22493@end ifnothtml 22494call. Parameters of the underlying 22495distribution object can be obtained by the 22496@ifhtml 22497@ref{funct:unur_dext_get_distrparams,@command{unur_dext_get_distrparams}} 22498@end ifhtml 22499@ifnothtml 22500@command{unur_dext_get_distrparams} 22501@end ifnothtml 22502call. 22503@end deftypefn 22504@end ifnotinfo 22505 22506@ifinfo 22507@anchor{funct:unur_dext_set_sample} 22508@deftypefn Function {int} unur_dext_set_sample (UNUR_PAR* @var{parameters}, int (* @var{sample})(UNUR_GEN* gen )) 22509Set sampling routine for external generator. 22510 22511@emph{Important:} 22512Use @code{unur_sample_urng(gen)} to get a uniform random number. 22513The pointer to the array or structure that contains the parameters 22514that are precomputed in the @var{init} routine are available by 22515@code{unur_dext_get_params(gen,0)}. 22516Additionally one can use the 22517@ifhtml 22518@ref{funct:unur_dext_get_distrparams,@command{unur_dext_get_distrparams}} 22519@end ifhtml 22520@ifnothtml 22521@command{unur_dext_get_distrparams} 22522@end ifnothtml 22523call. 22524@end deftypefn 22525@end ifinfo 22526@ifnotinfo 22527@anchor{funct:unur_dext_set_sample} 22528@deftypefn {} {int} unur_dext_set_sample (UNUR_PAR* @var{parameters}, int (* @var{sample})(UNUR_GEN* gen )) 22529Set sampling routine for external generator. 22530 22531@emph{Important:} 22532Use @code{unur_sample_urng(gen)} to get a uniform random number. 22533The pointer to the array or structure that contains the parameters 22534that are precomputed in the @var{init} routine are available by 22535@code{unur_dext_get_params(gen,0)}. 22536Additionally one can use the 22537@ifhtml 22538@ref{funct:unur_dext_get_distrparams,@command{unur_dext_get_distrparams}} 22539@end ifhtml 22540@ifnothtml 22541@command{unur_dext_get_distrparams} 22542@end ifnothtml 22543call. 22544@end deftypefn 22545@end ifnotinfo 22546 22547@ifinfo 22548@anchor{funct:unur_dext_get_params} 22549@deftypefn Function {void*} unur_dext_get_params (UNUR_GEN* @var{generator}, size_t @var{size}) 22550Get pointer to memory block for storing parameters of external 22551generator. A memory block of size @var{size} is automatically (re-) 22552allocated if necessary and the pointer to this block is stored in 22553the @var{generator} object. If one only needs the pointer to this 22554memory block set @var{size} to @code{0}. 22555 22556Notice, that @var{size} is the size of the memory block and not the 22557length of an array. 22558 22559@emph{Important:} This rountine should only be used in the 22560initialization and sampling routine of the external generator. 22561@end deftypefn 22562@end ifinfo 22563@ifnotinfo 22564@anchor{funct:unur_dext_get_params} 22565@deftypefn {} {void*} unur_dext_get_params (UNUR_GEN* @var{generator}, size_t @var{size}) 22566Get pointer to memory block for storing parameters of external 22567generator. A memory block of size @var{size} is automatically (re-) 22568allocated if necessary and the pointer to this block is stored in 22569the @var{generator} object. If one only needs the pointer to this 22570memory block set @var{size} to @code{0}. 22571 22572Notice, that @var{size} is the size of the memory block and not the 22573length of an array. 22574 22575@emph{Important:} This rountine should only be used in the 22576initialization and sampling routine of the external generator. 22577@end deftypefn 22578@end ifnotinfo 22579 22580@ifinfo 22581@anchor{funct:unur_dext_get_distrparams} 22582@deftypefn Function {double*} unur_dext_get_distrparams (UNUR_GEN* @var{generator}) 22583@anchor{funct:unur_dext_get_ndistrparams} 22584@deftypefnx Function {int} unur_dext_get_ndistrparams (UNUR_GEN* @var{generator}) 22585Get size of and pointer to array of parameters of underlying 22586distribution in @var{generator} object. 22587 22588@emph{Important:} These rountines should only be used in the 22589initialization and sampling routine of the external generator. 22590@end deftypefn 22591@end ifinfo 22592@ifnotinfo 22593@anchor{funct:unur_dext_get_distrparams} 22594@deftypefn {} {double*} unur_dext_get_distrparams (UNUR_GEN* @var{generator}) 22595@anchor{funct:unur_dext_get_ndistrparams} 22596@deftypefnx {} {int} unur_dext_get_ndistrparams (UNUR_GEN* @var{generator}) 22597Get size of and pointer to array of parameters of underlying 22598distribution in @var{generator} object. 22599 22600@emph{Important:} These rountines should only be used in the 22601initialization and sampling routine of the external generator. 22602@end deftypefn 22603@end ifnotinfo 22604 22605 22606 22607 22608@c 22609@c end of dext.h 22610@c ------------------------------------- 22611@c ------------------------------------- 22612@c dgt.h 22613@c 22614 22615@page 22616@node DGT 22617@subsection DGT -- (Discrete) Guide Table method (indexed search) 22618 22619@table @i 22620@item Required: 22621probability vector (PV) 22622@item Speed: 22623Set-up: slow (linear with the vector-length), Sampling: very fast 22624@item Reinit: 22625supported 22626@item Reference: 22627@ifhtml 22628@ref{bib:CAa74,, [CAa74]} 22629@end ifhtml 22630@ifnothtml 22631[CAa74] 22632@end ifnothtml 22633@ifhtml 22634@ref{bib:HLD04,, [HLD04: Sect.3.1.2]} 22635@end ifhtml 22636@ifnothtml 22637[HLD04: Sect.3.1.2] 22638@end ifnothtml 22639 22640@end table 22641@sp 1 22642 22643 22644DGT samples from arbitrary but finite probability vectors. Random 22645numbers are generated by the inversion method, i.e., 22646 22647@enumerate 22648@item 22649Generate a random number U ~ U(0,1). 22650@item 22651Find smallest integer I such that F(I) = P(X<=I) >= U. 22652@end enumerate 22653 22654Step (2) is the crucial step. Using sequential search requires 22655@i{O(E(X))} comparisons, where @i{E(X)} is the expectation of 22656the distribution. Indexed search, however, uses a guide table to 22657jump to some @i{I'} <= @i{I} near @i{I} to find @i{X} in constant 22658time. Indeed the expected number of comparisons is reduced to 2, 22659when the guide table has the same size as the probability vector 22660(this is the default). For larger guide tables this number 22661becomes smaller (but is always larger than 1), for smaller 22662tables it becomes larger. For the limit case of table size 1 the 22663algorithm simply does sequential search (but uses a more expensive 22664setup then method DSS (@pxref{DSS}). On the other hand the 22665setup time for guide table is @i{O(N)}, where @i{N} denotes the 22666length of the probability vector (for size 1 no preprocessing is 22667required). Moreover, for very large guide tables memory effects might 22668even reduce the speed of the algorithm. So we do not recommend to 22669use guide tables that are more than three times larger than the 22670given probability vector. If only a few random numbers have to be 22671generated, (much) smaller table sizes are better. 22672The size of the guide table relative to the length of the given 22673probability vector can be set by a 22674@ifhtml 22675@ref{funct:unur_dgt_set_guidefactor,@command{unur_dgt_set_guidefactor}} 22676@end ifhtml 22677@ifnothtml 22678@command{unur_dgt_set_guidefactor} 22679@end ifnothtml 22680call. 22681 22682There exist two variants for the setup step which can be set by a 22683@ifhtml 22684@ref{funct:unur_dgt_set_variant,@command{unur_dgt_set_variant}} 22685@end ifhtml 22686@ifnothtml 22687@command{unur_dgt_set_variant} 22688@end ifnothtml 22689call: Variants 1 and 2. 22690Variant 2 is faster but more sensitive to roundoff errors when the 22691guide table is large. By default variant 2 is used for short 22692probability vectors (@i{N}<1000) and variant 1 otherwise. 22693 22694By default the probability vector is indexed starting at 22695@code{0}. However this can be changed in the distribution object by 22696a 22697@ifhtml 22698@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 22699@end ifhtml 22700@ifnothtml 22701@command{unur_distr_discr_set_domain} 22702@end ifnothtml 22703call. 22704 22705The method also works when no probability vector but a PMF is 22706given. However, then additionally a bounded (not too large) domain 22707must be given or the sum over the PMF. In the latter case the 22708domain of the distribution is trucated (see 22709@ifhtml 22710@ref{funct:unur_distr_discr_make_pv,@command{unur_distr_discr_make_pv}} 22711@end ifhtml 22712@ifnothtml 22713@command{unur_distr_discr_make_pv} 22714@end ifnothtml 22715for details). 22716 22717 22718@subsubheading How To Use 22719 22720 22721Create an object for a discrete distribution either by setting a 22722probability vector or a PMF. The performance can be slightly 22723influenced by setting the size of the used table which can be 22724changed by 22725@ifhtml 22726@ref{funct:unur_dgt_set_guidefactor,@command{unur_dgt_set_guidefactor}.} 22727@end ifhtml 22728@ifnothtml 22729@command{unur_dgt_set_guidefactor}. 22730@end ifnothtml 22731It is possible to change the parameters and the domain of the chosen 22732distribution and run 22733@ifhtml 22734@ref{funct:unur_reinit,@command{unur_reinit}} 22735@end ifhtml 22736@ifnothtml 22737@command{unur_reinit} 22738@end ifnothtml 22739to reinitialize the generator object. 22740 22741 22742 22743@subheading Function reference 22744 22745@ifhtml 22746@itemize 22747@item @ref{funct:unur_dgt_new,unur_dgt_new} 22748@item @ref{funct:unur_dgt_set_guidefactor,unur_dgt_set_guidefactor} 22749@item @ref{funct:unur_dgt_set_variant,unur_dgt_set_variant} 22750@end itemize 22751@end ifhtml 22752 22753 22754@ifinfo 22755@anchor{funct:unur_dgt_new} 22756@deftypefn Function {UNUR_PAR*} unur_dgt_new (const @var{UNUR_DISTR* distribution}) 22757Get default parameters for generator. 22758@end deftypefn 22759@end ifinfo 22760@ifnotinfo 22761@anchor{funct:unur_dgt_new} 22762@deftypefn {} {UNUR_PAR*} unur_dgt_new (const @var{UNUR_DISTR* distribution}) 22763Get default parameters for generator. 22764@end deftypefn 22765@end ifnotinfo 22766 22767@ifinfo 22768@anchor{funct:unur_dgt_set_guidefactor} 22769@deftypefn Function {int} unur_dgt_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 22770Set size of guide table relative to length of PV. 22771Larger guide tables result in faster generation time but require a 22772more expensive setup. Sizes larger than 3 are not recommended. 22773If the relative size is set to 0, sequential search is used. 22774However, this is not recommended, except in exceptional cases, since 22775method DSS (@pxref{DSS}) is has almost no setup and is thus faster 22776(but requires the sum over the PV as input parameter). 22777 22778Default is @code{1}. 22779@end deftypefn 22780@end ifinfo 22781@ifnotinfo 22782@anchor{funct:unur_dgt_set_guidefactor} 22783@deftypefn {} {int} unur_dgt_set_guidefactor (UNUR_PAR* @var{parameters}, double @var{factor}) 22784Set size of guide table relative to length of PV. 22785Larger guide tables result in faster generation time but require a 22786more expensive setup. Sizes larger than 3 are not recommended. 22787If the relative size is set to 0, sequential search is used. 22788However, this is not recommended, except in exceptional cases, since 22789method DSS (@pxref{DSS}) is has almost no setup and is thus faster 22790(but requires the sum over the PV as input parameter). 22791 22792Default is @code{1}. 22793@end deftypefn 22794@end ifnotinfo 22795 22796@ifinfo 22797@anchor{funct:unur_dgt_set_variant} 22798@deftypefn Function {int} unur_dgt_set_variant (UNUR_PAR* @var{parameters}, unsigned @var{variant}) 22799Set variant for setup step. Possible values are @code{1} or 22800@code{2}. 22801Variant @code{2} is faster but more sensitive to roundoff errors 22802when the guide table is large. 22803By default variant @code{2} is used for short probability 22804vectors (@i{N}<1000) and variant @code{1} otherwise. 22805@end deftypefn 22806@end ifinfo 22807@ifnotinfo 22808@anchor{funct:unur_dgt_set_variant} 22809@deftypefn {} {int} unur_dgt_set_variant (UNUR_PAR* @var{parameters}, unsigned @var{variant}) 22810Set variant for setup step. Possible values are @code{1} or 22811@code{2}. 22812Variant @code{2} is faster but more sensitive to roundoff errors 22813when the guide table is large. 22814By default variant @code{2} is used for short probability 22815vectors (@i{N}<1000) and variant @code{1} otherwise. 22816@end deftypefn 22817@end ifnotinfo 22818 22819 22820 22821 22822@c 22823@c end of dgt.h 22824@c ------------------------------------- 22825@c ------------------------------------- 22826@c dsrou.h 22827@c 22828 22829@page 22830@node DSROU 22831@subsection DSROU -- Discrete Simple Ratio-Of-Uniforms method 22832 22833@table @i 22834@item Required: 22835T-concave PMF, mode, sum over PMF 22836@item Speed: 22837Set-up: fast, Sampling: slow 22838@item Reinit: 22839supported 22840@item Reference: 22841@ifhtml 22842@ref{bib:LJa01,, [LJa01]} 22843@end ifhtml 22844@ifnothtml 22845[LJa01] 22846@end ifnothtml 22847@ifhtml 22848@ref{bib:HLD04,, [HLD04: Sect.10.3.2; Alg.10.6]} 22849@end ifhtml 22850@ifnothtml 22851[HLD04: Sect.10.3.2; Alg.10.6] 22852@end ifnothtml 22853 22854@end table 22855@sp 1 22856 22857 22858DSROU is based on the ratio-of-uniforms method 22859(@pxref{Ratio-of-Uniforms}) but uses universal 22860inequalities for constructing a (universal) bounding rectangle. 22861It works for all @i{T}-concave distributions with 22862@iftex 22863@math{T(x) = -1/\sqrt{x}} 22864@end iftex 22865@ifhtml 22866@html 22867<I>T</I>(<I>x</I>) = -1/sqrt(<I>x</I>) 22868@end html 22869@end ifhtml 22870@ifinfo 22871@math{T(x) = -1/sqrt(x)} 22872@end ifinfo 22873. 22874 22875The method requires the PMF, the (exact) location of the mode 22876and the sum over the given PDF. The rejection constant is 4 for 22877all @i{T}-concave distributions. Optionally the CDF at the mode 22878can be given to increase the performance of the algorithm. Then 22879the rejection constant is reduced to 2. 22880 22881 22882@subsubheading How To Use 22883 22884 22885The method works for @i{T}-concave discrete distributions with 22886given PMF. The sum over of the PMF or an upper bound of this sum 22887must be known. 22888 22889Optionally the CDF at the mode can be given to increase the 22890performance using 22891@ifhtml 22892@ref{funct:unur_dsrou_set_cdfatmode,@command{unur_dsrou_set_cdfatmode}.} 22893@end ifhtml 22894@ifnothtml 22895@command{unur_dsrou_set_cdfatmode}. 22896@end ifnothtml 22897However, this @strong{must not} be called if the sum over the 22898PMF is replaced by an upper bound. 22899 22900It is possible to change the parameters and the domain of the chosen 22901distribution and run 22902@ifhtml 22903@ref{funct:unur_reinit,@command{unur_reinit}} 22904@end ifhtml 22905@ifnothtml 22906@command{unur_reinit} 22907@end ifnothtml 22908to reinitialize the generator object. 22909 22910If any of mode, CDF at mode, or the sum over the PMF has been 22911changed, then 22912@ifhtml 22913@ref{funct:unur_reinit,@command{unur_reinit}} 22914@end ifhtml 22915@ifnothtml 22916@command{unur_reinit} 22917@end ifnothtml 22918must be executed. 22919(Otherwise the generator produces garbage). 22920 22921There exists a test mode that verifies whether the conditions 22922for the method are satisfied or not while sampling. It can be 22923switched on or off by calling 22924@ifhtml 22925@ref{funct:unur_dsrou_set_verify,@command{unur_dsrou_set_verify}} 22926@end ifhtml 22927@ifnothtml 22928@command{unur_dsrou_set_verify} 22929@end ifnothtml 22930and 22931@ifhtml 22932@ref{funct:unur_dsrou_chg_verify,@command{unur_dsrou_chg_verify},} 22933@end ifhtml 22934@ifnothtml 22935@command{unur_dsrou_chg_verify}, 22936@end ifnothtml 22937respectively. 22938Notice however that sampling is (a little bit) slower then. 22939 22940 22941 22942 22943@subheading Function reference 22944 22945@ifhtml 22946@itemize 22947@item @ref{funct:unur_dsrou_new,unur_dsrou_new} 22948@item @ref{funct:unur_dsrou_set_cdfatmode,unur_dsrou_set_cdfatmode} 22949@item @ref{funct:unur_dsrou_set_verify,unur_dsrou_set_verify} 22950@item @ref{funct:unur_dsrou_chg_verify,unur_dsrou_chg_verify} 22951@item @ref{funct:unur_dsrou_chg_cdfatmode,unur_dsrou_chg_cdfatmode} 22952@end itemize 22953@end ifhtml 22954 22955 22956@ifinfo 22957@anchor{funct:unur_dsrou_new} 22958@deftypefn Function {UNUR_PAR*} unur_dsrou_new (const @var{UNUR_DISTR* distribution}) 22959Get default parameters for generator. 22960@end deftypefn 22961@end ifinfo 22962@ifnotinfo 22963@anchor{funct:unur_dsrou_new} 22964@deftypefn {} {UNUR_PAR*} unur_dsrou_new (const @var{UNUR_DISTR* distribution}) 22965Get default parameters for generator. 22966@end deftypefn 22967@end ifnotinfo 22968 22969@ifinfo 22970@anchor{funct:unur_dsrou_set_cdfatmode} 22971@deftypefn Function {int} unur_dsrou_set_cdfatmode (UNUR_PAR* @var{parameters}, double @var{Fmode}) 22972Set CDF at mode. 22973When set, the performance of the algorithm is increased by factor 2. 22974However, when the parameters of the distribution are changed 22975@ifhtml 22976@ref{funct:unur_dsrou_chg_cdfatmode,@command{unur_dsrou_chg_cdfatmode}} 22977@end ifhtml 22978@ifnothtml 22979@command{unur_dsrou_chg_cdfatmode} 22980@end ifnothtml 22981has to be used to update this value. 22982Notice that the algorithm detects a mode at the left boundary of 22983the domain automatically and it is not necessary to use this call 22984for a monotonically decreasing PMF. 22985 22986Default: not set. 22987@end deftypefn 22988@end ifinfo 22989@ifnotinfo 22990@anchor{funct:unur_dsrou_set_cdfatmode} 22991@deftypefn {} {int} unur_dsrou_set_cdfatmode (UNUR_PAR* @var{parameters}, double @var{Fmode}) 22992Set CDF at mode. 22993When set, the performance of the algorithm is increased by factor 2. 22994However, when the parameters of the distribution are changed 22995@ifhtml 22996@ref{funct:unur_dsrou_chg_cdfatmode,@command{unur_dsrou_chg_cdfatmode}} 22997@end ifhtml 22998@ifnothtml 22999@command{unur_dsrou_chg_cdfatmode} 23000@end ifnothtml 23001has to be used to update this value. 23002Notice that the algorithm detects a mode at the left boundary of 23003the domain automatically and it is not necessary to use this call 23004for a monotonically decreasing PMF. 23005 23006Default: not set. 23007@end deftypefn 23008@end ifnotinfo 23009 23010@ifinfo 23011@anchor{funct:unur_dsrou_set_verify} 23012@deftypefn Function {int} unur_dsrou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 23013@anchor{funct:unur_dsrou_chg_verify} 23014@deftypefnx Function {int} unur_dsrou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 23015Turn verifying of algorithm while sampling on/off. 23016If the condition squeeze(@i{x}) <= PMF(@i{x}) <= hat(@i{x}) is 23017violated for some @i{x} then @code{unur_errno} is set to 23018@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 23019happen due to round-off errors for a few values of 23020@i{x} (less than 1%). 23021 23022Default is @code{FALSE}. 23023@end deftypefn 23024@end ifinfo 23025@ifnotinfo 23026@anchor{funct:unur_dsrou_set_verify} 23027@deftypefn {} {int} unur_dsrou_set_verify (UNUR_PAR* @var{parameters}, int @var{verify}) 23028@anchor{funct:unur_dsrou_chg_verify} 23029@deftypefnx {} {int} unur_dsrou_chg_verify (UNUR_GEN* @var{generator}, int @var{verify}) 23030Turn verifying of algorithm while sampling on/off. 23031If the condition squeeze(@i{x}) <= PMF(@i{x}) <= hat(@i{x}) is 23032violated for some @i{x} then @code{unur_errno} is set to 23033@code{UNUR_ERR_GEN_CONDITION}. However notice that this might 23034happen due to round-off errors for a few values of 23035@i{x} (less than 1%). 23036 23037Default is @code{FALSE}. 23038@end deftypefn 23039@end ifnotinfo 23040 23041@ifinfo 23042@anchor{funct:unur_dsrou_chg_cdfatmode} 23043@deftypefn Function {int} unur_dsrou_chg_cdfatmode (UNUR_GEN* @var{generator}, double @var{Fmode}) 23044Change CDF at mode of distribution. 23045@ifhtml 23046@ref{funct:unur_reinit,@command{unur_reinit}} 23047@end ifhtml 23048@ifnothtml 23049@command{unur_reinit} 23050@end ifnothtml 23051must be executed before sampling from the 23052generator again. 23053@end deftypefn 23054@end ifinfo 23055@ifnotinfo 23056@anchor{funct:unur_dsrou_chg_cdfatmode} 23057@deftypefn {} {int} unur_dsrou_chg_cdfatmode (UNUR_GEN* @var{generator}, double @var{Fmode}) 23058Change CDF at mode of distribution. 23059@ifhtml 23060@ref{funct:unur_reinit,@command{unur_reinit}} 23061@end ifhtml 23062@ifnothtml 23063@command{unur_reinit} 23064@end ifnothtml 23065must be executed before sampling from the 23066generator again. 23067@end deftypefn 23068@end ifnotinfo 23069 23070 23071 23072 23073@c 23074@c end of dsrou.h 23075@c ------------------------------------- 23076@c ------------------------------------- 23077@c dss.h 23078@c 23079 23080@page 23081@node DSS 23082@subsection DSS -- (Discrete) Sequential Search method 23083 23084@table @i 23085@item Required: 23086probability vector (PV) and sum over PV; or probability mass function(PMF), sum over PV and domain; or or cumulative distribution function (CDF) 23087@item Speed: 23088Set-up: fast, Sampling: very slow (linear in expectation) 23089@item Reinit: 23090supported 23091@item Reference: 23092@ifhtml 23093@ref{bib:HLD04,, [HLD04: Sect.3.1.1; Alg.3.1]} 23094@end ifhtml 23095@ifnothtml 23096[HLD04: Sect.3.1.1; Alg.3.1] 23097@end ifnothtml 23098 23099@end table 23100@sp 1 23101 23102 23103DSS samples from arbitrary discrete distributions. 23104Random numbers are generated by the inversion method, i.e., 23105 23106@enumerate 23107@item 23108Generate a random number U ~ U(0,1). 23109@item 23110Find smallest integer I such that F(I) = P(X<=I) >= U. 23111@end enumerate 23112 23113Step (2) is the crucial step. Using sequential search requires 23114@i{O(E(X))} comparisons, where @i{E(X)} is the expectation of 23115the distribution. Thus this method is only recommended when only 23116a few random variates from the given distribution are required. 23117Otherwise, table methods like DGT (@pxref{DGT}) or DAU (@pxref{DAU}) 23118are much faster. These methods also need not the sum over the 23119PMF (or PV) as input. On the other hand, however, these methods 23120always compute a table. 23121 23122DSS runs with the PV, the PMF, or the CDF of the distribution. 23123It uses actually uses the first one in this list (in this 23124ordering) that could be found. 23125 23126 23127@subsubheading How To Use 23128 23129 23130It works with a discrete distribution object with contains at 23131least the PV, the PMF, or the CDF. 23132 23133It is possible to change the parameters and the domain of the chosen 23134distribution and run 23135@ifhtml 23136@ref{funct:unur_reinit,@command{unur_reinit}} 23137@end ifhtml 23138@ifnothtml 23139@command{unur_reinit} 23140@end ifnothtml 23141to reinitialize the generator object. 23142 23143 23144 23145 23146@subheading Function reference 23147 23148@ifhtml 23149@itemize 23150@item @ref{funct:unur_dss_new,unur_dss_new} 23151@end itemize 23152@end ifhtml 23153 23154 23155@ifinfo 23156@anchor{funct:unur_dss_new} 23157@deftypefn Function {UNUR_PAR*} unur_dss_new (const @var{UNUR_DISTR* distribution}) 23158Get default parameters for generator. 23159@end deftypefn 23160@end ifinfo 23161@ifnotinfo 23162@anchor{funct:unur_dss_new} 23163@deftypefn {} {UNUR_PAR*} unur_dss_new (const @var{UNUR_DISTR* distribution}) 23164Get default parameters for generator. 23165@end deftypefn 23166@end ifnotinfo 23167 23168 23169 23170 23171@c 23172@c end of dss.h 23173@c ------------------------------------- 23174@c ------------------------------------- 23175@c dstd.h 23176@c 23177 23178@page 23179@node DSTD 23180@subsection DSTD -- Discrete STandarD distributions 23181 23182@table @i 23183@item Required: 23184standard distribution from UNU.RAN library (@pxref{Stddist,,Standard distributions}) or discrete distribution with inverse CDF. 23185@item Speed: 23186Set-up: fast, Sampling: depends on distribution and generator 23187@item Reinit: 23188supported 23189@end table 23190@sp 1 23191 23192 23193DSTD is a wrapper for special generators for discrete univariate 23194standard distributions. It only works for distributions in the 23195UNU.RAN library of standard distributions 23196(@pxref{Stddist,,Standard distributions}) 23197or for discrete distributions where the inverse CDF is given. 23198If a distribution object is provided that is build from scratch, 23199it must provide the inverse CDF. Then CSTD implements the 23200inversion method. Otherwise, the @code{NULL} pointer is returned. 23201 23202For some distributions more than one special generator 23203is possible. 23204 23205 23206@subsubheading How To Use 23207 23208 23209Create a distribution object for a standard distribution 23210from the UNU.RAN library 23211(@pxref{Stddist,,Standard distributions}), 23212or create a discrete distribution object and set the function 23213for the inverse CDF using 23214@ifhtml 23215@ref{funct:unur_distr_discr_set_invcdf,@command{unur_distr_discr_set_invcdf}.} 23216@end ifhtml 23217@ifnothtml 23218@command{unur_distr_discr_set_invcdf}. 23219@end ifnothtml 23220For some distributions more than one special generator 23221(@emph{variants}) is possible. These can be choosen by a 23222@ifhtml 23223@ref{funct:unur_dstd_set_variant,@command{unur_dstd_set_variant}} 23224@end ifhtml 23225@ifnothtml 23226@command{unur_dstd_set_variant} 23227@end ifnothtml 23228call. For possible variants 23229@xref{Stddist,,Standard distributions}. 23230However the following are common to all distributions: 23231 23232@table @code 23233@item UNUR_STDGEN_DEFAULT 23234the default generator. 23235@item UNUR_STDGEN_FAST 23236the fastest available special generator. 23237@item UNUR_STDGEN_INVERSION 23238the inversion method (if available). 23239@end table 23240 23241Notice that the variant @code{UNUR_STDGEN_FAST} for a special 23242generator might be slower than one of the universal algorithms! 23243Additional variants may exist for particular distributions. 23244 23245Sampling from truncated distributions (which can be constructed by 23246changing the default domain of a distribution by means of 23247@ifhtml 23248@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 23249@end ifhtml 23250@ifnothtml 23251@command{unur_distr_discr_set_domain} 23252@end ifnothtml 23253or unur_dstd_chg_truncated calls) 23254is possible but requires the inversion method. Moreover the CDF 23255of the distribution must be implemented. 23256 23257It is possible to change the parameters and the domain of the chosen 23258distribution and run 23259@ifhtml 23260@ref{funct:unur_reinit,@command{unur_reinit}} 23261@end ifhtml 23262@ifnothtml 23263@command{unur_reinit} 23264@end ifnothtml 23265to reinitialize the generator object. 23266 23267 23268 23269 23270@subheading Function reference 23271 23272@ifhtml 23273@itemize 23274@item @ref{funct:unur_dstd_new,unur_dstd_new} 23275@item @ref{funct:unur_dstd_set_variant,unur_dstd_set_variant} 23276@item @ref{funct:unur_dstd_chg_truncated,unur_dstd_chg_truncated} 23277@end itemize 23278@end ifhtml 23279 23280 23281@ifinfo 23282@anchor{funct:unur_dstd_new} 23283@deftypefn Function {UNUR_PAR*} unur_dstd_new (const @var{UNUR_DISTR* distribution}) 23284Get default parameters for new generator. It requires a distribution object 23285for a discrete univariant distribution from the 23286UNU.RAN library of standard distributions 23287(@pxref{Stddist,,Standard distributions}). 23288 23289Using a truncated distribution is allowed only if the inversion method 23290is available and selected by the 23291@ifhtml 23292@ref{funct:unur_dstd_set_variant,@command{unur_dstd_set_variant}} 23293@end ifhtml 23294@ifnothtml 23295@command{unur_dstd_set_variant} 23296@end ifnothtml 23297call immediately 23298after creating the parameter object. 23299Use a 23300@ifhtml 23301@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 23302@end ifhtml 23303@ifnothtml 23304@command{unur_distr_discr_set_domain} 23305@end ifnothtml 23306call to get a truncated 23307distribution. 23308@end deftypefn 23309@end ifinfo 23310@ifnotinfo 23311@anchor{funct:unur_dstd_new} 23312@deftypefn {} {UNUR_PAR*} unur_dstd_new (const @var{UNUR_DISTR* distribution}) 23313Get default parameters for new generator. It requires a distribution object 23314for a discrete univariant distribution from the 23315UNU.RAN library of standard distributions 23316(@pxref{Stddist,,Standard distributions}). 23317 23318Using a truncated distribution is allowed only if the inversion method 23319is available and selected by the 23320@ifhtml 23321@ref{funct:unur_dstd_set_variant,@command{unur_dstd_set_variant}} 23322@end ifhtml 23323@ifnothtml 23324@command{unur_dstd_set_variant} 23325@end ifnothtml 23326call immediately 23327after creating the parameter object. 23328Use a 23329@ifhtml 23330@ref{funct:unur_distr_discr_set_domain,@command{unur_distr_discr_set_domain}} 23331@end ifhtml 23332@ifnothtml 23333@command{unur_distr_discr_set_domain} 23334@end ifnothtml 23335call to get a truncated 23336distribution. 23337@end deftypefn 23338@end ifnotinfo 23339 23340@ifinfo 23341@anchor{funct:unur_dstd_set_variant} 23342@deftypefn Function {int} unur_dstd_set_variant (UNUR_PAR* @var{parameters}, unsigned @var{variant}) 23343Set variant (special generator) for sampling from a given distribution. 23344For possible variants 23345@pxref{Stddist,,Standard distributions}. 23346 23347Common variants are @code{UNUR_STDGEN_DEFAULT} for the default generator, 23348@code{UNUR_STDGEN_FAST} for (one of the) fastest implemented 23349special generators, and @code{UNUR_STDGEN_INVERSION} for the 23350inversion method (if available). 23351If the selected variant number is not implemented, then an error code is 23352returned and the variant is not changed. 23353@end deftypefn 23354@end ifinfo 23355@ifnotinfo 23356@anchor{funct:unur_dstd_set_variant} 23357@deftypefn {} {int} unur_dstd_set_variant (UNUR_PAR* @var{parameters}, unsigned @var{variant}) 23358Set variant (special generator) for sampling from a given distribution. 23359For possible variants 23360@pxref{Stddist,,Standard distributions}. 23361 23362Common variants are @code{UNUR_STDGEN_DEFAULT} for the default generator, 23363@code{UNUR_STDGEN_FAST} for (one of the) fastest implemented 23364special generators, and @code{UNUR_STDGEN_INVERSION} for the 23365inversion method (if available). 23366If the selected variant number is not implemented, then an error code is 23367returned and the variant is not changed. 23368@end deftypefn 23369@end ifnotinfo 23370 23371@ifinfo 23372@anchor{funct:unur_dstd_chg_truncated} 23373@deftypefn Function {int} unur_dstd_chg_truncated (UNUR_GEN* @var{generator}, int @var{left}, int @var{right}) 23374Change left and right border of the domain of the (truncated) distribution. 23375This is only possible if the inversion method is used. 23376Otherwise this call has no effect and an error code is returned. 23377 23378Notice that the given truncated domain must be a subset of the 23379domain of the given distribution. The generator always uses the 23380intersection of the domain of the distribution and the truncated 23381domain given by this call. 23382 23383It is not required to run 23384@ifhtml 23385@ref{funct:unur_reinit,@command{unur_reinit}} 23386@end ifhtml 23387@ifnothtml 23388@command{unur_reinit} 23389@end ifnothtml 23390after this call has been used. 23391 23392@emph{Important:} If the CDF is (almost) the same for @var{left} and 23393@var{right} and (almost) equal to @code{0} or @code{1}, then the truncated 23394domain is not chanced and the call returns an error code. 23395 23396@emph{Notice:} If the parameters of the distribution has been changed 23397it is recommended to set the truncated domain again, since the 23398former call might change the domain of the distribution but not 23399update the values for the boundaries of the truncated 23400distribution. 23401@end deftypefn 23402@end ifinfo 23403@ifnotinfo 23404@anchor{funct:unur_dstd_chg_truncated} 23405@deftypefn {} {int} unur_dstd_chg_truncated (UNUR_GEN* @var{generator}, int @var{left}, int @var{right}) 23406Change left and right border of the domain of the (truncated) distribution. 23407This is only possible if the inversion method is used. 23408Otherwise this call has no effect and an error code is returned. 23409 23410Notice that the given truncated domain must be a subset of the 23411domain of the given distribution. The generator always uses the 23412intersection of the domain of the distribution and the truncated 23413domain given by this call. 23414 23415It is not required to run 23416@ifhtml 23417@ref{funct:unur_reinit,@command{unur_reinit}} 23418@end ifhtml 23419@ifnothtml 23420@command{unur_reinit} 23421@end ifnothtml 23422after this call has been used. 23423 23424@emph{Important:} If the CDF is (almost) the same for @var{left} and 23425@var{right} and (almost) equal to @code{0} or @code{1}, then the truncated 23426domain is not chanced and the call returns an error code. 23427 23428@emph{Notice:} If the parameters of the distribution has been changed 23429it is recommended to set the truncated domain again, since the 23430former call might change the domain of the distribution but not 23431update the values for the boundaries of the truncated 23432distribution. 23433@end deftypefn 23434@end ifnotinfo 23435 23436 23437 23438 23439@c 23440@c end of dstd.h 23441@c ------------------------------------- 23442@c ------------------------------------- 23443@c methods.dh 23444@c 23445 23446@page 23447@node Methods_for_MATR 23448@section Methods for random matrices 23449 23450@menu 23451* MCORR:: Random CORRelation matrix 23452@end menu 23453 23454 23455 23456@subheading Overview of methods 23457 23458@include methods_matr.texi 23459 23460 23461 23462@c 23463@c end of methods.dh 23464@c ------------------------------------- 23465@c ------------------------------------- 23466@c mcorr.h 23467@c 23468 23469@page 23470@node MCORR 23471@subsection MCORR -- Random CORRelation matrix 23472 23473@table @i 23474@item Required: 23475Distribution object for random correlation matrix 23476@item Speed: 23477Set-up: fast, Sampling: depends on dimension 23478@item Reinit: 23479supported 23480@item Reference: 23481@ifhtml 23482@ref{bib:DLa86,, [DLa86: Sect.6.1; p.605]} 23483@end ifhtml 23484@ifnothtml 23485[DLa86: Sect.6.1; p.605] 23486@end ifnothtml 23487@ifhtml 23488@ref{bib:MOa84,, [MOa84]} 23489@end ifhtml 23490@ifnothtml 23491[MOa84] 23492@end ifnothtml 23493 23494@end table 23495@sp 1 23496 23497 23498MCORR generates a random correlation matrix 23499(Pearson's correlation). 23500Two methods are used: 23501 23502@enumerate 23503@item 23504When a random correlation matrix having given eigenvalues is 23505sought, the method of Marsaglia and Olkin [MOa84] is used. 23506In this case, the correlation matrix 23507@iftex 23508@math{R} 23509@end iftex 23510@ifhtml 23511@html 23512<I>R</I> 23513@end html 23514@end ifhtml 23515@ifinfo 23516@math{R} 23517@end ifinfo 23518is given as 23519@iftex 23520@math{R=PDP'} 23521@end iftex 23522@ifhtml 23523@html 23524<I>R</I>=<I>PDP</I>' 23525@end html 23526@end ifhtml 23527@ifinfo 23528@math{R=PDP'} 23529@end ifinfo 23530where 23531@iftex 23532@math{D} 23533@end iftex 23534@ifhtml 23535@html 23536<I>D</I> 23537@end html 23538@end ifhtml 23539@ifinfo 23540@math{D} 23541@end ifinfo 23542is a diagonal 23543matrix containing the eigenvalues and 23544@iftex 23545@math{P} 23546@end iftex 23547@ifhtml 23548@html 23549<I>P</I> 23550@end html 23551@end ifhtml 23552@ifinfo 23553@math{P} 23554@end ifinfo 23555is a random 23556orthonormal matrix. In higher dimensions, the rounding-errors 23557introduced in the previous matrix multiplications could lead 23558to a non-symmetric correlation matrix. Therefore the symmetric 23559correlation matrix is computed as 23560@iftex 23561@math{R=(PDP'+P'DP)/2} 23562@end iftex 23563@ifhtml 23564@html 23565<I>R</I>=(<I>PDP</I>'+<I>P</I>'<I>DP</I>)/2 23566@end html 23567@end ifhtml 23568@ifinfo 23569@math{R=(PDP'+P'DP)/2} 23570@end ifinfo 23571. 23572 23573@item 23574A matrix 23575@iftex 23576@math{H} 23577@end iftex 23578@ifhtml 23579@html 23580<I>H</I> 23581@end html 23582@end ifhtml 23583@ifinfo 23584@math{H} 23585@end ifinfo 23586is generated where all rows are 23587independent random vectors of unit length uniformly on a sphere. 23588Then 23589@iftex 23590@math{HH'} 23591@end iftex 23592@ifhtml 23593@html 23594<I>HH</I>' 23595@end html 23596@end ifhtml 23597@ifinfo 23598@math{HH'} 23599@end ifinfo 23600is a correlation matrix (and vice versa if 23601@iftex 23602@math{HH'} 23603@end iftex 23604@ifhtml 23605@html 23606<I>HH</I>' 23607@end html 23608@end ifhtml 23609@ifinfo 23610@math{HH'} 23611@end ifinfo 23612is a correlation matrix then the rows of 23613@iftex 23614@math{H} 23615@end iftex 23616@ifhtml 23617@html 23618<I>H</I> 23619@end html 23620@end ifhtml 23621@ifinfo 23622@math{H} 23623@end ifinfo 23624are random vectors on a sphere). 23625 23626@end enumerate 23627 23628Notice that due to round-off errors the generated matrices might 23629not be positive definite in extremely rare cases 23630(especially when the given eigenvalues are amost 0). 23631 23632There are many other possibilites (distributions) of sampling 23633the random rows from a sphere. The chosen methods are simple but 23634does not result in a uniform distriubution of the random 23635correlation matrices. 23636 23637It only works with distribution objects of random correlation 23638matrices (@pxref{correlation,,Random Correlation Matrix}). 23639 23640 23641@subsubheading How To Use 23642 23643 23644Create a distibution object for random correlation matrices by a 23645@code{unur_distr_correlation} call 23646(@pxref{correlation,,Random Correlation Matrix}). 23647 23648When a correlation matrix with given eigenvalues should be 23649generated, these eigenvalues can be set by a 23650@ifhtml 23651@ref{funct:unur_mcorr_set_eigenvalues,@command{unur_mcorr_set_eigenvalues}} 23652@end ifhtml 23653@ifnothtml 23654@command{unur_mcorr_set_eigenvalues} 23655@end ifnothtml 23656call. 23657 23658Otherwise, a faster algorithm is used that generates 23659correlation matrices with random eigenstructure. 23660 23661Notice that due to round-off errors, 23662there is a (small) chance that the resulting matrix is 23663not positive definite for a Cholesky decomposition algorithm, 23664especially when the dimension of the distribution is high. 23665 23666It is possible to change the given eigenvalues using 23667@ifhtml 23668@ref{funct:unur_mcorr_chg_eigenvalues,@command{unur_mcorr_chg_eigenvalues}} 23669@end ifhtml 23670@ifnothtml 23671@command{unur_mcorr_chg_eigenvalues} 23672@end ifnothtml 23673and run 23674@ifhtml 23675@ref{funct:unur_reinit,@command{unur_reinit}} 23676@end ifhtml 23677@ifnothtml 23678@command{unur_reinit} 23679@end ifnothtml 23680to 23681reinitialize the generator object. 23682 23683 23684 23685 23686@subheading Function reference 23687 23688@ifhtml 23689@itemize 23690@item @ref{funct:unur_mcorr_new,unur_mcorr_new} 23691@item @ref{funct:unur_mcorr_set_eigenvalues,unur_mcorr_set_eigenvalues} 23692@item @ref{funct:unur_mcorr_chg_eigenvalues,unur_mcorr_chg_eigenvalues} 23693@end itemize 23694@end ifhtml 23695 23696 23697@ifinfo 23698@anchor{funct:unur_mcorr_new} 23699@deftypefn Function {UNUR_PAR*} unur_mcorr_new (const @var{UNUR_DISTR* distribution}) 23700Get default parameters for generator. 23701@end deftypefn 23702@end ifinfo 23703@ifnotinfo 23704@anchor{funct:unur_mcorr_new} 23705@deftypefn {} {UNUR_PAR*} unur_mcorr_new (const @var{UNUR_DISTR* distribution}) 23706Get default parameters for generator. 23707@end deftypefn 23708@end ifnotinfo 23709 23710@ifinfo 23711@anchor{funct:unur_mcorr_set_eigenvalues} 23712@deftypefn Function {int} unur_mcorr_set_eigenvalues (UNUR_PAR* @var{par}, const @var{double* eigenvalues}) 23713Sets the (optional) eigenvalues of the correlation matrix. 23714If set, then the Marsaglia and Olkin algorithm will be used 23715to generate random correlation matrices with given eigenvalues. 23716 23717Important: the given eigenvalues of the correlation matrix must be 23718strictly positive and sum to the dimension of the matrix. 23719If non-positive eigenvalues are attempted, no eigenvalues are set 23720and an error code is returned. 23721In case, that their sum is different from the dimension, an implicit 23722scaling to give the correct sum is performed. 23723@end deftypefn 23724@end ifinfo 23725@ifnotinfo 23726@anchor{funct:unur_mcorr_set_eigenvalues} 23727@deftypefn {} {int} unur_mcorr_set_eigenvalues (UNUR_PAR* @var{par}, const @var{double* eigenvalues}) 23728Sets the (optional) eigenvalues of the correlation matrix. 23729If set, then the Marsaglia and Olkin algorithm will be used 23730to generate random correlation matrices with given eigenvalues. 23731 23732Important: the given eigenvalues of the correlation matrix must be 23733strictly positive and sum to the dimension of the matrix. 23734If non-positive eigenvalues are attempted, no eigenvalues are set 23735and an error code is returned. 23736In case, that their sum is different from the dimension, an implicit 23737scaling to give the correct sum is performed. 23738@end deftypefn 23739@end ifnotinfo 23740 23741@ifinfo 23742@anchor{funct:unur_mcorr_chg_eigenvalues} 23743@deftypefn Function {int} unur_mcorr_chg_eigenvalues (UNUR_GEN* @var{gen}, const @var{double* eigenvalues}) 23744Change the eigenvalues of the correlation matrix. 23745One must run 23746@ifhtml 23747@ref{funct:unur_reinit,@command{unur_reinit}} 23748@end ifhtml 23749@ifnothtml 23750@command{unur_reinit} 23751@end ifnothtml 23752to reinitialize the generator 23753object then. 23754@end deftypefn 23755@end ifinfo 23756@ifnotinfo 23757@anchor{funct:unur_mcorr_chg_eigenvalues} 23758@deftypefn {} {int} unur_mcorr_chg_eigenvalues (UNUR_GEN* @var{gen}, const @var{double* eigenvalues}) 23759Change the eigenvalues of the correlation matrix. 23760One must run 23761@ifhtml 23762@ref{funct:unur_reinit,@command{unur_reinit}} 23763@end ifhtml 23764@ifnothtml 23765@command{unur_reinit} 23766@end ifnothtml 23767to reinitialize the generator 23768object then. 23769@end deftypefn 23770@end ifnotinfo 23771 23772 23773 23774 23775@c 23776@c end of mcorr.h 23777@c ------------------------------------- 23778@c ------------------------------------- 23779@c methods.dh 23780@c 23781 23782@page 23783@node Methods_for_UNID 23784@section Methods for uniform univariate distributions 23785 23786@menu 23787* UNIF:: wrapper for UNIForm random number generator 23788@end menu 23789 23790 23791 23792 23793@c 23794@c end of methods.dh 23795@c ------------------------------------- 23796@c ------------------------------------- 23797@c unif.h 23798@c 23799 23800@page 23801@node UNIF 23802@subsection UNIF -- wrapper for UNIForm random number generator 23803 23804 23805UNIF is a simple wrapper that makes it possible to use a uniform 23806random number generator as a UNU.RAN generator. There are no 23807parameters for this method. 23808 23809 23810@subsubheading How To Use 23811 23812 23813Create a generator object with @code{NULL} as argument. The created generator 23814object returns raw random numbers from the underlying uniform 23815random number generator. 23816 23817 23818 23819 23820@subheading Function reference 23821 23822@ifhtml 23823@itemize 23824@item @ref{funct:unur_unif_new,unur_unif_new} 23825@end itemize 23826@end ifhtml 23827 23828 23829@ifinfo 23830@anchor{funct:unur_unif_new} 23831@deftypefn Function {UNUR_PAR*} unur_unif_new (const @var{UNUR_DISTR* dummy}) 23832Get default parameters for generator. 23833UNIF does not need a distribution object. @var{dummy} is not used and 23834can (should) be set to @code{NULL}. It is used to keep the API consistent. 23835@end deftypefn 23836@end ifinfo 23837@ifnotinfo 23838@anchor{funct:unur_unif_new} 23839@deftypefn {} {UNUR_PAR*} unur_unif_new (const @var{UNUR_DISTR* dummy}) 23840Get default parameters for generator. 23841UNIF does not need a distribution object. @var{dummy} is not used and 23842can (should) be set to @code{NULL}. It is used to keep the API consistent. 23843@end deftypefn 23844@end ifnotinfo 23845 23846 23847 23848 23849@c 23850@c end of unif.h 23851@c ------------------------------------- 23852@c ------------------------------------- 23853@c methods.dh 23854@c 23855 23856@page 23857@node Meta_Methods 23858@section Meta Methods for univariate distributions 23859 23860@menu 23861* MIXT:: MIXTure of distributions 23862@end menu 23863 23864 23865 23866@subheading Example 23867 23868@smallexample 23869@include ref_example_mixt.texi 23870@end smallexample 23871 23872@subheading Example (Inversion) 23873 23874@smallexample 23875@include ref_example_mixt_inv.texi 23876@end smallexample 23877 23878 23879 23880@c 23881@c end of methods.dh 23882@c ------------------------------------- 23883@c ------------------------------------- 23884@c mixt.h 23885@c 23886 23887@page 23888@node MIXT 23889@subsection MIXT -- MIXTure of distributions 23890 23891 23892MIXT allows to sample from a mixture of univariate 23893distributions. 23894 23895Let 23896@iftex 23897@math{f_1,\ldots,f_n} 23898@end iftex 23899@ifhtml 23900@html 23901<I>f</I>_1,...,<I>f</I>_<I>n</I> 23902@end html 23903@end ifhtml 23904@ifinfo 23905@math{f_1,...,f_n} 23906@end ifinfo 23907be PDFs of various distributions 23908called the components and 23909@iftex 23910@math{(p_1,\ldots,p_n)} 23911@end iftex 23912@ifhtml 23913@html 23914(<I>p</I>_1,...,<I>p</I>_<I>n</I>) 23915@end html 23916@end ifhtml 23917@ifinfo 23918@math{(p_1,...,p_n)} 23919@end ifinfo 23920be a 23921probability vector. Then 23922@iftex 23923@math{f(x) = p_1\cdot f_1(x) + \ldots + p_n\cdot f_n(x)} 23924@end iftex 23925@ifhtml 23926@html 23927<I>f</I>(<I>x</I>) = <I>p</I>_1 * <I>f</I>_1(<I>x</I>) + ...+ <I>p</I>_<I>n</I> * <I>f</I>_<I>n</I>(<I>x</I>) 23928@end html 23929@end ifhtml 23930@ifinfo 23931@math{f(x) = p_1 * f_1(x) + ...+ p_n * f_n(x)} 23932@end ifinfo 23933is the PDF of the so called mixture of these distributions. 23934 23935Method MIXT takes generator objects for the components and 23936a probability vector and creates a generator object for 23937this mixture. 23938 23939The sampling part works as follows: 23940 23941@enumerate 23942@item 23943Generate an index @i{J} as the realisation of a discrete 23944random variate with the given probability vector. 23945This is done by means of method DGT 23946(@pxref{DGT,Guide Table method}). 23947@item 23948Generate a random variate @i{X} with PDF 23949@iftex 23950@math{f_J.} 23951@end iftex 23952@ifhtml 23953@html 23954<I>f</I>_<I>J</I>. 23955@end html 23956@end ifhtml 23957@ifinfo 23958@math{f_J.} 23959@end ifinfo 23960@end enumerate 23961 23962When the (interior of the) domains of the the components are 23963disjoint then it is possible to sample from the mixture by 23964inversion, provided that the following conditions are met: 23965 23966@itemize @minus 23967@item 23968The generator objects must use an inversion method for each 23969component. 23970@item 23971The domains of the PDFs 23972@iftex 23973@math{f_i} 23974@end iftex 23975@ifhtml 23976@html 23977<I>f</I>_<I>i</I> 23978@end html 23979@end ifhtml 23980@ifinfo 23981@math{f_i} 23982@end ifinfo 23983must not overlap. 23984@item 23985The components must be ordered with respect to their domains. 23986@end itemize 23987 23988 23989@subsubheading How To Use 23990 23991 23992Create generator objects for the components of the mixture and 23993store the corresponding pointers in an array. 23994Store all probabilities an a double array of the same size. 23995Create the parameter object for the generator of the mixture 23996distribution by means of 23997@ifhtml 23998@ref{funct:unur_mixt_new,@command{unur_mixt_new}.} 23999@end ifhtml 24000@ifnothtml 24001@command{unur_mixt_new}. 24002@end ifnothtml 24003The components of the mixture can be any continuous or discrete 24004univariate distributions. This also includes generators for 24005empirical distributions and mixtures of distributions. 24006In particular, mixtures can also be defined recursively. 24007 24008@emph{Remark:} 24009The components of the mixture can be continuous or discrete 24010distributions. The resulting mixture, however, is always a 24011continuous distribution and thus 24012@ifhtml 24013@ref{funct:unur_sample_cont,@command{unur_sample_cont}} 24014@end ifhtml 24015@ifnothtml 24016@command{unur_sample_cont} 24017@end ifnothtml 24018must be used! 24019 24020The inversion method can be switched on by means of 24021@ifhtml 24022@ref{funct:unur_mixt_set_useinversion,@command{unur_mixt_set_useinversion}} 24023@end ifhtml 24024@ifnothtml 24025@command{unur_mixt_set_useinversion} 24026@end ifnothtml 24027call. 24028However, the conditions for this method must then be met. 24029Otherwise, initialization of the mixture object fails. 24030 24031 24032 24033 24034@subheading Function reference 24035 24036@ifhtml 24037@itemize 24038@item @ref{funct:unur_mixt_new,unur_mixt_new} 24039@item @ref{funct:unur_mixt_set_useinversion,unur_mixt_set_useinversion} 24040@end itemize 24041@end ifhtml 24042 24043 24044@ifinfo 24045@anchor{funct:unur_mixt_new} 24046@deftypefn Function {UNUR_PAR*} unur_mixt_new (int @var{n}, const @var{double* prob}, UNUR_GEN** @var{comp}) 24047Get default parameters for the generator for a mixture of the 24048distributions given in the array @var{comp} (components) of length 24049@var{n}. The probabilities are given by @var{prob}. 24050 24051The generators in @var{comp} must be objects for (continuous or 24052discrete) univariate distributions 24053@end deftypefn 24054@end ifinfo 24055@ifnotinfo 24056@anchor{funct:unur_mixt_new} 24057@deftypefn {} {UNUR_PAR*} unur_mixt_new (int @var{n}, const @var{double* prob}, UNUR_GEN** @var{comp}) 24058Get default parameters for the generator for a mixture of the 24059distributions given in the array @var{comp} (components) of length 24060@var{n}. The probabilities are given by @var{prob}. 24061 24062The generators in @var{comp} must be objects for (continuous or 24063discrete) univariate distributions 24064@end deftypefn 24065@end ifnotinfo 24066 24067@ifinfo 24068@anchor{funct:unur_mixt_set_useinversion} 24069@deftypefn Function {int} unur_mixt_set_useinversion (UNUR_PAR* @var{parameters}, int @var{useinv}) 24070If @var{useinv} is @code{TRUE}, then the inversion method is used for 24071sampling from the mixture distribution. 24072 24073However, the following conditions must be satisfied: 24074 24075@itemize @minus 24076@item 24077The generator objects must use an inversion method for each 24078component. 24079@item 24080The domains of the components must not overlap. 24081@item 24082The components must be ordered with respect to their domains. 24083@end itemize 24084 24085If one of these conditions is violated, then initialization of the 24086mixture object fails. 24087 24088Default is @code{FALSE}. 24089@end deftypefn 24090@end ifinfo 24091@ifnotinfo 24092@anchor{funct:unur_mixt_set_useinversion} 24093@deftypefn {} {int} unur_mixt_set_useinversion (UNUR_PAR* @var{parameters}, int @var{useinv}) 24094If @var{useinv} is @code{TRUE}, then the inversion method is used for 24095sampling from the mixture distribution. 24096 24097However, the following conditions must be satisfied: 24098 24099@itemize @minus 24100@item 24101The generator objects must use an inversion method for each 24102component. 24103@item 24104The domains of the components must not overlap. 24105@item 24106The components must be ordered with respect to their domains. 24107@end itemize 24108 24109If one of these conditions is violated, then initialization of the 24110mixture object fails. 24111 24112Default is @code{FALSE}. 24113@end deftypefn 24114@end ifnotinfo 24115 24116 24117 24118 24119@c 24120@c end of mixt.h 24121@c ------------------------------------- 24122@c ------------------------------------- 24123@c urng.h 24124@c 24125 24126@node URNG 24127@chapter Using uniform random number generators 24128 24129@menu 24130* URNG-FVOID:: Simple interface for uniform random number generators 24131* URNG-GSL:: Interface to GSL uniform random number generators 24132* URNG-GSLQRNG:: Interface to GSL generators for quasi-random points 24133* URNG-PRNG:: Interface to Otmar Lendl's pseudo-random number generators 24134* URNG-RNGSTREAM:: Interface to L'Ecuyer's RNGSTREAM random number generators 24135* URNG-RANDOMSHIFT:: Combine point set generator with random shifts 24136@end menu 24137 24138 24139UNU.RAN is designed to work with many sources of (pseudo-) random 24140numbers or low discrepancy numbers (so called quasi-random 24141numbers) for almost all tasks in discrete event simulation, 24142(quasi-) Monte Carlo integration or any other stochastic 24143methods. Hence UNU.RAN uses pointers to access uniform (pseudo-) 24144random number generators (URNG). 24145 24146Each UNU.RAN (non-uniform random variate) generator object has a 24147pointer to a URNG object. Thus each UNU.RAN generator object may 24148have its own (independent) URNG or several generator objects can 24149share the same URNG. 24150 24151If no URNG is provided for a parameter or generator object a default 24152generator is used which is the same for all generators. This URNG is 24153defined in @file{unuran_config.h} at compile time and can be 24154changed at runtime. 24155 24156UNU.RAN uses a unified interface for all sources of random numbers. 24157Unfortunately, the API for random number generators, like the 24158@file{GSL} (GNU Scientific Library), Otmar Lendl's @file{prng} 24159(Pseudo random number generators), or a single function 24160implemented by the user herself, are quite different. 24161Hence an object of type @code{UNUR_URNG} is introduced to store 24162the URNG. Thus it is possible to handle different sources of 24163such URNGs with the unified API. It is inspired from similar to 24164Pierre L'Ecuyers @file{RngStreams} library: 24165 24166@itemize @minus 24167@item seed the random number generator; 24168@item get a uniform random number; 24169@item reset the URNG; 24170@item skip to the begining next substream; 24171@item sample antithetic numbers; 24172@item delete the URNG object. 24173@end itemize 24174 24175The routine to create a URNG depends on the chosen random number 24176generator (i.e. library). Nevertheless, there exist wrapper 24177functions to simplify this task. 24178 24179Currently the following sources of uniform random numbers are 24180directly supported (i.e., there exist wrapper functions). 24181Of course other random number generation libraries can be used. 24182 24183@enumerate 24184 24185@item 24186@code{FVOID} 24187 24188URNGs of type @code{double uniform(void *state)}. 24189The argument @var{state} can be simply ignored in the 24190implementation of @code{uniform} when a global state variable is 24191used. 24192UNU.RAN contains some build-in URNGs of this type in directory 24193@file{src/uniform/}. 24194 24195@item 24196@code{PRNG} 24197 24198URNGs from Otmar Lendl's @code{prng} library. It provides a very 24199flexible way to sample form arbitrary URNGs by means of an object 24200oriented programing paradigma. Similarly to the UNU.RAN library 24201independent generator objects can be build and used. 24202 24203This library has been developed by the pLab group at the university 24204of Salzburg (Austria, EU) and implemented by Otmar Lendl. 24205It is available from 24206@uref{http://statmath.wu.ac.at/prng/} 24207or from the pLab site at 24208@uref{http://random.mat.sbg.ac.at/}. 24209 24210This interface must be compiled into UNU.RAN using the 24211configure flag @code{--with-urng-prng}. 24212 24213@item 24214@code{RNGSTREAM} 24215 24216Pierre L'Ecuyer's @code{RngStream} library for multiple 24217independent streams of pseudo-random numbers. 24218A GNU-style package is available from 24219@uref{http://statmath.wu.ac.at/software/RngStreams/}. 24220 24221This interface must be compiled into UNU.RAN using the 24222configure flag @code{--with-urng-rngstream}. 24223 24224@item 24225@code{GSL} 24226 24227URNG from the GNU Scientific Library (GSL). 24228It is available from 24229@uref{http://www.gnu.org/software/gsl/}. 24230 24231This interface must be compiled into UNU.RAN using the 24232configure flag @code{--with-urng-gsl}. 24233 24234@end enumerate 24235 24236 24237@subsubheading How To Use 24238 24239 24240Each UNU.RAN generator object has a pointer to a uniform 24241(pseudo-) random number generator (URNG). It can be set via the 24242@ifhtml 24243@ref{funct:unur_set_urng,@command{unur_set_urng}} 24244@end ifhtml 24245@ifnothtml 24246@command{unur_set_urng} 24247@end ifnothtml 24248call. It is also possible to read this pointer 24249via 24250@ifhtml 24251@ref{funct:unur_get_urng,@command{unur_get_urng}} 24252@end ifhtml 24253@ifnothtml 24254@command{unur_get_urng} 24255@end ifnothtml 24256or change the URNG for an existing generator 24257object by means of 24258@ifhtml 24259@ref{funct:unur_chg_urng,@command{unur_chg_urng}.} 24260@end ifhtml 24261@ifnothtml 24262@command{unur_chg_urng}. 24263@end ifnothtml 24264It is important to note that these calls only copy the pointer 24265to the URNG object into the generator object. 24266 24267If no URNG is provided for a parameter or generator object a default 24268URNG is used which is the same for all generators. This URNG is 24269defined in @file{unuran_config.h} at compile time. A pointer to 24270this default URNG can be obtained via 24271@ifhtml 24272@ref{funct:unur_get_default_urng,@command{unur_get_default_urng}.} 24273@end ifhtml 24274@ifnothtml 24275@command{unur_get_default_urng}. 24276@end ifnothtml 24277Nevertheless, it is also possible to change this default URNG by 24278another one at runtime by means of the 24279@ifhtml 24280@ref{funct:unur_set_default_urng,@command{unur_set_default_urng}} 24281@end ifhtml 24282@ifnothtml 24283@command{unur_set_default_urng} 24284@end ifnothtml 24285call. However, this only takes effect for new parameter objects. 24286 24287Some generating methods provide the possibility of correlation 24288induction. For this feature a second auxiliary URNG is required. 24289It can be set and changed by 24290@ifhtml 24291@ref{funct:unur_set_urng_aux,@command{unur_set_urng_aux}} 24292@end ifhtml 24293@ifnothtml 24294@command{unur_set_urng_aux} 24295@end ifnothtml 24296and 24297@ifhtml 24298@ref{funct:unur_chg_urng_aux,@command{unur_chg_urng_aux}} 24299@end ifhtml 24300@ifnothtml 24301@command{unur_chg_urng_aux} 24302@end ifnothtml 24303calls, respectively. Since the auxiliary 24304URNG is by default the same as the main URNG, the 24305auxiliary URNG must be set after any 24306@ifhtml 24307@ref{funct:unur_set_urng,@command{unur_set_urng}} 24308@end ifhtml 24309@ifnothtml 24310@command{unur_set_urng} 24311@end ifnothtml 24312or 24313@ifhtml 24314@ref{funct:unur_chg_urng,@command{unur_chg_urng}} 24315@end ifhtml 24316@ifnothtml 24317@command{unur_chg_urng} 24318@end ifnothtml 24319call! Since in special cases mixing of two URNG 24320might cause problems, we supply a default auxiliary generator 24321that can be used by a 24322@ifhtml 24323@ref{funct:unur_use_urng_aux_default,@command{unur_use_urng_aux_default}} 24324@end ifhtml 24325@ifnothtml 24326@command{unur_use_urng_aux_default} 24327@end ifnothtml 24328call (after 24329the main URNG has been set). This default auxiliary generator 24330can be changed with analogous calls as the (main) default 24331uniform generator. 24332 24333Uniform random number generators form different sources have 24334different programming interfaces. Thus UNU.RAN stores all 24335information about a particular uniform random number generator 24336in a structure of type @code{UNUR_URNG}. Before a URNG can be 24337used with UNU.RAN an appropriate object has to be created ba a 24338@ifhtml 24339@ref{funct:unur_urng_new,@command{unur_urng_new}} 24340@end ifhtml 24341@ifnothtml 24342@command{unur_urng_new} 24343@end ifnothtml 24344call. 24345This call takes two arguments: the pointer to the sampling 24346routine of the generator and a pointer to a possible argument 24347that stores the state of the generator. The function must be of 24348type @code{double (*sampleunif)(void *params)}, but functions 24349without any argument also work. 24350Additionally one can set pointers to functions for reseting or 24351jumping the streams generated by the URNG by the corresponding 24352@code{set} calls. 24353 24354UNU.RAN provides a unified API to all sources of random numbers. 24355Notice, however, that not all functions work for all random 24356number generators (as the respective library has not implemented 24357the corresponding feature). 24358 24359There are wrapper functions for some libraries of uniform random 24360number generators to simplify the task of creating a UNU.RAN 24361object for URNGs. 24362These functions must be compiled into UNU.RAN using the 24363corresponding configure flags (see description of the respective 24364interface below). 24365 24366 24367 24368 24369@subheading Function reference 24370 24371@ifhtml 24372@itemize 24373@item @ref{funct:unur_get_default_urng,unur_get_default_urng} 24374@item @ref{funct:unur_set_default_urng,unur_set_default_urng} 24375@item @ref{funct:unur_set_default_urng_aux,unur_set_default_urng_aux} 24376@item @ref{funct:unur_get_default_urng_aux,unur_get_default_urng_aux} 24377@item @ref{funct:unur_set_urng,unur_set_urng} 24378@item @ref{funct:unur_chg_urng,unur_chg_urng} 24379@item @ref{funct:unur_get_urng,unur_get_urng} 24380@item @ref{funct:unur_set_urng_aux,unur_set_urng_aux} 24381@item @ref{funct:unur_use_urng_aux_default,unur_use_urng_aux_default} 24382@item @ref{funct:unur_chgto_urng_aux_default,unur_chgto_urng_aux_default} 24383@item @ref{funct:unur_chg_urng_aux,unur_chg_urng_aux} 24384@item @ref{funct:unur_get_urng_aux,unur_get_urng_aux} 24385@item @ref{funct:unur_urng_sample,unur_urng_sample} 24386@item @ref{funct:unur_sample_urng,unur_sample_urng} 24387@item @ref{funct:unur_urng_sample_array,unur_urng_sample_array} 24388@item @ref{funct:unur_urng_reset,unur_urng_reset} 24389@item @ref{funct:unur_urng_sync,unur_urng_sync} 24390@item @ref{funct:unur_urng_seed,unur_urng_seed} 24391@item @ref{funct:unur_urng_anti,unur_urng_anti} 24392@item @ref{funct:unur_urng_nextsub,unur_urng_nextsub} 24393@item @ref{funct:unur_urng_resetsub,unur_urng_resetsub} 24394@item @ref{funct:unur_gen_sync,unur_gen_sync} 24395@item @ref{funct:unur_gen_seed,unur_gen_seed} 24396@item @ref{funct:unur_gen_anti,unur_gen_anti} 24397@item @ref{funct:unur_gen_reset,unur_gen_reset} 24398@item @ref{funct:unur_gen_nextsub,unur_gen_nextsub} 24399@item @ref{funct:unur_gen_resetsub,unur_gen_resetsub} 24400@item @ref{funct:unur_urng_new,unur_urng_new} 24401@item @ref{funct:unur_urng_free,unur_urng_free} 24402@item @ref{funct:unur_urng_set_sample_array,unur_urng_set_sample_array} 24403@item @ref{funct:unur_urng_set_sync,unur_urng_set_sync} 24404@item @ref{funct:unur_urng_set_seed,unur_urng_set_seed} 24405@item @ref{funct:unur_urng_set_anti,unur_urng_set_anti} 24406@item @ref{funct:unur_urng_set_reset,unur_urng_set_reset} 24407@item @ref{funct:unur_urng_set_nextsub,unur_urng_set_nextsub} 24408@item @ref{funct:unur_urng_set_resetsub,unur_urng_set_resetsub} 24409@item @ref{funct:unur_urng_set_delete,unur_urng_set_delete} 24410@end itemize 24411@end ifhtml 24412 24413 24414@subheading Set and get default uniform RNGs 24415 24416@ifinfo 24417@anchor{funct:unur_get_default_urng} 24418@deftypefn Function {UNUR_URNG*} unur_get_default_urng (void) 24419Get the pointer to the default URNG. The default URNG is used by all 24420generators where no URNG was set explicitly by a 24421@ifhtml 24422@ref{funct:unur_set_urng,@command{unur_set_urng}} 24423@end ifhtml 24424@ifnothtml 24425@command{unur_set_urng} 24426@end ifnothtml 24427call. 24428@end deftypefn 24429@end ifinfo 24430@ifnotinfo 24431@anchor{funct:unur_get_default_urng} 24432@deftypefn {} {UNUR_URNG*} unur_get_default_urng (void) 24433Get the pointer to the default URNG. The default URNG is used by all 24434generators where no URNG was set explicitly by a 24435@ifhtml 24436@ref{funct:unur_set_urng,@command{unur_set_urng}} 24437@end ifhtml 24438@ifnothtml 24439@command{unur_set_urng} 24440@end ifnothtml 24441call. 24442@end deftypefn 24443@end ifnotinfo 24444 24445@ifinfo 24446@anchor{funct:unur_set_default_urng} 24447@deftypefn Function {UNUR_URNG*} unur_set_default_urng (UNUR_URNG* @var{urng_new}) 24448Change the default URNG that is used for new parameter objects. 24449It returns the pointer to the old default URNG that has been used. 24450@end deftypefn 24451@end ifinfo 24452@ifnotinfo 24453@anchor{funct:unur_set_default_urng} 24454@deftypefn {} {UNUR_URNG*} unur_set_default_urng (UNUR_URNG* @var{urng_new}) 24455Change the default URNG that is used for new parameter objects. 24456It returns the pointer to the old default URNG that has been used. 24457@end deftypefn 24458@end ifnotinfo 24459 24460@ifinfo 24461@anchor{funct:unur_set_default_urng_aux} 24462@deftypefn Function {UNUR_URNG*} unur_set_default_urng_aux (UNUR_URNG* @var{urng_new}) 24463@anchor{funct:unur_get_default_urng_aux} 24464@deftypefnx Function {UNUR_URNG*} unur_get_default_urng_aux (void) 24465Analogous calls for default auxiliary generator. 24466@end deftypefn 24467@end ifinfo 24468@ifnotinfo 24469@anchor{funct:unur_set_default_urng_aux} 24470@deftypefn {} {UNUR_URNG*} unur_set_default_urng_aux (UNUR_URNG* @var{urng_new}) 24471@anchor{funct:unur_get_default_urng_aux} 24472@deftypefnx {} {UNUR_URNG*} unur_get_default_urng_aux (void) 24473Analogous calls for default auxiliary generator. 24474@end deftypefn 24475@end ifnotinfo 24476 24477@subheading Set, change and get uniform RNGs in generator objects 24478 24479@ifinfo 24480@anchor{funct:unur_set_urng} 24481@deftypefn Function {int} unur_set_urng (UNUR_PAR* @var{parameters}, UNUR_URNG* @var{urng}) 24482Use the URNG @code{urng} for the new generator. This overrides the 24483default URNG. It also sets the auxiliary URNG to @code{urng}. 24484 24485@emph{Important}: For multivariate distributions that use 24486marginal distributions this call does not work properly. 24487It is then better first to create the generator object (by 24488a 24489@ifhtml 24490@ref{funct:unur_init,@command{unur_init}} 24491@end ifhtml 24492@ifnothtml 24493@command{unur_init} 24494@end ifnothtml 24495call) and then change the URNG by means of 24496@ifhtml 24497@ref{funct:unur_chg_urng,@command{unur_chg_urng}.} 24498@end ifhtml 24499@ifnothtml 24500@command{unur_chg_urng}. 24501@end ifnothtml 24502@end deftypefn 24503@end ifinfo 24504@ifnotinfo 24505@anchor{funct:unur_set_urng} 24506@deftypefn {} {int} unur_set_urng (UNUR_PAR* @var{parameters}, UNUR_URNG* @var{urng}) 24507Use the URNG @code{urng} for the new generator. This overrides the 24508default URNG. It also sets the auxiliary URNG to @code{urng}. 24509 24510@emph{Important}: For multivariate distributions that use 24511marginal distributions this call does not work properly. 24512It is then better first to create the generator object (by 24513a 24514@ifhtml 24515@ref{funct:unur_init,@command{unur_init}} 24516@end ifhtml 24517@ifnothtml 24518@command{unur_init} 24519@end ifnothtml 24520call) and then change the URNG by means of 24521@ifhtml 24522@ref{funct:unur_chg_urng,@command{unur_chg_urng}.} 24523@end ifhtml 24524@ifnothtml 24525@command{unur_chg_urng}. 24526@end ifnothtml 24527@end deftypefn 24528@end ifnotinfo 24529 24530@ifinfo 24531@anchor{funct:unur_chg_urng} 24532@deftypefn Function {UNUR_URNG*} unur_chg_urng (UNUR_GEN* @var{generator}, UNUR_URNG* @var{urng}) 24533Change the URNG for the given generator. It returns the pointer to 24534the old URNG that has been used by the generator. 24535It also changes the auxiliary URNG to @code{urng} and thus it 24536overrides the last 24537@ifhtml 24538@ref{funct:unur_chg_urng_aux,@command{unur_chg_urng_aux}} 24539@end ifhtml 24540@ifnothtml 24541@command{unur_chg_urng_aux} 24542@end ifnothtml 24543call. 24544@end deftypefn 24545@end ifinfo 24546@ifnotinfo 24547@anchor{funct:unur_chg_urng} 24548@deftypefn {} {UNUR_URNG*} unur_chg_urng (UNUR_GEN* @var{generator}, UNUR_URNG* @var{urng}) 24549Change the URNG for the given generator. It returns the pointer to 24550the old URNG that has been used by the generator. 24551It also changes the auxiliary URNG to @code{urng} and thus it 24552overrides the last 24553@ifhtml 24554@ref{funct:unur_chg_urng_aux,@command{unur_chg_urng_aux}} 24555@end ifhtml 24556@ifnothtml 24557@command{unur_chg_urng_aux} 24558@end ifnothtml 24559call. 24560@end deftypefn 24561@end ifnotinfo 24562 24563@ifinfo 24564@anchor{funct:unur_get_urng} 24565@deftypefn Function {UNUR_URNG*} unur_get_urng (UNUR_GEN* @var{generator}) 24566Get the pointer to the URNG that is used by the @var{generator}. 24567This is usefull if two generators should share the same URNG. 24568@end deftypefn 24569@end ifinfo 24570@ifnotinfo 24571@anchor{funct:unur_get_urng} 24572@deftypefn {} {UNUR_URNG*} unur_get_urng (UNUR_GEN* @var{generator}) 24573Get the pointer to the URNG that is used by the @var{generator}. 24574This is usefull if two generators should share the same URNG. 24575@end deftypefn 24576@end ifnotinfo 24577 24578@ifinfo 24579@anchor{funct:unur_set_urng_aux} 24580@deftypefn Function {int} unur_set_urng_aux (UNUR_PAR* @var{parameters}, UNUR_URNG* @var{urng_aux}) 24581Use the auxiliary URNG @code{urng_aux} for the new generator. 24582(Default is the default URNG or the URNG from the last 24583@ifhtml 24584@ref{funct:unur_set_urng,@command{unur_set_urng}} 24585@end ifhtml 24586@ifnothtml 24587@command{unur_set_urng} 24588@end ifnothtml 24589call. Thus if the auxiliary generator should be 24590different to the main URNG, 24591@ifhtml 24592@ref{funct:unur_set_urng_aux,@command{unur_set_urng_aux}} 24593@end ifhtml 24594@ifnothtml 24595@command{unur_set_urng_aux} 24596@end ifnothtml 24597must be called after 24598@ifhtml 24599@ref{funct:unur_set_urng,@command{unur_set_urng}.} 24600@end ifhtml 24601@ifnothtml 24602@command{unur_set_urng}. 24603@end ifnothtml 24604The auxiliary URNG is used as second stream of uniform random 24605number for correlation induction. 24606It is not possible to set an auxiliary URNG for a method that does 24607not need one. In this case an error code is returned. 24608@end deftypefn 24609@end ifinfo 24610@ifnotinfo 24611@anchor{funct:unur_set_urng_aux} 24612@deftypefn {} {int} unur_set_urng_aux (UNUR_PAR* @var{parameters}, UNUR_URNG* @var{urng_aux}) 24613Use the auxiliary URNG @code{urng_aux} for the new generator. 24614(Default is the default URNG or the URNG from the last 24615@ifhtml 24616@ref{funct:unur_set_urng,@command{unur_set_urng}} 24617@end ifhtml 24618@ifnothtml 24619@command{unur_set_urng} 24620@end ifnothtml 24621call. Thus if the auxiliary generator should be 24622different to the main URNG, 24623@ifhtml 24624@ref{funct:unur_set_urng_aux,@command{unur_set_urng_aux}} 24625@end ifhtml 24626@ifnothtml 24627@command{unur_set_urng_aux} 24628@end ifnothtml 24629must be called after 24630@ifhtml 24631@ref{funct:unur_set_urng,@command{unur_set_urng}.} 24632@end ifhtml 24633@ifnothtml 24634@command{unur_set_urng}. 24635@end ifnothtml 24636The auxiliary URNG is used as second stream of uniform random 24637number for correlation induction. 24638It is not possible to set an auxiliary URNG for a method that does 24639not need one. In this case an error code is returned. 24640@end deftypefn 24641@end ifnotinfo 24642 24643@ifinfo 24644@anchor{funct:unur_use_urng_aux_default} 24645@deftypefn Function {int} unur_use_urng_aux_default (UNUR_PAR* @var{parameters}) 24646Use the default auxiliary URNG. 24647(It must be set after 24648@ifhtml 24649@ref{funct:unur_get_urng,@command{unur_get_urng}.} 24650@end ifhtml 24651@ifnothtml 24652@command{unur_get_urng}. 24653@end ifnothtml 24654) 24655It is not possible to set an auxiliary URNG for a method that does 24656not use one (i.e. the call returns an error code). 24657@end deftypefn 24658@end ifinfo 24659@ifnotinfo 24660@anchor{funct:unur_use_urng_aux_default} 24661@deftypefn {} {int} unur_use_urng_aux_default (UNUR_PAR* @var{parameters}) 24662Use the default auxiliary URNG. 24663(It must be set after 24664@ifhtml 24665@ref{funct:unur_get_urng,@command{unur_get_urng}.} 24666@end ifhtml 24667@ifnothtml 24668@command{unur_get_urng}. 24669@end ifnothtml 24670) 24671It is not possible to set an auxiliary URNG for a method that does 24672not use one (i.e. the call returns an error code). 24673@end deftypefn 24674@end ifnotinfo 24675 24676@ifinfo 24677@anchor{funct:unur_chgto_urng_aux_default} 24678@deftypefn Function {int} unur_chgto_urng_aux_default (UNUR_GEN* @var{generator}) 24679Switch to default auxiliary URNG. 24680(It must be set after 24681@ifhtml 24682@ref{funct:unur_get_urng,@command{unur_get_urng}.} 24683@end ifhtml 24684@ifnothtml 24685@command{unur_get_urng}. 24686@end ifnothtml 24687) 24688It is not possible to set an auxiliary URNG for a method that does 24689not use one (i.e. the call returns an error code). 24690@end deftypefn 24691@end ifinfo 24692@ifnotinfo 24693@anchor{funct:unur_chgto_urng_aux_default} 24694@deftypefn {} {int} unur_chgto_urng_aux_default (UNUR_GEN* @var{generator}) 24695Switch to default auxiliary URNG. 24696(It must be set after 24697@ifhtml 24698@ref{funct:unur_get_urng,@command{unur_get_urng}.} 24699@end ifhtml 24700@ifnothtml 24701@command{unur_get_urng}. 24702@end ifnothtml 24703) 24704It is not possible to set an auxiliary URNG for a method that does 24705not use one (i.e. the call returns an error code). 24706@end deftypefn 24707@end ifnotinfo 24708 24709@ifinfo 24710@anchor{funct:unur_chg_urng_aux} 24711@deftypefn Function {UNUR_URNG*} unur_chg_urng_aux (UNUR_GEN* @var{generator}, UNUR_URNG* @var{urng_aux}) 24712Change the auxiliary URNG for the given @var{generator}. It returns 24713the pointer to the old auxiliary URNG that has been used by the 24714generator. It has to be called after each 24715@ifhtml 24716@ref{funct:unur_chg_urng,@command{unur_chg_urng}} 24717@end ifhtml 24718@ifnothtml 24719@command{unur_chg_urng} 24720@end ifnothtml 24721when the 24722auxiliary URNG should be different from the main URNG. 24723It is not possible to change the auxiliary URNG for a method that 24724does not use one (i.e. the call @code{NULL}). 24725@end deftypefn 24726@end ifinfo 24727@ifnotinfo 24728@anchor{funct:unur_chg_urng_aux} 24729@deftypefn {} {UNUR_URNG*} unur_chg_urng_aux (UNUR_GEN* @var{generator}, UNUR_URNG* @var{urng_aux}) 24730Change the auxiliary URNG for the given @var{generator}. It returns 24731the pointer to the old auxiliary URNG that has been used by the 24732generator. It has to be called after each 24733@ifhtml 24734@ref{funct:unur_chg_urng,@command{unur_chg_urng}} 24735@end ifhtml 24736@ifnothtml 24737@command{unur_chg_urng} 24738@end ifnothtml 24739when the 24740auxiliary URNG should be different from the main URNG. 24741It is not possible to change the auxiliary URNG for a method that 24742does not use one (i.e. the call @code{NULL}). 24743@end deftypefn 24744@end ifnotinfo 24745 24746@ifinfo 24747@anchor{funct:unur_get_urng_aux} 24748@deftypefn Function {UNUR_URNG*} unur_get_urng_aux (UNUR_GEN* @var{generator}) 24749Get the pointer to the auxiliary URNG that is used by the 24750@var{generator}. This is usefull if two generators should share the same 24751URNG. 24752@end deftypefn 24753@end ifinfo 24754@ifnotinfo 24755@anchor{funct:unur_get_urng_aux} 24756@deftypefn {} {UNUR_URNG*} unur_get_urng_aux (UNUR_GEN* @var{generator}) 24757Get the pointer to the auxiliary URNG that is used by the 24758@var{generator}. This is usefull if two generators should share the same 24759URNG. 24760@end deftypefn 24761@end ifnotinfo 24762 24763@subheading Handle uniform RNGs 24764 24765@emph{Notice:} Some of the below function calls do not work for 24766every source of random numbers since not every library has 24767implemented these features. 24768 24769@ifinfo 24770@anchor{funct:unur_urng_sample} 24771@deftypefn Function {double} unur_urng_sample (UNUR_URNG* @var{urng}) 24772Get a uniform random number from @var{urng}. 24773If the @code{NULL} pointer is given, the default uniform generator is 24774used. 24775@end deftypefn 24776@end ifinfo 24777@ifnotinfo 24778@anchor{funct:unur_urng_sample} 24779@deftypefn {} {double} unur_urng_sample (UNUR_URNG* @var{urng}) 24780Get a uniform random number from @var{urng}. 24781If the @code{NULL} pointer is given, the default uniform generator is 24782used. 24783@end deftypefn 24784@end ifnotinfo 24785 24786@ifinfo 24787@anchor{funct:unur_sample_urng} 24788@deftypefn Function {double} unur_sample_urng (UNUR_GEN* @var{gen}) 24789Get a uniform random number from the underlying uniform 24790random number generator of generator @var{gen}. 24791If the @code{NULL} pointer is given, the default uniform generator is 24792used. 24793@end deftypefn 24794@end ifinfo 24795@ifnotinfo 24796@anchor{funct:unur_sample_urng} 24797@deftypefn {} {double} unur_sample_urng (UNUR_GEN* @var{gen}) 24798Get a uniform random number from the underlying uniform 24799random number generator of generator @var{gen}. 24800If the @code{NULL} pointer is given, the default uniform generator is 24801used. 24802@end deftypefn 24803@end ifnotinfo 24804 24805@ifinfo 24806@anchor{funct:unur_urng_sample_array} 24807@deftypefn Function {int} unur_urng_sample_array (UNUR_URNG* @var{urng}, double* @var{X}, int @var{dim}) 24808Set array @var{X} of length @var{dim} with uniform random numbers 24809sampled from generator @var{urng}. If @var{urng} is the @code{NULL} 24810pointer, the default uniform generator is used. 24811 24812@emph{Important:} 24813If @var{urng} is based on a point set generator (this is the case 24814for generators of low discrepance point sets as used in quasi-Monte 24815Carlo methods) it has a ``natural dimension'' @i{s}. 24816In this case either only the first @i{s} entries of @var{X} are 24817filled (if @i{s} < @var{dim}), or the first @var{dim} coordinates 24818of the generated point are filled. 24819 24820The called returns the actual number of entries filled. In case of 24821an error @code{0} is returned. 24822@end deftypefn 24823@end ifinfo 24824@ifnotinfo 24825@anchor{funct:unur_urng_sample_array} 24826@deftypefn {} {int} unur_urng_sample_array (UNUR_URNG* @var{urng}, double* @var{X}, int @var{dim}) 24827Set array @var{X} of length @var{dim} with uniform random numbers 24828sampled from generator @var{urng}. If @var{urng} is the @code{NULL} 24829pointer, the default uniform generator is used. 24830 24831@emph{Important:} 24832If @var{urng} is based on a point set generator (this is the case 24833for generators of low discrepance point sets as used in quasi-Monte 24834Carlo methods) it has a ``natural dimension'' @i{s}. 24835In this case either only the first @i{s} entries of @var{X} are 24836filled (if @i{s} < @var{dim}), or the first @var{dim} coordinates 24837of the generated point are filled. 24838 24839The called returns the actual number of entries filled. In case of 24840an error @code{0} is returned. 24841@end deftypefn 24842@end ifnotinfo 24843 24844@ifinfo 24845@anchor{funct:unur_urng_reset} 24846@deftypefn Function {int} unur_urng_reset (UNUR_URNG* @var{urng}) 24847Reset @var{urng} object. 24848The routine tries two ways to reset the generator (in this order): 24849 24850@enumerate 24851@item 24852It uses the reset function given by an 24853@ifhtml 24854@ref{funct:unur_urng_set_reset,@command{unur_urng_set_reset}} 24855@end ifhtml 24856@ifnothtml 24857@command{unur_urng_set_reset} 24858@end ifnothtml 24859call. 24860 24861@item 24862It uses the seed given by the last 24863@ifhtml 24864@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 24865@end ifhtml 24866@ifnothtml 24867@command{unur_urng_seed} 24868@end ifnothtml 24869call (which 24870requires a seeding function given by a 24871@ifhtml 24872@ref{funct:unur_urng_set_seed,@command{unur_urng_set_seed}} 24873@end ifhtml 24874@ifnothtml 24875@command{unur_urng_set_seed} 24876@end ifnothtml 24877call). 24878@end enumerate 24879 24880If neither of the two methods work resetting of the generator is 24881not possible and an error code is returned. 24882 24883If the @code{NULL} pointer is given, the default uniform generator is 24884reset. 24885@end deftypefn 24886@end ifinfo 24887@ifnotinfo 24888@anchor{funct:unur_urng_reset} 24889@deftypefn {} {int} unur_urng_reset (UNUR_URNG* @var{urng}) 24890Reset @var{urng} object. 24891The routine tries two ways to reset the generator (in this order): 24892 24893@enumerate 24894@item 24895It uses the reset function given by an 24896@ifhtml 24897@ref{funct:unur_urng_set_reset,@command{unur_urng_set_reset}} 24898@end ifhtml 24899@ifnothtml 24900@command{unur_urng_set_reset} 24901@end ifnothtml 24902call. 24903 24904@item 24905It uses the seed given by the last 24906@ifhtml 24907@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 24908@end ifhtml 24909@ifnothtml 24910@command{unur_urng_seed} 24911@end ifnothtml 24912call (which 24913requires a seeding function given by a 24914@ifhtml 24915@ref{funct:unur_urng_set_seed,@command{unur_urng_set_seed}} 24916@end ifhtml 24917@ifnothtml 24918@command{unur_urng_set_seed} 24919@end ifnothtml 24920call). 24921@end enumerate 24922 24923If neither of the two methods work resetting of the generator is 24924not possible and an error code is returned. 24925 24926If the @code{NULL} pointer is given, the default uniform generator is 24927reset. 24928@end deftypefn 24929@end ifnotinfo 24930 24931@ifinfo 24932@anchor{funct:unur_urng_sync} 24933@deftypefn Function {int} unur_urng_sync (UNUR_URNG* @var{urng}) 24934Jump into defined state ("sync") of the generator. This is useful 24935when point generators are used where the coordinates are 24936sampled via 24937@ifhtml 24938@ref{funct:unur_urng_sample,@command{unur_urng_sample}.} 24939@end ifhtml 24940@ifnothtml 24941@command{unur_urng_sample}. 24942@end ifnothtml 24943Then this call can be used to 24944jump to the first coordinate of the next generated point. 24945@end deftypefn 24946@end ifinfo 24947@ifnotinfo 24948@anchor{funct:unur_urng_sync} 24949@deftypefn {} {int} unur_urng_sync (UNUR_URNG* @var{urng}) 24950Jump into defined state ("sync") of the generator. This is useful 24951when point generators are used where the coordinates are 24952sampled via 24953@ifhtml 24954@ref{funct:unur_urng_sample,@command{unur_urng_sample}.} 24955@end ifhtml 24956@ifnothtml 24957@command{unur_urng_sample}. 24958@end ifnothtml 24959Then this call can be used to 24960jump to the first coordinate of the next generated point. 24961@end deftypefn 24962@end ifnotinfo 24963 24964@ifinfo 24965@anchor{funct:unur_urng_seed} 24966@deftypefn Function {int} unur_urng_seed (UNUR_URNG* @var{urng}, unsigned @var{long seed}) 24967Set @var{seed} for generator @var{urng}. 24968It returns an error code if this is not possible for the given 24969URNG. If the @code{NULL} pointer is given, the default uniform generator is 24970seeded (if possible). 24971 24972@emph{Notice}: Seeding should be done only once for a particular 24973generator (except for resetting it to the initial state). 24974Expertise is required when multiple seeds are used to get independent 24975streams. Thus we recommend appropriate libraries for this task, 24976e.g. Pierre L'Ecuyer's @file{RngStreams} package. For this library 24977only a package seed can be set and thus the 24978@ifhtml 24979@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 24980@end ifhtml 24981@ifnothtml 24982@command{unur_urng_seed} 24983@end ifnothtml 24984call 24985will not have any effect to generators of this type. Use 24986@ifhtml 24987@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 24988@end ifhtml 24989@ifnothtml 24990@command{unur_urng_reset} 24991@end ifnothtml 24992or 24993@ifhtml 24994@ref{funct:unur_urng_rngstream_new,@command{unur_urng_rngstream_new}} 24995@end ifhtml 24996@ifnothtml 24997@command{unur_urng_rngstream_new} 24998@end ifnothtml 24999instead, depending 25000whether one wants to reset the stream or get a new stream that is 25001independent from the previous ones. 25002@end deftypefn 25003@end ifinfo 25004@ifnotinfo 25005@anchor{funct:unur_urng_seed} 25006@deftypefn {} {int} unur_urng_seed (UNUR_URNG* @var{urng}, unsigned @var{long seed}) 25007Set @var{seed} for generator @var{urng}. 25008It returns an error code if this is not possible for the given 25009URNG. If the @code{NULL} pointer is given, the default uniform generator is 25010seeded (if possible). 25011 25012@emph{Notice}: Seeding should be done only once for a particular 25013generator (except for resetting it to the initial state). 25014Expertise is required when multiple seeds are used to get independent 25015streams. Thus we recommend appropriate libraries for this task, 25016e.g. Pierre L'Ecuyer's @file{RngStreams} package. For this library 25017only a package seed can be set and thus the 25018@ifhtml 25019@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 25020@end ifhtml 25021@ifnothtml 25022@command{unur_urng_seed} 25023@end ifnothtml 25024call 25025will not have any effect to generators of this type. Use 25026@ifhtml 25027@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 25028@end ifhtml 25029@ifnothtml 25030@command{unur_urng_reset} 25031@end ifnothtml 25032or 25033@ifhtml 25034@ref{funct:unur_urng_rngstream_new,@command{unur_urng_rngstream_new}} 25035@end ifhtml 25036@ifnothtml 25037@command{unur_urng_rngstream_new} 25038@end ifnothtml 25039instead, depending 25040whether one wants to reset the stream or get a new stream that is 25041independent from the previous ones. 25042@end deftypefn 25043@end ifnotinfo 25044 25045@ifinfo 25046@anchor{funct:unur_urng_anti} 25047@deftypefn Function {int} unur_urng_anti (UNUR_URNG* @var{urng}, int @var{anti}) 25048Switch to antithetic random numbers in @var{urng}. 25049It returns an error code if this is not possible for the given 25050URNG. 25051 25052If the @code{NULL} pointer is given, the antithetic flag of the default 25053uniform generator is switched (if possible). 25054@end deftypefn 25055@end ifinfo 25056@ifnotinfo 25057@anchor{funct:unur_urng_anti} 25058@deftypefn {} {int} unur_urng_anti (UNUR_URNG* @var{urng}, int @var{anti}) 25059Switch to antithetic random numbers in @var{urng}. 25060It returns an error code if this is not possible for the given 25061URNG. 25062 25063If the @code{NULL} pointer is given, the antithetic flag of the default 25064uniform generator is switched (if possible). 25065@end deftypefn 25066@end ifnotinfo 25067 25068@ifinfo 25069@anchor{funct:unur_urng_nextsub} 25070@deftypefn Function {int} unur_urng_nextsub (UNUR_URNG* @var{urng}) 25071Jump to start of the next substream of @var{urng}. 25072It returns an error code if this is not possible for the given 25073URNG. 25074 25075If the @code{NULL} pointer is given, the default uniform generator is set 25076to the start of the next substream (if possible). 25077@end deftypefn 25078@end ifinfo 25079@ifnotinfo 25080@anchor{funct:unur_urng_nextsub} 25081@deftypefn {} {int} unur_urng_nextsub (UNUR_URNG* @var{urng}) 25082Jump to start of the next substream of @var{urng}. 25083It returns an error code if this is not possible for the given 25084URNG. 25085 25086If the @code{NULL} pointer is given, the default uniform generator is set 25087to the start of the next substream (if possible). 25088@end deftypefn 25089@end ifnotinfo 25090 25091@ifinfo 25092@anchor{funct:unur_urng_resetsub} 25093@deftypefn Function {int} unur_urng_resetsub (UNUR_URNG* @var{urng}) 25094Jump to start of the current substream of @var{urng}. 25095It returns an error code if this is not possible for the given 25096URNG. 25097 25098If the @code{NULL} pointer is given, the default uniform generator is set 25099to the start of the current substream (if possible). 25100@end deftypefn 25101@end ifinfo 25102@ifnotinfo 25103@anchor{funct:unur_urng_resetsub} 25104@deftypefn {} {int} unur_urng_resetsub (UNUR_URNG* @var{urng}) 25105Jump to start of the current substream of @var{urng}. 25106It returns an error code if this is not possible for the given 25107URNG. 25108 25109If the @code{NULL} pointer is given, the default uniform generator is set 25110to the start of the current substream (if possible). 25111@end deftypefn 25112@end ifnotinfo 25113 25114@ifinfo 25115@anchor{funct:unur_gen_sync} 25116@deftypefn Function {int} unur_gen_sync (UNUR_GEN* @var{generator}) 25117@anchor{funct:unur_gen_seed} 25118@deftypefnx Function {int} unur_gen_seed (UNUR_GEN* @var{generator}, unsigned @var{long seed}) 25119@anchor{funct:unur_gen_anti} 25120@deftypefnx Function {int} unur_gen_anti (UNUR_GEN* @var{generator}, int @var{anti}) 25121@anchor{funct:unur_gen_reset} 25122@deftypefnx Function {int} unur_gen_reset (UNUR_GEN* @var{generator}) 25123@anchor{funct:unur_gen_nextsub} 25124@deftypefnx Function {int} unur_gen_nextsub (UNUR_GEN* @var{generator}) 25125@anchor{funct:unur_gen_resetsub} 25126@deftypefnx Function {int} unur_gen_resetsub (UNUR_GEN* @var{generator}) 25127Analogous to 25128@ifhtml 25129@ref{funct:unur_urng_sync,@command{unur_urng_sync},} 25130@end ifhtml 25131@ifnothtml 25132@command{unur_urng_sync}, 25133@end ifnothtml 25134@ifhtml 25135@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 25136@end ifhtml 25137@ifnothtml 25138@command{unur_urng_seed} 25139@end ifnothtml 25140, 25141@ifhtml 25142@ref{funct:unur_urng_anti,@command{unur_urng_anti},} 25143@end ifhtml 25144@ifnothtml 25145@command{unur_urng_anti}, 25146@end ifnothtml 25147@ifhtml 25148@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 25149@end ifhtml 25150@ifnothtml 25151@command{unur_urng_reset} 25152@end ifnothtml 25153, 25154@ifhtml 25155@ref{funct:unur_urng_nextsub,@command{unur_urng_nextsub},} 25156@end ifhtml 25157@ifnothtml 25158@command{unur_urng_nextsub}, 25159@end ifnothtml 25160and 25161@ifhtml 25162@ref{funct:unur_urng_resetsub,@command{unur_urng_resetsub},} 25163@end ifhtml 25164@ifnothtml 25165@command{unur_urng_resetsub}, 25166@end ifnothtml 25167but act on the URNG object used by the @var{generator} object. 25168 25169@emph{Warning:} These calls should be used with care as it 25170influences all generator objects that share the same URNG object! 25171@end deftypefn 25172@end ifinfo 25173@ifnotinfo 25174@anchor{funct:unur_gen_sync} 25175@deftypefn {} {int} unur_gen_sync (UNUR_GEN* @var{generator}) 25176@anchor{funct:unur_gen_seed} 25177@deftypefnx {} {int} unur_gen_seed (UNUR_GEN* @var{generator}, unsigned @var{long seed}) 25178@anchor{funct:unur_gen_anti} 25179@deftypefnx {} {int} unur_gen_anti (UNUR_GEN* @var{generator}, int @var{anti}) 25180@anchor{funct:unur_gen_reset} 25181@deftypefnx {} {int} unur_gen_reset (UNUR_GEN* @var{generator}) 25182@anchor{funct:unur_gen_nextsub} 25183@deftypefnx {} {int} unur_gen_nextsub (UNUR_GEN* @var{generator}) 25184@anchor{funct:unur_gen_resetsub} 25185@deftypefnx {} {int} unur_gen_resetsub (UNUR_GEN* @var{generator}) 25186Analogous to 25187@ifhtml 25188@ref{funct:unur_urng_sync,@command{unur_urng_sync},} 25189@end ifhtml 25190@ifnothtml 25191@command{unur_urng_sync}, 25192@end ifnothtml 25193@ifhtml 25194@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 25195@end ifhtml 25196@ifnothtml 25197@command{unur_urng_seed} 25198@end ifnothtml 25199, 25200@ifhtml 25201@ref{funct:unur_urng_anti,@command{unur_urng_anti},} 25202@end ifhtml 25203@ifnothtml 25204@command{unur_urng_anti}, 25205@end ifnothtml 25206@ifhtml 25207@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 25208@end ifhtml 25209@ifnothtml 25210@command{unur_urng_reset} 25211@end ifnothtml 25212, 25213@ifhtml 25214@ref{funct:unur_urng_nextsub,@command{unur_urng_nextsub},} 25215@end ifhtml 25216@ifnothtml 25217@command{unur_urng_nextsub}, 25218@end ifnothtml 25219and 25220@ifhtml 25221@ref{funct:unur_urng_resetsub,@command{unur_urng_resetsub},} 25222@end ifhtml 25223@ifnothtml 25224@command{unur_urng_resetsub}, 25225@end ifnothtml 25226but act on the URNG object used by the @var{generator} object. 25227 25228@emph{Warning:} These calls should be used with care as it 25229influences all generator objects that share the same URNG object! 25230@end deftypefn 25231@end ifnotinfo 25232 25233@subheading API to create a new URNG object 25234 25235@emph{Notice:} These functions are provided to built a 25236UNUR_URNG object for a particular external random number 25237generator from scratch. For some libraries that contain random 25238number generators (like the GSL) there are special calls, 25239e.g. 25240@ifhtml 25241@ref{funct:unur_urng_gsl_new,@command{unur_urng_gsl_new},} 25242@end ifhtml 25243@ifnothtml 25244@command{unur_urng_gsl_new}, 25245@end ifnothtml 25246to get such an object. Then there is no 25247need to change the UNUR_URNG object as it already contains all 25248available features. 25249 25250If you have a particular library for random number generators you 25251can either write wrapper function like those in 25252@file{src/uniform/urng_gsl.c} or write an email to the authors of 25253UNU.RAN to write it for you. 25254 25255@ifinfo 25256@anchor{funct:unur_urng_new} 25257@deftypefn Function {UNUR_URNG*} unur_urng_new (double (* @var{sampleunif})(void* state ), void* @var{state}) 25258Get a new URNG object. 25259@var{sampleunif} is a function to the uniform sampling routine, 25260@var{state} a pointer to its arguments which usually contains the 25261state variables of the generator. 25262 25263Functions @var{sampleunif} with a different type for @var{p} or 25264without an argument at all also work. A typecast might be necessary 25265to avoid compiler warnings or error messages. 25266 25267For functions @var{sampleunif} that does not have any argument 25268should use @code{NULL} for @var{state}. 25269 25270@emph{Important:} @var{sampleunif} must not be the @code{NULL} pointer. 25271 25272There are appropriate calls that simplifies the task of creating 25273URNG objects for some libraries with uniform random number 25274generators, see below. 25275@end deftypefn 25276@end ifinfo 25277@ifnotinfo 25278@anchor{funct:unur_urng_new} 25279@deftypefn {} {UNUR_URNG*} unur_urng_new (double (* @var{sampleunif})(void* state ), void* @var{state}) 25280Get a new URNG object. 25281@var{sampleunif} is a function to the uniform sampling routine, 25282@var{state} a pointer to its arguments which usually contains the 25283state variables of the generator. 25284 25285Functions @var{sampleunif} with a different type for @var{p} or 25286without an argument at all also work. A typecast might be necessary 25287to avoid compiler warnings or error messages. 25288 25289For functions @var{sampleunif} that does not have any argument 25290should use @code{NULL} for @var{state}. 25291 25292@emph{Important:} @var{sampleunif} must not be the @code{NULL} pointer. 25293 25294There are appropriate calls that simplifies the task of creating 25295URNG objects for some libraries with uniform random number 25296generators, see below. 25297@end deftypefn 25298@end ifnotinfo 25299 25300@ifinfo 25301@anchor{funct:unur_urng_free} 25302@deftypefn Function {void} unur_urng_free (UNUR_URNG* @var{urng}) 25303Destroy @var{urng} object. 25304It returns an error code if this is not possible. 25305 25306If the @code{NULL} is given, this function does nothing. 25307 25308@emph{Warning:} This call must be used with care. The @var{urng} 25309object must not be used by any existing generator object! 25310It is designed to work in conjunction with the wrapper functions 25311to create URNG objects for generators of a particular library. 25312Thus an object created by an 25313@ifhtml 25314@ref{funct:unur_urng_prng_new,@command{unur_urng_prng_new}} 25315@end ifhtml 25316@ifnothtml 25317@command{unur_urng_prng_new} 25318@end ifnothtml 25319call can be 25320simply destroyed by an 25321@ifhtml 25322@ref{funct:unur_urng_free,@command{unur_urng_free}} 25323@end ifhtml 25324@ifnothtml 25325@command{unur_urng_free} 25326@end ifnothtml 25327call. 25328@end deftypefn 25329@end ifinfo 25330@ifnotinfo 25331@anchor{funct:unur_urng_free} 25332@deftypefn {} {void} unur_urng_free (UNUR_URNG* @var{urng}) 25333Destroy @var{urng} object. 25334It returns an error code if this is not possible. 25335 25336If the @code{NULL} is given, this function does nothing. 25337 25338@emph{Warning:} This call must be used with care. The @var{urng} 25339object must not be used by any existing generator object! 25340It is designed to work in conjunction with the wrapper functions 25341to create URNG objects for generators of a particular library. 25342Thus an object created by an 25343@ifhtml 25344@ref{funct:unur_urng_prng_new,@command{unur_urng_prng_new}} 25345@end ifhtml 25346@ifnothtml 25347@command{unur_urng_prng_new} 25348@end ifnothtml 25349call can be 25350simply destroyed by an 25351@ifhtml 25352@ref{funct:unur_urng_free,@command{unur_urng_free}} 25353@end ifhtml 25354@ifnothtml 25355@command{unur_urng_free} 25356@end ifnothtml 25357call. 25358@end deftypefn 25359@end ifnotinfo 25360 25361@ifinfo 25362@anchor{funct:unur_urng_set_sample_array} 25363@deftypefn Function {int} unur_urng_set_sample_array (UNUR_URNG* @var{urng}, unsigned int(* @var{samplearray})(void* state, double* @var{X}, int @var{dim} )) 25364Set function to fill array @var{X} of length @var{dim} with random 25365numbers generated by generator @var{urng} (if available). 25366@end deftypefn 25367@end ifinfo 25368@ifnotinfo 25369@anchor{funct:unur_urng_set_sample_array} 25370@deftypefn {} {int} unur_urng_set_sample_array (UNUR_URNG* @var{urng}, unsigned int(* @var{samplearray})(void* state, double* @var{X}, int @var{dim} )) 25371Set function to fill array @var{X} of length @var{dim} with random 25372numbers generated by generator @var{urng} (if available). 25373@end deftypefn 25374@end ifnotinfo 25375 25376@ifinfo 25377@anchor{funct:unur_urng_set_sync} 25378@deftypefn Function {int} unur_urng_set_sync (UNUR_URNG* @var{urng}, void (* @var{sync})(void* state )) 25379Set function for jumping into a defined state (``sync''). 25380@end deftypefn 25381@end ifinfo 25382@ifnotinfo 25383@anchor{funct:unur_urng_set_sync} 25384@deftypefn {} {int} unur_urng_set_sync (UNUR_URNG* @var{urng}, void (* @var{sync})(void* state )) 25385Set function for jumping into a defined state (``sync''). 25386@end deftypefn 25387@end ifnotinfo 25388 25389@ifinfo 25390@anchor{funct:unur_urng_set_seed} 25391@deftypefn Function {int} unur_urng_set_seed (UNUR_URNG* @var{urng}, void (* @var{setseed})(void* state, unsigned @var{long seed} )) 25392Set function to seed generator @var{urng} (if available). 25393@end deftypefn 25394@end ifinfo 25395@ifnotinfo 25396@anchor{funct:unur_urng_set_seed} 25397@deftypefn {} {int} unur_urng_set_seed (UNUR_URNG* @var{urng}, void (* @var{setseed})(void* state, unsigned @var{long seed} )) 25398Set function to seed generator @var{urng} (if available). 25399@end deftypefn 25400@end ifnotinfo 25401 25402@ifinfo 25403@anchor{funct:unur_urng_set_anti} 25404@deftypefn Function {int} unur_urng_set_anti (UNUR_URNG* @var{urng}, void (* @var{setanti})(void* state, int @var{anti} )) 25405Set function to switch the antithetic flag of generator @var{urng} 25406(if available). 25407@end deftypefn 25408@end ifinfo 25409@ifnotinfo 25410@anchor{funct:unur_urng_set_anti} 25411@deftypefn {} {int} unur_urng_set_anti (UNUR_URNG* @var{urng}, void (* @var{setanti})(void* state, int @var{anti} )) 25412Set function to switch the antithetic flag of generator @var{urng} 25413(if available). 25414@end deftypefn 25415@end ifnotinfo 25416 25417@ifinfo 25418@anchor{funct:unur_urng_set_reset} 25419@deftypefn Function {int} unur_urng_set_reset (UNUR_URNG* @var{urng}, void (* @var{reset})(void* state )) 25420Set function for reseting the uniform random number generator 25421@var{urng} (if available). 25422@end deftypefn 25423@end ifinfo 25424@ifnotinfo 25425@anchor{funct:unur_urng_set_reset} 25426@deftypefn {} {int} unur_urng_set_reset (UNUR_URNG* @var{urng}, void (* @var{reset})(void* state )) 25427Set function for reseting the uniform random number generator 25428@var{urng} (if available). 25429@end deftypefn 25430@end ifnotinfo 25431 25432@ifinfo 25433@anchor{funct:unur_urng_set_nextsub} 25434@deftypefn Function {int} unur_urng_set_nextsub (UNUR_URNG* @var{urng}, void (* @var{nextsub})(void* state )) 25435Set function that allows jumping to start of the next substream of 25436@var{urng} (if available). 25437@end deftypefn 25438@end ifinfo 25439@ifnotinfo 25440@anchor{funct:unur_urng_set_nextsub} 25441@deftypefn {} {int} unur_urng_set_nextsub (UNUR_URNG* @var{urng}, void (* @var{nextsub})(void* state )) 25442Set function that allows jumping to start of the next substream of 25443@var{urng} (if available). 25444@end deftypefn 25445@end ifnotinfo 25446 25447@ifinfo 25448@anchor{funct:unur_urng_set_resetsub} 25449@deftypefn Function {int} unur_urng_set_resetsub (UNUR_URNG* @var{urng}, void (* @var{resetsub})(void* state )) 25450Set function that allows jumping to start of the current substream 25451of @var{urng} (if available). 25452@end deftypefn 25453@end ifinfo 25454@ifnotinfo 25455@anchor{funct:unur_urng_set_resetsub} 25456@deftypefn {} {int} unur_urng_set_resetsub (UNUR_URNG* @var{urng}, void (* @var{resetsub})(void* state )) 25457Set function that allows jumping to start of the current substream 25458of @var{urng} (if available). 25459@end deftypefn 25460@end ifnotinfo 25461 25462@ifinfo 25463@anchor{funct:unur_urng_set_delete} 25464@deftypefn Function {int} unur_urng_set_delete (UNUR_URNG* @var{urng}, void (* @var{fpdelete})(void* state )) 25465Set function for destroying @var{urng} (if available). 25466@end deftypefn 25467@end ifinfo 25468@ifnotinfo 25469@anchor{funct:unur_urng_set_delete} 25470@deftypefn {} {int} unur_urng_set_delete (UNUR_URNG* @var{urng}, void (* @var{fpdelete})(void* state )) 25471Set function for destroying @var{urng} (if available). 25472@end deftypefn 25473@end ifnotinfo 25474 25475 25476 25477 25478@c 25479@c end of urng.h 25480@c ------------------------------------- 25481@c ------------------------------------- 25482@c urng_fvoid.h 25483@c 25484 25485@node URNG-FVOID 25486@section Simple interface for uniform random number generators 25487 25488 25489Simple interface for URNGs of type @code{double uniform(void *state)}. 25490 25491UNU.RAN contains some build-in URNGs of this type: 25492@table @code 25493@item unur_urng_MRG31k3p 25494Combined multiple recursive generator by Pierre L'Ecuyer and 25495Renee Touzin. 25496@item unur_urng_fish 25497Linear congruential generator by Fishman and Moore. 25498@item unur_urng_mstd 25499Linear congruential generator "Minimal Standard" by Park and Miller. 25500@end table 25501 25502Notice, however, that these generators are provided as a 25503fallback for the case that no state-of-the-art uniform random 25504number generators (e.g. @pxref{URNG-RNGSTREAM,Pierre L'Ecuyer's 25505@file{Rngstream} library, Pierre L'Ecuyer's @file{Rngstream} 25506library}) are used. 25507 25508 25509@subsubheading How To Use 25510 25511 25512Create an URNG object using 25513@ifhtml 25514@ref{funct:unur_urng_fvoid_new,@command{unur_urng_fvoid_new}.} 25515@end ifhtml 25516@ifnothtml 25517@command{unur_urng_fvoid_new}. 25518@end ifnothtml 25519By this call a pointer to the sampling routine and (optional) a 25520pointer to a reset routine are copied into the URNG object. 25521Other functions, like seeding the URNG, switching to antithetic 25522random number, or jumping to next substream, can be added to the 25523URNG object by the respective calls, e.g. by 25524@ifhtml 25525@ref{funct:unur_urng_set_seed,@command{unur_urng_set_seed}.} 25526@end ifhtml 25527@ifnothtml 25528@command{unur_urng_set_seed}. 25529@end ifnothtml 25530The following routines are supported for URNG objects of this 25531type: 25532 25533@itemize @minus 25534@item 25535@ifhtml 25536@ref{funct:unur_urng_sample,@command{unur_urng_sample}} 25537@end ifhtml 25538@ifnothtml 25539@command{unur_urng_sample} 25540@end ifnothtml 25541@item 25542@ifhtml 25543@ref{funct:unur_urng_sample_array,@command{unur_urng_sample_array}} 25544@end ifhtml 25545@ifnothtml 25546@command{unur_urng_sample_array} 25547@end ifnothtml 25548@item 25549@ifhtml 25550@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 25551@end ifhtml 25552@ifnothtml 25553@command{unur_urng_seed} 25554@end ifnothtml 25555[optional] 25556@item 25557@ifhtml 25558@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 25559@end ifhtml 25560@ifnothtml 25561@command{unur_urng_reset} 25562@end ifnothtml 25563[optional] 25564@item 25565@ifhtml 25566@ref{funct:unur_urng_free,@command{unur_urng_free}} 25567@end ifhtml 25568@ifnothtml 25569@command{unur_urng_free} 25570@end ifnothtml 25571@end itemize 25572 25573 25574 25575 25576@subheading Function reference 25577 25578@ifhtml 25579@itemize 25580@item @ref{funct:unur_urng_fvoid_new,unur_urng_fvoid_new} 25581@end itemize 25582@end ifhtml 25583 25584 25585@ifinfo 25586@anchor{funct:unur_urng_fvoid_new} 25587@deftypefn Function {UNUR_URNG*} unur_urng_fvoid_new (double (* @var{urand})(void* state ), void (* @var{reset})(void* state )) 25588Make a URNG object for a generator that consists of a single 25589function call @var{urand}. 25590 25591If there is no @var{reset} function use @code{NULL} for the second argument. 25592@end deftypefn 25593@end ifinfo 25594@ifnotinfo 25595@anchor{funct:unur_urng_fvoid_new} 25596@deftypefn {} {UNUR_URNG*} unur_urng_fvoid_new (double (* @var{urand})(void* state ), void (* @var{reset})(void* state )) 25597Make a URNG object for a generator that consists of a single 25598function call @var{urand}. 25599 25600If there is no @var{reset} function use @code{NULL} for the second argument. 25601@end deftypefn 25602@end ifnotinfo 25603 25604 25605 25606 25607@c 25608@c end of urng_fvoid.h 25609@c ------------------------------------- 25610@c ------------------------------------- 25611@c urng_gsl.h 25612@c 25613 25614@node URNG-GSL 25615@section Interface to GSL uniform random number generators 25616 25617 25618Interface to the uniform random number generators from the 25619GNU Scientific Library (GSL). Documentation and source code 25620of this library is available from 25621@uref{http://www.gnu.org/software/gsl/}. 25622 25623The interface to the GSL must be compiled into UNU.RAN using the 25624configure flag @code{--with-urng-gsl}. 25625Notice that the GSL has to be installed before running 25626@code{./configure}. 25627 25628 25629@subsubheading How To Use 25630 25631 25632When using this interface @file{unuran_urng_gsl.h} must be included 25633in the corresponding C file, i.e., one must add the line 25634@smallexample 25635#include <unuran_urng_gsl.h> 25636@end smallexample 25637 25638Moreover, one must not forget to link the executable against 25639@file{libgsl}. 25640 25641The following routines are supported for URNG objects of 25642type GSL: 25643 25644@itemize @minus 25645@item 25646@ifhtml 25647@ref{funct:unur_urng_sample,@command{unur_urng_sample}} 25648@end ifhtml 25649@ifnothtml 25650@command{unur_urng_sample} 25651@end ifnothtml 25652@item 25653@ifhtml 25654@ref{funct:unur_urng_sample_array,@command{unur_urng_sample_array}} 25655@end ifhtml 25656@ifnothtml 25657@command{unur_urng_sample_array} 25658@end ifnothtml 25659@item 25660@ifhtml 25661@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 25662@end ifhtml 25663@ifnothtml 25664@command{unur_urng_seed} 25665@end ifnothtml 25666@item 25667@ifhtml 25668@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 25669@end ifhtml 25670@ifnothtml 25671@command{unur_urng_reset} 25672@end ifnothtml 25673@item 25674@ifhtml 25675@ref{funct:unur_urng_free,@command{unur_urng_free}} 25676@end ifhtml 25677@ifnothtml 25678@command{unur_urng_free} 25679@end ifnothtml 25680@end itemize 25681 25682@smallexample 25683@include ref_example_gsl.texi 25684@end smallexample 25685 25686 25687 25688 25689@subheading Function reference 25690 25691@ifhtml 25692@itemize 25693@item @ref{funct:unur_urng_gsl_new,unur_urng_gsl_new} 25694@item @ref{funct:unur_urng_gslptr_new,unur_urng_gslptr_new} 25695@end itemize 25696@end ifhtml 25697 25698 25699@ifinfo 25700@anchor{funct:unur_urng_gsl_new} 25701@deftypefn Function {UNUR_URNG*} unur_urng_gsl_new (const @var{gsl_rng_type* urngtype}) 25702Make object for URNGs from the @file{GSL} (GNU Scientific Library). 25703@var{urngtype} is the type of the chosen generator as described in the 25704GSL manual (see Section Random Number Generation). This library is 25705available from @uref{http://www.gnu.org/software/gsl/}. 25706@end deftypefn 25707@end ifinfo 25708@ifnotinfo 25709@anchor{funct:unur_urng_gsl_new} 25710@deftypefn {} {UNUR_URNG*} unur_urng_gsl_new (const @var{gsl_rng_type* urngtype}) 25711Make object for URNGs from the @file{GSL} (GNU Scientific Library). 25712@var{urngtype} is the type of the chosen generator as described in the 25713GSL manual (see Section Random Number Generation). This library is 25714available from @uref{http://www.gnu.org/software/gsl/}. 25715@end deftypefn 25716@end ifnotinfo 25717 25718@ifinfo 25719@anchor{funct:unur_urng_gslptr_new} 25720@deftypefn Function {UNUR_URNG*} unur_urng_gslptr_new (gsl_rng* @var{urng}) 25721Similar to 25722@ifhtml 25723@ref{funct:unur_urng_gsl_new,@command{unur_urng_gsl_new}} 25724@end ifhtml 25725@ifnothtml 25726@command{unur_urng_gsl_new} 25727@end ifnothtml 25728but it uses a pointer to a 25729generator object as returned by @code{gsl_rng_alloc(rng_type)}; 25730see @file{GSL} manual for details. 25731 25732@emph{Notice}: There is a subtle but important difference between 25733these two calls. When a generator object is created by a 25734@ifhtml 25735@ref{funct:unur_urng_gsl_new,@command{unur_urng_gsl_new}} 25736@end ifhtml 25737@ifnothtml 25738@command{unur_urng_gsl_new} 25739@end ifnothtml 25740call, then resetting of the generator works. 25741When a generator object is created by a 25742@ifhtml 25743@ref{funct:unur_urng_gslptr_new,@command{unur_urng_gslptr_new}} 25744@end ifhtml 25745@ifnothtml 25746@command{unur_urng_gslptr_new} 25747@end ifnothtml 25748call, then resetting only works after a 25749@code{unur_urng_seed(urng,myseed)} call. 25750@end deftypefn 25751@end ifinfo 25752@ifnotinfo 25753@anchor{funct:unur_urng_gslptr_new} 25754@deftypefn {} {UNUR_URNG*} unur_urng_gslptr_new (gsl_rng* @var{urng}) 25755Similar to 25756@ifhtml 25757@ref{funct:unur_urng_gsl_new,@command{unur_urng_gsl_new}} 25758@end ifhtml 25759@ifnothtml 25760@command{unur_urng_gsl_new} 25761@end ifnothtml 25762but it uses a pointer to a 25763generator object as returned by @code{gsl_rng_alloc(rng_type)}; 25764see @file{GSL} manual for details. 25765 25766@emph{Notice}: There is a subtle but important difference between 25767these two calls. When a generator object is created by a 25768@ifhtml 25769@ref{funct:unur_urng_gsl_new,@command{unur_urng_gsl_new}} 25770@end ifhtml 25771@ifnothtml 25772@command{unur_urng_gsl_new} 25773@end ifnothtml 25774call, then resetting of the generator works. 25775When a generator object is created by a 25776@ifhtml 25777@ref{funct:unur_urng_gslptr_new,@command{unur_urng_gslptr_new}} 25778@end ifhtml 25779@ifnothtml 25780@command{unur_urng_gslptr_new} 25781@end ifnothtml 25782call, then resetting only works after a 25783@code{unur_urng_seed(urng,myseed)} call. 25784@end deftypefn 25785@end ifnotinfo 25786 25787 25788 25789 25790@c 25791@c end of urng_gsl.h 25792@c ------------------------------------- 25793@c ------------------------------------- 25794@c urng_gslqrng.h 25795@c 25796 25797@node URNG-GSLQRNG 25798@section Interface to GSL generators for quasi-random points 25799 25800 25801Interface to the generators for quasi-random points (also called 25802low discrepancy point sets) from the GNU Scientific Library (GSL). 25803Documentation and source code of this library is available from 25804@uref{http://www.gnu.org/software/gsl/}. 25805 25806The interface to the GSL must be compiled into UNU.RAN using the 25807configure flag @code{--with-urng-gsl}. 25808Notice that the GSL has to be installed before running 25809@code{./configure}. 25810 25811 25812@subsubheading How To Use 25813 25814 25815When using this interface @file{unuran_urng_gsl.h} must be included 25816in the corresponding C file, i.e., one must add the line 25817@smallexample 25818#include <unuran_urng_gsl.h> 25819@end smallexample 25820 25821Moreover, one must not forget to link the executable against 25822@file{libgsl}. 25823 25824The following routines are supported for URNG objects of this 25825type: 25826 25827@itemize @minus 25828@item 25829@ifhtml 25830@ref{funct:unur_urng_sample,@command{unur_urng_sample}} 25831@end ifhtml 25832@ifnothtml 25833@command{unur_urng_sample} 25834@end ifnothtml 25835@item 25836@ifhtml 25837@ref{funct:unur_urng_sample_array,@command{unur_urng_sample_array}} 25838@end ifhtml 25839@ifnothtml 25840@command{unur_urng_sample_array} 25841@end ifnothtml 25842@item 25843@ifhtml 25844@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 25845@end ifhtml 25846@ifnothtml 25847@command{unur_urng_reset} 25848@end ifnothtml 25849@item 25850@ifhtml 25851@ref{funct:unur_urng_sync,@command{unur_urng_sync}} 25852@end ifhtml 25853@ifnothtml 25854@command{unur_urng_sync} 25855@end ifnothtml 25856@item 25857@ifhtml 25858@ref{funct:unur_urng_free,@command{unur_urng_free}} 25859@end ifhtml 25860@ifnothtml 25861@command{unur_urng_free} 25862@end ifnothtml 25863@end itemize 25864@ifhtml 25865@ref{funct:unur_urng_sync,@command{unur_urng_sync}} 25866@end ifhtml 25867@ifnothtml 25868@command{unur_urng_sync} 25869@end ifnothtml 25870is used to jump to the first coordinate of 25871the next point generated by the generator. 25872 25873 25874 25875 25876@subheading Function reference 25877 25878@ifhtml 25879@itemize 25880@item @ref{funct:unur_urng_gslqrng_new,unur_urng_gslqrng_new} 25881@end itemize 25882@end ifhtml 25883 25884 25885@ifinfo 25886@anchor{funct:unur_urng_gslqrng_new} 25887@deftypefn Function {UNUR_URNG*} unur_urng_gslqrng_new (const @var{gsl_qrng_type* qrngtype}, unsigned @var{int dim}) 25888Make object for quasi-random point generators for dimension 25889@var{dim} from the @file{GSL} (GNU Scientific Library). 25890@var{qrngtype} is the type of the chosen generator as described in 25891the GSL manual (see section Quasi-Random Sequences). 25892This library is available from @uref{http://www.gnu.org/software/gsl/}. 25893@end deftypefn 25894@end ifinfo 25895@ifnotinfo 25896@anchor{funct:unur_urng_gslqrng_new} 25897@deftypefn {} {UNUR_URNG*} unur_urng_gslqrng_new (const @var{gsl_qrng_type* qrngtype}, unsigned @var{int dim}) 25898Make object for quasi-random point generators for dimension 25899@var{dim} from the @file{GSL} (GNU Scientific Library). 25900@var{qrngtype} is the type of the chosen generator as described in 25901the GSL manual (see section Quasi-Random Sequences). 25902This library is available from @uref{http://www.gnu.org/software/gsl/}. 25903@end deftypefn 25904@end ifnotinfo 25905 25906 25907 25908 25909@c 25910@c end of urng_gslqrng.h 25911@c ------------------------------------- 25912@c ------------------------------------- 25913@c urng_prng.h 25914@c 25915 25916@node URNG-PRNG 25917@section Interface to Otmar Lendl's pseudo-random number generators 25918 25919 25920URNGs from Otmar Lendl's @code{prng} library. It provides a very 25921flexible way to sample form arbitrary URNGs by means of an object 25922oriented programing paradigma. Similarly to the UNU.RAN library 25923independent generator objects can be build and used. 25924 25925This library has been developed by the pLab group at the university 25926of Salzburg (Austria, EU) and implemented by Otmar Lendl. 25927It is available from 25928@uref{http://statmath.wu.ac.at/prng/} 25929or from the pLab site at 25930@uref{http://random.mat.sbg.ac.at/}. 25931 25932The interface to the PRNG library must be compiled into UNU.RAN using the 25933configure flag @code{--with-urng-prng}. 25934Notice that the PRNG library has to be installed before running 25935@code{./configure}. 25936 25937 25938@subsubheading How To Use 25939 25940 25941When using this interface @file{unuran_urng_prng.h} must be included 25942in the corresponding C file, i.e., one must add the line 25943@smallexample 25944#include <unuran_urng_prng.h> 25945@end smallexample 25946 25947Moreover, one must not forget to link the executable against 25948@file{libprng}. 25949 25950The following routines are supported for URNG objects of 25951type PRNG: 25952 25953@itemize @minus 25954@item 25955@ifhtml 25956@ref{funct:unur_urng_sample,@command{unur_urng_sample}} 25957@end ifhtml 25958@ifnothtml 25959@command{unur_urng_sample} 25960@end ifnothtml 25961@item 25962@ifhtml 25963@ref{funct:unur_urng_sample_array,@command{unur_urng_sample_array}} 25964@end ifhtml 25965@ifnothtml 25966@command{unur_urng_sample_array} 25967@end ifnothtml 25968@item 25969@ifhtml 25970@ref{funct:unur_urng_seed,@command{unur_urng_seed}} 25971@end ifhtml 25972@ifnothtml 25973@command{unur_urng_seed} 25974@end ifnothtml 25975(availability depends on chosen PRNG generator!) 25976@item 25977@ifhtml 25978@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 25979@end ifhtml 25980@ifnothtml 25981@command{unur_urng_reset} 25982@end ifnothtml 25983@item 25984@ifhtml 25985@ref{funct:unur_urng_free,@command{unur_urng_free}} 25986@end ifhtml 25987@ifnothtml 25988@command{unur_urng_free} 25989@end ifnothtml 25990@end itemize 25991 25992 25993 25994 25995@subheading Function reference 25996 25997@ifhtml 25998@itemize 25999@item @ref{funct:unur_urng_prng_new,unur_urng_prng_new} 26000@item @ref{funct:unur_urng_prngptr_new,unur_urng_prngptr_new} 26001@end itemize 26002@end ifhtml 26003 26004 26005@ifinfo 26006@anchor{funct:unur_urng_prng_new} 26007@deftypefn Function {UNUR_URNG*} unur_urng_prng_new (const @var{char* prngstr}) 26008Make object for URNGs from Otmar Lendl's @file{prng} package. 26009@var{prngstr} is a string that contains the necessary information 26010to create a uniform random number generator. For the format of this 26011string see the @file{prng} user manual. 26012 26013The @file{prng} library provides a very flexible way to sample form 26014arbitrary URNGs by means of an object oriented programing 26015paradigma. Similarly to the UNU.RAN library independent generator 26016objects can be build and used. The library has been developed 26017and implemented by Otmar Lendl as member of the pLab group at the 26018university of Salzburg (Austria, EU). 26019 26020It is available via anonymous ftp from 26021@uref{http://statmath.wu.ac.at/prng/} 26022or from the pLab site at 26023@uref{http://random.mat.sbg.ac.at/}. 26024@end deftypefn 26025@end ifinfo 26026@ifnotinfo 26027@anchor{funct:unur_urng_prng_new} 26028@deftypefn {} {UNUR_URNG*} unur_urng_prng_new (const @var{char* prngstr}) 26029Make object for URNGs from Otmar Lendl's @file{prng} package. 26030@var{prngstr} is a string that contains the necessary information 26031to create a uniform random number generator. For the format of this 26032string see the @file{prng} user manual. 26033 26034The @file{prng} library provides a very flexible way to sample form 26035arbitrary URNGs by means of an object oriented programing 26036paradigma. Similarly to the UNU.RAN library independent generator 26037objects can be build and used. The library has been developed 26038and implemented by Otmar Lendl as member of the pLab group at the 26039university of Salzburg (Austria, EU). 26040 26041It is available via anonymous ftp from 26042@uref{http://statmath.wu.ac.at/prng/} 26043or from the pLab site at 26044@uref{http://random.mat.sbg.ac.at/}. 26045@end deftypefn 26046@end ifnotinfo 26047 26048@ifinfo 26049@anchor{funct:unur_urng_prngptr_new} 26050@deftypefn Function {UNUR_URNG*} unur_urng_prngptr_new (struct @var{prng* urng}) 26051Similar to 26052@ifhtml 26053@ref{funct:unur_urng_prng_new,@command{unur_urng_prng_new}} 26054@end ifhtml 26055@ifnothtml 26056@command{unur_urng_prng_new} 26057@end ifnothtml 26058but it uses a pointer to a 26059generator object as returned by @code{prng_new(prngstr)}; 26060see @file{prng} manual for details. 26061@end deftypefn 26062@end ifinfo 26063@ifnotinfo 26064@anchor{funct:unur_urng_prngptr_new} 26065@deftypefn {} {UNUR_URNG*} unur_urng_prngptr_new (struct @var{prng* urng}) 26066Similar to 26067@ifhtml 26068@ref{funct:unur_urng_prng_new,@command{unur_urng_prng_new}} 26069@end ifhtml 26070@ifnothtml 26071@command{unur_urng_prng_new} 26072@end ifnothtml 26073but it uses a pointer to a 26074generator object as returned by @code{prng_new(prngstr)}; 26075see @file{prng} manual for details. 26076@end deftypefn 26077@end ifnotinfo 26078 26079 26080 26081 26082@c 26083@c end of urng_prng.h 26084@c ------------------------------------- 26085@c ------------------------------------- 26086@c urng_rngstreams.h 26087@c 26088 26089@node URNG-RNGSTREAM 26090@section Interface to L'Ecuyer's RNGSTREAM random number generators 26091 26092 26093URNGs from Pierre L'Ecuyer's @file{RngStream} library for multiple 26094independent streams of pseudo-random numbers. 26095This library provides multiple independent streams of 26096pseudo-random numbers which itselves can be splitted into many 26097substreams. It is available from 26098@uref{http://www.iro.umontreal.ca/~lecuyer/myftp/streams00/c/}. 26099A GNU-style package is available from 26100@uref{http://statmath.wu.ac.at/software/RngStreams/}. 26101 26102The interface to the RngStream library must be compiled into UNU.RAN using the 26103configure flag @code{--with-urng-rngstream}. 26104Notice that the RngStream library has to be installed before running 26105@code{./configure}. 26106 26107 26108@subsubheading How To Use 26109 26110 26111When using this interface @file{unuran_urng_rngstream.h} must be included 26112in the corresponding C file, i.e., one must add the line 26113@smallexample 26114#include <unuran_urng_rngstream.h> 26115@end smallexample 26116 26117Moreover, one must not forget to link the executable against the 26118@file{RngStream} library (i.e., when using the GNU-style package 26119in UNIX like environments one has to add @code{-lrngstreams} 26120when linking an executable). 26121 26122Notice that the @file{rngstream} library uses a package seed, 26123that means one should seed the uniform random number generator 26124only once in an application using the routine 26125@uref{http://statmath.wu.ac.at/software/RngStreams/doc/rngstreams.html#index-RngStream_005fSetPackageSeed-2,,@code{RngStream_SetPackageSeed}}: 26126 26127@smallexample 26128unsigned long seed[] = @{111u, 222u, 333u, 444u, 555u, 666u@}; 26129RngStream_SetPackageSeed(seed); 26130@end smallexample 26131 26132The following routines are supported for URNG objects of this 26133type: 26134 26135@itemize @minus 26136@item 26137@ifhtml 26138@ref{funct:unur_urng_sample,@command{unur_urng_sample}} 26139@end ifhtml 26140@ifnothtml 26141@command{unur_urng_sample} 26142@end ifnothtml 26143@item 26144@ifhtml 26145@ref{funct:unur_urng_sample_array,@command{unur_urng_sample_array}} 26146@end ifhtml 26147@ifnothtml 26148@command{unur_urng_sample_array} 26149@end ifnothtml 26150@item 26151@ifhtml 26152@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 26153@end ifhtml 26154@ifnothtml 26155@command{unur_urng_reset} 26156@end ifnothtml 26157@item 26158@ifhtml 26159@ref{funct:unur_urng_nextsub,@command{unur_urng_nextsub}} 26160@end ifhtml 26161@ifnothtml 26162@command{unur_urng_nextsub} 26163@end ifnothtml 26164@item 26165@ifhtml 26166@ref{funct:unur_urng_resetsub,@command{unur_urng_resetsub}} 26167@end ifhtml 26168@ifnothtml 26169@command{unur_urng_resetsub} 26170@end ifnothtml 26171@item 26172@ifhtml 26173@ref{funct:unur_urng_anti,@command{unur_urng_anti}} 26174@end ifhtml 26175@ifnothtml 26176@command{unur_urng_anti} 26177@end ifnothtml 26178@item 26179@ifhtml 26180@ref{funct:unur_urng_free,@command{unur_urng_free}} 26181@end ifhtml 26182@ifnothtml 26183@command{unur_urng_free} 26184@end ifnothtml 26185@end itemize 26186 26187 26188 26189 26190@subheading Function reference 26191 26192@ifhtml 26193@itemize 26194@item @ref{funct:unur_urng_rngstream_new,unur_urng_rngstream_new} 26195@item @ref{funct:unur_urng_rngstreamptr_new,unur_urng_rngstreamptr_new} 26196@end itemize 26197@end ifhtml 26198 26199 26200@ifinfo 26201@anchor{funct:unur_urng_rngstream_new} 26202@deftypefn Function {UNUR_URNG*} unur_urng_rngstream_new (const @var{char* urngstr}) 26203Make object for URNGs from Pierre L'Ecuyer's @file{RngStream} 26204library. @var{urngstr} is an arbitrary string to label a stream. It 26205need not be unique. 26206@end deftypefn 26207@end ifinfo 26208@ifnotinfo 26209@anchor{funct:unur_urng_rngstream_new} 26210@deftypefn {} {UNUR_URNG*} unur_urng_rngstream_new (const @var{char* urngstr}) 26211Make object for URNGs from Pierre L'Ecuyer's @file{RngStream} 26212library. @var{urngstr} is an arbitrary string to label a stream. It 26213need not be unique. 26214@end deftypefn 26215@end ifnotinfo 26216 26217@ifinfo 26218@anchor{funct:unur_urng_rngstreamptr_new} 26219@deftypefn Function {UNUR_URNG*} unur_urng_rngstreamptr_new (RngStream @var{rngstream}) 26220Similar to 26221@ifhtml 26222@ref{funct:unur_urng_rngstream_new,@command{unur_urng_rngstream_new}} 26223@end ifhtml 26224@ifnothtml 26225@command{unur_urng_rngstream_new} 26226@end ifnothtml 26227but it uses a pointer to a 26228generator object as returned by @code{RngStream_CreateStream()}. 26229@end deftypefn 26230@end ifinfo 26231@ifnotinfo 26232@anchor{funct:unur_urng_rngstreamptr_new} 26233@deftypefn {} {UNUR_URNG*} unur_urng_rngstreamptr_new (RngStream @var{rngstream}) 26234Similar to 26235@ifhtml 26236@ref{funct:unur_urng_rngstream_new,@command{unur_urng_rngstream_new}} 26237@end ifhtml 26238@ifnothtml 26239@command{unur_urng_rngstream_new} 26240@end ifnothtml 26241but it uses a pointer to a 26242generator object as returned by @code{RngStream_CreateStream()}. 26243@end deftypefn 26244@end ifnotinfo 26245 26246 26247 26248 26249@c 26250@c end of urng_rngstreams.h 26251@c ------------------------------------- 26252@c ------------------------------------- 26253@c urng_randomshift.h 26254@c 26255 26256@node URNG-RANDOMSHIFT 26257@section Combine point set generator with random shifts 26258 26259 26260Generators of type RANDOMSHIFT combine a point set generator with 26261generators to apply random shifts as proposed in 26262@ifhtml 26263@ref{bib:CPa76,, [CPa76]} 26264@end ifhtml 26265@ifnothtml 26266[CPa76] 26267@end ifnothtml 26268: 26269 26270@enumerate 26271@item 26272Sample and store a random vector S. 26273@item 26274Run a QMC simulation where S is added to each point of the 26275generated quasi-random point (mod 1). 26276@item 26277Repeat steps 1 and 2. 26278@end enumerate 26279 26280 26281@subsubheading How To Use 26282 26283 26284Create a URNG object for a point set generator and a URNG object 26285for a generator to create shift vectors at random. 26286The meta URNG object can then be created using 26287@ifhtml 26288@ref{funct:unur_urng_randomshift_new,@command{unur_urng_randomshift_new}.} 26289@end ifhtml 26290@ifnothtml 26291@command{unur_urng_randomshift_new}. 26292@end ifnothtml 26293Notice that only pointers to the two underlying URNG generator 26294objects are copied into the newly created meta generator. Thus 26295manipulating the meta URNG also changes the underlying URNGs 26296and vice versa. 26297 26298The following routines are supported for URNG objects of 26299type RANDOMSHIFT: 26300 26301@itemize @minus 26302@item 26303@ifhtml 26304@ref{funct:unur_urng_sample,@command{unur_urng_sample}} 26305@end ifhtml 26306@ifnothtml 26307@command{unur_urng_sample} 26308@end ifnothtml 26309@item 26310@ifhtml 26311@ref{funct:unur_urng_sample_array,@command{unur_urng_sample_array}} 26312@end ifhtml 26313@ifnothtml 26314@command{unur_urng_sample_array} 26315@end ifnothtml 26316@item 26317@ifhtml 26318@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 26319@end ifhtml 26320@ifnothtml 26321@command{unur_urng_reset} 26322@end ifnothtml 26323@item 26324@ifhtml 26325@ref{funct:unur_urng_sync,@command{unur_urng_sync}} 26326@end ifhtml 26327@ifnothtml 26328@command{unur_urng_sync} 26329@end ifnothtml 26330@item 26331@ifhtml 26332@ref{funct:unur_urng_randomshift_nextshift,@command{unur_urng_randomshift_nextshift}} 26333@end ifhtml 26334@ifnothtml 26335@command{unur_urng_randomshift_nextshift} 26336@end ifnothtml 26337@item 26338@ifhtml 26339@ref{funct:unur_urng_free,@command{unur_urng_free}} 26340@end ifhtml 26341@ifnothtml 26342@command{unur_urng_free} 26343@end ifnothtml 26344@end itemize 26345@ifhtml 26346@ref{funct:unur_urng_sync,@command{unur_urng_sync}} 26347@end ifhtml 26348@ifnothtml 26349@command{unur_urng_sync} 26350@end ifnothtml 26351is used to jump to the first coordinate of 26352the next point generated by the generator. 26353@ifhtml 26354@ref{funct:unur_urng_randomshift_nextshift,@command{unur_urng_randomshift_nextshift}} 26355@end ifhtml 26356@ifnothtml 26357@command{unur_urng_randomshift_nextshift} 26358@end ifnothtml 26359allows to replace the shift 26360vector by another randomly chosen shift vector. 26361 26362@emph{Important:} 26363@ifhtml 26364@ref{funct:unur_urng_sync,@command{unur_urng_sync}} 26365@end ifhtml 26366@ifnothtml 26367@command{unur_urng_sync} 26368@end ifnothtml 26369is only available if it is 26370if it is implemented for the underlying point set generator. 26371 26372@emph{Important:} 26373@ifhtml 26374@ref{funct:unur_urng_reset,@command{unur_urng_reset}} 26375@end ifhtml 26376@ifnothtml 26377@command{unur_urng_reset} 26378@end ifnothtml 26379is only available if it is 26380available for both underlying generators. 26381 26382 26383 26384 26385@subheading Function reference 26386 26387@ifhtml 26388@itemize 26389@item @ref{funct:unur_urng_randomshift_new,unur_urng_randomshift_new} 26390@item @ref{funct:unur_urng_randomshift_nextshift,unur_urng_randomshift_nextshift} 26391@end itemize 26392@end ifhtml 26393 26394 26395@ifinfo 26396@anchor{funct:unur_urng_randomshift_new} 26397@deftypefn Function {UNUR_URNG*} unur_urng_randomshift_new (UNUR_URNG* @var{qrng}, UNUR_URNG* @var{srng}, int @var{dim}) 26398Make object for URNG with randomly shifted point sets. 26399@var{qrng} is a generated that generates point sets of dimension @var{dim}. 26400@var{srng} is a generated that generates random numbers or vectors. 26401 26402@emph{Notice:} Only pointers to the respective objects @var{qrng} 26403and @var{srng} are copied into the created meta generator. Thus 26404manipulating the meta URNG also changes the underlying URNGs 26405and vice versa. 26406@end deftypefn 26407@end ifinfo 26408@ifnotinfo 26409@anchor{funct:unur_urng_randomshift_new} 26410@deftypefn {} {UNUR_URNG*} unur_urng_randomshift_new (UNUR_URNG* @var{qrng}, UNUR_URNG* @var{srng}, int @var{dim}) 26411Make object for URNG with randomly shifted point sets. 26412@var{qrng} is a generated that generates point sets of dimension @var{dim}. 26413@var{srng} is a generated that generates random numbers or vectors. 26414 26415@emph{Notice:} Only pointers to the respective objects @var{qrng} 26416and @var{srng} are copied into the created meta generator. Thus 26417manipulating the meta URNG also changes the underlying URNGs 26418and vice versa. 26419@end deftypefn 26420@end ifnotinfo 26421 26422@ifinfo 26423@anchor{funct:unur_urng_randomshift_nextshift} 26424@deftypefn Function {int} unur_urng_randomshift_nextshift (UNUR_URNG* @var{urng}) 26425Get the next (randomly chosen) vector for shifting the points set, and the 26426underlying point generator @var{qrng} is reset. 26427@end deftypefn 26428@end ifinfo 26429@ifnotinfo 26430@anchor{funct:unur_urng_randomshift_nextshift} 26431@deftypefn {} {int} unur_urng_randomshift_nextshift (UNUR_URNG* @var{urng}) 26432Get the next (randomly chosen) vector for shifting the points set, and the 26433underlying point generator @var{qrng} is reset. 26434@end deftypefn 26435@end ifnotinfo 26436 26437 26438 26439 26440@c 26441@c end of urng_randomshift.h 26442@c ------------------------------------- 26443@c ------------------------------------- 26444@c stddist.dh 26445@c 26446 26447@node Stddist 26448@chapter UNU.RAN Library of standard distributions 26449 26450@menu 26451* Stddist_CONT:: UNU.RAN Library of continuous univariate distributions 26452* Stddist_CVEC:: UNU.RAN Library of continuous multivariate distributions 26453* Stddist_DISCR:: UNU.RAN Library of discrete univariate distributions 26454* Stddist_MATR:: UNU.RAN Library of random matrices 26455@end menu 26456 26457 26458Although it is not its primary target, many 26459distributions are already implemented in UNU.RAN. 26460This section presents these available distributions 26461and their parameters. 26462 26463The syntax to get a distribuion object for distributions 26464@code{<dname>} is: 26465 26466@deftypefn -- {UNUR_DISTR*} unur_distr_@code{<dname>} (double* @var{params}, int @var{n_params}) 26467@var{params} is an array of doubles of size 26468@var{n_params} holding the parameters. 26469@end deftypefn 26470 26471@noindent 26472E.g. to get an object for the gamma distribution (with shape parameter) use 26473@smallexample 26474unur_distr_gamma( params, 1 ); 26475@end smallexample 26476 26477Distributions may have default parameters with need not be given 26478explicitely. 26479E.g. The gamma distribution has three parameters: the 26480shape, scale and location parameter. Only the (first) shape parameter 26481is required. The others can be omitted and are then set by default 26482values. 26483 26484@sp 1 26485@smallexample 26486/* alpha = 5; default: beta = 1, gamma = 0 */ 26487double fpar[] = @{5.@}; 26488unur_distr_gamma( fpar, 1 ); 26489 26490/* alpha = 5, beta = 3; default: gamma = 0 */ 26491double fpar[] = @{5., 3.@}; 26492unur_distr_gamma( fpar, 2 ); 26493 26494/* alpha = 5, beta = 3, gamma = -2 26495double fpar[] = @{5., 3., -2.@}; 26496unur_distr_gamma( fpar, 3 ); 26497@end smallexample 26498 26499@sp 1 26500@strong{Important:} Naturally the computational accuracy 26501limits the possible parameters. There shouldn't be problems 26502when the parameters of a distribution are in a ``reasonable'' range but 26503e.g. the normal distribution N(10^15,1) won't yield the desired results. 26504(In this case it would be better generating N(0,1) and @emph{then} 26505transform the results.) 26506@* Of course computational inaccuracy is not specific to UNU.RAN 26507and should always be kept in mind when working with computers. 26508 26509@emph{Important:} The routines of the standard library are included 26510for non-uniform random variate generation and not to provide special 26511functions for statistical computations. 26512 26513@subheading Remark 26514 26515The following keywords are used in the tables: 26516@table @i 26517@item PDF 26518probability density function, 26519with variable @i{x}. 26520 26521@item PMF 26522probability mass function, 26523with variable @i{k}. 26524 26525@item constant 26526normalization constant for given PDF and PMF, resp. 26527They must be multiplied by @i{constant} to get the 26528``real'' PDF and PMF. 26529 26530@item CDF 26531gives information whether the CDF is implemented in UNU.RAN. 26532 26533@item domain 26534domain PDF and PMF, resp. 26535 26536@item parameters @var{n_std} (@var{n_total}): @r{list} 26537list of parameters for distribution, where @var{n_std} is the number 26538of parameters for the standard form of the distribution and 26539@var{n_total} the total number for the (non-standard form of the) 26540distribution. @var{list} is the list of parameters in the order as 26541they are stored in the array of parameters. Optional parameter that 26542can be omitted are enclosed in square brackets @code{[@dots{}]}. 26543 26544A detailed list of these parameters gives then the range of valid 26545parameters and defaults for optional parameters that are used when 26546these are omitted. 26547 26548@item reference 26549gives reference for distribution 26550(@pxref{Bibliography}). 26551 26552@item special generators 26553lists available special generators for the distribution. 26554The first number is the variant that to be set by 26555@ifhtml 26556@ref{funct:unur_cstd_set_variant,@command{unur_cstd_set_variant}} 26557@end ifhtml 26558@ifnothtml 26559@command{unur_cstd_set_variant} 26560@end ifnothtml 26561and 26562@ifhtml 26563@ref{funct:unur_dstd_set_variant,@command{unur_dstd_set_variant}} 26564@end ifhtml 26565@ifnothtml 26566@command{unur_dstd_set_variant} 26567@end ifnothtml 26568call, respectively. 26569If no variant is set the default variant @code{DEF} is used. 26570In the table the respective abbreviations @code{DEF} and @code{INV} 26571are used for @code{UNUR_STDGEN_DEFAULT} and 26572@code{UNUR_STDGEN_INVERSION}. 26573Also the references for these methods are given (@pxref{Bibliography}). 26574 26575Notice that these generators might be slower than universal methods. 26576 26577If @code{DEF} is ommited, the first entry is the default generator. 26578 26579@end table 26580 26581 26582 26583@c 26584@c end of stddist.dh 26585@c ------------------------------------- 26586@c ------------------------------------- 26587@c stddist.dh 26588@c 26589 26590@page 26591@node Stddist_CONT 26592@section UNU.RAN Library of continuous univariate distributions 26593 26594@menu 26595* F:: F-distribution 26596* beta:: Beta distribution 26597* cauchy:: Cauchy distribution 26598* chi:: Chi distribution 26599* chisquare:: Chisquare distribution 26600* exponential:: Exponential distribution 26601* extremeI:: Extreme value type I (Gumbel-type) distribution 26602* extremeII:: Extreme value type II (Frechet-type) distribution 26603* gamma:: Gamma distribution 26604* gig:: Generalized Inverse Gaussian distribution 26605* gig2:: Generalized Inverse Gaussian distribution 26606* hyperbolic:: Hyperbolic distribution 26607* ig:: Inverse Gaussian distribution 26608* laplace:: Laplace distribution 26609* logistic:: Logistic distribution 26610* lognormal:: Log-Normal distribution 26611* lomax:: Lomax distribution (Pareto distribution of second kind) 26612* normal:: Normal distribution 26613* pareto:: Pareto distribution (of first kind) 26614* powerexponential:: Powerexponential (Subbotin) distribution 26615* rayleigh:: Rayleigh distribution 26616* slash:: Slash distribution 26617* student:: Student's t distribution 26618* triangular:: Triangular distribution 26619* uniform:: Uniform distribution 26620* weibull:: Weibull distribution 26621@end menu 26622 26623 26624@c 26625@c end of stddist.dh 26626@c ------------------------------------- 26627@c ------------------------------------- 26628@c unur_distributions.h 26629@c 26630 26631@node F 26632@subsection @code{F} -- F-distribution 26633@anchor{funct:unur_distr_F} 26634@findex unur_distr_F 26635 26636 26637@table @i 26638@item PDF: 26639@iftex 26640@tex 26641$(x^{\nu_1/2-1}) / (1+\nu_1/\nu_2 x)^{(\nu_1+\nu_2)/2}$ 26642@end tex 26643@end iftex 26644@ifnottex 26645(x^(nu_1/2-1)) / (1+nu_1/nu_2 x)^((nu_1+nu_2)/2) 26646@end ifnottex 26647 26648@item constant: 26649@iftex 26650@tex 26651$(\nu_1/\nu_2)^{\nu_1/2} / B(\nu_1/2,\nu_2/2)$ 26652@end tex 26653@end iftex 26654@ifnottex 26655(nu_1/nu_2)^(nu_1/2) / B(nu_1/2,nu_2/2) 26656@end ifnottex 26657 26658@item domain: 26659@iftex 26660@tex 26661$0 < x < \infty$ 26662@end tex 26663@end iftex 26664@ifnottex 266650 < x < infinity 26666@end ifnottex 26667 26668@iftex 26669@item parameters 2 (2): @r{ nu_1, nu_2} 26670@sp 1 26671@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 26672@item No. @tab name @tab @tab default 26673@item @code{[0]} 26674@tab@tex$\nu_1 $@end tex 26675@tab@tex$> 0 $@end tex 26676@tab 26677@tab (@i{scale}) 26678@item @code{[1]} 26679@tab@tex$\nu_2 $@end tex 26680@tab@tex$> 0 $@end tex 26681@tab 26682@tab (@i{scale}) 26683@end multitable 26684@end iftex 26685@ifnottex 26686@item parameters 2 (2): nu_1, nu_2 26687@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 26688@item No. @tab name @tab @tab default 26689@item @code{[0]} @tab nu_1 @tab > 0 @tab @tab @i{(scale)} 26690@item @code{[1]} @tab nu_2 @tab > 0 @tab @tab @i{(scale)} 26691@end multitable 26692@end ifnottex 26693@item reference: 26694@ifhtml 26695@ref{bib:JKBc95,, [JKBc95: Ch.27; p.322]} 26696@end ifhtml 26697@ifnothtml 26698[JKBc95: Ch.27; p.322] 26699@end ifnothtml 26700 26701@end table 26702 26703 26704@c 26705@c end of unur_distributions.h 26706@c ------------------------------------- 26707@c ------------------------------------- 26708@c unur_distributions.h 26709@c 26710 26711@node beta 26712@subsection @code{beta} -- Beta distribution 26713@anchor{funct:unur_distr_beta} 26714@findex unur_distr_beta 26715 26716 26717@table @i 26718@item PDF: 26719@iftex 26720@tex 26721$(x-a)^{p-1} \, (b-x)^{q-1}$ 26722@end tex 26723@end iftex 26724@ifnottex 26725(x-a)^(p-1) * (b-x)^(q-1) 26726@end ifnottex 26727 26728@item constant: 26729@iftex 26730@tex 26731$1 / (B(p,q) \, (b-a)^{p+q-1})$ 26732@end tex 26733@end iftex 26734@ifnottex 267351 / (B(p,q) * (b-a)^(p+q-1)) 26736@end ifnottex 26737 26738@item domain: 26739@iftex 26740@tex 26741$a < x < b$ 26742@end tex 26743@end iftex 26744@ifnottex 26745a < x < b 26746@end ifnottex 26747 26748@iftex 26749@item parameters 2 (4): @r{ p, q [, a, b ]} 26750@sp 1 26751@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 26752@item No. @tab name @tab @tab default 26753@item @code{[0]} 26754@tab@tex$p $@end tex 26755@tab@tex$> 0 $@end tex 26756@tab 26757@tab (@i{scale}) 26758@item @code{[1]} 26759@tab@tex$q $@end tex 26760@tab@tex$> 0 $@end tex 26761@tab 26762@tab (@i{scale}) 26763@item @code{[2]} 26764@tab@tex$a $@end tex 26765@tab@tex$ $@end tex 26766@tab 0 26767@tab (@i{location, scale}) 26768@item @code{[3]} 26769@tab@tex$b $@end tex 26770@tab@tex$> a $@end tex 26771@tab 1 26772@tab (@i{location, scale}) 26773@end multitable 26774@end iftex 26775@ifnottex 26776@item parameters 2 (4): p, q [, a, b ] 26777@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 26778@item No. @tab name @tab @tab default 26779@item @code{[0]} @tab p @tab > 0 @tab @tab @i{(scale)} 26780@item @code{[1]} @tab q @tab > 0 @tab @tab @i{(scale)} 26781@item @code{[2]} @tab a @tab @tab 0 @tab @i{(location, scale)} 26782@item @code{[3]} @tab b @tab > a @tab 1 @tab @i{(location, scale)} 26783@end multitable 26784@end ifnottex 26785@item reference: 26786@ifhtml 26787@ref{bib:JKBc95,, [JKBc95: Ch.25; p.210]} 26788@end ifhtml 26789@ifnothtml 26790[JKBc95: Ch.25; p.210] 26791@end ifnothtml 26792 26793@end table 26794 26795 26796@c 26797@c end of unur_distributions.h 26798@c ------------------------------------- 26799@c ------------------------------------- 26800@c unur_distributions.h 26801@c 26802 26803@node cauchy 26804@subsection @code{cauchy} -- Cauchy distribution 26805@anchor{funct:unur_distr_cauchy} 26806@findex unur_distr_cauchy 26807 26808 26809@table @i 26810@item PDF: 26811@iftex 26812@tex 26813$1/(1 + ((x-\theta)/\lambda)^2)$ 26814@end tex 26815@end iftex 26816@ifnottex 268171/(1 + ((x-theta)/lambda)^2) 26818@end ifnottex 26819 26820@item constant: 26821@iftex 26822@tex 26823$1/(\pi \, \lambda)$ 26824@end tex 26825@end iftex 26826@ifnottex 268271/(pi * lambda) 26828@end ifnottex 26829 26830@item domain: 26831@iftex 26832@tex 26833$-\infty < x < \infty$ 26834@end tex 26835@end iftex 26836@ifnottex 26837-infinity < x < infinity 26838@end ifnottex 26839 26840@iftex 26841@item parameters 0 (2): @r{ [ theta [, lambda ] ]} 26842@sp 1 26843@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 26844@item No. @tab name @tab @tab default 26845@item @code{[0]} 26846@tab@tex$\theta $@end tex 26847@tab@tex$ $@end tex 26848@tab 0 26849@tab (@i{location}) 26850@item @code{[1]} 26851@tab@tex$\lambda $@end tex 26852@tab@tex$> 0 $@end tex 26853@tab 1 26854@tab (@i{scale}) 26855@end multitable 26856@end iftex 26857@ifnottex 26858@item parameters 0 (2): [ theta [, lambda ] ] 26859@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 26860@item No. @tab name @tab @tab default 26861@item @code{[0]} @tab theta @tab @tab 0 @tab @i{(location)} 26862@item @code{[1]} @tab lambda @tab > 0 @tab 1 @tab @i{(scale)} 26863@end multitable 26864@end ifnottex 26865@item reference: 26866@ifhtml 26867@ref{bib:JKBb94,, [JKBb94: Ch.16; p.299]} 26868@end ifhtml 26869@ifnothtml 26870[JKBb94: Ch.16; p.299] 26871@end ifnothtml 26872 26873@item special generators: 26874@table @code 26875@item INV 26876Inversion method 26877@end table 26878 26879@end table 26880 26881 26882@c 26883@c end of unur_distributions.h 26884@c ------------------------------------- 26885@c ------------------------------------- 26886@c unur_distributions.h 26887@c 26888 26889@node chi 26890@subsection @code{chi} -- Chi distribution 26891@anchor{funct:unur_distr_chi} 26892@findex unur_distr_chi 26893 26894 26895@table @i 26896@item PDF: 26897@iftex 26898@tex 26899$x^{\nu-1} \, \exp( -x^2/2 )$ 26900@end tex 26901@end iftex 26902@ifnottex 26903x^(nu-1) * exp( -x^2/2 ) 26904@end ifnottex 26905 26906@item constant: 26907@iftex 26908@tex 26909$1 / (2^{(\nu/2)-1} \, \Gamma(\nu/2))$ 26910@end tex 26911@end iftex 26912@ifnottex 269131 / (2^((nu/2)-1) * Gamma(nu/2)) 26914@end ifnottex 26915 26916@item domain: 26917@iftex 26918@tex 26919$0 \leq x < \infty$ 26920@end tex 26921@end iftex 26922@ifnottex 269230 <= x < infinity 26924@end ifnottex 26925 26926@iftex 26927@item parameters 1 (1): @r{ nu} 26928@sp 1 26929@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 26930@item No. @tab name @tab @tab default 26931@item @code{[0]} 26932@tab@tex$\nu $@end tex 26933@tab@tex$> 0 $@end tex 26934@tab 26935@tab (@i{shape}) 26936@end multitable 26937@end iftex 26938@ifnottex 26939@item parameters 1 (1): nu 26940@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 26941@item No. @tab name @tab @tab default 26942@item @code{[0]} @tab nu @tab > 0 @tab @tab @i{(shape)} 26943@end multitable 26944@end ifnottex 26945@item reference: 26946@ifhtml 26947@ref{bib:JKBb94,, [JKBb94: Ch.18; p.417]} 26948@end ifhtml 26949@ifnothtml 26950[JKBb94: Ch.18; p.417] 26951@end ifnothtml 26952 26953@item special generators: 26954@table @code 26955@item DEF 26956@iftex 26957Ratio of Uniforms with shift (only for 26958@tex $\nu \geq 1$ 26959@end tex 26960) [MJa87] 26961@end iftex 26962@ifhtml 26963Ratio of Uniforms with shift (only for nu >= 1) @ref{bib:MJa87, [MJa87]} 26964@end ifhtml 26965@ifinfo 26966Ratio of Uniforms with shift (only for nu >= 1) [MJa87] 26967@end ifinfo 26968@end table 26969 26970@end table 26971 26972 26973@c 26974@c end of unur_distributions.h 26975@c ------------------------------------- 26976@c ------------------------------------- 26977@c unur_distributions.h 26978@c 26979 26980@node chisquare 26981@subsection @code{chisquare} -- Chisquare distribution 26982@anchor{funct:unur_distr_chisquare} 26983@findex unur_distr_chisquare 26984 26985 26986@table @i 26987@item PDF: 26988@iftex 26989@tex 26990$x^{(\nu/2)-1} \, \exp( -x/2 )$ 26991@end tex 26992@end iftex 26993@ifnottex 26994x^((nu/2)-1) * exp( -x/2 ) 26995@end ifnottex 26996 26997@item constant: 26998@iftex 26999@tex 27000$1 / (2^{\nu/2} \, \Gamma(\nu/2))$ 27001@end tex 27002@end iftex 27003@ifnottex 270041 / (2^(nu/2) * Gamma(nu/2)) 27005@end ifnottex 27006 27007@item domain: 27008@iftex 27009@tex 27010$0 \leq x < \infty$ 27011@end tex 27012@end iftex 27013@ifnottex 270140 <= x < infinity 27015@end ifnottex 27016 27017@iftex 27018@item parameters 1 (1): @r{ nu} 27019@sp 1 27020@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27021@item No. @tab name @tab @tab default 27022@item @code{[0]} 27023@tab@tex$\nu $@end tex 27024@tab@tex$> 0 $@end tex 27025@tab 27026@tab (@i{shape (degrees of freedom)}) 27027@end multitable 27028@end iftex 27029@ifnottex 27030@item parameters 1 (1): nu 27031@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27032@item No. @tab name @tab @tab default 27033@item @code{[0]} @tab nu @tab > 0 @tab @tab @i{(shape (degrees of freedom))} 27034@end multitable 27035@end ifnottex 27036@item reference: 27037@ifhtml 27038@ref{bib:JKBb94,, [JKBb94: Ch.18; p.416]} 27039@end ifhtml 27040@ifnothtml 27041[JKBb94: Ch.18; p.416] 27042@end ifnothtml 27043 27044@end table 27045 27046 27047@c 27048@c end of unur_distributions.h 27049@c ------------------------------------- 27050@c ------------------------------------- 27051@c unur_distributions.h 27052@c 27053 27054@node exponential 27055@subsection @code{exponential} -- Exponential distribution 27056@anchor{funct:unur_distr_exponential} 27057@findex unur_distr_exponential 27058 27059 27060@table @i 27061@item PDF: 27062@iftex 27063@tex 27064$\exp( -(x-\theta)/\sigma)$ 27065@end tex 27066@end iftex 27067@ifnottex 27068exp( -(x-theta)/sigma) 27069@end ifnottex 27070 27071@item constant: 27072@iftex 27073@tex 27074$1/\sigma$ 27075@end tex 27076@end iftex 27077@ifnottex 270781/sigma 27079@end ifnottex 27080 27081@item domain: 27082@iftex 27083@tex 27084$\theta \leq x < \infty$ 27085@end tex 27086@end iftex 27087@ifnottex 27088theta <= x < infinity 27089@end ifnottex 27090 27091@iftex 27092@item parameters 0 (2): @r{ [ sigma [, theta ] ]} 27093@sp 1 27094@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27095@item No. @tab name @tab @tab default 27096@item @code{[0]} 27097@tab@tex$\sigma $@end tex 27098@tab@tex$> 0 $@end tex 27099@tab 1 27100@tab (@i{scale}) 27101@item @code{[1]} 27102@tab@tex$\theta $@end tex 27103@tab@tex$ $@end tex 27104@tab 0 27105@tab (@i{location}) 27106@end multitable 27107@end iftex 27108@ifnottex 27109@item parameters 0 (2): [ sigma [, theta ] ] 27110@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27111@item No. @tab name @tab @tab default 27112@item @code{[0]} @tab sigma @tab > 0 @tab 1 @tab @i{(scale)} 27113@item @code{[1]} @tab theta @tab @tab 0 @tab @i{(location)} 27114@end multitable 27115@end ifnottex 27116@item reference: 27117@ifhtml 27118@ref{bib:JKBb94,, [JKBb94: Ch.19; p.494]} 27119@end ifhtml 27120@ifnothtml 27121[JKBb94: Ch.19; p.494] 27122@end ifnothtml 27123 27124@item special generators: 27125@table @code 27126@item INV 27127Inversion method 27128@end table 27129 27130@end table 27131 27132 27133@c 27134@c end of unur_distributions.h 27135@c ------------------------------------- 27136@c ------------------------------------- 27137@c unur_distributions.h 27138@c 27139 27140@node extremeI 27141@subsection @code{extremeI} -- Extreme value type I (Gumbel-type) distribution 27142@anchor{funct:unur_distr_extremeI} 27143@findex unur_distr_extremeI 27144 27145 27146@table @i 27147@item PDF: 27148@iftex 27149@tex 27150$\exp( -\exp( -{x-\zeta\over \theta} ) - {x-\zeta\over \theta} )$ 27151@end tex 27152@end iftex 27153@ifnottex 27154exp( -exp( -(x-zeta)/theta ) - (x-zeta)/theta ) 27155@end ifnottex 27156 27157@item constant: 27158@iftex 27159@tex 27160$1/\theta$ 27161@end tex 27162@end iftex 27163@ifnottex 271641/theta 27165@end ifnottex 27166 27167@item domain: 27168@iftex 27169@tex 27170$-\infty < x <\infty$ 27171@end tex 27172@end iftex 27173@ifnottex 27174-infinity < x <infinity 27175@end ifnottex 27176 27177@iftex 27178@item parameters 0 (2): @r{ [ zeta [, theta ] ]} 27179@sp 1 27180@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27181@item No. @tab name @tab @tab default 27182@item @code{[0]} 27183@tab@tex$\zeta $@end tex 27184@tab@tex$ $@end tex 27185@tab 0 27186@tab (@i{location}) 27187@item @code{[1]} 27188@tab@tex$\theta $@end tex 27189@tab@tex$> 0 $@end tex 27190@tab 1 27191@tab (@i{scale}) 27192@end multitable 27193@end iftex 27194@ifnottex 27195@item parameters 0 (2): [ zeta [, theta ] ] 27196@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27197@item No. @tab name @tab @tab default 27198@item @code{[0]} @tab zeta @tab @tab 0 @tab @i{(location)} 27199@item @code{[1]} @tab theta @tab > 0 @tab 1 @tab @i{(scale)} 27200@end multitable 27201@end ifnottex 27202@item reference: 27203@ifhtml 27204@ref{bib:JKBc95,, [JKBc95: Ch.22; p.2]} 27205@end ifhtml 27206@ifnothtml 27207[JKBc95: Ch.22; p.2] 27208@end ifnothtml 27209 27210@item special generators: 27211@table @code 27212@item INV 27213Inversion method 27214@end table 27215 27216@end table 27217 27218 27219@c 27220@c end of unur_distributions.h 27221@c ------------------------------------- 27222@c ------------------------------------- 27223@c unur_distributions.h 27224@c 27225 27226@node extremeII 27227@subsection @code{extremeII} -- Extreme value type II (Frechet-type) distribution 27228@anchor{funct:unur_distr_extremeII} 27229@findex unur_distr_extremeII 27230 27231 27232@table @i 27233@item PDF: 27234@iftex 27235@tex 27236$\exp( -({x-\zeta\over \theta})^{-k}) \, ({x-\zeta\over \theta})^{-k-1}$ 27237@end tex 27238@end iftex 27239@ifnottex 27240exp( -((x-zeta)/theta)^(-k)) * ((x-zeta)/theta)^(-k-1) 27241@end ifnottex 27242 27243@item constant: 27244@iftex 27245@tex 27246$k/\theta$ 27247@end tex 27248@end iftex 27249@ifnottex 27250k/theta 27251@end ifnottex 27252 27253@item domain: 27254@iftex 27255@tex 27256$\zeta < x <\infty$ 27257@end tex 27258@end iftex 27259@ifnottex 27260zeta < x <infinity 27261@end ifnottex 27262 27263@iftex 27264@item parameters 1 (3): @r{ k [, zeta [, theta ] ]} 27265@sp 1 27266@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27267@item No. @tab name @tab @tab default 27268@item @code{[0]} 27269@tab@tex$k $@end tex 27270@tab@tex$> 0 $@end tex 27271@tab 27272@tab (@i{shape}) 27273@item @code{[1]} 27274@tab@tex$\zeta $@end tex 27275@tab@tex$ $@end tex 27276@tab 0 27277@tab (@i{location}) 27278@item @code{[2]} 27279@tab@tex$\theta $@end tex 27280@tab@tex$> 0 $@end tex 27281@tab 1 27282@tab (@i{scale}) 27283@end multitable 27284@end iftex 27285@ifnottex 27286@item parameters 1 (3): k [, zeta [, theta ] ] 27287@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27288@item No. @tab name @tab @tab default 27289@item @code{[0]} @tab k @tab > 0 @tab @tab @i{(shape)} 27290@item @code{[1]} @tab zeta @tab @tab 0 @tab @i{(location)} 27291@item @code{[2]} @tab theta @tab > 0 @tab 1 @tab @i{(scale)} 27292@end multitable 27293@end ifnottex 27294@item reference: 27295@ifhtml 27296@ref{bib:JKBc95,, [JKBc95: Ch.22; p.2]} 27297@end ifhtml 27298@ifnothtml 27299[JKBc95: Ch.22; p.2] 27300@end ifnothtml 27301 27302@item special generators: 27303@table @code 27304@item INV 27305Inversion method 27306@end table 27307 27308@end table 27309 27310 27311@c 27312@c end of unur_distributions.h 27313@c ------------------------------------- 27314@c ------------------------------------- 27315@c unur_distributions.h 27316@c 27317 27318@node gamma 27319@subsection @code{gamma} -- Gamma distribution 27320@anchor{funct:unur_distr_gamma} 27321@findex unur_distr_gamma 27322 27323 27324@table @i 27325@item PDF: 27326@iftex 27327@tex 27328$({x-\gamma\over \beta})^{\alpha-1} \, \exp( -{x-\gamma\over \beta} )$ 27329@end tex 27330@end iftex 27331@ifnottex 27332((x-gamma)/beta)^(alpha-1) * exp( -(x-gamma)/beta ) 27333@end ifnottex 27334 27335@item constant: 27336@iftex 27337@tex 27338$1 / (\beta \, \Gamma(\alpha))$ 27339@end tex 27340@end iftex 27341@ifnottex 273421 / (beta * Gamma(alpha)) 27343@end ifnottex 27344 27345@item domain: 27346@iftex 27347@tex 27348$\gamma < x < \infty$ 27349@end tex 27350@end iftex 27351@ifnottex 27352gamma < x < infinity 27353@end ifnottex 27354 27355@iftex 27356@item parameters 1 (3): @r{ alpha [, beta [, gamma ] ]} 27357@sp 1 27358@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27359@item No. @tab name @tab @tab default 27360@item @code{[0]} 27361@tab@tex$\alpha $@end tex 27362@tab@tex$> 0 $@end tex 27363@tab 27364@tab (@i{shape}) 27365@item @code{[1]} 27366@tab@tex$\beta $@end tex 27367@tab@tex$> 0 $@end tex 27368@tab 1 27369@tab (@i{scale}) 27370@item @code{[2]} 27371@tab@tex$\gamma $@end tex 27372@tab@tex$ $@end tex 27373@tab 0 27374@tab (@i{location}) 27375@end multitable 27376@end iftex 27377@ifnottex 27378@item parameters 1 (3): alpha [, beta [, gamma ] ] 27379@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27380@item No. @tab name @tab @tab default 27381@item @code{[0]} @tab alpha @tab > 0 @tab @tab @i{(shape)} 27382@item @code{[1]} @tab beta @tab > 0 @tab 1 @tab @i{(scale)} 27383@item @code{[2]} @tab gamma @tab @tab 0 @tab @i{(location)} 27384@end multitable 27385@end ifnottex 27386@item reference: 27387@ifhtml 27388@ref{bib:JKBb94,, [JKBb94: Ch.17; p.337]} 27389@end ifhtml 27390@ifnothtml 27391[JKBb94: Ch.17; p.337] 27392@end ifnothtml 27393 27394@item special generators: 27395@table @code 27396@item DEF 27397@iftex 27398Acceptance Rejection combined with Acceptance Complement [ADa74] [ADa82] 27399@end iftex 27400@ifhtml 27401Acceptance Rejection combined with Acceptance Complement @ref{bib:ADa74, [ADa74]} @ref{bib:ADa82, [ADa82]} 27402@end ifhtml 27403@ifinfo 27404Acceptance Rejection combined with Acceptance Complement [ADa74] [ADa82] 27405@end ifinfo 27406@item 2 27407@iftex 27408Rejection from \log-\logistic envelopes [CHa77] 27409@end iftex 27410@ifhtml 27411Rejection from log-logistic envelopes @ref{bib:CHa77, [CHa77]} 27412@end ifhtml 27413@ifinfo 27414Rejection from log-logistic envelopes [CHa77] 27415@end ifinfo 27416@end table 27417 27418@end table 27419 27420 27421@c 27422@c end of unur_distributions.h 27423@c ------------------------------------- 27424@c ------------------------------------- 27425@c unur_distributions.h 27426@c 27427 27428@node gig 27429@subsection @code{gig} -- Generalized Inverse Gaussian distribution 27430@anchor{funct:unur_distr_gig} 27431@findex unur_distr_gig 27432 27433 27434@table @i 27435@item PDF: 27436@iftex 27437@tex 27438$x^{\theta-1} \, \exp( -{1\over 2} \, \omega \, ({x\over \eta} + {\eta\over x}))$ 27439@end tex 27440@end iftex 27441@ifnottex 27442x^(theta-1) * exp( -1/2 * omega * (x/eta + eta/x)) 27443@end ifnottex 27444 27445@item constant: 27446@iftex 27447@tex 27448not implemented! 27449@end tex 27450@end iftex 27451@ifnottex 27452not implemented! 27453@end ifnottex 27454 27455@item CDF: 27456@iftex 27457@tex 27458not implemented! 27459@end tex 27460@end iftex 27461@ifnottex 27462not implemented! 27463@end ifnottex 27464 27465@item domain: 27466@iftex 27467@tex 27468$0 < x <\infty$ 27469@end tex 27470@end iftex 27471@ifnottex 274720 < x <infinity 27473@end ifnottex 27474 27475@iftex 27476@item parameters 2 (3): @r{ theta, omega [, eta ]} 27477@sp 1 27478@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27479@item No. @tab name @tab @tab default 27480@item @code{[0]} 27481@tab@tex$\theta $@end tex 27482@tab@tex$ $@end tex 27483@tab 27484@tab (@i{shape}) 27485@item @code{[1]} 27486@tab@tex$\omega $@end tex 27487@tab@tex$> 0 $@end tex 27488@tab 27489@tab (@i{scale}) 27490@item @code{[2]} 27491@tab@tex$\eta $@end tex 27492@tab@tex$> 0 $@end tex 27493@tab 1 27494@tab (@i{shape}) 27495@end multitable 27496@end iftex 27497@ifnottex 27498@item parameters 2 (3): theta, omega [, eta ] 27499@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27500@item No. @tab name @tab @tab default 27501@item @code{[0]} @tab theta @tab @tab @tab @i{(shape)} 27502@item @code{[1]} @tab omega @tab > 0 @tab @tab @i{(scale)} 27503@item @code{[2]} @tab eta @tab > 0 @tab 1 @tab @i{(shape)} 27504@end multitable 27505@end ifnottex 27506@item reference: 27507@ifhtml 27508@ref{bib:JKBb94,, [JKBb94: Ch.15; p.84]} 27509@end ifhtml 27510@ifnothtml 27511[JKBb94: Ch.15; p.84] 27512@end ifnothtml 27513 27514@item special generators: 27515@table @code 27516@item DEF 27517@iftex 27518Ratio-of-Uniforms method [Dag89] 27519@end iftex 27520@ifhtml 27521Ratio-of-Uniforms method @ref{bib:Dag89, [Dag89]} 27522@end ifhtml 27523@ifinfo 27524Ratio-of-Uniforms method [Dag89] 27525@end ifinfo 27526@end table 27527 27528@end table 27529 27530 27531@c 27532@c end of unur_distributions.h 27533@c ------------------------------------- 27534@c ------------------------------------- 27535@c unur_distributions.h 27536@c 27537 27538@node gig2 27539@subsection @code{gig2} -- Generalized Inverse Gaussian distribution 27540@anchor{funct:unur_distr_gig2} 27541@findex unur_distr_gig2 27542 27543 27544@table @i 27545@item PDF: 27546@iftex 27547@tex 27548$x^{\theta-1} \, \exp( -{1\over 2} \, ({\chi\over x} + \psi\, x))$ 27549@end tex 27550@end iftex 27551@ifnottex 27552x^(theta-1) * exp( -1/2 * (chi/x + psi*x)) 27553@end ifnottex 27554 27555@item constant: 27556@iftex 27557@tex 27558not implemented! 27559@end tex 27560@end iftex 27561@ifnottex 27562not implemented! 27563@end ifnottex 27564 27565@item CDF: 27566@iftex 27567@tex 27568not implemented! 27569@end tex 27570@end iftex 27571@ifnottex 27572not implemented! 27573@end ifnottex 27574 27575@item domain: 27576@iftex 27577@tex 27578$0 < x <\infty$ 27579@end tex 27580@end iftex 27581@ifnottex 275820 < x <infinity 27583@end ifnottex 27584 27585@iftex 27586@item parameters 3 (3): @r{ theta, psi, chi} 27587@sp 1 27588@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27589@item No. @tab name @tab @tab default 27590@item @code{[0]} 27591@tab@tex$\theta $@end tex 27592@tab@tex$ $@end tex 27593@tab 27594@tab (@i{shape}) 27595@item @code{[1]} 27596@tab@tex$\psi $@end tex 27597@tab@tex$> 0 $@end tex 27598@tab 27599@tab (@i{shape}) 27600@item @code{[2]} 27601@tab@tex$\chi $@end tex 27602@tab@tex$> 0 $@end tex 27603@tab 27604@tab (@i{shape}) 27605@end multitable 27606@end iftex 27607@ifnottex 27608@item parameters 3 (3): theta, psi, chi 27609@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27610@item No. @tab name @tab @tab default 27611@item @code{[0]} @tab theta @tab @tab @tab @i{(shape)} 27612@item @code{[1]} @tab psi @tab > 0 @tab @tab @i{(shape)} 27613@item @code{[2]} @tab chi @tab > 0 @tab @tab @i{(shape)} 27614@end multitable 27615@end ifnottex 27616@item reference: 27617@ifhtml 27618@ref{bib:JKBb94,, [JKBb94: Ch.15; p.84]} 27619@end ifhtml 27620@ifnothtml 27621[JKBb94: Ch.15; p.84] 27622@end ifnothtml 27623 27624@end table 27625 27626 27627@c 27628@c end of unur_distributions.h 27629@c ------------------------------------- 27630@c ------------------------------------- 27631@c unur_distributions.h 27632@c 27633 27634@node hyperbolic 27635@subsection @code{hyperbolic} -- Hyperbolic distribution 27636@anchor{funct:unur_distr_hyperbolic} 27637@findex unur_distr_hyperbolic 27638 27639 27640@table @i 27641@item PDF: 27642@iftex 27643@tex 27644$\exp( -\alpha \, \sqrt{\delta^2 + (x - \mu)^2} + \beta\, (x-\mu) )$ 27645@end tex 27646@end iftex 27647@ifnottex 27648exp( -alpha * sqrt(delta^2 + (x - mu)^2) + beta*(x-mu) ) 27649@end ifnottex 27650 27651@item constant: 27652@iftex 27653@tex 27654not implemented! 27655@end tex 27656@end iftex 27657@ifnottex 27658not implemented! 27659@end ifnottex 27660 27661@item CDF: 27662@iftex 27663@tex 27664not implemented! 27665@end tex 27666@end iftex 27667@ifnottex 27668not implemented! 27669@end ifnottex 27670 27671@item domain: 27672@iftex 27673@tex 27674$-\infty < x <\infty$ 27675@end tex 27676@end iftex 27677@ifnottex 27678-infinity < x <infinity 27679@end ifnottex 27680 27681@iftex 27682@item parameters 4 (4): @r{ alpha, beta, delta, mu} 27683@sp 1 27684@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27685@item No. @tab name @tab @tab default 27686@item @code{[0]} 27687@tab@tex$\alpha $@end tex 27688@tab@tex$>|\beta| $@end tex 27689@tab 27690@tab (@i{shape (tail)}) 27691@item @code{[1]} 27692@tab@tex$\beta $@end tex 27693@tab@tex$ $@end tex 27694@tab 27695@tab (@i{shape (asymmetry)}) 27696@item @code{[2]} 27697@tab@tex$\delta $@end tex 27698@tab@tex$> 0 $@end tex 27699@tab 27700@tab (@i{scale}) 27701@item @code{[3]} 27702@tab@tex$\mu $@end tex 27703@tab@tex$ $@end tex 27704@tab 27705@tab (@i{location}) 27706@end multitable 27707@end iftex 27708@ifnottex 27709@item parameters 4 (4): alpha, beta, delta, mu 27710@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27711@item No. @tab name @tab @tab default 27712@item @code{[0]} @tab alpha @tab >|beta| @tab @tab @i{(shape (tail))} 27713@item @code{[1]} @tab beta @tab @tab @tab @i{(shape (asymmetry))} 27714@item @code{[2]} @tab delta @tab > 0 @tab @tab @i{(scale)} 27715@item @code{[3]} @tab mu @tab @tab @tab @i{(location)} 27716@end multitable 27717@end ifnottex 27718@end table 27719 27720 27721@c 27722@c end of unur_distributions.h 27723@c ------------------------------------- 27724@c ------------------------------------- 27725@c unur_distributions.h 27726@c 27727 27728@node ig 27729@subsection @code{ig} -- Inverse Gaussian distribution 27730@anchor{funct:unur_distr_ig} 27731@findex unur_distr_ig 27732 27733 27734@table @i 27735@item PDF: 27736@iftex 27737@tex 27738$\sqrt{ {\lambda\over 2\, \pi\, x^3} } \, \exp( -{\lambda\, (x-\mu)^2\over 2\, \mu^2\, x} )$ 27739@end tex 27740@end iftex 27741@ifnottex 27742sqrt( lambda/2*pi*x^3 ) * exp( -(lambda*(x-mu)^2)/2*mu^2*x ) 27743@end ifnottex 27744 27745@item constant: 27746@iftex 27747@tex 27748$1$ 27749@end tex 27750@end iftex 27751@ifnottex 277521 27753@end ifnottex 27754 27755@item CDF: 27756@iftex 27757@tex 27758not implemented! 27759@end tex 27760@end iftex 27761@ifnottex 27762not implemented! 27763@end ifnottex 27764 27765@item domain: 27766@iftex 27767@tex 27768$0 < x <\infty$ 27769@end tex 27770@end iftex 27771@ifnottex 277720 < x <infinity 27773@end ifnottex 27774 27775@iftex 27776@item parameters 2 (2): @r{ mu, lambda} 27777@sp 1 27778@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27779@item No. @tab name @tab @tab default 27780@item @code{[0]} 27781@tab@tex$\mu $@end tex 27782@tab@tex$> 0 $@end tex 27783@tab 27784@tab (@i{mean}) 27785@item @code{[1]} 27786@tab@tex$\lambda $@end tex 27787@tab@tex$> 0 $@end tex 27788@tab 27789@tab (@i{shape}) 27790@end multitable 27791@end iftex 27792@ifnottex 27793@item parameters 2 (2): mu, lambda 27794@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27795@item No. @tab name @tab @tab default 27796@item @code{[0]} @tab mu @tab > 0 @tab @tab @i{(mean)} 27797@item @code{[1]} @tab lambda @tab > 0 @tab @tab @i{(shape)} 27798@end multitable 27799@end ifnottex 27800@item reference: 27801@ifhtml 27802@ref{bib:JKBb94,, [JKBb94: Ch.15; p.259]} 27803@end ifhtml 27804@ifnothtml 27805[JKBb94: Ch.15; p.259] 27806@end ifnothtml 27807 27808@end table 27809 27810 27811@c 27812@c end of unur_distributions.h 27813@c ------------------------------------- 27814@c ------------------------------------- 27815@c unur_distributions.h 27816@c 27817 27818@node laplace 27819@subsection @code{laplace} -- Laplace distribution 27820@anchor{funct:unur_distr_laplace} 27821@findex unur_distr_laplace 27822 27823 27824@table @i 27825@item PDF: 27826@iftex 27827@tex 27828$\exp( -|x-\theta| / \phi )$ 27829@end tex 27830@end iftex 27831@ifnottex 27832exp( -|x-theta| / phi ) 27833@end ifnottex 27834 27835@item constant: 27836@iftex 27837@tex 27838$1/(2 \, \phi)$ 27839@end tex 27840@end iftex 27841@ifnottex 278421/(2 * phi) 27843@end ifnottex 27844 27845@item domain: 27846@iftex 27847@tex 27848$-\infty < x <\infty$ 27849@end tex 27850@end iftex 27851@ifnottex 27852-infinity < x <infinity 27853@end ifnottex 27854 27855@iftex 27856@item parameters 0 (2): @r{ [ theta [, phi ] ]} 27857@sp 1 27858@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27859@item No. @tab name @tab @tab default 27860@item @code{[0]} 27861@tab@tex$\theta $@end tex 27862@tab@tex$ $@end tex 27863@tab 0 27864@tab (@i{location}) 27865@item @code{[1]} 27866@tab@tex$\phi $@end tex 27867@tab@tex$> 0 $@end tex 27868@tab 1 27869@tab (@i{scale}) 27870@end multitable 27871@end iftex 27872@ifnottex 27873@item parameters 0 (2): [ theta [, phi ] ] 27874@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27875@item No. @tab name @tab @tab default 27876@item @code{[0]} @tab theta @tab @tab 0 @tab @i{(location)} 27877@item @code{[1]} @tab phi @tab > 0 @tab 1 @tab @i{(scale)} 27878@end multitable 27879@end ifnottex 27880@item reference: 27881@ifhtml 27882@ref{bib:JKBc95,, [JKBc95: Ch.24; p.164]} 27883@end ifhtml 27884@ifnothtml 27885[JKBc95: Ch.24; p.164] 27886@end ifnothtml 27887 27888@item special generators: 27889@table @code 27890@item INV 27891Inversion method 27892@end table 27893 27894@end table 27895 27896 27897@c 27898@c end of unur_distributions.h 27899@c ------------------------------------- 27900@c ------------------------------------- 27901@c unur_distributions.h 27902@c 27903 27904@node logistic 27905@subsection @code{logistic} -- Logistic distribution 27906@anchor{funct:unur_distr_logistic} 27907@findex unur_distr_logistic 27908 27909 27910@table @i 27911@item PDF: 27912@iftex 27913@tex 27914$\exp(-{x-\alpha\over \beta}) \, (1 + \exp(-{x-\alpha\over \beta}))^{-2}$ 27915@end tex 27916@end iftex 27917@ifnottex 27918exp(-(x-alpha)/beta) * (1 + exp(-(x-alpha)/beta))^(-2) 27919@end ifnottex 27920 27921@item constant: 27922@iftex 27923@tex 27924$1/\beta$ 27925@end tex 27926@end iftex 27927@ifnottex 279281/beta 27929@end ifnottex 27930 27931@item domain: 27932@iftex 27933@tex 27934$-\infty < x <\infty$ 27935@end tex 27936@end iftex 27937@ifnottex 27938-infinity < x <infinity 27939@end ifnottex 27940 27941@iftex 27942@item parameters 0 (2): @r{ [ alpha [, beta ] ]} 27943@sp 1 27944@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27945@item No. @tab name @tab @tab default 27946@item @code{[0]} 27947@tab@tex$\alpha $@end tex 27948@tab@tex$ $@end tex 27949@tab 0 27950@tab (@i{location}) 27951@item @code{[1]} 27952@tab@tex$\beta $@end tex 27953@tab@tex$> 0 $@end tex 27954@tab 1 27955@tab (@i{scale}) 27956@end multitable 27957@end iftex 27958@ifnottex 27959@item parameters 0 (2): [ alpha [, beta ] ] 27960@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 27961@item No. @tab name @tab @tab default 27962@item @code{[0]} @tab alpha @tab @tab 0 @tab @i{(location)} 27963@item @code{[1]} @tab beta @tab > 0 @tab 1 @tab @i{(scale)} 27964@end multitable 27965@end ifnottex 27966@item reference: 27967@ifhtml 27968@ref{bib:JKBc95,, [JKBc95: Ch.23; p.115]} 27969@end ifhtml 27970@ifnothtml 27971[JKBc95: Ch.23; p.115] 27972@end ifnothtml 27973 27974@item special generators: 27975@table @code 27976@item INV 27977Inversion method 27978@end table 27979 27980@end table 27981 27982 27983@c 27984@c end of unur_distributions.h 27985@c ------------------------------------- 27986@c ------------------------------------- 27987@c unur_distributions.h 27988@c 27989 27990@node lognormal 27991@subsection @code{lognormal} -- Log-Normal distribution 27992@anchor{funct:unur_distr_lognormal} 27993@findex unur_distr_lognormal 27994 27995 27996@table @i 27997@item PDF: 27998@iftex 27999@tex 28000$1/(x-\theta) \, \exp( -(\log(x-\theta)-\zeta)^2/(2 \sigma^2) )$ 28001@end tex 28002@end iftex 28003@ifnottex 280041/(x-theta) * exp( -(log(x-theta)-zeta)^2/(2 sigma^2) ) 28005@end ifnottex 28006 28007@item constant: 28008@iftex 28009@tex 28010$1/(\sigma \, \sqrt{2 \pi})$ 28011@end tex 28012@end iftex 28013@ifnottex 280141/(sigma * sqrt(2 pi)) 28015@end ifnottex 28016 28017@item domain: 28018@iftex 28019@tex 28020$\theta \leq x < \infty$ 28021@end tex 28022@end iftex 28023@ifnottex 28024theta <= x < infinity 28025@end ifnottex 28026 28027@iftex 28028@item parameters 2 (3): @r{ zeta, sigma [, theta ]} 28029@sp 1 28030@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28031@item No. @tab name @tab @tab default 28032@item @code{[0]} 28033@tab@tex$\zeta $@end tex 28034@tab@tex$ $@end tex 28035@tab 28036@tab (@i{shape}) 28037@item @code{[1]} 28038@tab@tex$\sigma $@end tex 28039@tab@tex$> 0 $@end tex 28040@tab 28041@tab (@i{shape}) 28042@item @code{[2]} 28043@tab@tex$\theta $@end tex 28044@tab@tex$ $@end tex 28045@tab 0 28046@tab (@i{location}) 28047@end multitable 28048@end iftex 28049@ifnottex 28050@item parameters 2 (3): zeta, sigma [, theta ] 28051@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28052@item No. @tab name @tab @tab default 28053@item @code{[0]} @tab zeta @tab @tab @tab @i{(shape)} 28054@item @code{[1]} @tab sigma @tab > 0 @tab @tab @i{(shape)} 28055@item @code{[2]} @tab theta @tab @tab 0 @tab @i{(location)} 28056@end multitable 28057@end ifnottex 28058@item reference: 28059@ifhtml 28060@ref{bib:JKBb94,, [JKBb94: Ch.14; p. 208]} 28061@end ifhtml 28062@ifnothtml 28063[JKBb94: Ch.14; p. 208] 28064@end ifnothtml 28065 28066@end table 28067 28068 28069@c 28070@c end of unur_distributions.h 28071@c ------------------------------------- 28072@c ------------------------------------- 28073@c unur_distributions.h 28074@c 28075 28076@node lomax 28077@subsection @code{lomax} -- Lomax distribution (Pareto distribution of second kind) 28078@anchor{funct:unur_distr_lomax} 28079@findex unur_distr_lomax 28080 28081 28082@table @i 28083@item PDF: 28084@iftex 28085@tex 28086$(x+C)^{-(a+1)}$ 28087@end tex 28088@end iftex 28089@ifnottex 28090(x+C)^(-(a+1)) 28091@end ifnottex 28092 28093@item constant: 28094@iftex 28095@tex 28096$a \, C^a$ 28097@end tex 28098@end iftex 28099@ifnottex 28100a * C^a 28101@end ifnottex 28102 28103@item domain: 28104@iftex 28105@tex 28106$0 \leq x < \infty$ 28107@end tex 28108@end iftex 28109@ifnottex 281100 <= x < infinity 28111@end ifnottex 28112 28113@iftex 28114@item parameters 1 (2): @r{ a [, C ]} 28115@sp 1 28116@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28117@item No. @tab name @tab @tab default 28118@item @code{[0]} 28119@tab@tex$a $@end tex 28120@tab@tex$> 0 $@end tex 28121@tab 28122@tab (@i{shape}) 28123@item @code{[1]} 28124@tab@tex$C $@end tex 28125@tab@tex$> 0 $@end tex 28126@tab 1 28127@tab (@i{scale}) 28128@end multitable 28129@end iftex 28130@ifnottex 28131@item parameters 1 (2): a [, C ] 28132@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28133@item No. @tab name @tab @tab default 28134@item @code{[0]} @tab a @tab > 0 @tab @tab @i{(shape)} 28135@item @code{[1]} @tab C @tab > 0 @tab 1 @tab @i{(scale)} 28136@end multitable 28137@end ifnottex 28138@item reference: 28139@ifhtml 28140@ref{bib:JKBb94,, [JKBb94: Ch.20; p.575]} 28141@end ifhtml 28142@ifnothtml 28143[JKBb94: Ch.20; p.575] 28144@end ifnothtml 28145 28146@item special generators: 28147@table @code 28148@item INV 28149Inversion method 28150@end table 28151 28152@end table 28153 28154 28155@c 28156@c end of unur_distributions.h 28157@c ------------------------------------- 28158@c ------------------------------------- 28159@c unur_distributions.h 28160@c 28161 28162@node normal 28163@subsection @code{normal} -- Normal distribution 28164@anchor{funct:unur_distr_normal} 28165@findex unur_distr_normal 28166 28167 28168@table @i 28169@item PDF: 28170@iftex 28171@tex 28172$\exp( -{1\over 2} \, ({x-\mu\over \sigma})^2 )$ 28173@end tex 28174@end iftex 28175@ifnottex 28176exp( -1/2 * ((x-mu)/sigma)^2 ) 28177@end ifnottex 28178 28179@item constant: 28180@iftex 28181@tex 28182$1 / (\sigma \, \sqrt{2 \pi})$ 28183@end tex 28184@end iftex 28185@ifnottex 281861 / (sigma * sqrt(2 pi)) 28187@end ifnottex 28188 28189@item domain: 28190@iftex 28191@tex 28192$-\infty < x < \infty$ 28193@end tex 28194@end iftex 28195@ifnottex 28196-infinity < x < infinity 28197@end ifnottex 28198 28199@iftex 28200@item parameters 0 (2): @r{ [ mu [, sigma ] ]} 28201@sp 1 28202@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28203@item No. @tab name @tab @tab default 28204@item @code{[0]} 28205@tab@tex$\mu $@end tex 28206@tab@tex$ $@end tex 28207@tab 0 28208@tab (@i{location}) 28209@item @code{[1]} 28210@tab@tex$\sigma $@end tex 28211@tab@tex$> 0 $@end tex 28212@tab 1 28213@tab (@i{scale}) 28214@end multitable 28215@end iftex 28216@ifnottex 28217@item parameters 0 (2): [ mu [, sigma ] ] 28218@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28219@item No. @tab name @tab @tab default 28220@item @code{[0]} @tab mu @tab @tab 0 @tab @i{(location)} 28221@item @code{[1]} @tab sigma @tab > 0 @tab 1 @tab @i{(scale)} 28222@end multitable 28223@end ifnottex 28224@item reference: 28225@ifhtml 28226@ref{bib:JKBb94,, [JKBb94: Ch.13; p.80]} 28227@end ifhtml 28228@ifnothtml 28229[JKBb94: Ch.13; p.80] 28230@end ifnothtml 28231 28232@item special generators: 28233@table @code 28234@item DEF 28235@iftex 28236ACR method (Acceptance-Complement Ratio) [HDa90] 28237@end iftex 28238@ifhtml 28239ACR method (Acceptance-Complement Ratio) @ref{bib:HDa90, [HDa90]} 28240@end ifhtml 28241@ifinfo 28242ACR method (Acceptance-Complement Ratio) [HDa90] 28243@end ifinfo 28244@item 1 28245@iftex 28246Box-Muller method [BMa58] 28247@end iftex 28248@ifhtml 28249Box-Muller method @ref{bib:BMa58, [BMa58]} 28250@end ifhtml 28251@ifinfo 28252Box-Muller method [BMa58] 28253@end ifinfo 28254@item 2 28255@iftex 28256Polar method with rejection [MGa62] 28257@end iftex 28258@ifhtml 28259Polar method with rejection @ref{bib:MGa62, [MGa62]} 28260@end ifhtml 28261@ifinfo 28262Polar method with rejection [MGa62] 28263@end ifinfo 28264@item 3 28265@iftex 28266Kindermann-Ramage method [KRa76] 28267@end iftex 28268@ifhtml 28269Kindermann-Ramage method @ref{bib:KRa76, [KRa76]} 28270@end ifhtml 28271@ifinfo 28272Kindermann-Ramage method [KRa76] 28273@end ifinfo 28274@item INV 28275Inversion method (slow) 28276@end table 28277 28278@end table 28279 28280 28281@c 28282@c end of unur_distributions.h 28283@c ------------------------------------- 28284@c ------------------------------------- 28285@c unur_distributions.h 28286@c 28287 28288@node pareto 28289@subsection @code{pareto} -- Pareto distribution (of first kind) 28290@anchor{funct:unur_distr_pareto} 28291@findex unur_distr_pareto 28292 28293 28294@table @i 28295@item PDF: 28296@iftex 28297@tex 28298$x^{-(a+1)}$ 28299@end tex 28300@end iftex 28301@ifnottex 28302x^(-(a+1)) 28303@end ifnottex 28304 28305@item constant: 28306@iftex 28307@tex 28308$a \, k^a$ 28309@end tex 28310@end iftex 28311@ifnottex 28312a * k^a 28313@end ifnottex 28314 28315@item domain: 28316@iftex 28317@tex 28318$k < x < \infty$ 28319@end tex 28320@end iftex 28321@ifnottex 28322k < x < infinity 28323@end ifnottex 28324 28325@iftex 28326@item parameters 2 (2): @r{ k, a} 28327@sp 1 28328@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28329@item No. @tab name @tab @tab default 28330@item @code{[0]} 28331@tab@tex$k $@end tex 28332@tab@tex$> 0 $@end tex 28333@tab 28334@tab (@i{shape, location}) 28335@item @code{[1]} 28336@tab@tex$a $@end tex 28337@tab@tex$> 0 $@end tex 28338@tab 28339@tab (@i{shape}) 28340@end multitable 28341@end iftex 28342@ifnottex 28343@item parameters 2 (2): k, a 28344@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28345@item No. @tab name @tab @tab default 28346@item @code{[0]} @tab k @tab > 0 @tab @tab @i{(shape, location)} 28347@item @code{[1]} @tab a @tab > 0 @tab @tab @i{(shape)} 28348@end multitable 28349@end ifnottex 28350@item reference: 28351@ifhtml 28352@ref{bib:JKBb94,, [JKBb94: Ch.20; p.574]} 28353@end ifhtml 28354@ifnothtml 28355[JKBb94: Ch.20; p.574] 28356@end ifnothtml 28357 28358@item special generators: 28359@table @code 28360@item INV 28361Inversion method 28362@end table 28363 28364@end table 28365 28366 28367@c 28368@c end of unur_distributions.h 28369@c ------------------------------------- 28370@c ------------------------------------- 28371@c unur_distributions.h 28372@c 28373 28374@node powerexponential 28375@subsection @code{powerexponential} -- Powerexponential (Subbotin) distribution 28376@anchor{funct:unur_distr_powerexponential} 28377@findex unur_distr_powerexponential 28378 28379 28380@table @i 28381@item PDF: 28382@iftex 28383@tex 28384$\exp( -|x|^\tau )$ 28385@end tex 28386@end iftex 28387@ifnottex 28388exp( -|x|^tau ) 28389@end ifnottex 28390 28391@item constant: 28392@iftex 28393@tex 28394$1 / (2 \, \Gamma(1+1/\tau))$ 28395@end tex 28396@end iftex 28397@ifnottex 283981 / (2 * Gamma(1+1/tau)) 28399@end ifnottex 28400 28401@item domain: 28402@iftex 28403@tex 28404$-\infty < x < \infty$ 28405@end tex 28406@end iftex 28407@ifnottex 28408-infinity < x < infinity 28409@end ifnottex 28410 28411@iftex 28412@item parameters 1 (1): @r{ tau} 28413@sp 1 28414@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28415@item No. @tab name @tab @tab default 28416@item @code{[0]} 28417@tab@tex$\tau $@end tex 28418@tab@tex$> 0 $@end tex 28419@tab 28420@tab (@i{shape}) 28421@end multitable 28422@end iftex 28423@ifnottex 28424@item parameters 1 (1): tau 28425@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28426@item No. @tab name @tab @tab default 28427@item @code{[0]} @tab tau @tab > 0 @tab @tab @i{(shape)} 28428@end multitable 28429@end ifnottex 28430@item reference: 28431@ifhtml 28432@ref{bib:JKBc95,, [JKBc95: Ch.24; p.195]} 28433@end ifhtml 28434@ifnothtml 28435[JKBc95: Ch.24; p.195] 28436@end ifnothtml 28437 28438@item special generators: 28439@table @code 28440@item DEF 28441@iftex 28442Transformed density rejection (only for 28443@tex $\tau \geq 1$ 28444@end tex 28445) [DLa86] 28446@end iftex 28447@ifhtml 28448Transformed density rejection (only for tau >= 1) @ref{bib:DLa86, [DLa86]} 28449@end ifhtml 28450@ifinfo 28451Transformed density rejection (only for tau >= 1) [DLa86] 28452@end ifinfo 28453@end table 28454 28455@end table 28456 28457 28458@c 28459@c end of unur_distributions.h 28460@c ------------------------------------- 28461@c ------------------------------------- 28462@c unur_distributions.h 28463@c 28464 28465@node rayleigh 28466@subsection @code{rayleigh} -- Rayleigh distribution 28467@anchor{funct:unur_distr_rayleigh} 28468@findex unur_distr_rayleigh 28469 28470 28471@table @i 28472@item PDF: 28473@iftex 28474@tex 28475$x \, \exp( -1/2 \, ({x\over \sigma})^2 )$ 28476@end tex 28477@end iftex 28478@ifnottex 28479x * exp( -1/2 * (x/sigma)^2 ) 28480@end ifnottex 28481 28482@item constant: 28483@iftex 28484@tex 28485$1 / \sigma^2$ 28486@end tex 28487@end iftex 28488@ifnottex 284891 / sigma^2 28490@end ifnottex 28491 28492@item domain: 28493@iftex 28494@tex 28495$0 \leq x < \infty$ 28496@end tex 28497@end iftex 28498@ifnottex 284990 <= x < infinity 28500@end ifnottex 28501 28502@iftex 28503@item parameters 1 (1): @r{ sigma} 28504@sp 1 28505@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28506@item No. @tab name @tab @tab default 28507@item @code{[0]} 28508@tab@tex$\sigma $@end tex 28509@tab@tex$> 0 $@end tex 28510@tab 28511@tab (@i{scale}) 28512@end multitable 28513@end iftex 28514@ifnottex 28515@item parameters 1 (1): sigma 28516@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28517@item No. @tab name @tab @tab default 28518@item @code{[0]} @tab sigma @tab > 0 @tab @tab @i{(scale)} 28519@end multitable 28520@end ifnottex 28521@item reference: 28522@ifhtml 28523@ref{bib:JKBb94,, [JKBb94: Ch.18; p.456]} 28524@end ifhtml 28525@ifnothtml 28526[JKBb94: Ch.18; p.456] 28527@end ifnothtml 28528 28529@end table 28530 28531 28532@c 28533@c end of unur_distributions.h 28534@c ------------------------------------- 28535@c ------------------------------------- 28536@c unur_distributions.h 28537@c 28538 28539@node slash 28540@subsection @code{slash} -- Slash distribution 28541@anchor{funct:unur_distr_slash} 28542@findex unur_distr_slash 28543 28544 28545@table @i 28546@item PDF: 28547@iftex 28548@tex 28549$(1 - \exp(-x^2/2)) / x^2$ 28550@end tex 28551@end iftex 28552@ifnottex 28553(1 - exp(-x^2/2)) / x^2 28554@end ifnottex 28555 28556@item constant: 28557@iftex 28558@tex 28559$1 / \sqrt{2 \pi}$ 28560@end tex 28561@end iftex 28562@ifnottex 285631 / sqrt(2 pi) 28564@end ifnottex 28565 28566@item CDF: 28567@iftex 28568@tex 28569not implemented! 28570@end tex 28571@end iftex 28572@ifnottex 28573not implemented! 28574@end ifnottex 28575 28576@item domain: 28577@iftex 28578@tex 28579$-\infty < x < \infty$ 28580@end tex 28581@end iftex 28582@ifnottex 28583-infinity < x < infinity 28584@end ifnottex 28585 28586@item reference: 28587@ifhtml 28588@ref{bib:JKBb94,, [JKBb94: Ch.12; p.63]} 28589@end ifhtml 28590@ifnothtml 28591[JKBb94: Ch.12; p.63] 28592@end ifnothtml 28593 28594@item special generators: 28595@table @code 28596@item DEF 28597Ratio of normal and uniform random variates 28598@end table 28599 28600@end table 28601 28602 28603@c 28604@c end of unur_distributions.h 28605@c ------------------------------------- 28606@c ------------------------------------- 28607@c unur_distributions.h 28608@c 28609 28610@node student 28611@subsection @code{student} -- Student's t distribution 28612@anchor{funct:unur_distr_student} 28613@findex unur_distr_student 28614 28615 28616@table @i 28617@item PDF: 28618@iftex 28619@tex 28620$(1+{t^2\over \nu})^{-(\nu+1)/2}$ 28621@end tex 28622@end iftex 28623@ifnottex 28624(1+t^2/nu)^(-(nu+1)/2) 28625@end ifnottex 28626 28627@item constant: 28628@iftex 28629@tex 28630$1 / (\sqrt{\nu} \, B(1/2,\nu/2))$ 28631@end tex 28632@end iftex 28633@ifnottex 286341 / (sqrt(nu) * B(1/2,nu/2)) 28635@end ifnottex 28636 28637@item CDF: 28638@iftex 28639@tex 28640not implemented! 28641@end tex 28642@end iftex 28643@ifnottex 28644not implemented! 28645@end ifnottex 28646 28647@item domain: 28648@iftex 28649@tex 28650$-\infty < x < \infty$ 28651@end tex 28652@end iftex 28653@ifnottex 28654-infinity < x < infinity 28655@end ifnottex 28656 28657@iftex 28658@item parameters 1 (1): @r{ nu} 28659@sp 1 28660@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28661@item No. @tab name @tab @tab default 28662@item @code{[0]} 28663@tab@tex$\nu $@end tex 28664@tab@tex$> 0 $@end tex 28665@tab 28666@tab (@i{shape}) 28667@end multitable 28668@end iftex 28669@ifnottex 28670@item parameters 1 (1): nu 28671@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28672@item No. @tab name @tab @tab default 28673@item @code{[0]} @tab nu @tab > 0 @tab @tab @i{(shape)} 28674@end multitable 28675@end ifnottex 28676@item reference: 28677@ifhtml 28678@ref{bib:JKBc95,, [JKBc95: Ch.28; p.362]} 28679@end ifhtml 28680@ifnothtml 28681[JKBc95: Ch.28; p.362] 28682@end ifnothtml 28683 28684@end table 28685 28686 28687@c 28688@c end of unur_distributions.h 28689@c ------------------------------------- 28690@c ------------------------------------- 28691@c unur_distributions.h 28692@c 28693 28694@node triangular 28695@subsection @code{triangular} -- Triangular distribution 28696@anchor{funct:unur_distr_triangular} 28697@findex unur_distr_triangular 28698 28699 28700@table @i 28701@item PDF: 28702@iftex 28703@tex 28704$2\, x / H, \hbox{ for } 0 \leq x \leq H \hfill\break 2\, (1-x) / (1-H), \hbox{ for } H \leq x \leq 1$ 28705@end tex 28706@end iftex 28707@ifnottex 287082*x / H, for 0 <= x <= H 28709 28710 2*(1-x) / (1-H), for H <= x <= 1 28711@end ifnottex 28712 28713@item constant: 28714@iftex 28715@tex 28716$1$ 28717@end tex 28718@end iftex 28719@ifnottex 287201 28721@end ifnottex 28722 28723@item domain: 28724@iftex 28725@tex 28726$0 \leq x \leq 1$ 28727@end tex 28728@end iftex 28729@ifnottex 287300 <= x <= 1 28731@end ifnottex 28732 28733@iftex 28734@item parameters 0 (1): @r{ [ H ]} 28735@sp 1 28736@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28737@item No. @tab name @tab @tab default 28738@item @code{[0]} 28739@tab@tex$H $@end tex 28740@tab@tex$0 \leq H \leq 1 $@end tex 28741@tab 1/2 28742@tab (@i{shape}) 28743@end multitable 28744@end iftex 28745@ifnottex 28746@item parameters 0 (1): [ H ] 28747@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28748@item No. @tab name @tab @tab default 28749@item @code{[0]} @tab H @tab 0 <= H <= 1 @tab 1/2 @tab @i{(shape)} 28750@end multitable 28751@end ifnottex 28752@item reference: 28753@ifhtml 28754@ref{bib:JKBc95,, [JKBc95: Ch.26; p.297]} 28755@end ifhtml 28756@ifnothtml 28757[JKBc95: Ch.26; p.297] 28758@end ifnothtml 28759 28760@item special generators: 28761@table @code 28762@item INV 28763Inversion method 28764@end table 28765 28766@end table 28767 28768 28769@c 28770@c end of unur_distributions.h 28771@c ------------------------------------- 28772@c ------------------------------------- 28773@c unur_distributions.h 28774@c 28775 28776@node uniform 28777@subsection @code{uniform} -- Uniform distribution 28778@anchor{funct:unur_distr_uniform} 28779@findex unur_distr_uniform 28780 28781 28782@table @i 28783@item PDF: 28784@iftex 28785@tex 28786$1 / (b-a)$ 28787@end tex 28788@end iftex 28789@ifnottex 287901 / (b-a) 28791@end ifnottex 28792 28793@item constant: 28794@iftex 28795@tex 28796$1$ 28797@end tex 28798@end iftex 28799@ifnottex 288001 28801@end ifnottex 28802 28803@item domain: 28804@iftex 28805@tex 28806$a < x < b$ 28807@end tex 28808@end iftex 28809@ifnottex 28810a < x < b 28811@end ifnottex 28812 28813@iftex 28814@item parameters 0 (2): @r{ [ a, b ]} 28815@sp 1 28816@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28817@item No. @tab name @tab @tab default 28818@item @code{[0]} 28819@tab@tex$a $@end tex 28820@tab@tex$ $@end tex 28821@tab 0 28822@tab (@i{location}) 28823@item @code{[1]} 28824@tab@tex$b $@end tex 28825@tab@tex$> a $@end tex 28826@tab 1 28827@tab (@i{location}) 28828@end multitable 28829@end iftex 28830@ifnottex 28831@item parameters 0 (2): [ a, b ] 28832@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28833@item No. @tab name @tab @tab default 28834@item @code{[0]} @tab a @tab @tab 0 @tab @i{(location)} 28835@item @code{[1]} @tab b @tab > a @tab 1 @tab @i{(location)} 28836@end multitable 28837@end ifnottex 28838@item reference: 28839@ifhtml 28840@ref{bib:JKBc95,, [JKBc95: Ch.26; p.276]} 28841@end ifhtml 28842@ifnothtml 28843[JKBc95: Ch.26; p.276] 28844@end ifnothtml 28845 28846@item special generators: 28847@table @code 28848@item INV 28849Inversion method 28850@end table 28851 28852@end table 28853 28854 28855@c 28856@c end of unur_distributions.h 28857@c ------------------------------------- 28858@c ------------------------------------- 28859@c unur_distributions.h 28860@c 28861 28862@node weibull 28863@subsection @code{weibull} -- Weibull distribution 28864@anchor{funct:unur_distr_weibull} 28865@findex unur_distr_weibull 28866 28867 28868@table @i 28869@item PDF: 28870@iftex 28871@tex 28872$({x-\zeta\over \alpha})^{c-1} \, \exp( -({x-\zeta\over \alpha})^c )$ 28873@end tex 28874@end iftex 28875@ifnottex 28876((x-zeta)/alpha)^(c-1) * exp( -((x-zeta)/alpha)^c ) 28877@end ifnottex 28878 28879@item constant: 28880@iftex 28881@tex 28882$c / \alpha$ 28883@end tex 28884@end iftex 28885@ifnottex 28886c / alpha 28887@end ifnottex 28888 28889@item domain: 28890@iftex 28891@tex 28892$\zeta < x < \infty$ 28893@end tex 28894@end iftex 28895@ifnottex 28896zeta < x < infinity 28897@end ifnottex 28898 28899@iftex 28900@item parameters 1 (3): @r{ c [, alpha [, zeta ] ]} 28901@sp 1 28902@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28903@item No. @tab name @tab @tab default 28904@item @code{[0]} 28905@tab@tex$c $@end tex 28906@tab@tex$> 0 $@end tex 28907@tab 28908@tab (@i{shape}) 28909@item @code{[1]} 28910@tab@tex$\alpha $@end tex 28911@tab@tex$> 0 $@end tex 28912@tab 1 28913@tab (@i{scale}) 28914@item @code{[2]} 28915@tab@tex$\zeta $@end tex 28916@tab@tex$ $@end tex 28917@tab 0 28918@tab (@i{location}) 28919@end multitable 28920@end iftex 28921@ifnottex 28922@item parameters 1 (3): c [, alpha [, zeta ] ] 28923@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 28924@item No. @tab name @tab @tab default 28925@item @code{[0]} @tab c @tab > 0 @tab @tab @i{(shape)} 28926@item @code{[1]} @tab alpha @tab > 0 @tab 1 @tab @i{(scale)} 28927@item @code{[2]} @tab zeta @tab @tab 0 @tab @i{(location)} 28928@end multitable 28929@end ifnottex 28930@item reference: 28931@ifhtml 28932@ref{bib:JKBb94,, [JKBb94: Ch.21; p.628]} 28933@end ifhtml 28934@ifnothtml 28935[JKBb94: Ch.21; p.628] 28936@end ifnothtml 28937 28938@item special generators: 28939@table @code 28940@item INV 28941Inversion method 28942@end table 28943 28944@end table 28945 28946 28947@c 28948@c end of unur_distributions.h 28949@c ------------------------------------- 28950@c ------------------------------------- 28951@c stddist.dh 28952@c 28953 28954@page 28955@node Stddist_CVEC 28956@section UNU.RAN Library of continuous multivariate distributions 28957 28958@menu 28959* copula:: Copula (distribution with uniform marginals) 28960* multicauchy:: Multicauchy distribution 28961* multiexponential:: Multiexponential distribution 28962* multinormal:: Multinormal distribution 28963* multistudent:: Multistudent distribution 28964@end menu 28965 28966 28967@c 28968@c end of stddist.dh 28969@c ------------------------------------- 28970@c ------------------------------------- 28971@c unur_distributions.h 28972@c 28973 28974@node copula 28975@subsection @code{copula} -- Copula (distribution with uniform marginals) 28976@anchor{funct:unur_distr_copula} 28977@findex unur_distr_copula 28978 28979 28980@table @i 28981@end table 28982 28983 28984@code{UNUR_DISTR *unur_distr_copula(int dim, const double *rankcorr)} 28985creates a distribution object for a copula with @var{dim} components. 28986@var{rankcorr} is an array of size @var{dim}x@var{dim} and holds the 28987rank correlation matrix (Spearman's correlation), where the rows of 28988the matrix are stored consecutively in this array. The @code{NULL} pointer 28989can be used instead the identity matrix. 28990 28991If @var{covar} is not a valid rank correlation matrix (i.e., not positive 28992definite) then no distribution object is created and @code{NULL} is returned. 28993 28994 28995@c 28996@c end of unur_distributions.h 28997@c ------------------------------------- 28998@c ------------------------------------- 28999@c unur_distributions.h 29000@c 29001 29002@node multicauchy 29003@subsection @code{multicauchy} -- Multicauchy distribution 29004@anchor{funct:unur_distr_multicauchy} 29005@findex unur_distr_multicauchy 29006 29007 29008@table @i 29009@item PDF: 29010@iftex 29011@tex 29012$f(x) = 1 / ( 1 + (x-\mu)^t . \Sigma^{-1} . (x-\mu) )^{(dim+1)/2}$ 29013@end tex 29014@end iftex 29015@ifnottex 29016f(x) = 1 / ( 1 + (x-mu)^t . Sigma^(-1) . (x-mu) )^((dim+1)/2) 29017@end ifnottex 29018 29019@item constant: 29020@iftex 29021@tex 29022$\Gamma((dim+1)/2) / ( \pi^{(dim+1)/2} \, \sqrt{\det(\Sigma)} )$ 29023@end tex 29024@end iftex 29025@ifnottex 29026Gamma((dim+1)/2) / ( pi^((dim+1)/2) * sqrt(det(Sigma)) ) 29027@end ifnottex 29028 29029@item domain: 29030@iftex 29031@tex 29032$-\infty^{dim} < x < \infty^{dim}$ 29033@end tex 29034@end iftex 29035@ifnottex 29036-infinity^(dim) < x < infinity^(dim) 29037@end ifnottex 29038 29039@iftex 29040@item parameters 0 (2): @r{ [ mu, Sigma ]} 29041@sp 1 29042@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29043@item No. @tab name @tab @tab default 29044@item @code{[0]} 29045@tab@tex$\mu $@end tex 29046@tab@tex$ $@end tex 29047@tab (0,@dots{},0) 29048@tab (@i{location}) 29049@item @code{[1]} 29050@tab@tex$\Sigma $@end tex 29051@tab@tex$Symm, Pos. def. $@end tex 29052@tab I 29053@tab (@i{shape}) 29054@end multitable 29055@end iftex 29056@ifnottex 29057@item parameters 0 (2): [ mu, Sigma ] 29058@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29059@item No. @tab name @tab @tab default 29060@item @code{[0]} @tab mu @tab @tab (0,@dots{},0) @tab @i{(location)} 29061@item @code{[1]} @tab Sigma @tab Symm, Pos. def. @tab I @tab @i{(shape)} 29062@end multitable 29063@end ifnottex 29064@item special generators: 29065@table @code 29066@item DEF 29067Cholesky factor 29068@end table 29069 29070@end table 29071 29072 29073@c 29074@c end of unur_distributions.h 29075@c ------------------------------------- 29076@c ------------------------------------- 29077@c unur_distributions.h 29078@c 29079 29080@node multiexponential 29081@subsection @code{multiexponential} -- Multiexponential distribution 29082@anchor{funct:unur_distr_multiexponential} 29083@findex unur_distr_multiexponential 29084 29085 29086@table @i 29087@item PDF: 29088@iftex 29089@tex 29090$f(x) = Prod_{i=0}^{i=dim-1} \exp(-(dim-i) (x_{i}-x_{i-1} - (\theta_i-\theta_{i-1}) ) / \sigma_i); with x_{-1}=0 and \theta_{i-1}=0$ 29091@end tex 29092@end iftex 29093@ifnottex 29094f(x) = Prod_(i=0)^(i=dim-1) exp(-(dim-i) (x_(i)-x_(i-1) - (theta_i-theta_(i-1)) ) / sigma_i); with x_(-1)=0 and theta_(i-1)=0 29095@end ifnottex 29096 29097@item constant: 29098@iftex 29099@tex 29100$Prod_{i=0}^{i=dim-1} 1/\sigma_i$ 29101@end tex 29102@end iftex 29103@ifnottex 29104Prod_(i=0)^(i=dim-1) 1/sigma_i 29105@end ifnottex 29106 29107@item domain: 29108@iftex 29109@tex 29110$0^{dim} \leq x < \infty^{dim}$ 29111@end tex 29112@end iftex 29113@ifnottex 291140^(dim) <= x < infinity^(dim) 29115@end ifnottex 29116 29117@iftex 29118@item parameters 0 (2): @r{ [ sigma, theta ]} 29119@sp 1 29120@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29121@item No. @tab name @tab @tab default 29122@item @code{[0]} 29123@tab@tex$\sigma $@end tex 29124@tab@tex$ $@end tex 29125@tab (1,@dots{},1) 29126@tab (@i{shape}) 29127@item @code{[1]} 29128@tab@tex$\theta $@end tex 29129@tab@tex$ $@end tex 29130@tab (0,@dots{},0) 29131@tab (@i{location}) 29132@end multitable 29133@end iftex 29134@ifnottex 29135@item parameters 0 (2): [ sigma, theta ] 29136@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29137@item No. @tab name @tab @tab default 29138@item @code{[0]} @tab sigma @tab @tab (1,@dots{},1) @tab @i{(shape)} 29139@item @code{[1]} @tab theta @tab @tab (0,@dots{},0) @tab @i{(location)} 29140@end multitable 29141@end ifnottex 29142@end table 29143 29144 29145@c 29146@c end of unur_distributions.h 29147@c ------------------------------------- 29148@c ------------------------------------- 29149@c unur_distributions.h 29150@c 29151 29152@node multinormal 29153@subsection @code{multinormal} -- Multinormal distribution 29154@anchor{funct:unur_distr_multinormal} 29155@findex unur_distr_multinormal 29156 29157 29158@table @i 29159@item PDF: 29160@iftex 29161@tex 29162$f(x) = \exp( -1/2 \, (x-\mu)^t . \Sigma^{-1} . (x-\mu) )$ 29163@end tex 29164@end iftex 29165@ifnottex 29166f(x) = exp( -1/2 * (x-mu)^t . Sigma^(-1) . (x-mu) ) 29167@end ifnottex 29168 29169@item constant: 29170@iftex 29171@tex 29172$1 / ( (2 \pi)^{dim/2} \, \sqrt{\det(\Sigma)} )$ 29173@end tex 29174@end iftex 29175@ifnottex 291761 / ( (2 pi)^(dim/2) * sqrt(det(Sigma)) ) 29177@end ifnottex 29178 29179@item domain: 29180@iftex 29181@tex 29182$-\infty^{dim} < x < \infty^{dim}$ 29183@end tex 29184@end iftex 29185@ifnottex 29186-infinity^(dim) < x < infinity^(dim) 29187@end ifnottex 29188 29189@iftex 29190@item parameters 0 (2): @r{ [ mu, Sigma ]} 29191@sp 1 29192@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29193@item No. @tab name @tab @tab default 29194@item @code{[0]} 29195@tab@tex$\mu $@end tex 29196@tab@tex$ $@end tex 29197@tab (0,@dots{},0) 29198@tab (@i{location}) 29199@item @code{[1]} 29200@tab@tex$\Sigma $@end tex 29201@tab@tex$Symm, Pos. def. $@end tex 29202@tab I 29203@tab (@i{shape}) 29204@end multitable 29205@end iftex 29206@ifnottex 29207@item parameters 0 (2): [ mu, Sigma ] 29208@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29209@item No. @tab name @tab @tab default 29210@item @code{[0]} @tab mu @tab @tab (0,@dots{},0) @tab @i{(location)} 29211@item @code{[1]} @tab Sigma @tab Symm, Pos. def. @tab I @tab @i{(shape)} 29212@end multitable 29213@end ifnottex 29214@item reference: 29215@ifhtml 29216@ref{bib:KBJe00,, [KBJe00: Ch.45; p.105]} 29217@end ifhtml 29218@ifnothtml 29219[KBJe00: Ch.45; p.105] 29220@end ifnothtml 29221 29222@end table 29223 29224 29225@c 29226@c end of unur_distributions.h 29227@c ------------------------------------- 29228@c ------------------------------------- 29229@c unur_distributions.h 29230@c 29231 29232@node multistudent 29233@subsection @code{multistudent} -- Multistudent distribution 29234@anchor{funct:unur_distr_multistudent} 29235@findex unur_distr_multistudent 29236 29237 29238@table @i 29239@item PDF: 29240@iftex 29241@tex 29242$f(x) = 1 / ( 1 + (x-\mu)^t . \Sigma^{-1} . (x-\mu) / m)^{(dim+m)/2} )$ 29243@end tex 29244@end iftex 29245@ifnottex 29246f(x) = 1 / ( 1 + (x-mu)^t . Sigma^(-1) . (x-mu) / m)^((dim+m)/2) ) 29247@end ifnottex 29248 29249@item constant: 29250@iftex 29251@tex 29252$\Gamma((dim+m)/2) / ( \Gamma(m/2) (m\, \pi)^{dim/2} \, \sqrt{\det(\Sigma)} )$ 29253@end tex 29254@end iftex 29255@ifnottex 29256Gamma((dim+m)/2) / ( Gamma(m/2) (m*pi)^(dim/2) * sqrt(det(Sigma)) ) 29257@end ifnottex 29258 29259@item domain: 29260@iftex 29261@tex 29262$-\infty^{dim} < x < \infty^{dim}$ 29263@end tex 29264@end iftex 29265@ifnottex 29266-infinity^(dim) < x < infinity^(dim) 29267@end ifnottex 29268 29269@iftex 29270@item parameters 0 (3): @r{ [ m, mu, Sigma ]} 29271@sp 1 29272@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29273@item No. @tab name @tab @tab default 29274@item @code{[0]} 29275@tab@tex$m $@end tex 29276@tab@tex$m>0 $@end tex 29277@tab 1 29278@tab (@i{location}) 29279@item @code{[1]} 29280@tab@tex$\mu $@end tex 29281@tab@tex$ $@end tex 29282@tab (0,@dots{},0) 29283@tab (@i{location}) 29284@item @code{[2]} 29285@tab@tex$\Sigma $@end tex 29286@tab@tex$Symm, Pos. def. $@end tex 29287@tab I 29288@tab (@i{shape}) 29289@end multitable 29290@end iftex 29291@ifnottex 29292@item parameters 0 (3): [ m, mu, Sigma ] 29293@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29294@item No. @tab name @tab @tab default 29295@item @code{[0]} @tab m @tab m>0 @tab 1 @tab @i{(location)} 29296@item @code{[1]} @tab mu @tab @tab (0,@dots{},0) @tab @i{(location)} 29297@item @code{[2]} @tab Sigma @tab Symm, Pos. def. @tab I @tab @i{(shape)} 29298@end multitable 29299@end ifnottex 29300@end table 29301 29302 29303@c 29304@c end of unur_distributions.h 29305@c ------------------------------------- 29306@c ------------------------------------- 29307@c stddist.dh 29308@c 29309 29310@page 29311@node Stddist_DISCR 29312@section UNU.RAN Library of discrete univariate distributions 29313 29314@menu 29315* binomial:: Binomial distribution 29316* geometric:: Geometric distribution 29317* hypergeometric:: Hypergeometric distribution 29318* logarithmic:: Logarithmic distribution 29319* negativebinomial:: Negative Binomial distribution 29320* poisson:: Poisson distribution 29321@end menu 29322 29323 29324At the moment there are no CDFs implemented for discrete distribution. 29325Thus 29326@ifhtml 29327@ref{funct:unur_distr_discr_upd_pmfsum,@command{unur_distr_discr_upd_pmfsum}} 29328@end ifhtml 29329@ifnothtml 29330@command{unur_distr_discr_upd_pmfsum} 29331@end ifnothtml 29332does not work properly for truncated 29333distribution. 29334 29335 29336@c 29337@c end of stddist.dh 29338@c ------------------------------------- 29339@c ------------------------------------- 29340@c unur_distributions.h 29341@c 29342 29343@node binomial 29344@subsection @code{binomial} -- Binomial distribution 29345@anchor{funct:unur_distr_binomial} 29346@findex unur_distr_binomial 29347 29348 29349@table @i 29350@item PMF: 29351@iftex 29352@tex 29353${n \choose k} \, p^k \, (1-p)^{n-k}$ 29354@end tex 29355@end iftex 29356@ifnottex 29357(n \choose k) * p^k * (1-p)^(n-k) 29358@end ifnottex 29359 29360@item constant: 29361@iftex 29362@tex 29363$1$ 29364@end tex 29365@end iftex 29366@ifnottex 293671 29368@end ifnottex 29369 29370@item domain: 29371@iftex 29372@tex 29373$0 \leq k \leq n$ 29374@end tex 29375@end iftex 29376@ifnottex 293770 <= k <= n 29378@end ifnottex 29379 29380@iftex 29381@item parameters 2 (2): @r{ n, p} 29382@sp 1 29383@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29384@item No. @tab name @tab @tab default 29385@item @code{[0]} 29386@tab@tex$n $@end tex 29387@tab@tex$\geq 1 $@end tex 29388@tab 29389@tab (@i{no. of elements}) 29390@item @code{[1]} 29391@tab@tex$p $@end tex 29392@tab@tex$0 < p < 1 $@end tex 29393@tab 29394@tab (@i{shape}) 29395@end multitable 29396@end iftex 29397@ifnottex 29398@item parameters 2 (2): n, p 29399@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29400@item No. @tab name @tab @tab default 29401@item @code{[0]} @tab n @tab >= 1 @tab @tab @i{(no. of elements)} 29402@item @code{[1]} @tab p @tab 0 < p < 1 @tab @tab @i{(shape)} 29403@end multitable 29404@end ifnottex 29405@item reference: 29406@ifhtml 29407@ref{bib:JKKa92,, [JKKa92: Ch.3; p.105]} 29408@end ifhtml 29409@ifnothtml 29410[JKKa92: Ch.3; p.105] 29411@end ifnothtml 29412 29413@item special generators: 29414@table @code 29415@item DEF 29416@iftex 29417Ratio of Uniforms/Inversion [STa89] 29418@end iftex 29419@ifhtml 29420Ratio of Uniforms/Inversion @ref{bib:STa89, [STa89]} 29421@end ifhtml 29422@ifinfo 29423Ratio of Uniforms/Inversion [STa89] 29424@end ifinfo 29425@end table 29426 29427@end table 29428 29429 29430@c 29431@c end of unur_distributions.h 29432@c ------------------------------------- 29433@c ------------------------------------- 29434@c unur_distributions.h 29435@c 29436 29437@node geometric 29438@subsection @code{geometric} -- Geometric distribution 29439@anchor{funct:unur_distr_geometric} 29440@findex unur_distr_geometric 29441 29442 29443@table @i 29444@item PMF: 29445@iftex 29446@tex 29447$p \, (1-p)^k$ 29448@end tex 29449@end iftex 29450@ifnottex 29451p * (1-p)^k 29452@end ifnottex 29453 29454@item constant: 29455@iftex 29456@tex 29457$1$ 29458@end tex 29459@end iftex 29460@ifnottex 294611 29462@end ifnottex 29463 29464@item domain: 29465@iftex 29466@tex 29467$0 \leq k < \infty$ 29468@end tex 29469@end iftex 29470@ifnottex 294710 <= k < infinity 29472@end ifnottex 29473 29474@iftex 29475@item parameters 1 (1): @r{ p} 29476@sp 1 29477@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29478@item No. @tab name @tab @tab default 29479@item @code{[0]} 29480@tab@tex$p $@end tex 29481@tab@tex$0 < p < 1 $@end tex 29482@tab 29483@tab (@i{shape}) 29484@end multitable 29485@end iftex 29486@ifnottex 29487@item parameters 1 (1): p 29488@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29489@item No. @tab name @tab @tab default 29490@item @code{[0]} @tab p @tab 0 < p < 1 @tab @tab @i{(shape)} 29491@end multitable 29492@end ifnottex 29493@item reference: 29494@ifhtml 29495@ref{bib:JKKa92,, [JKKa92: Ch.5.2; p.201]} 29496@end ifhtml 29497@ifnothtml 29498[JKKa92: Ch.5.2; p.201] 29499@end ifnothtml 29500 29501@item special generators: 29502@table @code 29503@item INV 29504Inversion method 29505@end table 29506 29507@end table 29508 29509 29510@c 29511@c end of unur_distributions.h 29512@c ------------------------------------- 29513@c ------------------------------------- 29514@c unur_distributions.h 29515@c 29516 29517@node hypergeometric 29518@subsection @code{hypergeometric} -- Hypergeometric distribution 29519@anchor{funct:unur_distr_hypergeometric} 29520@findex unur_distr_hypergeometric 29521 29522 29523@table @i 29524@item PMF: 29525@iftex 29526@tex 29527${M \choose k} \, {N-M \choose n-k} / {N \choose n}$ 29528@end tex 29529@end iftex 29530@ifnottex 29531(M \choose k) * (N-M \choose n-k) / (N \choose n) 29532@end ifnottex 29533 29534@item constant: 29535@iftex 29536@tex 29537$1$ 29538@end tex 29539@end iftex 29540@ifnottex 295411 29542@end ifnottex 29543 29544@item domain: 29545@iftex 29546@tex 29547$\max(0,n-N+M) \leq k \leq \min(n,M)$ 29548@end tex 29549@end iftex 29550@ifnottex 29551max(0,n-N+M) <= k <= min(n,M) 29552@end ifnottex 29553 29554@iftex 29555@item parameters 3 (3): @r{ N, M, n} 29556@sp 1 29557@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29558@item No. @tab name @tab @tab default 29559@item @code{[0]} 29560@tab@tex$N $@end tex 29561@tab@tex$\geq 1 $@end tex 29562@tab 29563@tab (@i{no. of elements}) 29564@item @code{[1]} 29565@tab@tex$M $@end tex 29566@tab@tex$1 \leq M \leq N $@end tex 29567@tab 29568@tab (@i{shape}) 29569@item @code{[2]} 29570@tab@tex$n $@end tex 29571@tab@tex$1 \leq n \leq N $@end tex 29572@tab 29573@tab (@i{shape}) 29574@end multitable 29575@end iftex 29576@ifnottex 29577@item parameters 3 (3): N, M, n 29578@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29579@item No. @tab name @tab @tab default 29580@item @code{[0]} @tab N @tab >= 1 @tab @tab @i{(no. of elements)} 29581@item @code{[1]} @tab M @tab 1 <= M <= N @tab @tab @i{(shape)} 29582@item @code{[2]} @tab n @tab 1 <= n <= N @tab @tab @i{(shape)} 29583@end multitable 29584@end ifnottex 29585@item reference: 29586@ifhtml 29587@ref{bib:JKKa92,, [JKKa92: Ch.6; p.237]} 29588@end ifhtml 29589@ifnothtml 29590[JKKa92: Ch.6; p.237] 29591@end ifnothtml 29592 29593@item special generators: 29594@table @code 29595@item DEF 29596@iftex 29597Ratio of Uniforms/Inversion [STa89] 29598@end iftex 29599@ifhtml 29600Ratio of Uniforms/Inversion @ref{bib:STa89, [STa89]} 29601@end ifhtml 29602@ifinfo 29603Ratio of Uniforms/Inversion [STa89] 29604@end ifinfo 29605@end table 29606 29607@end table 29608 29609 29610@c 29611@c end of unur_distributions.h 29612@c ------------------------------------- 29613@c ------------------------------------- 29614@c unur_distributions.h 29615@c 29616 29617@node logarithmic 29618@subsection @code{logarithmic} -- Logarithmic distribution 29619@anchor{funct:unur_distr_logarithmic} 29620@findex unur_distr_logarithmic 29621 29622 29623@table @i 29624@item PMF: 29625@iftex 29626@tex 29627$\theta^k / k$ 29628@end tex 29629@end iftex 29630@ifnottex 29631theta^k / k 29632@end ifnottex 29633 29634@item constant: 29635@iftex 29636@tex 29637$- \log( 1.-\theta);$ 29638@end tex 29639@end iftex 29640@ifnottex 29641- log( 1.-theta); 29642@end ifnottex 29643 29644@item domain: 29645@iftex 29646@tex 29647$1 \leq k < \infty$ 29648@end tex 29649@end iftex 29650@ifnottex 296511 <= k < infinity 29652@end ifnottex 29653 29654@iftex 29655@item parameters 1 (1): @r{ theta} 29656@sp 1 29657@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29658@item No. @tab name @tab @tab default 29659@item @code{[0]} 29660@tab@tex$\theta $@end tex 29661@tab@tex$0 < \theta < 1 $@end tex 29662@tab 29663@tab (@i{shape}) 29664@end multitable 29665@end iftex 29666@ifnottex 29667@item parameters 1 (1): theta 29668@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29669@item No. @tab name @tab @tab default 29670@item @code{[0]} @tab theta @tab 0 < theta < 1 @tab @tab @i{(shape)} 29671@end multitable 29672@end ifnottex 29673@item reference: 29674@ifhtml 29675@ref{bib:JKKa92,, [JKKa92: Ch.7; p.285]} 29676@end ifhtml 29677@ifnothtml 29678[JKKa92: Ch.7; p.285] 29679@end ifnothtml 29680 29681@item special generators: 29682@table @code 29683@item DEF 29684@iftex 29685Inversion/Transformation [KAa81] 29686@end iftex 29687@ifhtml 29688Inversion/Transformation @ref{bib:KAa81, [KAa81]} 29689@end ifhtml 29690@ifinfo 29691Inversion/Transformation [KAa81] 29692@end ifinfo 29693@end table 29694 29695@end table 29696 29697 29698@c 29699@c end of unur_distributions.h 29700@c ------------------------------------- 29701@c ------------------------------------- 29702@c unur_distributions.h 29703@c 29704 29705@node negativebinomial 29706@subsection @code{negativebinomial} -- Negative Binomial distribution 29707@anchor{funct:unur_distr_negativebinomial} 29708@findex unur_distr_negativebinomial 29709 29710 29711@table @i 29712@item PMF: 29713@iftex 29714@tex 29715${k+r-1 \choose r-1} \, p^r \, (1-p)^k$ 29716@end tex 29717@end iftex 29718@ifnottex 29719(k+r-1 \choose r-1) * p^r * (1-p)^k 29720@end ifnottex 29721 29722@item constant: 29723@iftex 29724@tex 29725$1$ 29726@end tex 29727@end iftex 29728@ifnottex 297291 29730@end ifnottex 29731 29732@item domain: 29733@iftex 29734@tex 29735$0 \leq k < \infty$ 29736@end tex 29737@end iftex 29738@ifnottex 297390 <= k < infinity 29740@end ifnottex 29741 29742@iftex 29743@item parameters 2 (2): @r{ p, r} 29744@sp 1 29745@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29746@item No. @tab name @tab @tab default 29747@item @code{[0]} 29748@tab@tex$p $@end tex 29749@tab@tex$0 < p < 1 $@end tex 29750@tab 29751@tab (@i{shape}) 29752@item @code{[1]} 29753@tab@tex$r $@end tex 29754@tab@tex$> 0 $@end tex 29755@tab 29756@tab (@i{shape}) 29757@end multitable 29758@end iftex 29759@ifnottex 29760@item parameters 2 (2): p, r 29761@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29762@item No. @tab name @tab @tab default 29763@item @code{[0]} @tab p @tab 0 < p < 1 @tab @tab @i{(shape)} 29764@item @code{[1]} @tab r @tab > 0 @tab @tab @i{(shape)} 29765@end multitable 29766@end ifnottex 29767@item reference: 29768@ifhtml 29769@ref{bib:JKKa92,, [JKKa92: Ch.5.1; p.200]} 29770@end ifhtml 29771@ifnothtml 29772[JKKa92: Ch.5.1; p.200] 29773@end ifnothtml 29774 29775@end table 29776 29777 29778@c 29779@c end of unur_distributions.h 29780@c ------------------------------------- 29781@c ------------------------------------- 29782@c unur_distributions.h 29783@c 29784 29785@node poisson 29786@subsection @code{poisson} -- Poisson distribution 29787@anchor{funct:unur_distr_poisson} 29788@findex unur_distr_poisson 29789 29790 29791@table @i 29792@item PMF: 29793@iftex 29794@tex 29795$\theta^k / k!$ 29796@end tex 29797@end iftex 29798@ifnottex 29799theta^k / k! 29800@end ifnottex 29801 29802@item constant: 29803@iftex 29804@tex 29805$\exp(\theta)$ 29806@end tex 29807@end iftex 29808@ifnottex 29809exp(theta) 29810@end ifnottex 29811 29812@item domain: 29813@iftex 29814@tex 29815$0 \leq k < \infty$ 29816@end tex 29817@end iftex 29818@ifnottex 298190 <= k < infinity 29820@end ifnottex 29821 29822@iftex 29823@item parameters 1 (1): @r{ theta} 29824@sp 1 29825@multitable {No.} {namex} {999999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29826@item No. @tab name @tab @tab default 29827@item @code{[0]} 29828@tab@tex$\theta $@end tex 29829@tab@tex$> 0 $@end tex 29830@tab 29831@tab (@i{shape}) 29832@end multitable 29833@end iftex 29834@ifnottex 29835@item parameters 1 (1): theta 29836@multitable {No.xx} {namexxx} {99999999999} {defaultx} {xxxxxxxxxxxxxxxxxxxxxxxx} 29837@item No. @tab name @tab @tab default 29838@item @code{[0]} @tab theta @tab > 0 @tab @tab @i{(shape)} 29839@end multitable 29840@end ifnottex 29841@item reference: 29842@ifhtml 29843@ref{bib:JKKa92,, [JKKa92: Ch.4; p.151]} 29844@end ifhtml 29845@ifnothtml 29846[JKKa92: Ch.4; p.151] 29847@end ifnothtml 29848 29849@item special generators: 29850@table @code 29851@item DEF 29852@iftex 29853Tabulated Inversion combined with Acceptance Complement [ADb82] 29854@end iftex 29855@ifhtml 29856Tabulated Inversion combined with Acceptance Complement @ref{bib:ADb82, [ADb82]} 29857@end ifhtml 29858@ifinfo 29859Tabulated Inversion combined with Acceptance Complement [ADb82] 29860@end ifinfo 29861@item 2 29862@iftex 29863Tabulated Inversion combined with Patchwork Rejection [ZHa94] 29864@end iftex 29865@ifhtml 29866Tabulated Inversion combined with Patchwork Rejection @ref{bib:ZHa94, [ZHa94]} 29867@end ifhtml 29868@ifinfo 29869Tabulated Inversion combined with Patchwork Rejection [ZHa94] 29870@end ifinfo 29871@end table 29872 29873@end table 29874 29875 29876@c 29877@c end of unur_distributions.h 29878@c ------------------------------------- 29879@c ------------------------------------- 29880@c stddist.dh 29881@c 29882 29883@page 29884@node Stddist_MATR 29885@section UNU.RAN Library of random matrices 29886 29887@menu 29888* correlation:: Random correlation matrix 29889@end menu 29890 29891 29892@c 29893@c end of stddist.dh 29894@c ------------------------------------- 29895@c ------------------------------------- 29896@c unur_distributions.h 29897@c 29898 29899@node correlation 29900@subsection @code{correlation} -- Random correlation matrix 29901@anchor{funct:unur_distr_correlation} 29902@findex unur_distr_correlation 29903 29904 29905@table @i 29906@end table 29907 29908 29909@code{UNUR_DISTR *unur_distr_correlation( int n )} 29910creates a distribution object for a random correlation matrix of 29911@var{n} rows and columns. It can be used with method MCORR 29912(@pxref{MCORR,,Random Correlation Matrix}) to 29913generate random correlation matrices of the given size. 29914 29915 29916 29917@c 29918@c end of unur_distributions.h 29919@c ------------------------------------- 29920@c ------------------------------------- 29921@c error_debug.dh 29922@c 29923 29924@node Error_Debug 29925@chapter Error handling and Debugging 29926 29927@menu 29928* Output_streams:: Output streams 29929* Debug:: Debugging 29930* Error_reporting:: Error reporting 29931* Errno:: Error codes 29932* Error_handlers:: Error handlers 29933@end menu 29934 29935 29936UNU.RAN routines report an error whenever they cannot perform the 29937requested task. Additionally it is possible to get information 29938about the generated distribution of generator objects for debugging 29939purposes. However, the latter must be enabled when compiling and 29940installing the library. (It is disabled by default.) 29941This chapter describes all necessary details: 29942 29943@itemize 29944@item Choose an output stream to for writing the requested 29945information. 29946@item Select a debugging level. 29947@item Select an error handler. 29948@item Write your own error handler. 29949@item Get more information for a particular error code. 29950@end itemize 29951 29952 29953 29954@c 29955@c end of error_debug.dh 29956@c ------------------------------------- 29957@c ------------------------------------- 29958@c stream.h 29959@c 29960 29961@node Output_streams 29962@section Output streams 29963 29964 29965@cindex Error handlers 29966@cindex Output streams 29967 29968UNU.RAN uses a logfile for writing all error messages, warnings, 29969and debugging information onto an output stream. This stream can 29970be set at runtime by the 29971@ifhtml 29972@ref{funct:unur_set_stream,@command{unur_set_stream}} 29973@end ifhtml 29974@ifnothtml 29975@command{unur_set_stream} 29976@end ifnothtml 29977call. 29978If no such stream is given by the user a default stream is used 29979by the library: all messages are written into the file 29980@file{unuran.log} in the current working directory. The name of 29981this logfile is defined by the macro @code{UNUR_LOG_FILE} in 29982@file{unuran_config.h}. 29983(If UNU.RAN fails to open this file for writing, @file{stderr} 29984is used instead.) 29985 29986To destinguish between messages for different objects each of 29987these has its own identifier which is composed by the name of 29988the distribution obejct and generator type, resp., followed by a 29989dot and three digits. 29990(If there are more than 999 generators then the identifiers are 29991not unique.) 29992 29993@emph{Remark:} Writting debugging information must be switched 29994on at compile time using the configure flag 29995@code{--enable-logging}, see @ref{Debug,,Debugging}. 29996 29997 29998@subheading Function reference 29999 30000@ifhtml 30001@itemize 30002@item @ref{funct:unur_set_stream,unur_set_stream} 30003@item @ref{funct:unur_get_stream,unur_get_stream} 30004@end itemize 30005@end ifhtml 30006 30007 30008@ifinfo 30009@anchor{funct:unur_set_stream} 30010@deftypefn Function {FILE*} unur_set_stream (FILE* @var{new_stream}) 30011This function sets a new file handler for the output stream, 30012@var{new_stream}, for the UNU.RAN library routines. The previous 30013handler is returned (so that you can restore it later). 30014Note that the pointer to a user defined file handler is stored in a 30015static variable, so there can be only one output stream handler per 30016program. This function should be not be used in multi-threaded 30017programs except to set up a program-wide error handler from a 30018master thread. 30019 30020The @code{NULL} pointer is not allowed. 30021(If you want to disable logging of debugging information use 30022unur_set_default_debug(UNUR_DEBUG_OFF) instead. 30023If you want to disable error messages at all use 30024@ifhtml 30025@ref{funct:unur_set_error_handler_off,@command{unur_set_error_handler_off}.} 30026@end ifhtml 30027@ifnothtml 30028@command{unur_set_error_handler_off}. 30029@end ifnothtml 30030) 30031@end deftypefn 30032@end ifinfo 30033@ifnotinfo 30034@anchor{funct:unur_set_stream} 30035@deftypefn {} {FILE*} unur_set_stream (FILE* @var{new_stream}) 30036This function sets a new file handler for the output stream, 30037@var{new_stream}, for the UNU.RAN library routines. The previous 30038handler is returned (so that you can restore it later). 30039Note that the pointer to a user defined file handler is stored in a 30040static variable, so there can be only one output stream handler per 30041program. This function should be not be used in multi-threaded 30042programs except to set up a program-wide error handler from a 30043master thread. 30044 30045The @code{NULL} pointer is not allowed. 30046(If you want to disable logging of debugging information use 30047unur_set_default_debug(UNUR_DEBUG_OFF) instead. 30048If you want to disable error messages at all use 30049@ifhtml 30050@ref{funct:unur_set_error_handler_off,@command{unur_set_error_handler_off}.} 30051@end ifhtml 30052@ifnothtml 30053@command{unur_set_error_handler_off}. 30054@end ifnothtml 30055) 30056@end deftypefn 30057@end ifnotinfo 30058 30059@ifinfo 30060@anchor{funct:unur_get_stream} 30061@deftypefn Function {FILE*} unur_get_stream (void) 30062Get the file handle for the current output stream. It can be used to 30063allow applications to write additional information into the logfile. 30064@end deftypefn 30065@end ifinfo 30066@ifnotinfo 30067@anchor{funct:unur_get_stream} 30068@deftypefn {} {FILE*} unur_get_stream (void) 30069Get the file handle for the current output stream. It can be used to 30070allow applications to write additional information into the logfile. 30071@end deftypefn 30072@end ifnotinfo 30073 30074 30075 30076 30077@c 30078@c end of stream.h 30079@c ------------------------------------- 30080@c ------------------------------------- 30081@c debug.h 30082@c 30083 30084@node Debug 30085@section Debugging 30086 30087 30088The UNU.RAN library has several debugging levels which 30089can be switched on/off by debugging flags. This debugging 30090feature must be enabled when building the library using the 30091@code{--enable-logging} configure flag. 30092 30093The debugging levels range from print a short description of the 30094created generator object to a detailed description of hat 30095functions and tracing the sampling routines. The output is printed 30096onto the debugging output stream 30097(@pxref{Output_streams,,Output streams}). 30098 30099The debugging flags can be set or changed by the respective calls 30100@ifhtml 30101@ref{funct:unur_set_debug,@command{unur_set_debug}} 30102@end ifhtml 30103@ifnothtml 30104@command{unur_set_debug} 30105@end ifnothtml 30106and 30107@ifhtml 30108@ref{funct:unur_chg_debug,@command{unur_chg_debug}} 30109@end ifhtml 30110@ifnothtml 30111@command{unur_chg_debug} 30112@end ifnothtml 30113independently for each 30114generator. 30115 30116By default flag @code{UNUR_DEBUG_INIT} (see 30117below) is used. This default flags is set by the macro 30118@code{UNUR_DEBUGFLAG_DEFAULT} in @file{unuran_config.h} and can 30119be changed at runtime by a 30120@ifhtml 30121@ref{funct:unur_set_default_debug,@command{unur_set_default_debug}} 30122@end ifhtml 30123@ifnothtml 30124@command{unur_set_default_debug} 30125@end ifnothtml 30126call. 30127 30128Off course these debugging flags 30129depend on the chosen method. Since most of these are merely for 30130debugging the library itself, a description of the flags are given 30131in the corresponding source files of the method. 30132Nevertheless, the following flags can be used with all methods. 30133 30134Common debug flags: 30135 30136@ftable @code 30137@item UNUR_DEBUG_OFF 30138@findex UNUR_DEBUG_OFF 30139switch off all debuging information 30140@item UNUR_DEBUG_ALL 30141@findex UNUR_DEBUG_ALL 30142all avaivable information 30143@item UNUR_DEBUG_INIT 30144@findex UNUR_DEBUG_INIT 30145parameters of generator object after initialization 30146@item UNUR_DEBUG_SETUP 30147@findex UNUR_DEBUG_SETUP 30148data created at setup 30149@item UNUR_DEBUG_ADAPT 30150@findex UNUR_DEBUG_ADAPT 30151data created during adaptive steps 30152@item UNUR_DEBUG_SAMPLE 30153@findex UNUR_DEBUG_SAMPLE 30154trace sampling 30155@end ftable 30156 30157Notice that these are flags which could be combined using the 30158@code{|} operator. 30159 30160Almost all routines check a given pointer before they read from or write 30161to the given address. This does not hold for time-critical routines 30162like all sampling routines. Thus you are responsible for checking a 30163pointer that is returned from a 30164@ifhtml 30165@ref{funct:unur_init,@command{unur_init}} 30166@end ifhtml 30167@ifnothtml 30168@command{unur_init} 30169@end ifnothtml 30170call. 30171However, it is possible to turn on checking for invalid @code{NULL} pointers 30172even in such time-critical routines by building the library 30173using the @code{--enable-check-struct} configure flag. 30174 30175Another debugging tool used in the library are magic cookies that 30176validate a given pointer. It produces an error whenever a given 30177pointer points to an object that is invalid in the context. 30178The usage of magic cookies is also switched on by the 30179@code{--enable-check-struct} configure flag. 30180 30181 30182@subheading Function reference 30183 30184@ifhtml 30185@itemize 30186@item @ref{funct:unur_set_debug,unur_set_debug} 30187@item @ref{funct:unur_chg_debug,unur_chg_debug} 30188@item @ref{funct:unur_set_default_debug,unur_set_default_debug} 30189@end itemize 30190@end ifhtml 30191 30192 30193@ifinfo 30194@anchor{funct:unur_set_debug} 30195@deftypefn Function {int} unur_set_debug (UNUR_PAR* @var{parameters}, unsigned @var{debug}) 30196Set debugging flags for generator. 30197@end deftypefn 30198@end ifinfo 30199@ifnotinfo 30200@anchor{funct:unur_set_debug} 30201@deftypefn {} {int} unur_set_debug (UNUR_PAR* @var{parameters}, unsigned @var{debug}) 30202Set debugging flags for generator. 30203@end deftypefn 30204@end ifnotinfo 30205 30206@ifinfo 30207@anchor{funct:unur_chg_debug} 30208@deftypefn Function {int} unur_chg_debug (UNUR_GEN* @var{generator}, unsigned @var{debug}) 30209Change debugging flags for generator. 30210@end deftypefn 30211@end ifinfo 30212@ifnotinfo 30213@anchor{funct:unur_chg_debug} 30214@deftypefn {} {int} unur_chg_debug (UNUR_GEN* @var{generator}, unsigned @var{debug}) 30215Change debugging flags for generator. 30216@end deftypefn 30217@end ifnotinfo 30218 30219@ifinfo 30220@anchor{funct:unur_set_default_debug} 30221@deftypefn Function {int} unur_set_default_debug (unsigned @var{debug}) 30222Change default debugging flag. 30223@end deftypefn 30224@end ifinfo 30225@ifnotinfo 30226@anchor{funct:unur_set_default_debug} 30227@deftypefn {} {int} unur_set_default_debug (unsigned @var{debug}) 30228Change default debugging flag. 30229@end deftypefn 30230@end ifnotinfo 30231 30232 30233 30234 30235@c 30236@c end of debug.h 30237@c ------------------------------------- 30238@c ------------------------------------- 30239@c error.h 30240@c 30241 30242@node Error_reporting 30243@section Error reporting 30244 30245 30246UNU.RAN routines report an error whenever they cannot perform the 30247requested task. For example, applying transformed density 30248rejection to a distribution that violates the T-concavity 30249condition, or trying to set a parameter that is out of range, 30250result in an error message. 30251It might also happen that the setup fails for transformed density 30252rejection for a T-concave distribution with some extreme density 30253function simply because of round-off errors that makes the 30254generation of a hat function numerically impossible. 30255Situations like this may happen when using black box algorithms and 30256you should check the return values of all routines. 30257 30258All @command{..._set_...}, and @command{..._chg_...} calls 30259return @code{UNUR_SUCCESS} if they could be executed 30260successfully. Otherwise, some error codes are returned if it was 30261not possible to set or change the desired parameters, 30262e.g. because the given values are out of range, or simply 30263because the set call does not work for the chosen method. 30264 30265All routines that return a pointer to the requested object will 30266return a @code{NULL} pointer in case of error. 30267(Thus you should always check the pointer to avoid possible 30268segmentation faults. Sampling routines usually do not check the 30269given pointer to the generator object.) 30270 30271The library distinguishes between two major classes of error: 30272 30273@table @emph 30274 30275@item (fatal) errors: 30276The library was not able to construct the 30277requested object. 30278 30279@item warnings: 30280Some problems encounters while constructing a generator 30281object. The routine has tried to solve the problem but the resulting 30282object might not be what you want. For example, chosing a special 30283variant of a method does not work and the initialization routine 30284might switch to another variant. Then the generator produces random 30285variates of the requested distribution but correlation induction 30286is not possible. However, it also might happen that 30287changing the domain of a distribution has failed. Then the generator 30288produced random variates with too large/too small range, i.e. their 30289distribution is not correct. 30290@end table 30291 30292It is obvious from the example that this distinction between errors 30293and warning is rather crude and sometimes arbitrary. 30294 30295UNU.RAN routines use the global variable @var{unur_errno} to 30296report errors, completely analogously to @var{errno} in the ANSI 30297C standard library. 30298(However this approach is not thread-safe. There can 30299be only one instance of a global variable per program. Different 30300threads of execution may overwrite @var{unur_errno} 30301simultaneously). 30302Thus when an error occurs the caller of the routine can examine the 30303error code in @var{unur_errno} to get more details about the 30304reason why a routine failed. You get a short 30305description of the error by a 30306@ifhtml 30307@ref{funct:unur_get_strerror,@command{unur_get_strerror}} 30308@end ifhtml 30309@ifnothtml 30310@command{unur_get_strerror} 30311@end ifnothtml 30312call. 30313All the error code numbers have prefix @code{UNUR_ERR_} and expand 30314to non-zero constant unsigned integer values. 30315Error codes are divided into six main groups, 30316see @ref{Errno,,Error codes}. 30317 30318Alternatively, the variable @var{unur_errno} can also read by a 30319@ifhtml 30320@ref{funct:unur_get_errno,@command{unur_get_errno}} 30321@end ifhtml 30322@ifnothtml 30323@command{unur_get_errno} 30324@end ifnothtml 30325call and can be reset by the 30326@ifhtml 30327@ref{funct:unur_reset_errno,@command{unur_reset_errno}} 30328@end ifhtml 30329@ifnothtml 30330@command{unur_reset_errno} 30331@end ifnothtml 30332call (this is in particular required for the Windows version of the 30333library). 30334 30335Additionally, there exists a error handler 30336(@pxref{Error_handlers,,Error handlers}) that is invoked in case 30337of an error. 30338 30339 30340In addition to reporting errors by setting error codes in 30341@var{unur_errno}, the library also has an error handler 30342function. This function is called by other library functions 30343when they report an error, just before they return to the 30344caller (@pxref{Error_handlers,,Error handlers}). 30345The default behavior of the error handler is to print a short 30346message: 30347 30348@smallexample 30349AROU.004: [error] arou.c:1500 - (generator) condition for method violated: 30350AROU.004: ..> PDF not unimodal 30351@end smallexample 30352 30353The purpose of the error handler is to provide a function 30354where a breakpoint can be set that will catch library errors when 30355running under the debugger. It is not intended for use in production 30356programs, which should handle any errors using the return codes. 30357 30358 30359@subheading Function reference 30360 30361@ifhtml 30362@itemize 30363@item @ref{var:unur_errno,unur_errno} 30364@item @ref{funct:unur_get_errno,unur_get_errno} 30365@item @ref{funct:unur_reset_errno,unur_reset_errno} 30366@item @ref{funct:unur_get_strerror,unur_get_strerror} 30367@end itemize 30368@end ifhtml 30369 30370 30371@ifinfo 30372@anchor{var:unur_errno} 30373@deftypevar {extern int} unur_errno 30374@findex unur_errno 30375Global variable for reporting diagnostics of error. 30376@end deftypevar 30377@end ifinfo 30378@ifnotinfo 30379@anchor{var:unur_errno} 30380@deftypevar {extern int} unur_errno 30381@findex unur_errno 30382Global variable for reporting diagnostics of error. 30383@end deftypevar 30384@end ifnotinfo 30385 30386@ifinfo 30387@anchor{funct:unur_get_errno} 30388@deftypefn Function {int} unur_get_errno (void) 30389Get current value of global variable @var{unur_errno}. 30390@end deftypefn 30391@end ifinfo 30392@ifnotinfo 30393@anchor{funct:unur_get_errno} 30394@deftypefn {} {int} unur_get_errno (void) 30395Get current value of global variable @var{unur_errno}. 30396@end deftypefn 30397@end ifnotinfo 30398 30399@ifinfo 30400@anchor{funct:unur_reset_errno} 30401@deftypefn Function {void} unur_reset_errno (void) 30402Reset global variable @var{unur_errno} to @code{UNUR_SUCCESS} 30403(i.e., no errors occured). 30404@end deftypefn 30405@end ifinfo 30406@ifnotinfo 30407@anchor{funct:unur_reset_errno} 30408@deftypefn {} {void} unur_reset_errno (void) 30409Reset global variable @var{unur_errno} to @code{UNUR_SUCCESS} 30410(i.e., no errors occured). 30411@end deftypefn 30412@end ifnotinfo 30413 30414@ifinfo 30415@anchor{funct:unur_get_strerror} 30416@deftypefn Function {const char*} unur_get_strerror (const @var{int errnocode}) 30417Get a short description for error code value. 30418@end deftypefn 30419@end ifinfo 30420@ifnotinfo 30421@anchor{funct:unur_get_strerror} 30422@deftypefn {} {const char*} unur_get_strerror (const @var{int errnocode}) 30423Get a short description for error code value. 30424@end deftypefn 30425@end ifnotinfo 30426 30427 30428 30429 30430@c 30431@c end of error.h 30432@c ------------------------------------- 30433@c ------------------------------------- 30434@c unur_errno.h 30435@c 30436 30437@node Errno 30438@section Error codes 30439 30440 30441 30442@subsubheading List of error codes 30443 30444@itemize @bullet 30445@item Procedure executed successfully (no error) 30446@ftable @code 30447@item UNUR_SUCCESS (0x0u) 30448success (no error) 30449@end ftable 30450 30451@item Errors that occurred while handling distribution objects. 30452@ftable @code 30453@item UNUR_ERR_DISTR_SET 30454set failed (invalid parameter). 30455@item UNUR_ERR_DISTR_GET 30456get failed (parameter not set). 30457@item UNUR_ERR_DISTR_NPARAMS 30458invalid number of parameters. 30459@item UNUR_ERR_DISTR_DOMAIN 30460parameter(s) out of domain. 30461@item UNUR_ERR_DISTR_GEN 30462invalid variant for special generator. 30463@item UNUR_ERR_DISTR_REQUIRED 30464incomplete distribution object, entry missing. 30465@item UNUR_ERR_DISTR_UNKNOWN 30466unknown distribution, cannot handle. 30467@item UNUR_ERR_DISTR_INVALID 30468invalid distribution object. 30469@item UNUR_ERR_DISTR_DATA 30470data are missing. 30471@item UNUR_ERR_DISTR_PROP 30472desired property does not exist 30473@end ftable 30474 30475@item Errors that occurred while handling parameter objects. 30476@ftable @code 30477@item UNUR_ERR_PAR_SET 30478set failed (invalid parameter) 30479@item UNUR_ERR_PAR_VARIANT 30480invalid variant -> using default 30481@item UNUR_ERR_PAR_INVALID 30482invalid parameter object 30483@end ftable 30484 30485@item Errors that occurred while handling generator objects. 30486@ftable @code 30487@item UNUR_ERR_GEN 30488error with generator object. 30489@item UNUR_ERR_GEN_DATA 30490(possibly) invalid data. 30491@item UNUR_ERR_GEN_CONDITION 30492condition for method violated. 30493@item UNUR_ERR_GEN_INVALID 30494invalid generator object. 30495@item UNUR_ERR_GEN_SAMPLING 30496sampling error. 30497@item UNUR_ERR_NO_REINIT 30498reinit routine not implemented. 30499@item UNUR_ERR_NO_QUANTILE 30500quantile routine not implemented. 30501@end ftable 30502 30503@item Errors that occurred while handling URNG objects. 30504@ftable @code 30505@item UNUR_ERR_URNG 30506generic error with URNG object. 30507@item UNUR_ERR_URNG_MISS 30508missing functionality. 30509@end ftable 30510 30511@item Errors that occurred while parsing strings. 30512@ftable @code 30513@item UNUR_ERR_STR 30514error in string. 30515@item UNUR_ERR_STR_UNKNOWN 30516unknown keyword. 30517@item UNUR_ERR_STR_SYNTAX 30518syntax error. 30519@item UNUR_ERR_STR_INVALID 30520invalid parameter. 30521@item UNUR_ERR_FSTR_SYNTAX 30522syntax error in function string. 30523@item UNUR_ERR_FSTR_DERIV 30524cannot derivate function. 30525@end ftable 30526 30527@item Other run time errors. 30528@ftable @code 30529@item UNUR_ERR_DOMAIN 30530argument out of domain. 30531@item UNUR_ERR_ROUNDOFF 30532(serious) round-off error. 30533@item UNUR_ERR_MALLOC 30534virtual memory exhausted. 30535@item UNUR_ERR_NULL 30536invalid @code{NULL} pointer. 30537@item UNUR_ERR_COOKIE 30538invalid cookie. 30539@item UNUR_ERR_GENERIC 30540generic error. 30541@item UNUR_ERR_SILENT 30542silent error (no error message). 30543@item UNUR_ERR_INF 30544infinity occured. 30545@item UNUR_ERR_NAN 30546NaN occured. 30547@item UNUR_ERR_COMPILE 30548Requested routine requires different compilation switches. 30549Recompilation of library necessary. 30550@item UNUR_ERR_SHOULD_NOT_HAPPEN 30551Internal error, that should not happen. 30552Please report this bug! 30553@end ftable 30554 30555@end itemize 30556 30557 30558@c 30559@c end of unur_errno.h 30560@c ------------------------------------- 30561@c ------------------------------------- 30562@c error.h 30563@c 30564 30565@node Error_handlers 30566@section Error handlers 30567 30568 30569The default behavior of the UNU.RAN error handler is to print a 30570short message onto the output stream, usually a logfile 30571(@pxref{Output_streams,,Output streams}), e.g., 30572 30573@smallexample 30574AROU.004: [error] arou.c:1500 - (generator) condition for method violated: 30575AROU.004: ..> PDF not unimodal 30576@end smallexample 30577 30578This error handler can be switched off using the 30579@ifhtml 30580@ref{funct:unur_set_error_handler_off,@command{unur_set_error_handler_off}} 30581@end ifhtml 30582@ifnothtml 30583@command{unur_set_error_handler_off} 30584@end ifnothtml 30585call, or replace it by a new one. 30586Thus it allows to set a breakpoint that will catch library errors when 30587running under the debugger. It also can be used to redirect 30588error messages when UNU.RAN is included in general purpose 30589libraries or in interactive programming environments. 30590 30591@deftp {Data Type} UNUR_ERROR_HANDLER 30592 30593This is the type of UNU.RAN error handler functions. An error 30594handler will be passed six arguments which specify 30595the identifier of the object where the error occured (a string), 30596the name of the source file in which it occurred (also a string), 30597the line number in that file (an integer), 30598the type of error (a string: @code{"error"} or @code{"warning"}), 30599the error number (an integert), and 30600the reason for the error (a string). 30601The source file and line number are set at compile time 30602using the @code{__FILE__} and @code{__LINE__} directives in the 30603preprocessor. 30604The error number can be translated into a short description 30605using a 30606@ifhtml 30607@ref{funct:unur_get_strerror,@command{unur_get_strerror}} 30608@end ifhtml 30609@ifnothtml 30610@command{unur_get_strerror} 30611@end ifnothtml 30612call. 30613An error handler function returns type @code{void}. 30614 30615Error handler functions should be defined like this, 30616@example 30617void my_handler( 30618@ @ @ @ @ @ @ @ @ @ @ const char *objid, 30619@ @ @ @ @ @ @ @ @ @ @ const char *file, 30620@ @ @ @ @ @ @ @ @ @ @ int line, 30621@ @ @ @ @ @ @ @ @ @ @ const char *errortype, 30622@ @ @ @ @ @ @ @ @ @ @ int unur_errno, 30623@ @ @ @ @ @ @ @ @ @ @ const char *reason ) 30624@end example 30625@end deftp 30626 30627To request the use of your own error handler you need the call 30628@ifhtml 30629@ref{funct:unur_set_error_handler,@command{unur_set_error_handler}.} 30630@end ifhtml 30631@ifnothtml 30632@command{unur_set_error_handler}. 30633@end ifnothtml 30634 30635@subheading Function reference 30636 30637@ifhtml 30638@itemize 30639@item @ref{funct:unur_set_error_handler,unur_set_error_handler} 30640@item @ref{funct:unur_set_error_handler_off,unur_set_error_handler_off} 30641@end itemize 30642@end ifhtml 30643 30644 30645@ifinfo 30646@anchor{funct:unur_set_error_handler} 30647@deftypefn Function {UNUR_ERROR_HANDLER*} unur_set_error_handler (UNUR_ERROR_HANDLER* @var{new_handler}) 30648This function sets a new error handler, @var{new_handler}, for the 30649UNU.RAN library routines. The previous handler is returned (so that you 30650can restore it later). Note that the pointer to a user defined 30651error handler function is stored in a static variable, so there 30652can be only one error handler per program. This function should 30653be not be used in multi-threaded programs except to set up a 30654program-wide error handler from a master thread. 30655 30656To use the default behavior set the error handler to @code{NULL}. 30657@end deftypefn 30658@end ifinfo 30659@ifnotinfo 30660@anchor{funct:unur_set_error_handler} 30661@deftypefn {} {UNUR_ERROR_HANDLER*} unur_set_error_handler (UNUR_ERROR_HANDLER* @var{new_handler}) 30662This function sets a new error handler, @var{new_handler}, for the 30663UNU.RAN library routines. The previous handler is returned (so that you 30664can restore it later). Note that the pointer to a user defined 30665error handler function is stored in a static variable, so there 30666can be only one error handler per program. This function should 30667be not be used in multi-threaded programs except to set up a 30668program-wide error handler from a master thread. 30669 30670To use the default behavior set the error handler to @code{NULL}. 30671@end deftypefn 30672@end ifnotinfo 30673 30674@ifinfo 30675@anchor{funct:unur_set_error_handler_off} 30676@deftypefn Function {UNUR_ERROR_HANDLER*} unur_set_error_handler_off (void) 30677This function turns off the error handler by defining an error 30678handler which does nothing (except of setting @var{unur_errno}. 30679The previous handler is returned (so that you can restore it later). 30680@end deftypefn 30681@end ifinfo 30682@ifnotinfo 30683@anchor{funct:unur_set_error_handler_off} 30684@deftypefn {} {UNUR_ERROR_HANDLER*} unur_set_error_handler_off (void) 30685This function turns off the error handler by defining an error 30686handler which does nothing (except of setting @var{unur_errno}. 30687The previous handler is returned (so that you can restore it later). 30688@end deftypefn 30689@end ifnotinfo 30690 30691 30692 30693 30694@c 30695@c end of error.h 30696@c ------------------------------------- 30697@c ------------------------------------- 30698@c unuran_tests.h 30699@c 30700 30701@node Testing 30702@chapter Testing 30703 30704 30705The following routines can be used to test the performance of the 30706implemented generators and can be used to verify the implementions. 30707They are declared in @file{unuran_tests.h} which has to be included. 30708 30709 30710@subheading Function reference 30711 30712@ifhtml 30713@itemize 30714@item @ref{funct:unur_run_tests,unur_run_tests} 30715@item @ref{funct:unur_test_printsample,unur_test_printsample} 30716@item @ref{funct:unur_test_timing,unur_test_timing} 30717@item @ref{funct:unur_test_timing_R,unur_test_timing_R} 30718@item @ref{funct:unur_test_timing_uniform,unur_test_timing_uniform} 30719@item @ref{funct:unur_test_timing_exponential,unur_test_timing_exponential} 30720@item @ref{funct:unur_test_timing_total,unur_test_timing_total} 30721@item @ref{funct:unur_test_count_urn,unur_test_count_urn} 30722@item @ref{funct:unur_test_count_pdf,unur_test_count_pdf} 30723@item @ref{funct:unur_test_par_count_pdf,unur_test_par_count_pdf} 30724@item @ref{funct:unur_test_chi2,unur_test_chi2} 30725@item @ref{funct:unur_test_moments,unur_test_moments} 30726@item @ref{funct:unur_test_correlation,unur_test_correlation} 30727@item @ref{funct:unur_test_quartiles,unur_test_quartiles} 30728@item @ref{funct:unur_test_u_error,unur_test_u_error} 30729@end itemize 30730@end ifhtml 30731 30732 30733@ifinfo 30734@anchor{funct:unur_run_tests} 30735@deftypefn Function {void} unur_run_tests (UNUR_PAR* @var{parameters}, unsigned @var{tests}, FILE* @var{out}) 30736Run a battery of tests. 30737The following tests are available (use @code{|} to combine these 30738tests): 30739@table @code 30740@item UNUR_TEST_ALL 30741run all possible tests. 30742@item UNUR_TEST_TIME 30743estimate generation times. 30744@item UNUR_TEST_N_URNG 30745count number of uniform random numbers 30746@item UNUR_TEST_N_PDF 30747count number of PDF calls 30748@item UNUR_TEST_CHI2 30749run chi^2 test for goodness of fit 30750@item UNUR_TEST_SAMPLE 30751print a small sample. 30752@end table 30753All these tests can be started individually (see below). 30754@end deftypefn 30755@end ifinfo 30756@ifnotinfo 30757@anchor{funct:unur_run_tests} 30758@deftypefn {} {void} unur_run_tests (UNUR_PAR* @var{parameters}, unsigned @var{tests}, FILE* @var{out}) 30759Run a battery of tests. 30760The following tests are available (use @code{|} to combine these 30761tests): 30762@table @code 30763@item UNUR_TEST_ALL 30764run all possible tests. 30765@item UNUR_TEST_TIME 30766estimate generation times. 30767@item UNUR_TEST_N_URNG 30768count number of uniform random numbers 30769@item UNUR_TEST_N_PDF 30770count number of PDF calls 30771@item UNUR_TEST_CHI2 30772run chi^2 test for goodness of fit 30773@item UNUR_TEST_SAMPLE 30774print a small sample. 30775@end table 30776All these tests can be started individually (see below). 30777@end deftypefn 30778@end ifnotinfo 30779 30780@ifinfo 30781@anchor{funct:unur_test_printsample} 30782@deftypefn Function {void} unur_test_printsample (UNUR_GEN* @var{generator}, int @var{n_rows}, int @var{n_cols}, FILE* @var{out}) 30783Print a small sample with @var{n_rows} rows and @var{n_cols} columns. 30784@var{out} is the output stream to which all results are written. 30785@end deftypefn 30786@end ifinfo 30787@ifnotinfo 30788@anchor{funct:unur_test_printsample} 30789@deftypefn {} {void} unur_test_printsample (UNUR_GEN* @var{generator}, int @var{n_rows}, int @var{n_cols}, FILE* @var{out}) 30790Print a small sample with @var{n_rows} rows and @var{n_cols} columns. 30791@var{out} is the output stream to which all results are written. 30792@end deftypefn 30793@end ifnotinfo 30794 30795@ifinfo 30796@anchor{funct:unur_test_timing} 30797@deftypefn Function {UNUR_GEN*} unur_test_timing (UNUR_PAR* @var{parameters}, int @var{log10_samplesize}, double* @var{time_setup}, double* @var{time_sample}, int @var{verbosity}, FILE* @var{out}) 30798Timing. @var{parameters} is an parameter object for which setup 30799time and marginal generation times have to be measured. The results 30800are written into @var{time_setup} and @var{time_sample}, 30801respectively. @var{log10_samplesize} is the common logarithm of the 30802sample size that is used for timing. 30803 30804If @var{verbosity} is @code{TRUE} then a small table is printed to 30805output stream @var{out} with setup time, marginal generation time and 30806average generation times for generating 10, 100, @dots{} random 30807variates. All times are given in micro seconds and relative to 30808the generation times for the underlying uniform random number 30809(using the UNIF interface) and an exponential distributed 30810random variate using the inversion method. 30811 30812The created generator object is returned. 30813If a generator object could not be created successfully, then @code{NULL} 30814is returned. 30815 30816If @var{verbosity} is @code{TRUE} the result is written to the output 30817stream @var{out}. 30818 30819Notice: All timing results are subject to heavy changes. Reruning 30820timings usually results in different results. Minor changes in 30821the source code can cause changes in such timings up to 25 percent. 30822@end deftypefn 30823@end ifinfo 30824@ifnotinfo 30825@anchor{funct:unur_test_timing} 30826@deftypefn {} {UNUR_GEN*} unur_test_timing (UNUR_PAR* @var{parameters}, int @var{log10_samplesize}, double* @var{time_setup}, double* @var{time_sample}, int @var{verbosity}, FILE* @var{out}) 30827Timing. @var{parameters} is an parameter object for which setup 30828time and marginal generation times have to be measured. The results 30829are written into @var{time_setup} and @var{time_sample}, 30830respectively. @var{log10_samplesize} is the common logarithm of the 30831sample size that is used for timing. 30832 30833If @var{verbosity} is @code{TRUE} then a small table is printed to 30834output stream @var{out} with setup time, marginal generation time and 30835average generation times for generating 10, 100, @dots{} random 30836variates. All times are given in micro seconds and relative to 30837the generation times for the underlying uniform random number 30838(using the UNIF interface) and an exponential distributed 30839random variate using the inversion method. 30840 30841The created generator object is returned. 30842If a generator object could not be created successfully, then @code{NULL} 30843is returned. 30844 30845If @var{verbosity} is @code{TRUE} the result is written to the output 30846stream @var{out}. 30847 30848Notice: All timing results are subject to heavy changes. Reruning 30849timings usually results in different results. Minor changes in 30850the source code can cause changes in such timings up to 25 percent. 30851@end deftypefn 30852@end ifnotinfo 30853 30854@ifinfo 30855@anchor{funct:unur_test_timing_R} 30856@deftypefn Function {double} unur_test_timing_R (UNUR_PAR* @var{parameters}, const @var{char* distrstr}, const @var{char* methodstr}, double @var{log10_samplesize}, double* @var{time_setup}, double* @var{time_marginal}) 30857Timing. @var{parameters} is an parameter object for which setup 30858time and marginal generation times have to be measured. The results 30859are written into @var{time_setup} and @var{time_marginal}, 30860respectively. @var{log10_samplesize} is the common logarithm of the 30861sample size that is used for timing. 30862 30863Alternatively, one could provide the "parameter object" using 30864strings @var{distrstr} and @var{methodstr} as used for 30865@ifhtml 30866@ref{funct:unur_makegen_ssu,@command{unur_makegen_ssu}.} 30867@end ifhtml 30868@ifnothtml 30869@command{unur_makegen_ssu}. 30870@end ifnothtml 30871The results are more accurate than those of function 30872@ifhtml 30873@ref{funct:unur_test_timing,@command{unur_test_timing}} 30874@end ifhtml 30875@ifnothtml 30876@command{unur_test_timing} 30877@end ifnothtml 30878as the timings are computed using linear 30879regression with several timings for sample size 1 and 3088010^@var{log10_samplesize}. 30881For each sample size total generation time (including setup) is 30882measured 10 times. Since the these timings can be influenced by 30883external effects (like disc sync or handling of interupts) the 2 30884fastest and the 3 slowest timings are discarded. 30885Intercept and slope for simple linear regression are than stored 30886and 30887@math{R^2} 30888is returned. 30889 30890In case of an error @code{-100.} is returned. 30891 30892Notice: All timing results are subject to heavy changes. Reruning 30893timings usually results in different results. Minor changes in 30894the source code can cause changes in such timings up to 25 percent. 30895@end deftypefn 30896@end ifinfo 30897@ifnotinfo 30898@anchor{funct:unur_test_timing_R} 30899@deftypefn {} {double} unur_test_timing_R (UNUR_PAR* @var{parameters}, const @var{char* distrstr}, const @var{char* methodstr}, double @var{log10_samplesize}, double* @var{time_setup}, double* @var{time_marginal}) 30900Timing. @var{parameters} is an parameter object for which setup 30901time and marginal generation times have to be measured. The results 30902are written into @var{time_setup} and @var{time_marginal}, 30903respectively. @var{log10_samplesize} is the common logarithm of the 30904sample size that is used for timing. 30905 30906Alternatively, one could provide the "parameter object" using 30907strings @var{distrstr} and @var{methodstr} as used for 30908@ifhtml 30909@ref{funct:unur_makegen_ssu,@command{unur_makegen_ssu}.} 30910@end ifhtml 30911@ifnothtml 30912@command{unur_makegen_ssu}. 30913@end ifnothtml 30914The results are more accurate than those of function 30915@ifhtml 30916@ref{funct:unur_test_timing,@command{unur_test_timing}} 30917@end ifhtml 30918@ifnothtml 30919@command{unur_test_timing} 30920@end ifnothtml 30921as the timings are computed using linear 30922regression with several timings for sample size 1 and 3092310^@var{log10_samplesize}. 30924For each sample size total generation time (including setup) is 30925measured 10 times. Since the these timings can be influenced by 30926external effects (like disc sync or handling of interupts) the 2 30927fastest and the 3 slowest timings are discarded. 30928Intercept and slope for simple linear regression are than stored 30929and 30930@iftex 30931@math{R^2} 30932@end iftex 30933@ifhtml 30934@html 30935<I>R</I><SUP>2</SUP> 30936@end html 30937@end ifhtml 30938is returned. 30939 30940In case of an error @code{-100.} is returned. 30941 30942Notice: All timing results are subject to heavy changes. Reruning 30943timings usually results in different results. Minor changes in 30944the source code can cause changes in such timings up to 25 percent. 30945@end deftypefn 30946@end ifnotinfo 30947 30948@ifinfo 30949@anchor{funct:unur_test_timing_uniform} 30950@deftypefn Function {double} unur_test_timing_uniform (const @var{UNUR_PAR* parameters}, int @var{log10_samplesize}) 30951@anchor{funct:unur_test_timing_exponential} 30952@deftypefnx Function {double} unur_test_timing_exponential (const @var{UNUR_PAR* parameters}, int @var{log10_samplesize}) 30953Marginal generation times for the underlying uniform random number 30954(using the UNIF interface) and an exponential distributed 30955random variate using the inversion method. These times are used in 30956@ifhtml 30957@ref{funct:unur_test_timing,@command{unur_test_timing}} 30958@end ifhtml 30959@ifnothtml 30960@command{unur_test_timing} 30961@end ifnothtml 30962to compute the relative timings results. 30963@end deftypefn 30964@end ifinfo 30965@ifnotinfo 30966@anchor{funct:unur_test_timing_uniform} 30967@deftypefn {} {double} unur_test_timing_uniform (const @var{UNUR_PAR* parameters}, int @var{log10_samplesize}) 30968@anchor{funct:unur_test_timing_exponential} 30969@deftypefnx {} {double} unur_test_timing_exponential (const @var{UNUR_PAR* parameters}, int @var{log10_samplesize}) 30970Marginal generation times for the underlying uniform random number 30971(using the UNIF interface) and an exponential distributed 30972random variate using the inversion method. These times are used in 30973@ifhtml 30974@ref{funct:unur_test_timing,@command{unur_test_timing}} 30975@end ifhtml 30976@ifnothtml 30977@command{unur_test_timing} 30978@end ifnothtml 30979to compute the relative timings results. 30980@end deftypefn 30981@end ifnotinfo 30982 30983@ifinfo 30984@anchor{funct:unur_test_timing_total} 30985@deftypefn Function {double} unur_test_timing_total (const @var{UNUR_PAR* parameters}, int @var{samplesize}, double @var{avg_duration}) 30986Timing. @var{parameters} is an parameter object for which average 30987times a sample of size @var{samplesize} (including setup) are 30988estimated. Thus sampling is repeated and the median of these timings 30989is returned (in micro seconds). The number of iterations is computed 30990automatically such that the total amount of time necessary for the 30991test ist approximately @var{avg_duration} (given in seconds). 30992However, for very slow generator with expensive setup time the time 30993necessary for this test may be (much) larger. 30994 30995If an error occurs then @code{-1} is returned. 30996 30997Notice: All timing results are subject to heavy changes. Reruning 30998timings usually results in different results. Minor changes in 30999the source code can cause changes in such timings up to 25 percent. 31000@end deftypefn 31001@end ifinfo 31002@ifnotinfo 31003@anchor{funct:unur_test_timing_total} 31004@deftypefn {} {double} unur_test_timing_total (const @var{UNUR_PAR* parameters}, int @var{samplesize}, double @var{avg_duration}) 31005Timing. @var{parameters} is an parameter object for which average 31006times a sample of size @var{samplesize} (including setup) are 31007estimated. Thus sampling is repeated and the median of these timings 31008is returned (in micro seconds). The number of iterations is computed 31009automatically such that the total amount of time necessary for the 31010test ist approximately @var{avg_duration} (given in seconds). 31011However, for very slow generator with expensive setup time the time 31012necessary for this test may be (much) larger. 31013 31014If an error occurs then @code{-1} is returned. 31015 31016Notice: All timing results are subject to heavy changes. Reruning 31017timings usually results in different results. Minor changes in 31018the source code can cause changes in such timings up to 25 percent. 31019@end deftypefn 31020@end ifnotinfo 31021 31022@ifinfo 31023@anchor{funct:unur_test_count_urn} 31024@deftypefn Function {int} unur_test_count_urn (UNUR_GEN* @var{generator}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31025Count used uniform random numbers. It returns the total number of 31026uniform random numbers required for a sample of non-uniform random 31027variates of size @var{samplesize}. In case of an error @code{-1} 31028is returned. 31029 31030If @var{verbosity} is @code{TRUE} the result is written to the output 31031stream @var{out}. 31032 31033@emph{Notice:} This test uses global variables to store 31034counters. Thus it is not thread save. 31035@end deftypefn 31036@end ifinfo 31037@ifnotinfo 31038@anchor{funct:unur_test_count_urn} 31039@deftypefn {} {int} unur_test_count_urn (UNUR_GEN* @var{generator}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31040Count used uniform random numbers. It returns the total number of 31041uniform random numbers required for a sample of non-uniform random 31042variates of size @var{samplesize}. In case of an error @code{-1} 31043is returned. 31044 31045If @var{verbosity} is @code{TRUE} the result is written to the output 31046stream @var{out}. 31047 31048@emph{Notice:} This test uses global variables to store 31049counters. Thus it is not thread save. 31050@end deftypefn 31051@end ifnotinfo 31052 31053@ifinfo 31054@anchor{funct:unur_test_count_pdf} 31055@deftypefn Function {int} unur_test_count_pdf (UNUR_GEN* @var{generator}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31056Count evaluations of PDF and similar functions. It returns the 31057total number of evaluations of all such functions required for a 31058sample of non-uniform random variates of size @var{samplesize}. 31059If @var{verbosity} is @code{TRUE} then a more detailed report is printed 31060to the output stream @var{out}. 31061In case of an error @code{-1} is returned. 31062This test is run on a copy of the given generator object. 31063 31064@emph{Notice:} The printed numbers of evaluation should be interpreted 31065with care. For example, methods either use the PDF or the logPDF; 31066if only the logPDF is given, but a method needs the PDF then both 31067the logPDF and the PDF (a wrapper around the logPDF) are called and 31068thus one call to the PDF is counted twice. 31069 31070@emph{Notice:} This test uses global variables to store function 31071pointers and counters. Thus it is not thread save. 31072@end deftypefn 31073@end ifinfo 31074@ifnotinfo 31075@anchor{funct:unur_test_count_pdf} 31076@deftypefn {} {int} unur_test_count_pdf (UNUR_GEN* @var{generator}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31077Count evaluations of PDF and similar functions. It returns the 31078total number of evaluations of all such functions required for a 31079sample of non-uniform random variates of size @var{samplesize}. 31080If @var{verbosity} is @code{TRUE} then a more detailed report is printed 31081to the output stream @var{out}. 31082In case of an error @code{-1} is returned. 31083This test is run on a copy of the given generator object. 31084 31085@emph{Notice:} The printed numbers of evaluation should be interpreted 31086with care. For example, methods either use the PDF or the logPDF; 31087if only the logPDF is given, but a method needs the PDF then both 31088the logPDF and the PDF (a wrapper around the logPDF) are called and 31089thus one call to the PDF is counted twice. 31090 31091@emph{Notice:} This test uses global variables to store function 31092pointers and counters. Thus it is not thread save. 31093@end deftypefn 31094@end ifnotinfo 31095 31096@ifinfo 31097@anchor{funct:unur_test_par_count_pdf} 31098@deftypefn Function {int} unur_test_par_count_pdf (UNUR_PAR* @var{parameters}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31099Same as 31100@ifhtml 31101@ref{funct:unur_test_count_pdf,@command{unur_test_count_pdf}} 31102@end ifhtml 31103@ifnothtml 31104@command{unur_test_count_pdf} 31105@end ifnothtml 31106except that it is run on a parameter 31107object. Thus it also prints the number of function evaluations for 31108the setup. The temporary created generator object is destroyed 31109before the results are returned. 31110@end deftypefn 31111@end ifinfo 31112@ifnotinfo 31113@anchor{funct:unur_test_par_count_pdf} 31114@deftypefn {} {int} unur_test_par_count_pdf (UNUR_PAR* @var{parameters}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31115Same as 31116@ifhtml 31117@ref{funct:unur_test_count_pdf,@command{unur_test_count_pdf}} 31118@end ifhtml 31119@ifnothtml 31120@command{unur_test_count_pdf} 31121@end ifnothtml 31122except that it is run on a parameter 31123object. Thus it also prints the number of function evaluations for 31124the setup. The temporary created generator object is destroyed 31125before the results are returned. 31126@end deftypefn 31127@end ifnotinfo 31128 31129@ifinfo 31130@anchor{funct:unur_test_chi2} 31131@deftypefn Function {double} unur_test_chi2 (UNUR_GEN* @var{generator}, int @var{intervals}, int @var{samplesize}, int @var{classmin}, int @var{verbosity}, FILE* @var{out}) 31132Run a Chi^2 test with the @var{generator}. 31133The resulting p-value is returned. 31134 31135It works with discrete und continuous univariate distributions. 31136For the latter the CDF of the distribution is required. 31137 31138@var{intervals} is the number of intervals that is used for 31139continuous univariate distributions. @var{samplesize} is the size 31140of the sample that is used for testing. If it is set to @code{0} 31141then a sample of size @var{intervals}^2 is used (bounded to some 31142upper bound). 31143 31144@var{classmin} is the minimum number of expected entries per 31145class. If a class has to few entries then some classes are joined. 31146 31147@var{verbosity} controls the output of the routine. If it is set 31148to @code{1} then the result is written to the output stream 31149@var{out}. If it is set to @code{2} additionally the list of 31150expected and observed data is printed. 31151If it is set to @code{3} then all generated numbers are printed. 31152There is no output when it is set to @code{0}. 31153 31154@emph{Notice:} For multivariate distributions the generated points 31155are transformed by the inverse of the Cholesky factor of the 31156covariance matrix and the mean vectors (if given for the underlying 31157distribution). The marginal distributions of the transformed 31158vectors are then tested against the marginal distribution given by 31159a 31160@ifhtml 31161@ref{funct:unur_distr_cvec_set_marginals,@command{unur_distr_cvec_set_marginals}} 31162@end ifhtml 31163@ifnothtml 31164@command{unur_distr_cvec_set_marginals} 31165@end ifnothtml 31166or 31167@ifhtml 31168@ref{funct:unur_distr_cvec_set_marginal_array,@command{unur_distr_cvec_set_marginal_array}} 31169@end ifhtml 31170@ifnothtml 31171@command{unur_distr_cvec_set_marginal_array} 31172@end ifnothtml 31173call. 31174(Notice that these marginal distributions are never set by default 31175for any of the distributions provided by UNU.RAN.) 31176Then the Bonferroni corrected p-value of all these tests is returned. 31177However, the test may not be performed correctly if the domain of the 31178underlying distribution is truncated by a 31179@ifhtml 31180@ref{funct:unur_distr_cvec_set_domain_rect,@command{unur_distr_cvec_set_domain_rect}} 31181@end ifhtml 31182@ifnothtml 31183@command{unur_distr_cvec_set_domain_rect} 31184@end ifnothtml 31185call and the components of the 31186distribution are correlated (i.e. 31187@ifhtml 31188@ref{funct:unur_distr_cvec_set_covar,@command{unur_distr_cvec_set_covar}} 31189@end ifhtml 31190@ifnothtml 31191@command{unur_distr_cvec_set_covar} 31192@end ifnothtml 31193is 31194called with the non-NULL argument). Then it almost surely will fail. 31195@end deftypefn 31196@end ifinfo 31197@ifnotinfo 31198@anchor{funct:unur_test_chi2} 31199@deftypefn {} {double} unur_test_chi2 (UNUR_GEN* @var{generator}, int @var{intervals}, int @var{samplesize}, int @var{classmin}, int @var{verbosity}, FILE* @var{out}) 31200Run a Chi^2 test with the @var{generator}. 31201The resulting p-value is returned. 31202 31203It works with discrete und continuous univariate distributions. 31204For the latter the CDF of the distribution is required. 31205 31206@var{intervals} is the number of intervals that is used for 31207continuous univariate distributions. @var{samplesize} is the size 31208of the sample that is used for testing. If it is set to @code{0} 31209then a sample of size @var{intervals}^2 is used (bounded to some 31210upper bound). 31211 31212@var{classmin} is the minimum number of expected entries per 31213class. If a class has to few entries then some classes are joined. 31214 31215@var{verbosity} controls the output of the routine. If it is set 31216to @code{1} then the result is written to the output stream 31217@var{out}. If it is set to @code{2} additionally the list of 31218expected and observed data is printed. 31219If it is set to @code{3} then all generated numbers are printed. 31220There is no output when it is set to @code{0}. 31221 31222@emph{Notice:} For multivariate distributions the generated points 31223are transformed by the inverse of the Cholesky factor of the 31224covariance matrix and the mean vectors (if given for the underlying 31225distribution). The marginal distributions of the transformed 31226vectors are then tested against the marginal distribution given by 31227a 31228@ifhtml 31229@ref{funct:unur_distr_cvec_set_marginals,@command{unur_distr_cvec_set_marginals}} 31230@end ifhtml 31231@ifnothtml 31232@command{unur_distr_cvec_set_marginals} 31233@end ifnothtml 31234or 31235@ifhtml 31236@ref{funct:unur_distr_cvec_set_marginal_array,@command{unur_distr_cvec_set_marginal_array}} 31237@end ifhtml 31238@ifnothtml 31239@command{unur_distr_cvec_set_marginal_array} 31240@end ifnothtml 31241call. 31242(Notice that these marginal distributions are never set by default 31243for any of the distributions provided by UNU.RAN.) 31244Then the Bonferroni corrected p-value of all these tests is returned. 31245However, the test may not be performed correctly if the domain of the 31246underlying distribution is truncated by a 31247@ifhtml 31248@ref{funct:unur_distr_cvec_set_domain_rect,@command{unur_distr_cvec_set_domain_rect}} 31249@end ifhtml 31250@ifnothtml 31251@command{unur_distr_cvec_set_domain_rect} 31252@end ifnothtml 31253call and the components of the 31254distribution are correlated (i.e. 31255@ifhtml 31256@ref{funct:unur_distr_cvec_set_covar,@command{unur_distr_cvec_set_covar}} 31257@end ifhtml 31258@ifnothtml 31259@command{unur_distr_cvec_set_covar} 31260@end ifnothtml 31261is 31262called with the non-NULL argument). Then it almost surely will fail. 31263@end deftypefn 31264@end ifnotinfo 31265 31266@ifinfo 31267@anchor{funct:unur_test_moments} 31268@deftypefn Function {int} unur_test_moments (UNUR_GEN* @var{generator}, double* @var{moments}, int @var{n_moments}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31269Computes the first @var{n_moments} central moments for a sample of 31270size @var{samplesize}. The result is stored into the array 31271@var{moments}. 31272@var{n_moments} must be an integer between @code{1} and @code{4}. 31273For multivariate distributions the moments are stored consecutively 31274for each dimension and the provided @var{moments}-array must have 31275a length of at least (@var{n_moments}+1) * @var{dim}, where @var{dim} 31276is the dimension of the multivariate distribution. 31277The @var{m}'th moment for the @var{d}'th dimension (0<=@var{d}<@var{dim}) 31278is thus stored in the array element 31279@var{moments}[@var{d}*@var{n_moments}+@var{m}] 31280 31281If @var{verbosity} is @code{TRUE} the result is written to the output 31282stream @var{out}. 31283@end deftypefn 31284@end ifinfo 31285@ifnotinfo 31286@anchor{funct:unur_test_moments} 31287@deftypefn {} {int} unur_test_moments (UNUR_GEN* @var{generator}, double* @var{moments}, int @var{n_moments}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31288Computes the first @var{n_moments} central moments for a sample of 31289size @var{samplesize}. The result is stored into the array 31290@var{moments}. 31291@var{n_moments} must be an integer between @code{1} and @code{4}. 31292For multivariate distributions the moments are stored consecutively 31293for each dimension and the provided @var{moments}-array must have 31294a length of at least (@var{n_moments}+1) * @var{dim}, where @var{dim} 31295is the dimension of the multivariate distribution. 31296The @var{m}'th moment for the @var{d}'th dimension (0<=@var{d}<@var{dim}) 31297is thus stored in the array element 31298@var{moments}[@var{d}*@var{n_moments}+@var{m}] 31299 31300If @var{verbosity} is @code{TRUE} the result is written to the output 31301stream @var{out}. 31302@end deftypefn 31303@end ifnotinfo 31304 31305@ifinfo 31306@anchor{funct:unur_test_correlation} 31307@deftypefn Function {double} unur_test_correlation (UNUR_GEN* @var{generator1}, UNUR_GEN* @var{generator2}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31308Compute the correlation coefficient between streams from 31309@var{generator1} and @var{generator2} for two samples of size 31310@var{samplesize}. 31311The resultung correlation is returned. 31312 31313If @var{verbosity} is @code{TRUE} the result is written to the output 31314stream @var{out}. 31315@end deftypefn 31316@end ifinfo 31317@ifnotinfo 31318@anchor{funct:unur_test_correlation} 31319@deftypefn {} {double} unur_test_correlation (UNUR_GEN* @var{generator1}, UNUR_GEN* @var{generator2}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31320Compute the correlation coefficient between streams from 31321@var{generator1} and @var{generator2} for two samples of size 31322@var{samplesize}. 31323The resultung correlation is returned. 31324 31325If @var{verbosity} is @code{TRUE} the result is written to the output 31326stream @var{out}. 31327@end deftypefn 31328@end ifnotinfo 31329 31330@ifinfo 31331@anchor{funct:unur_test_quartiles} 31332@deftypefn Function {int} unur_test_quartiles (UNUR_GEN* @var{generator}, double* @var{q0}, double* @var{q1}, double* @var{q2}, double* @var{q3}, double* @var{q4}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31333Estimate quartiles of sample of size @var{samplesize}. 31334The resulting quantiles are stored in the variables @var{q}: 31335@table @var 31336@item q0 31337minimum 31338@item q1 3133925% 31340@item q2 31341median (50%) 31342@item q3 3134375% 31344@item q4 31345maximum 31346@end table 31347 31348If @var{verbosity} is @code{TRUE} the result is written to the output 31349stream @var{out}. 31350@end deftypefn 31351@end ifinfo 31352@ifnotinfo 31353@anchor{funct:unur_test_quartiles} 31354@deftypefn {} {int} unur_test_quartiles (UNUR_GEN* @var{generator}, double* @var{q0}, double* @var{q1}, double* @var{q2}, double* @var{q3}, double* @var{q4}, int @var{samplesize}, int @var{verbosity}, FILE* @var{out}) 31355Estimate quartiles of sample of size @var{samplesize}. 31356The resulting quantiles are stored in the variables @var{q}: 31357@table @var 31358@item q0 31359minimum 31360@item q1 3136125% 31362@item q2 31363median (50%) 31364@item q3 3136575% 31366@item q4 31367maximum 31368@end table 31369 31370If @var{verbosity} is @code{TRUE} the result is written to the output 31371stream @var{out}. 31372@end deftypefn 31373@end ifnotinfo 31374 31375@ifinfo 31376@anchor{funct:unur_test_u_error} 31377@deftypefn Function {double} unur_test_u_error (const @var{UNUR_GEN* generator}, double* @var{max_error}, double* @var{MAE}, double @var{threshold}, int @var{samplesize}, int @var{randomized}, int @var{testtails}, int @var{verbosity}, FILE* @var{out}) 31378Estimate U-error of an inversion method, i.e. 31379@math{error = | CDF^(-1)(U) - U |} 31380, by means of a simple Monte 31381Carlo method. 31382Maximum and mean absolute errors are stored in @var{max_error} and 31383@var{MAE}, respectively. 31384The particular computed U-errors should not exceed the given 31385@var{threshold}. However, approximization and round-off errors 31386might occasionally trigger such an event. 31387Thus the function returns a penalty score. It is @code{0.} when the 31388U-error never exceed the @var{threshold} value. It roughly gives the 31389portion of particular test points where the U-error is too larger. 31390However, each such event is weighted with 31391@math{1 + 10 x(uerror - threshold) / threshold} 31392. 31393 31394If @var{randomized} is @code{TRUE} a pseudo-random sequence is used for 31395the estimation. 31396 31397If @var{randomized} is @code{FALSE} then the U-values are choosen 31398equidistributed. 31399If in addition @var{randomized} is set to @code{TRUE} then the tails of 31400the distributions are tested with a more dense set of points. 31401 31402If @var{verbosity} is @code{TRUE} the result is written to the output 31403stream @var{out}. 31404 31405When the domain of the distribution is truncated then the u-error 31406might be larger due to rescaling of floating point numbers. Thus 31407the observed u-errors are corrected by the corresponding rescaling 31408factor. 31409 31410The test also works for discrete distributions albeit with some 31411restrictions: 31412It does not work correctly with truncated distributions and the 31413@var{testtails} flag is ignored. 31414Moreover, the value stored in @var{MAE} is rather useless. 31415 31416In case of an error a negative value is returned. 31417@end deftypefn 31418@end ifinfo 31419@ifnotinfo 31420@anchor{funct:unur_test_u_error} 31421@deftypefn {} {double} unur_test_u_error (const @var{UNUR_GEN* generator}, double* @var{max_error}, double* @var{MAE}, double @var{threshold}, int @var{samplesize}, int @var{randomized}, int @var{testtails}, int @var{verbosity}, FILE* @var{out}) 31422Estimate U-error of an inversion method, i.e. 31423@iftex 31424@math{error = | CDF^{-1}(U) - U |} 31425@end iftex 31426@ifhtml 31427@html 31428<I>error</I> = | <I>CDF</I><SUP>-1</SUP>(<I>U</I>) - <I>U</I> | 31429@end html 31430@end ifhtml 31431, by means of a simple Monte 31432Carlo method. 31433Maximum and mean absolute errors are stored in @var{max_error} and 31434@var{MAE}, respectively. 31435The particular computed U-errors should not exceed the given 31436@var{threshold}. However, approximization and round-off errors 31437might occasionally trigger such an event. 31438Thus the function returns a penalty score. It is @code{0.} when the 31439U-error never exceed the @var{threshold} value. It roughly gives the 31440portion of particular test points where the U-error is too larger. 31441However, each such event is weighted with 31442@iftex 31443@math{1 + 10 \times (uerror - threshold) / threshold} 31444@end iftex 31445@ifhtml 31446@html 314471 + 10 x(<I>uerror</I> - <I>threshold</I>) / <I>threshold</I> 31448@end html 31449@end ifhtml 31450. 31451 31452If @var{randomized} is @code{TRUE} a pseudo-random sequence is used for 31453the estimation. 31454 31455If @var{randomized} is @code{FALSE} then the U-values are choosen 31456equidistributed. 31457If in addition @var{randomized} is set to @code{TRUE} then the tails of 31458the distributions are tested with a more dense set of points. 31459 31460If @var{verbosity} is @code{TRUE} the result is written to the output 31461stream @var{out}. 31462 31463When the domain of the distribution is truncated then the u-error 31464might be larger due to rescaling of floating point numbers. Thus 31465the observed u-errors are corrected by the corresponding rescaling 31466factor. 31467 31468The test also works for discrete distributions albeit with some 31469restrictions: 31470It does not work correctly with truncated distributions and the 31471@var{testtails} flag is ignored. 31472Moreover, the value stored in @var{MAE} is rather useless. 31473 31474In case of an error a negative value is returned. 31475@end deftypefn 31476@end ifnotinfo 31477 31478 31479 31480 31481@c 31482@c end of unuran_tests.h 31483@c ------------------------------------- 31484@c ------------------------------------- 31485@c misc.dh 31486@c 31487 31488@node Misc 31489@chapter Miscelleanous 31490 31491@menu 31492* Math:: Mathematics 31493@end menu 31494 31495 31496@c 31497@c end of misc.dh 31498@c ------------------------------------- 31499@c ------------------------------------- 31500@c umath.h 31501@c 31502 31503@node Math 31504@section Mathematics 31505 31506 31507The following macros have been defined 31508 31509@ftable @code 31510@item UNUR_INFINITY 31511indicates infinity for floating point numbers (of type @code{double}). 31512Internally @code{HUGE_VAL} is used. 31513 31514@item INT_MAX 31515@itemx INT_MIN 31516indicate infinity and minus infinity, resp., for integers 31517(defined by ISO C standard). 31518 31519@item @code{TRUE} 31520@itemx @code{FALSE} 31521bolean expression for return values of @code{set} functions. 31522@end ftable 31523 31524 31525@c 31526@c end of umath.h 31527@c ------------------------------------- 31528@c ------------------------------------- 31529@c arvag.dh 31530@c 31531 31532@node RVG 31533@appendix A Short Introduction to Random Variate Generation 31534 31535@menu 31536* Inversion:: The Inversion Method 31537* Rejection:: The Rejection Method 31538* Composition:: The Composition Method 31539* Ratio-of-Uniforms:: The Ratio-of-Uniforms Method 31540* DiscreteInversion:: Inversion for Discrete Distributions 31541* IndexedSearch:: Indexed Search (Guide Table Method) 31542@end menu 31543 31544 31545 31546Random variate generation is the small field of research that deals 31547with algorithms to generate random variates from various 31548distributions. It is common to assume that a uniform random number 31549generator is available. This is a program that produces a sequence 31550of independent and identically distributed continuous 31551@iftex 31552@math{U(0,1)} 31553@end iftex 31554@ifhtml 31555@html 31556<I>U</I>(0,1) 31557@end html 31558@end ifhtml 31559@ifinfo 31560@math{U(0,1)} 31561@end ifinfo 31562random variates (i.e. uniform random variates 31563on the interval 31564@iftex 31565@math{(0,1)} 31566@end iftex 31567@ifhtml 31568@html 31569(0,1) 31570@end html 31571@end ifhtml 31572@ifinfo 31573@math{(0,1)} 31574@end ifinfo 31575). Of course real world computers can 31576never generate ideal random numbers and they cannot produce numbers 31577of arbitrary precision but state-of-the-art uniform random number 31578generators come close to this aim. Thus random variate generation 31579deals with the problem of transforming such a sequence of 31580@iftex 31581@math{U(0,1)} 31582@end iftex 31583@ifhtml 31584@html 31585<I>U</I>(0,1) 31586@end html 31587@end ifhtml 31588@ifinfo 31589@math{U(0,1)} 31590@end ifinfo 31591random numbers into non-uniform random variates. 31592 31593Here we shortly explain the basic ideas of the @emph{inversion}, 31594@emph{rejection}, and the @emph{ratio of uniforms} method. How 31595these ideas can be used to design a particular automatic random 31596variate generation algorithms that can be applied to large classes 31597of distributions is shortly explained in the description of the 31598different methods included in this manual. 31599 31600For a deeper treatment of the ideas presented here, for other 31601basic methods and for automatic generators we refer the interested 31602reader to our book [HLD04]. 31603 31604 31605 31606@c 31607@c end of arvag.dh 31608@c ------------------------------------- 31609@c ------------------------------------- 31610@c arvag.dh 31611@c 31612 31613@node Inversion 31614@section The Inversion Method 31615 31616 31617 31618When the inverse 31619@iftex 31620@math{F^{-1}} 31621@end iftex 31622@ifhtml 31623@html 31624<I>F</I><SUP>-1</SUP> 31625@end html 31626@end ifhtml 31627@ifinfo 31628@math{F^(-1)} 31629@end ifinfo 31630of the cumulative distribution 31631function is known, then random variate generation is easy. 31632We just generate a uniformly 31633@iftex 31634@math{U(0,1)} 31635@end iftex 31636@ifhtml 31637@html 31638<I>U</I>(0,1) 31639@end html 31640@end ifhtml 31641@ifinfo 31642@math{U(0,1)} 31643@end ifinfo 31644distributed random 31645number 31646@iftex 31647@math{U} 31648@end iftex 31649@ifhtml 31650@html 31651<I>U</I> 31652@end html 31653@end ifhtml 31654@ifinfo 31655@math{U} 31656@end ifinfo 31657and return 31658@iftex 31659 31660@quotation 31661@math{X=F^{-1}(U).} 31662@end quotation 31663 31664@end iftex 31665@ifhtml 31666@quotation 31667@html 31668<I>X</I>=<I>F</I><SUP>-1</SUP>(<I>U</I>). 31669@end html 31670@end quotation 31671@end ifhtml 31672@ifinfo 31673@quotation 31674@math{X=F^(-1)(U).} 31675@end quotation 31676@end ifinfo 31677 31678@noindent 31679The following figure shows how the inversion method works for 31680the exponential distribution. 31681 31682@sp 1 31683 31684@sp 1 31685@image{figures/inversion} 31686@sp 1 31687 31688@sp 1 31689 31690This algorithm is so simple that inversion is certainly the method 31691of choice if the inverse CDF is available in closed form. This is 31692the case e.g. for the exponential and the Cauchy distribution. 31693 31694The inversion method also has other special advantages that make it 31695even more attractive for simulation purposes. 31696It preserves the structural properties of the underlying uniform 31697pseudo-random number generator. 31698Consequently it can be used, e.g., for variance reduction techniques, 31699it is easy to sample from truncated distributions, from marginal 31700distributions, and from order statistics. 31701Moreover, the quality of the generated random variables depends only 31702on the underlying uniform (pseudo-) random number generator. 31703Another important advantage of the inversion method is that we can 31704easily characterize its performance. To generate one random variate 31705we always need exactly one uniform variate and one evaluation of 31706the inverse CDF. So its speed mainly depends on the costs for 31707evaluating the inverse CDF. Hence inversion is often considered as 31708the method of choice in the simulation literature. 31709 31710Unfortunately computing the inverse CDF is, for many important 31711standard distributions (e.g. for normal, student, gamma, and 31712beta-distributions), comparatively difficult and slow. Often no 31713such routines are available in standard programming libraries. 31714Then numerical methods for inverting the CDF are necessary, e.g. 31715Newton's method or (polynomial or rational) approximations of the 31716inverse CDF. Such procedures, however, have the disadvantage that 31717they are not exact and/or slow. 31718UNU.RAN implements several methods: 31719NINV (@pxref{NINV}), HINV (@pxref{HINV}) and PINV (@pxref{PINV}). 31720 31721For such approximate inversion methods the approximation error is 31722important for the quality of the generated point set. 31723Let 31724@iftex 31725@math{X=G^{-1}(U)} 31726@end iftex 31727@ifhtml 31728@html 31729<I>X</I>=<I>G</I><SUP>-1</SUP>(<I>U</I>) 31730@end html 31731@end ifhtml 31732@ifinfo 31733@math{X=G^(-1)(U)} 31734@end ifinfo 31735denote the approximate inverse CDF, 31736and let 31737@iftex 31738@math{F} 31739@end iftex 31740@ifhtml 31741@html 31742<I>F</I> 31743@end html 31744@end ifhtml 31745@ifinfo 31746@math{F} 31747@end ifinfo 31748and 31749@iftex 31750@math{F^{-1}} 31751@end iftex 31752@ifhtml 31753@html 31754<I>F</I><SUP>-1</SUP> 31755@end html 31756@end ifhtml 31757@ifinfo 31758@math{F^(-1)} 31759@end ifinfo 31760be the exact CDF and 31761inverse CDF of the distribution, resp. 31762There are three measures for the approximation error: 31763 31764@table @emph 31765@item u-error 31766is given by 31767@iftex 31768 31769@quotation 31770@math{uerror = |U-F(G^{-1}(U))|} 31771@end quotation 31772 31773@end iftex 31774@ifhtml 31775@quotation 31776@html 31777<I>uerror</I> = |<I>U</I>-<I>F</I>(<I>G</I><SUP>-1</SUP>(<I>U</I>))| 31778@end html 31779@end quotation 31780@end ifhtml 31781@ifinfo 31782@quotation 31783@math{uerror = |U-F(G^(-1)(U))|} 31784@end quotation 31785@end ifinfo 31786 31787@noindent 31788Goodness-of-fit tests like the Kolmogorov-Smirnov test or the 31789chi-squared test look at this type of error. 31790We are also convinced that it is the most suitable error measure for 31791Monte Carlo simulations as pseudo-random numbers and points of low 31792discrepancy sets are located on a grid of restricted resolution. 31793 31794@item x-error 31795is given by 31796@iftex 31797 31798@quotation 31799@math{absolute xerror = |F^{-1}(U)-G^{-1}(U)|} 31800@end quotation 31801 31802@end iftex 31803@ifhtml 31804@quotation 31805@html 31806<I>absolute</I> <I>xerror</I> = |<I>F</I><SUP>-1</SUP>(<I>U</I>)-<I>G</I><SUP>-1</SUP>(<I>U</I>)| 31807@end html 31808@end quotation 31809@end ifhtml 31810@ifinfo 31811@quotation 31812@math{absolute xerror = |F^(-1)(U)-G^(-1)(U)|} 31813@end quotation 31814@end ifinfo 31815 31816@noindent 31817@iftex 31818 31819@quotation 31820@math{relative xerror = |F^{-1}(U)-G^{-1}(U)|\cdot |F^{-1}(U)|} 31821@end quotation 31822 31823@end iftex 31824@ifhtml 31825@quotation 31826@html 31827<I>relative</I> <I>xerror</I> = |<I>F</I><SUP>-1</SUP>(<I>U</I>)-<I>G</I><SUP>-1</SUP>(<I>U</I>)| * |<I>F</I><SUP>-1</SUP>(<I>U</I>)| 31828@end html 31829@end quotation 31830@end ifhtml 31831@ifinfo 31832@quotation 31833@math{relative xerror = |F^(-1)(U)-G^(-1)(U)| * |F^(-1)(U)|} 31834@end quotation 31835@end ifinfo 31836 31837@noindent 31838The x-error measure the deviation of 31839@iftex 31840@math{G^{-1}(U)} 31841@end iftex 31842@ifhtml 31843@html 31844<I>G</I><SUP>-1</SUP>(<I>U</I>) 31845@end html 31846@end ifhtml 31847@ifinfo 31848@math{G^(-1)(U)} 31849@end ifinfo 31850from the exact result. This measure is suitable when the inverse 31851CDF is used as a quantile function in some computations. 31852The main problem with the x-error is that we have to use the 31853@emph{absolute x-error} for 31854@iftex 31855@math{X=F^{-1}(U)} 31856@end iftex 31857@ifhtml 31858@html 31859<I>X</I>=<I>F</I><SUP>-1</SUP>(<I>U</I>) 31860@end html 31861@end ifhtml 31862@ifinfo 31863@math{X=F^(-1)(U)} 31864@end ifinfo 31865close to zero 31866and the @emph{relative x-error} in the tails. 31867 31868@end table 31869 31870We use the terms @emph{u-resolution} and @emph{x-resolution} as the 31871maximal tolerated u-error and x-error, resp. 31872 31873UNU.RAN allows to set u-resolution and x-resolution 31874independently. Both requirements must be fulfilled. 31875We use the following strategy for checking whether the 31876precision goal is reached: 31877 31878@table @emph 31879@item checking u-error: 31880The u-error must be slightly smaller than the given u-resolution: 31881@iftex 31882 31883@quotation 31884@math{|U-F(G^{-1}(U))| < 0.9\cdot uresolution.} 31885@end quotation 31886 31887@end iftex 31888@ifhtml 31889@quotation 31890@html 31891|<I>U</I>-<I>F</I>(<I>G</I><SUP>-1</SUP>(<I>U</I>))| < 0.9 * <I>uresolution</I>. 31892@end html 31893@end quotation 31894@end ifhtml 31895@ifinfo 31896@quotation 31897@math{|U-F(G^(-1)(U))| < 0.9 * uresolution.} 31898@end quotation 31899@end ifinfo 31900 31901@noindent 31902There is no necessity to consinder the relative u-error as we have 31903@iftex 31904@math{0 < U < 1.} 31905@end iftex 31906@ifhtml 31907@html 319080 < <I>U</I> < 1. 31909@end html 31910@end ifhtml 31911@ifinfo 31912@math{0 < U < 1.} 31913@end ifinfo 31914 31915@item checking x-error: 31916We combine absoute and relative x-error and use the criterion 31917@iftex 31918 31919@quotation 31920@math{|F^{-1}(U)-G^{-1}(U)| < xresolution \cdot (|G^{-1}(U)| + xresolution).} 31921@end quotation 31922 31923@end iftex 31924@ifhtml 31925@quotation 31926@html 31927|<I>F</I><SUP>-1</SUP>(<I>U</I>)-<I>G</I><SUP>-1</SUP>(<I>U</I>)| < <I>xresolution</I> * (|<I>G</I><SUP>-1</SUP>(<I>U</I>)| + <I>xresolution</I>). 31928@end html 31929@end quotation 31930@end ifhtml 31931@ifinfo 31932@quotation 31933@math{|F^(-1)(U)-G^(-1)(U)| < xresolution * (|G^(-1)(U)| + xresolution).} 31934@end quotation 31935@end ifinfo 31936 31937@noindent 31938@end table 31939 31940@strong{Remark:} 31941It should be noted here that the criterion based on the u-error is 31942too stringent whereever the CDF is extremely steep (and thus the 31943PDF has a pole or a high and narrow peak). This is in particular a 31944problem for distributions with a pole (e.g., the gamma distribution 31945with shape parameter less than 0.5). 31946On the other hand using a criterion based on the x-error causes 31947problems whereever the CDF is extremly flat. This is in particular 31948the case in the (far) tails of heavy-tailed distributions (e.g., 31949for the Cauchy distribution). 31950 31951 31952 31953@c 31954@c end of arvag.dh 31955@c ------------------------------------- 31956@c ------------------------------------- 31957@c arvag.dh 31958@c 31959 31960@node Rejection 31961@section The Rejection Method 31962 31963 31964 31965The rejection method, often called @emph{acceptance-rejection 31966method}, has been suggested by John von Neumann in 1951. 31967Since then it has proven to be the most flexible and most efficient 31968method to generate variates from continuous distributions. 31969 31970We explain the rejection principle first for the density 31971@iftex 31972@math{f(x) = sin(x)/2} 31973@end iftex 31974@ifhtml 31975@html 31976<I>f</I>(<I>x</I>) = <I>sin</I>(<I>x</I>)/2 31977@end html 31978@end ifhtml 31979@ifinfo 31980@math{f(x) = sin(x)/2} 31981@end ifinfo 31982on the interval 31983@iftex 31984@math{(0,\pi).} 31985@end iftex 31986@ifhtml 31987@html 31988(0, pi). 31989@end html 31990@end ifhtml 31991@ifinfo 31992@math{(0, pi).} 31993@end ifinfo 31994To generate random variates from this distribution we also can 31995sample random points that are uniformly distributed in the region 31996between the graph of 31997@iftex 31998@math{f(x)} 31999@end iftex 32000@ifhtml 32001@html 32002<I>f</I>(<I>x</I>) 32003@end html 32004@end ifhtml 32005@ifinfo 32006@math{f(x)} 32007@end ifinfo 32008and the @i{x}-axis, 32009i.e., the shaded region in the below figure. 32010 32011@sp 1 32012@image{figures/rejection_from_constant_hat} 32013@sp 1 32014 32015 32016In general this is not a trivial task but in this example we can 32017easily use the rejection trick: 32018Sample a random point 32019@iftex 32020@math{(X,Y)} 32021@end iftex 32022@ifhtml 32023@html 32024(<I>X</I>,<I>Y</I>) 32025@end html 32026@end ifhtml 32027@ifinfo 32028@math{(X,Y)} 32029@end ifinfo 32030uniformly in the 32031bounding rectangle 32032@iftex 32033@math{(0,\pi)\times(0,0.5).} 32034@end iftex 32035@ifhtml 32036@html 32037(0, pi)x(0,0.5). 32038@end html 32039@end ifhtml 32040@ifinfo 32041@math{(0, pi)x(0,0.5).} 32042@end ifinfo 32043This is easy since 32044each coordinate can be sampled independently from the respective 32045uniform distributions 32046@iftex 32047@math{U(0,\pi)} 32048@end iftex 32049@ifhtml 32050@html 32051<I>U</I>(0, pi) 32052@end html 32053@end ifhtml 32054@ifinfo 32055@math{U(0, pi)} 32056@end ifinfo 32057and 32058@iftex 32059@math{U(0,0.5).} 32060@end iftex 32061@ifhtml 32062@html 32063<I>U</I>(0,0.5). 32064@end html 32065@end ifhtml 32066@ifinfo 32067@math{U(0,0.5).} 32068@end ifinfo 32069Whenever the point falls into the shaded region below the graph 32070(indicated by dots in the figure), i.e., when 32071@iftex 32072@math{Y < sin(X)/2,} 32073@end iftex 32074@ifhtml 32075@html 32076<I>Y</I> < <I>sin</I>(<I>X</I>)/2, 32077@end html 32078@end ifhtml 32079@ifinfo 32080@math{Y < sin(X)/2,} 32081@end ifinfo 32082we accept it and return 32083@iftex 32084@math{X} 32085@end iftex 32086@ifhtml 32087@html 32088<I>X</I> 32089@end html 32090@end ifhtml 32091@ifinfo 32092@math{X} 32093@end ifinfo 32094as a random variate 32095from the distribution with density 32096@iftex 32097@math{f(x).} 32098@end iftex 32099@ifhtml 32100@html 32101<I>f</I>(<I>x</I>). 32102@end html 32103@end ifhtml 32104@ifinfo 32105@math{f(x).} 32106@end ifinfo 32107Otherwise we have to reject the point (indicated by small circles 32108in the figure), and try again. 32109 32110It is quite clear that this idea works for every distribution with 32111a bounded density on a bounded domain. Moreover, we can use this 32112procedure with any multiple of the density, i.e., with any positive 32113bounded function with bounded integral and it is not necessary to 32114know the integral of this function. So we use the term density in 32115the sequel for any positive function with bounded integral. 32116 32117From the figure we can conclude that the performance of a rejection 32118algorithm depends heavily on the area of the enveloping 32119rectangle. Moreover, the method does not work if the target 32120distribution has infinite tails (or is unbounded). Hence 32121non-rectangular shaped regions for the envelopes are important and 32122we have to solve the problem of sampling points uniformly from such 32123domains. Looking again at the example above we notice that the 32124@i{x}-coordinate of the random point 32125@iftex 32126@math{(X,Y)} 32127@end iftex 32128@ifhtml 32129@html 32130(<I>X</I>,<I>Y</I>) 32131@end html 32132@end ifhtml 32133@ifinfo 32134@math{(X,Y)} 32135@end ifinfo 32136was 32137sampled by inversion from the uniform distribution on the domain of 32138the given density. This motivates us to replace the density of the 32139uniform distribution by the (multiple of a) density 32140@iftex 32141@math{h(x)} 32142@end iftex 32143@ifhtml 32144@html 32145<I>h</I>(<I>x</I>) 32146@end html 32147@end ifhtml 32148@ifinfo 32149@math{h(x)} 32150@end ifinfo 32151of some other appropriate distribution. We only have to take care 32152that it is chosen such that it is always an upper bound, i.e., 32153@iftex 32154@math{h(x)\geq f(x)} 32155@end iftex 32156@ifhtml 32157@html 32158<I>h</I>(<I>x</I>) >= <I>f</I>(<I>x</I>) 32159@end html 32160@end ifhtml 32161@ifinfo 32162@math{h(x) >= f(x)} 32163@end ifinfo 32164for all 32165@iftex 32166@math{x} 32167@end iftex 32168@ifhtml 32169@html 32170<I>x</I> 32171@end html 32172@end ifhtml 32173@ifinfo 32174@math{x} 32175@end ifinfo 32176in the domain of the 32177distribution. To generate the pair 32178@iftex 32179@math{(X,Y)} 32180@end iftex 32181@ifhtml 32182@html 32183(<I>X</I>,<I>Y</I>) 32184@end html 32185@end ifhtml 32186@ifinfo 32187@math{(X,Y)} 32188@end ifinfo 32189we generate 32190@iftex 32191@math{X} 32192@end iftex 32193@ifhtml 32194@html 32195<I>X</I> 32196@end html 32197@end ifhtml 32198@ifinfo 32199@math{X} 32200@end ifinfo 32201from the distribution with density proportional to 32202@iftex 32203@math{h(x)} 32204@end iftex 32205@ifhtml 32206@html 32207<I>h</I>(<I>x</I>) 32208@end html 32209@end ifhtml 32210@ifinfo 32211@math{h(x)} 32212@end ifinfo 32213and 32214@iftex 32215@math{Y} 32216@end iftex 32217@ifhtml 32218@html 32219<I>Y</I> 32220@end html 32221@end ifhtml 32222@ifinfo 32223@math{Y} 32224@end ifinfo 32225uniformly between 32226@iftex 32227@math{0} 32228@end iftex 32229@ifhtml 32230@html 322310 32232@end html 32233@end ifhtml 32234@ifinfo 32235@math{0} 32236@end ifinfo 32237and 32238@iftex 32239@math{h(X).} 32240@end iftex 32241@ifhtml 32242@html 32243<I>h</I>(<I>X</I>). 32244@end html 32245@end ifhtml 32246@ifinfo 32247@math{h(X).} 32248@end ifinfo 32249The first step (generate 32250@iftex 32251@math{X} 32252@end iftex 32253@ifhtml 32254@html 32255<I>X</I> 32256@end html 32257@end ifhtml 32258@ifinfo 32259@math{X} 32260@end ifinfo 32261) is usually 32262done by inversion (@pxref{Inversion}). 32263 32264Thus the general rejection algorithm for a hat 32265@iftex 32266@math{h(x)} 32267@end iftex 32268@ifhtml 32269@html 32270<I>h</I>(<I>x</I>) 32271@end html 32272@end ifhtml 32273@ifinfo 32274@math{h(x)} 32275@end ifinfo 32276with 32277inverse CDF 32278@iftex 32279@math{H^{-1}} 32280@end iftex 32281@ifhtml 32282@html 32283<I>H</I><SUP>-1</SUP> 32284@end html 32285@end ifhtml 32286@ifinfo 32287@math{H^(-1)} 32288@end ifinfo 32289consists of the following steps: 32290@enumerate 32291@item 32292Generate a 32293@iftex 32294@math{U(0,1)} 32295@end iftex 32296@ifhtml 32297@html 32298<I>U</I>(0,1) 32299@end html 32300@end ifhtml 32301@ifinfo 32302@math{U(0,1)} 32303@end ifinfo 32304random number 32305@iftex 32306@math{U.} 32307@end iftex 32308@ifhtml 32309@html 32310<I>U</I>. 32311@end html 32312@end ifhtml 32313@ifinfo 32314@math{U.} 32315@end ifinfo 32316@item 32317Set 32318@iftex 32319@math{X} 32320@end iftex 32321@ifhtml 32322@html 32323<I>X</I> 32324@end html 32325@end ifhtml 32326@ifinfo 32327@math{X} 32328@end ifinfo 32329to 32330@iftex 32331@math{H^{-1}(U).} 32332@end iftex 32333@ifhtml 32334@html 32335<I>H</I><SUP>-1</SUP>(<I>U</I>). 32336@end html 32337@end ifhtml 32338@ifinfo 32339@math{H^(-1)(U).} 32340@end ifinfo 32341@item 32342Generate a 32343@iftex 32344@math{U(0,1)} 32345@end iftex 32346@ifhtml 32347@html 32348<I>U</I>(0,1) 32349@end html 32350@end ifhtml 32351@ifinfo 32352@math{U(0,1)} 32353@end ifinfo 32354random number 32355@iftex 32356@math{V.} 32357@end iftex 32358@ifhtml 32359@html 32360<I>V</I>. 32361@end html 32362@end ifhtml 32363@ifinfo 32364@math{V.} 32365@end ifinfo 32366@item 32367Set 32368@iftex 32369@math{Y} 32370@end iftex 32371@ifhtml 32372@html 32373<I>Y</I> 32374@end html 32375@end ifhtml 32376@ifinfo 32377@math{Y} 32378@end ifinfo 32379to 32380@iftex 32381@math{V h(X).} 32382@end iftex 32383@ifhtml 32384@html 32385<I>V</I> <I>h</I>(<I>X</I>). 32386@end html 32387@end ifhtml 32388@ifinfo 32389@math{V h(X).} 32390@end ifinfo 32391@item 32392If 32393@iftex 32394@math{Y\leq f(X)} 32395@end iftex 32396@ifhtml 32397@html 32398<I>Y</I> <= <I>f</I>(<I>X</I>) 32399@end html 32400@end ifhtml 32401@ifinfo 32402@math{Y <= f(X)} 32403@end ifinfo 32404accept 32405@iftex 32406@math{X} 32407@end iftex 32408@ifhtml 32409@html 32410<I>X</I> 32411@end html 32412@end ifhtml 32413@ifinfo 32414@math{X} 32415@end ifinfo 32416as the random variate. 32417@item 32418Else try again. 32419@end enumerate 32420 32421If the evaluation of the density 32422@iftex 32423@math{f(x)} 32424@end iftex 32425@ifhtml 32426@html 32427<I>f</I>(<I>x</I>) 32428@end html 32429@end ifhtml 32430@ifinfo 32431@math{f(x)} 32432@end ifinfo 32433is expensive 32434(i.e., time consuming) it is possible to use a simple lower bound 32435of the density as so called @emph{squeeze function} 32436@iftex 32437@math{s(x)} 32438@end iftex 32439@ifhtml 32440@html 32441<I>s</I>(<I>x</I>) 32442@end html 32443@end ifhtml 32444@ifinfo 32445@math{s(x)} 32446@end ifinfo 32447(the triangular shaped function in the above 32448figure is an example for such a squeeze). We can then accept 32449@iftex 32450@math{X} 32451@end iftex 32452@ifhtml 32453@html 32454<I>X</I> 32455@end html 32456@end ifhtml 32457@ifinfo 32458@math{X} 32459@end ifinfo 32460when 32461@iftex 32462@math{Y\leq s(X)} 32463@end iftex 32464@ifhtml 32465@html 32466<I>Y</I> <= <I>s</I>(<I>X</I>) 32467@end html 32468@end ifhtml 32469@ifinfo 32470@math{Y <= s(X)} 32471@end ifinfo 32472and can thus often save the 32473evaluation of the density. 32474 32475We have seen so far that the rejection principle leads to 32476short and simple generation algorithms. The main practical problem 32477to apply the rejection algorithm is the search for a good fitting 32478hat function and for squeezes. We do not discuss these topics here 32479as they are the heart of the different automatic algorithms 32480implemented in UNU.RAN. Information about the construction of hat 32481and squeeze can therefore be found in the descriptions of the 32482methods. 32483 32484The performance characteristics of rejection algorithms mainly 32485depend on the fit of the hat and the squeeze. It is not difficult 32486to prove that: 32487@itemize @bullet 32488@item 32489The expected number of trials to generate one variate is the ratio 32490between the area below the hat and the area below the density. 32491@item 32492The expected number of evaluations of the density necessary to 32493generate one variate is equal to the ratio between the area below 32494the hat and the area below the density, when no squeeze is used. 32495Otherwise, when a squeeze is given it is equal to the ratio 32496between the area between hat and squeeze and the area below the hat. 32497@item 32498The @code{sqhratio} (i.e., the ratio between the area below the 32499squeeze and the area below the hat) used in some of the UNU.RAN 32500methods is easy to compute. It is useful as its reciprocal is an 32501upper bound for the expected number of trials of the rejection 32502algoritm. The expected number of evaluations of the density is 32503bounded by 32504@iftex 32505@math{(1/sqhratio)-1.} 32506@end iftex 32507@ifhtml 32508@html 32509(1/<I>sqhratio</I>)-1. 32510@end html 32511@end ifhtml 32512@ifinfo 32513@math{(1/sqhratio)-1.} 32514@end ifinfo 32515@end itemize 32516 32517 32518 32519@c 32520@c end of arvag.dh 32521@c ------------------------------------- 32522@c ------------------------------------- 32523@c arvag.dh 32524@c 32525 32526@node Composition 32527@section The Composition Method 32528 32529 32530 32531The composition method is an important principle to facilitate and 32532speed up random variate generation. The basic idea is simple. 32533To generate random variates with a given density we first split the 32534domain of the density into subintervals. Then we select one of 32535these randomly with probabilities given by the area below the 32536density in the respective subintervals. Finally we generate a 32537random variate from the density of the selected part by inversion 32538and return it as random variate of the full distribution. 32539 32540Composition can be combined with rejection. Thus it is possible to 32541decompose the domain of the distribution into subintervals and to 32542construct hat and squeeze functions seperatly in every 32543subinterval. The area below the hat must be determined in every 32544subinterval. Then the Composition rejection algorithm contains the 32545following steps: 32546 32547@enumerate 32548@item 32549Generate the index 32550@iftex 32551@math{J} 32552@end iftex 32553@ifhtml 32554@html 32555<I>J</I> 32556@end html 32557@end ifhtml 32558@ifinfo 32559@math{J} 32560@end ifinfo 32561of the subinterval as the 32562realisation of a discrete random variate with probabilities 32563proportional to the area below the hat. 32564@item 32565Generate a random variate 32566@iftex 32567@math{X} 32568@end iftex 32569@ifhtml 32570@html 32571<I>X</I> 32572@end html 32573@end ifhtml 32574@ifinfo 32575@math{X} 32576@end ifinfo 32577proportional to the hat in 32578interval 32579@iftex 32580@math{J.} 32581@end iftex 32582@ifhtml 32583@html 32584<I>J</I>. 32585@end html 32586@end ifhtml 32587@ifinfo 32588@math{J.} 32589@end ifinfo 32590@item 32591Generate the 32592@iftex 32593@math{U(0,f(X))} 32594@end iftex 32595@ifhtml 32596@html 32597<I>U</I>(0,<I>f</I>(<I>X</I>)) 32598@end html 32599@end ifhtml 32600@ifinfo 32601@math{U(0,f(X))} 32602@end ifinfo 32603random number 32604@iftex 32605@math{Y.} 32606@end iftex 32607@ifhtml 32608@html 32609<I>Y</I>. 32610@end html 32611@end ifhtml 32612@ifinfo 32613@math{Y.} 32614@end ifinfo 32615@item 32616If 32617@iftex 32618@math{Y\leq f(X)} 32619@end iftex 32620@ifhtml 32621@html 32622<I>Y</I> <= <I>f</I>(<I>X</I>) 32623@end html 32624@end ifhtml 32625@ifinfo 32626@math{Y <= f(X)} 32627@end ifinfo 32628accept 32629@iftex 32630@math{X} 32631@end iftex 32632@ifhtml 32633@html 32634<I>X</I> 32635@end html 32636@end ifhtml 32637@ifinfo 32638@math{X} 32639@end ifinfo 32640as random variate. 32641@item 32642Else start again with generating the index 32643@iftex 32644@math{J.} 32645@end iftex 32646@ifhtml 32647@html 32648<I>J</I>. 32649@end html 32650@end ifhtml 32651@ifinfo 32652@math{J.} 32653@end ifinfo 32654@end enumerate 32655 32656The first step can be done in constant time (i.e., independent of 32657the number of chosen subintervals) by means of the indexed search 32658method (@pxref{IndexedSearch}). 32659 32660It is possible to reduce the number of uniform random numbers 32661required in the above algorithm by recycling the random numbers 32662used in Step 1 and additionally by applying the principle of 32663@emph{immediate acceptance}. 32664For details see 32665@ifhtml 32666@ref{bib:HLD04,, [HLD04: Sect. 3.1]} 32667@end ifhtml 32668@ifnothtml 32669[HLD04: Sect. 3.1] 32670@end ifnothtml 32671. 32672 32673 32674 32675@c 32676@c end of arvag.dh 32677@c ------------------------------------- 32678@c ------------------------------------- 32679@c arvag.dh 32680@c 32681 32682@node Ratio-of-Uniforms 32683@section The Ratio-of-Uniforms Method 32684 32685 32686 32687The construction of an appropriate hat function for the given 32688density is the crucial step for constructing rejection algorithms. 32689Equivalently we can try to find an appropriate envelope for the region 32690between the graph of the density and the @i{x}-axis, such 32691that we can easily sample uniformly distributed random points. 32692This task could become easier if we can find transformations that map 32693the region between the density and the axis into a region of more 32694suitable shape (for example into a bounded region). 32695 32696As a first example we consider the following simple algorithm for 32697the Cauchy distribution. 32698@enumerate 32699@item 32700Generate a 32701@iftex 32702@math{U(-1,1)} 32703@end iftex 32704@ifhtml 32705@html 32706<I>U</I>(-1,1) 32707@end html 32708@end ifhtml 32709@ifinfo 32710@math{U(-1,1)} 32711@end ifinfo 32712random number 32713@iftex 32714@math{U} 32715@end iftex 32716@ifhtml 32717@html 32718<I>U</I> 32719@end html 32720@end ifhtml 32721@ifinfo 32722@math{U} 32723@end ifinfo 32724and a 32725@iftex 32726@math{U(0,1)} 32727@end iftex 32728@ifhtml 32729@html 32730<I>U</I>(0,1) 32731@end html 32732@end ifhtml 32733@ifinfo 32734@math{U(0,1)} 32735@end ifinfo 32736random number 32737@iftex 32738@math{V.} 32739@end iftex 32740@ifhtml 32741@html 32742<I>V</I>. 32743@end html 32744@end ifhtml 32745@ifinfo 32746@math{V.} 32747@end ifinfo 32748@item 32749If 32750@iftex 32751@math{U^2 + V^2\leq 1} 32752@end iftex 32753@ifhtml 32754@html 32755<I>U</I><SUP>2</SUP> + <I>V</I><SUP>2</SUP> <= 1 32756@end html 32757@end ifhtml 32758@ifinfo 32759@math{U^2 + V^2 <= 1} 32760@end ifinfo 32761accept 32762@iftex 32763@math{X=U/V} 32764@end iftex 32765@ifhtml 32766@html 32767<I>X</I>=<I>U</I>/<I>V</I> 32768@end html 32769@end ifhtml 32770@ifinfo 32771@math{X=U/V} 32772@end ifinfo 32773as a Cauchy 32774random variate. 32775@item 32776Else try again. 32777@end enumerate 32778 32779It is possible to prove that the above algorithm indeed generates 32780Cauchy random variates. The fundamental principle behind this 32781algorithm is the fact that the region below the density is mapped 32782by the transformation 32783@iftex 32784 32785@quotation 32786@math{(X,Y)\mapsto(U,V)=(2\,X\sqrt{Y},2\,\sqrt{Y})} 32787@end quotation 32788 32789@end iftex 32790@ifhtml 32791@quotation 32792@html 32793(<I>X</I>,<I>Y</I>) -> (<I>U</I>,<I>V</I>)=(2 <I>X</I>sqrt(<I>Y</I>),2 sqrt(<I>Y</I>)) 32794@end html 32795@end quotation 32796@end ifhtml 32797@ifinfo 32798@quotation 32799@math{(X,Y) -> (U,V)=(2 Xsqrt(Y),2 sqrt(Y))} 32800@end quotation 32801@end ifinfo 32802 32803@noindent 32804into a half-disc in such a way that the ratio between the area of 32805the image to the area of the preimage is constant. This is due to 32806the fact that that the Jacobian of this transformation is constant. 32807 32808@sp 1 32809@image{figures/rou-cauchy} 32810@sp 1 32811 32812 32813The above example is a special case of a more general principle, 32814called the @emph{Ratio-of-uniforms (RoU) method}. It is based on 32815the fact that for a random variable 32816@iftex 32817@math{X} 32818@end iftex 32819@ifhtml 32820@html 32821<I>X</I> 32822@end html 32823@end ifhtml 32824@ifinfo 32825@math{X} 32826@end ifinfo 32827with density 32828@iftex 32829@math{f(x)} 32830@end iftex 32831@ifhtml 32832@html 32833<I>f</I>(<I>x</I>) 32834@end html 32835@end ifhtml 32836@ifinfo 32837@math{f(x)} 32838@end ifinfo 32839and some constant 32840@iftex 32841@math{\mu} 32842@end iftex 32843@ifhtml 32844@html 32845mu 32846@end html 32847@end ifhtml 32848@ifinfo 32849@math{mu} 32850@end ifinfo 32851we can generate 32852@iftex 32853@math{X} 32854@end iftex 32855@ifhtml 32856@html 32857<I>X</I> 32858@end html 32859@end ifhtml 32860@ifinfo 32861@math{X} 32862@end ifinfo 32863from the desired density by calculating 32864@iftex 32865@math{X=U/V+\mu} 32866@end iftex 32867@ifhtml 32868@html 32869<I>X</I>=<I>U</I>/<I>V</I>+ mu 32870@end html 32871@end ifhtml 32872@ifinfo 32873@math{X=U/V+ mu} 32874@end ifinfo 32875for a pair 32876@iftex 32877@math{(U,V)} 32878@end iftex 32879@ifhtml 32880@html 32881(<I>U</I>,<I>V</I>) 32882@end html 32883@end ifhtml 32884@ifinfo 32885@math{(U,V)} 32886@end ifinfo 32887uniformly 32888distributed in the set 32889@iftex 32890 32891@quotation 32892@math{A_f=\lbrace (u,v)\colon 0 < v \leq \sqrt{f(u/v+\mu)}\rbrace .} 32893@end quotation 32894 32895@end iftex 32896@ifhtml 32897@quotation 32898@html 32899<I>A</I>_<I>f</I>= @{ (<I>u</I>,<I>v</I>) : 0 < <I>v</I> <= sqrt(<I>f</I>(<I>u</I>/<I>v</I>+ mu)) @} . 32900@end html 32901@end quotation 32902@end ifhtml 32903@ifinfo 32904@quotation 32905@math{A_f= @{ (u,v) : 0 < v <= sqrt(f(u/v+ mu)) @} .} 32906@end quotation 32907@end ifinfo 32908 32909@noindent 32910For most distributions it is best to set the constant 32911@iftex 32912@math{\mu} 32913@end iftex 32914@ifhtml 32915@html 32916mu 32917@end html 32918@end ifhtml 32919@ifinfo 32920@math{mu} 32921@end ifinfo 32922equal to the mode of the distribution. For sampling 32923random points uniformly distributed in 32924@iftex 32925@math{A_f} 32926@end iftex 32927@ifhtml 32928@html 32929<I>A</I>_<I>f</I> 32930@end html 32931@end ifhtml 32932@ifinfo 32933@math{A_f} 32934@end ifinfo 32935rejection 32936from a convenient enveloping region is used, usually the minimal 32937bounding rectangle, i.e., the smallest possible rectangle that 32938contains 32939@iftex 32940@math{A_f} 32941@end iftex 32942@ifhtml 32943@html 32944<I>A</I>_<I>f</I> 32945@end html 32946@end ifhtml 32947@ifinfo 32948@math{A_f} 32949@end ifinfo 32950(see the above figure). 32951It is given by 32952@iftex 32953@math{(u^-,u^+)\times (0,v^+)} 32954@end iftex 32955@ifhtml 32956@html 32957(<I>u</I><SUP>-</SUP>,<I>u</I><SUP>+</SUP>)x(0,<I>v</I><SUP>+</SUP>) 32958@end html 32959@end ifhtml 32960@ifinfo 32961@math{(u^-,u^+)x(0,v^+)} 32962@end ifinfo 32963where 32964@iftex 32965 32966@quotation 32967@math{ v^+ = \sup\limits_{b_l<x<b_r} \sqrt{f(x)}, \hfil\break u^- = \inf\limits_{b_l<x<b_r} (x-\mu) \sqrt{f(x)}, \hfil\break u^+ = \sup\limits_{b_l<x<b_r} (x-\mu) \sqrt{f(x)}.} 32968@end quotation 32969 32970@end iftex 32971@ifhtml 32972@quotation 32973@html 32974<I>v</I><SUP>+</SUP> = sup_<I>b</I>_<I>l</I><<I>x</I><<I>b</I>_<I>r</I> sqrt(<I>f</I>(<I>x</I>)), @*<I>u</I><SUP>-</SUP> = inf_<I>b</I>_<I>l</I><<I>x</I><<I>b</I>_<I>r</I> (<I>x</I>- mu) sqrt(<I>f</I>(<I>x</I>)), @*<I>u</I><SUP>+</SUP> = sup_<I>b</I>_<I>l</I><<I>x</I><<I>b</I>_<I>r</I> (<I>x</I>- mu) sqrt(<I>f</I>(<I>x</I>)). 32975@end html 32976@end quotation 32977@end ifhtml 32978@ifinfo 32979@quotation 32980@math{v^+ = sup_(b_l<x<b_r) sqrt(f(x)), @*u^- = inf_(b_l<x<b_r) (x- mu) sqrt(f(x)), @*u^+ = sup_(b_l<x<b_r) (x- mu) sqrt(f(x)).} 32981@end quotation 32982@end ifinfo 32983 32984@noindent 32985Then the ratio-of-uniforms method consists of the following simple 32986steps: 32987@enumerate 32988@item 32989Generate a 32990@iftex 32991@math{U(u^-,u^+)} 32992@end iftex 32993@ifhtml 32994@html 32995<I>U</I>(<I>u</I><SUP>-</SUP>,<I>u</I><SUP>+</SUP>) 32996@end html 32997@end ifhtml 32998@ifinfo 32999@math{U(u^-,u^+)} 33000@end ifinfo 33001random number 33002@iftex 33003@math{U} 33004@end iftex 33005@ifhtml 33006@html 33007<I>U</I> 33008@end html 33009@end ifhtml 33010@ifinfo 33011@math{U} 33012@end ifinfo 33013and a 33014@iftex 33015@math{U(0,v^+)} 33016@end iftex 33017@ifhtml 33018@html 33019<I>U</I>(0,<I>v</I><SUP>+</SUP>) 33020@end html 33021@end ifhtml 33022@ifinfo 33023@math{U(0,v^+)} 33024@end ifinfo 33025random number 33026@iftex 33027@math{V.} 33028@end iftex 33029@ifhtml 33030@html 33031<I>V</I>. 33032@end html 33033@end ifhtml 33034@ifinfo 33035@math{V.} 33036@end ifinfo 33037@item 33038Set 33039@iftex 33040@math{X} 33041@end iftex 33042@ifhtml 33043@html 33044<I>X</I> 33045@end html 33046@end ifhtml 33047@ifinfo 33048@math{X} 33049@end ifinfo 33050to 33051@iftex 33052@math{U/V+\mu.} 33053@end iftex 33054@ifhtml 33055@html 33056<I>U</I>/<I>V</I>+ mu. 33057@end html 33058@end ifhtml 33059@ifinfo 33060@math{U/V+ mu.} 33061@end ifinfo 33062@item 33063If 33064@iftex 33065@math{V^2 \leq f(X)} 33066@end iftex 33067@ifhtml 33068@html 33069<I>V</I><SUP>2</SUP> <= <I>f</I>(<I>X</I>) 33070@end html 33071@end ifhtml 33072@ifinfo 33073@math{V^2 <= f(X)} 33074@end ifinfo 33075accept 33076@iftex 33077@math{X} 33078@end iftex 33079@ifhtml 33080@html 33081<I>X</I> 33082@end html 33083@end ifhtml 33084@ifinfo 33085@math{X} 33086@end ifinfo 33087as the random 33088variate. 33089@item 33090Else try again. 33091@end enumerate 33092 33093To apply the ratio-of-uniforms algorithm to a certain density 33094we have to solve the simple optimization problems in the 33095definitions above to obtain the design constants 33096@iftex 33097@math{u^-,} 33098@end iftex 33099@ifhtml 33100@html 33101<I>u</I><SUP>-</SUP>, 33102@end html 33103@end ifhtml 33104@ifinfo 33105@math{u^-,} 33106@end ifinfo 33107@iftex 33108@math{u^+,} 33109@end iftex 33110@ifhtml 33111@html 33112<I>u</I><SUP>+</SUP>, 33113@end html 33114@end ifhtml 33115@ifinfo 33116@math{u^+,} 33117@end ifinfo 33118and 33119@iftex 33120@math{v^+.} 33121@end iftex 33122@ifhtml 33123@html 33124<I>v</I><SUP>+</SUP>. 33125@end html 33126@end ifhtml 33127@ifinfo 33128@math{v^+.} 33129@end ifinfo 33130This simple algorithm works for all distributions 33131with bounded densities that have subquadratic tails (i.e., 33132tails like 33133@iftex 33134@math{1/x^2} 33135@end iftex 33136@ifhtml 33137@html 331381/<I>x</I><SUP>2</SUP> 33139@end html 33140@end ifhtml 33141@ifinfo 33142@math{1/x^2} 33143@end ifinfo 33144or lower). For most standard 33145distributions it has quite good rejection constants. 33146(E.g. 1.3688 for the normal and 1.4715 for the exponential 33147distribution.) 33148 33149Nevertheless, we use more sophisticated method that construct 33150better fitting envelopes, like method AROU (@pxref{AROU}), or even 33151avoid the computation of these design constants and thus have 33152almost no setup, like method SROU (@pxref{SROU}). 33153 33154@subheading The Generalized Ratio-of-Uniforms Method 33155 33156The Ratio-of-Uniforms method can be generalized: If a point 33157@iftex 33158@math{(U,V)} 33159@end iftex 33160@ifhtml 33161@html 33162(<I>U</I>,<I>V</I>) 33163@end html 33164@end ifhtml 33165@ifinfo 33166@math{(U,V)} 33167@end ifinfo 33168is uniformly distributed in the set 33169@iftex 33170 33171@quotation 33172@math{A_f=\lbrace (u,v)\colon 0 < v \leq (f(u/v^r+\mu))^{1/(r+1)}\rbrace } 33173@end quotation 33174 33175@end iftex 33176@ifhtml 33177@quotation 33178@html 33179<I>A</I>_<I>f</I>= @{ (<I>u</I>,<I>v</I>) : 0 < <I>v</I> <= (<I>f</I>(<I>u</I>/<I>v</I><SUP><I>r</I></SUP>+ mu))<SUP>1/(<I>r</I>+1)</SUP> @} 33180@end html 33181@end quotation 33182@end ifhtml 33183@ifinfo 33184@quotation 33185@math{A_f= @{ (u,v) : 0 < v <= (f(u/v^r+ mu))^(1/(r+1)) @}} 33186@end quotation 33187@end ifinfo 33188 33189@noindent 33190then 33191@iftex 33192@math{X=U/V^r+\mu} 33193@end iftex 33194@ifhtml 33195@html 33196<I>X</I>=<I>U</I>/<I>V</I><SUP><I>r</I></SUP>+ mu 33197@end html 33198@end ifhtml 33199@ifinfo 33200@math{X=U/V^r+ mu} 33201@end ifinfo 33202has the denity 33203@iftex 33204@math{f(x).} 33205@end iftex 33206@ifhtml 33207@html 33208<I>f</I>(<I>x</I>). 33209@end html 33210@end ifhtml 33211@ifinfo 33212@math{f(x).} 33213@end ifinfo 33214The minimal bounding rectangle of this region is given by 33215@iftex 33216@math{(u^-,u^+)\times (0,v^+)} 33217@end iftex 33218@ifhtml 33219@html 33220(<I>u</I><SUP>-</SUP>,<I>u</I><SUP>+</SUP>)x(0,<I>v</I><SUP>+</SUP>) 33221@end html 33222@end ifhtml 33223@ifinfo 33224@math{(u^-,u^+)x(0,v^+)} 33225@end ifinfo 33226where 33227@iftex 33228 33229@quotation 33230@math{ v^+ = \sup\limits_{b_l<x<b_r} (f(x))^{1/(r+1)}, \hfil\break u^- = \inf\limits_{b_l<x<b_r} (x-\mu) (f(x))^{r/(r+1)}, \hfil\break u^+ = \sup\limits_{b_l<x<b_r} (x-\mu) (f(x))^{r/(r+1)}. } 33231@end quotation 33232 33233@end iftex 33234@ifhtml 33235@quotation 33236@html 33237<I>v</I><SUP>+</SUP> = sup_<I>b</I>_<I>l</I><<I>x</I><<I>b</I>_<I>r</I> (<I>f</I>(<I>x</I>))<SUP>1/(<I>r</I>+1)</SUP>, @*<I>u</I><SUP>-</SUP> = inf_<I>b</I>_<I>l</I><<I>x</I><<I>b</I>_<I>r</I> (<I>x</I>- mu) (<I>f</I>(<I>x</I>))<SUP><I>r</I>/(<I>r</I>+1)</SUP>, @*<I>u</I><SUP>+</SUP> = sup_<I>b</I>_<I>l</I><<I>x</I><<I>b</I>_<I>r</I> (<I>x</I>- mu) (<I>f</I>(<I>x</I>))<SUP><I>r</I>/(<I>r</I>+1)</SUP>. 33238@end html 33239@end quotation 33240@end ifhtml 33241@ifinfo 33242@quotation 33243@math{v^+ = sup_(b_l<x<b_r) (f(x))^(1/(r+1)), @*u^- = inf_(b_l<x<b_r) (x- mu) (f(x))^(r/(r+1)), @*u^+ = sup_(b_l<x<b_r) (x- mu) (f(x))^(r/(r+1)).} 33244@end quotation 33245@end ifinfo 33246 33247@noindent 33248The above algorithm has then to be adjusted accordingly. 33249Notice that the original Ratio-of-Uniforms method is the special 33250case with 33251@iftex 33252@math{r=1.} 33253@end iftex 33254@ifhtml 33255@html 33256<I>r</I>=1. 33257@end html 33258@end ifhtml 33259@ifinfo 33260@math{r=1.} 33261@end ifinfo 33262 33263 33264 33265@c 33266@c end of arvag.dh 33267@c ------------------------------------- 33268@c ------------------------------------- 33269@c arvag.dh 33270@c 33271 33272@node DiscreteInversion 33273@section Inversion for Discrete Distributions 33274 33275 33276 33277We have already presented the idea of the inversion method to 33278generate from continuous random variables (@pxref{Inversion}). For 33279a discrete random variable 33280@iftex 33281@math{X} 33282@end iftex 33283@ifhtml 33284@html 33285<I>X</I> 33286@end html 33287@end ifhtml 33288@ifinfo 33289@math{X} 33290@end ifinfo 33291we can write it 33292mathematically in the same way: 33293@iftex 33294 33295@quotation 33296@math{X=F^{-1}(U),} 33297@end quotation 33298 33299@end iftex 33300@ifhtml 33301@quotation 33302@html 33303<I>X</I>=<I>F</I><SUP>-1</SUP>(<I>U</I>), 33304@end html 33305@end quotation 33306@end ifhtml 33307@ifinfo 33308@quotation 33309@math{X=F^(-1)(U),} 33310@end quotation 33311@end ifinfo 33312 33313@noindent 33314where 33315@iftex 33316@math{F} 33317@end iftex 33318@ifhtml 33319@html 33320<I>F</I> 33321@end html 33322@end ifhtml 33323@ifinfo 33324@math{F} 33325@end ifinfo 33326is the CDF of the desired distribution and 33327@iftex 33328@math{U} 33329@end iftex 33330@ifhtml 33331@html 33332<I>U</I> 33333@end html 33334@end ifhtml 33335@ifinfo 33336@math{U} 33337@end ifinfo 33338is a uniform 33339@iftex 33340@math{U(0,1)} 33341@end iftex 33342@ifhtml 33343@html 33344<I>U</I>(0,1) 33345@end html 33346@end ifhtml 33347@ifinfo 33348@math{U(0,1)} 33349@end ifinfo 33350random number. The 33351difference compared to the continuous case is that 33352@iftex 33353@math{F} 33354@end iftex 33355@ifhtml 33356@html 33357<I>F</I> 33358@end html 33359@end ifhtml 33360@ifinfo 33361@math{F} 33362@end ifinfo 33363is 33364now a step-function. The following figure illustrates the idea of 33365discrete inversion for a simple distribution. 33366 33367@sp 1 33368@image{figures/discrete_inversion} 33369@sp 1 33370 33371 33372To realize this idea on a computer we have to use a search 33373algorithm. For the simplest version called @emph{Sequential Search} 33374the CDF is computed on-the-fly as sum of the probabilities 33375@iftex 33376@math{p(k),} 33377@end iftex 33378@ifhtml 33379@html 33380<I>p</I>(<I>k</I>), 33381@end html 33382@end ifhtml 33383@ifinfo 33384@math{p(k),} 33385@end ifinfo 33386since this is usually much cheaper than computing 33387the CDF directly. It is obvious that the basic form of the search 33388algorithm only works for discrete random variables with probability 33389mass functions 33390@iftex 33391@math{p(k)} 33392@end iftex 33393@ifhtml 33394@html 33395<I>p</I>(<I>k</I>) 33396@end html 33397@end ifhtml 33398@ifinfo 33399@math{p(k)} 33400@end ifinfo 33401for nonnegative 33402@iftex 33403@math{k.} 33404@end iftex 33405@ifhtml 33406@html 33407<I>k</I>. 33408@end html 33409@end ifhtml 33410@ifinfo 33411@math{k.} 33412@end ifinfo 33413The 33414sequential search algorithm consists of the following basic steps: 33415 33416@enumerate 33417@item 33418Generate a 33419@iftex 33420@math{U(0,1)} 33421@end iftex 33422@ifhtml 33423@html 33424<I>U</I>(0,1) 33425@end html 33426@end ifhtml 33427@ifinfo 33428@math{U(0,1)} 33429@end ifinfo 33430random number 33431@iftex 33432@math{U.} 33433@end iftex 33434@ifhtml 33435@html 33436<I>U</I>. 33437@end html 33438@end ifhtml 33439@ifinfo 33440@math{U.} 33441@end ifinfo 33442@item 33443Set 33444@iftex 33445@math{X} 33446@end iftex 33447@ifhtml 33448@html 33449<I>X</I> 33450@end html 33451@end ifhtml 33452@ifinfo 33453@math{X} 33454@end ifinfo 33455to 33456@iftex 33457@math{0} 33458@end iftex 33459@ifhtml 33460@html 334610 33462@end html 33463@end ifhtml 33464@ifinfo 33465@math{0} 33466@end ifinfo 33467and 33468@iftex 33469@math{P} 33470@end iftex 33471@ifhtml 33472@html 33473<I>P</I> 33474@end html 33475@end ifhtml 33476@ifinfo 33477@math{P} 33478@end ifinfo 33479to 33480@iftex 33481@math{p(0).} 33482@end iftex 33483@ifhtml 33484@html 33485<I>p</I>(0). 33486@end html 33487@end ifhtml 33488@ifinfo 33489@math{p(0).} 33490@end ifinfo 33491@item 33492Do while 33493@iftex 33494@math{U > P} 33495@end iftex 33496@ifhtml 33497@html 33498<I>U</I> > <I>P</I> 33499@end html 33500@end ifhtml 33501@ifinfo 33502@math{U > P} 33503@end ifinfo 33504@item 33505@w{ } @w{ } @w{ } Set 33506@iftex 33507@math{X} 33508@end iftex 33509@ifhtml 33510@html 33511<I>X</I> 33512@end html 33513@end ifhtml 33514@ifinfo 33515@math{X} 33516@end ifinfo 33517to 33518@iftex 33519@math{X+1} 33520@end iftex 33521@ifhtml 33522@html 33523<I>X</I>+1 33524@end html 33525@end ifhtml 33526@ifinfo 33527@math{X+1} 33528@end ifinfo 33529and 33530@iftex 33531@math{P} 33532@end iftex 33533@ifhtml 33534@html 33535<I>P</I> 33536@end html 33537@end ifhtml 33538@ifinfo 33539@math{P} 33540@end ifinfo 33541to 33542@iftex 33543@math{P+p(X).} 33544@end iftex 33545@ifhtml 33546@html 33547<I>P</I>+<I>p</I>(<I>X</I>). 33548@end html 33549@end ifhtml 33550@ifinfo 33551@math{P+p(X).} 33552@end ifinfo 33553@item 33554Return 33555@iftex 33556@math{X.} 33557@end iftex 33558@ifhtml 33559@html 33560<I>X</I>. 33561@end html 33562@end ifhtml 33563@ifinfo 33564@math{X.} 33565@end ifinfo 33566@end enumerate 33567 33568With the exception of some very simple discrete distributions, 33569sequential search algorithms become very slow as the while-loop has 33570to be repeated very often. The expected number of iterations, 33571i.e., the number of comparisons in the while condition, is equal to 33572the expectation of the distribution plus 33573@iftex 33574@math{1.} 33575@end iftex 33576@ifhtml 33577@html 335781. 33579@end html 33580@end ifhtml 33581@ifinfo 33582@math{1.} 33583@end ifinfo 33584It can therefore become arbitrary large or even infinity if the tail 33585of the distribution is very heavy. Another serious problem can be 33586critical round-off errors due to summing up many probabilities 33587@iftex 33588@math{p(k).} 33589@end iftex 33590@ifhtml 33591@html 33592<I>p</I>(<I>k</I>). 33593@end html 33594@end ifhtml 33595@ifinfo 33596@math{p(k).} 33597@end ifinfo 33598To speed up the search procedure it is best to use 33599indexed search. 33600 33601 33602 33603@c 33604@c end of arvag.dh 33605@c ------------------------------------- 33606@c ------------------------------------- 33607@c arvag.dh 33608@c 33609 33610@node IndexedSearch 33611@section Indexed Search (Guide Table Method) 33612 33613 33614 33615The idea to speed up the sequential search algorithm is easy to 33616understand. Instead of starting always at 33617@iftex 33618@math{0} 33619@end iftex 33620@ifhtml 33621@html 336220 33623@end html 33624@end ifhtml 33625@ifinfo 33626@math{0} 33627@end ifinfo 33628we store a 33629table of size 33630@iftex 33631@math{C} 33632@end iftex 33633@ifhtml 33634@html 33635<I>C</I> 33636@end html 33637@end ifhtml 33638@ifinfo 33639@math{C} 33640@end ifinfo 33641with starting points for our search. For 33642this table we compute 33643@iftex 33644@math{F^{-1}(U)} 33645@end iftex 33646@ifhtml 33647@html 33648<I>F</I><SUP>-1</SUP>(<I>U</I>) 33649@end html 33650@end ifhtml 33651@ifinfo 33652@math{F^(-1)(U)} 33653@end ifinfo 33654for 33655@iftex 33656@math{C} 33657@end iftex 33658@ifhtml 33659@html 33660<I>C</I> 33661@end html 33662@end ifhtml 33663@ifinfo 33664@math{C} 33665@end ifinfo 33666equidistributed values of 33667@iftex 33668@math{U,} 33669@end iftex 33670@ifhtml 33671@html 33672<I>U</I>, 33673@end html 33674@end ifhtml 33675@ifinfo 33676@math{U,} 33677@end ifinfo 33678i.e., 33679for 33680@iftex 33681@math{u_i = i/C,} 33682@end iftex 33683@ifhtml 33684@html 33685<I>u</I>_<I>i</I> = <I>i</I>/<I>C</I>, 33686@end html 33687@end ifhtml 33688@ifinfo 33689@math{u_i = i/C,} 33690@end ifinfo 33691@iftex 33692@math{i=0,...,C-1.} 33693@end iftex 33694@ifhtml 33695@html 33696<I>i</I>=0,...,<I>C</I>-1. 33697@end html 33698@end ifhtml 33699@ifinfo 33700@math{i=0,...,C-1.} 33701@end ifinfo 33702Such a table is 33703called @emph{guide table} or @emph{hash table}. 33704Then it is easy to prove that for every 33705@iftex 33706@math{U} 33707@end iftex 33708@ifhtml 33709@html 33710<I>U</I> 33711@end html 33712@end ifhtml 33713@ifinfo 33714@math{U} 33715@end ifinfo 33716in 33717@iftex 33718@math{(0,1)} 33719@end iftex 33720@ifhtml 33721@html 33722(0,1) 33723@end html 33724@end ifhtml 33725@ifinfo 33726@math{(0,1)} 33727@end ifinfo 33728the guide table entry for 33729@iftex 33730@math{k=floor(UC)} 33731@end iftex 33732@ifhtml 33733@html 33734<I>k</I>=<I>floor</I>(<I>UC</I>) 33735@end html 33736@end ifhtml 33737@ifinfo 33738@math{k=floor(UC)} 33739@end ifinfo 33740is bounded by 33741@iftex 33742@math{F^{-1}(U).} 33743@end iftex 33744@ifhtml 33745@html 33746<I>F</I><SUP>-1</SUP>(<I>U</I>). 33747@end html 33748@end ifhtml 33749@ifinfo 33750@math{F^(-1)(U).} 33751@end ifinfo 33752This shows that we can really 33753start our sequential search procedure from the table entry for 33754@iftex 33755@math{k} 33756@end iftex 33757@ifhtml 33758@html 33759<I>k</I> 33760@end html 33761@end ifhtml 33762@ifinfo 33763@math{k} 33764@end ifinfo 33765and the index 33766@iftex 33767@math{k} 33768@end iftex 33769@ifhtml 33770@html 33771<I>k</I> 33772@end html 33773@end ifhtml 33774@ifinfo 33775@math{k} 33776@end ifinfo 33777of the correct table entry 33778can be found rapidly by means of the truncation operation. 33779 33780The two main differences between @emph{indexed search} and 33781@emph{sequential search} are that we start searching at the number 33782determined by the guide table, and that we have to compute and 33783store the cumulative probabilities in the setup as we have to know 33784the cumulative probability for the starting point of the search 33785algorithm. The rounding problems that can occur in the sequential 33786search algorithm can occur here as well. 33787Compared to sequential search we have now the obvious drawback 33788of a slow setup. The computation of the cumulative probabilities 33789grows linear with the size of the domain of the distribution 33790@iftex 33791@math{L.} 33792@end iftex 33793@ifhtml 33794@html 33795<I>L</I>. 33796@end html 33797@end ifhtml 33798@ifinfo 33799@math{L.} 33800@end ifinfo 33801What we gain is really high speed as the marginal 33802execution time of the sampling algorithm becomes very small. The 33803expected number of comparisons is bounded by 33804@iftex 33805@math{1+L/C.} 33806@end iftex 33807@ifhtml 33808@html 338091+<I>L</I>/<I>C</I>. 33810@end html 33811@end ifhtml 33812@ifinfo 33813@math{1+L/C.} 33814@end ifinfo 33815This shows that there is a trade-off between speed and 33816the size of the guide table. Cache-effects in modern computers will 33817however slow down the speed-up for really large table sizes. 33818Thus we recommend to use a guide table that is about two times 33819larger than the probability vector to obtain optimal speed. 33820 33821 33822 33823@c 33824@c end of arvag.dh 33825@c ------------------------------------- 33826@c ------------------------------------- 33827@c glossary.dh 33828@c 33829 33830@node Glossary 33831@appendix Glossary 33832 33833 33834 33835@table @strong 33836 33837@item CDF 33838cumulative distribution function. 33839 33840@item HR 33841hazard rate (or failure rate). 33842 33843@item inverse local concavity 33844local concavity of inverse PDF 33845@iftex 33846@math{f^{-1}(y)} 33847@end iftex 33848@ifhtml 33849@html 33850<I>f</I><SUP>-1</SUP>(<I>y</I>) 33851@end html 33852@end ifhtml 33853@ifinfo 33854@math{f^(-1)(y)} 33855@end ifinfo 33856expressed in term of 33857@iftex 33858@math{x = f^{-1}(y).} 33859@end iftex 33860@ifhtml 33861@html 33862<I>x</I> = <I>f</I><SUP>-1</SUP>(<I>y</I>). 33863@end html 33864@end ifhtml 33865@ifinfo 33866@math{x = f^(-1)(y).} 33867@end ifinfo 33868Is is given by 33869@iftex 33870@math{ilc_f(x) = 1 + x\,f''(x) / f'(x)} 33871@end iftex 33872@ifhtml 33873@html 33874<I>ilc</I>_<I>f</I>(<I>x</I>) = 1 + <I>x</I> <I>f</I>''(<I>x</I>) / <I>f</I>'(<I>x</I>) 33875@end html 33876@end ifhtml 33877@ifinfo 33878@math{ilc_f(x) = 1 + x f''(x) / f'(x)} 33879@end ifinfo 33880 33881@item local concavity 33882maximum value of @i{c} such that PDF @i{f(x)} is 33883@iftex 33884@math{T_c.} 33885@end iftex 33886@ifhtml 33887@html 33888<I>T</I>_<I>c</I>. 33889@end html 33890@end ifhtml 33891@ifinfo 33892@math{T_c.} 33893@end ifinfo 33894Is is given by 33895@iftex 33896@math{lc_f(x) = 1 - f''(x)\,f(x) / f'(x)^2} 33897@end iftex 33898@ifhtml 33899@html 33900<I>lc</I>_<I>f</I>(<I>x</I>) = 1 - <I>f</I>''(<I>x</I>) <I>f</I>(<I>x</I>) / <I>f</I>'(<I>x</I>)<SUP>2</SUP> 33901@end html 33902@end ifhtml 33903@ifinfo 33904@math{lc_f(x) = 1 - f''(x) f(x) / f'(x)^2} 33905@end ifinfo 33906 33907@item PDF 33908probability density function. 33909 33910@item dPDF 33911derivative (gradient) of probability density function. 33912 33913@item PMF 33914probability mass function. 33915 33916@item PV 33917(finite) probability vector. 33918 33919@item URNG 33920uniform random number generator. 33921 33922@item @math{U(a,b)} 33923continuous uniform distribution on the interval 33924@iftex 33925@math{(a,b).} 33926@end iftex 33927@ifhtml 33928@html 33929(<I>a</I>,<I>b</I>). 33930@end html 33931@end ifhtml 33932@ifinfo 33933@math{(a,b).} 33934@end ifinfo 33935 33936@item T-concave 33937a function @i{f(x)} is called @i{T}-convace if the transformed function 33938@i{T(f(x))} is concave. 33939We only deal with transformations 33940@iftex 33941@math{T_c,} 33942@end iftex 33943@ifhtml 33944@html 33945<I>T</I>_<I>c</I>, 33946@end html 33947@end ifhtml 33948@ifinfo 33949@math{T_c,} 33950@end ifinfo 33951where 33952@table @code 33953@item @i{c} = 0 33954@iftex 33955@math{T(x) = \log(x)} 33956@end iftex 33957@ifhtml 33958@html 33959<I>T</I>(<I>x</I>) = log(<I>x</I>) 33960@end html 33961@end ifhtml 33962@ifinfo 33963@math{T(x) = log(x)} 33964@end ifinfo 33965@item @i{c} = @math{-0.5} 33966@iftex 33967@math{T(x) = -1/\sqrt{x}} 33968@end iftex 33969@ifhtml 33970@html 33971<I>T</I>(<I>x</I>) = -1/sqrt(<I>x</I>) 33972@end html 33973@end ifhtml 33974@ifinfo 33975@math{T(x) = -1/sqrt(x)} 33976@end ifinfo 33977@item @i{c} != 0 33978@iftex 33979@math{T(x) = sign(x) \cdot x^c} 33980@end iftex 33981@ifhtml 33982@html 33983<I>T</I>(<I>x</I>) = <I>sign</I>(<I>x</I>) * <I>x</I><SUP><I>c</I></SUP> 33984@end html 33985@end ifhtml 33986@ifinfo 33987@math{T(x) = sign(x) * x^c} 33988@end ifinfo 33989@end table 33990 33991@item u-error 33992for a given approximate inverse CDF 33993@iftex 33994@math{X=G^{-1}(U)} 33995@end iftex 33996@ifhtml 33997@html 33998<I>X</I>=<I>G</I><SUP>-1</SUP>(<I>U</I>) 33999@end html 34000@end ifhtml 34001@ifinfo 34002@math{X=G^(-1)(U)} 34003@end ifinfo 34004the u-error is given as 34005@iftex 34006 34007@quotation 34008@math{uerror = |U-F(G^{-1}(U))|} 34009@end quotation 34010 34011@end iftex 34012@ifhtml 34013@quotation 34014@html 34015<I>uerror</I> = |<I>U</I>-<I>F</I>(<I>G</I><SUP>-1</SUP>(<I>U</I>))| 34016@end html 34017@end quotation 34018@end ifhtml 34019@ifinfo 34020@quotation 34021@math{uerror = |U-F(G^(-1)(U))|} 34022@end quotation 34023@end ifinfo 34024 34025@noindent 34026where 34027@iftex 34028@math{F} 34029@end iftex 34030@ifhtml 34031@html 34032<I>F</I> 34033@end html 34034@end ifhtml 34035@ifinfo 34036@math{F} 34037@end ifinfo 34038denotes the exact CDF. 34039Goodness-of-fit tests like the Kolmogorov-Smirnov test or the 34040chi-squared test look at this type of error. 34041See @ref{Inversion} for more details. 34042 34043@item u-resolution 34044the maximal tolerated u-error for an approximate inverse CDF. 34045 34046@item x-error 34047for a given approximate inverse CDF 34048@iftex 34049@math{X=G^{-1}(U)} 34050@end iftex 34051@ifhtml 34052@html 34053<I>X</I>=<I>G</I><SUP>-1</SUP>(<I>U</I>) 34054@end html 34055@end ifhtml 34056@ifinfo 34057@math{X=G^(-1)(U)} 34058@end ifinfo 34059the x-error is given as 34060@iftex 34061 34062@quotation 34063@math{xerror = |F^{-1}(U)-G^{-1}(U)|} 34064@end quotation 34065 34066@end iftex 34067@ifhtml 34068@quotation 34069@html 34070<I>xerror</I> = |<I>F</I><SUP>-1</SUP>(<I>U</I>)-<I>G</I><SUP>-1</SUP>(<I>U</I>)| 34071@end html 34072@end quotation 34073@end ifhtml 34074@ifinfo 34075@quotation 34076@math{xerror = |F^(-1)(U)-G^(-1)(U)|} 34077@end quotation 34078@end ifinfo 34079 34080@noindent 34081where 34082@iftex 34083@math{F^{-1}} 34084@end iftex 34085@ifhtml 34086@html 34087<I>F</I><SUP>-1</SUP> 34088@end html 34089@end ifhtml 34090@ifinfo 34091@math{F^(-1)} 34092@end ifinfo 34093denotes the exact inverse CDF. 34094The x-error measure the deviation of 34095@iftex 34096@math{G^{-1}(U)} 34097@end iftex 34098@ifhtml 34099@html 34100<I>G</I><SUP>-1</SUP>(<I>U</I>) 34101@end html 34102@end ifhtml 34103@ifinfo 34104@math{G^(-1)(U)} 34105@end ifinfo 34106from the exact result. 34107Notice that we have to distinguish between @emph{absolute} and 34108@emph{relative} x-error. In UNU.RAN we use the absolute x-error near 0 34109and the relative x-error otherwise. 34110See @ref{Inversion} for more details. 34111 34112@item x-resolution 34113the maximal tolerated x-error for an approximate inverse CDF. 34114 34115@end table 34116 34117 34118 34119@c 34120@c end of glossary.dh 34121@c ------------------------------------- 34122@c ------------------------------------- 34123@c references.dh 34124@c 34125 34126@node Bibliography 34127@appendix Bibliography 34128 34129 34130 34131@subheading Standard Distributions 34132 34133@table @t 34134 34135@anchor{bib:JKKa92} 34136@item [JKKa92] 34137@sc{N.L. Johnson, S. Kotz, and A.W. Kemp} (1992). 34138@i{Univariate Discrete Distributions}, 341392nd edition, 34140John Wiley & Sons, Inc., New York. 34141 34142@anchor{bib:JKBb94} 34143@item [JKBb94] 34144@sc{N.L. Johnson, S. Kotz, and N. Balakrishnan} (1994). 34145@i{Continuous Univariate Distributions}, 34146Volume 1, 341472nd edition, 34148John Wiley & Sons, Inc., New York. 34149 34150@anchor{bib:JKBc95} 34151@item [JKBc95] 34152@sc{N.L. Johnson, S. Kotz, and N. Balakrishnan} (1995). 34153@i{Continuous Univariate Distributions}, 34154Volume 2, 341552nd edition, 34156John Wiley & Sons, Inc., New York. 34157 34158@anchor{bib:JKBd97} 34159@item [JKBd97] 34160@sc{N.L. Johnson, S. Kotz, and N. Balakrishnan} (1997). 34161@i{Discrete Multivariate Distributions}, 34162John Wiley & Sons, Inc., New York. 34163 34164@anchor{bib:KBJe00} 34165@item [KBJe00] 34166@sc{S. Kotz, N. Balakrishnan, and N.L. Johnson} (2000). 34167@i{Continuous Multivariate Distributions}, 34168Volume 1: Models and Applications, 34169John Wiley & Sons, Inc., New York. 34170 34171@end table 34172 34173@c ------------------------------------------------------- 34174 34175@subheading Universal Methods -- Surveys 34176 34177@table @t 34178 34179@anchor{bib:HLD04} 34180@item [HLD04] 34181@sc{W. H@"ormann, J. Leydold, and G. Derflinger} (2004). 34182@i{Automatic Nonuniform Random Variate Generation}, 34183Springer, Berlin. 34184 34185@end table 34186 34187@c ------------------------------------------------------- 34188 34189@subheading Universal Methods 34190 34191@table @t 34192 34193@anchor{bib:AJa93} 34194@item [AJa93] 34195@sc{J.H. Ahrens} (1993). 34196@i{Sampling from general distributions by suboptimal division of domains}, 34197Grazer Math. Berichte 319, 30pp. 34198 34199@anchor{bib:AJa95} 34200@item [AJa95] 34201@sc{J.H. Ahrens} (1995). 34202@i{An one-table method for sampling from continuous and discrete distributions}, 34203Computing 54(2), pp. 127-146. 34204 34205@anchor{bib:CAa74} 34206@item [CAa74] 34207@sc{H.C. Chen and Y. Asau} (1974). 34208@i{On generating random variates from an empirical distribution}, 34209AIIE Trans. 6, pp. 163-166. 34210 34211@anchor{bib:DHLa08} 34212@item [DHLa08] 34213@sc{G. Derflinger, W. H@"ormann, and J. Leydold} (2008). 34214@i{Numerical inversion when only the density function is known}, 34215Research Report Series of the Department of Statistics and Mathematics 78, 34216WU Wien, Augasse 2--6, A-1090 Wien, Austria, 34217@uref{http://epub.wu.ac.at/english/}. 34218 34219@anchor{bib:DLa86} 34220@item [DLa86] 34221@sc{L. Devroye} (1986). 34222@i{Non-Uniform Random Variate Generation}, 34223Springer Verlag, New York. 34224 34225@anchor{bib:GWa92} 34226@item [GWa92] 34227@sc{W.R. Gilks and P. Wild} (1992). 34228@i{Adaptive rejection sampling for Gibbs sampling}, 34229Applied Statistics 41, pp. 337-348. 34230 34231@anchor{bib:HWa95} 34232@item [HWa95] 34233@sc{W. H@"ormann} (1995). 34234@i{A rejection technique for sampling from T-concave distributions}, 34235ACM Trans. Math. Software 21(2), pp. 182-193. 34236 34237@anchor{bib:HDa96} 34238@item [HDa96] 34239@sc{W. H@"ormann and G. Derflinger} (1996). 34240@i{Rejection-inversion to generate variates from monotone discrete distributions}, 34241ACM TOMACS 6(3), 169-184. 34242 34243@anchor{bib:HLa00} 34244@item [HLa00] 34245@sc{W. H@"ormann and J. Leydold} (2000). 34246@i{Automatic random variate generation for simulation input.} 34247In: J.A. Joines, R. Barton, P. Fishwick, K. Kang (eds.), 34248Proceedings of the 2000 Winter Simulation Conference, pp. 675-682. 34249 34250@anchor{bib:HLa03} 34251@item [HLa03] 34252@sc{W. H@"ormann and J. Leydold} (2003). 34253@i{Continuous Random Variate Generation by Fast Numerical Inversion}, 34254ACM TOMACS 13(4), 347-362. 34255 34256@anchor{bib:HLDa07} 34257@item [HLDa07] 34258@sc{W. H@"ormann, J. Leydold, and G. Derflinger} (2007). 34259@i{Automatic Random Variate Generation for Unbounded Densities}, 34260ACM Trans. Model. Comput. Simul. 17(4), pp.18. 34261 34262@anchor{bib:KLPa05} 34263@item [KLPa05] 34264@sc{R. Karawatzki, J. Leydold, and K. P@"otzelberger} (2005). 34265@i{Automatic Markov chain Monte Carlo procedures for sampling from multivariate distributions}, 34266Research Report Series of the Department of Statistics and Mathematics 27, 34267WU Wien, Augasse 2--6, A-1090 Wien, Austria, 34268@uref{http://epub.wu.ac.at/english/}. 34269 34270@anchor{bib:LJa98} 34271@item [LJa98] 34272@sc{J. Leydold} (1998). 34273@i{A Rejection Technique for Sampling from Log-Concave Multivariate Distributions}, 34274ACM TOMACS 8(3), pp. 254-280. 34275 34276@anchor{bib:LJa00} 34277@item [LJa00] 34278@sc{J. Leydold} (2000). 34279@i{Automatic Sampling with the Ratio-of-Uniforms Method}, 34280ACM Trans. Math. Software 26(1), pp. 78-98. 34281 34282@anchor{bib:LJa01} 34283@item [LJa01] 34284@sc{J. Leydold} (2001). 34285@i{A simple universal generator for continuous and discrete 34286univariate T-concave distributions}, 34287ACM Trans. Math. Software 27(1), pp. 66-82. 34288 34289@anchor{bib:LJa02} 34290@item [LJa02] 34291@sc{J. Leydold} (2003). 34292@i{Short universal generators via generalized ratio-of-uniforms method}, 34293Math. Comp. 72(243), pp. 1453-1471. 34294 34295@anchor{bib:WGS91} 34296@item [WGS91] 34297@sc{J.C. Wakefield, A.E. Gelfand, and A.F.M. Smith} (1992). 34298@i{Efficient generation of random variates via the ratio-of-uniforms method}, 34299Statist. Comput. 1(2), pp. 129-133. 34300 34301@anchor{bib:WAa77} 34302@item [WAa77] 34303@sc{A.J. Walker} (1977). 34304@i{An efficient method for generating discrete random variables with general distributions}, 34305ACM Trans. Math. Software 3, pp. 253-256. 34306 34307@end table 34308 34309@c ------------------------------------------------------- 34310 34311@subheading Special Generators 34312 34313@table @t 34314 34315@anchor{bib:ADa74} 34316@item [ADa74] 34317@sc{J.H. Ahrens, U. Dieter} (1974). 34318@i{Computer methods for sampling from gamma, beta, Poisson 34319and binomial distributions}, 34320Computing 12, 223-246. 34321 34322@anchor{bib:ADa82} 34323@item [ADa82] 34324@sc{J.H. Ahrens, U. Dieter} (1982). 34325@i{Generating gamma variates by a modified rejection technique}, 34326Communications of the ACM 25, 47-54. 34327 34328@anchor{bib:ADb82} 34329@item [ADb82] 34330@sc{J.H. Ahrens, U. Dieter} (1982). 34331@i{Computer generation of Poisson deviates from modified normal distributions}, 34332ACM Trans. Math. Software 8, 163-179. 34333 34334@anchor{bib:BMa58} 34335@item [BMa58] 34336@sc{G.E.P. Box and M.E. Muller} (1958). 34337@i{A note on the generation of random normal deviates}, 34338Annals Math. Statist. 29, 610-611. 34339 34340@anchor{bib:CHa77} 34341@item [CHa77] 34342@sc{R.C.H. Cheng} (1977). 34343@i{The Generation of Gamma Variables with Non-Integral Shape Parameter}, 34344Appl. Statist. 26(1), 71-75. 34345 34346@anchor{bib:Dag89} 34347@item [Dag89] 34348@sc{J.S. Dagpunar} (1989). 34349@i{An Easily Implemented Generalised Inverse Gaussian Generator}, 34350Commun. Statist. Simul. 18(2), 703-710. 34351 34352@anchor{bib:HDa90} 34353@item [HDa90] 34354@sc{W. H@"ormann and G. Derflinger} (1990). 34355@i{The ACR Method for generating normal random variables}, 34356OR Spektrum 12, 181-185. 34357 34358@anchor{bib:KAa81} 34359@item [KAa81] 34360@sc{A.W. Kemp} (1981). 34361@i{Efficient generation of logarithmically distributed 34362pseudo-random variables}, 34363Appl. Statist. 30, 249-253. 34364 34365@anchor{bib:KRa76} 34366@item [KRa76] 34367@sc{A.J. Kinderman and J.G. Ramage} (1976). 34368@i{Computer Generation of Normal Random Variables}, 34369J. Am. Stat. Assoc. 71(356), 893 - 898. 34370 34371@anchor{bib:MJa87} 34372@item [MJa87] 34373@sc{J.F. Monahan} (1987). 34374@i{An algorithm for generating chi random variables}, 34375ACM Trans. Math. Software 13, 168-172. 34376 34377@anchor{bib:MGa62} 34378@item [MGa62] 34379@sc{G. Marsaglia} (1962). 34380@i{Improving the Polar Method for Generating a Pair of Random Variables}, 34381Boeing Sci. Res. Lab., Seattle, Washington. 34382 34383@anchor{bib:MOa84} 34384@item [MOa84] 34385@sc{G. Marsaglia and I. Olkin} (1984). 34386@i{Generating Correlation Matrices}, 34387SIAM J. Sci. Stat. Comput 5, 470-475. 34388 34389@anchor{bib:STa89} 34390@item [STa89] 34391@sc{E. Stadlober} (1989). 34392@i{Sampling from Poisson, binomial and hypergeometric distributions: 34393ratio of uniforms as a simple and fast alternative}, 34394Bericht 303, Math. Stat. Sektion, 34395Forschungsgesellschaft Joanneum, Graz. 34396 34397@anchor{bib:ZHa94} 34398@item [ZHa94] 34399@sc{H. Zechner} (1994). 34400@i{Efficient sampling from continuous and discrete unimodal distributions}, 34401Pd.D. Thesis, 156 pp., Technical University Graz, Austria. 34402 34403@end table 34404 34405@c ------------------------------------------------------- 34406 34407@subheading Other references 34408 34409@table @t 34410 34411@anchor{bib:CPa76} 34412@item [CPa76] 34413@sc{R. Cranley and T.N.L. Patterson} (1976). 34414@i{Randomization of number theoretic methods for multiple integration}, 34415SIAM J. Num. Anal., Vol. 13, pp. 904-914. 34416 34417@anchor{bib:HJa61} 34418@item [HJa61] 34419@sc{R. Hooke and T.A. Jeeves} (1961). 34420@i{Direct Search Solution of Numerical and Statistical Problems}, 34421Journal of the ACM, Vol. 8, April 1961, pp. 212-229. 34422 34423@end table 34424 34425@c ------------------------------------------------------- 34426 34427 34428 34429@c 34430@c end of references.dh 34431@c ------------------------------------- 34432@c ------------------------------------- 34433@c index.dh 34434@c 34435 34436@node FIndex 34437@appendix Function Index 34438 34439 34440@printindex fn 34441 34442 34443 34444@c 34445@c end of index.dh 34446@c ------------------------------------- 34447