145 lines
5.5 KiB
Plaintext
145 lines
5.5 KiB
Plaintext
[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).
|
|
]
|
|
|