GeographicLib::NormalGravity Class Reference

The normal gravity of the earth. More...

#include <NormalGravity.hpp>

Public Member Functions
Setting up the normal gravity
	NormalGravity (real a, real GM, real omega, real f_J2, bool geometricp=true)
	NormalGravity (real a, real GM, real omega, real f, real J2)
	NormalGravity ()
Compute the gravity
Math::real	SurfaceGravity (real lat) const
Math::real	Gravity (real lat, real h, real &gammay, real &gammaz) const
Math::real	U (real X, real Y, real Z, real &gammaX, real &gammaY, real &gammaZ) const
Math::real	V0 (real X, real Y, real Z, real &GammaX, real &GammaY, real &GammaZ) const
Math::real	Phi (real X, real Y, real &fX, real &fY) const
Inspector functions
bool	Init () const
Math::real	MajorRadius () const
Math::real	MassConstant () const
Math::real	DynamicalFormFactor (int n=2) const
Math::real	AngularVelocity () const
Math::real	Flattening () const
Math::real	EquatorialGravity () const
Math::real	PolarGravity () const
Math::real	GravityFlattening () const
Math::real	SurfacePotential () const
const Geocentric &	Earth () const

Static Public Member Functions
static Math::real	FlatteningToJ2 (real a, real GM, real omega, real f)
static const NormalGravity &	GRS80 ()
static Math::real	J2ToFlattening (real a, real GM, real omega, real J2)
static const NormalGravity &	WGS84 ()

Private Types
typedef Math::real	real

Private Member Functions
void	Initialize (real a, real GM, real omega, real f_J2, bool geometricp)
real	Jn (int n) const

Static Private Member Functions
static real	atan5series (real x)
static real	atan7series (real x)
static real	atanzz (real x, bool alt)
static real	Hf (real x, bool alt)
static real	Qf (real x, bool alt)
static real	QH3f (real x, bool alt)

Private Attributes
real	_a
real	_aomega2
real	_b
real	_E
real	_e2
Geocentric	_earth
real	_ep2
real	_f
real	_fstar
real	_gammae
real	_gammap
real	_GM
real	_J2
real	_k
real	_omega
real	_omega2
real	_Q0
real	_U0

Static Private Attributes
static const int	maxit_ = 20

Friends
class	GravityModel

Detailed Description

The normal gravity of the earth.

"Normal" gravity refers to an idealization of the earth which is modeled as an rotating ellipsoid. The eccentricity of the ellipsoid, the rotation speed, and the distribution of mass within the ellipsoid are such that the ellipsoid is a "level ellipoid", a surface of constant potential (gravitational plus centrifugal). The acceleration due to gravity is therefore perpendicular to the surface of the ellipsoid.

Because the distribution of mass within the ellipsoid is unspecified, only the potential exterior to the ellipsoid is well defined. In this class, the mass is assumed to be to concentrated on a "focal disc" of radius, (a² − b²)^1/2, where a is the equatorial radius of the ellipsoid and b is its polar semi-axis. In the case of an oblate ellipsoid, the mass is concentrated on a "focal rod" of length 2(b² − a²)^1/2. As a result the potential is well defined everywhere.

There is a closed solution to this problem which is implemented here. Series "approximations" are only used to evaluate certain combinations of elementary functions where use of the closed expression results in a loss of accuracy for small arguments due to cancellation of the leading terms. However these series include sufficient terms to give full machine precision.

Although the formulation used in this class applies to ellipsoids with arbitrary flattening, in practice, its use should be limited to about b/a ∈ [0.01, 100] or f ∈ [−99, 0.99].

Definitions:

• V₀, the gravitational contribution to the normal potential;
• Φ, the rotational contribution to the normal potential;
• U = V₀ + Φ, the total potential;
• Γ = ∇V₀, the acceleration due to mass of the earth;
• f = ∇Φ, the centrifugal acceleration;
• γ = ∇U = Γ + f, the normal acceleration;
• X, Y, Z, geocentric coordinates;
• x, y, z, local cartesian coordinates used to denote the east, north and up directions.

References:

