1 files changed, 96 insertions, 0 deletions
diff --git a/libtellurian_elevated_gravity.3 b/libtellurian_elevated_gravity.3
new file mode 100644
index 0000000..fb728b9
--- /dev/null
+++ b/libtellurian_elevated_gravity.3
@@ -0,0 +1,96 @@
+.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)