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 orginal 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;
  }
}

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 coeffient. 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 coeffient. 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 amust 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 defaulat) mean to use the machine epsilon.
[in]	scale;	if scale is negative (the default), tol sets the error relative to the largest Fourier coeffient. Otherwise, the error is relative to the maximum of the largest Fourier coefficient and scale.

Returns

the Trigfun represention of f ⁻¹(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 peroid 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 tat 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