GeographicLib: GeographicLib::Trigfun Class Reference

GeographicLib 2.7

Loading...
Searching...
No Matches
GeographicLib::Trigfun Class Reference

Representing a function by a Fourier series. More...

`#include <GeographicLib/Trigfun.hpp>`

## Public Member Functions
| Trigfun ()
| Trigfun (int n, const std::function< real(real)> &f, bool odd, bool sym, real halfp, bool centerp=false)
| Trigfun (const std::function< real(real)> &f, bool odd, bool sym, real halfp, int nmax=1<< 16, real tol=0, real scale=-1)
| Trigfun (const std::function< real(real, real)> &f, bool odd, bool sym, real halfp, int nmax=1<< 16, real tol=0, real scale=-1)
void | setsecular (real f0)
real | operator() (real x) const
Trigfun | integral () const
Trigfun | inverse (const std::function< real(real)> &fp, int nmax=1<< 16, real tol=0, real scale=-1) const
bool | Odd () const
bool | Symmetric () const
real | HalfPeriod () const
int | NCoeffs () const
real | Max () const
real | HalfRange () const
real | Slope () const

## Detailed Description

Representing a function by a Fourier series.

This class mimic the functionality of Chebfun's 'trig' representation of periodic functions. Key differences are:

- Only odd or even functions are allowed (i.e., only sine of only cosine terms in the Fourier series).
- Can specify that the function has symmetry about the quarter period point so that the Fourier series only includes odd harmonics.
- The integral of a Trigfun is counted as a Trigfun even if it includes a secular term.
- The inverse function of the integral is also a Trigfun (only makes sense if the original function is either strictly positive or strictly negative).

Assuming the half period = h, the function f(x) is represented as follows, here \( = (\pi/h) x\):

- sym = false,
  - odd = true, \( f(x) = C_0 y + \sum_{m = 1}^{M-1} C_m \sin my \);
  - odd = false, \( f(x) = \sum_{m = 0}^{M-1} C_m \cos my \);
- sym = true,
  - odd = true, \( f(x) = \sum_{m = 0}^{M-1} C_m \sin 2(m+\frac12) y \);
  - odd = false, \( f(x) = \sum_{m = 0}^{M-1} C_m \cos 2(m+\frac12) y \).

Here we compute FFTs using the kissfft package https://github.com/mborgerding/kissfft by Mark Borgerding.

Example of use:

// Example of using the GeographicLib::Trigfun class.
#include <iostream>
#include <iomanip>
#include <exception>
#include <GeographicLib/Trigfun.hpp>
using namespace std;
using namespace GeographicLib;
int main(int argc, const char* const argv[]) {
try {
// Approximate 1/sqrt(1 - k2*sin(x)^2) by a Fourier series
double k2 = Math::sq(0.8);
auto f = [k2] (double x) -> double
{ return 1/sqrt(1 - k2 * Math::sq(sin(x))); };
Trigfun tf(f, false, false, Math::pi()/2);
cout << "Number of coefficients: " << tf.NCoeffs() << "\n";
cout << "x tf(x) tf(x)-f(x)\n";
for (int i = 0; i <= 20; ++i) {
double x = i/10.0;
cout << x << " " << tf(x) << " " << tf(x) - f(x) << "\n";
}
}
catch (const std::exception& e) {
std::cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition Cart3Convert.cpp:52
Trigfun.hpp
Header for GeographicLib::Trigfun class.
GeographicLib::Math::sq
static T sq(T x)
Definition Math.hpp:209
GeographicLib::Math::pi
static T pi()
Definition Math.hpp:187
GeographicLib::Trigfun
Representing a function by a Fourier series.
Definition Trigfun.hpp:65
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

Definition at line 65 of file Trigfun.hpp.

## Constructor & Destructor Documentation

## ◆ Trigfun() [1/4]

GeographicLib::Trigfun::Trigfun | ( |  | ) |
| inline

Default constructor specifying with the function f(x) = 0.

Definition at line 271 of file Trigfun.hpp.

## ◆ Trigfun() [2/4]

GeographicLib::Trigfun::Trigfun | ( | int | n,
|  | const std::function< real(real)> & | f,
|  | bool | odd,
|  | bool | sym,
|  | real | halfp,
|  | bool | centerp = false )

Construct a Trigfun with a given number of samples a function.

Parameters

  [in] | n | the number of samples.
  [in] | f | the function.
  [in] | odd | is the function odd? If it's not odd, then it is even.
  [in] | sym | is the function symmetric about the quarter period point (so it contains only odd Fourier harmonics)?
  [in] | halfp | the half period.
  [in] | centerp | whether to sample on a centered grid (default false).

For sym = false, n is the number of samples in a half period, and spacing between the samples is halfp/n. (If centerp = false and oddp = false, the function is, in fact sampled n + 1 times.) The number of points given to the FFT routine is 2n.

For sym = true, n is the number of samples in a quarter period, and spacing between the samples is halfp/(2n). The number of points given to the FFT routine is 4n.

Note
  In order for the FFT method to operate efficiently, n should be the product of a small factors (typically a power of 2).

Warning
  f must be a periodic function and it must be either even or odd. With odd = true and sym = false, the secular term can be set with setsecular().

## ◆ Trigfun() [3/4]

GeographicLib::Trigfun::Trigfun | ( | const std::function< real(real)> & | f,
|  | bool | odd,
|  | bool | sym,
|  | real | halfp,
|  | int | nmax = 1<< 16,
|  | real | tol = 0,
|  | real | scale = -1 )

Construct a Trigfun from a function of one argument.

Parameters

  [in] | f | the function.
  [in] | odd | is the function odd? If it's not odd, then it is even.
  [in] | sym | is the function symmetric about the quarter period point (so it contains only odd Fourier harmonics)?
  [in] | halfp | the half period.
  [in] | nmax | the maximum number of points in a half/quarter period (default 2^16 = 65536).
  [in] | tol | the tolerance, the default value 0 means use the machine epsilon.
  [in] | scale; | if scale is negative (the default), tol sets the error relative to the largest Fourier coefficient. Otherwise, the error is relative to the maximum of the largest Fourier coefficient and scale.

The constructor successively doubles the number of sample points and updating the Fourier coefficients accordingly until the high order coefficients become sufficiently small. At that point Fourier series is truncated discarding some of the trailing coefficients. This mimics the method used by Chebfun. In particular, the method used to truncate the series is taken from Aurentz and L. N. Trefethen, Chopping a Chebyshev series (2017); preprint.

Warning
  f must be a periodic function and it must be either even or odd. With odd = true and sym = false, the secular term can be set with setsecular().

## ◆ Trigfun() [4/4]

GeographicLib::Trigfun::Trigfun | ( | const std::function< real(real, real)> & | f,
|  | bool | odd,
|  | bool | sym,
|  | real | halfp,
|  | int | nmax = 1<< 16,
|  | real | tol = 0,
|  | real | scale = -1 )

Construct a Trigfun from a function of two arguments.

Parameters

  [in] | f | the function.
  [in] | odd | is the function odd? If it's not odd, then it is even.
  [in] | sym | is the function symmetric about the quarter period point (so it contains only odd Fourier harmonics)?
  [in] | halfp | the half period.
  [in] | nmax | the maximum number of points in a half/quarter period (default 2^16 = 65536).
  [in] | tol | the tolerance, the default value 0 means use the machine epsilon.
  [in] | scale; | if scale is negative (the default), tol sets the error relative to the largest Fourier coefficient. Otherwise, the error is relative to the maximum of the largest Fourier coefficient and scale.

This accommodates the situation where the inverse of a Trigfun g is being computed using inverse(). In this case f(x, y0) returns the value y such that g(y) = x. This is typically found using Newton's method which requires a starting guess y0. In the implementation of inverse(), the Fourier representation is successively refined by doubling the number samples. At each stage, a good estimate of the function values at the new points is found by using the current Fourier representation.

Warning
  f must be a periodic function and it must be either even or odd. With odd = true and sym = false, the secular term can be set with setsecular().

## Member Function Documentation

## ◆ setsecular()

void GeographicLib::Trigfun::setsecular | ( | real | f0 | ) |

Set the coefficient of the secular term

Parameters

  [in] | f0 | the value of f(halfp).

Warning
  This throws an error unless odd = true and sym = false.

## ◆ operator()()

real GeographicLib::Trigfun::operator() | ( | real | x | ) | const

Evaluate the Trigfun.

Parameters

  [in] | x | the function argument.

Returns
  the function value f(x).

## ◆ integral()

Trigfun GeographicLib::Trigfun::integral | ( |  | ) | const

The integral of a Trigfun.

Returns
  the integral.

Warning
  The secular term (only present with odd = true and sym = false) is ignored when taking the integral.

## ◆ inverse()

Trigfun GeographicLib::Trigfun::inverse | ( | const std::function< real(real)> & | fp,
|  | int | nmax = 1 << 16,
|  | real | tol = 0,
|  | real | scale = -1 ) const
| inline

Produce a Trigfun for the inverse of f.

Parameters

  [in] | fp | the derivative of f(x).
  [in] | nmax | the maximum number of points in a quarter period (default 2^16 = 65536).
  [in] | tol | the tolerance using in terminating the root finding. tol = 0 (the default) mean to use the machine epsilon.
  [in] | scale; | if scale is negative (the default), tol sets the error relative to the largest Fourier coefficient. Otherwise, the error is relative to the maximum of the largest Fourier coefficient and scale.

Returns
  the Trigfun representation of f −1(z).

As with the normal constructor this routine successively doubles the number of sample points, which are computed using Newton's method. A good starting guess for Newton's method is provided by the previous Fourier approximation. As a result the average number of Newton iterations per sample point is about 1 or 2.

scale is used when f(x) is a correction term added to a larger contribution; and it would then be the magnitude of the larger contribution.

Note
  Computing the inverse is only possible with a Trigfun with a secular term.

Definition at line 433 of file Trigfun.hpp.

## ◆ Odd()

bool GeographicLib::Trigfun::Odd | ( |  | ) | const
| inline

Returns
  whether the function is odd or not. If it's not odd, then it is even.

Definition at line 442 of file Trigfun.hpp.

## ◆ Symmetric()

bool GeographicLib::Trigfun::Symmetric | ( |  | ) | const
| inline

Returns
  whether the function is symmetric about the quarter period point. If it is it, then the Fourier series has only odd terms.

Definition at line 447 of file Trigfun.hpp.

## ◆ HalfPeriod()

real GeographicLib::Trigfun::HalfPeriod | ( |  | ) | const
| inline

Returns
  the half period of the function.

Definition at line 451 of file Trigfun.hpp.

Referenced by Slope().

## ◆ NCoeffs()

int GeographicLib::Trigfun::NCoeffs | ( |  | ) | const
| inline

Returns
  the number of terms in the Fourier series.

Definition at line 455 of file Trigfun.hpp.

## ◆ Max()

real GeographicLib::Trigfun::Max | ( |  | ) | const

Returns
  an estimate of the amplitude of the oscillating component of f.

Note
  This estimate excludes any constant or secular terms in the series. The estimate is found by summing the absolute values of the remaining coefficients (and is thus an overestimate).

Referenced by HalfRange().

## ◆ HalfRange()

real GeographicLib::Trigfun::HalfRange | ( |  | ) | const
| inline

Returns
  the (approximate) half range of the function.

For a Trigfun containing a secular contribution this is the value of the function at the half perioid. Otherwise Max() is returned.

Definition at line 471 of file Trigfun.hpp.

References Max(), and GeographicLib::Math::pi().

Referenced by Slope().

## ◆ Slope()

real GeographicLib::Trigfun::Slope | ( |  | ) | const
| inline

Returns
  the average slope of the function.

For a Trigfun containing a secular contribution this is the slope of the secular component. Otherwise 0 is returned..

Definition at line 480 of file Trigfun.hpp.

References HalfPeriod(), and HalfRange().

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

- Trigfun.hpp