karney.util
===========

.. py:module:: karney.util

.. autoapi-nested-parse::

   Utility module
   ==============



Functions
---------

.. autoapisummary::

   karney.util.eccentricity2
   karney.util.polar_radius
   karney.util.third_flattening
   karney.util.deg
   karney.util.rad
   karney.util.nthroot
   karney.util.get_ellipsoid


Module Contents
---------------

.. py:function:: eccentricity2(f)

   Returns the first and second eccentricity squared given the flattening, f.

   :param f: Flattening of the ellipsoid
   :type f: array-like

   .. rubric:: Notes

   The (first) eccentricity squared is defined as e2 = f*(2-f).
   The second eccentricity squared is defined as e2m = e2 / (1 - e2).


.. py:function:: polar_radius(a, f)

   Returns the polar radius b given the equatorial radius a and flattening f of the ellipsoid.

   :param a: Semi-major half axis or equatorial radius of ellipsoid
   :type a: array-like
   :param f: Flattening of the ellipsoid
   :type f: array-like

   .. rubric:: Notes

   The semi minor half axis (polar radius) is defined as b = (1 - f) * a
   where a is the semi major half axis (equatorial radius) and f is the flattening
   of the ellipsoid.


.. py:function:: third_flattening(f)

   Returns the third flattening, n, given the flattening, f.

   :param f: Flattening of the ellipsoid
   :type f: array-like

   .. rubric:: Notes

   The third flattening is defined as n = f / (2 - f).


.. py:function:: deg(*rad_angles)

   Converts angle in radians to degrees.

   :param rad_angles: angle in radians

   :returns: angle in degrees
   :rtype: deg_angles

   .. rubric:: Examples

   >>> import numpy as np
   >>> from karney.util import deg
   >>> deg(np.pi/2)
   90.0
   >>> deg(np.pi/2, [0, np.pi])
   (90.0, array([  0., 180.]))

   .. seealso:: :py:obj:`rad`


.. py:function:: rad(*deg_angles)

   Converts angle in degrees to radians.

   :param deg_angles: angle in degrees

   :returns: angle in radians
   :rtype: rad_angles

   .. rubric:: Examples

   >>> import numpy as np
   >>> from karney.util import deg, rad
   >>> deg(rad(90))
   90.0
   >>> deg(*rad(90, [0, 180]))
   (90.0, array([  0., 180.]))

   .. seealso:: :py:obj:`deg`


.. py:function:: nthroot(x, n)

   Returns the n'th root of x to machine precision

   :param x:
   :type x: real scalar or numpy array
   :param n:
   :type n: scalar integer

   .. rubric:: Examples

   >>> import numpy as np
   >>> from karney.util import nthroot
   >>> np.allclose(nthroot(27.0, 3), 3.0)
   True


.. py:function:: get_ellipsoid(name)

   Returns semi-major axis (a), flattening (f) and name of reference ellipsoid as a named tuple.

   :param name: name of ellipsoid. Valid options are:
                1) Airy 1858
                2) Airy Modified
                3) Australian National
                4) Bessel 1841
                5) Clarke 1880
                6) Everest 1830
                7) Everest Modified
                8) Fisher 1960
                9) Fisher 1968
                10) Hough 1956
                11) Hayford / International ellipsoid 1924 / European Datum 1950 / ED50
                12) Krassovsky 1938
                13) NWL-9D / WGS 66
                14) South American 1969
                15) Soviet Geod. System 1985
                16) WGS 72
                17) Clarke 1866 / NAD27
                18) GRS80 / WGS84 / NAD83
                19) ETRS89 / EUREF89
                20) NGO1948
   :type name: string

   .. rubric:: Notes

   See also:
   https://en.wikipedia.org/wiki/Geodetic_datum
   https://en.wikipedia.org/wiki/Reference_ellipsoid

   .. rubric:: Examples

   >>> from karney.util import get_ellipsoid
   >>> get_ellipsoid(name="wgs84")
   Ellipsoid(a=6378137.0, f=0.0033528106647474805, name="GRS80 / WGS84 / NAD83")
   >>> get_ellipsoid(name="GRS80")
   Ellipsoid(a=6378137.0, f=0.0033528106647474805, name="GRS80 / WGS84 / NAD83")
   >>> get_ellipsoid(name="NAD83")
   Ellipsoid(a=6378137.0, f=0.0033528106647474805, name="GRS80 / WGS84 / NAD83")
   >>> get_ellipsoid(name=18)
   Ellipsoid(a=6378137.0, f=0.0033528106647474805, name="GRS80 / WGS84 / NAD83")

   >>> wgs72 = get_ellipsoid(name="WGS 72")
   >>> wgs72.a == 6378135.0
   True
   >>> wgs72.f == 0.003352779454167505
   True
   >>> wgs72.name
   'WGS 72'
   >>> wgs72 == (6378135.0, 0.003352779454167505, "WGS 72")
   True