GeographicLib::NormalGravity Class Reference

The normal gravity of the earth. More...

#include <GeographicLib/NormalGravity.hpp>

List of all members.

Public Member Functions

Setting up the normal gravity



 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 GeocentricEarth () const

Static Public Member Functions

static const NormalGravityWGS84 ()
static const NormalGravityGRS80 ()
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 surface of the ellipsoid is a surface of constant potential (gravitational plus centrifugal). The acceleration due to gravity is therefore perpendicular to the surface of the ellipsoid.

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 two leading terms. However these series include sufficient terms to give full machine precision.

Definitions:

References:

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(), 0);
    // 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;
  }
  return 0;
}

Definition at line 60 of file NormalGravity.hpp.


Constructor & Destructor Documentation

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

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 s1).
[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 J2 = (C A) / Ma2, 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 21 of file NormalGravity.cpp.

References FlatteningToJ2(), GeographicLib::Math::isfinite(), and J2ToFlattening().

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


Member Function Documentation

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 s2).

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

References GeographicLib::Math::degree(), and GeographicLib::Math::sq().

Referenced by GeographicLib::GravityModel::Circle(), and GeographicLib::GravityModel::GeoidHeight().

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 s2).
[out] gammaz the upward component of the acceleration (m s2); this is usually negative.
Returns:
U the corresponding normal potential.

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

References 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 s2).
[out] gammaY the Y component of the acceleration (m s2).
[out] gammaZ the Z component of the acceleration (m s2).
Returns:
U = V0 + the sum of the gravitational and centrifugal potentials (m2 s2).

The acceleration given by = U = V0 + = + f.

Definition at line 209 of file NormalGravity.cpp.

References Phi(), and V0().

Referenced by GeographicLib::GravityModel::Circle(), Gravity(), and GeographicLib::GravityModel::SphericalAnomaly().

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 gravity alone 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 gravity (m s2).
[out] GammaY the Y component of the acceleration due to gravity (m s2).
[out] GammaZ the Z component of the acceleration due to gravity (m s2).
Returns:
V0 the gravitational potential (m2 s2).

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

References GeographicLib::Math::hypot(), and GeographicLib::Math::sq().

Referenced by U().

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 s2).
[out] fY the Y component of the centrifugal acceleration (m s2).
Returns:
the centrifugal potential (m2 s2).

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

Definition at line 201 of file NormalGravity.cpp.

References GeographicLib::Math::sq().

Referenced by GeographicLib::GravityModel::Circle(), U(), and GeographicLib::GravityModel::W().

bool GeographicLib::NormalGravity::Init (  )  const [inline]
Returns:
true if the object has been initialized.

Definition at line 229 of file NormalGravity.hpp.

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

References GeographicLib::Math::NaN().

Math::real GeographicLib::NormalGravity::MassConstant (  )  const [inline]
Returns:
GM the mass constant of the ellipsoid (m3 s2). This is the value used in the constructor.

Definition at line 243 of file NormalGravity.hpp.

References GeographicLib::Math::NaN().

Referenced by GeographicLib::GravityModel::GravityModel().

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

References GeographicLib::Math::NaN().

Math::real GeographicLib::NormalGravity::AngularVelocity (  )  const [inline]
Returns:
the angular velocity of the ellipsoid (rad s1). This is the value used in the constructor.

Definition at line 265 of file NormalGravity.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::NormalGravity::Flattening (  )  const [inline]
Returns:
f the flattening of the ellipsoid (a b)/a.

Definition at line 272 of file NormalGravity.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::NormalGravity::EquatorialGravity (  )  const [inline]
Returns:
e the normal gravity at equator (m s2).

Definition at line 279 of file NormalGravity.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::NormalGravity::PolarGravity (  )  const [inline]
Returns:
p the normal gravity at poles (m s2).

Definition at line 286 of file NormalGravity.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::NormalGravity::GravityFlattening (  )  const [inline]
Returns:
f* the gravity flattening (p e) / e.

Definition at line 293 of file NormalGravity.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::NormalGravity::SurfacePotential (  )  const [inline]
Returns:
U0 the constant normal potential for the surface of the ellipsoid (m2 s2).

Definition at line 300 of file NormalGravity.hpp.

References GeographicLib::Math::NaN().

const Geocentric& GeographicLib::NormalGravity::Earth (  )  const [inline]
const NormalGravity & GeographicLib::NormalGravity::WGS84 (  )  [static]
const NormalGravity & GeographicLib::NormalGravity::GRS80 (  )  [static]
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 s1).
[in] J2 the dynamical form factor.
Returns:
f the flattening of the ellipsoid.

Definition at line 233 of file NormalGravity.cpp.

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

Referenced by NormalGravity().

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 s1).
[in] f the flattening of the ellipsoid.
Returns:
J2 the dynamical form factor.

Definition at line 254 of file NormalGravity.cpp.

References GeographicLib::Math::sq().

Referenced by NormalGravity().


Friends And Related Function Documentation

friend class GravityModel [friend]

Definition at line 64 of file NormalGravity.hpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 6 Oct 2014 for GeographicLib by  doxygen 1.6.1