GeographicLib  1.35
Public Member Functions | Friends | List of all members
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 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 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 119 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 137 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 148 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 171 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 190 of file CircularEngine.hpp.

Friends And Related Function Documentation

friend class SphericalEngine
friend

Definition at line 76 of file CircularEngine.hpp.

friend class GravityCircle
friend

Definition at line 77 of file CircularEngine.hpp.

friend class MagneticCircle
friend

Definition at line 78 of file CircularEngine.hpp.


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