info manual

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 159 insertions, 221 deletions

diff --git a/doc/info/solar-python.texinfo b/doc/info/solar-python.texinfo
index b47a789..624e244 100644
--- a/doc/info/solar-python.texinfo
+++ b/doc/info/solar-python.texinfo
@@ -87,27 +87,35 @@ constants available:
 @table @code
 @item SOLAR_APPARENT_RADIUS = 32 / 60
 Approximate apparent size of the Sun in degrees.
+
 @item SOLAR_ELEVATION_SUNSET_SUNRISE = 0.0
 The Sun's elevation at sunset and 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_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, 0.0)
 The Sun's lowest and highest elevation during
 civil twilight, measured in degrees
+
 @item SOLAR_ELEVATION_RANGE_NAUTICAL_TWILIGHT = (-12.0, -6.0)
 The Sun's lowest and highest elevation during
 nautical twilight, measured in degrees
+
 @item SOLAR_ELEVATION_RANGE_ASTRONOMICAL_TWILIGHT = (-18.0, -12.0)
 The Sun's lowest and highest elevation during
 astronomical twilight, measured in degrees
@@ -121,19 +129,25 @@ astronomical twilight, measured in degrees
 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}.
+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
@@ -146,8 +160,10 @@ type @code{float}, and all functions return
 @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
@@ -167,29 +183,39 @@ 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
@@ -202,6 +228,7 @@ 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
@@ -214,6 +241,7 @@ 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
@@ -223,6 +251,7 @@ requires one additional parameter:
 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
@@ -244,6 +273,7 @@ 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
@@ -275,6 +305,7 @@ negative for westwards.
 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,
@@ -285,6 +316,8 @@ 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.
@@ -294,6 +327,8 @@ 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.
@@ -302,6 +337,8 @@ 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
 
 
@@ -309,6 +346,124 @@ If @code{t} is @code{None}, the current time is used.
 @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
@@ -317,9 +472,10 @@ If @code{t} is @code{None}, the current time is used.
 Importing @code{solar_python} makes the following
 functions available:
 @table @code
-@item radians(deg):
+@item radians(deg)
 Convert an angle from degrees to radians.
-@item degrees(rad):
+
+@item degrees(rad)
 Convert an angle from radians to degrees.
 @end table
 
@@ -331,221 +487,3 @@ Convert an angle from radians to degrees.
 
 @bye
 
-
-
-
-
------------------------------  Prediction functions  -----------------------------
-
-def 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
-    
-    @param   delta:float          Iteration step size, negative for past
-                                  event, positive for future event
-    @param   requested:float      The value returned by `fun` for which to
-                                  calculate the time point of occurrence
-    @param   fun:(t:float)→float  Function that calculate the data of interest
-    @param   epsilon:float        Error tolerance for `requested`
-    @param   span:float           The number of Julian centuries (0,01 for
-                                  one year) to restrict the search to
-    @param   t:float?             The time in Julian Centuries, `None` for
-                                  the current time
-    @return  :float?              The calculated time point, `None` if none
-                                  were found within the specified time span
-    '''
-
-def future_past_equinox(delta, t = None):
-    '''
-    Predict the time point of the next or previous equinox
-    
-    @param   delta:float  Iteration step size, negative for
-                          past event, positive for future event
-    @param   t:float?     The time in Julian Centuries, `None`
-                          for the current time
-    @return  :float       The calculated time point
-    '''
-    return solar_prediction(delta, 0, solar_declination, t = t)
-
-
-def future_equinox(t = None):
-    '''
-    Predict the time point of the next equinox
-    
-    @param   t:float?     The time in Julian Centuries, `None`
-                          for the current time
-    @return  :float       The calculated time point
-    '''
-    return future_past_equinox(0.01 / 2000, t)
-    
-
-def past_equinox(t = None):
-    '''
-    Predict the time point of the previous equinox
-    
-    @param   t:float?     The time in Julian Centuries, `None`
-                          for the current time
-    @return  :float       The calculated time point
-    '''
-    return future_past_equinox(0.01 / -2000, t)
-
-
-
-def future_past_solstice(delta, t = None):
-    '''
-    Predict the time point of the next or previous solstice
-    
-    @param   delta:float  Iteration step size, negative for
-                          past event, positive for future event
-    @param   t:float?     The time in Julian Centuries, `None`
-                          for the current time
-    @return  :float       The calculated time point
-    '''
-    e = 0.00001
-    fun = solar_declination
-    dfun = lambda t : (fun(t + e) - fun(t - e)) / 2
-    return solar_prediction(delta, 0, dfun, t = t)
-
-
-def future_solstice(t = None):
-    '''
-    Predict the time point of the next solstice
-    
-    @param   t:float?  The time in Julian Centuries,
-                       `None` for the current time
-    @return  :float    The calculated time point
-    '''
-    return future_past_solstice(0.01 / 2000, t)
-    
-
-def past_solstice(t = None):
-    '''
-    Predict the time point of the previous solstice
-    
-    @param   t:float?  The time in Julian Centuries,
-                       `None` for the current time
-    @return  :float    The calculated time point
-    '''
-    return future_past_solstice(0.01 / -2000, t)
-
-
-
-def future_past_elevation(delta, latitude, longitude, elevation, t = None):
-    '''
-    Predict the time point of the next or previous time
-    the Sun reaches or reached a specific elevation
-    
-    @param   delta:float      Iteration step size, negative for past
-                              event, positive for future event
-    @param   latitude:float   The latitude in degrees northwards from
-                              the equator, negative for southwards
-    @param   longitude:float  The longitude in degrees eastwards from
-                              Greenwich, negative for westwards
-    @param   elevation:float  The elevation of interest
-    @param   t:float?         The time in Julian Centuries, `None`
-                              for the current time
-    @return  :float?          The calculated time point, `None` if
-                              none were found within a year
-    '''
-    fun = lambda t : solar_elevation(latitude, longitude, t)
-    return solar_prediction(delta, elevation, fun, t = t)
-
-
-def future_elevation(latitude, longitude, elevation, t = None):
-    '''
-    Predict the time point of the next time the Sun
-    reaches a specific elevation
-    
-    @param   latitude:float   The latitude in degrees northwards from
-                              the equator, negative for southwards
-    @param   longitude:float  The longitude in degrees eastwards from
-                              Greenwich, negative for westwards
-    @param   elevation:float  The elevation of interest
-    @param   t:float?         The time in Julian Centuries, `None`
-                              for the current time
-    @return  :float?          The calculated time point, `None` if
-                              none were found within a year
-    '''
-    return future_past_elevation(0.01 / 2000, latitude, longitude, elevation, t)
-    
-
-def past_elevation(latitude, longitude, elevation, t = None):
-    '''
-    Predict the time point of the previous time the Sun
-    reached a specific elevation
-    
-    @param   latitude:float   The latitude in degrees northwards from
-                              the equator, negative for southwards
-    @param   longitude:float  The longitude in degrees eastwards from
-                              Greenwich, negative for westwards
-    @param   elevation:float  The elevation of interest
-    @param   t:float?         The time in Julian Centuries, `None`
-                              for the current time
-    @return  :float?          The calculated time point, `None` if
-                              none were found within a year
-    '''
-    return future_past_elevation(0.01 / -2000, latitude, longitude, elevation, t)
-
-
-
-def future_past_elevation_derivative(delta, latitude, longitude, derivative, t = None):
-    '''
-    Predict the time point of the next or previous time the
-    Sun reaches or reached a specific elevation derivative
-    
-    @param   delta:float       Iteration step size, negative for past
-                               event, positive for future event
-    @param   latitude:float    The latitude in degrees northwards from
-                               the equator, negative for southwards
-    @param   longitude:float   The longitude in degrees eastwards from
-                               Greenwich, negative for westwards
-    @param   derivative:float  The elevation derivative value of interest
-    @param   t:float?          The time in Julian Centuries, `None`
-                               for the current time
-    @return  :float?           The calculated time point, `None` if
-                               none were found within a year
-    '''
-    fun = lambda t : solar_elevation(latitude, longitude, t)
-    dfun = lambda t : (fun(t + e) - fun(t - e)) / 2
-    return solar_prediction(delta, derivative, dfun, t = t)
-
-
-def future_elevation_derivative(latitude, longitude, derivative, t = None):
-    '''
-    Predict the time point of the next time the
-    Sun reaches a specific elevation derivative
-    
-    @param   latitude:float    The latitude in degrees northwards from
-                               the equator, negative for southwards
-    @param   longitude:float   The longitude in degrees eastwards from
-                               Greenwich, negative for westwards
-    @param   derivative:float  The elevation derivative value of interest
-    @param   t:float?          The time in Julian Centuries, `None`
-                               for the current time
-    @return  :float?           The calculated time point, `None` if
-                               none were found within a year
-    '''
-    return future_past_elevation_derivative(0.01 / 2000, latitude, longitude, derivative, t)
-    
-
-def past_elevation_derivative(latitude, longitude, derivative, t = None):
-    '''
-    Predict the time point of the previous time
-    the Sun reached a specific elevation derivative
-    
-    @param   latitude:float    The latitude in degrees northwards from
-                               the equator, negative for southwards
-    @param   longitude:float   The longitude in degrees eastwards from
-                               Greenwich, negative for westwards
-    @param   derivative:float  The elevation derivative value of interest
-    @param   t:float?          The time in Julian Centuries, `None`
-                               for the current time
-    @return  :float?           The calculated time point, `None`
-                               if none were found within a year
-    '''
-    return future_past_elevation_derivative(0.01 / -2000, latitude, longitude, derivative, t)
-
-
-# This algorithm is imprecise, gives an incorrent sunrise and I do not fully know its behaviour
-def sunrise_equation(latitude, longitude, t = None):