From 137fc5ce7b4a2df82f0f787e47671728212071de Mon Sep 17 00:00:00 2001 From: Don Cross Date: Wed, 25 May 2022 17:23:41 -0400 Subject: [PATCH] Python docs: better formatting of return values. --- generate/pydown/pydown.py | 2 +- source/python/README.md | 192 +++++++++++++++++++------------------- 2 files changed, 97 insertions(+), 97 deletions(-) diff --git a/generate/pydown/pydown.py b/generate/pydown/pydown.py index 67edc2e4..dc1e5fda 100755 --- a/generate/pydown/pydown.py +++ b/generate/pydown/pydown.py @@ -174,7 +174,7 @@ class DocInfo: md += self.Table(self.attributes, 'Attribute') md += self.EnumTable() if self.returns or self.returnType: - md += '### Returns' + md += '\n**Returns**' if self.returnType: md += ': ' + SymbolLink(self.returnType) md += '\n' diff --git a/source/python/README.md b/source/python/README.md index 2610565e..0b72de96 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -476,7 +476,7 @@ time steps. **The origin of the reference frame. See constructor for more info.** -### Returns: [`Body`](#Body) +**Returns**: [`Body`](#Body) ### GravitySimulator.SolarSystemBodyState(self, body) @@ -496,7 +496,7 @@ of the `originBody` parameter that was passed to this object's constructor. | --- | --- | --- | | [`Body`](#Body) | `body` | The Sun, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, or Neptune. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) The state vector of the requested Solar System body. @@ -527,7 +527,7 @@ that has not yet been updated by a call to [`GravitySimulator.Update`](#GravityS **The time represented by the current step of the gravity simulation.** -### Returns: [`Time`](#Time) +**Returns**: [`Time`](#Time) ### GravitySimulator.Update(self, time) @@ -547,7 +547,7 @@ this simulator. | --- | --- | --- | | [`Time`](#Time) | `time` | A time that is a small increment away from the current simulation time. It is up to the developer to figure out an appropriate time increment. Depending on the trajectories, a smaller or larger increment may be needed for the desired accuracy. Some experimentation may be needed. Generally, bodies that stay in the outer Solar System and move slowly can use larger time steps. Bodies that pass into the inner Solar System and move faster will need a smaller time step to maintain accuracy. The `time` value may be after or before the current simulation time to move forward or backward in time. | -### Returns: [`StateVector`](#StateVector)`[]` +**Returns**: [`StateVector`](#StateVector)`[]` An array of state vectors, one for each small body. --- @@ -864,7 +864,7 @@ The value of the calling object is not modified. This function creates a brand n | --- | --- | --- | | `float` | `days` | A floating point number of days by which to adjust `time`. May be negative, 0, or positive. | -### Returns: [`Time`](#Time) +**Returns**: [`Time`](#Time) ### Time.FromTerrestrialTime(tt) @@ -875,7 +875,7 @@ The value of the calling object is not modified. This function creates a brand n | --- | --- | --- | | `float` | `tt` | The number of days after the J2000 epoch. | -### Returns: [`Time`](#Time) +**Returns**: [`Time`](#Time) ### Time.Make(year, month, day, hour, minute, second) @@ -891,7 +891,7 @@ The value of the calling object is not modified. This function creates a brand n | `int` | `minute` | The UTC minute, in the range 0..59. | | `float` | `second` | The real-valued UTC second, in the range [0, 60). | -### Returns: [`Time`](#Time) +**Returns**: [`Time`](#Time) ### Time.Now() @@ -903,7 +903,7 @@ Converts that date and time to a [`Time`](#Time) value and returns the result. Callers can pass this value to other Astronomy Engine functions to calculate current observational conditions. -### Returns: [`Time`](#Time) +**Returns**: [`Time`](#Time) ### Time.Parse(text) @@ -921,7 +921,7 @@ and a 'Z' at the end of the time. | --- | --- | --- | | `string` | `text` | A string of the following formats: `yyyy-mm-dd` `yyyy-mm-ddThh:mmZ` `yyyy-mm-ddThh:mm:ssZ` `yyyy-mm-ddThh:mm:ss.sssZ` | -### Returns: [`Time`](#Time) +**Returns**: [`Time`](#Time) ### Time.Utc(self) @@ -931,7 +931,7 @@ and a 'Z' at the end of the time. Uses the standard [`datetime`](https://docs.python.org/3/library/datetime.html) class to represent the date and time in this Time object. -### Returns: `datetime` +**Returns**: `datetime` --- @@ -1192,7 +1192,7 @@ The angle is measured in the plane that contains both vectors. | [`Vector`](#Vector) | `a` | The first of a pair of vectors between which to measure an angle. | | [`Vector`](#Vector) | `b` | The second of a pair of vectors between which to measure an angle. | -### Returns: `float` +**Returns**: `float` The angle between the two vectors expressed in degrees. The value is in the range [0, 180]. @@ -1212,7 +1212,7 @@ 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` +**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. @@ -1232,7 +1232,7 @@ The vectors are expressed in equatorial J2000 coordinates (EQJ). | [`Body`](#Body) | `body` | The celestial body whose barycentric state vector is to be calculated. Supported values are `Body.Sun`, `Body.SSB`, `Body.Moon`, `Body.EMB`, and all planets: `Body.Mercury`, `Body.Venus`, `Body.Earth`, `Body.Mars`, `Body.Jupiter`, `Body.Saturn`, `Body.Uranus`, `Body.Neptune`, `Body.Pluto`. | | [`Time`](#Time) | `time` | The date and time for which to calculate position and velocity. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) An object that contains barycentric position and velocity vectors. --- @@ -1251,7 +1251,7 @@ An object that contains barycentric position and velocity vectors. | --- | --- | --- | | `str` | `name` | The common English name of a supported celestial body. | -### Returns: [`Body`](#Body) +**Returns**: [`Body`](#Body) If `name` is a valid body name, returns the enumeration value associated with that body. Otherwise, returns `Body.Invalid`. @@ -1271,7 +1271,7 @@ equivalent to rotating based on the first matrix, followed by the second. | [`RotationMatrix`](#RotationMatrix) | `a` | The first rotation to apply. | | [`RotationMatrix`](#RotationMatrix) | `b` | The second rotation to apply. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) The combined rotation matrix. --- @@ -1289,7 +1289,7 @@ constellation that contains that point. | `float` | `ra` | The right ascension (RA) of a point in the sky, using the J2000 equatorial system. | | `float` | `dec` | The declination (DEC) of a point in the sky, using the J2000 equatorial system. | -### Returns: [`ConstellationInfo`](#ConstellationInfo) +**Returns**: [`ConstellationInfo`](#ConstellationInfo) A structure that contains the 3-letter abbreviation and full name of the constellation that contains the given (ra,dec), along with the converted B1875 (ra,dec) for that point. @@ -1310,7 +1310,7 @@ This is the default Delta T function used by Astronomy Engine. | --- | --- | --- | | `float` | `ut` | The floating point number of days since noon UTC on January 1, 2000. | -### Returns: `float` +**Returns**: `float` The estimated difference TT-UT on the given date, expressed in seconds. --- @@ -1328,7 +1328,7 @@ which are relative to the plane of the Earth's orbit around the Sun. | --- | --- | --- | | [`Equatorial`](#Equatorial) | `equ` | Equatorial coordinates in the J2000 frame of reference. | -### Returns: [`EclipticCoordinates`](#EclipticCoordinates) +**Returns**: [`EclipticCoordinates`](#EclipticCoordinates) Ecliptic coordinates in the J2000 frame of reference. --- @@ -1353,7 +1353,7 @@ To calculate an equatorial J2000 vector instead, use [`GeoMoon`](#GeoMoon). | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's position. | -### Returns: [`Spherical`](#Spherical) +**Returns**: [`Spherical`](#Spherical) The Moon's position as a distance, ecliptic latitude, and ecliptic longitude. --- @@ -1373,7 +1373,7 @@ in degrees from the J2000 equinox. The ecliptic longitude is always in the range | [`Body`](#Body) | `body` | A body other than the Sun. | | [`Time`](#Time) | `time` | The date and time at which the body's ecliptic longitude is to be calculated. | -### Returns: `float` +**Returns**: `float` An angular value in degrees indicating the ecliptic longitude of the body. --- @@ -1402,7 +1402,7 @@ information about the given celestial body at the given time: | [`Body`](#Body) | `body` | The celestial body whose visibility is to be calculated. | | [`Time`](#Time) | `time` | The date and time of the observation. | -### Returns: [`ElongationEvent`](#ElongationEvent) +**Returns**: [`ElongationEvent`](#ElongationEvent) --- @@ -1430,7 +1430,7 @@ 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: [`Equatorial`](#Equatorial) +**Returns**: [`Equatorial`](#Equatorial) Equatorial coordinates in the specified frame of reference. --- @@ -1444,7 +1444,7 @@ Equatorial coordinates in the specified frame of reference. | --- | --- | --- | | [`Vector`](#Vector) | `vec` | A vector in an equatorial coordinate system. | -### Returns: [`Equatorial`](#Equatorial) +**Returns**: [`Equatorial`](#Equatorial) Angular coordinates expressed in the same equatorial system as `vec`. --- @@ -1463,7 +1463,7 @@ The velocity (vx, vy, vz) components are expressed in AU/day. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the EMB's geocentric state. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) The EMB's position and velocity vectors in J2000 equatorial coordinates. --- @@ -1488,7 +1488,7 @@ by Montenbruck and Pfleger. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's position. | -### Returns: [`Vector`](#Vector) +**Returns**: [`Vector`](#Vector) The Moon's position as a vector in J2000 Cartesian equatorial coordinates (EQJ). --- @@ -1511,7 +1511,7 @@ it is much more efficient to use [`GeoMoon`](#GeoMoon) instead. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's position and velocity. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) The Moon's position and velocity vectors in J2000 equatorial coordinates (EQJ). --- @@ -1540,7 +1540,7 @@ 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`](#Vector) +**Returns**: [`Vector`](#Vector) A geocentric position vector of the center of the given body. --- @@ -1561,7 +1561,7 @@ of the resulting vector. | [`Body`](#Body) | `body` | A body for which to calculate a heliocentric distance: the Sun, Moon, or any of the planets. | | [`Time`](#Time) | `time` | The date and time for which to calculate the heliocentric distance. | -### Returns: `float` +**Returns**: `float` The heliocentric distance in AU. --- @@ -1586,7 +1586,7 @@ of reference, consider using [`BaryState`](#BaryState) instead. | [`Body`](#Body) | `body` | The celestial body whose heliocentric state vector is to be calculated. Supported values are `Body.Sun`, `Body.SSB`, `Body.Moon`, `Body.EMB`, and all planets: `Body.Mercury`, `Body.Venus`, `Body.Earth`, `Body.Mars`, `Body.Jupiter`, `Body.Saturn`, `Body.Uranus`, `Body.Neptune`, `Body.Pluto`. | | [`Time`](#Time) | `time` | The date and time for which to calculate position and velocity. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) An object that contains heliocentric position and velocity vectors. --- @@ -1609,7 +1609,7 @@ If given an invalid value for `body`, this function raises an exception. | [`Body`](#Body) | `body` | The celestial body whose heliocentric position is to be calculated: The Sun, Moon, EMB, SSB, or any of the planets. | | [`Time`](#Time) | `time` | The time at which to calculate the heliocentric position. | -### Returns: [`Vector`](#Vector) +**Returns**: [`Vector`](#Vector) A heliocentric position vector of the center of the given body at the given time. @@ -1649,7 +1649,7 @@ to the respective `ra` and `dec` values passed in. | `float` | `dec` | Declination in degrees of the celestial object, referred to the mean equator of date for the J2000 epoch. Positive values are north of the celestial equator and negative values are south of it. | | [`Refraction`](#Refraction) | `refraction` | The option for selecting whether to correct for atmospheric lensing. If `Refraction.Normal`, a well-behaved refraction model is used. If `Refraction.None`, no refraction correct is performed. `Refraction.JplHorizons` is used only for compatibility testing with the JPL Horizons online tool. | -### Returns: [`HorizontalCoordinates`](#HorizontalCoordinates) +**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 @@ -1693,7 +1693,7 @@ This matrix can be the starting point for other operations, such as using a series of calls to [`Pivot`](#Pivot) to create a custom rotation matrix. -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) The identity rotation matrix. --- @@ -1724,7 +1724,7 @@ the rings appear edge-on, and are thus nearly invisible from the Earth. The `rin | [`Body`](#Body) | `body` | The Sun, Moon, or any planet other than the Earth. | | [`Time`](#Time) | `time` | The date and time of the observation. | -### Returns: [`IlluminationInfo`](#IlluminationInfo) +**Returns**: [`IlluminationInfo`](#IlluminationInfo) --- @@ -1744,7 +1744,7 @@ but refraction first must be removed from the observed position. | [`Refraction`](#Refraction) | `refraction` | `Refraction.Normal` - corrects for atmospheric refraction (recommended). `Refraction.Airless` - no correction is performed. `Refraction.JplHorizons` - For JPL Horizons compatibility testing only. | | `float` | `bent_altitude` | The apparent altitude that includes atmospheric refraction. | -### Returns: `float` +**Returns**: `float` The angular adjustment in degrees, to be added to the altitude angle to correct for atmospheric lensing. This will be less than or equal to zero. @@ -1763,7 +1763,7 @@ this function returns the matrix that reverses that transform. | --- | --- | --- | | [`RotationMatrix`](#RotationMatrix) | `rotation` | The rotation matrix to be inverted. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) The inverse rotation matrix. --- @@ -1788,7 +1788,7 @@ to convert to geocentric vectors. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate Jupiter's moons. | -### Returns: [`JupiterMoonsInfo`](#JupiterMoonsInfo) +**Returns**: [`JupiterMoonsInfo`](#JupiterMoonsInfo) The positions and velocities of Jupiter's 4 largest moons. --- @@ -1827,7 +1827,7 @@ for some other purpose. | [`Body`](#Body) | `major_body` | The more massive of the co-orbiting bodies: `Body.Sun` or `Body.Earth`. | | [`Body`](#Body) | `minor_body` | The less massive of the co-orbiting bodies. See main remarks. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) The position and velocity of the selected Lagrange point with respect to the major body's center. --- @@ -1865,7 +1865,7 @@ Consider calling [`LagrangePoint`](#LagrangePoint), instead of this function, fo | [`StateVector`](#StateVector) | `minor_state` | The state vector of the minor (less massive) of the pair of bodies. | | `float` | `minor_mass` | The mass product GM of the minor body. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) The position and velocity of the selected Lagrange point with respect to the major body's center. --- @@ -1891,7 +1891,7 @@ and the apparent angular diameter of the Moon `diam_deg`. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's libration angles. | -### Returns: [`LibrationInfo`](#LibrationInfo) +**Returns**: [`LibrationInfo`](#LibrationInfo) --- @@ -1912,7 +1912,7 @@ The values come from page 10 of a | --- | --- | --- | | [`Body`](#Body) | `body` | The body for which to find the GM product. Allowed to be the Sun, Moon, EMB (Earth/Moon Barycenter), or any planet. Any other value will cause an exception to be thrown. | -### Returns: `float` +**Returns**: `float` The mass product of the given body in au^3/day^2. --- @@ -1934,7 +1934,7 @@ Certain values of the angle have conventional definitions: | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time of the observation. | -### Returns: `float` +**Returns**: `float` --- @@ -1953,7 +1953,7 @@ to find the next solar eclipse. | --- | --- | --- | | [`Time`](#Time) | `prevEclipseTime` | A date and time near a new moon. Solar eclipse search will start at the next new moon. | -### Returns: [`GlobalSolarEclipseInfo`](#GlobalSolarEclipseInfo) +**Returns**: [`GlobalSolarEclipseInfo`](#GlobalSolarEclipseInfo) --- @@ -1973,7 +1973,7 @@ to find the next solar eclipse. | [`Time`](#Time) | `prevEclipseTime` | A date and time near a new moon. Solar eclipse search will start at the next new moon. | | [`Observer`](#Observer) | `observer` | The geographic location of the observer. | -### Returns: [`LocalSolarEclipseInfo`](#LocalSolarEclipseInfo) +**Returns**: [`LocalSolarEclipseInfo`](#LocalSolarEclipseInfo) --- @@ -1992,7 +1992,7 @@ See [`SearchLunarApsis`](#SearchLunarApsis) for more details. | --- | --- | --- | | [`Apsis`](#Apsis) | `apsis` | | -### Returns: [`Apsis`](#Apsis) +**Returns**: [`Apsis`](#Apsis) --- @@ -2011,7 +2011,7 @@ See [`SearchLunarApsis`](#SearchLunarApsis) for more details. | --- | --- | --- | | [`Time`](#Time) | `prevEclipseTime` | A date and time near a full moon. Lunar eclipse search will start at the next full moon. | -### Returns: [`LunarEclipseInfo`](#LunarEclipseInfo) +**Returns**: [`LunarEclipseInfo`](#LunarEclipseInfo) --- @@ -2027,7 +2027,7 @@ Then call `NextMoonNode` to find as many more consecutive nodes as desired. | --- | --- | --- | | [`NodeEventInfo`](#NodeEventInfo) | `prevNode` | The previous node find from calling [`SearchMoonNode`](#SearchMoonNode) or `NextMoonNode`. | -### Returns: [`NodeEventInfo`](#NodeEventInfo) +**Returns**: [`NodeEventInfo`](#NodeEventInfo) --- @@ -2045,7 +2045,7 @@ the one passed in as the parameter `mq`. | --- | --- | --- | | [`MoonQuarter`](#MoonQuarter) | `mq` | A value returned by a prior call to [`SearchMoonQuarter`](#SearchMoonQuarter) or [`NextMoonQuarter`](#NextMoonQuarter). | -### Returns: [`MoonQuarter`](#MoonQuarter) +**Returns**: [`MoonQuarter`](#MoonQuarter) --- @@ -2064,7 +2064,7 @@ See [`SearchPlanetApsis`](#SearchPlanetApsis) for more details. | [`Body`](#Body) | `body` | The planet for which to find the next perihelion/aphelion event. Not allowed to be `Body.Sun` or `Body.Moon`. Must match the body passed into the call that produced the `apsis` parameter. | | [`Apsis`](#Apsis) | `apsis` | An apsis event obtained from a call to [`SearchPlanetApsis`](#SearchPlanetApsis) or `NextPlanetApsis`. | -### Returns: [`Apsis`](#Apsis) +**Returns**: [`Apsis`](#Apsis) --- @@ -2082,7 +2082,7 @@ Keep calling this function as many times as you want to keep finding more transi | [`Body`](#Body) | `body` | The planet whose transit is to be found. Must be `Body.Mercury` or `Body.Venus`. | | [`Time`](#Time) | `prevTransitTime` | A date and time near the previous transit. | -### Returns: [`TransitInfo`](#TransitInfo) +**Returns**: [`TransitInfo`](#TransitInfo) --- @@ -2105,7 +2105,7 @@ on the Earth. | `float` | `latitude` | The latitude of the observer in degrees north or south of the equator. By formula symmetry, positive latitudes give the same answer as negative latitudes, so the sign does not matter. | | `float` | `height` | The height above the sea level geoid in meters. No range checking is done; however, accuracy is only valid in the range 0 to 100000 meters. | -### Returns: `float` +**Returns**: `float` The effective gravitational acceleration expressed in meters per second squared [m/s^2]. --- @@ -2132,7 +2132,7 @@ The returned velocity vector has components expressed in AU/day. | [`Observer`](#Observer) | `observer` | The geographic location of a point on or near the surface of the Earth. | | `bool` | `ofdate` | Selects the date of the Earth's equator in which to express the equatorial coordinates. The caller may pass `False` to use the orientation of the Earth's equator at noon UTC on January 1, 2000, in which case this function corrects for precession and nutation of the Earth as it was at the moment specified by the `time` parameter. Or the caller may pass `true` to use the Earth's equator at `time` as the orientation. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) An equatorial position vector and velocity vector relative to the center of the Earth. --- @@ -2159,7 +2159,7 @@ The inverse of this function is also available: [`VectorObserver`](#VectorObserv | [`Observer`](#Observer) | `observer` | The geographic location of a point on or near the surface of the Earth. | | `bool` | `ofdate` | Selects the date of the Earth's equator in which to express the equatorial coordinates. The caller may pass `False` to use the orientation of the Earth's equator at noon UTC on January 1, 2000, in which case this function corrects for precession and nutation of the Earth as it was at the moment specified by the `time` parameter. Or the caller may pass `true` to use the Earth's equator at `time` as the orientation. | -### Returns: [`Vector`](#Vector) +**Returns**: [`Vector`](#Vector) An equatorial vector from the center of the Earth to the specified location on (or near) the Earth's surface. @@ -2190,7 +2190,7 @@ If this happens, the function throws an exception. | [`Body`](#Body) | `body2` | The second body, relative to which the longitude of the first body is to be found. | | [`Time`](#Time) | `time` | The date and time of the observation. | -### Returns: `float` +**Returns**: `float` An angle in degrees in the range [0, 360). --- @@ -2215,7 +2215,7 @@ reorient ECL coordinates to the orientation of your telescope camera. | `int` | `axis` | An integer that selects which coordinate axis to rotate around: 0 = x, 1 = y, 2 = z. Any other value will cause an exception. | | `float` | `angle` | An angle in degrees indicating the amount of rotation around the specified axis. Positive angles indicate rotation counterclockwise as seen from the positive direction along that axis, looking towards the origin point of the orientation system. Any finite number of degrees is allowed, but best precision will result from keeping `angle` in the range [-360, +360]. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A pivoted matrix object. --- @@ -2235,7 +2235,7 @@ due to lensing of the Earth's atmosphere. | [`Refraction`](#Refraction) | `refraction` | The option for selecting whether to correct for atmospheric lensing. If `Refraction.Normal`, a well-behaved refraction model is used. If `Refraction.Airless`, no refraction correct is performed. `Refraction.JplHorizons` is used only for compatibility testing with the JPL Horizons online tool. Any other value raises an exception. | | `float` | `altitude` | The number of degrees above (positive) or below (negative) the horizon an object is, before being corrected for refraction. | -### Returns: `float` +**Returns**: `float` The number of additional degrees of altitude an object appears to have, due to atmospheric refraction, depending on the option selected by the `refraction` parameter. @@ -2256,7 +2256,7 @@ vectors are rotated the same way. | [`RotationMatrix`](#RotationMatrix) | `rotation` | A rotation matrix that specifies how the orientation of the vector is to be changed. | | [`StateVector`](#StateVector) | `state` | The state vector whose orientation is to be changed. | -### Returns: [`StateVector`](#StateVector) +**Returns**: [`StateVector`](#StateVector) A state vector in the orientation specified by `rotation`. --- @@ -2274,7 +2274,7 @@ in another orientation. | [`RotationMatrix`](#RotationMatrix) | `rotation` | A rotation matrix that specifies how the orientation of the vector is to be changed. | | [`Vector`](#Vector) | `vector` | The vector whose orientation is to be changed. | -### Returns: [`Vector`](#Vector) +**Returns**: [`Vector`](#Vector) A vector in the orientation specified by `rotation`. --- @@ -2297,7 +2297,7 @@ See [`AxisInfo`](#AxisInfo) for more detailed information. | [`Body`](#Body) | `body` | One of the following values: `Body.Sun`, `Body.Moon`, `Body.Mercury`, `Body.Venus`, `Body.Earth`, `Body.Mars`, `Body.Jupiter`, `Body.Saturn`, `Body.Uranus`, `Body.Neptune`, `Body.Pluto`. | | [`Time`](#Time) | `time` | The time at which to calculate the body's rotation axis. | -### Returns: [`AxisInfo`](#AxisInfo) +**Returns**: [`AxisInfo`](#AxisInfo) The body's north pole direction and angle of its prime meridian. --- @@ -2316,7 +2316,7 @@ Target: EQD = equatorial system, using equator of date. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time of the desired equator. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts ECL to EQD. --- @@ -2331,7 +2331,7 @@ for converting from one orientation to another. Source: ECL = ecliptic system, using equator at J2000 epoch. Target: EQJ = equatorial system, using equator at J2000 epoch. -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts ECL to EQJ. --- @@ -2353,7 +2353,7 @@ to a traditional altitude/azimuth pair. | [`Time`](#Time) | `time` | The date and time of the desired horizontal orientation. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that defines the observer's horizon. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts ECL to HOR at `time` and for `observer`. The components of the horizontal vector are: x = north, y = west, z = zenith (straight up from the observer). @@ -2376,7 +2376,7 @@ Target: ECL = ecliptic system, using equator at J2000 epoch. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time of the source equator. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQD to ECL. --- @@ -2395,7 +2395,7 @@ Target: EQJ = equatorial system, using equator at J2000 epoch. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time at which the Earth's equator defines the source orientation. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQD at `time` to EQJ. --- @@ -2417,7 +2417,7 @@ to a traditional altitude/azimuth pair. | [`Time`](#Time) | `time` | The date and time at which the Earth's equator applies. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that defines the observer's location. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQD to HOR at `time` and for `observer`. The components of the horizontal vector are: x = north, y = west, z = zenith (straight up from the observer). @@ -2436,7 +2436,7 @@ for converting from one orientation to another. Source: EQJ = equatorial system, using equator at J2000 epoch. Target: ECL = ecliptic system, using equator at J2000 epoch. -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQJ to ECL. --- @@ -2455,7 +2455,7 @@ Target: EQD = equatorial system, using equator of the specified date/time. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time at which the Earth's equator defines the target orientation. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQJ to EQD at `time`. --- @@ -2470,7 +2470,7 @@ for converting from one orientation to another. Source: EQJ = equatorial system, using the equator at the J2000 epoch. Target: GAL = galactic system (IAU 1958 definition). -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQJ to GAL. --- @@ -2492,7 +2492,7 @@ a traditional altitude/azimuth pair. | [`Time`](#Time) | `time` | The date and time of the desired horizontal orientation. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that defines the observer's horizon. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQJ to HOR at `time` and for `observer`. The components of the horizontal vector are: x = north, y = west, z = zenith (straight up from the observer). @@ -2511,7 +2511,7 @@ for converting from one orientation to another. Source: GAL = galactic system (IAU 1958 definition). Target: EQJ = equatorial system, using the equator at the J2000 epoch. -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts GAL to EQJ. --- @@ -2531,7 +2531,7 @@ Target: ECL = ecliptic system, using equator at J2000 epoch. | [`Time`](#Time) | `time` | The date and time of the horizontal observation. | | [`Observer`](#Observer) | `observer` | The location of the horizontal observer. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts HOR to ECL. --- @@ -2551,7 +2551,7 @@ Target: EQD = equatorial system, using equator of the specified date/time. | [`Time`](#Time) | `time` | The date and time at which the Earth's equator applies. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that defines the observer's horizon. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts HOR to EQD at `time` and for `observer`. --- @@ -2571,7 +2571,7 @@ Target: EQJ = equatorial system, using equator at the J2000 epoch. | [`Time`](#Time) | `time` | The date and time of the observation. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that define's the observer's horizon. | -### Returns: [`RotationMatrix`](#RotationMatrix) +**Returns**: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts HOR to EQJ at `time` and for `observer`. --- @@ -2623,7 +2623,7 @@ an [`Error`](#Error) exception. | `float` | `t2` | The upper time bound of the search window. See remarks above for more details. | | `float` | `dt_tolerance_seconds` | 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. | -### Returns: [`Time`](#Time) or `None` +**Returns**: [`Time`](#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 @@ -2659,7 +2659,7 @@ Astronomical twilight uses -18 degrees as the `altitude` value. | `float` | `limitDays` | The fractional number of days after `dateStart` that limits when the altitude event is to be found. Must be a positive number. | | `float` | `altitude` | The desired altitude angle of the body's center above (positive) or below (negative) the observer's local horizon, expressed in degrees. Must be in the range [-90, +90]. | -### Returns: [`Time`](#Time) or `None` +**Returns**: [`Time`](#Time) or `None` If the altitude event time is found within the specified time window, this function returns that time. Otherwise, it returns `None`. @@ -2681,7 +2681,7 @@ passing in the `peak` value returned from the previous call. | --- | --- | --- | | [`Time`](#Time) | `startTime` | The date and time for starting the search for a solar eclipse. | -### Returns: [`GlobalSolarEclipseInfo`](#GlobalSolarEclipseInfo) +**Returns**: [`GlobalSolarEclipseInfo`](#GlobalSolarEclipseInfo) --- @@ -2715,7 +2715,7 @@ of the body at that time, as seen by the given observer. | `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`](#HourAngleEvent) +**Returns**: [`HourAngleEvent`](#HourAngleEvent) --- @@ -2738,7 +2738,7 @@ See [`LocalSolarEclipseInfo`](#LocalSolarEclipseInfo) for more information about | [`Time`](#Time) | `startTime` | The date and time for starting the search for a solar eclipse. | | [`Observer`](#Observer) | `observer` | The geographic location of the observer. | -### Returns: [`LocalSolarEclipseInfo`](#LocalSolarEclipseInfo) +**Returns**: [`LocalSolarEclipseInfo`](#LocalSolarEclipseInfo) --- @@ -2763,7 +2763,7 @@ another call of `NextLunarApsis` as many times as desired. | --- | --- | --- | | [`Time`](#Time) | `startTime` | The date and time at which to start searching for the next perigee or apogee. | -### Returns: [`Apsis`](#Apsis) +**Returns**: [`Apsis`](#Apsis) --- @@ -2783,7 +2783,7 @@ passing in the `peak` value returned from the previous call. | --- | --- | --- | | [`Time`](#Time) | `startTime` | The date and time for starting the search for a lunar eclipse. | -### Returns: [`LunarEclipseInfo`](#LunarEclipseInfo) +**Returns**: [`LunarEclipseInfo`](#LunarEclipseInfo) --- @@ -2806,7 +2806,7 @@ observed in the morning or evening. See [`ElongationEvent`](#ElongationEvent) fo | [`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`](#SearchRelativeLongitude) to find the next opposition event. | | [`Time`](#Time) | `startTime` | The date and time at which to begin the search. The maximum elongation event found will always be the first one that occurs after this date and time. | -### Returns: [`ElongationEvent`](#ElongationEvent) +**Returns**: [`ElongationEvent`](#ElongationEvent) --- @@ -2828,7 +2828,7 @@ Then call [`NextMoonNode`](#NextMoonNode) to find as many more consecutive nodes | --- | --- | --- | | [`Time`](#Time) | `startTime` | The date and time for starting the search for an ascending or descending node of the Moon. | -### Returns: [`NodeEventInfo`](#NodeEventInfo) +**Returns**: [`NodeEventInfo`](#NodeEventInfo) --- @@ -2853,7 +2853,7 @@ This function is useful for finding general phase angles outside those four quar | [`Time`](#Time) | `startTime` | The beginning of the time window in which to search for the Moon reaching the specified phase. | | `float` | `limitDays` | The number of days after `startTime` that limits the time window for the search. | -### Returns: [`Time`](#Time) or `None` +**Returns**: [`Time`](#Time) or `None` --- @@ -2873,7 +2873,7 @@ followed by calls to [`NextMoonQuarter`](#NextMoonQuarter) as many times as desi | --- | --- | --- | | [`Time`](#Time) | `startTime` | The date and time at which to start the search. | -### Returns: [`MoonQuarter`](#MoonQuarter) +**Returns**: [`MoonQuarter`](#MoonQuarter) --- @@ -2898,7 +2898,7 @@ However, the difference is minor and has little practical value. | [`Body`](#Body) | `body` | Currently only `Body.Venus` is allowed. Any other value results in an exception. See remarks above for more details. | | [`Time`](#Time) | `startTime` | The date and time to start searching for the next peak magnitude event. | -### Returns: [`IlluminationInfo`](#IlluminationInfo) +**Returns**: [`IlluminationInfo`](#IlluminationInfo) --- @@ -2922,7 +2922,7 @@ into another call of `NextPlanetApsis` as many times as desired. | [`Body`](#Body) | `body` | The planet for which to find the next perihelion/aphelion event. Not allowed to be `Body.Sun` or `Body.Moon`. | | [`Time`](#Time) | `startTime` | The date and time at which to start searching for the next perihelion or aphelion. | -### Returns: [`Apsis`](#Apsis) +**Returns**: [`Apsis`](#Apsis) --- @@ -2965,7 +2965,7 @@ 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`](#Time) +**Returns**: [`Time`](#Time) The date and time of the relative longitude event. --- @@ -2998,7 +2998,7 @@ Therefore callers must not assume that the function will always succeed. | [`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`](#Time) or `None` +**Returns**: [`Time`](#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`. @@ -3025,7 +3025,7 @@ It is recommended to keep the window smaller than 10 days when possible. | [`Time`](#Time) | `startTime` | The date and time for starting the search for the desired longitude event. | | `float` | `limitDays` | The real-valued number of days, which when added to `startTime`, limits the range of time over which the search looks. It is recommended to keep this value between 1 and 10 days. See remarks above for more details. | -### Returns: [`Time`](#Time) or `None` +**Returns**: [`Time`](#Time) or `None` --- @@ -3045,7 +3045,7 @@ To continue the search, pass the `finish` time in the returned structure to | [`Body`](#Body) | `body` | The planet whose transit is to be found. Must be `Body.Mercury` or `Body.Venus`. | | [`Time`](#Time) | `startTime` | The date and time for starting the search for a transit. | -### Returns: [`TransitInfo`](#TransitInfo) +**Returns**: [`TransitInfo`](#TransitInfo) --- @@ -3076,7 +3076,7 @@ of winter in the southern hemisphere. | --- | --- | --- | | `int` | `year` | The calendar year number for which to calculate equinoxes and solstices. The value may be any integer, but only the years 1800 through 2100 have been validated for accuracy: unit testing against data from the United States Naval Observatory confirms that all equinoxes and solstices for that range of years are within 2 minutes of the correct time. | -### Returns: [`SeasonInfo`](#SeasonInfo) +**Returns**: [`SeasonInfo`](#SeasonInfo) --- @@ -3104,7 +3104,7 @@ To convert to degrees, multiply the return value by 15. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to find GAST. As an optimization, this function caches the sideral time value in `time`, unless it has already been cached, in which case the cached value is reused. | -### Returns: `float` +**Returns**: `float` GAST expressed in sidereal hours. --- @@ -3120,7 +3120,7 @@ Given a Cartesian vector, returns latitude, longitude, and distance. | --- | --- | --- | | [`Vector`](#Vector) | `vector` | Cartesian vector to be converted to spherical coordinates. | -### Returns: [`Spherical`](#Spherical) +**Returns**: [`Spherical`](#Spherical) Spherical coordinates that are equivalent to the given vector. --- @@ -3147,7 +3147,7 @@ In fact, the function [`Seasons`](#Seasons) does use this function for that purp | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the Sun's position. | -### Returns: [`EclipticCoordinates`](#EclipticCoordinates) +**Returns**: [`EclipticCoordinates`](#EclipticCoordinates) The ecliptic coordinates of the Sun using the Earth's true equator of date. --- @@ -3163,7 +3163,7 @@ The ecliptic coordinates of the Sun using the Earth's true equator of date. | [`Time`](#Time) | `time` | The date and time of the observation. This is needed because the returned vector object requires a valid time value when passed to certain other functions. | | [`Refraction`](#Refraction) | `refraction` | See remarks in function [`RefractionAngle`](#RefractionAngle). | -### Returns: [`Vector`](#Vector) +**Returns**: [`Vector`](#Vector) A vector in the horizontal system: `x` = north, `y` = west, and `z` = zenith (up). --- @@ -3182,7 +3182,7 @@ includes the time, as required by all `Time` objects. | [`Spherical`](#Spherical) | `sphere` | Spherical coordinates to be converted. | | [`Time`](#Time) | `time` | The time that should be included in the returned vector. | -### Returns: [`Vector`](#Vector) +**Returns**: [`Vector`](#Vector) The vector form of the supplied spherical coordinates. --- @@ -3201,7 +3201,7 @@ latitude, longitude, and elevation for that vector. | [`Vector`](#Vector) | `vector` | The geocentric equatorial position vector for which to find geographic coordinates. The components are expressed in astronomical units (AU). The time `vector.t` determines the Earth's rotation. | | `bool` | `ofdate` | Selects the date of the Earth's equator in which `vector` is expressed. The caller may pass `False` to use the orientation of the Earth's equator at noon UTC on January 1, 2000, in which case this function corrects for precession and nutation of the Earth as it was at the moment specified by the the time `vector.t`. Or the caller may pass `True` to use the Earth's equator at `vector.t` as the orientation. | -### Returns: [`Observer`](#Observer) +**Returns**: [`Observer`](#Observer) The geographic latitude, longitude, and elevation above sea level that corresponds to the given equatorial vector.