GeographicLib  1.49
GravityCircle.hpp
Go to the documentation of this file.
1 /**
2  * \file GravityCircle.hpp
3  * \brief Header for GeographicLib::GravityCircle 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_GRAVITYCIRCLE_HPP)
11 #define GEOGRAPHICLIB_GRAVITYCIRCLE_HPP 1
12 
13 #include <vector>
17 
18 namespace GeographicLib {
19 
20  /**
21  * \brief Gravity on a circle of latitude
22  *
23  * Evaluate the earth's gravity field on a circle of constant height and
24  * latitude. This uses a CircularEngine to pre-evaluate the inner sum of the
25  * spherical harmonic sum, allowing the values of the field at several
26  * different longitudes to be evaluated rapidly.
27  *
28  * Use GravityModel::Circle to create a GravityCircle object. (The
29  * constructor for this class is private.)
30  *
31  * See \ref gravityparallel for an example of using GravityCircle (together
32  * with OpenMP) to speed up the computation of geoid heights.
33  *
34  * Example of use:
35  * \include example-GravityCircle.cpp
36  *
37  * <a href="Gravity.1.html">Gravity</a> is a command-line utility providing
38  * access to the functionality of GravityModel and GravityCircle.
39  **********************************************************************/
40 
42  private:
43  typedef Math::real real;
44  enum mask {
45  NONE = GravityModel::NONE,
46  GRAVITY = GravityModel::GRAVITY,
47  DISTURBANCE = GravityModel::DISTURBANCE,
48  DISTURBING_POTENTIAL = GravityModel::DISTURBING_POTENTIAL,
49  GEOID_HEIGHT = GravityModel::GEOID_HEIGHT,
50  SPHERICAL_ANOMALY = GravityModel::SPHERICAL_ANOMALY,
51  ALL = GravityModel::ALL,
52  };
53 
54  unsigned _caps;
55  real _a, _f, _lat, _h, _Z, _Px, _invR, _cpsi, _spsi,
56  _cphi, _sphi, _amodel, _GMmodel, _dzonal0,
57  _corrmult, _gamma0, _gamma, _frot;
58  CircularEngine _gravitational, _disturbing, _correction;
59 
60  GravityCircle(mask caps, real a, real f, real lat, real h,
61  real Z, real P, real cphi, real sphi,
62  real amodel, real GMmodel, real dzonal0, real corrmult,
63  real gamma0, real gamma, real frot,
64  const CircularEngine& gravitational,
65  const CircularEngine& disturbing,
66  const CircularEngine& correction)
67  : _caps(caps)
68  , _a(a)
69  , _f(f)
70  , _lat(Math::LatFix(lat))
71  , _h(h)
72  , _Z(Z)
73  , _Px(P)
74  , _invR(1 / Math::hypot(_Px, _Z))
75  , _cpsi(_Px * _invR)
76  , _spsi(_Z * _invR)
77  , _cphi(cphi)
78  , _sphi(sphi)
79  , _amodel(amodel)
80  , _GMmodel(GMmodel)
81  , _dzonal0(dzonal0)
82  , _corrmult(corrmult)
83  , _gamma0(gamma0)
84  , _gamma(gamma)
85  , _frot(frot)
86  , _gravitational(gravitational)
87  , _disturbing(disturbing)
88  , _correction(correction)
89  {}
90 
91  friend class GravityModel; // GravityModel calls the private constructor
92  Math::real W(real slam, real clam,
93  real& gX, real& gY, real& gZ) const;
94  Math::real V(real slam, real clam,
95  real& gX, real& gY, real& gZ) const;
96  Math::real InternalT(real slam, real clam,
97  real& deltaX, real& deltaY, real& deltaZ,
98  bool gradp, bool correct) const;
99  public:
100  /**
101  * A default constructor for the normal gravity. This sets up an
102  * uninitialized object which can be later replaced by the
103  * GravityModel::Circle.
104  **********************************************************************/
105  GravityCircle() : _a(-1) {}
106 
107  /** \name Compute the gravitational field
108  **********************************************************************/
109  ///@{
110  /**
111  * Evaluate the gravity.
112  *
113  * @param[in] lon the geographic longitude (degrees).
114  * @param[out] gx the easterly component of the acceleration
115  * (m s<sup>&minus;2</sup>).
116  * @param[out] gy the northerly component of the acceleration
117  * (m s<sup>&minus;2</sup>).
118  * @param[out] gz the upward component of the acceleration
119  * (m s<sup>&minus;2</sup>); this is usually negative.
120  * @return \e W the sum of the gravitational and centrifugal potentials
121  * (m<sup>2</sup> s<sup>&minus;2</sup>).
122  *
123  * The function includes the effects of the earth's rotation.
124  **********************************************************************/
125  Math::real Gravity(real lon, real& gx, real& gy, real& gz) const;
126 
127  /**
128  * Evaluate the gravity disturbance vector.
129  *
130  * @param[in] lon the geographic longitude (degrees).
131  * @param[out] deltax the easterly component of the disturbance vector
132  * (m s<sup>&minus;2</sup>).
133  * @param[out] deltay the northerly component of the disturbance vector
134  * (m s<sup>&minus;2</sup>).
135  * @param[out] deltaz the upward component of the disturbance vector
136  * (m s<sup>&minus;2</sup>).
137  * @return \e T the corresponding disturbing potential
138  * (m<sup>2</sup> s<sup>&minus;2</sup>).
139  **********************************************************************/
140  Math::real Disturbance(real lon, real& deltax, real& deltay, real& deltaz)
141  const;
142 
143  /**
144  * Evaluate the geoid height.
145  *
146  * @param[in] lon the geographic longitude (degrees).
147  * @return \e N the height of the geoid above the reference ellipsoid
148  * (meters).
149  *
150  * Some approximations are made in computing the geoid height so that the
151  * results of the NGA codes are reproduced accurately. Details are given
152  * in \ref gravitygeoid.
153  **********************************************************************/
154  Math::real GeoidHeight(real lon) const;
155 
156  /**
157  * Evaluate the components of the gravity anomaly vector using the
158  * spherical approximation.
159  *
160  * @param[in] lon the geographic longitude (degrees).
161  * @param[out] Dg01 the gravity anomaly (m s<sup>&minus;2</sup>).
162  * @param[out] xi the northerly component of the deflection of the vertical
163  * (degrees).
164  * @param[out] eta the easterly component of the deflection of the vertical
165  * (degrees).
166  *
167  * The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used
168  * so that the results of the NGA codes are reproduced accurately.
169  * approximations used here. Details are given in \ref gravitygeoid.
170  **********************************************************************/
171  void SphericalAnomaly(real lon, real& Dg01, real& xi, real& eta)
172  const;
173 
174  /**
175  * Evaluate the components of the acceleration due to gravity and the
176  * centrifugal acceleration in geocentric coordinates.
177  *
178  * @param[in] lon the geographic longitude (degrees).
179  * @param[out] gX the \e X component of the acceleration
180  * (m s<sup>&minus;2</sup>).
181  * @param[out] gY the \e Y component of the acceleration
182  * (m s<sup>&minus;2</sup>).
183  * @param[out] gZ the \e Z component of the acceleration
184  * (m s<sup>&minus;2</sup>).
185  * @return \e W = \e V + &Phi; the sum of the gravitational and
186  * centrifugal potentials (m<sup>2</sup> s<sup>&minus;2</sup>).
187  **********************************************************************/
188  Math::real W(real lon, real& gX, real& gY, real& gZ) const {
189  real slam, clam;
190  Math::sincosd(lon, slam, clam);
191  return W(slam, clam, gX, gY, gZ);
192  }
193 
194  /**
195  * Evaluate the components of the acceleration due to gravity in geocentric
196  * coordinates.
197  *
198  * @param[in] lon the geographic longitude (degrees).
199  * @param[out] GX the \e X component of the acceleration
200  * (m s<sup>&minus;2</sup>).
201  * @param[out] GY the \e Y component of the acceleration
202  * (m s<sup>&minus;2</sup>).
203  * @param[out] GZ the \e Z component of the acceleration
204  * (m s<sup>&minus;2</sup>).
205  * @return \e V = \e W - &Phi; the gravitational potential
206  * (m<sup>2</sup> s<sup>&minus;2</sup>).
207  **********************************************************************/
208  Math::real V(real lon, real& GX, real& GY, real& GZ) const {
209  real slam, clam;
210  Math::sincosd(lon, slam, clam);
211  return V(slam, clam, GX, GY, GZ);
212  }
213 
214  /**
215  * Evaluate the components of the gravity disturbance in geocentric
216  * coordinates.
217  *
218  * @param[in] lon the geographic longitude (degrees).
219  * @param[out] deltaX the \e X component of the gravity disturbance
220  * (m s<sup>&minus;2</sup>).
221  * @param[out] deltaY the \e Y component of the gravity disturbance
222  * (m s<sup>&minus;2</sup>).
223  * @param[out] deltaZ the \e Z component of the gravity disturbance
224  * (m s<sup>&minus;2</sup>).
225  * @return \e T = \e W - \e U the disturbing potential (also called the
226  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
227  **********************************************************************/
228  Math::real T(real lon, real& deltaX, real& deltaY, real& deltaZ)
229  const {
230  real slam, clam;
231  Math::sincosd(lon, slam, clam);
232  return InternalT(slam, clam, deltaX, deltaY, deltaZ, true, true);
233  }
234 
235  /**
236  * Evaluate disturbing potential in geocentric coordinates.
237  *
238  * @param[in] lon the geographic longitude (degrees).
239  * @return \e T = \e W - \e U the disturbing potential (also called the
240  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
241  **********************************************************************/
242  Math::real T(real lon) const {
243  real slam, clam, dummy;
244  Math::sincosd(lon, slam, clam);
245  return InternalT(slam, clam, dummy, dummy, dummy, false, true);
246  }
247 
248  ///@}
249 
250  /** \name Inspector functions
251  **********************************************************************/
252  ///@{
253  /**
254  * @return true if the object has been initialized.
255  **********************************************************************/
256  bool Init() const { return _a > 0; }
257 
258  /**
259  * @return \e a the equatorial radius of the ellipsoid (meters). This is
260  * the value inherited from the GravityModel object used in the
261  * constructor.
262  **********************************************************************/
264  { return Init() ? _a : Math::NaN(); }
265 
266  /**
267  * @return \e f the flattening of the ellipsoid. This is the value
268  * inherited from the GravityModel object used in the constructor.
269  **********************************************************************/
271  { return Init() ? _f : Math::NaN(); }
272 
273  /**
274  * @return the latitude of the circle (degrees).
275  **********************************************************************/
277  { return Init() ? _lat : Math::NaN(); }
278 
279  /**
280  * @return the height of the circle (meters).
281  **********************************************************************/
283  { return Init() ? _h : Math::NaN(); }
284 
285  /**
286  * @return \e caps the computational capabilities that this object was
287  * constructed with.
288  **********************************************************************/
289  unsigned Capabilities() const { return _caps; }
290 
291  /**
292  * @param[in] testcaps a set of bitor'ed GravityModel::mask values.
293  * @return true if the GravityCircle object has all these capabilities.
294  **********************************************************************/
295  bool Capabilities(unsigned testcaps) const {
296  return (_caps & testcaps) == testcaps;
297  }
298  ///@}
299  };
300 
301 } // namespace GeographicLib
302 
303 #endif // GEOGRAPHICLIB_GRAVITYCIRCLE_HPP
static T NaN()
Definition: Math.hpp:830
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:91
GeographicLib::Math::real real
Definition: GeodSolve.cpp:31
static T LatFix(T x)
Definition: Math.hpp:467
bool Capabilities(unsigned testcaps) const
static void sincosd(T x, T &sinx, T &cosx)
Definition: Math.hpp:558
Header for GeographicLib::GravityModel class.
Math::real Flattening() const
static T hypot(T x, T y)
Definition: Math.hpp:243
Math::real T(real lon, real &deltaX, real &deltaY, real &deltaZ) const
Math::real MajorRadius() const
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
Header for GeographicLib::CircularEngine class.
Spherical harmonic sums for a circle.
Model of the earth&#39;s gravity field.
Header for GeographicLib::Constants class.
Math::real W(real lon, real &gX, real &gY, real &gZ) const
Math::real T(real lon) const
Math::real V(real lon, real &GX, real &GY, real &GZ) const
Gravity on a circle of latitude.