GeographicLib  1.40
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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) <charles@karney.com> and licensed under
6  * the MIT/X11 License. For more information, see
7  * http://geographiclib.sourceforge.net/
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 geoid height entails correcting for the mass of the earth
37  * above the geoid. The egm96 and egm2008 include separate correction terms
38  * 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 model 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  *
205  * The function includes the effects of the earth's rotation.
206  **********************************************************************/
207  Math::real Gravity(real lat, real lon, real h,
208  real& gx, real& gy, real& gz) const;
209 
210  /**
211  * Evaluate the gravity disturbance vector at an arbitrary point above (or
212  * below) the ellipsoid.
213  *
214  * @param[in] lat the geographic latitude (degrees).
215  * @param[in] lon the geographic longitude (degrees).
216  * @param[in] h the height above the ellipsoid (meters).
217  * @param[out] deltax the easterly component of the disturbance vector
218  * (m s<sup>&minus;2</sup>).
219  * @param[out] deltay the northerly component of the disturbance vector
220  * (m s<sup>&minus;2</sup>).
221  * @param[out] deltaz the upward component of the disturbance vector
222  * (m s<sup>&minus;2</sup>).
223  * @return \e T the corresponding disturbing potential.
224  **********************************************************************/
225  Math::real Disturbance(real lat, real lon, real h,
226  real& deltax, real& deltay, real& deltaz)
227  const;
228 
229  /**
230  * Evaluate the geoid height.
231  *
232  * @param[in] lat the geographic latitude (degrees).
233  * @param[in] lon the geographic longitude (degrees).
234  * @return \e N the height of the geoid above the ReferenceEllipsoid()
235  * (meters).
236  *
237  * This calls NormalGravity::U for ReferenceEllipsoid(). Some
238  * approximations are made in computing the geoid height so that the
239  * results of the NGA codes are reproduced accurately. Details are given
240  * in \ref gravitygeoid.
241  **********************************************************************/
242  Math::real GeoidHeight(real lat, real lon) const;
243 
244  /**
245  * Evaluate the components of the gravity anomaly vector using the
246  * spherical approximation.
247  *
248  * @param[in] lat the geographic latitude (degrees).
249  * @param[in] lon the geographic longitude (degrees).
250  * @param[in] h the height above the ellipsoid (meters).
251  * @param[out] Dg01 the gravity anomaly (m s<sup>&minus;2</sup>).
252  * @param[out] xi the northerly component of the deflection of the vertical
253  * (degrees).
254  * @param[out] eta the easterly component of the deflection of the vertical
255  * (degrees).
256  *
257  * The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used
258  * so that the results of the NGA codes are reproduced accurately.
259  * approximations used here. Details are given in \ref gravitygeoid.
260  **********************************************************************/
261  void SphericalAnomaly(real lat, real lon, real h,
262  real& Dg01, real& xi, real& eta) const;
263  ///@}
264 
265  /** \name Compute gravity in geocentric coordinates
266  **********************************************************************/
267  ///@{
268  /**
269  * Evaluate the components of the acceleration due to gravity and the
270  * centrifugal acceleration in geocentric coordinates.
271  *
272  * @param[in] X geocentric coordinate of point (meters).
273  * @param[in] Y geocentric coordinate of point (meters).
274  * @param[in] Z geocentric coordinate of point (meters).
275  * @param[out] gX the \e X component of the acceleration
276  * (m s<sup>&minus;2</sup>).
277  * @param[out] gY the \e Y component of the acceleration
278  * (m s<sup>&minus;2</sup>).
279  * @param[out] gZ the \e Z component of the acceleration
280  * (m s<sup>&minus;2</sup>).
281  * @return \e W = \e V + &Phi; the sum of the gravitational and
282  * centrifugal potentials (m<sup>2</sup> s<sup>&minus;2</sup>).
283  *
284  * This calls NormalGravity::U for ReferenceEllipsoid().
285  **********************************************************************/
286  Math::real W(real X, real Y, real Z,
287  real& gX, real& gY, real& gZ) const;
288 
289  /**
290  * Evaluate the components of the acceleration due to gravity in geocentric
291  * coordinates.
292  *
293  * @param[in] X geocentric coordinate of point (meters).
294  * @param[in] Y geocentric coordinate of point (meters).
295  * @param[in] Z geocentric coordinate of point (meters).
296  * @param[out] GX the \e X component of the acceleration
297  * (m s<sup>&minus;2</sup>).
298  * @param[out] GY the \e Y component of the acceleration
299  * (m s<sup>&minus;2</sup>).
300  * @param[out] GZ the \e Z component of the acceleration
301  * (m s<sup>&minus;2</sup>).
302  * @return \e V = \e W - &Phi; the gravitational potential
303  * (m<sup>2</sup> s<sup>&minus;2</sup>).
304  **********************************************************************/
305  Math::real V(real X, real Y, real Z,
306  real& GX, real& GY, real& GZ) const;
307 
308  /**
309  * Evaluate the components of the gravity disturbance in geocentric
310  * coordinates.
311  *
312  * @param[in] X geocentric coordinate of point (meters).
313  * @param[in] Y geocentric coordinate of point (meters).
314  * @param[in] Z geocentric coordinate of point (meters).
315  * @param[out] deltaX the \e X component of the gravity disturbance
316  * (m s<sup>&minus;2</sup>).
317  * @param[out] deltaY the \e Y component of the gravity disturbance
318  * (m s<sup>&minus;2</sup>).
319  * @param[out] deltaZ the \e Z component of the gravity disturbance
320  * (m s<sup>&minus;2</sup>).
321  * @return \e T = \e W - \e U the disturbing potential (also called the
322  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
323  **********************************************************************/
324  Math::real T(real X, real Y, real Z,
325  real& deltaX, real& deltaY, real& deltaZ) const
326  { return InternalT(X, Y, Z, deltaX, deltaY, deltaZ, true, true); }
327 
328  /**
329  * Evaluate disturbing potential in geocentric coordinates.
330  *
331  * @param[in] X geocentric coordinate of point (meters).
332  * @param[in] Y geocentric coordinate of point (meters).
333  * @param[in] Z geocentric coordinate of point (meters).
334  * @return \e T = \e W - \e U the disturbing potential (also called the
335  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
336  **********************************************************************/
337  Math::real T(real X, real Y, real Z) const {
338  real dummy;
339  return InternalT(X, Y, Z, dummy, dummy, dummy, false, true);
340  }
341 
342  /**
343  * Evaluate the components of the acceleration due to normal gravity and
344  * the centrifugal acceleration in geocentric coordinates.
345  *
346  * @param[in] X geocentric coordinate of point (meters).
347  * @param[in] Y geocentric coordinate of point (meters).
348  * @param[in] Z geocentric coordinate of point (meters).
349  * @param[out] gammaX the \e X component of the normal acceleration
350  * (m s<sup>&minus;2</sup>).
351  * @param[out] gammaY the \e Y component of the normal acceleration
352  * (m s<sup>&minus;2</sup>).
353  * @param[out] gammaZ the \e Z component of the normal acceleration
354  * (m s<sup>&minus;2</sup>).
355  * @return \e U = <i>V</i><sub>0</sub> + &Phi; the sum of the
356  * normal gravitational and centrifugal potentials
357  * (m<sup>2</sup> s<sup>&minus;2</sup>).
358  *
359  * This calls NormalGravity::U for ReferenceEllipsoid().
360  **********************************************************************/
361  Math::real U(real X, real Y, real Z,
362  real& gammaX, real& gammaY, real& gammaZ) const
363  { return _earth.U(X, Y, Z, gammaX, gammaY, gammaZ); }
364 
365  /**
366  * Evaluate the centrifugal acceleration in geocentric coordinates.
367  *
368  * @param[in] X geocentric coordinate of point (meters).
369  * @param[in] Y geocentric coordinate of point (meters).
370  * @param[out] fX the \e X component of the centrifugal acceleration
371  * (m s<sup>&minus;2</sup>).
372  * @param[out] fY the \e Y component of the centrifugal acceleration
373  * (m s<sup>&minus;2</sup>).
374  * @return &Phi; the centrifugal potential (m<sup>2</sup>
375  * s<sup>&minus;2</sup>).
376  *
377  * This calls NormalGravity::Phi for ReferenceEllipsoid().
378  **********************************************************************/
379  Math::real Phi(real X, real Y, real& fX, real& fY) const
380  { return _earth.Phi(X, Y, fX, fY); }
381  ///@}
382 
383  /** \name Compute gravity on a circle of constant latitude
384  **********************************************************************/
385  ///@{
386  /**
387  * Create a GravityCircle object to allow the gravity field at many points
388  * with constant \e lat and \e h and varying \e lon to be computed
389  * efficiently.
390  *
391  * @param[in] lat latitude of the point (degrees).
392  * @param[in] h the height of the point above the ellipsoid (meters).
393  * @param[in] caps bitor'ed combination of GravityModel::mask values
394  * specifying the capabilities of the resulting GravityCircle object.
395  * @exception std::bad_alloc if the memory necessary for creating a
396  * GravityCircle can't be allocated.
397  * @return a GravityCircle object whose member functions computes the
398  * gravitational field at a particular values of \e lon.
399  *
400  * The GravityModel::mask values are
401  * - \e caps |= GravityModel::GRAVITY
402  * - \e caps |= GravityModel::DISTURBANCE
403  * - \e caps |= GravityModel::DISTURBING_POTENTIAL
404  * - \e caps |= GravityModel::SPHERICAL_ANOMALY
405  * - \e caps |= GravityModel::GEOID_HEIGHT
406  * .
407  * The default value of \e caps is GravityModel::ALL which turns on all the
408  * capabilities. If an unsupported function is invoked, it will return
409  * NaNs. Note that GravityModel::GEOID_HEIGHT will only be honored if \e h
410  * = 0.
411  *
412  * If the field at several points on a circle of latitude need to be
413  * calculated then creating a GravityCircle object and using its member
414  * functions will be substantially faster, especially for high-degree
415  * models. See \ref gravityparallel for an example of using GravityCircle
416  * (together with OpenMP) to speed up the computation of geoid heights.
417  **********************************************************************/
418  GravityCircle Circle(real lat, real h, unsigned caps = ALL) const;
419  ///@}
420 
421  /** \name Inspector functions
422  **********************************************************************/
423  ///@{
424 
425  /**
426  * @return the NormalGravity object for the reference ellipsoid.
427  **********************************************************************/
428  const NormalGravity& ReferenceEllipsoid() const { return _earth; }
429 
430  /**
431  * @return the description of the gravity model, if available, in the data
432  * file; if absent, return "NONE".
433  **********************************************************************/
434  const std::string& Description() const { return _description; }
435 
436  /**
437  * @return date of the model; if absent, return "UNKNOWN".
438  **********************************************************************/
439  const std::string& DateTime() const { return _date; }
440 
441  /**
442  * @return full file name used to load the gravity model.
443  **********************************************************************/
444  const std::string& GravityFile() const { return _filename; }
445 
446  /**
447  * @return "name" used to load the gravity model (from the first argument
448  * of the constructor, but this may be overridden by the model file).
449  **********************************************************************/
450  const std::string& GravityModelName() const { return _name; }
451 
452  /**
453  * @return directory used to load the gravity model.
454  **********************************************************************/
455  const std::string& GravityModelDirectory() const { return _dir; }
456 
457  /**
458  * @return \e a the equatorial radius of the ellipsoid (meters).
459  **********************************************************************/
460  Math::real MajorRadius() const { return _earth.MajorRadius(); }
461 
462  /**
463  * @return \e GM the mass constant of the model (m<sup>3</sup>
464  * s<sup>&minus;2</sup>); this is the product of \e G the gravitational
465  * constant and \e M the mass of the earth (usually including the mass of
466  * the earth's atmosphere).
467  **********************************************************************/
468  Math::real MassConstant() const { return _GMmodel; }
469 
470  /**
471  * @return \e GM the mass constant of the ReferenceEllipsoid()
472  * (m<sup>3</sup> s<sup>&minus;2</sup>).
473  **********************************************************************/
475  { return _earth.MassConstant(); }
476 
477  /**
478  * @return &omega; the angular velocity of the model and the
479  * ReferenceEllipsoid() (rad s<sup>&minus;1</sup>).
480  **********************************************************************/
482  { return _earth.AngularVelocity(); }
483 
484  /**
485  * @return \e f the flattening of the ellipsoid.
486  **********************************************************************/
487  Math::real Flattening() const { return _earth.Flattening(); }
488  ///@}
489 
490  /**
491  * @return the default path for gravity model data files.
492  *
493  * This is the value of the environment variable
494  * GEOGRAPHICLIB_GRAVITY_PATH, if set; otherwise, it is
495  * $GEOGRAPHICLIB_DATA/gravity if the environment variable
496  * GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default
497  * (/usr/local/share/GeographicLib/gravity on non-Windows systems and
498  * C:/ProgramData/GeographicLib/gravity on Windows systems).
499  **********************************************************************/
500  static std::string DefaultGravityPath();
501 
502  /**
503  * @return the default name for the gravity model.
504  *
505  * This is the value of the environment variable
506  * GEOGRAPHICLIB_GRAVITY_NAME, if set; otherwise, it is "egm96". The
507  * GravityModel class does not use this function; it is just provided as a
508  * convenience for a calling program when constructing a GravityModel
509  * object.
510  **********************************************************************/
511  static std::string DefaultGravityName();
512  };
513 
514 } // namespace GeographicLib
515 
516 #if defined(_MSC_VER)
517 # pragma warning (pop)
518 #endif
519 
520 #endif // GEOGRAPHICLIB_GRAVITYMODEL_HPP
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:69
const std::string & GravityFile() const
GeographicLib::Math::real real
Definition: GeodSolve.cpp:32
The normal gravity of the earth.
Math::real T(real X, real Y, real Z, real &deltaX, real &deltaY, real &deltaZ) const
Math::real Flattening() const
Math::real MajorRadius() const
Math::real Flattening() const
const std::string & GravityModelName() const
Math::real AngularVelocity() const
Math::real AngularVelocity() const
const std::string & Description() const
Header for GeographicLib::SphericalHarmonic1 class.
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
const NormalGravity & ReferenceEllipsoid() const
const std::string & GravityModelDirectory() const
Header for GeographicLib::SphericalHarmonic class.
Model of the earth's gravity field.
Math::real Phi(real X, real Y, real &fX, real &fY) const
Math::real MajorRadius() const
Header for GeographicLib::NormalGravity class.
Math::real MassConstant() const
Math::real U(real X, real Y, real Z, real &gammaX, real &gammaY, real &gammaZ) const
Header for GeographicLib::Constants class.
const std::string & DateTime() const
Spherical harmonic series with a correction to the coefficients.
Math::real U(real X, real Y, real Z, real &gammaX, real &gammaY, real &gammaZ) const
Math::real T(real X, real Y, real Z) const
Math::real Phi(real X, real Y, real &fX, real &fY) const
Math::real ReferenceMassConstant() const
Spherical harmonic series.
Gravity on a circle of latitude.
Math::real MassConstant() const