Fourth commit

Signed-off-by: Mattias Andrée <m@maandree.se>

2 files changed, 269 insertions, 24 deletions

diff --git a/libtellurian.h b/libtellurian.h
index 2113f29..609f61d 100644
--- a/libtellurian.h
+++ b/libtellurian.h
@@ -40,7 +40,7 @@
 /**
  * The Earth's rectifying radius, in meters
  */
-#define LIBTELLURIAN_RECTIFYING_RADIUS 6367449.14582 /* 2π⁻¹∫{0 → ½π} √(a² cos² φ + b² sin² φ) dφ ≅ ∛(½(√a³+√b³))² */
+#define LIBTELLURIAN_RECTIFYING_RADIUS 6367449.145823328 /* 2π⁻¹∫{0→½π} √(a²cos²φ + b²sin²φ) dφ ≅ 1.5(a+b) - ½√[(3a+b)(a+3b)] */
 
 /**
  * The Earth's nominal equatorial radius, in meters
@@ -63,9 +63,11 @@
 #define LIBTELLURIAN_EQUATORIAL_CIRCUMFERENCE 40075016.68557849 /* 2bπ */
 
 /**
- * The Earth's meridional circumference, in meters
+ * The circumference, in meters, of a sphere inscribed in the Earth's
+ * spheroid and intersecting with it's pole (the circumference of
+ * a circle with Earth's polar radius)
  */
-#define LIBTELLURIAN_MERIDIONAL_CIRCUMFERENCE 39940652.74224401 /* 2bπ */
+#define LIBTELLURIAN_POLAR_CIRCUMFERENCE 39940652.74224401 /* 2bπ */
 
 /**
  * The Earth's mean circumference (arithmetic mean), in meters
@@ -85,33 +87,49 @@
 /**
  * The Earth's rectifying circumference, in meters
  */
-#define LIBTELLURIAN_RECTIFYING_CIRCUMFERENCE 40007862.91722943 /* 4 ∫{0 → ½π} √(a² cos² φ + b² sin² φ) dφ */
+#define LIBTELLURIAN_MERIDIONAL_CIRCUMFERENCE 40007862.91722943 /* 4 ∫{0 → ½π} √(a² cos² φ + b² sin² φ) dφ */
 
 /**
- * The Earth's gravity at the equator, in meters per square-second
+ * The Earth's gravity at the equator, in meters per square second
  */
-#define LIBTELLURIAN_EQUATORIAL_GRAVITY 9.7803253359
+#define LIBTELLURIAN_EQUATORIAL_GRAVITY 9.7803253359 /* 𝔾ₑ */
 
 /**
- * The Earth's gravity at the poles, in meters per square-second
+ * The Earth's gravity at the poles, in meters per square second
  */
-#define LIBTELLURIAN_POLAR_GRAVITY 9.8321849378
+#define LIBTELLURIAN_POLAR_GRAVITY 9.8321849378 /* 𝔾ₚ */
 
 /**
- * The Earth's normal gravity at the equator, in meters per square-second
+ * The Earth's normal gravity at the equator, in meters per square second
  */
-#define LIBTELLURIAN_NORMAL_EQUATORIAL_GRAVITY 9.7803267715
+#define LIBTELLURIAN_NORMAL_EQUATORIAL_GRAVITY 9.78379185547421 /* ½𝔾ₑ + √((½𝔾ₑ)² + aω²) */
 
 /**
- * The Earth's normal gravity at the poles, in meters per square-second
+ * The Earth's normal gravity at the poles, in meters per square second
  */
-#define LIBTELLURIAN_NORMAL_POLAR_GRAVITY 9.8321863685
+#define LIBTELLURIAN_NORMAL_POLAR_GRAVITY LIBTELLURIAN_POLAR_GRAVITY
 
 /**
  * The Earth's mass, in kilograms
  */
 #define LIBTELLURIAN_MASS_OF_EARTH 5.972168e24
 
+/**
+ * The Earth's nominal mean angular velocity, in radians per second
+ */
+#define LIBTELLURIAN_ANGULAR_VELOCITY 7.292115e-5 /* ω */
+
+/**
+ * The geocentric gravitational constant, in cubic meters per square second
+ * 
+ * This is the (universal) gravitational constant (6.67430e-11) multiplied
+ * by the mass of the Earth, however this value more reliable that the
+ * gravitation constant and the mass of th Earth, and should thus be used
+ * instead of multiplying the universial gravitational constant with the
+ * the msas of the Earth
+ */
+#define LIBTELLURIAN_GEOCENTRIC_GRAVITATIONAL_CONSTANT 3.986004418e14
+
 
 /**
  * Calculate the distance of the nominal sea level (geocentric
@@ -311,7 +329,7 @@ void libtellurian_end_point_radians(double latitude1, double longitude1, double
  * as an oblate spheroid
  * 
  * @param   latitude  GPS latitude coordinate, in degrees
- * @return            The normal gravity, in meters per square-second
+ * @return            The normal gravity, in meters per square second
  */
 LIBTELLURIAN_CONST__
 double libtellurian_normal_gravity(double latitude);
