GeographicLib::CircularEngine Class Reference

Spherical harmonic sums for a circle. More...

#include <CircularEngine.hpp>

Public Member Functions
	CircularEngine ()
Math::real	operator() (real lon) const
Math::real	operator() (real lon, real &gradx, real &grady, real &gradz) const
Math::real	operator() (real sinlon, real coslon) const
Math::real	operator() (real sinlon, real coslon, real &gradx, real &grady, real &gradz) const

Private Types
enum	normalization { FULL = SphericalEngine::FULL, SCHMIDT = SphericalEngine::SCHMIDT }
typedef Math::real	real

Private Member Functions
	CircularEngine (int M, bool gradp, unsigned norm, real a, real r, real u, real t)
void	SetCoeff (int m, real wc, real ws)
void	SetCoeff (int m, real wc, real ws, real wrc, real wrs, real wtc, real wts)
Math::real	Value (bool gradp, real sl, real cl, real &gradx, real &grady, real &gradz) const

Private Attributes
real	_a
bool	_gradp
int	_M
unsigned	_norm
real	_q
real	_r
real	_t
real	_u
real	_uq
real	_uq2
std::vector< real >	_wc
std::vector< real >	_wrc
std::vector< real >	_wrs
std::vector< real >	_ws
std::vector< real >	_wtc
std::vector< real >	_wts

Friends
class	SphericalEngine

Detailed Description

Spherical harmonic sums for a circle.

The class is a companion to SphericalEngine. If the results of a spherical harmonic sum are needed for several points on a circle of constant latitude lat and height h, then SphericalEngine::Circle can compute the inner sum, which is independent of longitude lon, and produce a CircularEngine object. CircularEngine::operator()() can then be used to perform the outer sum for particular vales of lon. This can lead to substantial improvements in computational speed for high degree sum (approximately by a factor of N / 2 where N is the maximum degree).

CircularEngine is tightly linked to the internals of SphericalEngine. For that reason, the constructor for this class is private. Use SphericalHarmonic::Circle, SphericalHarmonic1::Circle, and SphericalHarmonic2::Circle to create instances of this class.

CircularEngine stores the coefficients needed to allow the summation over order to be performed in 2 or 6 vectors of length M + 1 (depending on whether gradients are to be calculated). For this reason the constructor may throw a std::bad_alloc exception.

Example of use:

// Example of using the GeographicLib::CircularEngine class
 
#include <iostream>
#include <exception>
#include <vector>
#include <GeographicLib/CircularEngine.hpp>
#include <GeographicLib/SphericalHarmonic.hpp>
 
using namespace std;
using namespace GeographicLib;
 
