solar-python -- Solar data calculation and prediction library for Python
************************************************************************

Copyright © 2015 Mattias Andrée

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Overview
********

solar-python is a Python 3 library that can be used to calculate information about the Sun's position and related data, and predict when solar events occur.

Import the module solar_python to use the library.

Documentation is available by the command help in python.

Constants
*********

Importing solar_python makes the following constants available:

SOLAR_APPARENT_RADIUS = 32.0 / 60.0
     Approximate apparent size of the Sun in degrees.

SOLAR_ELEVATION_PRESUNSET_POSTSUNRISE = 32.0 / 60.0
     The Sun's elevation at beginning of sunset and end of sunrise, measured in degrees.

SOLAR_ELEVATION_SUNSET_SUNRISE = -32.0 / 60.0
     The Sun's elevation at (end of) sunset and (beginning of) sunrise, measured in degrees.

SOLAR_ELEVATION_CIVIL_DUSK_DAWN = -6.0
     The Sun's elevation at civil dusk and civil dawn, measured in degrees

SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN = -12.0
     The Sun's elevation at nautical dusk and nautical dawn, measured in degrees

SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN = -18.0
     The Sun's elevation at astronomical dusk and astronomical dawn, measured in degrees

SOLAR_ELEVATION_AMATEUR_ASTRONOMICAL_DUSK_DAWN = -15.0
     The Sun's elevation at amateur astronomical dusk and amateur astronomical dawn, measured in degrees

SOLAR_ELEVATION_RANGE_TWILIGHT = (-18.0, 0.0)
     The Sun's lowest and highest elevation during all periods of twilight, measured in degrees

SOLAR_ELEVATION_RANGE_CIVIL_TWILIGHT = (-6.0, -32.0 / 60.0)
     The Sun's lowest and highest elevation during civil twilight, measured in degrees

SOLAR_ELEVATION_RANGE_NAUTICAL_TWILIGHT = (-12.0, -32.0 / 60.0)
     The Sun's lowest and highest elevation during nautical twilight, measured in degrees

SOLAR_ELEVATION_RANGE_ASTRONOMICAL_TWILIGHT = (-18.0, -32.0 / 60.0)
     The Sun's lowest and highest elevation during astronomical twilight, measured in degrees

SOLAR_ELEVATION_RANGE_AMATEUR_ASTRONOMICAL_TWILIGHT = (-15.0, -32.0 / 60.0)
     The Sun's lowest and highest elevation during amateur astronomical twilight, measured in degrees

SOLAR_ELEVATION_RANGE_GOLDEN_HOUR = (-4.0, 6.0)
     The Sun's lowest and highest elevation during the golden hour (magic hour), measured in degrees. These elevations are approximate.

SOLAR_ELEVATION_RANGE_BLUE_HOUR = (-6.0, -4.0)
     The Sun's lowest and highest elevation during the blue hour, measured in degrees. These elevations are approximate.

Calendar functions
******************

Importing solar_python makes the following calendar conversion functions available. All parameters are of the type float, and all functions return float except where noted otherwise.

julian_day_to_epoch(t)
     Converts a Julian Day timestamp, t, to a POSIX time timestamp.

epoch_to_julian_day(t)
     Converts a POSIX time timestamp, t, to a Julian Day timestamp

julian_day_to_julian_centuries(t)
     Converts a Julian Day timestamp, t, to a Julian Centuries timestamp.

julian_centuries_to_julian_day(t)
     Converts a Julian Centuries timestamp, t, to a Julian Day timestamp.

epoch_to_julian_centuries(t)
     Converts a POSIX time timestamp, t, to a Julian Centuries timestamp.

julian_centuries_to_epoch(t)
     Converts a Julian Centuries timestamp, t, to a POSIX time timestamp.

solar_python also makes the following functions available. All parameters are of the type float, and all functions return float.

epoch()
     Get current POSIX time.

julian_day()
     Get current Julian Day time.

julian_centuries()
     Get current Julian Centuries time (100 Julian days since J2000.)

Observation functions
*********************

Importing solar_python makes the following solar data observation functions available. All parameters are of the type float, and all functions return float. All parameters named t or noon is the time in Julian Centuries. These are low-level functions.

sun_geometric_mean_longitude(t)
     Calculates the Sun's geometric mean longitude.

sun_geometric_mean_anomaly(t)
     Calculates the Sun's geometric mean anomaly, in radians.

earth_orbit_eccentricity(t)
     Calculates the Earth's orbit eccentricity.

sun_equation_of_centre(t)
     Calculates the Sun's equation of the centre --- the difference between the true anomaly and the mean anomaly --- in radians.

sun_real_longitude(t)
     Calculates the Sun's real longitudinal position, in radians.

sun_apparent_longitude(t)
     Calculates the Sun's apparent longitudinal position, in radians.

mean_ecliptic_obliquity(t)
     Calculates the uncorrected mean ecliptic obliquity of the Sun's apparent motion without variation correction, in radians.

corrected_mean_ecliptic_obliquity(t)
     Calculates the mean ecliptic obliquity of the Sun's apparent motion with variation correction, in radians.

solar_declination(t)
     Calculates the Sun's declination, in radians.

equation_of_time(t)
     Calculates the equation of time --- the discrepancy between apparent and mean solar time --- in degrees.

hour_angle_from_elevation(latitude, declination, elevation)
     Calculates the solar hour angle, in radians, from the Sun's elevation, in radians. The Sun's elevation is given by the parameter elevation. This functions requires two additional parameters:

     longitude
          The longitude in degrees eastwards from Greenwich, negative for westwards.

     declination
          The declination, in radians.

elevation_from_hour_angle(latitude, declination, hour_angle)
     Calculates the Sun's elevation, in radians, from the solar hour angle, in radians. The solar hour angle is given by the parameter hour_angle. This functions requires two additional parameters:

     longitude
          The longitude in degrees eastwards from Greenwich, negative for westwards.

     declination
          The declination, in radians.

time_of_solar_noon(t, longitude)
     Calculates the time, in Julian Centuries, of the solar noon the closest to the time t. This functions requires one additional parameter:

     longitude
          The longitude in degrees eastwards from Greenwich, negative for westwards.

time_of_solar_elevation(t, noon, latitude, longitude, elevation)
     Calculates the time, in Julian Centuries, the Sun has a specified apparent elevation, expressed in radians via the parameter elevation, at a geographical position, expressed in degrees by the parameters:

     latitude
          The latitude in degrees northwards from the equator, negative for southwards.

     longitude
          The longitude in degrees eastwards from Greenwich, negative for westwards.

     The function require two additional parameter:

     t
          A time, in Julian Centuries, close to the sought time.

     noon
          The time, in Julian Centuries, of the closest solar noon.

solar_elevation_from_time(t, latitude, longitude):
     Calculates the Sun's elevation, in radians, as apparent from a geographical position, expressed in degrees by the parameters:

     latitude
          The latitude in degrees northwards from the equator, negative for southwards.

     longitude
          The longitude in degrees eastwards from Greenwich, negative for westwards.

The library also provides the high-level functions:

solar_elevation(latitude, longitude, t = None)
     Calculates the Sun's elevation, in degrees as apparent from a geographical position, expressed in degrees by the parameters:

     latitude
          The latitude in degrees northwards from the equator, negative for southwards.

     longitude
          The longitude in degrees eastwards from Greenwich, negative for westwards.

     The function also requires the time in Julian Centuries, provided via the parameter t. If t is None, the current time is used.

have_sunrise_and_sunset(latitude, t = None)
     Determine whether solar declination currently is so that there can be sunrises and sunsets. If not, you either have 24-hour daytime or 24-hour nighttime. The function requires the time in Julian Centuries, provided via the parameter t, and the latitude, provided via the parameter latitude, in degrees northwards from the equator, negative for southwards. If t is None, the current time is used.

     This function returns a boolean.

is_summer(latitude, t = None)
     Determine whether it is summer on the hemisphere on which you are located. The function requires the time in Julian Centuries, provided via the parameter t, and the latitude, provided via the parameter latitude, in degrees northwards from the equator, negative for southwards. If t is None, the current time is used.

     This function returns a boolean.

