| [section:sph_harm Spherical Harmonics] |
| |
| [h4 Synopsis] |
| |
| `` |
| #include <boost/math/special_functions/spheric_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_pomotion_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 Peak Errors In the Sperical Harmonic Functions |
| [[Significand Size] [Platform and Compiler] [Errors in range |
| |
| 0 < l < 20] ] |
| [[53] [Win32, Visual C++ 8] [Peak=2x10[super 4] Mean=700] ] |
| [[64] [SUSE Linux IA32, g++ 4.1] [Peak=2900 Mean=100]] |
| [[64] [Red Hat Linux IA64, g++ 3.4.4] [Peak=2900 Mean=100] ] |
| [[113] [HPUX IA64, aCC A.06.06] [Peak=6700 Mean=230]] |
| ] |
| |
| 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). |
| ] |
| |