@@ -322,22 +340,48 @@ double libtellurian_normal_gravity(double latitude);
  * as an oblate spheroid
  * 
  * @param   latitude  GPS latitude coordinate, in radians
- * @return            The normal gravity, in meters per square-second
+ * @return            The normal gravity, in meters per square second
  */
 LIBTELLURIAN_CONST__
 double libtellurian_normal_gravity_radians(double latitude);
 
 /**
+ * Calculate the effective gravity based on an already
+ * calculated normal gravity, that is, the normal gravity
+ * subtracted by a centrifugal correction based on the
+ * normal gravity and the latitude it is calculated from
+ * 
+ * @param   gravity   The normal gravity, in meters per square second
+ * @param   latitude  GPS latitude coordinate, in degrees
+ * @return            The effective gravity, in meters per square second
+ */
+LIBTELLURIAN_CONST__
+double libtellurian_effective_gravity(double gravity, double latitude);
+
+/**
+ * Calculate the effective gravity based on an already
+ * calculated normal gravity, that is, the normal gravity
+ * subtracted by a centrifugal correction based on the
+ * normal gravity and the latitude it is calculated from
+ * 
+ * @param   gravity   The normal gravity, in meters per square second
+ * @param   latitude  GPS latitude coordinate, in radians
+ * @return            The effective gravity, in meters per square second
+ */
+LIBTELLURIAN_CONST__
+double libtellurian_effective_gravity_radians(double gravity, double latitude);
+
+/**
  * Calculate the gravity adjusted for the elevation
  * above the altitude where the gravity is measure
  * 
  * Altitudes above circa 100000 meters is out of range
  * for this function (that would be in outer space)
  * 
- * @param   gravity   The gravity at sea level, in meters per square-second
+ * @param   gravity   The gravity at sea level, in meters per square second
  * @param   latitude  GPS latitude coordinate, in degrees
  * @param   altitude  Elevation above the gravity's measurement point, in meters
- * @return            The height-adjusted gravity, in meters per square-second
+ * @return            The height-adjusted gravity, in meters per square second
  */
 LIBTELLURIAN_CONST__
 double libtellurian_elevated_gravity(double gravity, double latitude, double altitude);
