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

Python documentation: remove extraneous blank lines from Markdown.

Browse Source
This commit is contained in:
Don Cross
2019-07-17 20:21:36 -04:00
parent 3ad7c7d9ec
commit 746dbe2409
2 changed files with 4 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
source/python/README.md
View File

@@ -3,7 +3,6 @@
<a name="classes"></a>
## Classes
---
<a name="Apsis"></a>
@@ -21,7 +20,6 @@ point is called *apogee*. The closest approach of a planet to the Sun is called
This data structure is returned by #SearchLunarApsis and #NextLunarApsis
to iterate through consecutive alternating perigees and apogees.
| Type | Attribute | Description |
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time of the apsis. |
@@ -29,9 +27,6 @@ to iterate through consecutive alternating perigees and apogees.
| `float` | `dist_au` | The distance between the centers of the bodies in astronomical units. |
| `float` | `dist_km` | The distance between the centers of the bodies in kilometers. |
---
<a name="EclipticCoordinates"></a>
@@ -42,7 +37,6 @@ to iterate through consecutive alternating perigees and apogees.
Coordinates of a celestial body as seen from the center of the Sun (heliocentric),
oriented with respect to the plane of the Earth's orbit around the Sun (the ecliptic).
| Type | Attribute | Description |
| --- | --- | --- |
| `float` | `ex` | Cartesian x-coordinate: in the direction of the equinox along the ecliptic plane. |
@@ -51,9 +45,6 @@ oriented with respect to the plane of the Earth's orbit around the Sun (the ecli
| `float` | `elat` | Latitude in degrees north (positive) or south (negative) of the ecliptic plane. |
| `float` | `elon` | Longitude in degrees around the ecliptic plane prograde from the equinox. |
---
<a name="ElongationEvent"></a>
@@ -64,7 +55,6 @@ oriented with respect to the plane of the Earth's orbit around the Sun (the ecli
See the #Elongation function for more detailed information about the members of this class.
See also #SearchMaxElongation for how to search for maximum elongation events.
| Type | Attribute | Description |
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time of the observation. |
@@ -72,9 +62,6 @@ See also #SearchMaxElongation for how to search for maximum elongation events.
| `float` | `elongation` | The angle in degrees between the body and the Sun, as seen from the Earth. |
| `float` | `ecliptic_separation` | The difference between the ecliptic longitudes of the body and the Sun, as seen from the Earth. |
---
<a name="Equatorial"></a>
@@ -87,16 +74,12 @@ Can be geocentric or topocentric, depending on context.
The coordinates are oriented with respect to the Earth's
equator projected onto the sky.
| Type | Attribute | Description |
| --- | --- | --- |
| `float` | `ra` | Right ascension in sidereal hours. |
| `float` | `dec` | Declination in degrees. |
| `float` | `dist` | Distance to the celestial body in AU. |
---
<a name="HorizontalCoordinates"></a>
@@ -108,7 +91,6 @@ Contains horizontal and equatorial coordinates as seen by an observer
on or near the surface of the Earth (a topocentric observer).
All coordinates are optionally corrected for atmospheric refraction.
| Type | Attribute | Description |
| --- | --- | --- |
| `float` | `azimuth` | The compass direction laterally around the observer's horizon, measured in degrees. North is 0 degrees, east is 90 degrees, south is 180 degrees, etc. |
@@ -116,9 +98,6 @@ All coordinates are optionally corrected for atmospheric refraction.
| `float` | `ra` | The right ascension in sidereal hours. |
| `float` | `dec` | The declination in degrees. |
---
<a name="HourAngleEvent"></a>
@@ -129,15 +108,11 @@ All coordinates are optionally corrected for atmospheric refraction.
Returned by the function #Astronomy_SearchHourAngle to report information about
a celestial body crossing a certain hour angle as seen by a specified topocentric observer.
| Type | Attribute | Description |
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time when the body crosses the specified hour angle. |
| [`HorizontalCoordinates`](#HorizontalCoordinates) | `hor` | Apparent coordinates of the body at the time it crosses the specified hour angle. |
---
<a name="MoonQuarter"></a>
@@ -152,15 +127,11 @@ Along with the `quarter` attribute that specifies the
type of quarter, it contains a `time` field that indicates
when the lunar quarter event happens.
| Type | Attribute | Description |
| --- | --- | --- |
| `int` | `quarter` | 0=new moon, 1=first quarter, 2=full moon, 3=third quarter. |
| [`Time`](#Time) | `time` | The date and time of the lunar quarter. |
---
<a name="Observer"></a>
@@ -174,9 +145,6 @@ when the lunar quarter event happens.
| `float` | `longitude` | Geographic longitude in degrees east of the prime meridian at Greenwich, England. |
| `float` | `height` | Elevation above sea level in meters. |
---
<a name="Time"></a>
@@ -187,7 +155,6 @@ when the lunar quarter event happens.
All calculations performed by Astronomy Engine are based on
dates and times represented by `Time` objects.
| Type | Parameter | Description |
| --- | --- | --- |
| `float` | `ut` | UT1/UTC number of days since noon on January 1, 2000. See the `ut` attribute of this class for more details. |
@@ -197,11 +164,8 @@ dates and times represented by `Time` objects.
| `float` | `ut` | The floating point number of days of Universal Time since noon UTC January 1, 2000. Astronomy Engine approximates UTC and UT1 as being the same thing, although they are not exactly equivalent; UTC and UT1 can disagree by up to 0.9 seconds. This approximation is sufficient for the accuracy requirements of Astronomy Engine. Universal Time Coordinate (UTC) is the international standard for legal and civil timekeeping and replaces the older Greenwich Mean Time (GMT) standard. UTC is kept in sync with unpredictable observed changes in the Earth's rotation by occasionally adding leap seconds as needed. UT1 is an idealized time scale based on observed rotation of the Earth, which gradually slows down in an unpredictable way over time, due to tidal drag by the Moon and Sun, large scale weather events like hurricanes, and internal seismic and convection effects. Conceptually, UT1 drifts from atomic time continuously and erratically, whereas UTC is adjusted by a scheduled whole number of leap seconds as needed. The value in `ut` is appropriate for any calculation involving the Earth's rotation, such as calculating rise/set times, culumination, and anything involving apparent sidereal time. Before the era of atomic timekeeping, days based on the Earth's rotation were often known as *mean solar days*. |
| `float` | `tt` | Terrestrial Time days since noon on January 1, 2000. Terrestrial Time is an atomic time scale defined as a number of days since noon on January 1, 2000. In this system, days are not based on Earth rotations, but instead by the number of elapsed [SI seconds](https://physics.nist.gov/cuu/Units/second.html) divided by 86400. Unlike `ut`, `tt` increases uniformly without adjustments for changes in the Earth's rotation. The value in `tt` is used for calculations of movements not involving the Earth's rotation, such as the orbits of planets around the Sun, or the Moon around the Earth. Historically, Terrestrial Time has also been known by the term *Ephemeris Time* (ET). |
#### member functions
<a name="Time.Make"></a>
### Time.Make(year, month, day, hour, minute, second)
@@ -218,10 +182,6 @@ dates and times represented by `Time` objects.
### Returns: #Time
---
<a name="Vector"></a>
@@ -233,7 +193,6 @@ The vector's space coordinates are measured in astronomical units (AU).
The coordinate system varies and depends on context.
The vector also includes a time stamp.
| Type | Attribute | Description |
| --- | --- | --- |
| `float` | `x` | The x-coordinate of the vector, measured in AU. |
@@ -241,25 +200,18 @@ The vector also includes a time stamp.
| `float` | `z` | The z-coordinate of the vector, measured in AU. |
| [`Time`](#Time) | `t` | The date and time at which the coordinate is valid. |
#### member functions
<a name="Vector.Length"></a>
### Vector.Length(self)
Returns the length of the vector in AU.
---
<a name="enumerations"></a>
## Enumerated Types
---
<a name="ApsisKind"></a>
@@ -272,15 +224,12 @@ or farthest from, the body it orbits (its primary).
`ApsisKind` is an enumerated type that indicates which of these
two cases applies to a particular apsis event.
| Value | Description |
| --- | --- |
| `Pericenter` | The satellite is at its closest point to its primary. |
| `Apocenter` | The satellite is at its farthest point from its primary. |
| `Invalid` | A placeholder for an undefined, unknown, or invalid apsis. |
---
<a name="Body"></a>
@@ -303,8 +252,6 @@ two cases applies to a particular apsis event.
| `Sun` | The Sun. |
| `Moon` | The Earth's moon. |
---
<a name="Direction"></a>
@@ -316,14 +263,11 @@ Specifies the direction of a rising or setting event for a body.
For example, `Direction.Rise` is used to find sunrise times,
and `Direction.Set` is used to find sunset times.
| Value | Description |
| --- | --- |
| `Rise` | First appearance of a body as it rises above the horizon. |
| `Set` | Last appearance of a body as it sinks below the horizon. |
---
<a name="Refraction"></a>
@@ -335,15 +279,12 @@ Some functions allow enabling or disabling atmospheric refraction
for the calculated apparent position of a celestial body
as seen by an observer on the surface of the Earth.
| Value | Description |
| --- | --- |
| `Airless` | No atmospheric refraction correction. |
| `Normal` | Recommended correction for standard atmospheric refraction. |
| `JplHorizons` | Used only for compatibility testing with JPL Horizons online tool. |
---
<a name="Visibility"></a>
@@ -356,13 +297,11 @@ as seen by an observer on the surface of the Earth.
| `Morning` | The body is best visible in the morning, before sunrise. |
| `Evening` | The body is best visible in the evening, after sunset. |
---
<a name="errors"></a>
## Error Types
---
<a name="BadVectorError"></a>
@@ -370,10 +309,6 @@ as seen by an observer on the surface of the Earth.
A vector magnitude is too small to have a direction in space.
---
<a name="EarthNotAllowedError"></a>
@@ -381,10 +316,6 @@ A vector magnitude is too small to have a direction in space.
The Earth is not allowed as the celestial body in this calculation.
---
<a name="Error"></a>
@@ -392,10 +323,6 @@ The Earth is not allowed as the celestial body in this calculation.
Indicates an error in an astronomical calculation.
---
<a name="InternalError"></a>
@@ -410,10 +337,6 @@ page on GitHub. Please include a copy of the stack trace, along with a descripti
of how to reproduce the error. This will help improve the quality of
Astronomy Engine for everyone! (Thank you in advance from the author.)
---
<a name="InvalidBodyError"></a>
@@ -421,10 +344,6 @@ Astronomy Engine for everyone! (Thank you in advance from the author.)
The celestial body is not allowed for this calculation.
---
<a name="NoConvergeError"></a>
@@ -439,15 +358,11 @@ page on GitHub. Please include a copy of the stack trace, along with a descripti
of how to reproduce the error. This will help improve the quality of
Astronomy Engine for everyone! (Thank you in advance from the author.)
---
<a name="functions"></a>
## Functions
---
<a name="AngleFromSun"></a>
@@ -459,7 +374,6 @@ This function calculates the angular separation between the given body and the S
as seen from the center of the Earth. This angle is helpful for determining how
easy it is to see the body away from the glare of the Sun.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | The celestial body whose angle from the Sun is to be measured. Not allowed to be `Body.Earth`. |
@@ -469,10 +383,6 @@ easy it is to see the body away from the glare of the Sun.
A numeric value indicating the angle in degrees between the Sun
and the specified body as seen from the center of the Earth.
---
<a name="BodyCode"></a>
@@ -485,7 +395,6 @@ and the specified body as seen from the center of the Earth.
<Body.Mars: 3>
```
| Type | Parameter | Description |
| --- | --- | --- |
| `str` | `name` | The common English name of a supported celestial body. |
@@ -495,10 +404,6 @@ If `name` is a valid body name, returns the enumeration
value associated with that body.
Otherwise, returns `Body.Invalid`.
---
<a name="Ecliptic"></a>
@@ -512,14 +417,9 @@ which are relative to the plane of the Earth's orbit around the Sun.
equ : EquatorialCoordinates
Equatorial coordinates in the J2000 frame of reference.
### Returns: #EclipticCoordinates
Ecliptic coordinates in the J2000 frame of reference.
---
<a name="EclipticLongitude"></a>
@@ -534,7 +434,6 @@ in degrees from the J2000 equinox. The ecliptic longitude is always in the range
time : Time
The date and time at which the body's ecliptic longitude is to be calculated.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | A body other than the Sun. |
@@ -542,10 +441,6 @@ time : Time
### Returns: `float`
An angular value in degrees indicating the ecliptic longitude of the body.
---
<a name="Elongation"></a>
@@ -569,17 +464,12 @@ information about the given celestial body at the given time:
time : Time
The date and time of the observation.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | The celestial body whose visibility is to be calculated. |
### Returns: #ElongationEvent
---
<a name="Equator"></a>
@@ -598,7 +488,6 @@ significant for the Moon, because it is so close to the Earth. However, parallax
has a small effect on the apparent positions of other bodies.
Correction for aberration is optional, using the `aberration` parameter.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | The celestial body to be observed. Not allowed to be `Body.Earth`. |
@@ -610,10 +499,6 @@ Correction for aberration is optional, using the `aberration` parameter.
### Returns: #EquatorialCoordinates
Equatorial coordinates in the specified frame of reference.
---
<a name="GeoMoon"></a>
@@ -630,7 +515,6 @@ It is adapted from Turbo Pascal code from the book
[Astronomy on the Personal Computer](https://www.springer.com/us/book/9783540672210)
by Montenbruck and Pfleger.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's position. |
@@ -638,10 +522,6 @@ by Montenbruck and Pfleger.
### Returns: #Vector
The Moon's position as a vector in J2000 Cartesian equatorial coordinates.
---
<a name="GeoVector"></a>
@@ -663,7 +543,6 @@ Also, the position can optionally be corrected for
causing the apparent direction of the body to be shifted due to transverse
movement of the Earth with respect to the rays of light coming from that body.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | A body for which to calculate a heliocentric position: the Sun, Moon, or any of the planets. |
@@ -673,10 +552,6 @@ movement of the Earth with respect to the rays of light coming from that body.
### Returns: #Vector
A geocentric position vector of the center of the given body.
---
<a name="HelioVector"></a>
@@ -693,7 +568,6 @@ This is different from the behavior of #GeoVector.
If given an invalid value for `body`, or the body is `Body.Pluto` and `time` is outside
the year range 1700..2200, this function raise an exception.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | The celestial body whose heliocentric position is to be calculated: The Sun, Moon, or any of the planets. |
@@ -703,10 +577,6 @@ the year range 1700..2200, this function raise an exception.
A heliocentric position vector of the center of the given body
at the given time.
---
<a name="Horizon"></a>
@@ -735,17 +605,12 @@ If refraction is disabled, none of these four coordinates will be corrected; in
the right ascension and declination in the returned object will be numerically identical
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.
---
<a name="LongitudeFromSun"></a>
@@ -772,7 +637,6 @@ is visible in the morning sky before sunrise.
time : Time
The date and time of the observation.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | The celestial body for which to find longitude from the Sun. |
@@ -780,10 +644,6 @@ time : Time
### Returns: `float`
An angle in degrees in the range [0, 360).
---
<a name="MoonPhase"></a>
@@ -799,17 +659,12 @@ Certain values of the angle have conventional definitions:
- 180 = full moon
- 270 = third quarter
| Type | Parameter | Description |
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time of the observation. |
### Returns: `float`
---
<a name="NextMoonQuarter"></a>
@@ -822,17 +677,12 @@ one or more times to continue finding consecutive lunar quarters.
This function finds the next consecutive moon quarter event after
the one passed in as the parameter `mq`.
| Type | Parameter | Description |
| --- | --- | --- |
| [`MoonQuarter`](#MoonQuarter) | `mq` | A value returned by a prior call to #SearchMoonQuarter or #NextMoonQuarter. |
### Returns: #MoonQuarter
---
<a name="Search"></a>
@@ -886,7 +736,6 @@ dt_tolerance_seconds : float
Specifies an amount of time in seconds within which a bounded ascending root
is considered accurate enough to stop. A typical value is 1 second.
| Type | Parameter | Description |
| --- | --- | --- |
| `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. |
@@ -899,10 +748,6 @@ inclusive range [`t1`, `t2`].
If there is no ascending root, or there is more than one ascending root,
the function returns `None`.
---
<a name="SearchMaxElongation"></a>
@@ -919,7 +764,6 @@ This function solves for those times, reporting the next maximum elongation even
the elongation value itself, the relative longitude with the Sun, and whether the planet is best
observed in the morning or evening. See #ElongationEvent for more details about the returned object.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | Either `Body.Mercury` or `Body.Venus`. Any other value will result in an exception. To find the best viewing opportunities for planets farther from the Sun than the Earth is (Mars through Pluto), use #SearchRelativeLongitude to find the next opposition event. |
@@ -927,10 +771,6 @@ observed in the morning or evening. See #ElongationEvent for more details about
### Returns: #ElongationEvent
---
<a name="SearchMoonPhase"></a>
@@ -948,7 +788,6 @@ If you want to iterate through lunar quarters (new moon, first quarter, full moo
it is much easier to call the functions #SearchMoonQuarter and #NextMoonQuarter.
This function is useful for finding general phase angles outside those four quarters.
| Type | Parameter | Description |
| --- | --- | --- |
| `float` | `targetLon` | The difference in geocentric longitude between the Sun and Moon that specifies the lunar phase being sought. This can be any value in the range [0, 360). Certain values have conventional names: 0 = new moon, 90 = first quarter, 180 = full moon, 270 = third quarter. |
@@ -957,10 +796,6 @@ This function is useful for finding general phase angles outside those four quar
### Returns: #Time or `None`
---
<a name="SearchMoonQuarter"></a>
@@ -975,17 +810,12 @@ after the specified date and time.
To continue iterating through consecutive lunar quarters, call this function once,
followed by calls to #NextMoonQuarter as many times as desired.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Time`](#Time) | `startTime` | The date and time at which to start the search. |
### Returns: #MoonQuarter
---
<a name="SearchRelativeLongitude"></a>
@@ -1021,7 +851,6 @@ the Earth and another planet:
conjunction, the planet is very difficult to see from the Earth.
Superior conjunction is possible for any planet other than the Earth.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Body`](#Body) | `body` | A planet other than the Earth. If `body` is not a planet, or if it is `Body.Earth`, an error occurs. |
@@ -1031,10 +860,6 @@ the Earth and another planet:
### Returns: #Time
The date and time of the relative longitude event.
---
<a name="SearchSunLongitude"></a>
@@ -1064,13 +889,8 @@ limitDays : float
It is recommended to keep this value between 1 and 10 days.
See remarks above for more details.
### Returns: #Time or `None`
---
<a name="SunPosition"></a>
@@ -1091,7 +911,6 @@ in order to obtain the exact equatorial plane at the given time.
This function can be used for calculating changes of seasons: equinoxes and solstices.
In fact, the function #Seasons does use this function for that purpose.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time for which to calculate the Sun's position. |
@@ -1099,6 +918,3 @@ In fact, the function #Seasons does use this function for that purpose.
### Returns: #EclipticCoordinates
The ecliptic coordinates of the Sun using the Earth's true equator of date.