bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / libs / math / doc / sf / spherical_harmonic.qbk

[section:sph_harm Spherical Harmonics]

[h4 Synopsis]

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

   namespace boost{ namespace math{
   
   template <class T1, class T2>
   std::complex<``__sf_result``> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi);

   template <class T1, class T2, class ``__Policy``>
   std::complex<``__sf_result``> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);

   template <class T1, class T2>
   ``__sf_result`` spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi);

   template <class T1, class T2, class ``__Policy``>
   ``__sf_result`` spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);

   template <class T1, class T2>
   ``__sf_result`` spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi);
      
   template <class T1, class T2, class ``__Policy``>
   ``__sf_result`` spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
      
   }} // namespaces

[h4 Description]

The return type of these functions is computed using the __arg_promotion_rules
when T1 and T2 are different types.

[optional_policy]

   template <class T1, class T2>
   std::complex<``__sf_result``> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi);
   
   template <class T1, class T2, class ``__Policy``>
   std::complex<``__sf_result``> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
   
Returns the value of the Spherical Harmonic Y[sub n][super m](theta, phi):

[equation spherical_0]

The spherical harmonics Y[sub n][super m](theta, phi) are the angular 
portion of the solution to Laplace's equation in spherical coordinates 
where azimuthal symmetry is not present.

[caution Care must be taken in correctly identifying the arguments to this
function: [theta][space] is taken as the polar (colatitudinal) coordinate 
with [theta][space] in \[0, [pi]\], and [phi][space] as the azimuthal (longitudinal)
coordinate with [phi][space] in \[0,2[pi]).  This is the convention used in Physics,
and matches the definition used by 
[@http://documents.wolfram.com/mathematica/functions/SphericalHarmonicY 
Mathematica in the function SpericalHarmonicY], 
but is opposite to the usual mathematical conventions.

Some other sources include an additional Condon-Shortley phase term of 
(-1)[super m] in the definition of this function: note however that our
definition of the associated Legendre polynomial already includes this term.

This implementation returns zero for m > n

For [theta][space] outside \[0, [pi]\] and [phi][space] outside \[0, 2[pi]\] this 
implementation follows the convention used by Mathematica:
the function is periodic with period [pi][space] in [theta][space] and 2[pi][space] in
[phi].  Please note that this is not the behaviour one would get
from a casual application of the function's definition.  Cautious users 
should keep [theta][space] and [phi][space] to the range \[0, [pi]\] and 
\[0, 2[pi]\] respectively.

See: [@http://mathworld.wolfram.com/SphericalHarmonic.html 
Weisstein, Eric W. "Spherical Harmonic." 
From MathWorld--A Wolfram Web Resource].  ]

   template <class T1, class T2>
   ``__sf_result`` spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi);
   
   template <class T1, class T2, class ``__Policy``>
   ``__sf_result`` spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
   
Returns the real part of Y[sub n][super m](theta, phi):

[equation spherical_1]

   template <class T1, class T2>
   ``__sf_result`` spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi);
   
   template <class T1, class T2, class ``__Policy``>
   ``__sf_result`` spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
   
Returns the imaginary part of Y[sub n][super m](theta, phi):

[equation spherical_2]

[h4 Accuracy]

The following table shows peak errors for various domains of input arguments.  
Note that only results for the widest floating point type on the system are 
given as narrower types have __zero_error.  Peak errors are the same
for both the real and imaginary parts, as the error is dominated by
calculation of the associated Legendre polynomials: especially near the
roots of the associated Legendre function.

All values are in units of epsilon.

[table_spherical_harmonic_r]

[table_spherical_harmonic_i]

Note that the worst errors occur when the degree increases, values greater than
~120 are very unlikely to produce sensible results, especially 
when the order is also large.  Further the relative errors
are likely to grow arbitrarily large when the function is very close to a root.

[h4 Testing]

A mixture of spot tests of values calculated using functions.wolfram.com, 
and randomly generated test data are
used: the test data was computed using
[@http://shoup.net/ntl/doc/RR.txt NTL::RR] at 1000-bit precision.

[h4 Implementation]

These functions are implemented fairly naively using the formulae
given above.  Some extra care is taken to prevent roundoff error
when converting from polar coordinates (so for example the 
['1-x[super 2]] term used by the associated Legendre functions is calculated
without roundoff error using ['x = cos(theta)], and 
['1-x[super 2] = sin[super 2](theta)]).  The limiting factor in the error
rates for these functions is the need to calculate values near the roots
of the associated Legendre functions.

[endsect][/section:beta_function The Beta Function]
[/ 
  Copyright 2006 John Maddock and Paul A. Bristow.
  Distributed under 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).
]