******************************************
:mod:`astro` --- Sun movement calculations
******************************************

.. module:: astro
   :synopsis: Sun movement calculations

The sun's movement has a profound effect on many terrestrial animal species. In
this module you will find functions calculating the sun's position at a given
moment in time (e.g. to find out whether the sun is above the horizon or not)
or the time when the sun reaches a certain angle (e.g. to calculate the start
of the civil dawn on a specific date). The algorithms are based on the
excellent book `Practical Astronomy with your Calculator or Spreadsheet`_ by
Peter Duffett-Smith and Jonathan Zwart and should provide enough precision for
a wide range of applications.

Working with dates and locations around the world is often made complicated by
the presence of time zones. To make it easier and remove the need to worry
about time zone related details like daylight saving, all routines in this
module expect date and time values to be in UTC with the corresponding
Greenwich date, which if why the date parameter for many of the routines is
called ``gdatetime`` for "Greenwich date-time". If you are using telemetry data
from tracking collars, there is a good chance that the dates will already be in
the correct format. Otherwise you would have to convert them as appropriate.

.. _Practical Astronomy with your Calculator or Spreadsheet: http://www.cambridge.org/practicalastronomy

Functions
=========

.. function:: local_noon(gdatetime, lon_obs)

   This function returns the moment of mean solar noon for the supplied date
   and geographic longitude. The mean solar noon is the time when the sun
   transits over a meridian, without taking the equation of time (temporal
   deviation due to the Earth's axis inclination and orbit shape) into account.
   The result is the closest noon for the given time, i.e. the result can be
   before or after ``gdatetime``. Roughly speaking, for values between 00:00
   and 24:00 local time the returned value will be 12:00 of the same date.

.. function:: sun_az_alt(gdatetime, lon_obs, lat_obs)

   With this function you can calculate the azimuth and altitude of the sun on
   any moment for a given set of geographic coordinates::

      az, alt = sun_az_alt(datetime.utcnow(), lon, lat)

   The result is a tuple containing both values, which should be unpacked as
   shown above.

.. function:: sun_time(gdatetime, lon_obs, lat_obs[, rising[, angle]])

   This function calculates the time when the sun reaches the requested
   altitude or returns the closest result if it doesn't on that particular day.
   For example, if you would want to know when the sun sets during the arctic
   day above the North polar circle, it's impossible to give a correct answer,
   so instead the function will return the time when the sun is at its lowest
   position.

   The return value is a tuple of two values, a boolean indicating whether the
   sun reaches the desired position on that day or not, and a ``datetime``
   value of the moment itself when the boolean part is ``True`` or the
   closest approximation (either solar noon if the sun never descends to this
   particular altitude or midnight if it never rises this far) if the boolean
   value is ``False``.

   ``gdatetime``
      Due to the complexity involved in finding the correct position of the
      sun, the solution is found by approximation. The ``gdatetime`` value you
      have to supply is used as the starting point. For consistent results it
      might be a good idea to first calculate the :func:`local_noon` for a
      given `datetime` value before passing it to :func:`sun_time`.

   ``lon_obs``
      The geographic longitude of the observation.

   ``lat_obs``
      The geographic latitude of the observation.

   ``rising``
      This is a boolean value indicating whether you are asking for the moment
      when the sun reaches the requested angle before the noon when it is
      rising (if ``True``) or thereafter, when it is setting. The default value
      is ``True``.

   ``angle``
      The angle relative to the horizon you are asking for. The value is
      expected to be in degrees, with the positive direction pointing downward,
      i.e. below the horizon. For example, for the start of nautical morning
      twilight you would set ``rising`` to ``True`` and ``angle`` to ``12.0``.
      If you want to know when the sun descends to 20 degrees above the ground
      in the evening, you would call the function with ``rising`` set to
      ``False`` and ``angle`` to ``-20.0``.

      If this parameter is omitted, the value of -0.

.. function:: sun_calc(lon_obs, lat_obs)

   By calling :func:`sun_calc` you get another function as result that acts as
   a shortcut to :func:`sun_time` with hard-coded geographic coordinates and
   the calculation of local noon already handled. The only parameters you will
   still have to pass to the resulting function are a date and time value as
   well as the desired sun position (``rising`` and ``angle``)::

      sc = sun_calc(lon, lat)
      sunrise = sc(datetime.utcnow(), True, 6.0)

   is equivalent to::

      dt = datetime.utcnow()
      ln = local_noon(dt, lon)
      sunrise = sun_time(ln, lon, lat, True, 6.0)