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

Python: include documentation about function return values in Markdown.

Browse Source
This commit is contained in:
Don Cross
2019-07-13 17:48:15 -04:00
parent 7721f7a735
commit 8a18cdc58a
4 changed files with 109 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
source/python/README.md
View File

@@ -146,6 +146,9 @@ dates and times represented by `Time` objects.
| `int` | `minute` | The UTC minute, in the range 0..59. |
| `float` | `second` | The real-valued UTC second, in the range [0, 60). |
### Returns: #Time
@@ -392,6 +395,11 @@ easy it is to see the body away from the glare of the Sun.
| [`Body`](#Body) | `body` | The celestial body whose angle from the Sun is to be measured. Not allowed to be `Body.Earth`. |
| [`Time`](#Time) | `time` | The time at which the observation is made. |
### Returns: `float`
A numeric value indicating the angle in degrees between the Sun
and the specified body as seen from the center of the Earth.
@@ -412,6 +420,12 @@ easy it is to see the body away from the glare of the Sun.
| --- | --- | --- |
| `str` | `name` | The common English name of a supported celestial body. |
### Returns: #Body
If `name` is a valid body name, returns the enumeration
value associated with that body.
Otherwise, returns `Body.Invalid`.
@@ -429,6 +443,10 @@ equ : EquatorialCoordinates
Equatorial coordinates in the J2000 frame of reference.
### Returns: #EclipticCoordinates
Ecliptic coordinates in the J2000 frame of reference.
@@ -451,6 +469,10 @@ time : Time
| --- | --- | --- |
| [`Body`](#Body) | `body` | A body other than the Sun. |
### Returns: `float`
An angular value in degrees indicating the ecliptic longitude of the body.
@@ -482,6 +504,9 @@ time : Time
| --- | --- | --- |
| [`Body`](#Body) | `body` | The celestial body whose visibility is to be calculated. |
### Returns: #ElongationEvent
@@ -512,6 +537,10 @@ Correction for aberration is optional, using the `aberration` parameter.
| `bool` | `ofdate` | Selects the date of the Earth's equator in which to express the equatorial coordinates. If `True`, returns coordinates using the equator and equinox of date. If `False`, returns coordinates converted to the J2000 system. |
| `bool` | `aberration` | If `True`, corrects for aberration of light based on the motion of the Earth with respect to the heliocentric origin. If `False`, does not correct for aberration. |
### Returns: #EquatorialCoordinates
Equatorial coordinates in the specified frame of reference.
@@ -536,6 +565,10 @@ by Montenbruck and Pfleger.
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's position. |
### Returns: #Vector
The Moon's position as a vector in J2000 Cartesian equatorial coordinates.
@@ -567,6 +600,10 @@ movement of the Earth with respect to the rays of light coming from that body.
| [`Time`](#Time) | `time` | The date and time for which to calculate the position. |
| `bool` | `aberration` | A boolean value indicating whether to correct for aberration. |
### Returns: #Vector
A geocentric position vector of the center of the given body.
@@ -592,6 +629,11 @@ the year range 1700..2200, this function raise an exception.
| [`Body`](#Body) | `body` | The celestial body whose heliocentric position is to be calculated: The Sun, Moon, or any of the planets. |
| [`Time`](#Time) | `time` | The time at which to calculate the heliocentric position. |
### Returns: #Vector
A heliocentric position vector of the center of the given body
at the given time.
@@ -624,6 +666,13 @@ the right ascension and declination in the returned object will be numerically i
to the respective `ra` and `dec` values passed in.
### Returns: #HorizontalCoordinates
The horizontal coordinates (altitude and azimuth), along with
equatorial coordinates (right ascension and declination), all
optionally corrected for atmospheric refraction. See remarks above
for more details.
@@ -658,6 +707,10 @@ time : Time
| --- | --- | --- |
| [`Body`](#Body) | `body` | The celestial body for which to find longitude from the Sun. |
### Returns: `float`
An angle in degrees in the range [0, 360).
@@ -719,6 +772,15 @@ dt_tolerance_seconds : float
| --- | --- | --- |
| `function(context, Time)` | `func` | A function that takes an arbitrary context parameter and a #Time parameter. Returns a float value. See remarks above for more details. |
### Returns: #Time or `None`
If the search is successful, returns a #Time object that is within
`dt_tolerance_seconds` of an ascending root.
In this case, the returned time value will always be within the
inclusive range [`t1`, `t2`].
If there is no ascending root, or there is more than one ascending root,
the function returns `None`.
@@ -764,6 +826,10 @@ the Earth and another planet:
| `float` | `targetRelLon` | The desired relative longitude, expressed in degrees. Must be in the range [0, 360). |
| [`Time`](#Time) | `startTime` | The date and time at which to begin the search. |
### Returns: #Time
The date and time of the relative longitude event.
@@ -792,5 +858,9 @@ In fact, the function #Seasons does use this function for that purpose.
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time for which to calculate the Sun's position. |
### Returns: #EclipticCoordinates
The ecliptic coordinates of the Sun using the Earth's true equator of date.

25
source/python/astronomy.py
View File

@@ -143,7 +143,7 @@ def BodyCode(name):
Returns
-------
Body
#Body
If `name` is a valid body name, returns the enumeration
value associated with that body.
Otherwise, returns `Body.Invalid`.
@@ -432,6 +432,7 @@ class Time:
Returns
-------
#Time
"""
micro = round(math.fmod(second, 1.0) * 1000000)
second = math.floor(second - micro/1000000)
@@ -2086,7 +2087,7 @@ def GeoMoon(time):
Returns
-------
Vector
#Vector
The Moon's position as a vector in J2000 Cartesian equatorial coordinates.
"""
@@ -3207,7 +3208,7 @@ def GeoVector(body, time, aberration):
Returns
-------
Vector
#Vector
A geocentric position vector of the center of the given body.
"""
if body == Body.Moon:
@@ -3289,7 +3290,7 @@ def Equator(body, time, observer, ofdate, aberration):
Returns
-------
Equatorial
#EquatorialCoordinates
Equatorial coordinates in the specified frame of reference.
"""
gc_observer = _geo_pos(time, observer)
@@ -3377,7 +3378,7 @@ def Horizon(time, observer, ra, dec, refraction):
Returns
-------
HorizontalCoordinates
#HorizontalCoordinates
The horizontal coordinates (altitude and azimuth), along with
equatorial coordinates (right ascension and declination), all
optionally corrected for atmospheric refraction. See remarks above
@@ -3542,7 +3543,7 @@ def SunPosition(time):
Returns
-------
EclipticCoordinates
#EclipticCoordinates
The ecliptic coordinates of the Sun using the Earth's true equator of date.
"""
# Correct for light travel time from the Sun.
@@ -3571,7 +3572,7 @@ def Ecliptic(equ):
Returns
-------
EclipticCoordinates
#EclipticCoordinates
Ecliptic coordinates in the J2000 frame of reference.
"""
# Based on NOVAS functions equ2ecl() and equ2ecl_vec().
@@ -3596,7 +3597,7 @@ def EclipticLongitude(body, time):
Returns
-------
float
`float`
An angular value in degrees indicating the ecliptic longitude of the body.
"""
if body == Body.Sun:
@@ -3622,7 +3623,7 @@ def AngleFromSun(body, time):
Returns
-------
float
`float`
A numeric value indicating the angle in degrees between the Sun
and the specified body as seen from the center of the Earth.
"""
@@ -3666,7 +3667,7 @@ def LongitudeFromSun(body, time):
Returns
-------
float
`float`
An angle in degrees in the range [0, 360).
"""
if body == Body.Earth:
@@ -3741,7 +3742,7 @@ def Elongation(body, time):
Returns
-------
ElongationEvent
#ElongationEvent
"""
angle = LongitudeFromSun(body, time)
if angle > 180.0:
@@ -3807,7 +3808,7 @@ def SearchRelativeLongitude(body, targetRelLon, startTime):
Returns
-------
Time
#Time
The date and time of the relative longitude event.
"""
if body == Body.Earth: