]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |