Classes | Public Types | Static Public Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Friends | List of all members
GeographicLib::SphericalEngine Class Reference

The evaluation engine for SphericalHarmonic. More...

#include <SphericalEngine.hpp>

Classes

class  coeff
 Package up coefficients for SphericalEngine. More...
 

Public Types

enum  normalization { FULL, SCHMIDT }
 

Static Public Member Functions

template<bool gradp, normalization norm, int L>
static CircularEngine Circle (const coeff c[], const real f[], real p, real z, real a)
 
static void ClearRootTable ()
 
static void RootTable (int N)
 
template<bool gradp, normalization norm, int L>
static Math::real Value (const coeff c[], const real f[], real x, real y, real z, real a, real &gradx, real &grady, real &gradz)
 

Private Types

typedef Math::real real
 

Private Member Functions

 SphericalEngine ()
 

Static Private Member Functions

static real eps ()
 
static real scale ()
 
static std::vector< real > & sqrttable ()
 

Friends

class CircularEngine
 

Detailed Description

The evaluation engine for SphericalHarmonic.

This serves as the backend to SphericalHarmonic, SphericalHarmonic1, and SphericalHarmonic2. Typically end-users will not have to access this class directly.

See SphericalEngine.cpp for more information on the implementation.

Example of use:

// Example of using the GeographicLib::SphericalEngine class
#include <iostream>
#include <exception>
#include <vector>
using namespace std;
using namespace GeographicLib;
int main() {
// See also example-SphericHarmonic.cpp
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);
c[0] = SphericalEngine::coeff(C, S, N);
double f[] = {1};
double x = 2, y = 3, z = 1, a = 1;
double v, vx, vy, vz;
v = SphericalEngine::Value<true, SphericalEngine::FULL, 1>
(c, f, x, y, z, a, vx, vy, vz);
cout << v << " " << vx << " " << vy << " " << vz << "\n";
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}

Definition at line 40 of file SphericalEngine.hpp.

Member Typedef Documentation

◆ real

Definition at line 42 of file SphericalEngine.hpp.

Member Enumeration Documentation

◆ normalization

Supported normalizations for associated Legendre polynomials.

Enumerator
FULL 

Fully normalized associated Legendre polynomials. See SphericalHarmonic::FULL for documentation.

SCHMIDT 

Schmidt semi-normalized associated Legendre polynomials. See SphericalHarmonic::SCHMIDT for documentation.

Definition at line 70 of file SphericalEngine.hpp.

Constructor & Destructor Documentation

◆ SphericalEngine()

GeographicLib::SphericalEngine::SphericalEngine ( )
private

Member Function Documentation

◆ Circle()

template<bool gradp, SphericalEngine::normalization norm, int L>
CircularEngine GeographicLib::SphericalEngine::Circle ( const coeff  c[],
const real  f[],
real  p,
real  z,
real  a 
)
static

Create a CircularEngine object

Template Parameters
gradpshould the gradient be calculated.
normthe normalization for the associated Legendre polynomials.
Lthe number of terms in the coefficients.
Parameters
[in]can array of coeff objects.
[in]farray of coefficient multipliers. f[0] should be 1.
[in]pthe radius of the circle = sqrt(x2 + y2).
[in]zthe height of the circle.
[in]athe normalizing radius.
Exceptions
std::bad_allocif the memory for the CircularEngine can't be allocated.
Returns
the CircularEngine object.

If you need to evaluate the spherical harmonic sum for several points with constant f, p = sqrt(x2 + y2), z, and a, it is more efficient to construct call SphericalEngine::Circle to give a CircularEngine object and then call CircularEngine::operator()() with arguments x/p and y/p.

Definition at line 298 of file SphericalEngine.cpp.

◆ ClearRootTable()

static void GeographicLib::SphericalEngine::ClearRootTable ( )
inlinestatic

Clear the static table of square roots and release the memory. Call this only when you are sure you no longer will be using SphericalEngine. Your program will crash if you call SphericalEngine after calling this routine.

Warning
It's safest not to call this routine at all. (The space used by the table is modest.)

Definition at line 365 of file SphericalEngine.hpp.

◆ eps()

static real GeographicLib::SphericalEngine::eps ( )
inlinestaticprivate

Definition at line 60 of file SphericalEngine.hpp.

◆ RootTable()

void GeographicLib::SphericalEngine::RootTable ( int  N)
static

Check that the static table of square roots is big enough and enlarge it if necessary.

Parameters
[in]Nthe maximum degree to be used in SphericalEngine.
Exceptions
std::bad_allocif the memory for the square root table can't be allocated.

Typically, there's no need for an end-user to call this routine, because the constructors for SphericalEngine::coeff do so. However, since this updates a static table, there's a possible race condition in a multi-threaded environment. Because this routine does nothing if the table is already large enough, one way to avoid race conditions is to call this routine at program start up (when it's still single threaded), supplying the largest degree that your program will use. E.g.,

suffices to accommodate extant magnetic and gravity models.

Definition at line 376 of file SphericalEngine.cpp.

◆ scale()

static real GeographicLib::SphericalEngine::scale ( )
inlinestaticprivate

Definition at line 49 of file SphericalEngine.hpp.

◆ sqrttable()

vector< Math::real > & GeographicLib::SphericalEngine::sqrttable ( )
staticprivate

Definition at line 147 of file SphericalEngine.cpp.

◆ Value()

template<bool gradp, SphericalEngine::normalization norm, int L>
Math::real GeographicLib::SphericalEngine::Value ( const coeff  c[],
const real  f[],
real  x,
real  y,
real  z,
real  a,
real gradx,
real grady,
real gradz 
)
static

Evaluate a spherical harmonic sum and its gradient.

Template Parameters
gradpshould the gradient be calculated.
normthe normalization for the associated Legendre polynomials.
Lthe number of terms in the coefficients.
Parameters
[in]can array of coeff objects.
[in]farray of coefficient multipliers. f[0] should be 1.
[in]xthe x component of the cartesian position.
[in]ythe y component of the cartesian position.
[in]zthe z component of the cartesian position.
[in]athe normalizing radius.
[out]gradxthe x component of the gradient.
[out]gradythe y component of the gradient.
[out]gradzthe z component of the gradient.
Returns
the spherical harmonic sum.

See the SphericalHarmonic class for the definition of the sum. The coefficients used by this function are, for example, c[0].Cv + f[1] * c[1].Cv + ... + f[L−1] * c[L−1].Cv. (Note that f[0] is not used.) The upper limits on the sum are determined by c[0].nmx() and c[0].mmx(); these limits apply to all the components of the coefficients. The parameters gradp, norm, and L are template parameters, to allow more optimization to be done at compile time.

Clenshaw summation is used which permits the evaluation of the sum without the need to allocate temporary arrays. Thus this function never throws an exception.

Definition at line 153 of file SphericalEngine.cpp.

Friends And Related Function Documentation

◆ CircularEngine

friend class CircularEngine
friend

Definition at line 44 of file SphericalEngine.hpp.


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


gtsam
Author(s):
autogenerated on Tue Jul 4 2023 02:46:12