BRL-CAD
Loading...
Searching...
No Matches
numgen.h
Go to the documentation of this file.
1
/* N U M G E N . H
2
* BRL-CAD
3
*
4
* Copyright (c) 2016-2025 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
/** @addtogroup bn_rand
23
*
24
* @brief
25
* Routines for generating series of pseudo-random or quasi-random numbers.
26
*
27
* @code
28
* @endcode
29
*/
30
/** @{ */
31
/** @file numgen.h */
32
33
#ifndef BN_NUMGEN_H
34
#define BN_NUMGEN_H
35
36
#include "
common.h
"
37
38
#include "
vmath.h
"
39
40
#include "
bn/defines.h
"
41
42
__BEGIN_DECLS
43
/* Most of the following are API design possibilities only - not yet active */
44
/**
45
* The following container holds all state associated with a particular
46
* number generator. The details of that state are specific to the
47
* type of selected generator and are not public, but the container allows
48
* libbn to avoid using globals to maintain state - instead, each "generator"
49
* instance has its own state.
50
*/
51
typedef
struct
bn_num_s
*
bn_numgen
;
52
53
#if 0
54
/**
55
* The available number generators in libbn.
56
*/
57
typedef
enum
{
58
BN_NUMGEN_PRAND_TABLE
= 0,
59
BN_NUMGEN_PRAND_MT1337
,
60
BN_NUMGEN_QRAND_SOBOL
,
61
BN_NUMGEN_QRAND_SCRAMBLED_SOBOL
,
62
BN_NUMGEN_QRAND_HALTON
,
63
BN_NUMGEN_NRAND_BOX_MULLER
,
64
BN_NUMGEN_NRAND_RATIO_OF_UNIFORMS
,
65
BN_NUMGEN_NULL
66
}
bn_numgen_t
;
67
68
/**
69
* Create an instance of the number generator with the type
70
* and seed specified by the user. By default, a generator will
71
* return numbers between 0 and 1 - to adjust the range, use
72
* bn_numgen_setrange */
73
BN_EXPORT
bn_numgen
bn_numgen_create
(
bn_numgen_t
type,
int
dim,
double
seed
);
74
75
/** Returns the type of a bn_numgen instance */
76
BN_EXPORT
bn_numgen_t
bn_numgen_type
(
bn_numgen
n
);
77
78
/**
79
* Set the range of the numbers to be returned. Return 1 if range
80
* is valid for the generator, and zero if it is unsupported. */
81
BN_EXPORT
int
bn_numgen_setrange
(
bn_numgen
ngen
,
double
lb
,
double
ub
);
82
83
/**
84
* Some generators only support a finite number of unique returns before
85
* repeating. By default, bn_numgen generators are periodic - they will start
86
* over at the beginning.
87
*
88
* If this function is called with flag == 0, the generator will refuse to
89
* repeat itself and not assign any numbers once it reaches its periodic limit.
90
* If flag is set to 1, it will restore a generator to its default behavior.
91
*
92
* If passed -1 in the flag var, the return code will report the existing
93
* periodic flag state but will not change it in the generator.
94
*/
95
BN_EXPORT
int
bn_numgen_periodic
(
bn_numgen
ngen
,
int
flag
);
96
97
/**
98
* Destroy the specified bn_numgen instance */
99
BN_EXPORT
void
bn_numgen_destroy
(
bn_numgen
n
);
100
101
/**
102
* Get the next cnt numbers in the generator's sequence. See the documentation
103
* for each individual generator for the particulars of what output will be
104
* returned in the array. The user is responsible for allocating an array
105
* large enough to hold the requested output.
106
*
107
* When in non-periodic mode, an exhausted generator will report zero numbers
108
* assigned to output arrays and will not alter the array contents.
109
*
110
* Return codes: >= 0 number of numbers assigned.
111
* < 0 error.
112
*/
113
BN_EXPORT
int
bn_numgen_next_ints
(
int
*l,
size_t
cnt
,
bn_numgen
ngen
);
114
BN_EXPORT
int
bn_numgen_next_ulongs
(
unsigned
long
*l,
size_t
cnt
,
bn_numgen
ngen
);
115
BN_EXPORT
int
bn_numgen_next_fastf_t
(
fastf_t
*l,
size_t
cnt
,
bn_numgen
ngen
);
116
BN_EXPORT
int
bn_numgen_next_doubles
(
double
*l,
size_t
cnt
,
bn_numgen
ngen
);
117
#endif
118
119
/**
120
* @brief
121
* Generate points on a unit sphere per Marsaglia (1972):
122
* https://projecteuclid.org/euclid.aoms/1177692644
123
*
124
* The user is responsible for selecting the numerical generator used to
125
* supply pseudo or quasi-random numbers to bg_sph_sample - different
126
* types of inputs may be needed depending on the application.
127
*/
128
BN_EXPORT
extern
void
bn_sph_pnts
(
point_t
*
pnts
,
size_t
cnt
,
bn_numgen
n
);
129
130
131
132
__END_DECLS
133
134
#endif
/* BN_RAND_H */
135
/** @} */
136
/*
137
* Local Variables:
138
* mode: C
139
* tab-width: 8
140
* indent-tabs-mode: t
141
* c-file-style: "stroustrup"
142
* End:
143
* ex: shiftwidth=4 tabstop=8
144
*/
defines.h
dvec
Definition
dvec.h:74
common.h
Header file for the BRL-CAD common definitions.
bn_numgen
struct bn_num_s * bn_numgen
Definition
numgen.h:51
bn_sph_pnts
void bn_sph_pnts(point_t *pnts, size_t cnt, bn_numgen n)
Generate points on a unit sphere per Marsaglia (1972): https://projecteuclid.org/euclid....
flag
void float float int int * flag
Definition
tig.h:129
n
void float float int * n
Definition
tig.h:74
fastf_t
double fastf_t
fastest 64-bit (or larger) floating point type
Definition
vmath.h:334
point_t
fastf_t point_t[ELEMENTS_PER_POINT]
3-tuple point
Definition
vmath.h:355
vmath.h
fundamental vector, matrix, quaternion math macros
include
bn
numgen.h
Generated on Sat Jul 5 2025 01:23:50 for BRL-CAD by
1.9.8