123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144 |
- [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] is taken as the polar (colatitudinal) coordinate
- with [theta] in \[0, [pi]\], and [phi]as the azimuthal (longitudinal)
- coordinate with [phi]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] outside \[0, [pi]\] and [phi] outside \[0, 2[pi]\] this
- implementation follows the convention used by Mathematica:
- the function is periodic with period [pi] in [theta] and 2[pi] 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] and [phi] 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).
- ]
|