GeographicLib  1.21
Public Member Functions | Friends
GeographicLib::CircularEngine Class Reference

Spherical Harmonic sums for a circle. More...

#include <GeographicLib/CircularEngine.hpp>

List of all members.

Public Member Functions

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

Friends

class SphericalEngine
class GravityCircle
class MagneticCircle

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 bad_alloc exception.

Example of use:

// Example of using the GeographicLib::CircularEngine class
// $Id: a742c5ccdb47b73fcd599dc1adda36a70450b5a5 $

#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;
  }
  return 0;
}

Constructor & Destructor Documentation

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 120 of file CircularEngine.hpp.


Member Function Documentation

Math::real GeographicLib::CircularEngine::operator() ( real  coslon,
real  sinlon 
) const throw () [inline]

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

Parameters:
[in]coslonthe cosine of the longitude.
[in]sinlonthe sine of the longitude.
Returns:
V the value of the sum.

The arguments must satisfy coslon2 + sinlon2 = 1.

Definition at line 138 of file CircularEngine.hpp.

Math::real GeographicLib::CircularEngine::operator() ( real  lon) const throw () [inline]

Evaluate the sum for a particular longitude.

Parameters:
[in]lonthe longitude (degrees).
Returns:
V the value of the sum.

Definition at line 149 of file CircularEngine.hpp.

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

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

Parameters:
[in]coslonthe cosine of the longitude.
[in]sinlonthe sine of the longitude.
[out]gradxx component of the gradient.
[out]gradyy component of the gradient.
[out]gradzz 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 coslon2 + sinlon2 = 1.

Definition at line 172 of file CircularEngine.hpp.

Math::real GeographicLib::CircularEngine::operator() ( real  lon,
real &  gradx,
real &  grady,
real &  gradz 
) const throw () [inline]

Evaluate the sum and its gradient for a particular longitude.

Parameters:
[in]lonthe longitude (degrees).
[out]gradxx component of the gradient.
[out]gradyy component of the gradient.
[out]gradzz 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 191 of file CircularEngine.hpp.


Friends And Related Function Documentation

friend class SphericalEngine [friend]

Definition at line 77 of file CircularEngine.hpp.

friend class GravityCircle [friend]

Definition at line 78 of file CircularEngine.hpp.

friend class MagneticCircle [friend]

Definition at line 79 of file CircularEngine.hpp.


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