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

   1 [section:sph_harm Spherical Harmonics]
   2
   3 [h4 Synopsis]
   4
   5 ``
   6 #include <boost/math/special_functions/spherical_harmonic.hpp>
   7 ``
   8
   9    namespace boost{ namespace math{
  10
  11    template <class T1, class T2>
  12    std::complex<``__sf_result``> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi);
  13
  14    template <class T1, class T2, class ``__Policy``>
  15    std::complex<``__sf_result``> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
  16
  17    template <class T1, class T2>
  18    ``__sf_result`` spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi);
  19
  20    template <class T1, class T2, class ``__Policy``>
  21    ``__sf_result`` spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
  22
  23    template <class T1, class T2>
  24    ``__sf_result`` spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi);
  25
  26    template <class T1, class T2, class ``__Policy``>
  27    ``__sf_result`` spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
  28
  29    }} // namespaces
  30
  31 [h4 Description]
  32
  33 The return type of these functions is computed using the __arg_promotion_rules
  34 when T1 and T2 are different types.
  35
  36 [optional_policy]
  37
  38    template <class T1, class T2>
  39    std::complex<``__sf_result``> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi);
  40
  41    template <class T1, class T2, class ``__Policy``>
  42    std::complex<``__sf_result``> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
  43
  44 Returns the value of the Spherical Harmonic Y[sub n][super m](theta, phi):
  45
  46 [equation spherical_0]
  47
  48 The spherical harmonics Y[sub n][super m](theta, phi) are the angular
  49 portion of the solution to Laplace's equation in spherical coordinates
  50 where azimuthal symmetry is not present.
  51
  52 [caution Care must be taken in correctly identifying the arguments to this
  53 function: [theta][space] is taken as the polar (colatitudinal) coordinate
  54 with [theta][space] in \[0, [pi]\], and [phi][space] as the azimuthal (longitudinal)
  55 coordinate with [phi][space] in \[0,2[pi]).  This is the convention used in Physics,
  56 and matches the definition used by
  57 [@http://documents.wolfram.com/mathematica/functions/SphericalHarmonicY
  58 Mathematica in the function SpericalHarmonicY],
  59 but is opposite to the usual mathematical conventions.
  60
  61 Some other sources include an additional Condon-Shortley phase term of
  62 (-1)[super m] in the definition of this function: note however that our
  63 definition of the associated Legendre polynomial already includes this term.
  64
  65 This implementation returns zero for m > n
  66
  67 For [theta][space] outside \[0, [pi]\] and [phi][space] outside \[0, 2[pi]\] this
  68 implementation follows the convention used by Mathematica:
  69 the function is periodic with period [pi][space] in [theta][space] and 2[pi][space] in
  70 [phi].  Please note that this is not the behaviour one would get
  71 from a casual application of the function's definition.  Cautious users
  72 should keep [theta][space] and [phi][space] to the range \[0, [pi]\] and
  73 \[0, 2[pi]\] respectively.
  74
  75 See: [@http://mathworld.wolfram.com/SphericalHarmonic.html
  76 Weisstein, Eric W. "Spherical Harmonic."
  77 From MathWorld--A Wolfram Web Resource].  ]
  78
  79    template <class T1, class T2>
  80    ``__sf_result`` spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi);
  81
  82    template <class T1, class T2, class ``__Policy``>
  83    ``__sf_result`` spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
  84
  85 Returns the real part of Y[sub n][super m](theta, phi):
  86
  87 [equation spherical_1]
  88
  89    template <class T1, class T2>
  90    ``__sf_result`` spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi);
  91
  92    template <class T1, class T2, class ``__Policy``>
  93    ``__sf_result`` spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi, const ``__Policy``&);
  94
  95 Returns the imaginary part of Y[sub n][super m](theta, phi):
  96
  97 [equation spherical_2]
  98
  99 [h4 Accuracy]
 100
 101 The following table shows peak errors for various domains of input arguments.
 102 Note that only results for the widest floating point type on the system are
 103 given as narrower types have __zero_error.  Peak errors are the same
 104 for both the real and imaginary parts, as the error is dominated by
 105 calculation of the associated Legendre polynomials: especially near the
 106 roots of the associated Legendre function.
 107
 108 All values are in units of epsilon.
 109
 110 [table_spherical_harmonic_r]
 111
 112 [table_spherical_harmonic_i]
 113
 114 Note that the worst errors occur when the degree increases, values greater than
 115 ~120 are very unlikely to produce sensible results, especially
 116 when the order is also large.  Further the relative errors
 117 are likely to grow arbitrarily large when the function is very close to a root.
 118
 119 [h4 Testing]
 120
 121 A mixture of spot tests of values calculated using functions.wolfram.com,
 122 and randomly generated test data are
 123 used: the test data was computed using
 124 [@http://shoup.net/ntl/doc/RR.txt NTL::RR] at 1000-bit precision.
 125
 126 [h4 Implementation]
 127
 128 These functions are implemented fairly naively using the formulae
 129 given above.  Some extra care is taken to prevent roundoff error
 130 when converting from polar coordinates (so for example the
 131 ['1-x[super 2]] term used by the associated Legendre functions is calculated
 132 without roundoff error using ['x = cos(theta)], and
 133 ['1-x[super 2] = sin[super 2](theta)]).  The limiting factor in the error
 134 rates for these functions is the need to calculate values near the roots
 135 of the associated Legendre functions.
 136
 137 [endsect][/section:beta_function The Beta Function]
 138 [/
 139   Copyright 2006 John Maddock and Paul A. Bristow.
 140   Distributed under the Boost Software License, Version 1.0.
 141   (See accompanying file LICENSE_1_0.txt or copy at
 142   http://www.boost.org/LICENSE_1_0.txt).
 143 ]
 144