GeographicLib: GeographicLib::GravityModel Class Reference

GeographicLib 2.7

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

Model of the earth's gravity field. More...

`#include <GeographicLib/GravityModel.hpp>`

## Public Types
enum | mask { NONE , GRAVITY , DISTURBANCE , DISTURBING_POTENTIAL , SPHERICAL_ANOMALY , GEOID_HEIGHT , ALL }

## Public Member Functions
| GravityModel (GravityModel &&)=default
GravityModel & | operator= (GravityModel &&)=default
Setting up the gravity model
| GravityModel (const std::string &name, const std::string &path="", int Nmax=-1, int Mmax=-1)
Compute gravity in geodetic coordinates
Math::real | Gravity (real lat, real lon, real h, real &gx, real &gy, real &gz) const
Math::real | Disturbance (real lat, real lon, real h, real &deltax, real &deltay, real &deltaz) const
Math::real | GeoidHeight (real lat, real lon) const
void | SphericalAnomaly (real lat, real lon, real h, real &Dg01, real &xi, real &eta) const
Compute gravity in geocentric coordinates
Math::real | W (real X, real Y, real Z, real &gX, real &gY, real &gZ) const
Math::real | V (real X, real Y, real Z, real &GX, real &GY, real &GZ) const
Math::real | T (real X, real Y, real Z, real &deltaX, real &deltaY, real &deltaZ) const
Math::real | T (real X, real Y, real Z) const
Math::real | U (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
Compute gravity on a circle of constant latitude
GravityCircle | Circle (real lat, real h, unsigned caps=ALL) const
Inspector functions
const NormalGravity & | ReferenceEllipsoid () const
const std::string & | Description () const
const std::string & | DateTime () const
const std::string & | GravityFile () const
const std::string & | GravityModelName () const
const std::string & | GravityModelDirectory () const
Math::real | EquatorialRadius () const
Math::real | MassConstant () const
Math::real | ReferenceMassConstant () const
Math::real | AngularVelocity () const
Math::real | Flattening () const
int | Degree () const
int | Order () const

## Static Public Member Functions
static std::string | DefaultGravityPath ()
static std::string | DefaultGravityName ()

## Friends
class | GravityCircle

## Detailed Description

Model of the earth's gravity field.

Evaluate the earth's gravity field according to a model. The supported models treat only the gravitational field exterior to the mass of the earth. When computing the field at points near (but above) the surface of the earth a small correction can be applied to account for the mass of the atmosphere above the point in question; see The effect of the mass of the atmosphere. Determining the height of the geoid above the ellipsoid entails correcting for the mass of the earth above the geoid. The egm96 and egm2008 include separate correction terms to account for this mass.

Definitions and terminology (from Heiskanen and Moritz, Sec 2-13):

- V = gravitational potential;
- Φ = rotational potential;
- W = V + Φ = T + U = total potential;
- V0 = normal gravitation potential;
- U = V0 + Φ = total normal potential;
- T = W − U = V − V0 = anomalous or disturbing potential;
- g = ∇W = γ + δ;
- f = ∇Φ;
- Γ = ∇V0;
- γ = ∇U;
- δ = ∇T = gravity disturbance vector = gP − γP;
- δg = gravity disturbance = gP − γP;
- Δg = gravity anomaly vector = gP − γQ; here the line PQ is perpendicular to ellipsoid and the potential at P equals the normal potential at Q;
- Δg = gravity anomaly = gP − γQ;
- (ξ, η) deflection of the vertical, the difference in directions of gP and γQ, ξ = NS, η = EW.
- X, Y, Z, geocentric coordinates;
- x, y, z, local cartesian coordinates used to denote the east, north and up directions.

See Gravity models for details of how to install the gravity models and the data format.

References:

- W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San Francisco, 1967).

Example of use:

// Example of using the GeographicLib::GravityModel class
// This requires that the egm96 gravity model be installed; see
// https://geographiclib.sourceforge.io/C++/doc/gravity.html#gravityinst
#include <iostream>
#include <exception>
#include <GeographicLib/GravityModel.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
GravityModel grav("egm96");
double lat = 27.99, lon = 86.93, h = 8820; // Mt Everest
double gx, gy, gz;
grav.Gravity(lat,lon, h, gx, gy, gz);
cout << gx << " " << gy << " " << gz << "\n";
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition Cart3Convert.cpp:52
GravityModel.hpp
Header for GeographicLib::GravityModel class.
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

Gravity is a command-line utility providing access to the functionality of GravityModel and GravityCircle.

Definition at line 83 of file GravityModel.hpp.

## Member Enumeration Documentation

## ◆ mask

enum GeographicLib::GravityModel::mask

Bit masks for the capabilities to be given to the GravityCircle object produced by Circle.

Enumerator
NONE | No capabilities.
GRAVITY | Allow calls to GravityCircle::Gravity, GravityCircle::W, and GravityCircle::V.
DISTURBANCE | Allow calls to GravityCircle::Disturbance and GravityCircle::T.
DISTURBING_POTENTIAL | Allow calls to GravityCircle::T(real lon) (i.e., computing the disturbing potential and not the gravity disturbance vector).
SPHERICAL_ANOMALY | Allow calls to GravityCircle::SphericalAnomaly.
GEOID_HEIGHT | Allow calls to GravityCircle::GeoidHeight.
ALL | All capabilities.

Definition at line 123 of file GravityModel.hpp.

## Constructor & Destructor Documentation

## ◆ GravityModel() [1/2]

GeographicLib::GravityModel::GravityModel | ( | GravityModel && |  | ) |
| default

Move constructs a gravity model.

## ◆ GravityModel() [2/2]

GeographicLib::GravityModel::GravityModel | ( | const std::string & | name,
|  | const std::string & | path = "",
|  | int | Nmax = -1,
|  | int | Mmax = -1 )
| explicit

Construct a gravity model.

Parameters

  [in] | name | the name of the model.
  [in] | path | (optional) directory for data file.
  [in] | Nmax | (optional) if nonnegative, truncate the degree of the model this value.
  [in] | Mmax | (optional) if nonnegative, truncate the order of the model this value.

Exceptions

  GeographicErr | if the data file cannot be found, is unreadable, or is corrupt, or if Mmax > Nmax.
  std::bad_alloc | if the memory necessary for storing the model can't be allocated.

A filename is formed by appending ".egm" (World Gravity Model) to the name. If path is specified (and is non-empty), then the file is loaded from directory, path. Otherwise the path is given by DefaultGravityPath().

This file contains the metadata which specifies the properties of the model. The coefficients for the spherical harmonic sums are obtained from a file obtained by appending ".cof" to metadata file (so the filename ends in ".egm.cof").

If Nmax ≥ 0 and Mmax < 0, then Mmax is set to Nmax. After the model is loaded, the maximum degree and order of the model can be found by the Degree() and Order() methods.

Definition at line 38 of file GravityModel.cpp.

References DefaultGravityPath(), GeographicLib::SphericalEngine::coeff::readcoeffs(), and GeographicLib::Math::sq().

## Member Function Documentation

## ◆ operator=()

GravityModel & GeographicLib::GravityModel::operator= | ( | GravityModel && |  | ) |
| default

Move assigns a gravity model.

References Disturbance(), GeoidHeight(), Gravity(), SphericalAnomaly(), V(), and W().

## ◆ Gravity()

Math::real GeographicLib::GravityModel::Gravity | ( | real | lat,
|  | real | lon,
|  | real | h,
|  | real & | gx,
|  | real & | gy,
|  | real & | gz ) const

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

Parameters

  [in] | lat | the geographic latitude (degrees).
  [in] | lon | the geographic longitude (degrees).
  [in] | h | the height above the ellipsoid (meters).
  [out] | gx | the easterly component of the acceleration (m s−2).
  [out] | gy | the northerly component of the acceleration (m s−2).
  [out] | gz | the upward component of the acceleration (m s−2); this is usually negative.

Returns
  W the sum of the gravitational and centrifugal potentials (m2 s−2).

The function includes the effects of the earth's rotation.

Definition at line 304 of file GravityModel.cpp.

References W().

Referenced by main(), and operator=().

## ◆ Disturbance()

Math::real GeographicLib::GravityModel::Disturbance | ( | real | lat,
|  | real | lon,
|  | real | h,
|  | real & | deltax,
|  | real & | deltay,
|  | real & | deltaz ) const

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

Parameters

  [in] | lat | the geographic latitude (degrees).
  [in] | lon | the geographic longitude (degrees).
  [in] | h | the height above the ellipsoid (meters).
  [out] | deltax | the easterly component of the disturbance vector (m s−2).
  [out] | deltay | the northerly component of the disturbance vector (m s−2).
  [out] | deltaz | the upward component of the disturbance vector (m s−2).

Returns
  T the corresponding disturbing potential (m2 s−2).

Definition at line 312 of file GravityModel.cpp.

Referenced by main(), and operator=().

## ◆ GeoidHeight()

Math::real GeographicLib::GravityModel::GeoidHeight | ( | real | lat,
|  | real | lon ) const

Evaluate the geoid height.

Parameters

  [in] | lat | the geographic latitude (degrees).
  [in] | lon | the geographic longitude (degrees).

Returns
  N the height of the geoid above the ReferenceEllipsoid() (meters).

This calls NormalGravity::U for ReferenceEllipsoid(). Some approximations are made in computing the geoid height so that the results of the NGA codes are reproduced accurately. Details are given in Details of the geoid height and anomaly calculations.

Definition at line 290 of file GravityModel.cpp.

References T().

Referenced by main(), and operator=().

## ◆ SphericalAnomaly()

void GeographicLib::GravityModel::SphericalAnomaly | ( | real | lat,
|  | real | lon,
|  | real | h,
|  | real & | Dg01,
|  | real & | xi,
|  | real & | eta ) const

Evaluate the components of the gravity anomaly vector using the spherical approximation.

Parameters

  [in] | lat | the geographic latitude (degrees).
  [in] | lon | the geographic longitude (degrees).
  [in] | h | the height above the ellipsoid (meters).
  [out] | Dg01 | the gravity anomaly (m s−2).
  [out] | xi | the northerly component of the deflection of the vertical (degrees).
  [out] | eta | the easterly component of the deflection of the vertical (degrees).

The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used so that the results of the NGA codes are reproduced accurately. approximations used here. Details are given in Details of the geoid height and anomaly calculations.

Definition at line 264 of file GravityModel.cpp.

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

Referenced by main(), and operator=().

## ◆ W()

Math::real GeographicLib::GravityModel::W | ( | real | X,
|  | real | Y,
|  | real | Z,
|  | real & | gX,
|  | real & | gY,
|  | real & | gZ ) 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] | gX | the X component of the acceleration (m s−2).
  [out] | gY | the Y component of the acceleration (m s−2).
  [out] | gZ | the Z component of the acceleration (m s−2).

Returns
  W = V + Φ the sum of the gravitational and centrifugal potentials (m2 s−2).

This calls NormalGravity::U for ReferenceEllipsoid().

Definition at line 255 of file GravityModel.cpp.

References V().

Referenced by Gravity(), and operator=().

## ◆ V()

Math::real GeographicLib::GravityModel::V | ( | real | X,
|  | real | Y,
|  | real | Z,
|  | real & | GX,
|  | real & | GY,
|  | real & | GZ ) const

Evaluate the components of the acceleration due to gravity 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] | GX | the X component of the acceleration (m s−2).
  [out] | GY | the Y component of the acceleration (m s−2).
  [out] | GZ | the Z component of the acceleration (m s−2).

Returns
  V = W - Φ the gravitational potential (m2 s−2).

Definition at line 243 of file GravityModel.cpp.

Referenced by operator=(), and W().

## ◆ T() [1/2]

Math::real GeographicLib::GravityModel::T | ( | real | X,
|  | real | Y,
|  | real | Z,
|  | real & | deltaX,
|  | real & | deltaY,
|  | real & | deltaZ ) const
| inline

Evaluate the components of the gravity disturbance 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] | deltaX | the X component of the gravity disturbance (m s−2).
  [out] | deltaY | the Y component of the gravity disturbance (m s−2).
  [out] | deltaZ | the Z component of the gravity disturbance (m s−2).

Returns
  T = W - U the disturbing potential (also called the anomalous potential) (m2 s−2).

Definition at line 348 of file GravityModel.hpp.

Referenced by GeoidHeight(), and SphericalAnomaly().

## ◆ T() [2/2]

Math::real GeographicLib::GravityModel::T | ( | real | X,
|  | real | Y,
|  | real | Z ) const
| inline

Evaluate disturbing potential 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).

Returns
  T = W - U the disturbing potential (also called the anomalous potential) (m2 s−2).

Definition at line 361 of file GravityModel.hpp.

## ◆ U()

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

Evaluate the components of the acceleration due to normal 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 normal acceleration (m s−2).
  [out] | gammaY | the Y component of the normal acceleration (m s−2).
  [out] | gammaZ | the Z component of the normal acceleration (m s−2).

Returns
  U = V0 + Φ the sum of the normal gravitational and centrifugal potentials (m2 s−2).

This calls NormalGravity::U for ReferenceEllipsoid().

Definition at line 385 of file GravityModel.hpp.

Referenced by GravityCircle.

## ◆ Phi()

Math::real GeographicLib::GravityModel::Phi | ( | real | X,
|  | real | Y,
|  | real & | fX,
|  | real & | fY ) const
| inline

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

This calls NormalGravity::Phi for ReferenceEllipsoid().

Definition at line 403 of file GravityModel.hpp.

## ◆ Circle()

GravityCircle GeographicLib::GravityModel::Circle | ( | real | lat,
|  | real | h,
|  | unsigned | caps = ALL ) const

Create a GravityCircle object to allow the gravity field at many points with constant lat and h and varying lon to be computed efficiently.

Parameters

  [in] | lat | latitude of the point (degrees).
  [in] | h | the height of the point above the ellipsoid (meters).
  [in] | caps | bitor'ed combination of GravityModel::mask values specifying the capabilities of the resulting GravityCircle object.

Exceptions

  std::bad_alloc | if the memory necessary for creating a GravityCircle can't be allocated.

Returns
  a GravityCircle object whose member functions computes the gravitational field at a particular values of lon.

The GravityModel::mask values are

- caps |= GravityModel::GRAVITY
- caps |= GravityModel::DISTURBANCE
- caps |= GravityModel::DISTURBING_POTENTIAL
- caps |= GravityModel::SPHERICAL_ANOMALY
- caps |= GravityModel::GEOID_HEIGHT

The default value of caps is GravityModel::ALL which turns on all the capabilities. If an unsupported function is invoked, it will return NaNs. Note that GravityModel::GEOID_HEIGHT will only be honored if h = 0.

If the field at several points on a circle of latitude need to be calculated then creating a GravityCircle object and using its member functions will be substantially faster, especially for high-degree models. See Geoid heights on a multi-processor system for an example of using GravityCircle (together with OpenMP) to speed up the computation of geoid heights.

Definition at line 322 of file GravityModel.cpp.

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

Referenced by main().

## ◆ ReferenceEllipsoid()

const NormalGravity & GeographicLib::GravityModel::ReferenceEllipsoid | ( |  | ) | const
| inline

Returns
  the NormalGravity object for the reference ellipsoid.

Definition at line 452 of file GravityModel.hpp.

## ◆ Description()

const std::string & GeographicLib::GravityModel::Description | ( |  | ) | const
| inline

Returns
  the description of the gravity model, if available, in the data file; if absent, return "NONE".

Definition at line 458 of file GravityModel.hpp.

Referenced by main().

## ◆ DateTime()

const std::string & GeographicLib::GravityModel::DateTime | ( |  | ) | const
| inline

Returns
  date of the model; if absent, return "UNKNOWN".

Definition at line 463 of file GravityModel.hpp.

Referenced by main().

## ◆ GravityFile()

const std::string & GeographicLib::GravityModel::GravityFile | ( |  | ) | const
| inline

Returns
  full file name used to load the gravity model.

Definition at line 468 of file GravityModel.hpp.

Referenced by main().

## ◆ GravityModelName()

const std::string & GeographicLib::GravityModel::GravityModelName | ( |  | ) | const
| inline

Returns
  "name" used to load the gravity model (from the first argument of the constructor, but this may be overridden by the model file).

Definition at line 474 of file GravityModel.hpp.

Referenced by main().

## ◆ GravityModelDirectory()

const std::string & GeographicLib::GravityModel::GravityModelDirectory | ( |  | ) | const
| inline

Returns
  directory used to load the gravity model.

Definition at line 479 of file GravityModel.hpp.

## ◆ EquatorialRadius()

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

Returns
  a the equatorial radius of the ellipsoid (meters).

Definition at line 484 of file GravityModel.hpp.

## ◆ MassConstant()

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

Returns
  GM the mass constant of the model (m3 s−2); 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).

Definition at line 492 of file GravityModel.hpp.

## ◆ ReferenceMassConstant()

Math::real GeographicLib::GravityModel::ReferenceMassConstant | ( |  | ) | const
| inline

Returns
  GM the mass constant of the ReferenceEllipsoid() (m3 s−2).

Definition at line 498 of file GravityModel.hpp.

## ◆ AngularVelocity()

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

Returns
  ω the angular velocity of the model and the ReferenceEllipsoid() (rad s−1).

Definition at line 505 of file GravityModel.hpp.

## ◆ Flattening()

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

Returns
  f the flattening of the ellipsoid.

Definition at line 511 of file GravityModel.hpp.

## ◆ Degree()

int GeographicLib::GravityModel::Degree | ( |  | ) | const
| inline

Returns
  Nmax the maximum degree of the components of the model.

Definition at line 516 of file GravityModel.hpp.

## ◆ Order()

int GeographicLib::GravityModel::Order | ( |  | ) | const
| inline

Returns
  Mmax the maximum order of the components of the model.

Definition at line 521 of file GravityModel.hpp.

## ◆ DefaultGravityPath()

string GeographicLib::GravityModel::DefaultGravityPath | ( |  | ) |
| static

Returns
  the default path for gravity model data files.

This is the value of the environment variable GEOGRAPHICLIB_GRAVITY_PATH, if set; otherwise, it is $GEOGRAPHICLIB_DATA/gravity if the environment variable GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default (/usr/local/share/GeographicLib/gravity on non-Windows systems and C:/ProgramData/GeographicLib/gravity on Windows systems).

Definition at line 356 of file GravityModel.cpp.

References GEOGRAPHICLIB_DATA.

Referenced by GravityModel(), and main().

## ◆ DefaultGravityName()

string GeographicLib::GravityModel::DefaultGravityName | ( |  | ) |
| static

Returns
  the default name for the gravity model.

This is the value of the environment variable GEOGRAPHICLIB_GRAVITY_NAME, if set; otherwise, it is "egm96". The GravityModel class does not use this function; it is just provided as a convenience for a calling program when constructing a GravityModel object.

Definition at line 369 of file GravityModel.cpp.

References GEOGRAPHICLIB_GRAVITY_DEFAULT_NAME.

Referenced by main().

## Friends And Related Symbol Documentation

## ◆ GravityCircle

friend class GravityCircle
| friend

Definition at line 86 of file GravityModel.hpp.

References GravityCircle, and U().

Referenced by Circle(), and GravityCircle.

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

- GravityModel.hpp
- GravityModel.cpp