boost_1_45_0/libs/math/doc/sf_and_dist/ellint_carlson.qbk

[/
Copyright (c) 2006 Xiaogang Zhang
Copyright (c) 2006 John Maddock
Use, modification and distribution are subject to the
Boost Software License, Version 1.0. (See accompanying file
LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section:ellint_carlson Elliptic Integrals - Carlson Form]

[heading Synopsis]

``
  #include <boost/math/special_functions/ellint_rf.hpp>
``

  namespace boost { namespace math {

  template <class T1, class T2, class T3>
  ``__sf_result`` ellint_rf(T1 x, T2 y, T3 z)

  template <class T1, class T2, class T3, class ``__Policy``>
  ``__sf_result`` ellint_rf(T1 x, T2 y, T3 z, const ``__Policy``&)

  }} // namespaces


``
  #include <boost/math/special_functions/ellint_rd.hpp>
``

  namespace boost { namespace math {

  template <class T1, class T2, class T3>
  ``__sf_result`` ellint_rd(T1 x, T2 y, T3 z)

  template <class T1, class T2, class T3, class ``__Policy``>
  ``__sf_result`` ellint_rd(T1 x, T2 y, T3 z, const ``__Policy``&)

  }} // namespaces


``
  #include <boost/math/special_functions/ellint_rj.hpp>
``

  namespace boost { namespace math {

  template <class T1, class T2, class T3, class T4>
  ``__sf_result`` ellint_rj(T1 x, T2 y, T3 z, T4 p)

  template <class T1, class T2, class T3, class T4, class ``__Policy``>
  ``__sf_result`` ellint_rj(T1 x, T2 y, T3 z, T4 p, const ``__Policy``&)

  }} // namespaces


``
  #include <boost/math/special_functions/ellint_rc.hpp>
``

  namespace boost { namespace math {

  template <class T1, class T2>
  ``__sf_result`` ellint_rc(T1 x, T2 y)

  template <class T1, class T2, class ``__Policy``>
  ``__sf_result`` ellint_rc(T1 x, T2 y, const ``__Policy``&)

  }} // namespaces


[heading Description]

These functions return Carlson's symmetrical elliptic integrals, the functions
have complicated behavior over all their possible domains, but the following
graph gives an idea of their behavior:

[graph ellint_carlson]

The return type of these functions is computed using the __arg_pomotion_rules
when the arguments are of different types: otherwise the return is the same type 
as the arguments.

  template <class T1, class T2, class T3>
  ``__sf_result`` ellint_rf(T1 x, T2 y, T3 z)
  
  template <class T1, class T2, class T3, class ``__Policy``>
  ``__sf_result`` ellint_rf(T1 x, T2 y, T3 z, const ``__Policy``&)
  
Returns Carlson's Elliptic Integral R[sub F]:

[equation ellint9]

Requires that all of the arguments are non-negative, and at most
one may be zero.  Otherwise returns the result of __domain_error.

[optional_policy]

  template <class T1, class T2, class T3>
  ``__sf_result`` ellint_rd(T1 x, T2 y, T3 z)
  
  template <class T1, class T2, class T3, class ``__Policy``>
  ``__sf_result`` ellint_rd(T1 x, T2 y, T3 z, const ``__Policy``&)
  
Returns Carlson's elliptic integral R[sub D]:

[equation ellint10]

Requires that x and y are non-negative, with at most one of them
zero, and that z >= 0.  Otherwise returns the result of __domain_error.

[optional_policy]

  template <class T1, class T2, class T3, class T4>
  ``__sf_result`` ellint_rj(T1 x, T2 y, T3 z, T4 p)

  template <class T1, class T2, class T3, class T4, class ``__Policy``>
  ``__sf_result`` ellint_rj(T1 x, T2 y, T3 z, T4 p, const ``__Policy``&)

Returns Carlson's elliptic integral R[sub J]:
  
[equation ellint11]

Requires that x, y and z are non-negative, with at most one of them
zero, and that ['p != 0].  Otherwise returns the result of __domain_error.

[optional_policy]

When ['p < 0] the function returns the
[@http://en.wikipedia.org/wiki/Cauchy_principal_value Cauchy principal value]
using the relation:

[equation ellint17]

  template <class T1, class T2>
  ``__sf_result`` ellint_rc(T1 x, T2 y)

  template <class T1, class T2, class ``__Policy``>
  ``__sf_result`` ellint_rc(T1 x, T2 y, const ``__Policy``&)

Returns Carlson's elliptic integral R[sub C]:
  
[equation ellint12]

Requires that ['x > 0] and that ['y != 0].  
Otherwise returns the result of __domain_error.

[optional_policy]

When ['y < 0] the function returns the
[@http://mathworld.wolfram.com/CauchyPrincipalValue.html Cauchy principal value]
using the relation:

[equation ellint18]

[heading Testing]

There are two sets of tests.

Spot tests compare selected values with test data given in:

[:B. C. Carlson, ['[@http://arxiv.org/abs/math.CA/9409227 
Numerical computation of real or complex elliptic integrals]]. Numerical Algorithms,
Volume 10, Number 1 / March, 1995, pp 13-26.]

Random test data generated using NTL::RR at 1000-bit precision and our
implementation checks for rounding-errors and/or regressions.

There are also sanity checks that use the inter-relations between the integrals
to verify their correctness: see the above Carlson paper for details.

[heading Accuracy]

These functions are computed using only basic arithmetic operations, so
there isn't much variation in accuracy over differing platforms.
Note that only results for the widest floating-point type on the 
system are given as narrower types have __zero_error.  All values
are relative errors in units of epsilon.

[table Errors Rates in the Carlson Elliptic Integrals
[[Significand Size] [Platform and Compiler] [R[sub F]] [R[sub D]] [R[sub J]] [R[sub C]]]
[[53] [Win32 / Visual C++ 8.0] [Peak=2.9 Mean=0.75] [Peak=2.6 Mean=0.9] [Peak=108 Mean=6.9] [Peak=2.4 Mean=0.6] ]
[[64] [Red Hat Linux / G++ 3.4] [Peak=2.5 Mean=0.75] [Peak=2.7 Mean=0.9] [Peak=105 Mean=8] [Peak=1.9 Mean=0.7] ]
[[113] [HP-UX / HP aCC 6] [Peak=5.3 Mean=1.6] [Peak=2.9 Mean=0.99] [Peak=180 Mean=12] [Peak=1.8 Mean=0.7] ]
]

[heading Implementation]

The key of Carlson's algorithm [[link ellint_ref_carlson79 Carlson79]] is the
duplication theorem:

[equation ellint13]

By applying it repeatedly, ['x], ['y], ['z] get
closer and closer. When they are nearly equal, the special case equation

[equation ellint16]

is used. More specifically, ['[R F]] is evaluated from a Taylor series
expansion to the fifth order. The calculations of the other three integrals
are analogous.

For ['p < 0] in ['R[sub J](x, y, z, p)] and ['y < 0] in ['R[sub C](x, y)],
the integrals are singular and their
[@http://mathworld.wolfram.com/CauchyPrincipalValue.html Cauchy principal values]
are returned via the relations:

[equation ellint17]

[equation ellint18]

[endsect]