1 /***************************************************************************** 2 * * 3 * UNURAN -- Universal Non-Uniform Random number generator * 4 * * 5 ***************************************************************************** 6 * * 7 * FILE: dsrou.h * 8 * * 9 * PURPOSE: * 10 * function prototypes for method DSROU * 11 * (Discrete, Simple universal generator, Ratio-Of-Uniforms method) * 12 * * 13 * USAGE: * 14 * only included in unuran.h * 15 * * 16 ***************************************************************************** 17 * * 18 * Copyright (c) 2000-2006 Wolfgang Hoermann and Josef Leydold * 19 * Department of Statistics and Mathematics, WU Wien, Austria * 20 * * 21 * This program is free software; you can redistribute it and/or modify * 22 * it under the terms of the GNU General Public License as published by * 23 * the Free Software Foundation; either version 2 of the License, or * 24 * (at your option) any later version. * 25 * * 26 * This program is distributed in the hope that it will be useful, * 27 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 28 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 29 * GNU General Public License for more details. * 30 * * 31 * You should have received a copy of the GNU General Public License * 32 * along with this program; if not, write to the * 33 * Free Software Foundation, Inc., * 34 * 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA * 35 * * 36 *****************************************************************************/ 37 38 /* 39 =METHOD DSROU Discrete Simple Ratio-Of-Uniforms method 40 41 =UP Methods_for_DISCR 42 43 =REQUIRED T-concave PMF, mode, sum over PMF 44 45 =SPEED Set-up: fast, Sampling: slow 46 47 =REINIT supported 48 49 =REF [LJa01] [HLD04: Sect.10.3.2, Alg.10.6] 50 51 =DESCRIPTION 52 DSROU is based on the ratio-of-uniforms method 53 (@pxref{Ratio-of-Uniforms}) but uses universal 54 inequalities for constructing a (universal) bounding rectangle. 55 It works for all @i{T}-concave distributions with 56 @unurmath{T(x) = -1/\sqrt{x}}. 57 58 The method requires the PMF, the (exact) location of the mode 59 and the sum over the given PDF. The rejection constant is 4 for 60 all @i{T}-concave distributions. Optionally the CDF at the mode 61 can be given to increase the performance of the algorithm. Then 62 the rejection constant is reduced to 2. 63 64 =HOWTOUSE 65 The method works for @i{T}-concave discrete distributions with 66 given PMF. The sum over of the PMF or an upper bound of this sum 67 must be known. 68 69 Optionally the CDF at the mode can be given to increase the 70 performance using unur_dsrou_set_cdfatmode(). 71 However, this @strong{must not} be called if the sum over the 72 PMF is replaced by an upper bound. 73 74 It is possible to change the parameters and the domain of the chosen 75 distribution and run unur_reinit() to reinitialize the generator object. 76 77 If any of mode, CDF at mode, or the sum over the PMF has been 78 changed, then unur_reinit() must be executed. 79 (Otherwise the generator produces garbage). 80 81 There exists a test mode that verifies whether the conditions 82 for the method are satisfied or not while sampling. It can be 83 switched on or off by calling unur_dsrou_set_verify() and 84 unur_dsrou_chg_verify(), respectively. 85 Notice however that sampling is (a little bit) slower then. 86 87 =END 88 */ 89 90 /*---------------------------------------------------------------------------*/ 91 /* Routines for user interface */ 92 93 /* =ROUTINES */ 94 95 UNUR_PAR *unur_dsrou_new( const UNUR_DISTR *distribution ); 96 /* 97 Get default parameters for generator. 98 */ 99 100 /*...........................................................................*/ 101 102 int unur_dsrou_set_cdfatmode( UNUR_PAR *parameters, double Fmode ); 103 /* 104 Set CDF at mode. 105 When set, the performance of the algorithm is increased by factor 2. 106 However, when the parameters of the distribution are changed 107 unur_dsrou_chg_cdfatmode() has to be used to update this value. 108 Notice that the algorithm detects a mode at the left boundary of 109 the domain automatically and it is not necessary to use this call 110 for a monotonically decreasing PMF. 111 112 Default: not set. 113 */ 114 115 int unur_dsrou_set_verify( UNUR_PAR *parameters, int verify ); 116 /* */ 117 118 int unur_dsrou_chg_verify( UNUR_GEN *generator, int verify ); 119 /* 120 Turn verifying of algorithm while sampling on/off. 121 If the condition squeeze(@i{x}) <= PMF(@i{x}) <= hat(@i{x}) is 122 violated for some @i{x} then @code{unur_errno} is set to 123 @code{UNUR_ERR_GEN_CONDITION}. However notice that this might 124 happen due to round-off errors for a few values of 125 @i{x} (less than 1%). 126 127 Default is FALSE. 128 */ 129 130 /*...........................................................................*/ 131 132 int unur_dsrou_chg_cdfatmode( UNUR_GEN *generator, double Fmode ); 133 /* 134 Change CDF at mode of distribution. 135 unur_reinit() must be executed before sampling from the 136 generator again. 137 */ 138 139 /* =END */ 140 /*---------------------------------------------------------------------------*/ 141