Mathematical functions needed by GeographicLib. More...

#include <GeographicLib/Math.hpp>

Public Types
enum	dms { qd = 90 , dm = 60 , ms = 60 , hd = 2 * qd , td = 2 * hd , ds = dm * ms }

typedef double	extended

typedef double	real

Static Public Member Functions
static int	digits ()

static int	set_digits (int ndigits)

static int	digits10 ()

static int	extra_digits ()

template<typename T = real>
static T	pi ()

template<typename T = real>
static T	degree ()

template<typename T >
static T	sq (T x)

template<typename T >
static void	norm (T &x, T &y)

template<typename T >
static T	sum (T u, T v, T &t)

template<typename T >
static T	polyval (int N, const T p[], T x)

template<typename T >
static T	AngNormalize (T x)

template<typename T >
static T	LatFix (T x)

template<typename T >
static T	AngDiff (T x, T y, T &e)

template<typename T >
static T	AngDiff (T x, T y)

template<typename T >
static T	AngRound (T x)

template<typename T >
static void	sincosd (T x, T &sinx, T &cosx)

template<typename T >
static void	sincosde (T x, T t, T &sinx, T &cosx)

template<typename T >
static T	sind (T x)

template<typename T >
static T	cosd (T x)

template<typename T >
static T	tand (T x)

template<typename T >
static T	atan2d (T y, T x)

template<typename T >
static T	atand (T x)

template<typename T >
static T	eatanhe (T x, T es)

template<typename T >
static T	taupf (T tau, T es)

template<typename T >
static T	tauf (T taup, T es)

template<typename T = real>
static T	NaN ()

template<typename T = real>
static T	infinity ()

template<typename T >
static T	swab (T x)

Static Public Attributes
static const bool	bigendian = GEOGRAPHICLIB_WORDS_BIGENDIAN

Detailed Description

Mathematical functions needed by GeographicLib.

Define mathematical functions in order to localize system dependencies and to provide generic versions of the functions. In addition define a real type to be used by GeographicLib.

Example of use:

// Example of using the GeographicLib::Math class
 
#include <iostream>
#include <exception>
#include <GeographicLib/Math.hpp>
 
using namespace std;
using namespace GeographicLib;
 
