From c36b943c7d4a64c9e50fcd2db535ad8f88ce6efc Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Thu, 5 Jun 2014 05:37:41 +0200 Subject: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- info/blueshift.texinfo | 70 +++++++++++++++++++++++++++++++++++++++++++++++--- src/solar.py | 14 ---------- 2 files changed, 67 insertions(+), 17 deletions(-) diff --git a/info/blueshift.texinfo b/info/blueshift.texinfo index be30aad..4b3dce1 100644 --- a/info/blueshift.texinfo +++ b/info/blueshift.texinfo @@ -1372,6 +1372,15 @@ geographical position (@code{latitude}, @code{longitude}). Calculates the same thing as @code{solar_elevation_from_time}, except the time is optional and defaults to the current time. +@item have_sunrise_and_sunset(latitude, t = None) +Determine whether you have sunrise and sunsets. + +@item is_summer(latitude, t = None) +Determine whether it is summer. + +@item is_winter(latitude, t = None) +Determine whether it is winter. + @item future_past_elevation(delta, latitude, longitude, elevation, t = None) Calculates the next or previous point in time the Sun's elevation will be @code{elevation} degrees or was @@ -1379,12 +1388,12 @@ elevation will be @code{elevation} degrees or was (@code{latitude}, @code{longitude}). The calculated timepoint may actually be the current time, @code{t}. If not time point can be found within a Julian year -@code{None} will be returned. This function uses -interpolation to determine time point, because inverting +@code{None} will be returned. This function uses binary +search to determine time point, because inverting @code{solar_elevation} is unfeasible to do algebraically; @code{delta} specified the size of the steps between the timepoints that are tested to determine the timespan in -which to do the interpolation. +which to do the binary search. @item future_elevation(latitude, longitude, elevation, t = None) Calculates the next point in time the Sun's elevation will @@ -1401,6 +1410,61 @@ Calculates the previous point in time the Sun's elevation was timepoint may actually be the current time, @code{t}. If not time point can be found within a Julian year @code{None} will be returned. This function uses + +@item future_past_elevation_derivative(delta, latitude, longitude, derivative, t = None) +Similar to @code{future_past_elevation}, but calculates the +time point for a first derivative of the solar elevation. + +@item future_elevation_derivative(latitude, longitude, derivative, t = None) +Similar to @code{future_elevation}, but calculates the +time point for a first derivative of the solar elevation. + +@item past_elevation_derivative(latitude, longitude, derivative, t = None) +Similar to @code{past_elevation}, but calculates the +time point for a first derivative of the solar elevation. + +@item future_past_equinox(delta, t = None) +Similar to @code{future_past_elevation}, but calculates the +time point for an equinox. The result cannot be @code{None}. + +@item future_equinox(t = None) +Similar to @code{future_elevation}, but calculates the +time point for an equinox. The result cannot be @code{None}. + +@item past_equinox(t = None) +Similar to @code{past_elevation}, but calculates the +time point for an equinox. The result cannot be @code{None}. + +@item future_past_solstice(delta, t = None) +Similar to @code{future_past_elevation}, but calculates the +time point for a solstice. The result cannot be @code{None}. + +@item future_solstice(t = None) +Similar to @code{future_elevation}, but calculates the +time point for a solstice. The result cannot be @code{None}. + +@item past_solstice(t = None) +Similar to @code{past_elevation}, but calculates the +time point for a solstice. The result cannot be @code{None}. + +@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 by way of +binary searching. This conditions is satisfied if +@code{fun} of a timepoint equals @code{requested} +with a tolerance of @code{epsilon}. +@code{delta} specified the size of the steps between the +timepoints that are tested to determine the timespan in +which to do the binary search. This timespan is limited +to @code{span} with is a timespan in Julian Centuries; +0,01 is approximately one Gregorian year. +If no satisfactory timepoint can be found +within the specified span @code{None} is returned. + +@item ptime(t) +Prints a time, input in the Julian Centuries format, +as a human-readable local time. + @end table For all functions beneath @code{degrees}, @code{t} is the diff --git a/src/solar.py b/src/solar.py index 1cdf017..38fa11b 100644 --- a/src/solar.py +++ b/src/solar.py @@ -468,7 +468,6 @@ def solar_elevation(latitude, longitude, t = None): -# TODO document def have_sunrise_and_sunset(latitude, t = None): ''' Determine whether solar declination currently is @@ -494,7 +493,6 @@ def have_sunrise_and_sunset(latitude, t = None): return -90 - d < latitude < 90 + d -# TODO document def is_summer(latitude, t = None): ''' Determine whether it is summer @@ -511,7 +509,6 @@ def is_summer(latitude, t = None): return (d > 0) == (latitude > 0) -# TODO document def is_winter(latitude, t = None): ''' Determine whether it is winter @@ -529,7 +526,6 @@ def is_winter(latitude, t = None): -# TODO document def solar_prediction(delta, requested, fun, epsilon = 0.000001, span = 0.01, t = None): ''' Predict the time point of the next or previous @@ -583,7 +579,6 @@ def solar_prediction(delta, requested, fun, epsilon = 0.000001, span = 0.01, t = -# TODO document def future_past_equinox(delta, t = None): ''' Predict the time point of the next or previous equinox @@ -597,7 +592,6 @@ def future_past_equinox(delta, t = None): return solar_prediction(delta, 0, solar_declination, t = t) -# TODO document def future_equinox(t = None): ''' Predict the time point of the next equinox @@ -611,7 +605,6 @@ def future_equinox(t = None): return future_past_equinox(0.01 / 2000, t) -# TODO document def past_equinox(t = None): ''' Predict the time point of the previous equinox @@ -626,7 +619,6 @@ def past_equinox(t = None): -# TODO document def future_past_solstice(delta, t = None): ''' Predict the time point of the next or previous solstice @@ -643,7 +635,6 @@ def future_past_solstice(delta, t = None): return solar_prediction(delta, 0, dfun, t = t) -# TODO document def future_solstice(t = None): ''' Predict the time point of the next solstice @@ -655,7 +646,6 @@ def future_solstice(t = None): return future_past_solstice(0.01 / 2000, t) -# TODO document def past_solstice(t = None): ''' Predict the time point of the previous solstice @@ -726,7 +716,6 @@ def past_elevation(latitude, longitude, elevation, t = None): -# TODO document def future_past_elevation_derivative(delta, latitude, longitude, derivative, t = None): ''' Predict the time point of the next or previous time the @@ -749,7 +738,6 @@ def future_past_elevation_derivative(delta, latitude, longitude, derivative, t = return solar_prediction(delta, derivative, dfun, t = t) -# TODO document def future_elevation_derivative(latitude, longitude, derivative, t = None): ''' Predict the time point of the next time the @@ -768,7 +756,6 @@ def future_elevation_derivative(latitude, longitude, derivative, t = None): return future_past_elevation_derivative(0.01 / 2000, latitude, longitude, derivative, t) -# TODO document def past_elevation_derivative(latitude, longitude, derivative, t = None): ''' Predict the time point of the previous time @@ -831,7 +818,6 @@ def sunrise_equation(latitude, longitude, t = None): -# TODO document def ptime(t): ''' Print a time stamp in human-readable local time -- cgit v1.2.3-70-g09d2