From c64880a7895d67c246e140d03e5a14b24435da5e Mon Sep 17 00:00:00 2001 From: Don Cross Date: Fri, 19 Jul 2019 21:23:52 -0400 Subject: [PATCH] Python: added documentation for function SearchRiseSet. --- generate/template/astronomy.c | 2 +- generate/template/astronomy.py | 43 +++++++++++++++++++++++++++++++++- source/c/README.md | 2 +- source/c/astronomy.c | 2 +- source/python/README.md | 36 +++++++++++++++++++++++++++- source/python/astronomy.py | 43 +++++++++++++++++++++++++++++++++- 6 files changed, 122 insertions(+), 6 deletions(-) diff --git a/generate/template/astronomy.c b/generate/template/astronomy.c index 745c7ccc..b73a5595 100644 --- a/generate/template/astronomy.c +++ b/generate/template/astronomy.c @@ -3202,7 +3202,7 @@ static astro_func_result_t peak_altitude(void *context, astro_time_t time) * The Sun, Moon, or any planet other than the Earth. * * @param observer - * The location where observation takes places. + * The location where observation takes place. * You can create an observer structure by calling #Astronomy_MakeObserver. * * @param direction diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 879945ef..1c50a99b 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -2425,7 +2425,6 @@ def SearchHourAngle(body, observer, hourAngle, startTime): The celestial body, which can the Sun, the Moon, or any planet other than the Earth. observer : Observer Indicates a location on or near the surface of the Earth where the observer is located. - Call #Astronomy_MakeObserver to create an observer structure. hourAngle : float An hour angle value in the range [0.0, 24.0) indicating the number of sidereal hours after the body's most recent culmination. @@ -2516,6 +2515,48 @@ def _peak_altitude(context, time): return context.direction * (alt + _REFRACTION_NEAR_HORIZON) def SearchRiseSet(body, observer, direction, startTime, limitDays): + """Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. + + This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + Rise time is when the body first starts to be visible above the horizon. + For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + Set time is the moment when the body appears to vanish below the horizon. + + This function corrects for typical atmospheric refraction, which causes celestial + bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + + Note that rise or set may not occur in every 24 hour period. + For example, near the Earth's poles, there are long periods of time where + the Sun stays below the horizon, never rising. + Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + significant amount during each rotation of the Earth. + Therefore callers must not assume that the function will always succeed. + + Parameters + ---------- + body : Body + The Sun, Moon, or any planet other than the Earth. + observer : Observer + The location where observation takes place. + direction : Direction + Either `Direction.Rise` to find a rise time or `Direction.Set` to find a set time. + startTime : Time + The date and time at which to start the search. + limitDays : float + Limits how many days to search for a rise or set time. + To limit a rise or set time to the same day, you can use a value of 1 day. + In cases where you want to find the next rise or set time no matter how far + in the future (for example, for an observer near the south pole), you can pass + in a larger value like 365. + + Returns + ------- + #Time or `None` + If the rise or set time is found within the specified time window, + this function returns that time. Otherwise, it returns `None`. + """ if body == Body.Earth: raise EarthNotAllowedError() elif body == Body.Sun: diff --git a/source/c/README.md b/source/c/README.md index 11ade703..cc34245a 100644 --- a/source/c/README.md +++ b/source/c/README.md @@ -920,7 +920,7 @@ Note that rise or set may not occur in every 24 hour period. For example, near t | Type | Parameter | Description | | --- | --- | --- | | [`astro_body_t`](#astro_body_t) | `body` | The Sun, Moon, or any planet other than the Earth. | -| [`astro_observer_t`](#astro_observer_t) | `observer` | The location where observation takes places. You can create an observer structure by calling [`Astronomy_MakeObserver`](#Astronomy_MakeObserver). | +| [`astro_observer_t`](#astro_observer_t) | `observer` | The location where observation takes place. You can create an observer structure by calling [`Astronomy_MakeObserver`](#Astronomy_MakeObserver). | | [`astro_direction_t`](#astro_direction_t) | `direction` | Either `DIRECTION_RISE` to find a rise time or `DIRECTION_SET` to find a set time. | | [`astro_time_t`](#astro_time_t) | `startTime` | The date and time at which to start the search. | | `double` | `limitDays` | Limits how many days to search for a rise or set time. To limit a rise or set time to the same day, you can use a value of 1 day. In cases where you want to find the next rise or set time no matter how far in the future (for example, for an observer near the south pole), you can pass in a larger value like 365. | diff --git a/source/c/astronomy.c b/source/c/astronomy.c index 21b3f28f..d82ae92b 100644 --- a/source/c/astronomy.c +++ b/source/c/astronomy.c @@ -4441,7 +4441,7 @@ static astro_func_result_t peak_altitude(void *context, astro_time_t time) * The Sun, Moon, or any planet other than the Earth. * * @param observer - * The location where observation takes places. + * The location where observation takes place. * You can create an observer structure by calling #Astronomy_MakeObserver. * * @param direction diff --git a/source/python/README.md b/source/python/README.md index c06994d1..4a115b0f 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -826,7 +826,7 @@ of the body at that time, as seen by the given observer. | Type | Parameter | Description | | --- | --- | --- | | [`Body`](#Body) | `body` | The celestial body, which can the Sun, the Moon, or any planet other than the Earth. | -| [`Observer`](#Observer) | `observer` | Indicates a location on or near the surface of the Earth where the observer is located. Call #Astronomy_MakeObserver to create an observer structure. | +| [`Observer`](#Observer) | `observer` | Indicates a location on or near the surface of the Earth where the observer is located. | | `float` | `hourAngle` | An hour angle value in the range [0.0, 24.0) indicating the number of sidereal hours after the body's most recent culmination. | | [`Time`](#Time) | `startTime` | The date and time at which to start the search. | @@ -971,6 +971,40 @@ The date and time of the relative longitude event. --- + +### SearchRiseSet(body, observer, direction, startTime, limitDays) + +**Searches for the next time a celestial body rises or sets as seen by an observer on the Earth.** + +This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. +Rise time is when the body first starts to be visible above the horizon. +For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. +Set time is the moment when the body appears to vanish below the horizon. +This function corrects for typical atmospheric refraction, which causes celestial +bodies to appear higher above the horizon than they would if the Earth had no atmosphere. +It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). +Note that rise or set may not occur in every 24 hour period. +For example, near the Earth's poles, there are long periods of time where +the Sun stays below the horizon, never rising. +Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. +This is because the Moon sets nearly an hour later each day due to orbiting the Earth a +significant amount during each rotation of the Earth. +Therefore callers must not assume that the function will always succeed. + +| Type | Parameter | Description | +| --- | --- | --- | +| [`Body`](#Body) | `body` | The Sun, Moon, or any planet other than the Earth. | +| [`Observer`](#Observer) | `observer` | The location where observation takes place. | +| [`Direction`](#Direction) | `direction` | Either `Direction.Rise` to find a rise time or `Direction.Set` to find a set time. | +| [`Time`](#Time) | `startTime` | The date and time at which to start the search. | +| `float` | `limitDays` | Limits how many days to search for a rise or set time. To limit a rise or set time to the same day, you can use a value of 1 day. In cases where you want to find the next rise or set time no matter how far in the future (for example, for an observer near the south pole), you can pass in a larger value like 365. | + +### Returns: #Time or `None` +If the rise or set time is found within the specified time window, +this function returns that time. Otherwise, it returns `None`. + +--- + ### SearchSunLongitude(targetLon, startTime, limitDays) diff --git a/source/python/astronomy.py b/source/python/astronomy.py index ce6efcd6..1b7b7505 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -4486,7 +4486,6 @@ def SearchHourAngle(body, observer, hourAngle, startTime): The celestial body, which can the Sun, the Moon, or any planet other than the Earth. observer : Observer Indicates a location on or near the surface of the Earth where the observer is located. - Call #Astronomy_MakeObserver to create an observer structure. hourAngle : float An hour angle value in the range [0.0, 24.0) indicating the number of sidereal hours after the body's most recent culmination. @@ -4577,6 +4576,48 @@ def _peak_altitude(context, time): return context.direction * (alt + _REFRACTION_NEAR_HORIZON) def SearchRiseSet(body, observer, direction, startTime, limitDays): + """Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. + + This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + Rise time is when the body first starts to be visible above the horizon. + For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + Set time is the moment when the body appears to vanish below the horizon. + + This function corrects for typical atmospheric refraction, which causes celestial + bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + + Note that rise or set may not occur in every 24 hour period. + For example, near the Earth's poles, there are long periods of time where + the Sun stays below the horizon, never rising. + Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + significant amount during each rotation of the Earth. + Therefore callers must not assume that the function will always succeed. + + Parameters + ---------- + body : Body + The Sun, Moon, or any planet other than the Earth. + observer : Observer + The location where observation takes place. + direction : Direction + Either `Direction.Rise` to find a rise time or `Direction.Set` to find a set time. + startTime : Time + The date and time at which to start the search. + limitDays : float + Limits how many days to search for a rise or set time. + To limit a rise or set time to the same day, you can use a value of 1 day. + In cases where you want to find the next rise or set time no matter how far + in the future (for example, for an observer near the south pole), you can pass + in a larger value like 365. + + Returns + ------- + #Time or `None` + If the rise or set time is found within the specified time window, + this function returns that time. Otherwise, it returns `None`. + """ if body == Body.Earth: raise EarthNotAllowedError() elif body == Body.Sun: