\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename solar-python.info
@settitle solar-python
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header


@dircategory Astronomy
@direntry
* solar-python: (solar-python).      Solar data calculation and prediction library for Python
@end direntry


@copying
Copyright @copyright{} 2015 Mattias Andrée

@quotation
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''.
@end quotation
@end copying

@ifnottex
@node Top
@top solar-python -- Solar data calculation and prediction library for Python
@insertcopying
@end ifnottex

@titlepage
@title solar-python
@subtitle Solar data calculation and prediction library for Python
@author by Mattias Andrée (maandree)

@page
@vskip 0pt plus 1filll
@insertcopying
@page
@end titlepage

@contents



@menu
* Overview::                        Brief overview of @command{solar-python}.
* Constants::                       List of constants.
* Calendar functions::              List of calendar functions.
* Observation functions::           List of solar data observation functions.
* Prediction functions::            List of solar data prediction functions.
* Miscellaneous functions::         List of miscellaneous functions.
* GNU Free Documentation License::  Copying and sharing this manual.
@end menu



@node Overview
@chapter Overview

@command{solar-python} is Python 3 library that can
be used to calculate information about the Sun's
position and related data and predict at when time
solar events occur.

Import the module @code{solar_python} to use the
library.

Documentation is available by the command @code{help}
in python.



@node Constants
@chapter Constants

Importing @code{solar_python} makes the following
constants available:

@table @code
@item SOLAR_APPARENT_RADIUS = 32.0 / 60.0
Approximate apparent size of the Sun in degrees.

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

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

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

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

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

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

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

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

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

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

@item 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

@item 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.
@end table



@node Calendar functions
@chapter Calendar functions

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

@table @code
@item julian_day_to_epoch(t)
Converts a Julian Day timestamp, @code{t}, to a POSIX time timestamp.

@item epoch_to_julian_day(t)
Converts a POSIX time timestamp, @code{t}, to a Julian Day timestamp

@item julian_day_to_julian_centuries(t)
Converts a Julian Day timestamp, @code{t}, to a Julian Centuries timestamp.

@item julian_centuries_to_julian_day(t)
Converts a Julian Centuries timestamp, @code{t}, to a Julian Day timestamp.

@item epoch_to_julian_centuries(t)
Converts a POSIX time timestamp, @code{t}, to a Julian Centuries timestamp.

@item julian_centuries_to_epoch(t)
Converts a Julian Centuries timestamp, @code{t}, to a POSIX time timestamp.
@end table

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

@table @code
@item epoch()
Get current POSIX time.

@item julian_day()
Get current Julian Day time.

@item julian_centuries()
Get current Julian Centuries time (100 Julian days since J2000.)
@end table



@node Observation functions
@chapter Observation functions

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

@table @code
@item sun_geometric_mean_longitude(t)
Calculates the Sun's geometric mean longitude.

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

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

@item 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.

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

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

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

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

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

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

@item 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 gived by the
parameter @code{elevation}. This functions requires two
additional parameters:
@table @code
@item longitude
The longitude in degrees eastwards from Greenwich,
negative for westwards.
@item declination
The declination, in radians.
@end table

@item 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 gived by the
parameter @code{hour_angle}. This functions requires two
additional parameters:
@table @code
@item longitude
The longitude in degrees eastwards from Greenwich,
negative for westwards.
@item declination
The declination, in radians.
@end table

@item time_of_solar_noon(t, longitude)
Calculates the time, in Julian Centuries, of the solar
noon the closest to the time @code{t}. This functions
requires one additional parameter:
@table @code
@item longitude
The longitude in degrees eastwards from Greenwich,
negative for westwards.
@end table

@item 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 @code{elevation}, at a geographical
position, expressed in degrees by the parameters:
@table @code
@item latitude
The latitude in degrees northwards from the equator,
negative for southwards.
@item longitude
The longitude in degrees eastwards from Greenwich,
negative for westwards.
@end table
@noindent
The function require two additional parameter:
@table @code
@item t
A time, in Julian Centuries, close to the sought time.
@item noon
The time, in Julian Centuries, of the closest solar noon.
@end table

@item 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:
@table @code
@item latitude
The latitude in degrees northwards from the equator,
negative for southwards.
@item longitude
The longitude in degrees eastwards from Greenwich,
negative for westwards.
@end table
@end table

The library also provides the high-level functions:
@table @code
@item solar_elevation(latitude, longitude, t = None)
Calculates the Sun's elevation, in degreesm as apparent
from a geographical position, expressed in degrees by the parameters:
@table @code
@item latitude
The latitude in degrees northwards from the equator,
negative for southwards.
@item longitude
The longitude in degrees eastwards from Greenwich,
negative for westwards.
@end table
@noindent
The function also requires to the in Julian Centuries,
provided via the parameter @code{t}. If @code{t} is
@code{None}, the current time is used.

@item 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 to the in Julian Centuries,
provided via the parameter @code{t}, and the latitude,
provided via the parameter @code{latitude}, in degrees
northwards from the equator, negative for southwards.
If @code{t} is @code{None}, the current time is used.

This function returns a boolean.

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

This function returns a boolean.

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

This function returns a boolean.
@end table



@node Prediction functions
@chapter Prediction functions

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

@table @code
@item 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 @code{None} if the condition is not meet within
the specified timespan, specified by the parameter
@code{span} in Julian Centuries (@code{0.01} for
one year).

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

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

@item 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 @code{delta}.
If this value is negative, a past event will be determined,
and if it is positive, a future event will be predicted.

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

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

@item 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 @code{delta}.
If this value is negative, a past event will be determined,
and if it is positive, a future event will be predicted.

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

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

@item 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
@code{elevation}. @code{None} is returned if not found
withing a year.

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

@item 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 @code{elevation}. @code{None}
is returned if not found withing a year.

@item 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 @code{elevation}. @code{None}
is returned if not found withing a year.

@item 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. @code{None} is returned if not found withing a
year. The sought derivative is specified via the parameter
@code{derivative}, expressed in degrees per Julian Century.

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

@item 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. @code{None}
is returned if not found withing a year. The sought derivative
is specified via the parameter @code{derivative}, expressed in
degrees per Julian Century.

@item 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.
@code{None} is returned if not found withing a year. The
sought derivative is specified via the parameter
@code{derivative}, expressed in degrees per Julian Century.

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



@node Miscellaneous functions
@chapter Miscellaneous functions

Importing @code{solar_python} makes the following
functions available:
@table @code
@item radians(deg)
Convert an angle from degrees to radians.

@item degrees(rad)
Convert an angle from radians to degrees.
@end table



@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texinfo

@bye