• C. Somigliana, Teoria generale del campo gravitazionale dell'ellissoide di rotazione, Mem. Soc. Astron. Ital, 4, 541–599 (1929).
• W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San Francisco, 1967), Secs. 1-19, 2-7, 2-8 (2-9, 2-10), 6-2 (6-3).
• B. Hofmann-Wellenhof, H. Moritz, Physical Geodesy (Second edition, Springer, 2006) https://doi.org/10.1007/978-3-211-33545-1
• H. Moritz, Geodetic Reference System 1980, J. Geodesy 54(3), 395-405 (1980) https://doi.org/10.1007/BF02521480

For more information on normal gravity see normalgravity.

Example of use:

// Example of using the GeographicLib::NormalGravity class
 
#include <iostream>
#include <exception>
#include <GeographicLib/NormalGravity.hpp>
#include <GeographicLib/Constants.hpp>
 
using namespace std;
using namespace GeographicLib;
 
int main() {
  try {
    NormalGravity grav(Constants::WGS84_a(), Constants::WGS84_GM(),
                       Constants::WGS84_omega(), Constants::WGS84_f());
    // Alternatively: const NormalGravity& grav = NormalGravity::WGS84();
    double lat = 27.99, h = 8820; // Mt Everest
    double gammay, gammaz;
    grav.Gravity(lat, h, gammay, gammaz);
    cout << gammay << " " << gammaz << "\n";
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Definition at line 79 of file NormalGravity.hpp.

Member Typedef Documentation

real

typedef Math::real GeographicLib::NormalGravity::real

private

Definition at line 82 of file NormalGravity.hpp.

Constructor & Destructor Documentation

NormalGravity() [1/3]

GeographicLib::NormalGravity::NormalGravity	(	real	a,
		real	GM,
		real	omega,
		real	f_J2,
		bool	geometricp = true
	)

Constructor for the normal gravity.

Parameters

[in]	a	equatorial radius (meters).
[in]	GM	mass constant of the ellipsoid (meters3/seconds2); this is the product of G the gravitational constant and M the mass of the earth (usually including the mass of the earth's atmosphere).
[in]	omega	the angular velocity (rad s−1).
[in]	f_J2	either the flattening of the ellipsoid f or the the dynamical form factor J2.
[out]	geometricp	if true (the default), then f_J2 denotes the flattening, else it denotes the dynamical form factor J2.

Exceptions

if	a is not positive or if the other parameters do not obey the restrictions given below.

The shape of the ellipsoid can be given in one of two ways:

• geometrically (geomtricp = true), the ellipsoid is defined by the flattening f = (a − b) / a, where a and b are the equatorial radius and the polar semi-axis. The parameters should obey a > 0, f < 1. There are no restrictions on GM or omega, in particular, GM need not be positive.
• physically (geometricp = false), the ellipsoid is defined by the dynamical form factor J₂ = (C − A) / Ma², where A and C are the equatorial and polar moments of inertia and M is the mass of the earth. The parameters should obey a > 0, GM > 0 and J2 < 1/3 − (omega²a³/GM) 8/(45π). There is no restriction on omega.

Definition at line 61 of file src/NormalGravity.cpp.

NormalGravity() [2/3]

GeographicLib::NormalGravity::NormalGravity	(	real	a,
		real	GM,
		real	omega,
		real	f,
		real	J2
	)

Deprecated:

Old constructor for the normal gravity.

Parameters

[in]	a	equatorial radius (meters).
[in]	GM	mass constant of the ellipsoid (meters3/seconds2); this is the product of G the gravitational constant and M the mass of the earth (usually including the mass of the earth's atmosphere).
[in]	omega	the angular velocity (rad s−1).
[in]	f	the flattening of the ellipsoid.
[in]	J2	the dynamical form factor.

Exceptions

if	a is not positive or the other constants are inconsistent (see below).

If omega is non-zero, then exactly one of f and J2 should be positive and this will be used to define the ellipsoid. The shape of the ellipsoid can be given in one of two ways:

• geometrically, the ellipsoid is defined by the flattening f = (a − b) / a, where a and b are the equatorial radius and the polar semi-axis.
• physically, the ellipsoid is defined by the dynamical form factor J₂ = (C − A) / Ma², where A and C are the equatorial and polar moments of inertia and M is the mass of the earth.

If omega, f, and J2 are all zero, then the ellipsoid becomes a sphere.

Definition at line 66 of file src/NormalGravity.cpp.

NormalGravity() [3/3]

GeographicLib::NormalGravity::NormalGravity ( )

inline

A default constructor for the normal gravity. This sets up an uninitialized object and is used by GravityModel which constructs this object before it has read in the parameters for the reference ellipsoid.

Definition at line 180 of file NormalGravity.hpp.

Member Function Documentation

AngularVelocity()

Math::real GeographicLib::NormalGravity::AngularVelocity ( ) const

inline

Returns

ω the angular velocity of the ellipsoid (rad s⁻¹). This is the value used in the constructor.

Definition at line 329 of file NormalGravity.hpp.

atan5series()

Math::real GeographicLib::NormalGravity::atan5series ( real  x )

staticprivate

Definition at line 122 of file src/NormalGravity.cpp.

atan7series()

Math::real GeographicLib::NormalGravity::atan7series ( real  x )

staticprivate

Definition at line 99 of file src/NormalGravity.cpp.

atanzz()

static real GeographicLib::NormalGravity::atanzz ( real  x, bool  alt  )

inlinestaticprivate

Definition at line 87 of file NormalGravity.hpp.

DynamicalFormFactor()

Math::real GeographicLib::NormalGravity::DynamicalFormFactor ( int  n = 2 ) const

inline

Returns

J_n the dynamical form factors of the ellipsoid.

If n = 2 (the default), this is the value of J₂ used in the constructor. Otherwise it is the zonal coefficient of the Legendre harmonic sum of the normal gravitational potential. Note that J_n = 0 if n is odd. In most gravity applications, fully normalized Legendre functions are used and the corresponding coefficient is C_n0 = −J_n / sqrt(2 n + 1).

Definition at line 322 of file NormalGravity.hpp.

Earth()

const Geocentric& GeographicLib::NormalGravity::Earth ( ) const

inline

Returns

the Geocentric object used by this instance.

Definition at line 370 of file NormalGravity.hpp.

EquatorialGravity()

Math::real GeographicLib::NormalGravity::EquatorialGravity ( ) const

inline

Returns

γ_e the normal gravity at equator (m s⁻²).

Definition at line 343 of file NormalGravity.hpp.

Flattening()

Math::real GeographicLib::NormalGravity::Flattening ( ) const

inline

Returns

f the flattening of the ellipsoid (a − b)/a.

Definition at line 336 of file NormalGravity.hpp.

FlatteningToJ2()

Math::real GeographicLib::NormalGravity::FlatteningToJ2 ( real  a, real  GM, real  omega, real  f  )

static

Compute the dynamical form factor from the flattening.

Parameters

[in]	a	equatorial radius (meters).
[in]	GM	mass constant of the ellipsoid (meters3/seconds2); this is the product of G the gravitational constant and M the mass of the earth (usually including the mass of the earth's atmosphere).
[in]	omega	the angular velocity (rad s−1).
[in]	f	the flattening of the ellipsoid.

Returns

J2 the dynamical form factor.

This routine requires a > 0, GM ≠ 0, f < 1. The values of these parameters are not checked.

Definition at line 307 of file src/NormalGravity.cpp.

Gravity()

Math::real GeographicLib::NormalGravity::Gravity	(	real	lat,
		real	h,
		real &	gammay,
		real &	gammaz
	)		const

Evaluate the gravity at an arbitrary point above (or below) the ellipsoid.

Parameters

[in]	lat	the geographic latitude (degrees).
[in]	h	the height above the ellipsoid (meters).
[out]	gammay	the northerly component of the acceleration (m s−2).
[out]	gammaz	the upward component of the acceleration (m s−2); this is usually negative.

Returns

U the corresponding normal potential (m² s⁻²).

Due to the axial symmetry of the ellipsoid, the result is independent of the value of the longitude and the easterly component of the acceleration vanishes, gammax = 0. The function includes the effects of the earth's rotation. When h = 0, this function gives gammay = 0 and the returned value matches that of NormalGravity::SurfaceGravity.

Definition at line 255 of file src/NormalGravity.cpp.

GravityFlattening()

Math::real GeographicLib::NormalGravity::GravityFlattening ( ) const

inline

Returns

f* the gravity flattening (γ_p − γ_e) / γ_e.

Definition at line 357 of file NormalGravity.hpp.

GRS80()

const NormalGravity & GeographicLib::NormalGravity::GRS80 ( )

static

A global instantiation of NormalGravity for the GRS80 ellipsoid.

Definition at line 91 of file src/NormalGravity.cpp.

Hf()

Math::real GeographicLib::NormalGravity::Hf ( real  x, bool  alt  )

staticprivate

Definition at line 141 of file src/NormalGravity.cpp.

Init()

bool GeographicLib::NormalGravity::Init ( ) const

inline

Returns

true if the object has been initialized.

Definition at line 293 of file NormalGravity.hpp.

Initialize()

void GeographicLib::NormalGravity::Initialize ( real  a, real  GM, real  omega, real  f_J2, bool  geometricp  )

private

Definition at line 21 of file src/NormalGravity.cpp.

J2ToFlattening()

Math::real GeographicLib::NormalGravity::J2ToFlattening ( real  a, real  GM, real  omega, real  J2  )

static

Compute the flattening from the dynamical form factor.

Parameters

[in]	a	equatorial radius (meters).
[in]	GM	mass constant of the ellipsoid (meters3/seconds2); this is the product of G the gravitational constant and M the mass of the earth (usually including the mass of the earth's atmosphere).
[in]	omega	the angular velocity (rad s−1).
[in]	J2	the dynamical form factor.

Returns

f the flattening of the ellipsoid.

This routine requires a > 0, GM > 0, J2 < 1/3 − omega²a³/GM 8/(45π). A NaN is returned if these conditions do not hold. The restriction to positive GM is made because for negative GM two solutions are possible.

Definition at line 268 of file src/NormalGravity.cpp.

Jn()

Math::real GeographicLib::NormalGravity::Jn ( int  n ) const

private

Definition at line 165 of file src/NormalGravity.cpp.

MajorRadius()

Math::real GeographicLib::NormalGravity::MajorRadius ( ) const

inline

Returns

a the equatorial radius of the ellipsoid (meters). This is the value used in the constructor.

Definition at line 299 of file NormalGravity.hpp.

MassConstant()

Math::real GeographicLib::NormalGravity::MassConstant ( ) const

inline

Returns

GM the mass constant of the ellipsoid (m³ s⁻²). This is the value used in the constructor.

Definition at line 307 of file NormalGravity.hpp.

Phi()

Math::real GeographicLib::NormalGravity::Phi	(	real	X,
		real	Y,
		real &	fX,
		real &	fY
	)		const

Evaluate the centrifugal acceleration in geocentric coordinates.

Parameters

[in]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[out]	fX	the X component of the centrifugal acceleration (m s−2).
[out]	fY	the Y component of the centrifugal acceleration (m s−2).

Returns

Φ the centrifugal potential (m² s⁻²).

Φ is independent of Z, thus fZ = 0. This function NormalGravity::U sums the results of NormalGravity::V0 and NormalGravity::Phi.

Definition at line 239 of file src/NormalGravity.cpp.

PolarGravity()

Math::real GeographicLib::NormalGravity::PolarGravity ( ) const

inline

Returns

γ_p the normal gravity at poles (m s⁻²).

Definition at line 350 of file NormalGravity.hpp.

Qf()

Math::real GeographicLib::NormalGravity::Qf ( real  x, bool  alt  )

staticprivate

Definition at line 130 of file src/NormalGravity.cpp.

QH3f()

Math::real GeographicLib::NormalGravity::QH3f ( real  x, bool  alt  )

staticprivate

Definition at line 153 of file src/NormalGravity.cpp.

SurfaceGravity()

Math::real GeographicLib::NormalGravity::SurfaceGravity

(

real

lat

)

const

Evaluate the gravity on the surface of the ellipsoid.

Parameters

[in]

lat

the geographic latitude (degrees).

Returns

γ the acceleration due to gravity, positive downwards (m s⁻²).

Due to the axial symmetry of the ellipsoid, the result is independent of the value of the longitude. This acceleration is perpendicular to the surface of the ellipsoid. It includes the effects of the earth's rotation.

Definition at line 177 of file src/NormalGravity.cpp.

SurfacePotential()

Math::real GeographicLib::NormalGravity::SurfacePotential ( ) const

inline

Returns

U₀ the constant normal potential for the surface of the ellipsoid (m² s⁻²).

Definition at line 364 of file NormalGravity.hpp.

U()

Math::real GeographicLib::NormalGravity::U	(	real	X,
		real	Y,
		real	Z,
		real &	gammaX,
		real &	gammaY,
		real &	gammaZ
	)		const

Evaluate the components of the acceleration due to gravity and the centrifugal acceleration in geocentric coordinates.

Parameters

[in]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[in]	Z	geocentric coordinate of point (meters).
[out]	gammaX	the X component of the acceleration (m s−2).
[out]	gammaY	the Y component of the acceleration (m s−2).
[out]	gammaZ	the Z component of the acceleration (m s−2).

Returns

U = V₀ + Φ the sum of the gravitational and centrifugal potentials (m² s⁻²).

The acceleration given by γ = ∇U = ∇V₀ + ∇Φ = Γ + f.

Definition at line 246 of file src/NormalGravity.cpp.

V0()

Math::real GeographicLib::NormalGravity::V0	(	real	X,
		real	Y,
		real	Z,
		real &	GammaX,
		real &	GammaY,
		real &	GammaZ
	)		const

Evaluate the components of the acceleration due to the gravitational force in geocentric coordinates.

Parameters

[in]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[in]	Z	geocentric coordinate of point (meters).
[out]	GammaX	the X component of the acceleration due to the gravitational force (m s−2).
[out]	GammaY	the Y component of the acceleration due to the
[out]	GammaZ	the Z component of the acceleration due to the gravitational force (m s−2).

Returns

V₀ the gravitational potential (m² s⁻²).

This function excludes the centrifugal acceleration and is appropriate to use for space applications. In terrestrial applications, the function NormalGravity::U (which includes this effect) should usually be used.

Definition at line 183 of file src/NormalGravity.cpp.

WGS84()

const NormalGravity & GeographicLib::NormalGravity::WGS84 ( )

static

A global instantiation of NormalGravity for the WGS84 ellipsoid.

Definition at line 83 of file src/NormalGravity.cpp.

Friends And Related Function Documentation

GravityModel

friend class GravityModel

friend

Definition at line 83 of file NormalGravity.hpp.

Member Data Documentation

_a

real GeographicLib::NormalGravity::_a

private

Definition at line 84 of file NormalGravity.hpp.

_aomega2

real GeographicLib::NormalGravity::_aomega2

private

Definition at line 84 of file NormalGravity.hpp.

_b

real GeographicLib::NormalGravity::_b

private

Definition at line 85 of file NormalGravity.hpp.

_E

real GeographicLib::NormalGravity::_E

private

Definition at line 85 of file NormalGravity.hpp.

_e2

real GeographicLib::NormalGravity::_e2

private

Definition at line 85 of file NormalGravity.hpp.

_earth

Geocentric GeographicLib::NormalGravity::_earth

private

Definition at line 86 of file NormalGravity.hpp.

_ep2

real GeographicLib::NormalGravity::_ep2

private

Definition at line 85 of file NormalGravity.hpp.

_f

real GeographicLib::NormalGravity::_f

private

Definition at line 84 of file NormalGravity.hpp.

_fstar

real GeographicLib::NormalGravity::_fstar

private

Definition at line 85 of file NormalGravity.hpp.

_gammae

real GeographicLib::NormalGravity::_gammae

private

Definition at line 85 of file NormalGravity.hpp.

_gammap

real GeographicLib::NormalGravity::_gammap

private

Definition at line 85 of file NormalGravity.hpp.

_GM

real GeographicLib::NormalGravity::_GM

private

Definition at line 84 of file NormalGravity.hpp.

_J2

real GeographicLib::NormalGravity::_J2

private

Definition at line 84 of file NormalGravity.hpp.

_k

real GeographicLib::NormalGravity::_k

private

Definition at line 85 of file NormalGravity.hpp.

_omega

real GeographicLib::NormalGravity::_omega

private

Definition at line 84 of file NormalGravity.hpp.

_omega2

real GeographicLib::NormalGravity::_omega2

private

Definition at line 84 of file NormalGravity.hpp.

_Q0

real GeographicLib::NormalGravity::_Q0

private

Definition at line 85 of file NormalGravity.hpp.

_U0

real GeographicLib::NormalGravity::_U0

private

Definition at line 85 of file NormalGravity.hpp.

maxit_

const int GeographicLib::NormalGravity::maxit_ = 20

staticprivate

Definition at line 81 of file NormalGravity.hpp.

---

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

• NormalGravity.hpp
• src/NormalGravity.cpp