BRL-CAD
msr.h
Go to the documentation of this file.
1 /* M S R . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 /*----------------------------------------------------------------------*/
22 /* @file msr.h */
23 /** @addtogroup msr */
24 /** @{ */
25 
26 /** @brief
27  * Minimal Standard RANdom number generator
28  *
29  * @par From:
30  * Stephen K. Park and Keith W. Miller
31  * @n "Random number generators: good ones are hard to find"
32  * @n CACM vol 31 no 10, Oct 88
33  *
34  */
35 
36 #ifndef BN_MSR_H
37 #define BN_MSR_H
38 
39 #include "common.h"
40 #include "bn/defines.h"
41 #include "bu/magic.h"
42 
44 
45 /*
46  * Define data structures and constants for the "MSR" random number
47  * package.
48  *
49  * Also define a set of macros to access the random number tables and
50  * to limit the area/volume that a set of random numbers inhabit.
51  */
52 
53 struct bn_unif {
54  uint32_t magic;
55  long msr_seed;
57  double *msr_doubles;
59  long *msr_longs;
60 };
61 
62 #define BN_CK_UNIF(_p) BU_CKMAG(_p, BN_UNIF_MAGIC, "bn_unif")
63 #define BN_CK_GAUSS(_p) BU_CKMAG(_p, BN_GAUSS_MAGIC, "bn_gauss")
64 
65 
66 /**
67  * NOTE!!! The order of msr_gauss and msr_unif MUST match in the first
68  * three entries as msr_gauss is passed as a msr_unif in
69  * msr_gauss_fill.
70  */
71 struct bn_gauss {
72  uint32_t magic;
77  double *msr_gausses;
78 };
79 
80 
81 /* bn_unif_init Initialize a random number structure.
82  *
83  * @par Entry
84  * setseed seed to use
85  * method method to use to generate numbers;
86  *
87  * @par Exit
88  * returns a pointer to a bn_unif structure.
89  * returns 0 on error.
90  *
91  * @par Uses
92  * None.
93  *
94  * @par Calls
95  * bu_malloc
96  *
97  * @par Method @code
98  * malloc up a structure with pointers to the numbers
99  * get space for the integer table.
100  * get space for the floating table.
101  * set pointer counters
102  * set seed if one was given and setseed != 1
103  @endcode
104  *
105  */
106 BN_EXPORT extern struct bn_unif *bn_unif_init(long setseed,
107  int method);
108 
109 /*
110  * bn_unif_free free random number table
111  *
112  */
113 BN_EXPORT extern void bn_unif_free(struct bn_unif *p);
114 
115 /* bn_unif_long_fill fill a random number table.
116  *
117  * Use the msrad algorithm to fill a random number table
118  * with values from 1 to 2^31-1. These numbers can (and are) extracted from
119  * the random number table via high speed macros and bn_unif_long_fill called
120  * when the table is exhausted.
121  *
122  * @par Entry
123  * p pointer to a bn_unif structure.
124  *
125  * @par Exit
126  * if (!p) returns 1 else returns a value between 1 and 2^31-1
127  *
128  * @par Calls
129  * None. msran is inlined for speed reasons.
130  *
131  * @par Uses
132  * None.
133  *
134  * @par Method @code
135  * if (!p) return 1;
136  * if p->msr_longs != NULL
137  * msr_longs is reloaded with random numbers;
138  * msr_long_ptr is set to BN_MSR_MAXTBL
139  * endif
140  * msr_seed is updated.
141  @endcode
142 */
143 BN_EXPORT extern long bn_unif_long_fill(struct bn_unif *p);
144 
145 /* bn_unif_double_fill fill a random number table.
146  *
147  * Use the msrad algorithm to fill a random number table
148  * with values from -0.5 to 0.5. These numbers can (and are) extracted from
149  * the random number table via high speed macros and bn_unif_double_fill
150  * called when the table is exhausted.
151  *
152  * @par Entry
153  * p pointer to a bn_unif structure.
154  *
155  * @par Exit
156  * if (!p) returns 0.0 else returns a value between -0.5 and 0.5
157  *
158  * @par Calls
159  * None. msran is inlined for speed reasons.
160  *
161  * @par Uses
162  * None.
163  *
164  * @par Method @code
165  * if (!p) return (0.0)
166  * if p->msr_longs != NULL
167  * msr_longs is reloaded with random numbers;
168  * msr_long_ptr is set to BN_MSR_MAXTBL
169  * endif
170  * msr_seed is updated.
171  @endcode
172 */
173 BN_EXPORT extern double bn_unif_double_fill(struct bn_unif *p);
174 
175 /* bn_gauss_init Initialize a random number struct for gaussian
176  * numbers.
177  *
178  * @par Entry
179  * setseed Seed to use.
180  * method method to use to generate numbers (not used)
181  *
182  * @par Exit
183  * Returns a pointer toa bn_msr_gauss structure.
184  * returns 0 on error.
185  *
186  * @par Calls
187  * bu_malloc
188  *
189  * @par Uses
190  * None.
191  *
192  * @par Method @code
193  * malloc up a structure
194  * get table space
195  * set seed and pointer.
196  * if setseed != 0 then seed = setseed
197  @endcode
198 */
199 BN_EXPORT extern struct bn_gauss *bn_gauss_init(long setseed,
200  int method);
201 
202 /*
203  * bn_gauss_free free random number table
204  *
205  */
206 BN_EXPORT extern void bn_gauss_free(struct bn_gauss *p);
207 
208 /* bn_gauss_fill fill a random number table.
209  *
210  * Use the msrad algorithm to fill a random number table.
211  * hese numbers can (and are) extracted from
212  * the random number table via high speed macros and bn_msr_gauss_fill
213  * called when the table is exhausted.
214  *
215  * @par Entry
216  * p pointer to a bn_msr_gauss structure.
217  *
218  * @par Exit
219  * if (!p) returns 0.0 else returns a value with a mean of 0 and
220  * a variance of 1.0.
221  *
222  * @par Calls
223  * BN_UNIF_CIRCLE to get to uniform random number whose radius is
224  * <= 1.0. I.e. sqrt(v1*v1 + v2*v2) <= 1.0
225  * BN_UNIF_CIRCLE is a macro which can call bn_unif_double_fill.
226  *
227  * @par Uses
228  * None.
229  *
230  * @par Method @code
231  * if (!p) return (0.0)
232  * if p->msr_longs != NULL
233  * msr_longs is reloaded with random numbers;
234  * msr_long_ptr is set to BN_MSR_MAXTBL
235  * endif
236  * msr_seed is updated.
237  @endcode
238 */
239 BN_EXPORT extern double bn_gauss_fill(struct bn_gauss *p);
240 
241 #define BN_UNIF_LONG(_p) \
242  (((_p)->msr_long_ptr) ? \
243  (_p)->msr_longs[--(_p)->msr_long_ptr] : \
244  bn_unif_long_fill(_p))
245 #define BN_UNIF_DOUBLE(_p) \
246  (((_p)->msr_double_ptr) ? \
247  (_p)->msr_doubles[--(_p)->msr_double_ptr] : \
248  bn_unif_double_fill(_p))
249 
250 #define BN_UNIF_CIRCLE(_p, _x, _y, _r) { \
251  do { \
252  (_x) = 2.0*BN_UNIF_DOUBLE((_p)); \
253  (_y) = 2.0*BN_UNIF_DOUBLE((_p)); \
254  (_r) = (_x)*(_x)+(_y)*(_y); \
255  } while ((_r) >= 1.0); }
256 
257 #define BN_UNIF_SPHERE(_p, _x, _y, _z, _r) { \
258  do { \
259  (_x) = 2.0*BN_UNIF_DOUBLE(_p); \
260  (_y) = 2.0*BN_UNIF_DOUBLE(_p); \
261  (_z) = 2.0*BN_UNIF_DOUBLE(_p); \
262  (_r) = (_x)*(_x)+(_y)*(_y)+(_z)*(_z);\
263  } while ((_r) >= 1.0) }
264 
265 #define BN_GAUSS_DOUBLE(_p) \
266  (((_p)->msr_gauss_ptr) ? \
267  (_p)->msr_gausses[--(_p)->msr_gauss_ptr] : \
268  bn_gauss_fill(_p))
269 
271 
272 #endif /* BN_MSR_H */
273 /** @} */
274 /*
275  * Local Variables:
276  * mode: C
277  * tab-width: 8
278  * indent-tabs-mode: t
279  * c-file-style: "stroustrup"
280  * End:
281  * ex: shiftwidth=4 tabstop=8
282  */
Minimal Standard RANdom number generator.
Definition: msr.h:53
int msr_long_ptr
Definition: msr.h:58
int msr_double_ptr
Definition: msr.h:56
Header file for the BRL-CAD common definitions.
void bn_unif_free(struct bn_unif *p)
Definition: msr.c:155
long bn_unif_long_fill(struct bn_unif *p)
Definition: msr.c:78
void bn_gauss_free(struct bn_gauss *p)
Definition: msr.c:220
Definition: msr.h:71
double * msr_gauss_doubles
Definition: msr.h:75
long msr_seed
Definition: msr.h:55
int msr_gauss_ptr
Definition: msr.h:76
struct bn_gauss * bn_gauss_init(long setseed, int method)
double * msr_gausses
Definition: msr.h:77
#define __BEGIN_DECLS
Definition: common.h:73
double * msr_doubles
Definition: msr.h:57
int msr_gauss_dbl_ptr
Definition: msr.h:74
uint32_t magic
Definition: msr.h:72
uint32_t magic
Definition: msr.h:54
long * msr_longs
Definition: msr.h:59
double bn_unif_double_fill(struct bn_unif *p)
Definition: msr.c:115
double bn_gauss_fill(struct bn_gauss *p)
Definition: msr.c:190
#define __END_DECLS
Definition: common.h:74
struct bn_unif * bn_unif_init(long setseed, int method)
long msr_gauss_seed
Definition: msr.h:73