GeographicLib
1.44

Spherical harmonic series. More...
#include <GeographicLib/SphericalHarmonic.hpp>
Public Types  
enum  normalization { FULL, SCHMIDT } 
Public Member Functions  
SphericalHarmonic (const std::vector< real > &C, const std::vector< real > &S, int N, real a, unsigned norm=FULL)  
SphericalHarmonic (const std::vector< real > &C, const std::vector< real > &S, int N, int nmx, int mmx, real a, unsigned norm=FULL)  
SphericalHarmonic ()  
Math::real  operator() (real x, real y, real z) const 
Math::real  operator() (real x, real y, real z, real &gradx, real &grady, real &gradz) const 
CircularEngine  Circle (real p, real z, bool gradp) const 
const SphericalEngine::coeff &  Coefficients () const 
Spherical harmonic series.
This class evaluates the spherical harmonic sum
V(x, y, z) = sum(n = 0..N)[ q^(n+1) * sum(m = 0..n)[ (C[n,m] * cos(m*lambda) + S[n,m] * sin(m*lambda)) * P[n,m](cos(theta)) ] ]
where
Two normalizations are supported for P_{nm}
Clenshaw summation is used for the sums over both n and m. This allows the computation to be carried out without the need for any temporary arrays. See SphericalEngine.cpp for more information on the implementation.
References:
Example of use:
Definition at line 69 of file SphericalHarmonic.hpp.
Supported normalizations for the associated Legendre polynomials.
Enumerator  

FULL 
Fully normalized associated Legendre polynomials. These are defined by P_{nm}^{full}(z) = (−1)^{m} sqrt(k (2n + 1) (n − m)! / (n + m)!) P_{n}^{m}(z), where P_{n}^{m}(z) is Ferrers function (also known as the Legendre function on the cut or the associated Legendre polynomial) http://dlmf.nist.gov/14.7.E10 and k = 1 for m = 0 and k = 2 otherwise. The mean squared value of P_{nm}^{full}(cosθ) cos(mλ) and P_{nm}^{full}(cosθ) sin(mλ) over the sphere is 1. 
SCHMIDT 
Schmidt seminormalized associated Legendre polynomials. These are defined by P_{nm}^{schmidt}(z) = (−1)^{m} sqrt(k (n − m)! / (n + m)!) P_{n}^{m}(z), where P_{n}^{m}(z) is Ferrers function (also known as the Legendre function on the cut or the associated Legendre polynomial) http://dlmf.nist.gov/14.7.E10 and k = 1 for m = 0 and k = 2 otherwise. The mean squared value of P_{nm}^{schmidt}(cosθ) cos(mλ) and P_{nm}^{schmidt}(cosθ) sin(mλ) over the sphere is 1/(2n + 1). 
Definition at line 74 of file SphericalHarmonic.hpp.

inline 
Constructor with a full set of coefficients specified.
[in]  C  the coefficients C_{nm}. 
[in]  S  the coefficients S_{nm}. 
[in]  N  the maximum degree and order of the sum 
[in]  a  the reference radius appearing in the definition of the sum. 
[in]  norm  the normalization for the associated Legendre polynomials, either SphericalHarmonic::FULL (the default) or SphericalHarmonic::SCHMIDT. 
GeographicErr  if N does not satisfy N ≥ −1. 
GeographicErr  if C or S is not big enough to hold the coefficients. 
The coefficients C_{nm} and S_{nm} are stored in the onedimensional vectors C and S which must contain (N + 1)(N + 2)/2 and N (N + 1)/2 elements, respectively, stored in "columnmajor" order. Thus for N = 3, the order would be: C_{00}, C_{10}, C_{20}, C_{30}, C_{11}, C_{21}, C_{31}, C_{22}, C_{32}, C_{33}. In general the (n,m) element is at index m N − m (m − 1)/2 + n. The layout of S is the same except that the first column is omitted (since the m = 0 terms never contribute to the sum) and the 0th element is S_{11}
The class stores pointers to the first elements of C and S. These arrays should not be altered or destroyed during the lifetime of a SphericalHarmonic object.
Definition at line 172 of file SphericalHarmonic.hpp.

inline 
Constructor with a subset of coefficients specified.
[in]  C  the coefficients C_{nm}. 
[in]  S  the coefficients S_{nm}. 
[in]  N  the degree used to determine the layout of C and S. 
[in]  nmx  the maximum degree used in the sum. The sum over n is from 0 thru nmx. 
[in]  mmx  the maximum order used in the sum. The sum over m is from 0 thru min(n, mmx). 
[in]  a  the reference radius appearing in the definition of the sum. 
[in]  norm  the normalization for the associated Legendre polynomials, either SphericalHarmonic::FULL (the default) or SphericalHarmonic::SCHMIDT. 
GeographicErr  if N, nmx, and mmx do not satisfy N ≥ nmx ≥ mmx ≥ −1. 
GeographicErr  if C or S is not big enough to hold the coefficients. 
The class stores pointers to the first elements of C and S. These arrays should not be altered or destroyed during the lifetime of a SphericalHarmonic object.
Definition at line 203 of file SphericalHarmonic.hpp.

inline 
A default constructor so that the object can be created when the constructor for another object is initialized. This default object can then be reset with the default copy assignment operator.
Definition at line 216 of file SphericalHarmonic.hpp.

inline 
Compute the spherical harmonic sum.
[in]  x  cartesian coordinate. 
[in]  y  cartesian coordinate. 
[in]  z  cartesian coordinate. 
This routine requires constant memory and thus never throws an exception.
Definition at line 229 of file SphericalHarmonic.hpp.

inline 
Compute a spherical harmonic sum and its gradient.
[in]  x  cartesian coordinate. 
[in]  y  cartesian coordinate. 
[in]  z  cartesian coordinate. 
[out]  gradx  x component of the gradient 
[out]  grady  y component of the gradient 
[out]  gradz  z component of the gradient 
This is the same as the previous function, except that the components of the gradients of the sum in the x, y, and z directions are computed. This routine requires constant memory and thus never throws an exception.
Definition at line 262 of file SphericalHarmonic.hpp.

inline 
Create a CircularEngine to allow the efficient evaluation of several points on a circle of latitude.
[in]  p  the radius of the circle. 
[in]  z  the height of the circle above the equatorial plane. 
[in]  gradp  if true the returned object will be able to compute the gradient of the sum. 
std::bad_alloc  if the memory for the CircularEngine can't be allocated. 
SphericalHarmonic::operator()() exchanges the order of the sums in the definition, i.e., ∑_{n = 0..N} ∑_{m = 0..n} becomes ∑_{m = 0..N} ∑_{n = m..N}. SphericalHarmonic::Circle performs the inner sum over degree n (which entails about N^{2} operations). Calling CircularEngine::operator()() on the returned object performs the outer sum over the order m (about N operations).
Here's an example of computing the spherical sum at a sequence of longitudes without using a CircularEngine object
Here is the same calculation done using a CircularEngine object. This will be about N/2 times faster.
Definition at line 329 of file SphericalHarmonic.hpp.
Referenced by GeographicLib::GravityModel::Circle().

inline 
Definition at line 353 of file SphericalHarmonic.hpp.
Referenced by GeographicLib::GravityModel::GravityModel().