int main() {
  try {
    cout << Math::pi() << " " << Math::sq(Math::pi()) << "\n";
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Definition at line 76 of file Math.hpp.

Member Typedef Documentation

◆ extended

typedef double GeographicLib::Math::extended

Definition at line 89 of file Math.hpp.

◆ real

typedef double GeographicLib::Math::real

The real type for GeographicLib. Nearly all the testing has been done with real = double. However, the algorithms should also work with float and long double (where available). (CAUTION: reasonable accuracy typically cannot be obtained using floats.)

Definition at line 99 of file Math.hpp.

Member Enumeration Documentation

◆ dms

enum GeographicLib::Math::dms

The constants defining the standard (Babylonian) meanings of degrees, minutes, and seconds, for angles. Read the constants as follows (for example): ms = 60 is the ratio 1 minute / 1 second. The abbreviations are

t a whole turn (360°)
h a half turn (180°)
q a quarter turn (a right angle = 90°)
d a degree
m a minute
s a second

Note that degree() is ratio 1 degree / 1 radian, thus, for example, Math::degree() * Math::qd is the ratio 1 quarter turn / 1 radian = π/2.

Defining all these in one place would mean that it's simple to convert to the centesimal system for measuring angles. The DMS class assumes that Math::dm and Math::ms are less than or equal to 100 (so that two digits suffice for the integer parts of the minutes and degrees components of an angle). Switching to the centesimal convention will break most of the tests. Also the normal definition of degree is baked into some classes, e.g., UTMUPS, MGRS, Georef, Geohash, etc.

Enumerator
qd	degrees per quarter turn
dm	minutes per degree
ms	seconds per minute
hd	degrees per half turn
td	degrees per turn
ds	seconds per degree

Definition at line 139 of file Math.hpp.

Member Function Documentation

◆ digits()

int GeographicLib::Math::digits ( )

static

Returns: the number of bits of precision in a real number.

Definition at line 26 of file Math.cpp.

Referenced by GeographicLib::MGRS::Forward(), GeographicLib::GeodesicExact::GeodesicExact(), and set_digits().

◆ set_digits()

int GeographicLib::Math::set_digits ( int ndigits )

static

Set the binary precision of a real number.

Parameters

[in] ndigits the number of bits of precision.

Returns: the resulting number of bits of precision.

This only has an effect when GEOGRAPHICLIB_PRECISION = 5. See also Utility::set_digits for caveats about when this routine should be called.

Definition at line 34 of file Math.cpp.

References digits().

Referenced by GeographicLib::Utility::set_digits().

◆ digits10()

int GeographicLib::Math::digits10 ( )

static

Returns: the number of decimal digits of precision in a real number.

Definition at line 43 of file Math.cpp.

Referenced by extra_digits().

◆ extra_digits()

int GeographicLib::Math::extra_digits ( )

static

Number of additional decimal digits of precision for real relative to double (0 for float).

Definition at line 51 of file Math.cpp.

References digits10().

Referenced by GeographicLib::GeoCoords::DMSRepresentation(), GeographicLib::DMS::Encode(), and GeographicLib::GeoCoords::GeoRepresentation().

◆ pi()

template<typename T = real>

static T GeographicLib::Math::pi ( )

inlinestatic

Template Parameters

T	the type of the returned value.

Returns: π.

Definition at line 190 of file Math.hpp.

◆ degree()

template<typename T = real>

static T GeographicLib::Math::degree ( )

inlinestatic

Template Parameters

T	the type of the returned value.

Returns: the number of radians in a degree.

Definition at line 200 of file Math.hpp.

Referenced by GeographicLib::Constants::arcminute(), GeographicLib::Constants::arcsecond(), GeographicLib::Constants::degree(), GeographicLib::GeodesicLineExact::EquatorialArc(), GeographicLib::MagneticModel::FieldComponents(), GeographicLib::CassiniSoldner::Forward(), GeographicLib::AlbersEqualArea::Forward(), GeographicLib::LambertConformalConic::Forward(), GeographicLib::TransverseMercatorExact::Forward(), GeographicLib::Rhumb::GenInverse(), GeographicLib::GeodesicLine::GenPosition(), GeographicLib::GeodesicLineExact::GenPosition(), GeographicLib::RhumbLine::GenPosition(), GeographicLib::Ellipsoid::InverseIsometricLatitude(), GeographicLib::Ellipsoid::InverseRectifyingLatitude(), GeographicLib::Ellipsoid::IsometricLatitude(), GeographicLib::AlbersEqualArea::Reverse(), GeographicLib::LambertConformalConic::Reverse(), GeographicLib::TransverseMercatorExact::Reverse(), GeographicLib::GravityModel::SphericalAnomaly(), GeographicLib::JacobiConformal::x(), and GeographicLib::JacobiConformal::y().

◆ sq()

template<typename T >

static T GeographicLib::Math::sq ( T x )

inlinestatic

Square a number.

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in] x

Returns: x².

Definition at line 212 of file Math.hpp.

◆ norm()

template<typename T >

static void GeographicLib::Math::norm	(	T &	x,
		T &	y
	)

inlinestatic

Normalize a two-vector.

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in,out]	x	on output set to x/hypot(x, y).
[in,out]	y	on output set to y/hypot(x, y).

Definition at line 222 of file Math.hpp.

Referenced by GeographicLib::CassiniSoldner::Reset().

◆ sum()

template<typename T >

T GeographicLib::Math::sum	(	T	u,
		T	v,
		T &	t
	)

static

The error-free sum of two numbers.

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in]	u
[in]	v
[out]	t	the exact error given by (u + v) - s.

Returns: s = round(u + v).

See D. E. Knuth, TAOCP, Vol 2, 4.2.2, Theorem B.

Note: t can be the same as one of the first two arguments.

Definition at line 57 of file Math.cpp.

References GEOGRAPHICLIB_VOLATILE.

Referenced by AngDiff().

◆ polyval()

template<typename T >

static T GeographicLib::Math::polyval	(	int	N,
		const T	p[],
		T	x
	)

inlinestatic

Evaluate a polynomial.

Template Parameters

T	the type of the arguments and returned value.

Parameters

[in]	N	the order of the polynomial.
[in]	p	the coefficient array (of size N + 1) with p₀ being coefficient of x^N.
[in]	x	the variable.

Returns: the value of the polynomial.

Evaluate ∑_n=0..N p_n x^N−n. Return 0 if N < 0. Return p₀, if N = 0 (even if x is infinite or a nan). The evaluation uses Horner's method.

