NETGeographicLib::SphericalHarmonic Class Reference

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

#include <NETGeographicLib/SphericalHarmonic.h>

List of all members.

Public Types

enum  Normalization { FULL, 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;
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:

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;
        SphericalHarmonic^ h = gcnew 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, 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

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) 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 (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) 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

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

Referenced by ~SphericalHarmonic().

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

NETGeographicLib::SphericalHarmonic::~SphericalHarmonic (  )  [inline]

The destructor calls the finalizer

Definition at line 208 of file SphericalHarmonic.h.

References SphericalHarmonic().


Member Function Documentation

double NETGeographicLib::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.

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

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] 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).

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

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends

Generated on 6 Oct 2014 for NETGeographicLib by  doxygen 1.6.1