NETGeographicLib  1.43
Public Types | Public Member Functions | List of all members
NETGeographicLib::SphericalHarmonic Class Reference

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

#include <NETGeographicLib/SphericalHarmonic.h>

Public Types

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

Public Member Functions

 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 ()
 
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)
 
CircularEngineCircle (double p, double z, bool gradp)
 
SphericalCoefficientsCoefficients ()
 

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

Two normalizations are supported for Pnm

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# Example:

using System;
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:

using namespace System;
using namespace NETGeographicLib;
int main(array<System::String ^> ^/*args*/)
{
try {
int N = 3; // The maximum degree
array<double>^ ca = {10, 9, 8, 7, 6, 5, 4, 3, 2, 1}; // cosine coefficients
array<double>^ sa = {6, 5, 4, 3, 2, 1}; // sine coefficients
double a = 1;
double x = 2, y = 3, z = 1;
double v, vx, vy, vz;
v = h->HarmonicSum(x, y, z, vx, vy, 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));
return -1;
}
return 0;
}

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

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) (nm)! / (n + m)!) Pnm(z), where Pnm(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 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 (nm)! / (n + m)!) Pnm(z), where Pnm(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 Pnmschmidt(cosθ) cos(mλ) and Pnmschmidt(cosθ) sin(mλ) over the sphere is 1/(2n + 1).

Definition at line 90 of file SphericalHarmonic.h.

Constructor & Destructor Documentation

◆ SphericalHarmonic() [1/2]

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

Constructor with a full set of coefficients specified.

Parameters
[in]Cthe coefficients Cnm.
[in]Sthe coefficients Snm.
[in]Nthe maximum degree and order of the sum
[in]athe reference radius appearing in the definition of the sum.
[in]normthe normalization for the associated Legendre polynomials, either SphericalHarmonic::full (the default) or SphericalHarmonic::schmidt.
Exceptions
GeographicErrif N does not satisfy N ≥ −1.
GeographicErrif 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 Nm (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.

Referenced by ~SphericalHarmonic().

◆ SphericalHarmonic() [2/2]

NETGeographicLib::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]Cthe coefficients Cnm.
[in]Sthe coefficients Snm.
[in]Nthe degree used to determine the layout of C and S.
[in]nmxthe maximum degree used in the sum. The sum over n is from 0 thru nmx.
[in]mmxthe maximum order used in the sum. The sum over m is from 0 thru min(n, mmx).
[in]athe reference radius appearing in the definition of the sum.
[in]normthe normalization for the associated Legendre polynomials, either SphericalHarmonic::FULL (the default) or SphericalHarmonic::SCHMIDT.
Exceptions
GeographicErrif N, nmx, and mmx do not satisfy Nnmxmmx ≥ −1.
GeographicErrif 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.

◆ ~SphericalHarmonic()

NETGeographicLib::SphericalHarmonic::~SphericalHarmonic ( )
inline

The destructor calls the finalizer

Definition at line 208 of file SphericalHarmonic.h.

References Circle(), Coefficients(), HarmonicSum(), and SphericalHarmonic().

Member Function Documentation

◆ HarmonicSum() [1/2]

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

Compute the spherical harmonic sum.

Parameters
[in]xcartesian coordinate.
[in]ycartesian coordinate.
[in]zcartesian coordinate.
Returns
V the spherical harmonic sum.

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

Referenced by ~SphericalHarmonic().

◆ HarmonicSum() [2/2]

double NETGeographicLib::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]xcartesian coordinate.
[in]ycartesian coordinate.
[in]zcartesian coordinate.
[out]gradxx component of the gradient
[out]gradyy component of the gradient
[out]gradzz 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.

◆ Circle()

CircularEngine ^ NETGeographicLib::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]pthe radius of the circle.
[in]zthe height of the circle above the equatorial plane.
[in]gradpif true the returned object will be able to compute the gradient of the sum.
Exceptions
std::bad_allocif 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..Nm = 0..n becomes ∑m = 0..Nn = 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).

Referenced by ~SphericalHarmonic().

◆ Coefficients()

SphericalCoefficients ^ NETGeographicLib::SphericalHarmonic::Coefficients ( )
Returns
the zeroth SphericalCoefficients object.

Referenced by ~SphericalHarmonic().


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