aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/info/solar-python.texinfo380
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):