]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [template tr1_overview[] |
2 | Many of the special functions included in this library are also a part | |
3 | of the either the [C99] or the [tr1]. Therefore this library | |
4 | includes a thin wrapper header `boost/math/tr1.hpp` that provides | |
5 | compatibility with these two standards. | |
6 | ||
7 | There are various pros and cons to using the library in this way: | |
8 | ||
9 | Pros: | |
10 | ||
11 | * The header to include is lightweight (i.e. fast to compile). | |
12 | * The functions have extern "C" linkage, | |
13 | and so are usable from other languages (not just C and C++). | |
14 | * C99 and C++ TR1 Standard compatibility. | |
15 | ||
16 | Cons: | |
17 | ||
18 | * You will need to compile and link to the external Boost.Math libraries. | |
19 | * Limited to support for the types, `float`, `double` and `long double`. | |
20 | * Error handling is handled via setting ::errno and returning NaN's and | |
21 | infinities: this may be less flexible than an C++ exception based approach. | |
22 | ||
23 | [note The separate libraries are required *only* if you choose to use | |
24 | boost/math/tr1.hpp rather than some other Boost.Math header, the rest | |
25 | of Boost.Math remains header-only.] | |
26 | ||
27 | The separate libraries required in order to use tr1.hpp can be compiled | |
28 | using bjam from within the libs/math/build directory, or from the Boost | |
29 | root directory using the usual Boost-wide install procedure. | |
30 | Alternatively the source files are located in libs/math/src and each have | |
31 | the same name as the function they implement. The various libraries are | |
32 | named as follows: | |
33 | ||
34 | [table | |
35 | [[Name][Type][Functions]] | |
36 | [[boost_math_c99f-<suffix>][float][C99 Functions]] | |
37 | [[boost_math_c99-<suffix>][double][C99 Functions]] | |
38 | [[boost_math_c99l-<suffix>][long double][C99 Functions]] | |
39 | [[boost_math_tr1f-<suffix>][float][TR1 Functions]] | |
40 | [[boost_math_tr1-<suffix>][double][TR1 Functions]] | |
41 | [[boost_math_tr1l-<suffix>][long double][TR1 Functions]] | |
42 | ] | |
43 | ||
44 | Where `<suffix>` encodes the compiler and build options used to | |
45 | build the libraries: for example "libboost_math_tr1-vc80-mt-gd.lib" | |
46 | would be the statically linked TR1 library to use with Visual C++ 8.0, | |
47 | in multithreading debug mode, with the DLL VC++ runtime, where as | |
48 | "boost_math_tr1-vc80-mt.lib" would be import library for the TR1 DLL | |
49 | to be used with Visual C++ 8.0 with the release multithreaded DLL | |
50 | VC++ runtime. | |
51 | Refer to the getting started guide for a | |
52 | [@http://www.boost.org/doc/libs/1_35_0/more/getting_started/windows.html#library-naming | |
53 | full explanation of the `<suffix>` meanings]. | |
54 | ||
55 | [note | |
56 | Visual C++ users will typically have the correct library variant to link | |
57 | against selected for them by boost/math/tr1.hpp based on your compiler | |
58 | settings. | |
59 | ||
60 | Users will need to define BOOST_MATH_TR1_DYN_LINK when building | |
61 | their code if they want to link against the DLL versions of these libraries | |
62 | rather than the static versions. | |
63 | ||
64 | Users can disable auto-linking by defining BOOST_MATH_TR1_NO_LIB when | |
65 | building: this is typically only used when linking against a customised | |
66 | build of the libraries.] | |
67 | ||
68 | [note Linux and Unix users will generally only have one variant of | |
69 | these libraries installed, and can generally just link against | |
70 | -lboost_math_tr1 etc.] | |
71 | ||
72 | [h4 Usage Recomendations] | |
73 | ||
74 | This library now presents the user with a choice: | |
75 | ||
76 | * To include the header only versions of the functions and have | |
77 | an easier time linking, but a longer compile time. | |
78 | * To include the TR1 headers and link against an external library. | |
79 | ||
80 | Which option you choose depends largely on how you prefer to work | |
81 | and how your system is set up. | |
82 | ||
83 | For example a casual user who just needs the acosh function, would | |
84 | probably be better off including `<boost/math/special_functions/acosh.hpp>` | |
85 | and using `boost::math::acosh(x)` in their code. | |
86 | ||
87 | However, for large scale | |
88 | software development where compile times are significant, and where the | |
89 | Boost libraries are already built and installed on the system, then | |
90 | including `<boost/math/tr1.hpp>` and using `boost::math::tr1::acosh(x)` | |
91 | will speed up compile times, reduce object files sizes (since there are | |
92 | no templates being instantiated any more), and also speed up debugging | |
93 | runtimes - since the externally compiled libraries can be | |
94 | compiler optimised, rather than built using full settings - the difference | |
95 | in performance between | |
96 | [link math_toolkit.getting_best | |
97 | release and debug builds can be as much as 20 times], | |
98 | so for complex applications this can be a big win. | |
99 | ||
100 | [h4 Supported C99 Functions] | |
101 | ||
102 | See also the [link math_toolkit.c99 | |
103 | quick reference guide for these functions]. | |
104 | ||
105 | namespace boost{ namespace math{ namespace tr1{ extern "C"{ | |
106 | ||
107 | typedef unspecified float_t; | |
108 | typedef unspecified double_t; | |
109 | ||
110 | double acosh(double x); | |
111 | float acoshf(float x); | |
112 | long double acoshl(long double x); | |
113 | ||
114 | double asinh(double x); | |
115 | float asinhf(float x); | |
116 | long double asinhl(long double x); | |
117 | ||
118 | double atanh(double x); | |
119 | float atanhf(float x); | |
120 | long double atanhl(long double x); | |
121 | ||
122 | double cbrt(double x); | |
123 | float cbrtf(float x); | |
124 | long double cbrtl(long double x); | |
125 | ||
126 | double copysign(double x, double y); | |
127 | float copysignf(float x, float y); | |
128 | long double copysignl(long double x, long double y); | |
129 | ||
130 | double erf(double x); | |
131 | float erff(float x); | |
132 | long double erfl(long double x); | |
133 | ||
134 | double erfc(double x); | |
135 | float erfcf(float x); | |
136 | long double erfcl(long double x); | |
137 | ||
138 | double expm1(double x); | |
139 | float expm1f(float x); | |
140 | long double expm1l(long double x); | |
141 | ||
142 | double fmax(double x, double y); | |
143 | float fmaxf(float x, float y); | |
144 | long double fmaxl(long double x, long double y); | |
145 | ||
146 | double fmin(double x, double y); | |
147 | float fminf(float x, float y); | |
148 | long double fminl(long double x, long double y); | |
149 | ||
150 | double hypot(double x, double y); | |
151 | float hypotf(float x, float y); | |
152 | long double hypotl(long double x, long double y); | |
153 | ||
154 | double lgamma(double x); | |
155 | float lgammaf(float x); | |
156 | long double lgammal(long double x); | |
157 | ||
158 | long long llround(double x); | |
159 | long long llroundf(float x); | |
160 | long long llroundl(long double x); | |
161 | ||
162 | double log1p(double x); | |
163 | float log1pf(float x); | |
164 | long double log1pl(long double x); | |
165 | ||
166 | long lround(double x); | |
167 | long lroundf(float x); | |
168 | long lroundl(long double x); | |
169 | ||
170 | double nextafter(double x, double y); | |
171 | float nextafterf(float x, float y); | |
172 | long double nextafterl(long double x, long double y); | |
173 | ||
174 | double nexttoward(double x, long double y); | |
175 | float nexttowardf(float x, long double y); | |
176 | long double nexttowardl(long double x, long double y); | |
177 | ||
178 | double round(double x); | |
179 | float roundf(float x); | |
180 | long double roundl(long double x); | |
181 | ||
182 | double tgamma(double x); | |
183 | float tgammaf(float x); | |
184 | long double tgammal(long double x); | |
185 | ||
186 | double trunc(double x); | |
187 | float truncf(float x); | |
188 | long double truncl(long double x); | |
189 | ||
190 | }}}} // namespaces | |
191 | ||
192 | [h4 Supported TR1 Functions] | |
193 | ||
194 | See also the [link math_toolkit.main_tr1 | |
195 | quick reference guide for these functions]. | |
196 | ||
197 | namespace boost{ namespace math{ namespace tr1{ extern "C"{ | |
198 | ||
199 | // [5.2.1.1] associated Laguerre polynomials: | |
200 | double assoc_laguerre(unsigned n, unsigned m, double x); | |
201 | float assoc_laguerref(unsigned n, unsigned m, float x); | |
202 | long double assoc_laguerrel(unsigned n, unsigned m, long double x); | |
203 | ||
204 | // [5.2.1.2] associated Legendre functions: | |
205 | double assoc_legendre(unsigned l, unsigned m, double x); | |
206 | float assoc_legendref(unsigned l, unsigned m, float x); | |
207 | long double assoc_legendrel(unsigned l, unsigned m, long double x); | |
208 | ||
209 | // [5.2.1.3] beta function: | |
210 | double beta(double x, double y); | |
211 | float betaf(float x, float y); | |
212 | long double betal(long double x, long double y); | |
213 | ||
214 | // [5.2.1.4] (complete) elliptic integral of the first kind: | |
215 | double comp_ellint_1(double k); | |
216 | float comp_ellint_1f(float k); | |
217 | long double comp_ellint_1l(long double k); | |
218 | ||
219 | // [5.2.1.5] (complete) elliptic integral of the second kind: | |
220 | double comp_ellint_2(double k); | |
221 | float comp_ellint_2f(float k); | |
222 | long double comp_ellint_2l(long double k); | |
223 | ||
224 | // [5.2.1.6] (complete) elliptic integral of the third kind: | |
225 | double comp_ellint_3(double k, double nu); | |
226 | float comp_ellint_3f(float k, float nu); | |
227 | long double comp_ellint_3l(long double k, long double nu); | |
228 | ||
229 | // [5.2.1.8] regular modified cylindrical Bessel functions: | |
230 | double cyl_bessel_i(double nu, double x); | |
231 | float cyl_bessel_if(float nu, float x); | |
232 | long double cyl_bessel_il(long double nu, long double x); | |
233 | ||
234 | // [5.2.1.9] cylindrical Bessel functions (of the first kind): | |
235 | double cyl_bessel_j(double nu, double x); | |
236 | float cyl_bessel_jf(float nu, float x); | |
237 | long double cyl_bessel_jl(long double nu, long double x); | |
238 | ||
239 | // [5.2.1.10] irregular modified cylindrical Bessel functions: | |
240 | double cyl_bessel_k(double nu, double x); | |
241 | float cyl_bessel_kf(float nu, float x); | |
242 | long double cyl_bessel_kl(long double nu, long double x); | |
243 | ||
244 | // [5.2.1.11] cylindrical Neumann functions; | |
245 | // cylindrical Bessel functions (of the second kind): | |
246 | double cyl_neumann(double nu, double x); | |
247 | float cyl_neumannf(float nu, float x); | |
248 | long double cyl_neumannl(long double nu, long double x); | |
249 | ||
250 | // [5.2.1.12] (incomplete) elliptic integral of the first kind: | |
251 | double ellint_1(double k, double phi); | |
252 | float ellint_1f(float k, float phi); | |
253 | long double ellint_1l(long double k, long double phi); | |
254 | ||
255 | // [5.2.1.13] (incomplete) elliptic integral of the second kind: | |
256 | double ellint_2(double k, double phi); | |
257 | float ellint_2f(float k, float phi); | |
258 | long double ellint_2l(long double k, long double phi); | |
259 | ||
260 | // [5.2.1.14] (incomplete) elliptic integral of the third kind: | |
261 | double ellint_3(double k, double nu, double phi); | |
262 | float ellint_3f(float k, float nu, float phi); | |
263 | long double ellint_3l(long double k, long double nu, long double phi); | |
264 | ||
265 | // [5.2.1.15] exponential integral: | |
266 | double expint(double x); | |
267 | float expintf(float x); | |
268 | long double expintl(long double x); | |
269 | ||
270 | // [5.2.1.16] Hermite polynomials: | |
271 | double hermite(unsigned n, double x); | |
272 | float hermitef(unsigned n, float x); | |
273 | long double hermitel(unsigned n, long double x); | |
274 | ||
275 | // [5.2.1.18] Laguerre polynomials: | |
276 | double laguerre(unsigned n, double x); | |
277 | float laguerref(unsigned n, float x); | |
278 | long double laguerrel(unsigned n, long double x); | |
279 | ||
280 | // [5.2.1.19] Legendre polynomials: | |
281 | double legendre(unsigned l, double x); | |
282 | float legendref(unsigned l, float x); | |
283 | long double legendrel(unsigned l, long double x); | |
284 | ||
285 | // [5.2.1.20] Riemann zeta function: | |
286 | double riemann_zeta(double); | |
287 | float riemann_zetaf(float); | |
288 | long double riemann_zetal(long double); | |
289 | ||
290 | // [5.2.1.21] spherical Bessel functions (of the first kind): | |
291 | double sph_bessel(unsigned n, double x); | |
292 | float sph_besself(unsigned n, float x); | |
293 | long double sph_bessell(unsigned n, long double x); | |
294 | ||
295 | // [5.2.1.22] spherical associated Legendre functions: | |
296 | double sph_legendre(unsigned l, unsigned m, double theta); | |
297 | float sph_legendref(unsigned l, unsigned m, float theta); | |
298 | long double sph_legendrel(unsigned l, unsigned m, long double theta); | |
299 | ||
300 | // [5.2.1.23] spherical Neumann functions; | |
301 | // spherical Bessel functions (of the second kind): | |
302 | double sph_neumann(unsigned n, double x); | |
303 | float sph_neumannf(unsigned n, float x); | |
304 | long double sph_neumannl(unsigned n, long double x); | |
305 | ||
306 | }}}} // namespaces | |
307 | ||
308 | In addition sufficient additional overloads of the `double` versions of the | |
309 | above functions are provided, so that calling the function with any mixture | |
310 | of `float`, `double`, `long double`, or /integer/ arguments is supported, with the | |
311 | return type determined by the __arg_promotion_rules. | |
312 | ||
313 | [h4 Currently Unsupported C99 Functions] | |
314 | ||
315 | double exp2(double x); | |
316 | float exp2f(float x); | |
317 | long double exp2l(long double x); | |
318 | ||
319 | double fdim(double x, double y); | |
320 | float fdimf(float x, float y); | |
321 | long double fdiml(long double x, long double y); | |
322 | ||
323 | double fma(double x, double y, double z); | |
324 | float fmaf(float x, float y, float z); | |
325 | long double fmal(long double x, long double y, long double z); | |
326 | ||
327 | int ilogb(double x); | |
328 | int ilogbf(float x); | |
329 | int ilogbl(long double x); | |
330 | ||
331 | long long llrint(double x); | |
332 | long long llrintf(float x); | |
333 | long long llrintl(long double x); | |
334 | ||
335 | double log2(double x); | |
336 | float log2f(float x); | |
337 | long double log2l(long double x); | |
338 | ||
339 | double logb(double x); | |
340 | float logbf(float x); | |
341 | long double logbl(long double x); | |
342 | ||
343 | long lrint(double x); | |
344 | long lrintf(float x); | |
345 | long lrintl(long double x); | |
346 | ||
347 | double nan(const char *str); | |
348 | float nanf(const char *str); | |
349 | long double nanl(const char *str); | |
350 | ||
351 | double nearbyint(double x); | |
352 | float nearbyintf(float x); | |
353 | long double nearbyintl(long double x); | |
354 | ||
355 | double remainder(double x, double y); | |
356 | float remainderf(float x, float y); | |
357 | long double remainderl(long double x, long double y); | |
358 | ||
359 | double remquo(double x, double y, int *pquo); | |
360 | float remquof(float x, float y, int *pquo); | |
361 | long double remquol(long double x, long double y, int *pquo); | |
362 | ||
363 | double rint(double x); | |
364 | float rintf(float x); | |
365 | long double rintl(long double x); | |
366 | ||
367 | double scalbln(double x, long ex); | |
368 | float scalblnf(float x, long ex); | |
369 | long double scalblnl(long double x, long ex); | |
370 | ||
371 | double scalbn(double x, int ex); | |
372 | float scalbnf(float x, int ex); | |
373 | long double scalbnl(long double x, int ex); | |
374 | ||
375 | [h4 Currently Unsupported TR1 Functions] | |
376 | ||
377 | // [5.2.1.7] confluent hypergeometric functions: | |
378 | double conf_hyperg(double a, double c, double x); | |
379 | float conf_hypergf(float a, float c, float x); | |
380 | long double conf_hypergl(long double a, long double c, long double x); | |
381 | ||
382 | // [5.2.1.17] hypergeometric functions: | |
383 | double hyperg(double a, double b, double c, double x); | |
384 | float hypergf(float a, float b, float c, float x); | |
385 | long double hypergl(long double a, long double b, long double c, | |
386 | long double x); | |
387 | ||
388 | ||
389 | ] | |
390 | ||
391 | [/ | |
392 | Copyright 2008 John Maddock and Paul A. Bristow. | |
393 | Distributed under the Boost Software License, Version 1.0. | |
394 | (See accompanying file LICENSE_1_0.txt or copy at | |
395 | http://www.boost.org/LICENSE_1_0.txt). | |
396 | ] | |
397 | ||
398 |