ceph/src/boost/libs/math/doc/sf/ellint_legendre.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_1 Elliptic Integrals of the First Kind - Legendre Form]
  10
  11 [heading Synopsis]
  12
  13 ``
  14   #include <boost/math/special_functions/ellint_1.hpp>
  15 ``
  16
  17   namespace boost { namespace math {
  18
  19   template <class T1, class T2>
  20   ``__sf_result`` ellint_1(T1 k, T2 phi);
  21
  22   template <class T1, class T2, class ``__Policy``>
  23   ``__sf_result`` ellint_1(T1 k, T2 phi, const ``__Policy``&);
  24
  25   template <class T>
  26   ``__sf_result`` ellint_1(T k);
  27
  28   template <class T, class ``__Policy``>
  29   ``__sf_result`` ellint_1(T k, const ``__Policy``&);
  30
  31   }} // namespaces
  32
  33 [heading Description]
  34
  35 These two functions evaluate the incomplete elliptic integral of the first kind
  36 ['F([phi], k)] and its complete counterpart ['K(k) = F([pi]/2, k)].
  37
  38 [graph ellint_1]
  39
  40 The return type of these functions is computed using the __arg_promotion_rules
  41 when T1 and T2 are different types: when they are the same type then the result
  42 is the same type as the arguments.
  43
  44   template <class T1, class T2>
  45   ``__sf_result`` ellint_1(T1 k, T2 phi);
  46
  47   template <class T1, class T2, class ``__Policy``>
  48   ``__sf_result`` ellint_1(T1 k, T2 phi, const ``__Policy``&);
  49
  50 Returns the incomplete elliptic integral of the first kind ['F([phi], k)]:
  51
  52 [equation ellint2]
  53
  54 Requires -1 <= k <= 1, otherwise returns the result of __domain_error.
  55
  56 [optional_policy]
  57
  58   template <class T>
  59   ``__sf_result`` ellint_1(T k);
  60
  61   template <class T>
  62   ``__sf_result`` ellint_1(T k, const ``__Policy``&);
  63
  64 Returns the complete elliptic integral of the first kind ['K(k)]:
  65
  66 [equation ellint6]
  67
  68 Requires -1 <= k <= 1, otherwise returns the result of __domain_error.
  69
  70 [optional_policy]
  71
  72 [heading Accuracy]
  73
  74 These functions are computed using only basic arithmetic operations, so
  75 there isn't much variation in accuracy over differing platforms.
  76 Note that only results for the widest floating point type on the
  77 system are given as narrower types have __zero_error.  All values
  78 are relative errors in units of epsilon.
  79
  80 [table_ellint_1]
  81
  82 [heading Testing]
  83
  84 The tests use a mixture of spot test values calculated using the online
  85 calculator at [@http://functions.wolfram.com/ functions.wolfram.com],
  86 and random test data generated using
  87 NTL::RR at 1000-bit precision and this implementation.
  88
  89 [heading Implementation]
  90
  91 These functions are implemented in terms of Carlson's integrals
  92 using the relations:
  93
  94 [equation ellint19]
  95
  96 and
  97
  98 [equation ellint20]
  99
 100
 101 [endsect]
 102
 103 [section:ellint_2 Elliptic Integrals of the Second Kind - Legendre Form]
 104
 105 [heading Synopsis]
 106
 107 ``
 108   #include <boost/math/special_functions/ellint_2.hpp>
 109 ``
 110
 111   namespace boost { namespace math {
 112
 113   template <class T1, class T2>
 114   ``__sf_result`` ellint_2(T1 k, T2 phi);
 115
 116   template <class T1, class T2, class ``__Policy``>
 117   ``__sf_result`` ellint_2(T1 k, T2 phi, const ``__Policy``&);
 118
 119   template <class T>
 120   ``__sf_result`` ellint_2(T k);
 121
 122   template <class T, class ``__Policy``>
 123   ``__sf_result`` ellint_2(T k, const ``__Policy``&);
 124
 125   }} // namespaces
 126
 127 [heading Description]
 128
 129 These two functions evaluate the incomplete elliptic integral of the second kind
 130 ['E([phi], k)] and its complete counterpart ['E(k) = E([pi]/2, k)].
 131
 132 [graph ellint_2]
 133
 134 The return type of these functions is computed using the __arg_promotion_rules
 135 when T1 and T2 are different types: when they are the same type then the result
 136 is the same type as the arguments.
 137
 138   template <class T1, class T2>
 139   ``__sf_result`` ellint_2(T1 k, T2 phi);
 140
 141   template <class T1, class T2, class ``__Policy``>
 142   ``__sf_result`` ellint_2(T1 k, T2 phi, const ``__Policy``&);
 143
 144 Returns the incomplete elliptic integral of the second kind ['E([phi], k)]:
 145
 146 [equation ellint3]
 147
 148 Requires -1 <= k <= 1, otherwise returns the result of __domain_error.
 149
 150 [optional_policy]
 151
 152   template <class T>
 153   ``__sf_result`` ellint_2(T k);
 154
 155   template <class T>
 156   ``__sf_result`` ellint_2(T k, const ``__Policy``&);
 157
 158 Returns the complete elliptic integral of the second kind ['E(k)]:
 159
 160 [equation ellint7]
 161
 162 Requires -1 <= k <= 1, otherwise returns the result of __domain_error.
 163
 164 [optional_policy]
 165
 166 [heading Accuracy]
 167
 168 These functions are computed using only basic arithmetic operations, so
 169 there isn't much variation in accuracy over differing platforms.
 170 Note that only results for the widest floating point type on the
 171 system are given as narrower types have __zero_error.  All values
 172 are relative errors in units of epsilon.
 173
 174 [table_ellint_2]
 175
 176 [heading Testing]
 177
 178 The tests use a mixture of spot test values calculated using the online
 179 calculator at [@http://functions.wolfram.com
 180 functions.wolfram.com], and random test data generated using
 181 NTL::RR at 1000-bit precision and this implementation.
 182
 183 [heading Implementation]
 184
 185 These functions are implemented in terms of Carlson's integrals
 186 using the relations:
 187
 188 [equation ellint21]
 189
 190 and
 191
 192 [equation ellint22]
 193
 194
 195 [endsect]
 196
 197 [section:ellint_3 Elliptic Integrals of the Third Kind - Legendre Form]
 198
 199 [heading Synopsis]
 200
 201 ``
 202   #include <boost/math/special_functions/ellint_3.hpp>
 203 ``
 204
 205   namespace boost { namespace math {
 206
 207   template <class T1, class T2, class T3>
 208   ``__sf_result`` ellint_3(T1 k, T2 n, T3 phi);
 209
 210   template <class T1, class T2, class T3, class ``__Policy``>
 211   ``__sf_result`` ellint_3(T1 k, T2 n, T3 phi, const ``__Policy``&);
 212
 213   template <class T1, class T2>
 214   ``__sf_result`` ellint_3(T1 k, T2 n);
 215
 216   template <class T1, class T2, class ``__Policy``>
 217   ``__sf_result`` ellint_3(T1 k, T2 n, const ``__Policy``&);
 218
 219   }} // namespaces
 220
 221 [heading Description]
 222
 223 These two functions evaluate the incomplete elliptic integral of the third kind
 224 ['[Pi](n, [phi], k)] and its complete counterpart ['[Pi](n, k) = E(n, [pi]/2, k)].
 225
 226 [graph ellint_3]
 227
 228 The return type of these functions is computed using the __arg_promotion_rules
 229 when the arguments are of different types: when they are the same type then the result
 230 is the same type as the arguments.
 231
 232   template <class T1, class T2, class T3>
 233   ``__sf_result`` ellint_3(T1 k, T2 n, T3 phi);
 234
 235   template <class T1, class T2, class T3, class ``__Policy``>
 236   ``__sf_result`` ellint_3(T1 k, T2 n, T3 phi, const ``__Policy``&);
 237
 238 Returns the incomplete elliptic integral of the third kind ['[Pi](n, [phi], k)]:
 239
 240 [equation ellint4]
 241
 242 Requires ['-1 <= k <= 1] and ['n < 1/sin[super 2]([phi])], otherwise
 243 returns the result of __domain_error (outside this range the result
 244 would be complex).
 245
 246 [optional_policy]
 247
 248   template <class T1, class T2>
 249   ``__sf_result`` ellint_3(T1 k, T2 n);
 250
 251   template <class T1, class T2, class ``__Policy``>
 252   ``__sf_result`` ellint_3(T1 k, T2 n, const ``__Policy``&);
 253
 254 Returns the complete elliptic integral of the first kind ['[Pi](n, k)]:
 255
 256 [equation ellint8]
 257
 258 Requires ['-1 <= k <= 1] and ['n < 1], otherwise returns the
 259 result of __domain_error (outside this range the result would be complex).
 260
 261 [optional_policy]
 262
 263 [heading Accuracy]
 264
 265 These functions are computed using only basic arithmetic operations, so
 266 there isn't much variation in accuracy over differing platforms.
 267 Note that only results for the widest floating point type on the
 268 system are given as narrower types have __zero_error.  All values
 269 are relative errors in units of epsilon.
 270
 271 [table_ellint_3]
 272
 273 [heading Testing]
 274
 275 The tests use a mixture of spot test values calculated using the online
 276 calculator at [@http://functions.wolfram.com
 277 functions.wolfram.com], and random test data generated using
 278 NTL::RR at 1000-bit precision and this implementation.
 279
 280 [heading Implementation]
 281
 282 The implementation for [Pi](n, [phi], k) first siphons off the special cases:
 283
 284 ['[Pi](0, [phi], k) = F([phi], k)]
 285
 286 ['[Pi](n, [pi]/2, k) = [Pi](n, k)]
 287
 288 and
 289
 290 [equation ellint23]
 291
 292 Then if n < 0 the relations (A&S 17.7.15/16):
 293
 294 [equation ellint24]
 295
 296 are used to shift /n/ to the range \[0, 1\].
 297
 298 Then the relations:
 299
 300 ['[Pi](n, -[phi], k) = -[Pi](n, [phi], k)]
 301
 302 ['[Pi](n, [phi]+m[pi], k) = [Pi](n, [phi], k) + 2m[Pi](n, k) ; n <= 1]
 303
 304 ['[Pi](n, [phi]+m[pi], k) = [Pi](n, [phi], k) ; n > 1]
 305 [footnote I haven't been able to find a literature reference for this
 306 relation, but it appears to be the convention used by Mathematica.
 307 Intuitively the first ['2 * m * [Pi](n, k)] terms cancel out as the
 308 derivative alternates between +[infin] and -[infin].]
 309
 310 are used to move [phi][space] to the range \[0, [pi]\/2\].
 311
 312 The functions are then implemented in terms of Carlson's integrals
 313 using the relations:
 314
 315 [equation ellint25]
 316
 317 and
 318
 319 [equation ellint26]
 320
 321 [endsect]
 322
 323 [section:ellint_d Elliptic Integral D - Legendre Form]
 324
 325 [heading Synopsis]
 326
 327 ``
 328   #include <boost/math/special_functions/ellint_d.hpp>
 329 ``
 330
 331   namespace boost { namespace math {
 332
 333   template <class T1, class T2>
 334   ``__sf_result`` ellint_d(T1 k, T2 phi);
 335
 336   template <class T1, class T2, class ``__Policy``>
 337   ``__sf_result`` ellint_d(T1 k, T2 phi, const ``__Policy``&);
 338
 339   template <class T1>
 340   ``__sf_result`` ellint_d(T1 k);
 341
 342   template <class T1, class ``__Policy``>
 343   ``__sf_result`` ellint_d(T1 k, const ``__Policy``&);
 344
 345   }} // namespaces
 346
 347 [heading Description]
 348
 349 These two functions evaluate the incomplete elliptic integral
 350 ['D([phi], k)] and its complete counterpart ['D(k) = D([pi]/2, k)].
 351
 352 The return type of these functions is computed using the __arg_pomotion_rules
 353 when the arguments are of different types: when they are the same type then the result
 354 is the same type as the arguments.
 355
 356   template <class T1, class T2>
 357   ``__sf_result`` ellint_d(T1 k, T2 phi);
 358
 359   template <class T1, class T2, class ``__Policy``>
 360   ``__sf_result`` ellint_3(T1 k, T2 phi, const ``__Policy``&);
 361
 362 Returns the incomplete elliptic integral:
 363
 364 [equation ellint_d]
 365
 366 Requires ['-1 <= k <= 1], otherwise
 367 returns the result of __domain_error (outside this range the result
 368 would be complex).
 369
 370 [optional_policy]
 371
 372   template <class T1>
 373   ``__sf_result`` ellint_d(T1 k);
 374
 375   template <class T1, class ``__Policy``>
 376   ``__sf_result`` ellint_d(T1 k, const ``__Policy``&);
 377
 378 Returns the complete elliptic integral ['D(k) = D([pi]/2, k)]
 379
 380 Requires ['-1 <= k <= 1] otherwise returns the
 381 result of __domain_error (outside this range the result would be complex).
 382
 383 [optional_policy]
 384
 385 [heading Accuracy]
 386
 387 These functions are trivially computed in terms of other elliptic integrals
 388 and generally have very low error rates (a few epsilon) unless parameter [phi]
 389 is very large, in which case the usual trigonometric function argument-reduction issues apply.
 390
 391 [table_ellint_d_complete_]
 392
 393 [table_ellint_d]
 394
 395 [heading Testing]
 396
 397 The tests use a mixture of spot test values calculated using
 398 values calculated at wolframalpha.com, and random test data generated using
 399 MPFR at 1000-bit precision and a deliberately naive implementation in terms of
 400 the Legendre integrals.
 401
 402 [heading Implementation]
 403
 404 The implementation for D([phi], k) first performs argument reduction using the relations:
 405
 406 ['D(-[phi], k) = -D([phi], k)]
 407
 408 and
 409
 410 ['D(n[pi]+[phi], k) = 2nD(k) + D([phi], k)]
 411
 412 to move [phi][space] to the range \[0, [pi]\/2\].
 413
 414 The functions are then implemented in terms of Carlson's integral R[sub D]
 415 using the relation:
 416
 417 [equation ellint_d]
 418
 419 [endsect]
 420
 421 [section:jacobi_zeta Jacobi Zeta Function]
 422
 423 [heading Synopsis]
 424
 425 ``
 426   #include <boost/math/special_functions/jacobi_zeta.hpp>
 427 ``
 428
 429   namespace boost { namespace math {
 430
 431   template <class T1, class T2>
 432   ``__sf_result`` jacobi_zeta(T1 k, T2 phi);
 433
 434   template <class T1, class T2, class ``__Policy``>
 435   ``__sf_result`` jacobi_zeta(T1 k, T2 phi, const ``__Policy``&);
 436
 437   }} // namespaces
 438
 439 [heading Description]
 440
 441 This function evaluates the Jacobi Zeta Function ['Z([phi], k)]
 442
 443 [equation jacobi_zeta]
 444
 445 The return type of this function is computed using the __arg_pomotion_rules
 446 when the arguments are of different types: when they are the same type then the result
 447 is the same type as the arguments.
 448
 449 Requires ['-1 <= k <= 1], otherwise
 450 returns the result of __domain_error (outside this range the result
 451 would be complex).
 452
 453 [optional_policy]
 454
 455 Note that there is no complete analogue of this function (where [phi] = [pi] / 2)
 456 as this takes the value 0 for all ['k].
 457
 458 [heading Accuracy]
 459
 460 These functions are trivially computed in terms of other elliptic integrals
 461 and generally have very low error rates (a few epsilon) unless parameter [phi]
 462 is very large, in which case the usual trigonometric function argument-reduction issues apply.
 463
 464 [table_jacobi_zeta]
 465
 466 [heading Testing]
 467
 468 The tests use a mixture of spot test values calculated using
 469 values calculated at wolframalpha.com, and random test data generated using
 470 MPFR at 1000-bit precision and a deliberately naive implementation in terms of
 471 the Legendre integrals.
 472
 473 [heading Implementation]
 474
 475 The implementation for Z([phi], k) first makes the argument [phi] positive using:
 476
 477 ['Z(-[phi], k) = -Z([phi], k)]
 478
 479 The function is then implemented in terms of Carlson's integral R[sub J]
 480 using the relation:
 481
 482 [equation jacobi_zeta]
 483
 484 There is one special case where the above relation fails: when ['k = 1], in that case
 485 the function simplifies to
 486
 487 ['Z([phi], 1) = sign(cos([phi])) sin([phi])]
 488
 489 [endsect]
 490
 491 [section:heuman_lambda Heuman Lambda Function]
 492
 493 [heading Synopsis]
 494
 495 ``
 496   #include <boost/math/special_functions/heuman_lambda.hpp>
 497 ``
 498
 499   namespace boost { namespace math {
 500
 501   template <class T1, class T2>
 502   ``__sf_result`` heuman_lambda(T1 k, T2 phi);
 503
 504   template <class T1, class T2, class ``__Policy``>
 505   ``__sf_result`` heuman_lambda(T1 k, T2 phi, const ``__Policy``&);
 506
 507   }} // namespaces
 508
 509 [heading Description]
 510
 511 This function evaluates the Heuman Lambda Function ['[Lambda][sub 0]([phi], k)]
 512
 513 [equation heuman_lambda]
 514
 515 The return type of this function is computed using the __arg_pomotion_rules
 516 when the arguments are of different types: when they are the same type then the result
 517 is the same type as the arguments.
 518
 519 Requires ['-1 <= k <= 1], otherwise
 520 returns the result of __domain_error (outside this range the result
 521 would be complex).
 522
 523 [optional_policy]
 524
 525 Note that there is no complete analogue of this function (where [phi] = [pi] / 2)
 526 as this takes the value 1 for all ['k].
 527
 528 [heading Accuracy]
 529
 530 These functions are trivially computed in terms of other elliptic integrals
 531 and generally have very low error rates (a few epsilon) unless parameter [phi]
 532 is very large, in which case the usual trigonometric function argument-reduction issues apply.
 533
 534 [table_heuman_lambda]
 535
 536 [heading Testing]
 537
 538 The tests use a mixture of spot test values calculated using
 539 values calculated at wolframalpha.com, and random test data generated using
 540 MPFR at 1000-bit precision and a deliberately naive implementation in terms of
 541 the Legendre integrals.
 542
 543 [heading Implementation]
 544
 545 The function is then implemented in terms of Carlson's integrals R[sub J] and R[sub F]
 546 using the relation:
 547
 548 [equation heuman_lambda]
 549
 550 This relation fails for ['|[phi]| >= [pi]/2] in which case the definition in terms of the
 551 Jacobi Zeta is used.
 552
 553 [endsect]
 554