1 /***************************************************************************** 2 * * 3 * UNURAN -- Universal Non-Uniform Random number generator * 4 * * 5 ***************************************************************************** 6 * * 7 * FILE: dext.h * 8 * * 9 * PURPOSE: * 10 * function prototypes for method DEXT * 11 * (wrapper for Continuous EXTernal generators) * 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 DEXT wrapper for Discrete EXTernal generators 40 41 =UP Methods_for_DISCR 42 43 =REQUIRED routine for sampling discrete random variates 44 45 =SPEED depends on external generator 46 47 =REINIT supported 48 49 =DESCRIPTION 50 Method DEXT is a wrapper for external generators for discrete 51 univariate distributions. It allows the usage of external 52 random variate generators within the UNU.RAN framework. 53 54 =HOWTOUSE 55 The following steps are required to use some external generator 56 within the UNU.RAN framework (some of these are optional): 57 58 @enumerate 59 @item 60 Make an empty generator object using a unur_dext_new() call. 61 The argument @var{distribution} is optional and can be replaced 62 by NULL. However, it is required if you want to pass 63 parameters of the generated distribution to the external 64 generator or for running some validation tests provided by 65 UNU.RAN. 66 67 @item 68 Create an initialization routine of type 69 @code{int (*init)(UNUR_GEN *gen)} and plug it into the generator 70 object using the unur_dext_set_init() call. Notice that the 71 @var{init} routine must return @code{UNUR_SUCCESS} when it has 72 been executed successfully and @code{UNUR_FAILURE} otherwise. 73 It is possible to get the size of and the pointer to the array 74 of parameters of the underlying distribution object by the 75 respective calls unur_dext_get_ndistrparams() and 76 unur_dext_get_distrparams(). 77 Parameters for the external generator that are computed in the 78 @var{init} routine can be stored in a single array or structure 79 which is available by the unur_dext_get_params() call. 80 81 Using an @var{init} routine is optional and can be omitted. 82 83 @item 84 Create a sampling routine of type 85 @code{int (*sample)(UNUR_GEN *gen)} and plug it into the 86 generator object using the unur_dext_set_sample() call. 87 88 Uniform random numbers are provided by the unur_sample_urng() 89 call. Do not use your own implementation of a uniform random 90 number generator directly. If you want to use your own random 91 number generator we recommend to use the UNU.RAN interface (see 92 @pxref{URNG,,Using uniform random number generators}). 93 94 The array or structure that contains parameters for the external 95 generator that are computed in the @var{init} routine are 96 available using the unur_dext_get_params() call. 97 98 Using a @var{sample} routine is of course obligatory. 99 @end enumerate 100 101 It is possible to change the parameters and the domain of the 102 chosen distribution and run unur_reinit() to reinitialize the 103 generator object. The @var{init} routine is then called again. 104 105 Here is a short example that demonstrates the application of 106 this method by means of the geometric distribution: 107 108 @smallexample 109 @include ref_example_dext.texi 110 @end smallexample 111 112 =END 113 */ 114 115 /*---------------------------------------------------------------------------*/ 116 /* Routines for user interface */ 117 118 /* =ROUTINES */ 119 120 UNUR_PAR *unur_dext_new( const UNUR_DISTR *distribution ); 121 /* 122 Get default parameters for new generator. 123 */ 124 125 /*...........................................................................*/ 126 127 int unur_dext_set_init( UNUR_PAR *parameters, int (*init)(UNUR_GEN *gen) ); 128 /* 129 Set initialization routine for external generator. Inside the 130 131 @emph{Important:} The routine @var{init} must return 132 @code{UNUR_SUCCESS} when the generator was initialized successfully 133 and @code{UNUR_FAILURE} otherwise. 134 135 Parameters that are computed in the @var{init} routine can be 136 stored in an array or structure that is avaiable by means of the 137 unur_dext_get_params() call. Parameters of the underlying 138 distribution object can be obtained by the 139 unur_dext_get_distrparams() call. 140 */ 141 142 int unur_dext_set_sample( UNUR_PAR *parameters, int (*sample)(UNUR_GEN *gen) ); 143 /* 144 Set sampling routine for external generator. 145 146 @emph{Important:} 147 Use @code{unur_sample_urng(gen)} to get a uniform random number. 148 The pointer to the array or structure that contains the parameters 149 that are precomputed in the @var{init} routine are available by 150 @code{unur_dext_get_params(gen,0)}. 151 Additionally one can use the unur_dext_get_distrparams() call. 152 */ 153 154 void *unur_dext_get_params( UNUR_GEN *generator, size_t size ); 155 /* 156 Get pointer to memory block for storing parameters of external 157 generator. A memory block of size @var{size} is automatically (re-) 158 allocated if necessary and the pointer to this block is stored in 159 the @var{generator} object. If one only needs the pointer to this 160 memory block set @var{size} to @code{0}. 161 162 Notice, that @var{size} is the size of the memory block and not the 163 length of an array. 164 165 @emph{Important:} This rountine should only be used in the 166 initialization and sampling routine of the external generator. 167 */ 168 169 double *unur_dext_get_distrparams( UNUR_GEN *generator ); 170 /* */ 171 172 int unur_dext_get_ndistrparams( UNUR_GEN *generator ); 173 /* 174 Get size of and pointer to array of parameters of underlying 175 distribution in @var{generator} object. 176 177 @emph{Important:} These rountines should only be used in the 178 initialization and sampling routine of the external generator. 179 */ 180 181 /*...........................................................................*/ 182 183 184 /* =END */ 185 /*---------------------------------------------------------------------------*/ 186