@@ -349,31 +393,31 @@ double libtellurian_elevated_gravity(double gravity, double latitude, double alt
  * Altitudes above circa 100000 meters is out of range
  * for this function (that would be in outer space)
  * 
- * @param   gravity   The gravity at sea level, in meters per square-second
+ * @param   gravity   The gravity at sea level, in meters per square second
  * @param   latitude  GPS latitude coordinate, in radians
  * @param   altitude  Elevation above the gravity's measurement point, in meters
- * @return            The height-adjusted gravity, in meters per square-second
+ * @return            The height-adjusted gravity, in meters per square second
  */
 LIBTELLURIAN_CONST__
 double libtellurian_elevated_gravity_radians(double gravity, double latitude, double altitude);
 
 /**
- * Calculate the Earth's meridan radius of curvature at some latitude
+ * Calculate the Earth's meridian radius of curvature at some latitude
  * 
  * @param   latitude  GPS latitude coordinate, in degrees
- * @return            The meridan radius of curvature, in meters
+ * @return            The meridian radius of curvature, in meters
  */
 LIBTELLURIAN_CONST__
-double libtellurian_meridan_radius(double latitude);
+double libtellurian_meridian_radius(double latitude);
 
 /**
- * Calculate the Earth's meridan radius of curvature at some latitude
+ * Calculate the Earth's meridian radius of curvature at some latitude
  * 
  * @param   latitude  GPS latitude coordinate, in radians
- * @return            The meridan radius of curvature, in meters
+ * @return            The meridian radius of curvature, in meters
  */
 LIBTELLURIAN_CONST__
-double libtellurian_meridan_radius_radians(double latitude);
+double libtellurian_meridian_radius_radians(double latitude);
 
 /**
  * Calculate the Earth's transverse radius of curvature at some latitude
diff --git a/libtellurian.h.0 b/libtellurian.h.0
new file mode 100644
index 0000000..472d35c
--- /dev/null
+++ b/libtellurian.h.0
@@ -0,0 +1,201 @@
+.TH LIBTELLURIAN.H 0 libtellurian
+.SH NAME
+libtellurian.h \- Geodesy library header
+
+.SH SYNPOSIS
+.nf
+#include <libtellurian.h>
+
+#define LIBTELLURIAN_EQUATORIAL_RADIUS                  6378137.0
+#define LIBTELLURIAN_POLAR_RADIUS                       6356752.314245
+
+#define LIBTELLURIAN_MEAN_RADIUS                        /* derived value omitted */
+#define LIBTELLURIAN_VOLUMETRIC_RADIUS                  /* derived value omitted */
+#define LIBTELLURIAN_AUTHALIC_RADIUS                    /* derived value omitted */
+#define LIBTELLURIAN_RECTIFYING_RADIUS                  /* derived value omitted */
+
+#define LIBTELLURIAN_NOMINAL_EQUATORIAL_RADIUS          6378100.
+#define LIBTELLURIAN_NOMINAL_POLAR_RADIUS               6356800.
+#define LIBTELLURIAN_NOMINAL_RADIUS                     LIBTELLURIAN_NOMINAL_EQUATORIAL_RADIUS
+
+#define LIBTELLURIAN_EQUATORIAL_CIRCUMFERENCE           /* derived value omitted */
+#define LIBTELLURIAN_POLAR_CIRCUMFERENCE                /* derived value omitted */
+
+#define LIBTELLURIAN_MEAN_CIRCUMFERENCE                 /* derived value omitted */
+#define LIBTELLURIAN_VOLUMETRIC_CIRCUMFERENCE           /* derived value omitted */
+#define LIBTELLURIAN_AUTHALIC_CIRCUMFERENCE             /* derived value omitted */
+#define LIBTELLURIAN_MERIDIONAL_CIRCUMFERENCE           /* derived value omitted */
+
+#define LIBTELLURIAN_EQUATORIAL_GRAVITY                 9.7803253359
+#define LIBTELLURIAN_POLAR_GRAVITY                      9.8321849378
+#define LIBTELLURIAN_NORMAL_EQUATORIAL_GRAVITY          /* derived value omitted */
+#define LIBTELLURIAN_NORMAL_POLAR_GRAVITY               LIBTELLURIAN_POLAR_GRAVITY
+
+#define LIBTELLURIAN_MASS_OF_EARTH                      5.972168e24
+#define LIBTELLURIAN_ANGULAR_VELOCITY                   7.292115e-5
+#define LIBTELLURIAN_GEOCENTRIC_GRAVITATIONAL_CONSTANT  3.986004418e14
+.fi
+.PP
+Link with
+.I -ltellurian
+.IR -lm .
+
+.SH DESCRIPTION
+.B libtellurian.h
+provides a collection of constants useful for geodesy:
+.TP
+.B LIBTELLURIAN_EQUATORIAL_RADIUS
+The Earth's semimajor axes, in meters, which is the radius
+of the of the circle formed by the Earth's equator, when
+modelled as a spheroid.
+
+This value is a measurement and is subject to refinement.
+.TP
+.B LIBTELLURIAN_POLAR_RADIUS
+The Earth's semiminor axis, in meters, which is the distance
+the center of the Earth, when modelled as a spheroid, and
+either pole.
+
+This value is a measurement and is subject to refinement.
+.TP
+.B LIBTELLURIAN_MEAN_RADIUS
+The arithmetic mean of
+.I LIBTELLURIAN_EQUATORIAL_RADIUS
+and
+.IR LIBTELLURIAN_POLAR_RADIUS .
+.TP
+.B LIBTELLURIAN_VOLUMETRIC_RADIUS
+The geometric mean of
+.I LIBTELLURIAN_EQUATORIAL_RADIUS
+and
+.IR LIBTELLURIAN_POLAR_RADIUS ,
+which is the radius of a sphere with the same volume as
+the Earth.
+.TP
+.B LIBTELLURIAN_AUTHALIC_RADIUS
+The radius, in meters, of a sphere with the same area
+as the Earth.
+
+This is a value derived from
+.I LIBTELLURIAN_EQUATORIAL_RADIUS
+and
+.IR LIBTELLURIAN_POLAR_RADIUS .
+.TP
+.B LIBTELLURIAN_RECTIFYING_RADIUS
+The radius, in meters, of a sphere with the same
+circumference as the a great ellipse, on the Earth's
+ellipsoid, intersecting with both poles (the
+meridional circumference).
+
+This is a value derived from
+.I LIBTELLURIAN_EQUATORIAL_RADIUS
+and
+.IR LIBTELLURIAN_POLAR_RADIUS .
+.TP
+.B LIBTELLURIAN_NOMINAL_EQUATORIAL_RADIUS
+The Earth's nominal equatorial radius, in meters,
+which is a standardised approximate value of
+.IR LIBTELLURIAN_EQUATORIAL_RADIUS .
+.TP
+.B LIBTELLURIAN_NOMINAL_POLAR_RADIUS
+The Earth's nominal polar radius, in meters,
+which is a standardised approximate value of
+.IR LIBTELLURIAN_POLAR_RADIUS .
+.TP
+.B LIBTELLURIAN_NOMINAL_RADIUS
+The Earth's nominal radius, in meters, which is
+a standardised approximate value of
+.IR LIBTELLURIAN_EQUATORIAL_RADIUS ,
+and is a synonym for
+.IR LIBTELLURIAN_NOMINAL_EQUATORIAL_RADIUS .
+.TP
+.B LIBTELLURIAN_EQUATORIAL_CIRCUMFERENCE
+The circumference, in meters, of a circle with the radius
+.IR LIBTELLURIAN_EQUATORIAL_RADIUS .
+.TP
+.B LIBTELLURIAN_POLAR_CIRCUMFERENCE
+The circumference, in meters, of a circle with the radius
+.IR LIBTELLURIAN_POLAR_RADIUS .
+.TP
+.B LIBTELLURIAN_MEAN_CIRCUMFERENCE
+The circumference, in meters, of a circle with the radius
+.IR LIBTELLURIAN_MEAN_RADIUS .
+.TP
+.B LIBTELLURIAN_VOLUMETRIC_CIRCUMFERENCE
+The circumference, in meters, of a circle with the radius
+.IR LIBTELLURIAN_VOLUMETRIC_RADIUS .
+.TP
+.B LIBTELLURIAN_AUTHALIC_CIRCUMFERENCE
+The circumference, in meters, of a circle with the radius
+.IR LIBTELLURIAN_AUTHALIC_RADIUS .
+.TP
+.B LIBTELLURIAN_MERIDIONAL_CIRCUMFERENCE
+The circumference, in meters, of a circle with the radius
+.IR LIBTELLURIAN_RECTIFYING_RADIUS .
+.TP
+.B LIBTELLURIAN_EQUATORIAL_GRAVITY
+The Earth's gravity, in meters per square second, at the equator.
+
+This value is a measurement and is subject to refinement.
+.TP
+.B LIBTELLURIAN_POLAR_GRAVITY
+The Earth's gravity, in meters per square second, at the poles.
+
+This value is a measurement and is subject to refinement.
+.TP
+.B LIBTELLURIAN_NORMAL_EQUATORIAL_GRAVITY
+The Earth's normal gravity, in meters per square second, at
+the equator. This is a gravity theoretical gravitational
+acceleration at the Earth's ellipsoid unaffected by rotation
+and assuming the Earth's is spheroidal.
+
+This value is derived from
+.IR LIBTELLURIAN_EQUATORIAL_GRAVITY ,
+.IR LIBTELLURIAN_EQUATORIAL_RADIUS ,
+and
+.IR LIBTELLURIAN_ANGULAR_VELOCITY .
+.TP
+.B LIBTELLURIAN_NORMAL_POLAR_GRAVITY
+The Earth's normal gravity, in meters per square second, at
+the poles. This is a gravity theoretical gravitational
+acceleration at the Earth's ellipsoid unaffected by rotation
+and assuming the Earth's is spheroidal.
+
+This is an alias for a measurement and is subject to refinement.
+.TP
+.B LIBTELLURIAN_MASS_OF_EARTH
+The mass of the Earth, in kilograms.
+
+This value is a measurement and is subject to refinement.
+.TP
+.B LIBTELLURIAN_ANGULAR_VELOCITY
+The Earth's nominal mean angular velocity, in radians per second.
+
+This value is a measurement and is subject to refinement.
+.TP
+.B LIBTELLURIAN_GEOCENTRIC_GRAVITATIONAL_CONSTANT
+The geocentric gravitational constant, in cubic meters per square
+second. This is the product of the (universal) gravitational
+constant and the Earth's mass, however this value is more reliable
+than both the mass of the Earth and the (even less reliable)
+universal gravitational constant.
+
+This value is a measurement and is subject to refinement.
+.PP
+.B libtellurian.h
+also defines a number of geodesy functions. See
+.BR libtellurian (7)
+for more information.
+
+.SH SEE ALSO
+.BR libtellurian (7),
+.BR libtellurian_sea_level (3),
+.BR libtellurian_coarse_distance (3),
+.BR libtellurian_distance (3),
+.BR libtellurian_end_point (3),
+.BR libtellurian_normal_gravity (3),
+.BR libtellurian_elevated_gravity (3),
+.BR libtellurian_meridian_radius (3),
+.BR libtellurian_transverse_radius (3),
+.BR libtellurian_azimuthal_radius (3),
+.BR libtellurian_gaussian_radius (3)