is_winter(latitude, t = None)
     Determine whether it is winter on the hemisphere on which you are located. The function requires the time in Julian Centuries, provided via the parameter t, and the latitude, provided via the parameter latitude, in degrees northwards from the equator, negative for southwards. If t is None, the current time is used.

     This function returns a boolean.

Prediction functions
********************

Importing solar_python makes the following solar data prediction functions available. All parameters are of the type float, and all functions return float. All parameters named t is the time in Julian Centuries, and the current time if set to None. Some functions require the geographical position of the observer. This latitude is provided via the parameter latitude in degrees northwards from the equator, negative for southwards. This longitude is provided via the parameter longitude in degrees eastwards from Greenwich, negative for westwards.

solar_prediction(delta, requested, fun, epsilon = 0.000001, span = 0.01, t = None)
     Predict the time point of the next or previous time an arbitrary condition is meet. This function returns the calculated time in Julian Centuries, or None if the condition is not meet within the specified timespan, specified by the parameter span in Julian Centuries (0.01 for one year).

     The function shall find the input --- one parameter in Julian Centuries --- for which the function-parameter fun returns the value of requested within an error tolerance of epsilon.

     The function uses the iteration step size delta. If this value is negative, a past event will be determined, and if it is positive, a future event will be predicted.

future_past_equinox(delta, t = None)
     Predict the time point, in Julian Centuries, of the next or previous equinox.

     The function uses the iteration step size delta. If this value is negative, a past event will be determined, and if it is positive, a future event will be predicted.

future_equinox(t = None)
     Predict the time point, in Julian Centuries, of the next equinox.

past_equinox(t = None)
     Predict the time point, in Julian Centuries, of the previous equinox.

future_past_solstice(delta, t = None)
     Predict the time point, in Julian Centuries, of the next or previous solstice.

     The function uses the iteration step size delta. If this value is negative, a past event will be determined, and if it is positive, a future event will be predicted.

future_solstice(t = None)
     Predict the time point, in Julian Centuries, of the next solstice.

past_solstice(t = None)
     Predict the time point, in Julian Centuries, of the previous solstice.

future_past_elevation(delta, latitude, longitude, elevation, t = None)
     Predict the time point, in Julian Centuries, of the next or previous time the Sun reaches or reached a specific elevation, specified in degrees via the parameter elevation. None is returned if not found within a year.

     The function uses the iteration step size delta. If this value is negative, a past event will be determined, and if it is positive, a future event will be predicted.

future_elevation(latitude, longitude, elevation, t = None)
     Predict the time point, in Julian Centuries, of the next time the Sun reaches a specific elevation, specified in degrees via the parameter elevation. None is returned if not found within a year.

past_elevation(latitude, longitude, elevation, t = None)
     Predict the time point, in Julian Centuries, of the previous time the Sun reached a specific elevation, specified in degrees via the parameter elevation. None is returned if not found within a year.

future_past_elevation_derivative(delta, latitude, longitude, derivative, t = None)
     Predict the time point, in Julian Centuries, of the next or previous time the Sun reaches or reached a specific elevation derivative. None is returned if not found within a year. The sought derivative is specified via the parameter derivative, expressed in degrees per Julian Century.

     The function uses the iteration step size delta. If this value is negative, a past event will be determined, and if it is positive, a future event will be predicted.

future_elevation_derivative(latitude, longitude, derivative, t = None)
     Predict the time point, in Julian Centuries, of the next time the Sun reaches a specific elevation derivative. None is returned if not found within a year. The sought derivative is specified via the parameter derivative, expressed in degrees per Julian Century.

past_elevation_derivative(latitude, longitude, derivative, t = None)
     Predict the time point, in Julian Centuries, of the previous time the Sun reached a specific elevation derivative. None is returned if not found within a year. The sought derivative is specified via the parameter derivative, expressed in degrees per Julian Century.

sunrise_equation(latitude, longitude, t = None)
     This algorithm is imprecise, gives an incorrent sunrise. Its behaviour is not fully known.

Miscellaneous functions
***********************

Importing solar_python makes the following functions available:

radians(deg)
     Convert an angle from degrees to radians.

degrees(rad)
     Convert an angle from radians to degrees.

GNU Free Documentation License
******************************

     [file fdl.texinfo not included]