.NET wrapper for GeographicLib::SphericalHarmonic. More...

#include <SphericalHarmonic.h>

Public Types
enum	Normalization { Normalization::FULL, Normalization::SCHMIDT }

Public Member Functions
CircularEngine	Circle (double p, double z, bool gradp)

SphericalCoefficients	Coefficients ()

double	HarmonicSum (double x, double y, double z)

double	HarmonicSum (double x, double y, double z, [System::Runtime::InteropServices::Out] double% gradx, [System::Runtime::InteropServices::Out] double% grady, [System::Runtime::InteropServices::Out] double% gradz)

	SphericalHarmonic (array< double >^ C, array< double >^ S, int N, double a, Normalization norm)

	SphericalHarmonic (array< double >^ C, array< double >^ S, int N, int nmx, int mmx, double a, Normalization norm)

	~SphericalHarmonic ()

Private Member Functions
	!SphericalHarmonic ()

Private Attributes
std::vector< double > *	m_C

const GeographicLib::SphericalHarmonic *	m_pSphericalHarmonic

std::vector< double > *	m_S

Detailed Description

.NET wrapper for GeographicLib::SphericalHarmonic.

This class allows .NET applications to access GeographicLib::SphericalHarmonic.

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

p² = x² + y²,
r² = p² + z²,
q = a/r,
θ = atan2(p, z) = the spherical colatitude,
λ = atan2(y, x) = the longitude.
P_nm(t) is the associated Legendre polynomial of degree n and order m.

Two normalizations are supported for P_nm

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 GeographicLib::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). (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).

C# Example:

using System;
using NETGeographicLib;
 
namespace example_SphericalHarmonic
{
    class Program
    {
        static void Main(string[] args)
        {
            try {
                int N = 3;                  // The maximum degree
                double[] ca = {10, 9, 8, 7, 6, 5, 4, 3, 2, 1}; // cosine coefficients
                double[] sa = {6, 5, 4, 3, 2, 1}; // sine coefficients
                double a = 1;
                SphericalHarmonic h = new SphericalHarmonic(ca, sa, N, a, SphericalHarmonic.Normalization.SCHMIDT);
                double x = 2, y = 3, z = 1;
                double v, vx, vy, vz;
                v = h.HarmonicSum(x, y, z, out vx, out vy, out vz);
                Console.WriteLine(String.Format("{0} {1} {2} {3}", v, vx, vy, vz));
            }
            catch (GeographicErr e) {
                Console.WriteLine(String.Format("Caught exception: {0}", e.Message));
            }
        }
    }
}

Managed C++ Example:

// 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;
  }
}

Visual Basic Example:

Imports NETGeographicLib
 
Module example_SphericalHarmonic
    Sub Main()
        Try
            Dim N As Integer = 3 ' The maximum degree
            Dim ca As Double() = {10, 9, 8, 7, 6, 5, 4, 3, 2, 1} ' cosine coefficients
            Dim sa As Double() = {6, 5, 4, 3, 2, 1} ' sine coefficients
            Dim a As Double = 1
            Dim h As SphericalHarmonic = New SphericalHarmonic(ca, sa, N, a, SphericalHarmonic.Normalization.SCHMIDT)
            Dim x As Double = 2, y = 3, z = 1
            Dim vx, vy, vz As Double
            Dim v As Double = h.HarmonicSum(x, y, z, vx, vy, vz)
            Console.WriteLine(String.Format("{0} {1} {2} {3}", v, vx, vy, vz))
        Catch ex As GeographicErr
            Console.WriteLine(String.Format("Caught exception: {0}", ex.Message))
        End Try
    End Sub
End Module

INTERFACE DIFFERENCES:
This class replaces the GeographicLib::SphericalHarmonic::operator() with HarmonicSum.

Coefficients returns a SphericalCoefficients object.

The Normalization parameter in the constructors is passed in as an enumeration rather than an unsigned.

Definition at line 75 of file SphericalHarmonic.h.

Member Enumeration Documentation

◆ Normalization

enum NETGeographicLib::SphericalHarmonic::Normalization

strong

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 semi-normalized 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 90 of file SphericalHarmonic.h.

Constructor & Destructor Documentation

◆ !SphericalHarmonic()

SphericalHarmonic::!SphericalHarmonic ( )

private

Definition at line 23 of file SphericalHarmonic.cpp.

◆ SphericalHarmonic() [1/2]

SphericalHarmonic::SphericalHarmonic	(	array< double >^	C,
		array< double >^	S,
		int	N,
		double	a,
		Normalization	norm
	)

Constructor with a full set of coefficients specified.

Parameters

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

Exceptions

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 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: C₀₀, C₁₀, C₂₀, C₃₀, C₁₁, C₂₁, C₃₁, C₂₂, C₃₂, C₃₃. 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₁₁

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 43 of file SphericalHarmonic.cpp.

◆ SphericalHarmonic() [2/2]

SphericalHarmonic::SphericalHarmonic	(	array< double >^	C,
		array< double >^	S,
		int	N,
		int	nmx,
		int	mmx,
		double	a,
		Normalization	norm
	)

Constructor with a subset of coefficients specified.

Parameters

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

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 71 of file SphericalHarmonic.cpp.

◆ ~SphericalHarmonic()

NETGeographicLib::SphericalHarmonic::~SphericalHarmonic ( )

inline

The destructor calls the finalizer

Definition at line 208 of file SphericalHarmonic.h.

Member Function Documentation

◆ Circle()

CircularEngine SphericalHarmonic::Circle	(	double	p,
		double	z,
		bool	gradp
	)

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 N² operations). Calling CircularEngine::operator()() on the returned object performs the outer sum over the order m (about N operations).

Definition at line 118 of file SphericalHarmonic.cpp.

◆ Coefficients()

SphericalCoefficients SphericalHarmonic::Coefficients ( )

Returns: the zeroth SphericalCoefficients object.

Definition at line 124 of file SphericalHarmonic.cpp.

◆ HarmonicSum() [1/2]

double SphericalHarmonic::HarmonicSum	(	double	x,
		double	y,
		double	z
	)

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 100 of file SphericalHarmonic.cpp.

◆ HarmonicSum() [2/2]

double SphericalHarmonic::HarmonicSum	(	double	x,
		double	y,
		double	z,
		[System::Runtime::InteropServices::Out] double%	gradx,
		[System::Runtime::InteropServices::Out] double%	grady,
		[System::Runtime::InteropServices::Out] double%	gradz
	)

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 106 of file SphericalHarmonic.cpp.

Member Data Documentation

◆ m_C

std::vector<double>* NETGeographicLib::SphericalHarmonic::m_C

private

Definition at line 85 of file SphericalHarmonic.h.

◆ m_pSphericalHarmonic

const GeographicLib::SphericalHarmonic* NETGeographicLib::SphericalHarmonic::m_pSphericalHarmonic

private

Definition at line 79 of file SphericalHarmonic.h.

◆ m_S

std::vector<double> * NETGeographicLib::SphericalHarmonic::m_S

private

Definition at line 85 of file SphericalHarmonic.h.

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

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ Normalization

Constructor & Destructor Documentation

◆ !SphericalHarmonic()

◆ SphericalHarmonic() [1/2]

◆ SphericalHarmonic() [2/2]

◆ ~SphericalHarmonic()

Member Function Documentation

◆ Circle()

◆ Coefficients()

◆ HarmonicSum() [1/2]

◆ HarmonicSum() [2/2]

Member Data Documentation

◆ m_C

◆ m_pSphericalHarmonic

◆ m_S