ceph/src/boost/libs/math/doc/sf/ellint_carlson.qbk

   1 [/
   2 Copyright (c) 2006 Xiaogang Zhang
   3 Copyright (c) 2006 John Maddock
   4 Use, modification and distribution are subject to the
   5 Boost Software License, Version 1.0. (See accompanying file
   6 LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   7 ]
   8
   9 [section:ellint_carlson Elliptic Integrals - Carlson Form]
  10
  11 [heading Synopsis]
  12
  13 ``
  14   #include <boost/math/special_functions/ellint_rf.hpp>
  15 ``
  16
  17   namespace boost { namespace math {
  18
  19   template <class T1, class T2, class T3>
  20   ``__sf_result`` ellint_rf(T1 x, T2 y, T3 z)
  21
  22   template <class T1, class T2, class T3, class ``__Policy``>
  23   ``__sf_result`` ellint_rf(T1 x, T2 y, T3 z, const ``__Policy``&)
  24
  25   }} // namespaces
  26
  27
  28 ``
  29   #include <boost/math/special_functions/ellint_rd.hpp>
  30 ``
  31
  32   namespace boost { namespace math {
  33
  34   template <class T1, class T2, class T3>
  35   ``__sf_result`` ellint_rd(T1 x, T2 y, T3 z)
  36
  37   template <class T1, class T2, class T3, class ``__Policy``>
  38   ``__sf_result`` ellint_rd(T1 x, T2 y, T3 z, const ``__Policy``&)
  39
  40   }} // namespaces
  41
  42
  43 ``
  44   #include <boost/math/special_functions/ellint_rj.hpp>
  45 ``
  46
  47   namespace boost { namespace math {
  48
  49   template <class T1, class T2, class T3, class T4>
  50   ``__sf_result`` ellint_rj(T1 x, T2 y, T3 z, T4 p)
  51
  52   template <class T1, class T2, class T3, class T4, class ``__Policy``>
  53   ``__sf_result`` ellint_rj(T1 x, T2 y, T3 z, T4 p, const ``__Policy``&)
  54
  55   }} // namespaces
  56
  57
  58 ``
  59   #include <boost/math/special_functions/ellint_rc.hpp>
  60 ``
  61
  62   namespace boost { namespace math {
  63
  64   template <class T1, class T2>
  65   ``__sf_result`` ellint_rc(T1 x, T2 y)
  66
  67   template <class T1, class T2, class ``__Policy``>
  68   ``__sf_result`` ellint_rc(T1 x, T2 y, const ``__Policy``&)
  69
  70   }} // namespaces
  71
  72 ``
  73   #include <boost/math/special_functions/ellint_rg.hpp>
  74 ``
  75
  76   namespace boost { namespace math {
  77
  78   template <class T1, class T2, class T3>
  79   ``__sf_result`` ellint_rg(T1 x, T2 y, T3 z)
  80
  81   template <class T1, class T2, class T3, class ``__Policy``>
  82   ``__sf_result`` ellint_rg(T1 x, T2 y, T3 z, const ``__Policy``&)
  83
  84   }} // namespaces
  85
  86
  87
  88 [heading Description]
  89
  90 These functions return Carlson's symmetrical elliptic integrals, the functions
  91 have complicated behavior over all their possible domains, but the following
  92 graph gives an idea of their behavior:
  93
  94 [graph ellint_carlson]
  95
  96 The return type of these functions is computed using the __arg_promotion_rules
  97 when the arguments are of different types: otherwise the return is the same type
  98 as the arguments.
  99
 100   template <class T1, class T2, class T3>
 101   ``__sf_result`` ellint_rf(T1 x, T2 y, T3 z)
 102
 103   template <class T1, class T2, class T3, class ``__Policy``>
 104   ``__sf_result`` ellint_rf(T1 x, T2 y, T3 z, const ``__Policy``&)
 105
 106 Returns Carlson's Elliptic Integral R[sub F]:
 107
 108 [equation ellint9]
 109
 110 Requires that all of the arguments are non-negative, and at most
 111 one may be zero.  Otherwise returns the result of __domain_error.
 112
 113 [optional_policy]
 114
 115   template <class T1, class T2, class T3>
 116   ``__sf_result`` ellint_rd(T1 x, T2 y, T3 z)
 117
 118   template <class T1, class T2, class T3, class ``__Policy``>
 119   ``__sf_result`` ellint_rd(T1 x, T2 y, T3 z, const ``__Policy``&)
 120
 121 Returns Carlson's elliptic integral R[sub D]:
 122
 123 [equation ellint10]
 124
 125 Requires that x and y are non-negative, with at most one of them
 126 zero, and that z >= 0.  Otherwise returns the result of __domain_error.
 127
 128 [optional_policy]
 129
 130   template <class T1, class T2, class T3, class T4>
 131   ``__sf_result`` ellint_rj(T1 x, T2 y, T3 z, T4 p)
 132
 133   template <class T1, class T2, class T3, class T4, class ``__Policy``>
 134   ``__sf_result`` ellint_rj(T1 x, T2 y, T3 z, T4 p, const ``__Policy``&)
 135
 136 Returns Carlson's elliptic integral R[sub J]:
 137
 138 [equation ellint11]
 139
 140 Requires that x, y and z are non-negative, with at most one of them
 141 zero, and that ['p != 0].  Otherwise returns the result of __domain_error.
 142
 143 [optional_policy]
 144
 145 When ['p < 0] the function returns the
 146 [@http://en.wikipedia.org/wiki/Cauchy_principal_value Cauchy principal value]
 147 using the relation:
 148
 149 [equation ellint17]
 150
 151   template <class T1, class T2>
 152   ``__sf_result`` ellint_rc(T1 x, T2 y)
 153
 154   template <class T1, class T2, class ``__Policy``>
 155   ``__sf_result`` ellint_rc(T1 x, T2 y, const ``__Policy``&)
 156
 157 Returns Carlson's elliptic integral R[sub C]:
 158
 159 [equation ellint12]
 160
 161 Requires that ['x > 0] and that ['y != 0].
 162 Otherwise returns the result of __domain_error.
 163
 164 [optional_policy]
 165
 166 When ['y < 0] the function returns the
 167 [@http://mathworld.wolfram.com/CauchyPrincipalValue.html Cauchy principal value]
 168 using the relation:
 169
 170 [equation ellint18]
 171
 172   template <class T1, class T2, class T3>
 173   ``__sf_result`` ellint_rg(T1 x, T2 y, T3 z)
 174
 175   template <class T1, class T2, class T3, class ``__Policy``>
 176   ``__sf_result`` ellint_rg(T1 x, T2 y, T3 z, const ``__Policy``&)
 177
 178 Returns Carlson's elliptic integral R[sub G]:
 179
 180 [equation ellint27]
 181
 182 Requires that x and y are non-negative, otherwise returns the result of __domain_error.
 183
 184 [optional_policy]
 185
 186 [heading Testing]
 187
 188 There are two sets of tests.
 189
 190 Spot tests compare selected values with test data given in:
 191
 192 [:B. C. Carlson, ['[@http://arxiv.org/abs/math.CA/9409227
 193 Numerical computation of real or complex elliptic integrals]]. Numerical Algorithms,
 194 Volume 10, Number 1 / March, 1995, pp 13-26.]
 195
 196 Random test data generated using NTL::RR at 1000-bit precision and our
 197 implementation checks for rounding-errors and/or regressions.
 198
 199 There are also sanity checks that use the inter-relations between the integrals
 200 to verify their correctness: see the above Carlson paper for details.
 201
 202 [heading Accuracy]
 203
 204 These functions are computed using only basic arithmetic operations, so
 205 there isn't much variation in accuracy over differing platforms.
 206 Note that only results for the widest floating-point type on the
 207 system are given as narrower types have __zero_error.  All values
 208 are relative errors in units of epsilon.
 209
 210 [table_ellint_rc]
 211
 212 [table_ellint_rd]
 213
 214 [table_ellint_rg]
 215
 216 [table_ellint_rf]
 217
 218 [table_ellint_rj]
 219
 220
 221 [heading Implementation]
 222
 223 The key of Carlson's algorithm [[link ellint_ref_carlson79 Carlson79]] is the
 224 duplication theorem:
 225
 226 [equation ellint13]
 227
 228 By applying it repeatedly, ['x], ['y], ['z] get
 229 closer and closer. When they are nearly equal, the special case equation
 230
 231 [equation ellint16]
 232
 233 is used. More specifically, ['[R F]] is evaluated from a Taylor series
 234 expansion to the fifth order. The calculations of the other three integrals
 235 are analogous, except for R[sub C] which can be computed from elementary functions.
 236
 237 For ['p < 0] in ['R[sub J](x, y, z, p)] and ['y < 0] in ['R[sub C](x, y)],
 238 the integrals are singular and their
 239 [@http://mathworld.wolfram.com/CauchyPrincipalValue.html Cauchy principal values]
 240 are returned via the relations:
 241
 242 [equation ellint17]
 243
 244 [equation ellint18]
 245
 246 [endsect]