GeographicLib  1.37
GeographicLib::CircularEngine Class Reference

Spherical harmonic sums for a circle. More...

#include <GeographicLib/CircularEngine.hpp>

## Public Member Functions

CircularEngine ()

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

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

## 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 std::bad_alloc exception.

Example of use:

// Example of using the GeographicLib::CircularEngine class
#include <iostream>
#include <exception>
#include <vector>
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;
}

Definition at line 52 of file CircularEngine.hpp.

## 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
inline

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

Parameters
 [in] coslon the cosine of the longitude. [in] sinlon the 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
inline

Evaluate the sum for a particular longitude.

Parameters
 [in] lon the 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
inline

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

Parameters
 [in] coslon the cosine of the longitude. [in] sinlon the sine 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 coslon2 + sinlon2 = 1.

Definition at line 172 of file CircularEngine.hpp.

inline

Evaluate the sum and its gradient for a particular longitude.

Parameters
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: