GeographicLib  1.48
GravityModel.hpp
Go to the documentation of this file.
1 /**
2  * \file GravityModel.hpp
3  * \brief Header for GeographicLib::GravityModel class
4  *
5  * Copyright (c) Charles Karney (2011-2016) <charles@karney.com> and licensed
6  * under the MIT/X11 License. For more information, see
7  * https://geographiclib.sourceforge.io/
8  **********************************************************************/
9 
10 #if !defined(GEOGRAPHICLIB_GRAVITYMODEL_HPP)
11 #define GEOGRAPHICLIB_GRAVITYMODEL_HPP 1
12 
17 
18 #if defined(_MSC_VER)
19 // Squelch warnings about dll vs vector
20 # pragma warning (push)
21 # pragma warning (disable: 4251)
22 #endif
23 
24 namespace GeographicLib {
25 
26  class GravityCircle;
27 
28  /**
29  * \brief Model of the earth's gravity field
30  *
31  * Evaluate the earth's gravity field according to a model. The supported
32  * models treat only the gravitational field exterior to the mass of the
33  * earth. When computing the field at points near (but above) the surface of
34  * the earth a small correction can be applied to account for the mass of the
35  * atomsphere above the point in question; see \ref gravityatmos.
36  * Determining the height of the geoid above the ellipsoid entails correcting
37  * for the mass of the earth above the geoid. The egm96 and egm2008 include
38  * separate correction terms to account for this mass.
39  *
40  * Definitions and terminology (from Heiskanen and Moritz, Sec 2-13):
41  * - \e V = gravitational potential;
42  * - &Phi; = rotational potential;
43  * - \e W = \e V + &Phi; = \e T + \e U = total potential;
44  * - <i>V</i><sub>0</sub> = normal gravitation potential;
45  * - \e U = <i>V</i><sub>0</sub> + &Phi; = total normal potential;
46  * - \e T = \e W &minus; \e U = \e V &minus; <i>V</i><sub>0</sub> = anomalous
47  * or disturbing potential;
48  * - <b>g</b> = &nabla;\e W = <b>&gamma;</b> + <b>&delta;</b>;
49  * - <b>f</b> = &nabla;&Phi;;
50  * - <b>&Gamma;</b> = &nabla;<i>V</i><sub>0</sub>;
51  * - <b>&gamma;</b> = &nabla;\e U;
52  * - <b>&delta;</b> = &nabla;\e T = gravity disturbance vector
53  * = <b>g</b><sub><i>P</i></sub> &minus; <b>&gamma;</b><sub><i>P</i></sub>;
54  * - &delta;\e g = gravity disturbance = <i>g</i><sub><i>P</i></sub> &minus;
55  * &gamma;<sub><i>P</i></sub>;
56  * - &Delta;<b>g</b> = gravity anomaly vector = <b>g</b><sub><i>P</i></sub>
57  * &minus; <b>&gamma;</b><sub><i>Q</i></sub>; here the line \e PQ is
58  * perpendicular to ellipsoid and the potential at \e P equals the normal
59  * potential at \e Q;
60  * - &Delta;\e g = gravity anomaly = <i>g</i><sub><i>P</i></sub> &minus;
61  * &gamma;<sub><i>Q</i></sub>;
62  * - (&xi;, &eta;) deflection of the vertical, the difference in
63  * directions of <b>g</b><sub><i>P</i></sub> and
64  * <b>&gamma;</b><sub><i>Q</i></sub>, &xi; = NS, &eta; = EW.
65  * - \e X, \e Y, \e Z, geocentric coordinates;
66  * - \e x, \e y, \e z, local cartesian coordinates used to denote the east,
67  * north and up directions.
68  *
69  * See \ref gravity for details of how to install the gravity models and the
70  * data format.
71  *
72  * References:
73  * - W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San
74  * Francisco, 1967).
75  *
76  * Example of use:
77  * \include example-GravityModel.cpp
78  *
79  * <a href="Gravity.1.html">Gravity</a> is a command-line utility providing
80  * access to the functionality of GravityModel and GravityCircle.
81  **********************************************************************/
82 
84  private:
85  typedef Math::real real;
86  friend class GravityCircle;
87  static const int idlength_ = 8;
88  std::string _name, _dir, _description, _date, _filename, _id;
89  real _amodel, _GMmodel, _zeta0, _corrmult;
91  NormalGravity _earth;
92  std::vector<real> _Cx, _Sx, _CC, _CS, _zonal;
93  real _dzonal0; // A left over contribution to _zonal.
94  SphericalHarmonic _gravitational;
95  SphericalHarmonic1 _disturbing;
96  SphericalHarmonic _correction;
97  void ReadMetadata(const std::string& name);
98  Math::real InternalT(real X, real Y, real Z,
99  real& deltaX, real& deltaY, real& deltaZ,
100  bool gradp, bool correct) const;
101  GravityModel(const GravityModel&); // copy constructor not allowed
102  GravityModel& operator=(const GravityModel&); // nor copy assignment
103 
104  enum captype {
105  CAP_NONE = 0U,
106  CAP_G = 1U<<0, // implies potentials W and V
107  CAP_T = 1U<<1,
108  CAP_DELTA = 1U<<2 | CAP_T, // delta implies T?
109  CAP_C = 1U<<3,
110  CAP_GAMMA0 = 1U<<4,
111  CAP_GAMMA = 1U<<5,
112  CAP_ALL = 0x3FU,
113  };
114 
115  public:
116 
117  /**
118  * Bit masks for the capabilities to be given to the GravityCircle object
119  * produced by Circle.
120  **********************************************************************/
121  enum mask {
122  /**
123  * No capabilities.
124  * @hideinitializer
125  **********************************************************************/
126  NONE = 0U,
127  /**
128  * Allow calls to GravityCircle::Gravity, GravityCircle::W, and
129  * GravityCircle::V.
130  * @hideinitializer
131  **********************************************************************/
132  GRAVITY = CAP_G,
133  /**
134  * Allow calls to GravityCircle::Disturbance and GravityCircle::T.
135  * @hideinitializer
136  **********************************************************************/
137  DISTURBANCE = CAP_DELTA,
138  /**
139  * Allow calls to GravityCircle::T(real lon) (i.e., computing the
140  * disturbing potential and not the gravity disturbance vector).
141  * @hideinitializer
142  **********************************************************************/
143  DISTURBING_POTENTIAL = CAP_T,
144  /**
145  * Allow calls to GravityCircle::SphericalAnomaly.
146  * @hideinitializer
147  **********************************************************************/
148  SPHERICAL_ANOMALY = CAP_DELTA | CAP_GAMMA,
149  /**
150  * Allow calls to GravityCircle::GeoidHeight.
151  * @hideinitializer
152  **********************************************************************/
153  GEOID_HEIGHT = CAP_T | CAP_C | CAP_GAMMA0,
154  /**
155  * All capabilities.
156  * @hideinitializer
157  **********************************************************************/
158  ALL = CAP_ALL,
159  };
160  /** \name Setting up the gravity model
161  **********************************************************************/
162  ///@{
163  /**
164  * Construct a gravity model.
165  *
166  * @param[in] name the name of the model.
167  * @param[in] path (optional) directory for data file.
168  * @exception GeographicErr if the data file cannot be found, is
169  * unreadable, or is corrupt.
170  * @exception std::bad_alloc if the memory necessary for storing the model
171  * can't be allocated.
172  *
173  * A filename is formed by appending ".egm" (World Gravity Model) to the
174  * name. If \e path is specified (and is non-empty), then the file is
175  * loaded from directory, \e path. Otherwise the path is given by
176  * DefaultGravityPath().
177  *
178  * This file contains the metadata which specifies the properties of the
179  * model. The coefficients for the spherical harmonic sums are obtained
180  * from a file obtained by appending ".cof" to metadata file (so the
181  * filename ends in ".egm.cof").
182  **********************************************************************/
183  explicit GravityModel(const std::string& name,
184  const std::string& path = "");
185  ///@}
186 
187  /** \name Compute gravity in geodetic coordinates
188  **********************************************************************/
189  ///@{
190  /**
191  * Evaluate the gravity at an arbitrary point above (or below) the
192  * ellipsoid.
193  *
194  * @param[in] lat the geographic latitude (degrees).
195  * @param[in] lon the geographic longitude (degrees).
196  * @param[in] h the height above the ellipsoid (meters).
197  * @param[out] gx the easterly component of the acceleration
198  * (m s<sup>&minus;2</sup>).
199  * @param[out] gy the northerly component of the acceleration
200  * (m s<sup>&minus;2</sup>).
201  * @param[out] gz the upward component of the acceleration
202  * (m s<sup>&minus;2</sup>); this is usually negative.
203  * @return \e W the sum of the gravitational and centrifugal potentials
204  * (m<sup>2</sup> s<sup>&minus;2</sup>).
205  *
206  * The function includes the effects of the earth's rotation.
207  **********************************************************************/
208  Math::real Gravity(real lat, real lon, real h,
209  real& gx, real& gy, real& gz) const;
210 
211  /**
212  * Evaluate the gravity disturbance vector at an arbitrary point above (or
213  * below) the ellipsoid.
214  *
215  * @param[in] lat the geographic latitude (degrees).
216  * @param[in] lon the geographic longitude (degrees).
217  * @param[in] h the height above the ellipsoid (meters).
218  * @param[out] deltax the easterly component of the disturbance vector
219  * (m s<sup>&minus;2</sup>).
220  * @param[out] deltay the northerly component of the disturbance vector
221  * (m s<sup>&minus;2</sup>).
222  * @param[out] deltaz the upward component of the disturbance vector
223  * (m s<sup>&minus;2</sup>).
224  * @return \e T the corresponding disturbing potential
225  * (m<sup>2</sup> s<sup>&minus;2</sup>).
226  **********************************************************************/
227  Math::real Disturbance(real lat, real lon, real h,
228  real& deltax, real& deltay, real& deltaz)
229  const;
230 
231  /**
232  * Evaluate the geoid height.
233  *
234  * @param[in] lat the geographic latitude (degrees).
235  * @param[in] lon the geographic longitude (degrees).
236  * @return \e N the height of the geoid above the ReferenceEllipsoid()
237  * (meters).
238  *
239  * This calls NormalGravity::U for ReferenceEllipsoid(). Some
240  * approximations are made in computing the geoid height so that the
241  * results of the NGA codes are reproduced accurately. Details are given
242  * in \ref gravitygeoid.
243  **********************************************************************/
244  Math::real GeoidHeight(real lat, real lon) const;
245 
246  /**
247  * Evaluate the components of the gravity anomaly vector using the
248  * spherical approximation.
249  *
250  * @param[in] lat the geographic latitude (degrees).
251  * @param[in] lon the geographic longitude (degrees).
252  * @param[in] h the height above the ellipsoid (meters).
253  * @param[out] Dg01 the gravity anomaly (m s<sup>&minus;2</sup>).
254  * @param[out] xi the northerly component of the deflection of the vertical
255  * (degrees).
256  * @param[out] eta the easterly component of the deflection of the vertical
257  * (degrees).
258  *
259  * The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used
260  * so that the results of the NGA codes are reproduced accurately.
261  * approximations used here. Details are given in \ref gravitygeoid.
262  **********************************************************************/
263  void SphericalAnomaly(real lat, real lon, real h,
264  real& Dg01, real& xi, real& eta) const;
265  ///@}
266 
267  /** \name Compute gravity in geocentric coordinates
268  **********************************************************************/
269  ///@{
270  /**
271  * Evaluate the components of the acceleration due to gravity and the
272  * centrifugal acceleration in geocentric coordinates.
273  *
274  * @param[in] X geocentric coordinate of point (meters).
275  * @param[in] Y geocentric coordinate of point (meters).
276  * @param[in] Z geocentric coordinate of point (meters).
277  * @param[out] gX the \e X component of the acceleration
278  * (m s<sup>&minus;2</sup>).
279  * @param[out] gY the \e Y component of the acceleration
280  * (m s<sup>&minus;2</sup>).
281  * @param[out] gZ the \e Z component of the acceleration
282  * (m s<sup>&minus;2</sup>).
283  * @return \e W = \e V + &Phi; the sum of the gravitational and
284  * centrifugal potentials (m<sup>2</sup> s<sup>&minus;2</sup>).
285  *
286  * This calls NormalGravity::U for ReferenceEllipsoid().
287  **********************************************************************/
288  Math::real W(real X, real Y, real Z,
289  real& gX, real& gY, real& gZ) const;
290 
291  /**
292  * Evaluate the components of the acceleration due to gravity in geocentric
293  * coordinates.
294  *
295  * @param[in] X geocentric coordinate of point (meters).
296  * @param[in] Y geocentric coordinate of point (meters).
297  * @param[in] Z geocentric coordinate of point (meters).
298  * @param[out] GX the \e X component of the acceleration
299  * (m s<sup>&minus;2</sup>).
300  * @param[out] GY the \e Y component of the acceleration
301  * (m s<sup>&minus;2</sup>).
302  * @param[out] GZ the \e Z component of the acceleration
303  * (m s<sup>&minus;2</sup>).
304  * @return \e V = \e W - &Phi; the gravitational potential
305  * (m<sup>2</sup> s<sup>&minus;2</sup>).
306  **********************************************************************/
307  Math::real V(real X, real Y, real Z,
308  real& GX, real& GY, real& GZ) const;
309 
310  /**
311  * Evaluate the components of the gravity disturbance in geocentric
312  * coordinates.
313  *
314  * @param[in] X geocentric coordinate of point (meters).
315  * @param[in] Y geocentric coordinate of point (meters).
316  * @param[in] Z geocentric coordinate of point (meters).
317  * @param[out] deltaX the \e X component of the gravity disturbance
318  * (m s<sup>&minus;2</sup>).
319  * @param[out] deltaY the \e Y component of the gravity disturbance
320  * (m s<sup>&minus;2</sup>).
321  * @param[out] deltaZ the \e Z component of the gravity disturbance
322  * (m s<sup>&minus;2</sup>).
323  * @return \e T = \e W - \e U the disturbing potential (also called the
324  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
325  **********************************************************************/
326  Math::real T(real X, real Y, real Z,
327  real& deltaX, real& deltaY, real& deltaZ) const
328  { return InternalT(X, Y, Z, deltaX, deltaY, deltaZ, true, true); }
329 
330  /**
331  * Evaluate disturbing potential in geocentric coordinates.
332  *
333  * @param[in] X geocentric coordinate of point (meters).
334  * @param[in] Y geocentric coordinate of point (meters).
335  * @param[in] Z geocentric coordinate of point (meters).
336  * @return \e T = \e W - \e U the disturbing potential (also called the
337  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
338  **********************************************************************/
339  Math::real T(real X, real Y, real Z) const {
340  real dummy;
341  return InternalT(X, Y, Z, dummy, dummy, dummy, false, true);
342  }
343 
344  /**
345  * Evaluate the components of the acceleration due to normal gravity and
346  * the centrifugal acceleration in geocentric coordinates.
347  *
348  * @param[in] X geocentric coordinate of point (meters).
349  * @param[in] Y geocentric coordinate of point (meters).
350  * @param[in] Z geocentric coordinate of point (meters).
351  * @param[out] gammaX the \e X component of the normal acceleration
352  * (m s<sup>&minus;2</sup>).
353  * @param[out] gammaY the \e Y component of the normal acceleration
354  * (m s<sup>&minus;2</sup>).
355  * @param[out] gammaZ the \e Z component of the normal acceleration
356  * (m s<sup>&minus;2</sup>).
357  * @return \e U = <i>V</i><sub>0</sub> + &Phi; the sum of the
358  * normal gravitational and centrifugal potentials
359  * (m<sup>2</sup> s<sup>&minus;2</sup>).
360  *
361  * This calls NormalGravity::U for ReferenceEllipsoid().
362  **********************************************************************/
363  Math::real U(real X, real Y, real Z,
364  real& gammaX, real& gammaY, real& gammaZ) const
365  { return _earth.U(X, Y, Z, gammaX, gammaY, gammaZ); }
366 
367  /**
368  * Evaluate the centrifugal acceleration in geocentric coordinates.
369  *
370  * @param[in] X geocentric coordinate of point (meters).
371  * @param[in] Y geocentric coordinate of point (meters).
372  * @param[out] fX the \e X component of the centrifugal acceleration
373  * (m s<sup>&minus;2</sup>).
374  * @param[out] fY the \e Y component of the centrifugal acceleration
375  * (m s<sup>&minus;2</sup>).
376  * @return &Phi; the centrifugal potential (m<sup>2</sup>
377  * s<sup>&minus;2</sup>).
378  *
379  * This calls NormalGravity::Phi for ReferenceEllipsoid().
380  **********************************************************************/
381  Math::real Phi(real X, real Y, real& fX, real& fY) const
382  { return _earth.Phi(X, Y, fX, fY); }
383  ///@}
384 
385  /** \name Compute gravity on a circle of constant latitude
386  **********************************************************************/
387  ///@{
388  /**
389  * Create a GravityCircle object to allow the gravity field at many points
390  * with constant \e lat and \e h and varying \e lon to be computed
391  * efficiently.
392  *
393  * @param[in] lat latitude of the point (degrees).
394  * @param[in] h the height of the point above the ellipsoid (meters).
395  * @param[in] caps bitor'ed combination of GravityModel::mask values
396  * specifying the capabilities of the resulting GravityCircle object.
397  * @exception std::bad_alloc if the memory necessary for creating a
398  * GravityCircle can't be allocated.
399  * @return a GravityCircle object whose member functions computes the
400  * gravitational field at a particular values of \e lon.
401  *
402  * The GravityModel::mask values are
403  * - \e caps |= GravityModel::GRAVITY
404  * - \e caps |= GravityModel::DISTURBANCE
405  * - \e caps |= GravityModel::DISTURBING_POTENTIAL
406  * - \e caps |= GravityModel::SPHERICAL_ANOMALY
407  * - \e caps |= GravityModel::GEOID_HEIGHT
408  * .
409  * The default value of \e caps is GravityModel::ALL which turns on all the
410  * capabilities. If an unsupported function is invoked, it will return
411  * NaNs. Note that GravityModel::GEOID_HEIGHT will only be honored if \e h
412  * = 0.
413  *
414  * If the field at several points on a circle of latitude need to be
415  * calculated then creating a GravityCircle object and using its member
416  * functions will be substantially faster, especially for high-degree
417  * models. See \ref gravityparallel for an example of using GravityCircle
418  * (together with OpenMP) to speed up the computation of geoid heights.
419  **********************************************************************/
420  GravityCircle Circle(real lat, real h, unsigned caps = ALL) const;
421  ///@}
422 
423  /** \name Inspector functions
424  **********************************************************************/
425  ///@{
426 
427  /**
428  * @return the NormalGravity object for the reference ellipsoid.
429  **********************************************************************/
430  const NormalGravity& ReferenceEllipsoid() const { return _earth; }
431 
432  /**
433  * @return the description of the gravity model, if available, in the data
434  * file; if absent, return "NONE".
435  **********************************************************************/
436  const std::string& Description() const { return _description; }
437 
438  /**
439  * @return date of the model; if absent, return "UNKNOWN".
440  **********************************************************************/
441  const std::string& DateTime() const { return _date; }
442 
443  /**
444  * @return full file name used to load the gravity model.
445  **********************************************************************/
446  const std::string& GravityFile() const { return _filename; }
447 
448  /**
449  * @return "name" used to load the gravity model (from the first argument
450  * of the constructor, but this may be overridden by the model file).
451  **********************************************************************/
452  const std::string& GravityModelName() const { return _name; }
453 
454  /**
455  * @return directory used to load the gravity model.
456  **********************************************************************/
457  const std::string& GravityModelDirectory() const { return _dir; }
458 
459  /**
460  * @return \e a the equatorial radius of the ellipsoid (meters).
461  **********************************************************************/
462  Math::real MajorRadius() const { return _earth.MajorRadius(); }
463 
464  /**
465  * @return \e GM the mass constant of the model (m<sup>3</sup>
466  * s<sup>&minus;2</sup>); this is the product of \e G the gravitational
467  * constant and \e M the mass of the earth (usually including the mass of
468  * the earth's atmosphere).
469  **********************************************************************/
470  Math::real MassConstant() const { return _GMmodel; }
471 
472  /**
473  * @return \e GM the mass constant of the ReferenceEllipsoid()
474  * (m<sup>3</sup> s<sup>&minus;2</sup>).
475  **********************************************************************/
477  { return _earth.MassConstant(); }
478 
479  /**
480  * @return &omega; the angular velocity of the model and the
481  * ReferenceEllipsoid() (rad s<sup>&minus;1</sup>).
482  **********************************************************************/
484  { return _earth.AngularVelocity(); }
485 
486  /**
487  * @return \e f the flattening of the ellipsoid.
488  **********************************************************************/
489  Math::real Flattening() const { return _earth.Flattening(); }
490  ///@}
491 
492  /**
493  * @return the default path for gravity model data files.
494  *
495  * This is the value of the environment variable
496  * GEOGRAPHICLIB_GRAVITY_PATH, if set; otherwise, it is
497  * $GEOGRAPHICLIB_DATA/gravity if the environment variable
498  * GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default
499  * (/usr/local/share/GeographicLib/gravity on non-Windows systems and
500  * C:/ProgramData/GeographicLib/gravity on Windows systems).
501  **********************************************************************/
502  static std::string DefaultGravityPath();
503 
504  /**
505  * @return the default name for the gravity model.
506  *
507  * This is the value of the environment variable
508  * GEOGRAPHICLIB_GRAVITY_NAME, if set; otherwise, it is "egm96". The
509  * GravityModel class does not use this function; it is just provided as a
510  * convenience for a calling program when constructing a GravityModel
511  * object.
512  **********************************************************************/
513  static std::string DefaultGravityName();
514  };
515 
516 } // namespace GeographicLib
517 
518 #if defined(_MSC_VER)
519 # pragma warning (pop)
520 #endif
521 
522 #endif // GEOGRAPHICLIB_GRAVITYMODEL_HPP
Math::real Phi(real X, real Y, real &fX, real &fY) const
const std::string & GravityModelName() const
Math::real T(real X, real Y, real Z, real &deltaX, real &deltaY, real &deltaZ) const
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:91
Math::real MajorRadius() const
const std::string & Description() const
GeographicLib::Math::real real
Definition: GeodSolve.cpp:31
The normal gravity of the earth.
Math::real Flattening() const
const NormalGravity & ReferenceEllipsoid() const
Math::real MassConstant() const
const std::string & DateTime() const
Math::real Flattening() const
Math::real MassConstant() const
Header for GeographicLib::SphericalHarmonic1 class.
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
Header for GeographicLib::SphericalHarmonic class.
Model of the earth&#39;s gravity field.
Math::real ReferenceMassConstant() const
Math::real AngularVelocity() const
Header for GeographicLib::NormalGravity class.
const std::string & GravityFile() const
Math::real T(real X, real Y, real Z) const
Header for GeographicLib::Constants class.
Spherical harmonic series with a correction to the coefficients.
Math::real AngularVelocity() const
Spherical harmonic series.
Math::real Phi(real X, real Y, real &fX, real &fY) const
const std::string & GravityModelDirectory() const
Math::real MajorRadius() const
Math::real U(real X, real Y, real Z, real &gammaX, real &gammaY, real &gammaZ) const
Math::real U(real X, real Y, real Z, real &gammaX, real &gammaY, real &gammaZ) const
Gravity on a circle of latitude.