int main() {
  // This computes the same value as example-SphericalHarmonic.cpp using a
  // CircularEngine (which will be faster if many values on a circle of
  // latitude are to be found).
  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, p = Math::hypot(x, y);
    CircularEngine circ = h.Circle(p, z, true);
    double v, vx, vy, vz;
    v = circ(x/p, y/p, vx, vy, vz);
    cout << v << " " << vx << " " << vy << " " << vz << "\n";
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Definition at line 52 of file CircularEngine.hpp.

Member Typedef Documentation

real

typedef Math::real GeographicLib::CircularEngine::real

private

Definition at line 54 of file CircularEngine.hpp.

Member Enumeration Documentation

normalization

enum GeographicLib::CircularEngine::normalization

private

Enumerator
FULL
SCHMIDT

Definition at line 55 of file CircularEngine.hpp.

Constructor & Destructor Documentation

CircularEngine() [1/2]

GeographicLib::CircularEngine::CircularEngine ( int  M, bool  gradp, unsigned  norm, real  a, real  r, real  u, real  t  )

inlineprivate

Definition at line 70 of file CircularEngine.hpp.

CircularEngine() [2/2]

GeographicLib::CircularEngine::CircularEngine ( )

inline

A default constructor. CircularEngine::operator()() on the resulting object returns zero. The resulting object can be assigned to the result of SphericalHarmonic::Circle.

Definition at line 110 of file CircularEngine.hpp.

Member Function Documentation

operator()() [1/4]

Math::real GeographicLib::CircularEngine::operator() ( real  lon ) const

inline

Evaluate the sum for a particular longitude.

Parameters

[in]

lon

the longitude (degrees).

Returns

V the value of the sum.

Definition at line 139 of file CircularEngine.hpp.

operator()() [2/4]

Math::real GeographicLib::CircularEngine::operator() ( real  lon, real &  gradx, real &  grady, real &  gradz  ) const

inline

Evaluate the sum and its gradient for a particular longitude.

Parameters

[in]	lon	the longitude (degrees).
[out]	gradx	x component of the gradient.
[out]	grady	y component of the gradient.
[out]	gradz	z component of the gradient.

Returns

V the value of the sum.

The gradients will only be computed if the CircularEngine object was created with this capability (e.g., via gradp = true in SphericalHarmonic::Circle). If not, gradx, etc., will not be touched.

Definition at line 181 of file CircularEngine.hpp.

operator()() [3/4]

Math::real GeographicLib::CircularEngine::operator() ( real  sinlon, real  coslon  ) const

inline

Evaluate the sum for a particular longitude given in terms of its sine and cosine.

Parameters

[in]	sinlon	the sine of the longitude.
[in]	coslon	the cosine of the longitude.

Returns

V the value of the sum.

The arguments must satisfy sinlon² + coslon² = 1.

Definition at line 128 of file CircularEngine.hpp.

operator()() [4/4]

Math::real GeographicLib::CircularEngine::operator() ( real  sinlon, real  coslon, real &  gradx, real &  grady, real &  gradz  ) const

inline

Evaluate the sum and its gradient for a particular longitude given in terms of its sine and cosine.

Parameters

[in]	sinlon	the sine of the longitude.
[in]	coslon	the cosine of the longitude.
[out]	gradx	x component of the gradient.
[out]	grady	y component of the gradient.
[out]	gradz	z component of the gradient.

Returns

V the value of the sum.

The gradients will only be computed if the CircularEngine object was created with this capability (e.g., via gradp = true in SphericalHarmonic::Circle). If not, gradx, etc., will not be touched. The arguments must satisfy sinlon² + coslon² = 1.

Definition at line 162 of file CircularEngine.hpp.

SetCoeff() [1/2]

void GeographicLib::CircularEngine::SetCoeff ( int  m, real  wc, real  ws  )

inlineprivate

Definition at line 91 of file CircularEngine.hpp.

SetCoeff() [2/2]

void GeographicLib::CircularEngine::SetCoeff ( int  m, real  wc, real  ws, real  wrc, real  wrs, real  wtc, real  wts  )

inlineprivate

Definition at line 94 of file CircularEngine.hpp.

Value()

Math::real GeographicLib::CircularEngine::Value ( bool  gradp, real  sl, real  cl, real &  gradx, real &  grady, real &  gradz  ) const

private

Definition at line 16 of file src/CircularEngine.cpp.

Friends And Related Function Documentation

SphericalEngine

friend class SphericalEngine

friend

Definition at line 69 of file CircularEngine.hpp.

Member Data Documentation

_a

real GeographicLib::CircularEngine::_a

private

Definition at line 62 of file CircularEngine.hpp.

_gradp

bool GeographicLib::CircularEngine::_gradp

private

Definition at line 60 of file CircularEngine.hpp.

_M

int GeographicLib::CircularEngine::_M

private

Definition at line 59 of file CircularEngine.hpp.

_norm

unsigned GeographicLib::CircularEngine::_norm

private

Definition at line 61 of file CircularEngine.hpp.

_q

real GeographicLib::CircularEngine::_q

private

Definition at line 64 of file CircularEngine.hpp.

_r

real GeographicLib::CircularEngine::_r

private

Definition at line 62 of file CircularEngine.hpp.

_t

real GeographicLib::CircularEngine::_t

private

Definition at line 62 of file CircularEngine.hpp.

_u

real GeographicLib::CircularEngine::_u

private

Definition at line 62 of file CircularEngine.hpp.

_uq

real GeographicLib::CircularEngine::_uq

private

Definition at line 64 of file CircularEngine.hpp.

_uq2

real GeographicLib::CircularEngine::_uq2

private

Definition at line 64 of file CircularEngine.hpp.

_wc

std::vector<real> GeographicLib::CircularEngine::_wc

private

Definition at line 63 of file CircularEngine.hpp.

_wrc

std::vector<real> GeographicLib::CircularEngine::_wrc

private

Definition at line 63 of file CircularEngine.hpp.

_wrs

std::vector<real> GeographicLib::CircularEngine::_wrs

private

Definition at line 63 of file CircularEngine.hpp.

_ws

std::vector<real> GeographicLib::CircularEngine::_ws

private

Definition at line 63 of file CircularEngine.hpp.

_wtc

std::vector<real> GeographicLib::CircularEngine::_wtc

private

Definition at line 63 of file CircularEngine.hpp.

_wts

std::vector<real> GeographicLib::CircularEngine::_wts

private

Definition at line 63 of file CircularEngine.hpp.

---

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

• CircularEngine.hpp
• src/CircularEngine.cpp