/usr/include/GeographicLib/NormalGravity.hpp is in libgeographiclib-dev 1.21-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 | /**
* \file NormalGravity.hpp
* \brief Header for GeographicLib::NormalGravity class
*
* Copyright (c) Charles Karney (2011) <charles@karney.com> and licensed under
* the MIT/X11 License. For more information, see
* http://geographiclib.sourceforge.net/
**********************************************************************/
#if !defined(GEOGRAPHICLIB_NORMALGRAVITY_HPP)
#define GEOGRAPHICLIB_NORMALGRAVITY_HPP \
"$Id: e4b65c9c5787d8ee14f476cbb518fd5007006344 $"
#include <GeographicLib/Constants.hpp>
#include <GeographicLib/Geocentric.hpp>
namespace GeographicLib {
/**
* \brief The normal gravity of the earth
*
* "Normal" gravity refers to an idealization of the earth which is modeled
* as an rotating ellipsoid. The eccentricity of the ellipsoid, the rotation
* speed, and the distribution of mass within the ellipsoid are such that the
* surface of the ellipsoid is a surface of constant potential (gravitational
* plus centrifugal). The acceleration due to gravity is therefore
* perpendicular to the surface of the ellipsoid.
*
* There is a closed solution to this problem which is implemented here.
* Series "approximations" are only used to evaluate certain combinations of
* elementary functions where use of the closed expression results in a loss
* of accuracy for small arguments due to cancellation of the two leading
* terms. However these series include sufficient terms to give full machine
* precision.
*
* Definitions:
* - <i>V</i><sub>0</sub>, the gravitational contribution to the normal
* potential;
* - \e Phi, the rotational contribution to the normal potential;
* - \e U = <i>V</i><sub>0</sub> + \e Phi, the total
* potential;
* - <b>Gamma</b> = <b>grad</b> <i>V</i><sub>0</sub>, the acceleration due to
* mass of the earth;
* - <b>f</b> = <b>grad</b> \e Phi, the centrifugal acceleration;
* - <b>gamma</b> = <b>grad</b> \e U = <b>Gamma</b> + <b>f</b>, the normal
* acceleration;
* - \e X, \e Y, \e Z, geocentric coordinates;
* - \e x, \e y, \e z, local cartesian coordinates used to denote the east,
* north and up directions.
*
* References:
* - W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San
* Francisco, 1967), Secs. 1-19, 2-7, 2-8 (2-9, 2-10), 6-2 (6-3).
* - H. Moritz, Geodetic Reference System 1980, J. Geod. 54(3), 395-405
* (1980) http://dx.doi.org/10.1007/BF02521480
*
* Example of use:
* \include example-NormalGravity.cpp
**********************************************************************/
class GEOGRAPHIC_EXPORT NormalGravity {
private:
static const int maxit_ = 10;
typedef Math::real real;
friend class GravityModel;
real _a, _GM, _omega, _f, _J2, _omega2, _aomega2;
real _e2, _ep2, _b, _E, _U0, _gammae, _gammap, _q0, _m, _k, _fstar;
Geocentric _earth;
static Math::real qf(real ep2) throw();
static Math::real qpf(real ep2) throw();
Math::real Jn(int n) const throw();
public:
/** \name Setting up the normal gravity
**********************************************************************/
///@{
/**
* Constructor for the normal gravity.
*
* @param[in] a equatorial radius (meters).
* @param[in] GM mass constant of the ellipsoid
* (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G
* the gravitational constant and \e M the mass of the earth (usually
* including the mass of the earth's atmosphere).
* @param[in] omega the angular velocity (rad s<sup>-1</sup>).
* @param[in] f the flattening of the ellipsoid.
* @param[in] J2 dynamical form factor.
*
* Exactly one of \e f and \e J2 should be positive and this will be used
* to define the ellipsoid. The shape of the ellipsoid can be given in one
* of two ways:
* - geometrically, the ellipsoid is defined by the flattening \e f =
* (\e a - \e b) / \e a, where \e a and \e b are the equatorial radius
* and the polar semi-axis.
* - physically, the ellipsoid is defined by the dynamical form factor
* <i>J</i><sub>2</sub> = (\e C - \e A) / <i>Ma</i><sup>2</sup>, where \e
* A and \e C are the equatorial and polar moments of inertia and \e M is
* the mass of the earth.
**********************************************************************/
NormalGravity(real a, real GM, real omega, real f, real J2);
/**
* A default constructor for the normal gravity. This sets up an
* uninitialized object and is used by GravityModel which constructs this
* object before it has read in the parameters for the reference ellipsoid.
**********************************************************************/
NormalGravity() : _a(-1) {}
///@}
/** \name Compute the gravity
**********************************************************************/
///@{
/**
* Evaluate the gravity on the surface of the ellipsoid.
*
* @param[in] lat the geographic latitude (degrees).
* @return \e gamma the acceleration due to gravity, positive downwards
* (m s<sup>-2</sup>).
*
* Due to the axial symmetry of the ellipsoid, the result is independent of
* the value of the longitude. This acceleration is perpendicular to the
* surface of the ellipsoid. It includes the effects of the earth's
* rotation.
**********************************************************************/
Math::real SurfaceGravity(real lat) const throw();
/**
* Evaluate the gravity at an arbitrary point above (or below) the
* ellipsoid.
*
* @param[in] lat the geographic latitude (degrees).
* @param[in] h the height above the ellipsoid (meters).
* @param[out] gammay the northerly component of the acceleration
* (m s<sup>-2</sup>).
* @param[out] gammaz the upward component of the acceleration
* (m s<sup>-2</sup>); this is usually negative.
* @return \e U the corresponding normal potential.
*
* Due to the axial symmetry of the ellipsoid, the result is independent of
* the value of the longitude and the easterly component of the
* acceleration vanishes, \e gammax = 0. The function includes the effects
* of the earth's rotation. When \e h = 0, this function gives \e gammay =
* 0 and the returned value matches that of NormalGravity::SurfaceGravity.
**********************************************************************/
Math::real Gravity(real lat, real h, real& gammay, real& gammaz)
const throw();
/**
* Evaluate the components of the acceleration due to gravity and the
* centrifugal acceleration in geocentric coordinates.
*
* @param[in] X geocentric coordinate of point (meters).
* @param[in] Y geocentric coordinate of point (meters).
* @param[in] Z geocentric coordinate of point (meters).
* @param[out] gammaX the \e X component of the acceleration
* (m s<sup>-2</sup>).
* @param[out] gammaY the \e Y component of the acceleration
* (m s<sup>-2</sup>).
* @param[out] gammaZ the \e Z component of the acceleration
* (m s<sup>-2</sup>).
* @return \e U = <i>V</i><sub>0</sub> + \e Phi the sum of the
* gravitational and centrifugal potentials
* (m<sup>2</sup> s<sup>-2</sup>).
*
* The acceleration given by <b>gamma</b> = <b>grad</b> \e U = <b>grad</b>
* <i>V</i><sub>0</sub> + <b>grad</b> \e Phi = <b>Gamma</b> + <b>f</b>.
**********************************************************************/
Math::real U(real X, real Y, real Z,
real& gammaX, real& gammaY, real& gammaZ) const throw();
/**
* Evaluate the components of the acceleration due to gravity alone in
* geocentric coordinates.
*
* @param[in] X geocentric coordinate of point (meters).
* @param[in] Y geocentric coordinate of point (meters).
* @param[in] Z geocentric coordinate of point (meters).
* @param[out] GammaX the \e X component of the acceleration due to gravity
* (m s<sup>-2</sup>).
* @param[out] GammaY the \e Y component of the acceleration due to gravity
* (m s<sup>-2</sup>).
* @param[out] GammaZ the \e Z component of the acceleration due to gravity
* (m s<sup>-2</sup>).
* @return <i>V</i><sub>0</sub> the gravitational potential
* (m<sup>2</sup> s<sup>-2</sup>).
*
* This function excludes the centrifugal acceleration and is appropriate
* to use for space applications. In terrestrial applications, the
* function NormalGravity::U (which includes this effect) should usually be
* used.
**********************************************************************/
Math::real V0(real X, real Y, real Z,
real& GammaX, real& GammaY, real& GammaZ) const throw();
/**
* Evaluate the centrifugal acceleration in geocentric coordinates.
*
* @param[in] X geocentric coordinate of point (meters).
* @param[in] Y geocentric coordinate of point (meters).
* @param[out] fX the \e X component of the centrifugal acceleration
* (m s<sup>-2</sup>).
* @param[out] fY the \e Y component of the centrifugal acceleration
* (m s<sup>-2</sup>).
* @return \e Phi the centrifugal potential (m<sup>2</sup> s<sup>-2</sup>).
*
* \e Phi is independent of \e Z, thus \e fZ = 0. This function
* NormalGravity::U sums the results of NormalGravity::V0 and
* NormalGravity::Phi.
**********************************************************************/
Math::real Phi(real X, real Y, real& fX, real& fY) const throw();
///@}
/** \name Inspector functions
**********************************************************************/
///@{
/**
* @return true if the object has been initialized.
**********************************************************************/
bool Init() const throw() { return _a > 0; }
/**
* @return \e a the equatorial radius of the ellipsoid (meters). This is
* the value used in the constructor.
**********************************************************************/
Math::real MajorRadius() const throw()
{ return Init() ? _a : Math::NaN<real>(); }
/**
* @return \e GM the mass constant of the ellipsoid
* (m<sup>3</sup> s<sup>-2</sup>). This is the value used in the
* constructor.
**********************************************************************/
Math::real MassConstant() const throw()
{ return Init() ? _GM : Math::NaN<real>(); }
/**
* @return \e J<sub>n</sub> the dynamical form factors of the ellipsoid.
*
* If \e n = 2 (the default), this is the value of <i>J</i><sub>2</sub>
* used in the constructor. Otherwise it is the zonal coefficient of the
* Legendre harmonic sum of the normal gravitational potential. Note that
* \e J<sub>n</sub> = 0 if \e is odd. In most gravity applications, fully
* normalized Legendre functions are used and the corresponding coefficient
* is <i>C</i><sub><i>n</i>0</sub> = -\e J<sub>n</sub> / sqrt(2 \e n + 1).
**********************************************************************/
Math::real DynamicalFormFactor(int n = 2) const throw()
{ return Init() ? ( n == 2 ? _J2 : Jn(n)) : Math::NaN<real>(); }
/**
* @return \e omega the angular velocity of the ellipsoid
* (rad s<sup>-1</sup>). This is the value used in the constructor.
**********************************************************************/
Math::real AngularVelocity() const throw()
{ return Init() ? _omega : Math::NaN<real>(); }
/**
* @return <i>f</i> the flattening of the ellipsoid (\e a - \e b)/\e a.
**********************************************************************/
Math::real Flattening() const throw()
{ return Init() ? _f : Math::NaN<real>(); }
/**
* @return <i>gamma</i><sub>e</sub> the normal gravity at equator
* (m s<sup>-2</sup>).
**********************************************************************/
Math::real EquatorialGravity() const throw()
{ return Init() ? _gammae : Math::NaN<real>(); }
/**
* @return <i>gamma</i><sub>p</sub> the normal gravity at poles
* (m s<sup>-2</sup>).
**********************************************************************/
Math::real PolarGravity() const throw()
{ return Init() ? _gammap : Math::NaN<real>(); }
/**
* @return <i>f*</i> the gravity flattening
* (<i>gamma</i><sub>p</sub> - <i>gamma</i><sub>e</sub>) /
* <i>gamma</i><sub>e</sub>.
**********************************************************************/
Math::real GravityFlattening() const throw()
{ return Init() ? _fstar : Math::NaN<real>(); }
/**
* @return <i>U</i><sub>0</sub> the constant normal potential for the
* surface of the ellipsoid (m<sup>2</sup> s<sup>-2</sup>).
**********************************************************************/
Math::real SurfacePotential() const throw()
{ return Init() ? _U0 : Math::NaN<real>(); }
/**
* @return the Geocentric object used by this instance.
**********************************************************************/
const Geocentric& Earth() const throw() { return _earth; }
///@}
/**
* A global instantiation of NormalGravity for the WGS84 ellipsoid.
**********************************************************************/
static const NormalGravity WGS84;
/**
* A global instantiation of NormalGravity for the GRS80 ellipsoid.
**********************************************************************/
static const NormalGravity GRS80;
};
} // namespace GeographicLib
#endif // GEOGRAPHICLIB_NORMALGRAVITY_HPP
|