Definition at line 271 of file Math.hpp.

Referenced by GeographicLib::Rhumb::Rhumb(), and GeographicLib::TransverseMercator::TransverseMercator().

◆ AngNormalize()

template<typename T >

T GeographicLib::Math::AngNormalize ( T x )

static

Normalize an angle.

Template Parameters

T	the type of the argument and returned value.

Parameters

[in] x the angle in degrees.

Returns: the angle reduced to the range [−180°, 180°].

The range of x is unrestricted. If the result is ±0° or ±180° then the sign is the sign of x.

Definition at line 71 of file Math.cpp.

References hd, and td.

◆ LatFix()

template<typename T >

static T GeographicLib::Math::LatFix ( T x )

inlinestatic

Normalize a latitude.

Template Parameters

T	the type of the argument and returned value.

Parameters

[in] x the angle in degrees.

Returns: x if it is in the range [−90°, 90°], otherwise return NaN.

Definition at line 300 of file Math.hpp.

◆ AngDiff() [1/2]

template<typename T >

T GeographicLib::Math::AngDiff	(	T	x,
		T	y,
		T &	e
	)

static

The exact difference of two angles reduced to [−180°, 180°].

Template Parameters

T	the type of the arguments and returned value.

Parameters

[in]	x	the first angle in degrees.
[in]	y	the second angle in degrees.
[out]	e	the error term in degrees.

Returns: d, the truncated value of y − x.

This computes z = y − x exactly, reduced to [−180°, 180°]; and then sets z = d + e where d is the nearest representable number to z and e is the truncation error. If z = ±0° or ±180°, then the sign of d is given by the sign of y − x. The maximum absolute value of e is 2⁻²⁶ (for doubles).

Definition at line 82 of file Math.cpp.

References hd, sum(), and td.

Referenced by GeographicLib::UTMUPS::Forward(), GeographicLib::CassiniSoldner::Forward(), GeographicLib::AlbersEqualArea::Forward(), GeographicLib::LambertConformalConic::Forward(), GeographicLib::TransverseMercator::Forward(), GeographicLib::TransverseMercatorExact::Forward(), and GeographicLib::Rhumb::GenInverse().

◆ AngDiff() [2/2]

template<typename T >

static T GeographicLib::Math::AngDiff	(	T	x,
		T	y
	)

inlinestatic

Difference of two angles reduced to [−180°, 180°]

Template Parameters

T	the type of the arguments and returned value.

Parameters

[in]	x	the first angle in degrees.
[in]	y	the second angle in degrees.

Returns: y − x, reduced to the range [−180°, 180°].

The result is equivalent to computing the difference exactly, reducing it to [−180°, 180°] and rounding the result.

Definition at line 334 of file Math.hpp.

◆ AngRound()

template<typename T >

T GeographicLib::Math::AngRound ( T x )

static

Coarsen a value close to zero.

Template Parameters

T	the type of the argument and returned value.

Parameters

[in] x

Returns: the coarsened value.

The makes the smallest gap in x = 1/16 − nextafter(1/16, 0) = 1/2⁵⁷ for doubles = 0.8 pm on the earth if x is an angle in degrees. (This is about 2000 times more resolution than we get with angles around 90°.) We use this to avoid having to deal with near singular cases when x is non-zero but tiny (e.g., 10⁻²⁰⁰). This sign of ±0 is preserved.

Definition at line 97 of file Math.cpp.

References GEOGRAPHICLIB_VOLATILE.

Referenced by GeographicLib::Geodesic::GenDirectLine(), GeographicLib::GeodesicExact::GenDirectLine(), GeographicLib::GeodesicLine::GeodesicLine(), GeographicLib::GeodesicLineExact::GeodesicLineExact(), and sincosde().

◆ sincosd()

template<typename T >

void GeographicLib::Math::sincosd	(	T	x,
		T &	sinx,
		T &	cosx
	)

static

Evaluate the sine and cosine function with the argument in degrees

Template Parameters

T	the type of the arguments.

Parameters

[in]	x	in degrees.
[out]	sinx	sin(x).
[out]	cosx	cos(x).

The results obey exactly the elementary properties of the trigonometric functions, e.g., sin 9° = cos 81° = − sin 123456789°. If x = −0 or a negative multiple of 180°, then sinx = −0; this is the only case where −0 is returned.

Definition at line 106 of file Math.cpp.

