diff --git a/generate/template/astronomy.c b/generate/template/astronomy.c index 6021f4a3..745c7ccc 100644 --- a/generate/template/astronomy.c +++ b/generate/template/astronomy.c @@ -3037,8 +3037,13 @@ astro_search_result_t Astronomy_SearchRelativeLongitude(astro_body_t body, doubl * * This function searches for the next time a celestial body reaches the given hour angle * after the date and time specified by `startTime`. - * To find when a body culminates, pass 0 for `startTime`. - * To find when a body reaches its lowest point in the sky, pass 12 for `startTime`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. + * + * Note that, especially close to the Earth's poles, a body as seen on a given day + * may always be above the horizon or always below the horizon, so the caller cannot + * assume that a culminating object is visible nor that an object is below the horizon + * at its minimum altitude. * * On success, the function reports the date and time, along with the horizontal coordinates * of the body at that time, as seen by the given observer. diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 0f02b8d2..879945ef 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -2396,6 +2396,46 @@ class HourAngleEvent: self.hor = hor def SearchHourAngle(body, observer, hourAngle, startTime): + """Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + + The *hour angle* of a celestial body indicates its position in the sky with respect + to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + the number of hours that have passed since the most recent time that the body has culminated, + or reached its highest point. + + This function searches for the next time a celestial body reaches the given hour angle + after the date and time specified by `startTime`. + To find when a body culminates, pass 0 for `hourAngle`. + To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. + + Note that, especially close to the Earth's poles, a body as seen on a given day + may always be above the horizon or always below the horizon, so the caller cannot + assume that a culminating object is visible nor that an object is below the horizon + at its minimum altitude. + + On success, the function reports the date and time, along with the horizontal coordinates + of the body at that time, as seen by the given observer. + + Parameters + ---------- + body : Body + 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. + startTime : Time + The date and time at which to start the search. + + Returns + ------- + #HourAngleEvent + """ if body == Body.Earth: raise EarthNotAllowedError() diff --git a/source/c/README.md b/source/c/README.md index cffb456c..11ade703 100644 --- a/source/c/README.md +++ b/source/c/README.md @@ -701,7 +701,9 @@ If the search does not converge within 20 iterations, it will fail with status c The *hour angle* of a celestial body indicates its position in the sky with respect to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. The hour angle increases by 1 unit for every sidereal hour that passes after that point, up to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates the number of hours that have passed since the most recent time that the body has culminated, or reached its highest point. -This function searches for the next time a celestial body reaches the given hour angle after the date and time specified by `startTime`. To find when a body culminates, pass 0 for `startTime`. To find when a body reaches its lowest point in the sky, pass 12 for `startTime`. +This function searches for the next time a celestial body reaches the given hour angle after the date and time specified by `startTime`. To find when a body culminates, pass 0 for `hourAngle`. To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. + +Note that, especially close to the Earth's poles, a body as seen on a given day may always be above the horizon or always below the horizon, so the caller cannot assume that a culminating object is visible nor that an object is below the horizon at its minimum altitude. On success, the function reports the date and time, along with the horizontal coordinates of the body at that time, as seen by the given observer. diff --git a/source/c/astronomy.c b/source/c/astronomy.c index 3a00408a..21b3f28f 100644 --- a/source/c/astronomy.c +++ b/source/c/astronomy.c @@ -4276,8 +4276,13 @@ astro_search_result_t Astronomy_SearchRelativeLongitude(astro_body_t body, doubl * * This function searches for the next time a celestial body reaches the given hour angle * after the date and time specified by `startTime`. - * To find when a body culminates, pass 0 for `startTime`. - * To find when a body reaches its lowest point in the sky, pass 12 for `startTime`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. + * + * Note that, especially close to the Earth's poles, a body as seen on a given day + * may always be above the horizon or always below the horizon, so the caller cannot + * assume that a culminating object is visible nor that an object is below the horizon + * at its minimum altitude. * * On success, the function reports the date and time, along with the horizontal coordinates * of the body at that time, as seen by the given observer. diff --git a/source/python/README.md b/source/python/README.md index 6bad8be5..c06994d1 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -800,6 +800,40 @@ the function returns `None`. --- + +### SearchHourAngle(body, observer, hourAngle, startTime) + +**Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth.** + +The *hour angle* of a celestial body indicates its position in the sky with respect +to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. +The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. +The hour angle increases by 1 unit for every sidereal hour that passes after that point, up +to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates +the number of hours that have passed since the most recent time that the body has culminated, +or reached its highest point. +This function searches for the next time a celestial body reaches the given hour angle +after the date and time specified by `startTime`. +To find when a body culminates, pass 0 for `hourAngle`. +To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. +Note that, especially close to the Earth's poles, a body as seen on a given day +may always be above the horizon or always below the horizon, so the caller cannot +assume that a culminating object is visible nor that an object is below the horizon +at its minimum altitude. +On success, the function reports the date and time, along with the horizontal coordinates +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. | +| `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. | + +### Returns: #HourAngleEvent + +--- + ### SearchMaxElongation(body, startTime) diff --git a/source/python/astronomy.py b/source/python/astronomy.py index 9189f130..ce6efcd6 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -4457,6 +4457,46 @@ class HourAngleEvent: self.hor = hor def SearchHourAngle(body, observer, hourAngle, startTime): + """Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + + The *hour angle* of a celestial body indicates its position in the sky with respect + to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + the number of hours that have passed since the most recent time that the body has culminated, + or reached its highest point. + + This function searches for the next time a celestial body reaches the given hour angle + after the date and time specified by `startTime`. + To find when a body culminates, pass 0 for `hourAngle`. + To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. + + Note that, especially close to the Earth's poles, a body as seen on a given day + may always be above the horizon or always below the horizon, so the caller cannot + assume that a culminating object is visible nor that an object is below the horizon + at its minimum altitude. + + On success, the function reports the date and time, along with the horizontal coordinates + of the body at that time, as seen by the given observer. + + Parameters + ---------- + body : Body + 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. + startTime : Time + The date and time at which to start the search. + + Returns + ------- + #HourAngleEvent + """ if body == Body.Earth: raise EarthNotAllowedError()