GeographicLib: GeographicLib::SphericalHarmonic Class Reference

GeographicLib 2.6

Loading...
Searching...
No Matches
GeographicLib::SphericalHarmonic Class Reference

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

## Detailed Description

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

- p2 = x2 + y2,
- r2 = p2 + z2,
- q = a/r,
- θ = atan2(p, z) = the spherical colatitude,
- λ = atan2(y, x) = the longitude.
- Pnm(t) is the associated Legendre polynomial of degree n and order m.

Two normalizations are supported for Pnm

- fully normalized denoted by SphericalHarmonic::FULL.
- Schmidt semi-normalized denoted by SphericalHarmonic::SCHMIDT.

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:

- C. W. Clenshaw, A note on the summation of Chebyshev series, Math. Tables Aids Comput. 9(51), 118–120 (1955).
- R. E. Deakin, Derivatives of the earth's potentials, Geomatics Research Australasia 68, 31–60, (June 1998).
- W. A. Heiskanen and H. Moritz, Physical Geodesy, (Freeman, San Francisco, 1967). https://archive.org/details/HeiskanenMoritz1967PhysicalGeodesy (See Sec. 1-14, for a definition of Pbar.)
- S. A. Holmes and W. E. Featherstone, A unified approach to the Clenshaw summation and the recursive computation of very high degree and order normalised associated Legendre functions, J. Geodesy 76(5), 279–299 (2002).
- C. C. Tscherning and K. Poder, Some geodetic applications of Clenshaw summation, Boll. Geod. Sci. Aff. 41(4), 349–375 (1982).

Example of use:

// Example of using the GeographicLib::SphericalHarmonic class
#include <iostream>
#include <exception>
#include <vector>
#include <GeographicLib/SphericalHarmonic.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
int N = 3; // The maxium degree
double ca[] = {10, 9, 8, 7, 6, 5, 4, 3, 2, 1}; // cosine coefficients
vector<double> C(ca, ca + (N + 1) * (N + 2) / 2);
double sa[] = {6, 5, 4, 3, 2, 1}; // sine coefficients
vector<double> S(sa, sa + N * (N + 1) / 2);
double a = 1;
SphericalHarmonic h(C, S, N, a);
double x = 2, y = 3, z = 1;
double v, vx, vy, vz;
v = h(x, y, z, vx, vy, vz);
cout << v << " " << vx << " " << vy << " " << vz << "\n";
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition Cart3Convert.cpp:52
SphericalHarmonic.hpp
Header for GeographicLib::SphericalHarmonic class.
GeographicLib::SphericalHarmonic
Spherical harmonic series.
Definition SphericalHarmonic.hpp:71
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

Definition at line 71 of file SphericalHarmonic.hpp.

## Member Enumeration Documentation

## ◆ normalization

enum GeographicLib::SphericalHarmonic::normalization

Supported normalizations for the associated Legendre polynomials.

Enumerator
FULL | Fully normalized associated Legendre polynomials. These are defined by Pnmfull(z) = (−1)m sqrt(k (2n + 1) (n − m)! / (n + m)!) Pnm(z), where Pnm(z) is Ferrers function (also known as the Legendre function on the cut or the associated Legendre polynomial) https://dlmf.nist.gov/14.7.E10 and k = 1 for m = 0 and k = 2 otherwise. The mean squared value of Pnmfull(cosθ) cos(mλ) and Pnmfull(cosθ) sin(mλ) over the sphere is 1.
SCHMIDT | Schmidt semi-normalized associated Legendre polynomials. These are defined by Pnmschmidt(z) = (−1)m sqrt(k (n − m)! / (n + m)!) Pnm(z), where Pnm(z) is Ferrers function (also known as the Legendre function on the cut or the associated Legendre polynomial) https://dlmf.nist.gov/14.7.E10 and k = 1 for m = 0 and k = 2 otherwise. The mean squared value of Pnmschmidt(cosθ) cos(mλ) and Pnmschmidt(cosθ) sin(mλ) over the sphere is 1/(2n + 1).

Definition at line 76 of file SphericalHarmonic.hpp.

## Constructor & Destructor Documentation

## ◆ SphericalHarmonic() [1/3]

GeographicLib::SphericalHarmonic::SphericalHarmonic | ( | const std::vector< real > & | C,
|  | const std::vector< real > & | S,
|  | int | N,
|  | real | a,
|  | unsigned | norm = FULL )
| inline

Constructor with a full set of coefficients specified.