References qd.

Referenced by GeographicLib::AlbersEqualArea::AlbersEqualArea(), GeographicLib::EllipticFunction::Ed(), GeographicLib::MagneticCircle::FieldGeocentric(), GeographicLib::PolarStereographic::Forward(), GeographicLib::CassiniSoldner::Forward(), GeographicLib::AzimuthalEquidistant::Forward(), GeographicLib::Gnomonic::Forward(), GeographicLib::AlbersEqualArea::Forward(), GeographicLib::LambertConformalConic::Forward(), GeographicLib::TransverseMercator::Forward(), GeographicLib::Geodesic::GenDirectLine(), GeographicLib::GeodesicExact::GenDirectLine(), GeographicLib::GeodesicLine::GenPosition(), GeographicLib::GeodesicLineExact::GenPosition(), GeographicLib::GeodesicLine::GeodesicLine(), GeographicLib::GeodesicLineExact::GeodesicLineExact(), GeographicLib::LambertConformalConic::LambertConformalConic(), GeographicLib::Ellipsoid::NormalCurvatureRadius(), GeographicLib::CircularEngine::operator()(), GeographicLib::CassiniSoldner::Reset(), GeographicLib::LocalCartesian::Reset(), GeographicLib::GravityCircle::T(), tand(), GeographicLib::GravityCircle::V(), GeographicLib::GravityCircle::W(), GeographicLib::JacobiConformal::x(), and GeographicLib::JacobiConformal::y().

◆ sincosde()

template<typename T >

void GeographicLib::Math::sincosde	(	T	x,
		T	t,
		T &	sinx,
		T &	cosx
	)

static

Evaluate the sine and cosine with reduced argument plus correction

Template Parameters

T	the type of the arguments.

Parameters

[in]	x	reduced angle in degrees.
[in]	t	correction in degrees.
[out]	sinx	sin(x + t).
[out]	cosx	cos(x + t).

This is a variant of Math::sincosd allowing a correction to the angle to be supplied. x must be in [−180°, 180°] and t is assumed to be a small correction. Math::AngRound is applied to the reduced angle to prevent problems with x + t being extremely close but not exactly equal to one of the four cardinal directions.

Definition at line 126 of file Math.cpp.

References AngRound(), and qd.

◆ sind()

template<typename T >

T GeographicLib::Math::sind ( T x )

static

Evaluate the sine function with the argument in degrees

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in] x in degrees.

Returns: sin(x).

The result is +0 for x = +0 and positive multiples of 180°. The result is −0 for x = -0 and negative multiples of 180°.

Definition at line 148 of file Math.cpp.

References qd.

Referenced by GeographicLib::Ellipsoid::MeridionalCurvatureRadius(), GeographicLib::Ellipsoid::NormalCurvatureRadius(), GeographicLib::NormalGravity::SurfaceGravity(), and GeographicLib::Ellipsoid::TransverseCurvatureRadius().

◆ cosd()

template<typename T >

T GeographicLib::Math::cosd ( T x )

static

Evaluate the cosine function with the argument in degrees

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in] x in degrees.

Returns: cos(x).

The result is +0 for x an odd multiple of 90°.

Definition at line 160 of file Math.cpp.

References qd.

◆ tand()

template<typename T >

T GeographicLib::Math::tand ( T x )

static

Evaluate the tangent function with the argument in degrees

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in] x in degrees.

Returns: tan(x).

If x is an odd multiple of 90°, then a suitably large (but finite) value is returned.

Definition at line 172 of file Math.cpp.

References sincosd(), and sq().

◆ atan2d()

template<typename T >

T GeographicLib::Math::atan2d	(	T	y,
		T	x
	)

static

Evaluate the atan2 function with the result in degrees

Template Parameters

T	the type of the arguments and the returned value.

Parameters

[in]	y
[in]	x

Returns: atan2(y, x) in degrees.

The result is in the range [−180° 180°]. N.B., atan2d(±0, −1) = ±180°.

Definition at line 183 of file Math.cpp.

References hd, qd, and std::swap().

◆ atand()

template<typename T >

T GeographicLib::Math::atand ( T x )

static

Evaluate the atan function with the result in degrees

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in] x

Returns: atan(x) in degrees.

Definition at line 202 of file Math.cpp.

References atan2d().

◆ eatanhe()

template<typename T >

T GeographicLib::Math::eatanhe	(	T	x,
		T	es
	)

