GeographicLib 2.3

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 sinlon, real coslon) const
Math::real | operator() (real lon) const
Math::real | operator() (real sinlon, real coslon, real &gradx, real &grady, real &gradz) const
Math::real | operator() (real lon, real &gradx, real &grady, real &gradz) const

## 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 {
using std::hypot;
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 = 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;
}
}
main
int main(int argc, const char *const argv[])
Definition: CartConvert.cpp:29
CircularEngine.hpp
Header for GeographicLib::CircularEngine class.
SphericalHarmonic.hpp
Header for GeographicLib::SphericalHarmonic class.
GeographicLib::CircularEngine::CircularEngine
CircularEngine()
Definition: CircularEngine.hpp:110
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812

Definition at line 52 of file CircularEngine.hpp.

## Constructor & Destructor Documentation

## ◆ CircularEngine()

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 | 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 sinlon2 + coslon2 = 1.

Definition at line 128 of file CircularEngine.hpp.

## ◆ operator()() [2/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.

References GeographicLib::Math::sincosd().

## ◆ operator()() [3/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 sinlon2 + coslon2 = 1.

Definition at line 162 of file CircularEngine.hpp.

## ◆ operator()() [4/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.

References GeographicLib::Math::sincosd().

## Friends And Related Function Documentation

## ◆ SphericalEngine

friend class SphericalEngine
| friend

Definition at line 69 of file CircularEngine.hpp.

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

- CircularEngine.hpp
- CircularEngine.cpp