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 33The return type of these functions is computed using the __arg_promotion_rules 34when 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 44Returns the value of the Spherical Harmonic Y[sub n][super m](theta, phi): 45 46[equation spherical_0] 47 48The spherical harmonics Y[sub n][super m](theta, phi) are the angular 49portion of the solution to Laplace's equation in spherical coordinates 50where azimuthal symmetry is not present. 51 52[caution Care must be taken in correctly identifying the arguments to this 53function: [theta] is taken as the polar (colatitudinal) coordinate 54with [theta] in \[0, [pi]\], and [phi]as the azimuthal (longitudinal) 55coordinate with [phi]in \[0,2[pi]). This is the convention used in Physics, 56and matches the definition used by 57[@http://documents.wolfram.com/mathematica/functions/SphericalHarmonicY 58Mathematica in the function SpericalHarmonicY], 59but is opposite to the usual mathematical conventions. 60 61Some other sources include an additional Condon-Shortley phase term of 62(-1)[super m] in the definition of this function: note however that our 63definition of the associated Legendre polynomial already includes this term. 64 65This implementation returns zero for m > n 66 67For [theta] outside \[0, [pi]\] and [phi] outside \[0, 2[pi]\] this 68implementation follows the convention used by Mathematica: 69the function is periodic with period [pi] in [theta] and 2[pi] in 70[phi]. Please note that this is not the behaviour one would get 71from a casual application of the function's definition. Cautious users 72should keep [theta] and [phi] to the range \[0, [pi]\] and 73\[0, 2[pi]\] respectively. 74 75See: [@http://mathworld.wolfram.com/SphericalHarmonic.html 76Weisstein, Eric W. "Spherical Harmonic." 77From 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 85Returns 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 95Returns the imaginary part of Y[sub n][super m](theta, phi): 96 97[equation spherical_2] 98 99[h4 Accuracy] 100 101The following table shows peak errors for various domains of input arguments. 102Note that only results for the widest floating point type on the system are 103given as narrower types have __zero_error. Peak errors are the same 104for both the real and imaginary parts, as the error is dominated by 105calculation of the associated Legendre polynomials: especially near the 106roots of the associated Legendre function. 107 108All values are in units of epsilon. 109 110[table_spherical_harmonic_r] 111 112[table_spherical_harmonic_i] 113 114Note that the worst errors occur when the degree increases, values greater than 115~120 are very unlikely to produce sensible results, especially 116when the order is also large. Further the relative errors 117are likely to grow arbitrarily large when the function is very close to a root. 118 119[h4 Testing] 120 121A mixture of spot tests of values calculated using functions.wolfram.com, 122and randomly generated test data are 123used: 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 128These functions are implemented fairly naively using the formulae 129given above. Some extra care is taken to prevent roundoff error 130when converting from polar coordinates (so for example the 131['1-x[super 2]] term used by the associated Legendre functions is calculated 132without roundoff error using ['x = cos(theta)], and 133['1-x[super 2] = sin[super 2](theta)]). The limiting factor in the error 134rates for these functions is the need to calculate values near the roots 135of 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 145