libs/math/doc/overview/tr1.qbk

   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   Copyright 2008 John Maddock and Paul A. Bristow.
 392   Distributed under the Boost Software License, Version 1.0.
 393   (See accompanying file LICENSE_1_0.txt or copy at
 394   http://www.boost.org/LICENSE_1_0.txt).
 395 ]
 396
 397