mirror/astronomy
1
0
Fork 0
mirror of https://github.com/cosinekitty/astronomy.git synced 2026-05-19 06:17:03 -04:00
Code Issues Packages Projects Releases Wiki Activity

Python: added documentation for function SearchHourAngle.

Browse Source
This commit is contained in:
Don Cross
2019-07-19 21:11:54 -04:00
parent f7bda9890c
commit 91e4c7c8d2
6 changed files with 131 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
generate/template/astronomy.c
View File

@@ -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.

40
generate/template/astronomy.py
View File

@@ -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()

4
source/c/README.md
View File

@@ -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.

9
source/c/astronomy.c
View File

@@ -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.

34
source/python/README.md
View File

@@ -800,6 +800,40 @@ the function returns `None`.
---
<a name="SearchHourAngle"></a>
### 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
---
<a name="SearchMaxElongation"></a>
### SearchMaxElongation(body, startTime)

40
source/python/astronomy.py
View File

@@ -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()