GeographicLib 2.3

NormalGravity.cpp
Go to the documentation of this file.
1/**
2 * \file NormalGravity.cpp
3 * \brief Implementation for GeographicLib::NormalGravity class
4 *
5 * Copyright (c) Charles Karney (2011-2022) <karney@alum.mit.edu> and licensed
6 * under the MIT/X11 License. For more information, see
7 * https://geographiclib.sourceforge.io/
8 **********************************************************************/
9
10#include <GeographicLib/NormalGravity.hpp>
11
12#if defined(_MSC_VER)
13// Squelch warnings about constant conditional expressions
14# pragma warning (disable: 4127)
15#endif
16
17 namespace GeographicLib {
18
19 using namespace std;
20
21 void NormalGravity::Initialize(real a, real GM, real omega, real f_J2,
22 bool geometricp) {
23 _a = a;
24 if (!(isfinite(_a) && _a > 0))
25 throw GeographicErr("Equatorial radius is not positive");
26 _gGM = GM;
27 if (!isfinite(_gGM))
28 throw GeographicErr("Gravitational constant is not finite");
29 _omega = omega;
30 _omega2 = Math::sq(_omega);
31 _aomega2 = Math::sq(_omega * _a);
32 if (!(isfinite(_omega2) && isfinite(_aomega2)))
33 throw GeographicErr("Rotation velocity is not finite");
34 _f = geometricp ? f_J2 : J2ToFlattening(_a, _gGM, _omega, f_J2);
35 _b = _a * (1 - _f);
36 if (!(isfinite(_b) && _b > 0))
37 throw GeographicErr("Polar semi-axis is not positive");
38 _jJ2 = geometricp ? FlatteningToJ2(_a, _gGM, _omega, f_J2) : f_J2;
39 _e2 = _f * (2 - _f);
40 _ep2 = _e2 / (1 - _e2);
41 real ex2 = _f < 0 ? -_e2 : _ep2;
42 _qQ0 = Qf(ex2, _f < 0);
43 _earth = Geocentric(_a, _f);
44 _eE = _a * sqrt(fabs(_e2)); // H+M, Eq 2-54
45 // H+M, Eq 2-61
46 _uU0 = _gGM * atanzz(ex2, _f < 0) / _b + _aomega2 / 3;
47 real P = Hf(ex2, _f < 0) / (6 * _qQ0);
48 // H+M, Eq 2-73
49 _gammae = _gGM / (_a * _b) - (1 + P) * _a * _omega2;
50 // H+M, Eq 2-74
51 _gammap = _gGM / (_a * _a) + 2 * P * _b * _omega2;
52 // k = gammae * (b * gammap / (a * gammae) - 1)
53 // = (b * gammap - a * gammae) / a
54 _k = -_e2 * _gGM / (_a * _b) +
55 _omega2 * (P * (_a + 2 * _b * (1 - _f)) + _a);
56 // f* = (gammap - gammae) / gammae
57 _fstar = (-_f * _gGM / (_a * _b) + _omega2 * (P * (_a + 2 * _b) + _a)) /
58 _gammae;
59 }
60
61 NormalGravity::NormalGravity(real a, real GM, real omega, real f_J2,
62 bool geometricp) {
63 Initialize(a, GM, omega, f_J2, geometricp);
64 }
65
66 const NormalGravity& NormalGravity::WGS84() {
67 static const NormalGravity wgs84(Constants::WGS84_a(),
68 Constants::WGS84_GM(),
69 Constants::WGS84_omega(),
70 Constants::WGS84_f(), true);
71 return wgs84;
72 }
73
74 const NormalGravity& NormalGravity::GRS80() {
75 static const NormalGravity grs80(Constants::GRS80_a(),
76 Constants::GRS80_GM(),
77 Constants::GRS80_omega(),
78 Constants::GRS80_J2(), false);
79 return grs80;
80 }
81
82 Math::real NormalGravity::atan7series(real x) {
83 // compute -sum( (-x)^n/(2*n+7), n, 0, inf)
84 // = -1/7 + x/9 - x^2/11 + x^3/13 ...
85 // = (atan(sqrt(x))/sqrt(x)-(1-x/3+x^2/5)) / x^3 (x > 0)
86 // = (atanh(sqrt(-x))/sqrt(-x)-(1-x/3+x^2/5)) / x^3 (x < 0)
87 // require abs(x) < 1/2, but better to restrict calls to abs(x) < 1/4
88 static const real lg2eps_ = -log2(numeric_limits<real>::epsilon() / 2);
89 int e;
90 frexp(x, &e);
91 e = max(-e, 1); // Here's where abs(x) < 1/2 is assumed
92 // x = [0.5,1) * 2^(-e)
93 // estimate n s.t. x^n/n < 1/7 * epsilon/2
94 // a stronger condition is x^n < epsilon/2
95 // taking log2 of both sides, a stronger condition is n*(-e) < -lg2eps;
96 // or n*e > lg2eps or n > ceiling(lg2eps/e)
97 int n = x == 0 ? 1 : int(ceil(lg2eps_ / e));
98 Math::real v = 0;
99 while (n--) // iterating from n-1 down to 0
100 v = - x * v - 1/Math::real(2*n + 7);
101 return v;
102 }
103
104 Math::real NormalGravity::atan5series(real x) {
105 // Compute Taylor series approximations to
106 // (atan(z)-(z-z^3/3))/z^5,
107 // z = sqrt(x)
108 // require abs(x) < 1/2, but better to restrict calls to abs(x) < 1/4
109 return 1/real(5) + x * atan7series(x);
110 }
111
112 Math::real NormalGravity::Qf(real x, bool alt) {
113 // Compute
114 // Q(z) = (((1 + 3/z^2) * atan(z) - 3/z)/2) / z^3
115 // = q(z)/z^3 with q(z) defined by H+M, Eq 2-57 with z = E/u
116 // z = sqrt(x)
117 real y = alt ? -x / (1 + x) : x;
118 return !(4 * fabs(y) < 1) ? // Backwards test to allow NaNs through
119 ((1 + 3/y) * atanzz(x, alt) - 3/y) / (2 * y) :
120 (3 * (3 + y) * atan5series(y) - 1) / 6;
121 }
122
123 Math::real NormalGravity::Hf(real x, bool alt) {
124 // z = sqrt(x)
125 // Compute
126 // H(z) = (3*Q(z)+z*diff(Q(z),z))*(1+z^2)
127 // = (3 * (1 + 1/z^2) * (1 - atan(z)/z) - 1) / z^2
128 // = q'(z)/z^2, with q'(z) defined by H+M, Eq 2-67, with z = E/u
129 real y = alt ? -x / (1 + x) : x;
130 return !(4 * fabs(y) < 1) ? // Backwards test to allow NaNs through
131 (3 * (1 + 1/y) * (1 - atanzz(x, alt)) - 1) / y :
132 1 - 3 * (1 + y) * atan5series(y);
133 }
134
135 Math::real NormalGravity::QH3f(real x, bool alt) {
136 // z = sqrt(x)
137 // (Q(z) - H(z)/3) / z^2
138 // = - (1+z^2)/(3*z) * d(Q(z))/dz - Q(z)
139 // = ((15+9*z^2)*atan(z)-4*z^3-15*z)/(6*z^7)
140 // = ((25+15*z^2)*atan7+3)/10
141 real y = alt ? -x / (1 + x) : x;
142 return !(4 * fabs(y) < 1) ? // Backwards test to allow NaNs through
143 ((9 + 15/y) * atanzz(x, alt) - 4 - 15/y) / (6 * Math::sq(y)) :
144 ((25 + 15*y) * atan7series(y) + 3)/10;
145 }
146
147 Math::real NormalGravity::Jn(int n) const {
148 // Note Jn(0) = -1; Jn(2) = _jJ2; Jn(odd) = 0
149 if (n & 1 || n < 0)
150 return 0;
151 n /= 2;
152 real e2n = 1; // Perhaps this should just be e2n = pow(-_e2, n);
153 for (int j = n; j--;)
154 e2n *= -_e2;
155 return // H+M, Eq 2-92
156 -3 * e2n * ((1 - n) + 5 * n * _jJ2 / _e2) / ((2 * n + 1) * (2 * n + 3));
157 }
158
159 Math::real NormalGravity::SurfaceGravity(real lat) const {
160 real sphi = Math::sind(Math::LatFix(lat));
161 // H+M, Eq 2-78
162 return (_gammae + _k * Math::sq(sphi)) / sqrt(1 - _e2 * Math::sq(sphi));
163 }
164
165 Math::real NormalGravity::V0(real X, real Y, real Z,
166 real& GammaX, real& GammaY, real& GammaZ) const
167 {
168 // See H+M, Sec 6-2
169 real
170 p = hypot(X, Y),
171 clam = p != 0 ? X/p : 1,
172 slam = p != 0 ? Y/p : 0,
173 r = hypot(p, Z);
174 if (_f < 0) swap(p, Z);
175 real
176 Q = Math::sq(r) - Math::sq(_eE),
177 t2 = Math::sq(2 * _eE * Z),
178 disc = sqrt(Math::sq(Q) + t2),
179 // This is H+M, Eq 6-8a, but generalized to deal with Q negative
180 // accurately.
181 u = sqrt((Q >= 0 ? (Q + disc) : t2 / (disc - Q)) / 2),
182 uE = hypot(u, _eE),
183 // H+M, Eq 6-8b
184 sbet = u != 0 ? Z * uE : copysign(sqrt(-Q), Z),
185 cbet = u != 0 ? p * u : p,
186 s = hypot(cbet, sbet);
187 sbet = s != 0 ? sbet/s : 1;
188 cbet = s != 0 ? cbet/s : 0;
189 real
190 z = _eE/u,
191 z2 = Math::sq(z),
192 den = hypot(u, _eE * sbet);
193 if (_f < 0) {
194 swap(sbet, cbet);
195 swap(u, uE);
196 }
197 real
198 invw = uE / den, // H+M, Eq 2-63
199 bu = _b / (u != 0 || _f < 0 ? u : _eE),
200 // Qf(z2->inf, false) = pi/(4*z^3)
201 q = ((u != 0 || _f < 0 ? Qf(z2, _f < 0) : Math::pi() / 4) / _qQ0) *
202 bu * Math::sq(bu),
203 qp = _b * Math::sq(bu) * (u != 0 || _f < 0 ? Hf(z2, _f < 0) : 2) / _qQ0,
204 ang = (Math::sq(sbet) - 1/real(3)) / 2,
205 // H+M, Eqs 2-62 + 6-9, but omitting last (rotational) term.
206 Vres = _gGM * (u != 0 || _f < 0 ?
207 atanzz(z2, _f < 0) / u :
208 Math::pi() / (2 * _eE)) + _aomega2 * q * ang,
209 // H+M, Eq 6-10
210 gamu = - (_gGM + (_aomega2 * qp * ang)) * invw / Math::sq(uE),
211 gamb = _aomega2 * q * sbet * cbet * invw / uE,
212 t = u * invw / uE,
213 gamp = t * cbet * gamu - invw * sbet * gamb;
214 // H+M, Eq 6-12
215 GammaX = gamp * clam;
216 GammaY = gamp * slam;
217 GammaZ = invw * sbet * gamu + t * cbet * gamb;
218 return Vres;
219 }
220
221 Math::real NormalGravity::Phi(real X, real Y, real& fX, real& fY) const {
222 fX = _omega2 * X;
223 fY = _omega2 * Y;
224 // N.B. fZ = 0;
225 return _omega2 * (Math::sq(X) + Math::sq(Y)) / 2;
226 }
227
228 Math::real NormalGravity::U(real X, real Y, real Z,
229 real& gammaX, real& gammaY, real& gammaZ) const {
230 real fX, fY;
231 real Ures = V0(X, Y, Z, gammaX, gammaY, gammaZ) + Phi(X, Y, fX, fY);
232 gammaX += fX;
233 gammaY += fY;
234 return Ures;
235 }
236
237 Math::real NormalGravity::Gravity(real lat, real h,
238 real& gammay, real& gammaz) const {
239 real X, Y, Z;
240 real M[Geocentric::dim2_];
241 _earth.IntForward(lat, 0, h, X, Y, Z, M);
242 real gammaX, gammaY, gammaZ,
243 Ures = U(X, Y, Z, gammaX, gammaY, gammaZ);
244 // gammax = M[0] * gammaX + M[3] * gammaY + M[6] * gammaZ;
245 gammay = M[1] * gammaX + M[4] * gammaY + M[7] * gammaZ;
246 gammaz = M[2] * gammaX + M[5] * gammaY + M[8] * gammaZ;
247 return Ures;
248 }
249
250 Math::real NormalGravity::J2ToFlattening(real a, real GM,
251 real omega, real J2) {
252 // Solve
253 // f = e^2 * (1 - K * e/q0) - 3 * J2 = 0
254 // for e^2 using Newton's method
255 static const real maxe_ = 1 - numeric_limits<real>::epsilon();
256 static const real eps2_ = sqrt(numeric_limits<real>::epsilon()) / 100;
257 real
258 K = 2 * Math::sq(a * omega) * a / (15 * GM),
259 J0 = (1 - 4 * K / Math::pi()) / 3;
260 if (!(GM > 0 && isfinite(K) && K >= 0))
261 return Math::NaN();
262 if (!(isfinite(J2) && J2 <= J0)) return Math::NaN();
263 if (J2 == J0) return 1;
264 // Solve e2 - f1 * f2 * K / Q0 - 3 * J2 = 0 for J2 close to J0;
265 // subst e2 = ep2/(1+ep2), f2 = 1/(1+ep2), f1 = 1/sqrt(1+ep2), J2 = J0-dJ2,
266 // Q0 = pi/(4*z^3) - 2/z^4 + (3*pi)/(4*z^5), z = sqrt(ep2), and balance two
267 // leading terms to give
268 real
269 ep2 = fmax(Math::sq(32 * K / (3 * Math::sq(Math::pi()) * (J0 - J2))),
270 -maxe_),
271 e2 = fmin(ep2 / (1 + ep2), maxe_);
272 for (int j = 0; j < maxit_ || GEOGRAPHICLIB_PANIC; ++j) {
273 real
274 e2a = e2, ep2a = ep2,
275 f2 = 1 - e2, // (1 - f)^2
276 f1 = sqrt(f2), // (1 - f)
277 Q0 = Qf(e2 < 0 ? -e2 : ep2, e2 < 0),
278 h = e2 - f1 * f2 * K / Q0 - 3 * J2,
279 dh = 1 - 3 * f1 * K * QH3f(e2 < 0 ? -e2 : ep2, e2 < 0) /
280 (2 * Math::sq(Q0));
281 e2 = fmin(e2a - h / dh, maxe_);
282 ep2 = fmax(e2 / (1 - e2), -maxe_);
283 if (fabs(h) < eps2_ || e2 == e2a || ep2 == ep2a)
284 break;
285 }
286 return e2 / (1 + sqrt(1 - e2));
287 }
288
289 Math::real NormalGravity::FlatteningToJ2(real a, real GM,
290 real omega, real f) {
291 real
292 K = 2 * Math::sq(a * omega) * a / (15 * GM),
293 f1 = 1 - f,
294 f2 = Math::sq(f1),
295 e2 = f * (2 - f);
296 // H+M, Eq 2-90 + 2-92'
297 return (e2 - K * f1 * f2 / Qf(f < 0 ? -e2 : e2 / f2, f < 0)) / 3;
298 }
299
300} // namespace GeographicLib
real
GeographicLib::Math::real real
Definition: GeodSolve.cpp:29
GEOGRAPHICLIB_PANIC
#define GEOGRAPHICLIB_PANIC
Definition: Math.hpp:62
NormalGravity.hpp
Header for GeographicLib::NormalGravity class.
GeographicLib::Constants::GRS80_J2
static T GRS80_J2()
Definition: Constants.hpp:193
GeographicLib::Constants::GRS80_GM
static T GRS80_GM()
Definition: Constants.hpp:172
GeographicLib::Constants::WGS84_omega
static T WGS84_omega()
Definition: Constants.hpp:159
GeographicLib::Constants::GRS80_a
static T GRS80_a()
Definition: Constants.hpp:165
GeographicLib::Constants::GRS80_omega
static T GRS80_omega()
Definition: Constants.hpp:186
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition: Constants.hpp:141
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition: Constants.hpp:135
GeographicLib::Constants::WGS84_GM
static T WGS84_GM()
Definition: Constants.hpp:152
GeographicLib::Math::LatFix
static T LatFix(T x)
Definition: Math.hpp:293
GeographicLib::Math::sq
static T sq(T x)
Definition: Math.hpp:205
GeographicLib::Math::sind
static T sind(T x)
Definition: Math.cpp:148
GeographicLib::Math::pi
static T pi()
Definition: Math.hpp:183
GeographicLib::Math::NaN
static T NaN()
Definition: Math.cpp:250
GeographicLib::Math::real
double real
Definition: Math.hpp:100
GeographicLib::NormalGravity
The normal gravity of the earth.
Definition: NormalGravity.hpp:80
GeographicLib::NormalGravity::V0
Math::real V0(real X, real Y, real Z, real &GammaX, real &GammaY, real &GammaZ) const
Definition: NormalGravity.cpp:165
GeographicLib::NormalGravity::NormalGravity
NormalGravity()
Definition: NormalGravity.hpp:152
GeographicLib::NormalGravity::FlatteningToJ2
static Math::real FlatteningToJ2(real a, real GM, real omega, real f)
Definition: NormalGravity.cpp:289
GeographicLib::NormalGravity::Phi
Math::real Phi(real X, real Y, real &fX, real &fY) const
Definition: NormalGravity.cpp:221
GeographicLib::NormalGravity::WGS84
static const NormalGravity & WGS84()
Definition: NormalGravity.cpp:66
GeographicLib::NormalGravity::J2ToFlattening
static Math::real J2ToFlattening(real a, real GM, real omega, real J2)
Definition: NormalGravity.cpp:250
GeographicLib::NormalGravity::U
Math::real U(real X, real Y, real Z, real &gammaX, real &gammaY, real &gammaZ) const
Definition: NormalGravity.cpp:228
GeographicLib::NormalGravity::SurfaceGravity
Math::real SurfaceGravity(real lat) const
Definition: NormalGravity.cpp:159
GeographicLib::NormalGravity::GRS80
static const NormalGravity & GRS80()
Definition: NormalGravity.cpp:74
GeographicLib::NormalGravity::Gravity
Math::real Gravity(real lat, real h, real &gammay, real &gammaz) const
Definition: NormalGravity.cpp:237
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812
std::swap
void swap(GeographicLib::NearestNeighbor< dist_t, pos_t, distfun_t > &a, GeographicLib::NearestNeighbor< dist_t, pos_t, distfun_t > &b)
Definition: NearestNeighbor.hpp:825