GeographicLib: GeographicLib::NormalGravity Class Reference

GeographicLib 2.5.2

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

The normal gravity of the earth. More...

`#include <GeographicLib/NormalGravity.hpp>`

## Public Member Functions
Setting up the normal gravity
| NormalGravity (real a, real GM, real omega, real f_J2, bool geometricp=true)
| 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 | EquatorialRadius () 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 const NormalGravity & | WGS84 ()
static const NormalGravity & | GRS80 ()
static Math::real | J2ToFlattening (real a, real GM, real omega, real J2)
static Math::real | FlatteningToJ2 (real a, real GM, real omega, real f)

## 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, (a2 − b2)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(b2 − a2)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:

- V0, the gravitational contribution to the normal potential;
- Φ, the rotational contribution to the normal potential;
- U = V0 + Φ, the total potential;
- Γ = ∇V0, 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). https://archive.org/details/HeiskanenMoritz1967PhysicalGeodesy
- 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 Normal gravity.

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;
}
}
main
int main(int argc, const char *const argv[])
Definition CartConvert.cpp:28
Constants.hpp
Header for GeographicLib::Constants class.
NormalGravity.hpp
Header for GeographicLib::NormalGravity class.
GeographicLib::Constants::WGS84_omega
static T WGS84_omega()
Definition Constants.hpp:159
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition Constants.hpp:141
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition Constants.hpp:135
GeographicLib::Constants::WGS84_GM
static T WGS84_GM()
Definition Constants.hpp:152
GeographicLib::NormalGravity::NormalGravity
NormalGravity(real a, real GM, real omega, real f_J2, bool geometricp=true)
Definition NormalGravity.cpp:56
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

Definition at line 80 of file NormalGravity.hpp.

## Constructor & Destructor Documentation

## ◆ NormalGravity() [1/2]

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 J2 = (C − A) / Ma2, 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 − (omega2a3/GM) 8/(45π). There is no restriction on omega.

Definition at line 56 of file NormalGravity.cpp.

Referenced by GRS80(), and WGS84().

## ◆ NormalGravity() [2/2]

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 152 of file NormalGravity.hpp.

## Member Function Documentation

## ◆ 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−2).

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 154 of file NormalGravity.cpp.

References GeographicLib::Math::LatFix(), GeographicLib::Math::sind(), and GeographicLib::Math::sq().

## ◆ 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 (m2 s−2).

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 232 of file NormalGravity.cpp.

References U().

## ◆ 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 = V0 + Φ the sum of the gravitational and centrifugal potentials (m2 s−2).

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

Definition at line 223 of file NormalGravity.cpp.

References Phi(), and V0().

Referenced by Gravity().

## ◆ 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
  V0 the gravitational potential (m2 s−2).

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 160 of file NormalGravity.cpp.

References GeographicLib::Math::pi(), GeographicLib::Math::sq(), and std::swap().

Referenced by U().

## ◆ 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 (m2 s−2).

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

Definition at line 216 of file NormalGravity.cpp.

References GeographicLib::Math::sq().

Referenced by U().

## ◆ Init()

bool GeographicLib::NormalGravity::Init | ( |  | ) | const
| inline

Returns
  true if the object has been initialized.

Definition at line 265 of file NormalGravity.hpp.

Referenced by AngularVelocity(), DynamicalFormFactor(), EquatorialGravity(), EquatorialRadius(), Flattening(), GravityFlattening(), MassConstant(), PolarGravity(), and SurfacePotential().

## ◆ EquatorialRadius()

Math::real GeographicLib::NormalGravity::EquatorialRadius | ( |  | ) | const
| inline

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

Definition at line 271 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ MassConstant()

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

Returns
  GM the mass constant of the ellipsoid (m3 s−2). This is the value used in the constructor.

Definition at line 279 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ DynamicalFormFactor()

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

Returns
  Jn the dynamical form factors of the ellipsoid.

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

Definition at line 294 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ AngularVelocity()

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

Returns
  ω the angular velocity of the ellipsoid (rad s−1). This is the value used in the constructor.

Definition at line 301 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ Flattening()

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

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

Definition at line 308 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ EquatorialGravity()

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

Returns
  γe the normal gravity at equator (m s−2).

Definition at line 315 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ PolarGravity()

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

Returns
  γp the normal gravity at poles (m s−2).

Definition at line 322 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ GravityFlattening()

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

Returns
  f* the gravity flattening (γp − γe) / γe.

Definition at line 329 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ SurfacePotential()

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

Returns
  U0 the constant normal potential for the surface of the ellipsoid (m2 s−2).

Definition at line 336 of file NormalGravity.hpp.

References Init(), and GeographicLib::Math::NaN().

## ◆ Earth()

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

Returns
  the Geocentric object used by this instance.

Definition at line 342 of file NormalGravity.hpp.

## ◆ WGS84()

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

A global instantiation of NormalGravity for the WGS84 ellipsoid.

Definition at line 61 of file NormalGravity.cpp.

References NormalGravity(), GeographicLib::Constants::WGS84_a(), GeographicLib::Constants::WGS84_f(), GeographicLib::Constants::WGS84_GM(), and GeographicLib::Constants::WGS84_omega().

## ◆ GRS80()

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

A global instantiation of NormalGravity for the GRS80 ellipsoid.

Definition at line 69 of file NormalGravity.cpp.

References GeographicLib::Constants::GRS80_a(), GeographicLib::Constants::GRS80_GM(), GeographicLib::Constants::GRS80_J2(), GeographicLib::Constants::GRS80_omega(), and NormalGravity().

## ◆ 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 − omega2a3/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 245 of file NormalGravity.cpp.

References GEOGRAPHICLIB_PANIC, GeographicLib::Math::NaN(), GeographicLib::Math::pi(), and GeographicLib::Math::sq().

## ◆ 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 287 of file NormalGravity.cpp.

References GeographicLib::Math::sq().

## Friends And Related Symbol Documentation

## ◆ GravityModel

friend class GravityModel
| friend

Definition at line 84 of file NormalGravity.hpp.

References GravityModel.

Referenced by GravityModel.

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

- NormalGravity.hpp
- NormalGravity.cpp