static

Evaluate e atanh(e x)

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in]	x
[in]	es	the signed eccentricity = sign(e²) sqrt(\|e²\|)

Returns: e atanh(e x)

If e² is negative (e is imaginary), the expression is evaluated in terms of atan.

Definition at line 205 of file Math.cpp.

Referenced by GeographicLib::LambertConformalConic::Forward(), tauf(), and taupf().

◆ taupf()

template<typename T >

T GeographicLib::Math::taupf	(	T	tau,
		T	es
	)

static

tanχ in terms of tanφ

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in]	tau	τ = tanφ
[in]	es	the signed eccentricity = sign(e²) sqrt(\|e²\|)

Returns: τ′ = tanχ

See Eqs. (7–9) of C. F. F. Karney, Transverse Mercator with an accuracy of a few nanometers, J. Geodesy 85(8), 475–485 (Aug. 2011) (preprint arXiv:1002.1417).

Definition at line 209 of file Math.cpp.

References eatanhe().

Referenced by GeographicLib::Ellipsoid::ConformalLatitude(), GeographicLib::PolarStereographic::Forward(), GeographicLib::TransverseMercator::Forward(), GeographicLib::TransverseMercatorExact::Forward(), GeographicLib::Ellipsoid::IsometricLatitude(), and tauf().

◆ tauf()

template<typename T >

T GeographicLib::Math::tauf	(	T	taup,
		T	es
	)

static

tanφ in terms of tanχ

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in]	taup	τ′ = tanχ
[in]	es	the signed eccentricity = sign(e²) sqrt(\|e²\|)

Returns: τ = tanφ

See Eqs. (19–21) of C. F. F. Karney, Transverse Mercator with an accuracy of a few nanometers, J. Geodesy 85(8), 475–485 (Aug. 2011) (preprint arXiv:1002.1417).

Definition at line 219 of file Math.cpp.

References eatanhe(), GEOGRAPHICLIB_PANIC, sq(), and taupf().

Referenced by GeographicLib::TransverseMercatorExact::Forward(), GeographicLib::Ellipsoid::InverseConformalLatitude(), GeographicLib::Ellipsoid::InverseIsometricLatitude(), GeographicLib::PolarStereographic::Reverse(), GeographicLib::LambertConformalConic::Reverse(), GeographicLib::TransverseMercator::Reverse(), and GeographicLib::TransverseMercatorExact::Reverse().

◆ NaN()

template<typename T >

T GeographicLib::Math::NaN

static

The NaN (not a number)

Template Parameters

T	the type of the returned value.

Returns: NaN if available, otherwise return the max real of type T.

Definition at line 250 of file Math.cpp.

◆ infinity()

template<typename T >

T GeographicLib::Math::infinity

static

Infinity

Template Parameters

T	the type of the returned value.

Returns: infinity if available, otherwise return the max real.

Definition at line 262 of file Math.cpp.

Referenced by GeographicLib::EllipticFunction::Reset().

◆ swab()

template<typename T >

static T GeographicLib::Math::swab ( T x )

inlinestatic

Swap the bytes of a quantity

Template Parameters

T	the type of the argument and the returned value.

Parameters

[in] x

Returns: x with its bytes swapped.

Definition at line 517 of file Math.hpp.

References std::swap().

Member Data Documentation

◆ bigendian

const bool GeographicLib::Math::bigendian = GEOGRAPHICLIB_WORDS_BIGENDIAN

static

true if the machine is big-endian.

Definition at line 184 of file Math.hpp.

Referenced by GeographicLib::Utility::readarray(), and GeographicLib::Utility::writearray().

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

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ extended

◆ real

Member Enumeration Documentation

◆ dms

Member Function Documentation

◆ digits()

◆ set_digits()

◆ digits10()

◆ extra_digits()

◆ pi()

◆ degree()

◆ sq()

◆ norm()

◆ sum()

◆ polyval()

◆ AngNormalize()

◆ LatFix()

◆ AngDiff() [1/2]

◆ AngDiff() [2/2]

◆ AngRound()

◆ sincosd()

◆ sincosde()

◆ sind()

◆ cosd()

◆ tand()

◆ atan2d()

◆ atand()

◆ eatanhe()

◆ taupf()

◆ tauf()

◆ NaN()

◆ infinity()

◆ swab()

Member Data Documentation

◆ bigendian