.TH LIBTELLURIAN_ELEVATED_GRAVITY 3 libtellurian
.SH NAME
libtellurian_elevated_gravity \- Calculate gravity at some altitude

.SH SYNPOSIS
.nf
#include <libtellurian.h>

double libtellurian_elevated_gravity(double \fIgravity\fP, double \fIlatitude\fP, double \fIaltitude\fP);

double libtellurian_elevated_gravity_radians(double \fIgravity\fP, double \fIlatitude\fP, double \fIaltitude\fP);
.fi
.PP
Link with
.I -ltellurian
.IR -lm .

.SH DESCRIPTION
The
.BR libtellurian_elevated_gravity ()
function models the Earth as a spheroid and calculates
the gravity at a given
.I altitude
and
.IR latitude ,
given the
.I gravity
at zero-altitude on the same
.IR latitude .
.PP
The
.I latitude
shall be specified according to GPS and in degrees
and the
.I gravity
shall be specified in meters per square second.
However the
.I altitude
shall be the number of metres above a reference datum
for which the input
.I gravity
applies. For the normal gravity, this would be the
geocentric radius as calculated by the
.BR libtellurian_sea_level (3)
function, and so the
.I altitude
would be the altitude reported in raw GPS measurements,
howver, for real world gravity, this would typically
be the orthometric altitude.
.PP
The
.BR libtellurian_elevated_gravity_radians ()
function is identical to the
.BR libtellurian_elevated_gravity ()
function except that
.I latitude
shall be specified in radians.

.SH RETURN VALUE
The
.BR libtellurian_elevated_gravity ()
and
.BR libtellurian_elevated_gravity_radians ()
functions return the normal gravity, at the specified
latitude, measured in meters per square second.

.SH ERRORS
None.

.SH NOTES
Some GPS systems, espcially those for hiking, surveying,
and aviation, report orthometric height (height above
sea level), rather than ellipsoidal height to make it
easier for the user to interpret.
.PP
The
.BR libtellurian_normal_gravity (3)
function does not account for the Earth's rotation,
however, the
.BR libtellurian_elevated_gravity ()
function does account for the Earth's rotation.
Given a normal gravity, it should for first be corrected
for the rotation of the Earth, using the
.BR libtellurian_effective_gravity (3)
function, before it is input to the
.BR libtellurian_elevated_gravity ()
function.
.PP
The adjustment this function creates is useful for
common heights in aviation, does not work for outer
space.

.SH SEE ALSO
.BR libtellurian (7),
.BR libtellurian_effective_gravity (3),
.BR libtellurian_normal_gravity (3)