Imrpove makefile and flatten the hier a bit

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 511 insertions, 0 deletions

diff --git a/info/solar-python.texinfo b/info/solar-python.texinfo
new file mode 100644
index 0000000..e33d6e0
--- /dev/null
+++ b/info/solar-python.texinfo
@@ -0,0 +1,511 @@
+\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.
+
+@item 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.
+@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
+