1 /*****************************************************************************
2  *                                                                           *
3  *          UNURAN -- Universal Non-Uniform Random number generator          *
4  *                                                                           *
5  *****************************************************************************
6  *                                                                           *
7  *   FILE: urng_fvoid.h                                                      *
8  *                                                                           *
9  *   PURPOSE:                                                                *
10  *     Function prototypes for meta uniform random number generator to       *
11  *     combine point set generator with random shifts.                       *
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 #ifndef URNG_RANDOMSHIFT_H_SEEN
40 #define URNG_RANDOMSHIFT_H_SEEN
41 /*---------------------------------------------------------------------------*/
42 
43 /*
44    =NODE  URNG-RANDOMSHIFT  Combine point set generator with random shifts
45 
46    =UP URNG [90]
47 
48    =DESCRIPTION
49       Generators of type RANDOMSHIFT combine a point set generator with
50       generators to apply random shifts as proposed in
51       @unurbibref{CPa76}:
52 
53       @enumerate
54       @item
55       Sample and store a random vector S.
56       @item
57       Run a QMC simulation where S is added to each point of the
58       generated quasi-random point (mod 1).
59       @item
60       Repeat steps 1 and 2.
61       @end enumerate
62 
63    =HOWTOUSE
64       Create a URNG object for a point set generator and a URNG object
65       for a generator to create shift vectors at random.
66       The meta URNG object can then be created using
67       unur_urng_randomshift_new().
68       Notice that only pointers to the two underlying URNG generator
69       objects are copied into the newly created meta generator. Thus
70       manipulating the meta URNG also changes the underlying URNGs
71       and vice versa.
72 
73       The following routines are supported for URNG objects of
74       type RANDOMSHIFT:
75 
76       @itemize @minus
77       @item unur_urng_sample()
78       @item unur_urng_sample_array()
79       @item unur_urng_reset()
80       @item unur_urng_sync()
81       @item unur_urng_randomshift_nextshift()
82       @item unur_urng_free()
83       @end itemize
84 
85       unur_urng_sync() is used to jump to the first coordinate of
86       the next point generated by the generator.
87 
88       unur_urng_randomshift_nextshift() allows to replace the shift
89       vector by another randomly chosen shift vector.
90 
91       @emph{Important:} unur_urng_sync() is only available if it is
92       if it is implemented for the underlying point set generator.
93 
94       @emph{Important:} unur_urng_reset() is only available if it is
95       available for both underlying generators.
96 
97    =END
98 
99 */
100 
101 /*---------------------------------------------------------------------------*/
102 
103 /* =ROUTINES */
104 
105 /*---------------------------------------------------------------------------*/
106 
107 UNUR_URNG *unur_urng_randomshift_new( UNUR_URNG *qrng, UNUR_URNG *srng, int dim );
108 /*
109    Make object for URNG with randomly shifted point sets.
110    @var{qrng} is a generated that generates point sets of dimension @var{dim}.
111    @var{srng} is a generated that generates random numbers or vectors.
112 
113    @emph{Notice:} Only pointers to the respective objects @var{qrng}
114    and @var{srng} are copied into the created meta generator. Thus
115    manipulating the meta URNG also changes the underlying URNGs
116    and vice versa.
117 */
118 
119 int unur_urng_randomshift_nextshift( UNUR_URNG *urng );
120 /*
121    Get the next (randomly chosen) vector for shifting the points set, and the
122    underlying point generator @var{qrng} is reset.
123 */
124 
125 /*
126    =END
127 */
128 
129 /*---------------------------------------------------------------------------*/
130 #endif  /* URNG_RANDOMSHIFT_H_SEEN */
131 /*---------------------------------------------------------------------------*/
132