GeographicLib  1.43
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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) <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_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(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 clam, real slam,
93  real& gX, real& gY, real& gZ) const;
94  Math::real V(real clam, real slam,
95  real& gX, real& gY, real& gZ) const;
96  Math::real InternalT(real clam, real slam,
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  *
122  * The function includes the effects of the earth's rotation.
123  **********************************************************************/
124  Math::real Gravity(real lon, real& gx, real& gy, real& gz) const;
125 
126  /**
127  * Evaluate the gravity disturbance vector.
128  *
129  * @param[in] lon the geographic longitude (degrees).
130  * @param[out] deltax the easterly component of the disturbance vector
131  * (m s<sup>&minus;2</sup>).
132  * @param[out] deltay the northerly component of the disturbance vector
133  * (m s<sup>&minus;2</sup>).
134  * @param[out] deltaz the upward component of the disturbance vector
135  * (m s<sup>&minus;2</sup>).
136  * @return \e T the corresponding disturbing potential.
137  **********************************************************************/
138  Math::real Disturbance(real lon, real& deltax, real& deltay, real& deltaz)
139  const;
140 
141  /**
142  * Evaluate the geoid height.
143  *
144  * @param[in] lon the geographic longitude (degrees).
145  * @return \e N the height of the geoid above the reference ellipsoid
146  * (meters).
147  *
148  * Some approximations are made in computing the geoid height so that the
149  * results of the NGA codes are reproduced accurately. Details are given
150  * in \ref gravitygeoid.
151  **********************************************************************/
152  Math::real GeoidHeight(real lon) const;
153 
154  /**
155  * Evaluate the components of the gravity anomaly vector using the
156  * spherical approximation.
157  *
158  * @param[in] lon the geographic longitude (degrees).
159  * @param[out] Dg01 the gravity anomaly (m s<sup>&minus;2</sup>).
160  * @param[out] xi the northerly component of the deflection of the vertical
161  * (degrees).
162  * @param[out] eta the easterly component of the deflection of the vertical
163  * (degrees).
164  *
165  * The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used
166  * so that the results of the NGA codes are reproduced accurately.
167  * approximations used here. Details are given in \ref gravitygeoid.
168  **********************************************************************/
169  void SphericalAnomaly(real lon, real& Dg01, real& xi, real& eta)
170  const;
171 
172  /**
173  * Evaluate the components of the acceleration due to gravity and the
174  * centrifugal acceleration in geocentric coordinates.
175  *
176  * @param[in] lon the geographic longitude (degrees).
177  * @param[out] gX the \e X component of the acceleration
178  * (m s<sup>&minus;2</sup>).
179  * @param[out] gY the \e Y component of the acceleration
180  * (m s<sup>&minus;2</sup>).
181  * @param[out] gZ the \e Z component of the acceleration
182  * (m s<sup>&minus;2</sup>).
183  * @return \e W = \e V + &Phi; the sum of the gravitational and
184  * centrifugal potentials (m<sup>2</sup> s<sup>&minus;2</sup>).
185  **********************************************************************/
186  Math::real W(real lon, real& gX, real& gY, real& gZ) const {
187  real clam, slam;
188  CircularEngine::cossin(lon, clam, slam);
189  return W(clam, slam, gX, gY, gZ);
190  }
191 
192  /**
193  * Evaluate the components of the acceleration due to gravity in geocentric
194  * coordinates.
195  *
196  * @param[in] lon the geographic longitude (degrees).
197  * @param[out] GX the \e X component of the acceleration
198  * (m s<sup>&minus;2</sup>).
199  * @param[out] GY the \e Y component of the acceleration
200  * (m s<sup>&minus;2</sup>).
201  * @param[out] GZ the \e Z component of the acceleration
202  * (m s<sup>&minus;2</sup>).
203  * @return \e V = \e W - &Phi; the gravitational potential
204  * (m<sup>2</sup> s<sup>&minus;2</sup>).
205  **********************************************************************/
206  Math::real V(real lon, real& GX, real& GY, real& GZ) const {
207  real clam, slam;
208  CircularEngine::cossin(lon, clam, slam);
209  return V(clam, slam, GX, GY, GZ);
210  }
211 
212  /**
213  * Evaluate the components of the gravity disturbance in geocentric
214  * coordinates.
215  *
216  * @param[in] lon the geographic longitude (degrees).
217  * @param[out] deltaX the \e X component of the gravity disturbance
218  * (m s<sup>&minus;2</sup>).
219  * @param[out] deltaY the \e Y component of the gravity disturbance
220  * (m s<sup>&minus;2</sup>).
221  * @param[out] deltaZ the \e Z component of the gravity disturbance
222  * (m s<sup>&minus;2</sup>).
223  * @return \e T = \e W - \e U the disturbing potential (also called the
224  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
225  **********************************************************************/
226  Math::real T(real lon, real& deltaX, real& deltaY, real& deltaZ)
227  const {
228  real clam, slam;
229  CircularEngine::cossin(lon, clam, slam);
230  return InternalT(clam, slam, deltaX, deltaY, deltaZ, true, true);
231  }
232 
233  /**
234  * Evaluate disturbing potential in geocentric coordinates.
235  *
236  * @param[in] lon the geographic longitude (degrees).
237  * @return \e T = \e W - \e U the disturbing potential (also called the
238  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
239  **********************************************************************/
240  Math::real T(real lon) const {
241  real clam, slam, dummy;
242  CircularEngine::cossin(lon, clam, slam);
243  return InternalT(clam, slam, dummy, dummy, dummy, false, true);
244  }
245 
246  ///@}
247 
248  /** \name Inspector functions
249  **********************************************************************/
250  ///@{
251  /**
252  * @return true if the object has been initialized.
253  **********************************************************************/
254  bool Init() const { return _a > 0; }
255 
256  /**
257  * @return \e a the equatorial radius of the ellipsoid (meters). This is
258  * the value inherited from the GravityModel object used in the
259  * constructor.
260  **********************************************************************/
262  { return Init() ? _a : Math::NaN(); }
263 
264  /**
265  * @return \e f the flattening of the ellipsoid. This is the value
266  * inherited from the GravityModel object used in the constructor.
267  **********************************************************************/
269  { return Init() ? _f : Math::NaN(); }
270 
271  /**
272  * @return the latitude of the circle (degrees).
273  **********************************************************************/
275  { return Init() ? _lat : Math::NaN(); }
276 
277  /**
278  * @return the height of the circle (meters).
279  **********************************************************************/
281  { return Init() ? _h : Math::NaN(); }
282 
283  /**
284  * @return \e caps the computational capabilities that this object was
285  * constructed with.
286  **********************************************************************/
287  unsigned Capabilities() const { return _caps; }
288 
289  /**
290  * @param[in] testcaps a set of bitor'ed GravityModel::mask values.
291  * @return true if the GravityCircle object has all these capabilities.
292  **********************************************************************/
293  bool Capabilities(unsigned testcaps) const {
294  return (_caps & testcaps) == testcaps;
295  }
296  ///@}
297  };
298 
299 } // namespace GeographicLib
300 
301 #endif // GEOGRAPHICLIB_GRAVITYCIRCLE_HPP
static T NaN()
Definition: Math.hpp:629
Math::real Height() const
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:90
GeographicLib::Math::real real
Definition: GeodSolve.cpp:32
Header for GeographicLib::GravityModel class.
Math::real V(real lon, real &GX, real &GY, real &GZ) const
static T hypot(T x, T y)
Definition: Math.hpp:255
Math::real T(real lon) const
Math::real MajorRadius() const
Header for GeographicLib::CircularEngine class.
Spherical harmonic sums for a circle.
Model of the earth's gravity field.
Math::real Flattening() const
unsigned Capabilities() const
Header for GeographicLib::Constants class.
Math::real W(real lon, real &gX, real &gY, real &gZ) const
Math::real Latitude() const
bool Capabilities(unsigned testcaps) const
Math::real T(real lon, real &deltaX, real &deltaY, real &deltaZ) const
Gravity on a circle of latitude.