Parameters

  [in] | C | the coefficients Cnm.
  [in] | S | the coefficients Snm.
  [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.

Exceptions

  GeographicErr | if N does not satisfy N ≥ −1.
  GeographicErr | if C or S is not big enough to hold the coefficients.

The coefficients Cnm and Snm are stored in the one-dimensional vectors C and S which must contain (N + 1)(N + 2)/2 and N (N + 1)/2 elements, respectively, stored in "column-major" order. Thus for N = 3, the order would be: C00, C10, C20, C30, C11, C21, C31, C22, C32, C33. 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 S11

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 169 of file SphericalHarmonic.hpp.

References FULL.

## ◆ SphericalHarmonic() [2/3]

GeographicLib::SphericalHarmonic::SphericalHarmonic | ( | const std::vector< real > & | C,
|  | const std::vector< real > & | S,
|  | int | N,
|  | int | nmx,
|  | int | mmx,
|  | real | a,
|  | unsigned | norm = FULL )
| inline

Constructor with a subset of coefficients specified.

Parameters

  [in] | C | the coefficients Cnm.
  [in] | S | the coefficients Snm.
  [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.

Exceptions

  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 200 of file SphericalHarmonic.hpp.

References FULL.

## ◆ SphericalHarmonic() [3/3]

GeographicLib::SphericalHarmonic::SphericalHarmonic | ( |  | ) |
| 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 213 of file SphericalHarmonic.hpp.

## Member Function Documentation

## ◆ operator()() [1/2]

Math::real GeographicLib::SphericalHarmonic::operator() | ( | real | x,
|  | real | y,
|  | real | z ) const
| inline

Compute the spherical harmonic sum.

Parameters

  [in] | x | cartesian coordinate.
  [in] | y | cartesian coordinate.
  [in] | z | cartesian coordinate.

Returns
  V the spherical harmonic sum.

This routine requires constant memory and thus never throws an exception.

Definition at line 226 of file SphericalHarmonic.hpp.

References FULL, SCHMIDT, and GeographicLib::SphericalEngine::Value().

## ◆ operator()() [2/2]

Math::real GeographicLib::SphericalHarmonic::operator() | ( | real | x,
|  | real | y,
|  | real | z,
|  | real & | gradx,
|  | real & | grady,
|  | real & | gradz ) const
| inline

Compute a spherical harmonic sum and its gradient.

Parameters

  [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

Returns
  V the spherical harmonic sum.

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 260 of file SphericalHarmonic.hpp.

References FULL, SCHMIDT, and GeographicLib::SphericalEngine::Value().

## ◆ Circle()

CircularEngine GeographicLib::SphericalHarmonic::Circle | ( | real | p,
|  | real | z,
|  | bool | gradp ) const
| inline

Create a CircularEngine to allow the efficient evaluation of several points on a circle of latitude.

Parameters

  [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.

Exceptions

  std::bad_alloc | if the memory for the CircularEngine can't be allocated.

Returns
  the CircularEngine object.

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 N2 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

SphericalHarmonic h(...); // Create the SphericalHarmonic object
double r = 2, lat = 33, lon0 = 44, dlon = 0.01;
double
phi = lat * Math::degree<double>(),
z = r * sin(phi), p = r * cos(phi);
for (int i = 0; i <= 100; ++i) {
real
lon = lon0 + i * dlon,
lam = lon * Math::degree<double>();
std::cout << lon << " " << h(p * cos(lam), p * sin(lam), z) << "\n";
}
GeographicLib::Math::degree
static T degree()
Definition Math.hpp:197
GeographicLib::SphericalHarmonic::SphericalHarmonic
SphericalHarmonic(const std::vector< real > &C, const std::vector< real > &S, int N, real a, unsigned norm=FULL)
Definition SphericalHarmonic.hpp:169

Here is the same calculation done using a CircularEngine object. This will be about N/2 times faster.

SphericalHarmonic h(...); // Create the SphericalHarmonic object
double r = 2, lat = 33, lon0 = 44, dlon = 0.01;
double
phi = lat * Math::degree<double>(),
z = r * sin(phi), p = r * cos(phi);
CircularEngine c(h(p, z, false)); // Create the CircularEngine object
for (int i = 0; i <= 100; ++i) {
real
lon = lon0 + i * dlon;
std::cout << lon << " " << c(lon) << "\n";
}
GeographicLib::CircularEngine
Spherical harmonic sums for a circle.
Definition CircularEngine.hpp:52

Definition at line 328 of file SphericalHarmonic.hpp.

References GeographicLib::SphericalEngine::Circle(), FULL, and SCHMIDT.

## ◆ Coefficients()

const SphericalEngine::coeff & GeographicLib::SphericalHarmonic::Coefficients | ( |  | ) | const
| inline

Returns
  the zeroth SphericalEngine::coeff object.

Definition at line 352 of file SphericalHarmonic.hpp.

The documentation for this class was generated from the following file:

- SphericalHarmonic.hpp