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.
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.
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.
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.
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.
By calling sun_calc() you get another function as result that acts as a shortcut to 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)