Package: astronomy-engine
Astronomy Engine (Python)This is the complete programming reference for the Python version of
Astronomy Engine. Supports Python 3. Does NOT support Python 2.
See thehome pagefor more info.Quick StartTo include Astronomy Engine in your own Python program,
you can use theastronomy-enginepackage:pip install astronomy-engineAlternatively, you can copy the fileastronomy/astronomy.pyinto your project directory.With either approach, add the following line toward the top of your program:importastronomyTo get started quickly, here are someexamples.ContentsTopic IndexConstantsClassesEnumerated TypesError TypesFunctionsTopic IndexPosition of Sun, Moon, and planetsFunctionDescriptionHelioVectorCalculates body position vector with respect to the center of the Sun.GeoVectorCalculates body position vector with respect to the center of the Earth.EquatorCalculates right ascension and declination.EclipticConverts J2000 mean equator (EQJ) coordinates to true ecliptic of date (ECT) coordinates.EclipticLongitudeCalculates true ecliptic of date (ECT) longitude for a body.HorizonCalculates horizontal coordinates (azimuth, altitude) for a given observer on the Earth.PairLongitudeCalculates the difference in apparent ecliptic longitude between two bodies, as seen from the Earth.BaryStateCalculates the barycentric position and velocity vectors of the Sun or a planet.Geographic helper functionsFunctionDescriptionObserverVectorCalculates a vector from the center of the Earth to an observer on the Earth's surface.VectorObserverCalculates the geographic coordinates for a geocentric equatorial vector.Rise, set, and culmination timesFunctionDescriptionSearchRiseSetFinds time of rise or set for a body as seen by an observer on the Earth.SearchAltitudeFinds time when a body reaches a given altitude above or below the horizon. Useful for finding civil, nautical, or astronomical twilight.SearchHourAngleFinds when body reaches a given hour angle for an observer on the Earth. Hour angle = 0 finds culmination, the highest point in the sky.Moon phasesFunctionDescriptionMoonPhaseDetermines the Moon's phase expressed as an ecliptic longitude.SearchMoonPhaseFinds the next instance of the Moon reaching a specific ecliptic longitude separation from the Sun.SearchMoonQuarterFinds the first quarter moon phase after a given date and time.NextMoonQuarterFinds the next quarter moon phase after a previous one that has been found.Eclipses and TransitsFunctionDescriptionSearchLunarEclipseSearch for the first lunar eclipse after a given date.NextLunarEclipseContinue searching for more lunar eclipses.SearchGlobalSolarEclipseSearch for the first solar eclipse after a given date that is visible anywhere on the Earth.NextGlobalSolarEclipseContinue searching for solar eclipses visible anywhere on the Earth.SearchLocalSolarEclipseSearch for the first solar eclipse after a given date that is visible at a particular location on the Earth.NextLocalSolarEclipseContinue searching for solar eclipses visible at a particular location on the Earth.SearchTransitSearch for the next transit of Mercury or Venus.NextTransitContinue searching for transits of Mercury or Venus.Lunar perigee and apogeeFunctionDescriptionSearchLunarApsisFinds the next perigee or apogee of the Moon after a specified date.NextLunarApsisGiven an already-found apsis, finds the next perigee or apogee of the Moon.Planet perihelion and aphelionFunctionDescriptionSearchPlanetApsisFinds the next perihelion or aphelion of a planet after a specified date.NextPlanetApsisGiven an already-found apsis, finds the next perihelion or aphelion of a planet.Visual magnitude and elongationFunctionDescriptionIlluminationCalculates visual magnitude and phase angle of bodies as seen from the Earth.SearchPeakMagnitudeSearches for the date and time Venus will next appear brightest as seen from the Earth.AngleFromSunReturns full angle seen from Earth between body and Sun.ElongationCalculates ecliptic longitude angle between a body and the Sun, as seen from the Earth.SearchMaxElongationSearches for the next maximum elongation event for Mercury or Venus that occurs after the given date.Oppositions and conjunctionsFunctionDescriptionSearchRelativeLongitudeFinds oppositions and conjunctions of planets.Equinoxes, solstices, and apparent solar motionFunctionDescriptionSearchSunLongitudeFinds the next time the Sun reaches a specified apparent ecliptic longitude in thetrue equator of datesystem.SeasonsFinds the equinoxes and solstices for a given calendar year.SunPositionCalculates the Sun's apparent true ecliptic of date (ECT) coordinates as seen from the Earth.Coordinate transformsThe following orientation systems are supported.
Astronomy Engine can convert a vector from any of these orientations to any of the others.
It also allows converting from a vector to spherical (angular) coordinates and back,
within a given orientation. Note the 3-letter codes for each of the orientation systems;
these are used in function and type names.EQJ = J2000 Mean Equator: Uses the Earth's mean equator (corrected for precession but ignoring nutation) on January 1, 2000, at noon UTC. This moment in time is called J2000.EQD = True Equator of Date: Uses the Earth's equator on a given date and time, adjusted for precession and nutation.ECL = J2000 Mean Ecliptic: Uses the plane of the Earth's orbit around the Sun at J2000. The x-axis is referenced against the J2000 mean equinox.ECT = True Ecliptic of Date: Uses the true (corrected for precession and nutation) orbital plane of the Earth on the given date. The x-axis is referenced against the true equinox for that date.HOR = Horizontal: Uses the viewpoint of an observer at a specific location on the Earth at a given date and time.GAL = Galactic: Based on the IAU 1958 definition of galactic coordinates.FunctionDescriptionRotateVectorApplies a rotation matrix to a vector, yielding a vector in another orientation system.InverseRotationGiven a rotation matrix, finds the inverse rotation matrix that does the opposite transformation.CombineRotationGiven two rotation matrices, returns a rotation matrix that combines them into a net transformation.IdentityMatrixReturns a 3x3 identity matrix, which can be used to form other rotation matrices.PivotTransforms a rotation matrix by pivoting it around a given axis by a given angle.VectorFromSphereConverts spherical coordinates to Cartesian coordinates.SphereFromVectorConverts Cartesian coordinates to spherical coordinates.EquatorFromVectorGiven an equatorial vector, calculates equatorial angular coordinates.VectorFromHorizonGiven apparent angular horizontal coordinates, calculates horizontal vector.HorizonFromVectorGiven a vector in horizontal orientation, calculates horizontal angular coordinates.Rotation_EQD_EQJCalculates a rotation matrix from true equator of date (EQD) to J2000 mean equator (EQJ).Rotation_EQD_ECTCalculates a rotation matrix from true equator of date (EQD) to true ecliptic of date (ECT).Rotation_EQD_ECLCalculates a rotation matrix from true equator of date (EQD) to J2000 mean ecliptic (ECL).Rotation_EQD_HORCalculates a rotation matrix from true equator of date (EQD) to horizontal (HOR).Rotation_EQJ_EQDCalculates a rotation matrix from J2000 mean equator (EQJ) to true equator of date (EQD).Rotation_EQJ_ECTCalculates a rotation matrix from J2000 mean equator (EQJ) to true ecliptic of date (ECT).Rotation_EQJ_ECLCalculates a rotation matrix from J2000 mean equator (EQJ) to J2000 mean ecliptic (ECL).Rotation_EQJ_HORCalculates a rotation matrix from J2000 mean equator (EQJ) to horizontal (HOR).Rotation_ECT_EQDCalculates a rotation matrix from true ecliptic of date (ECT) to true equator of date (EQD).Rotation_ECT_EQJCalculates a rotation matrix from true ecliptic of date (ECT) J2000 mean equator (EQJ).Rotation_ECL_EQDCalculates a rotation matrix from J2000 mean ecliptic (ECL) to true equator of date (EQD).Rotation_ECL_EQJCalculates a rotation matrix from J2000 mean ecliptic (ECL) to J2000 mean equator (EQJ).Rotation_ECL_HORCalculates a rotation matrix from J2000 mean ecliptic (ECL) to horizontal (HOR).Rotation_HOR_EQDCalculates a rotation matrix from horizontal (HOR) to true equator of date (EQD).Rotation_HOR_EQJCalculates a rotation matrix from horizontal (HOR) to J2000 equatorial (EQJ).Rotation_HOR_ECLCalculates a rotation matrix from horizontal (HOR) to J2000 mean ecliptic (ECL).Rotation_EQJ_GALCalculates a rotation matrix from J2000 mean equator (EQJ) to galactic (GAL).Rotation_GAL_EQJCalculates a rotation matrix from galactic (GAL) to J2000 mean equator (EQJ).Gravitational simulation of small bodiesAstronomy Engine provides aGravitySimulatorclass
that allows you to model the trajectories of one or more small bodies like asteroids,
comets, or coasting spacecraft. If you know an initial position vector
and velocity vector for a small body, the gravity simulator can incrementally
simulate the pull of gravity on it from the Sun and planets, to calculate its
movement through the Solar System.ConstantsThe following numeric constants are exported by theastronomymodule.
They may be of use for unit conversion.
Note: For the other supported programming languages, Astronomy Engine defines
helper constantsDEG2RADandRAD2DEGto convert between angular degrees and radians.
However, because Python defines theangular conversion functionsmath.degrees()andmath.radians(), they are not needed in the Python version.AU_PER_LY = 63241.07708807546The number of astronomical units in one light-year.CALLISTO_RADIUS_KM = 2410.3The mean radius of Jupiter's moon Callisto, expressed in kilometers.C_AUDAY = 173.1446326846693The speed of light expressed in astronomical units per day.EUROPA_RADIUS_KM = 1560.8The mean radius of Jupiter's moon Europa, expressed in kilometers.GANYMEDE_RADIUS_KM = 2631.2The mean radius of Jupiter's moon Ganymede, expressed in kilometers.IO_RADIUS_KM = 1821.6The mean radius of Jupiter's moon Io, expressed in kilometers.JUPITER_EQUATORIAL_RADIUS_KM = 71492.0The equatorial radius of Jupiter, expressed in kilometers.JUPITER_MEAN_RADIUS_KM = 69911.0The volumetric mean radius of Jupiter, expressed in kilometers.JUPITER_POLAR_RADIUS_KM = 66854.0The polar radius of Jupiter, expressed in kilometers.KM_PER_AU = 1.4959787069098932e+8The number of kilometers per astronomical unit.Classesclass ApsisAn event where a satellite is closest to or farthest from the body it orbits.For the Moon orbiting the Earth, or a planet orbiting the Sun, anapsisis an
event where the orbiting body reaches its closest or farthest point from the primary body.
The closest approach is calledpericenterand the farthest point isapocenter.
More specific terminology is common for particular orbiting bodies.
The Moon's closest approach to the Earth is calledperigeeand its furthest
point is calledapogee. The closest approach of a planet to the Sun is calledperihelionand the furthest point is calledaphelion.
This data structure is returned bySearchLunarApsisandNextLunarApsisto iterate through consecutive alternating perigees and apogees.TypeAttributeDescriptionTimetimeThe date and time of the apsis.ApsisKindkindWhether this is a pericenter or apocenter event.floatdist_auThe distance between the centers of the bodies in astronomical units.floatdist_kmThe distance between the centers of the bodies in kilometers.class AtmosphereInfoInformation about idealized atmospheric variables at a given elevation.TypeAttributeDescriptionfloatpressureAtmospheric pressure in pascals.floattemperatureAtmospheric temperature in kelvins.floatdensityAtmospheric densitive relative to sea level.class AxisInfoInformation about a body's rotation axis at a given time.This structure is returned byRotationAxisto report
the orientation of a body's rotation axis at a given moment in time.
The axis is specified by the direction in space that the body's north pole
points, using angular equatorial coordinates in the J2000 system (EQJ).
Thusrais the right ascension, anddecis the declination, of the
body's north pole vector at the given moment in time. The north pole
of a body is defined as the pole that lies on the north side of theSolar System's invariable plane,
regardless of the body's direction of rotation.
Thespinfield indicates the angular position of a prime meridian
arbitrarily recommended for the body by the International Astronomical
Union (IAU).
The fieldsra,dec, andspincorrespond to the variables
α0, δ0, and W, respectively, fromReport of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2015.
The fieldnorthis a unit vector pointing in the direction of the body's north pole.
It is expressed in the J2000 mean equator system (EQJ).TypeAttributeDescriptionfloatraThe J2000 right ascension of the body's north pole direction, in sidereal hours.floatdecThe J2000 declination of the body's north pole direction, in degrees.floatspinRotation angle of the body's prime meridian, in degrees.VectornorthA J2000 dimensionless unit vector pointing in the direction of the body's north pole.class ConstellationInfoReports the constellation that a given celestial point lies within.TheConstellationfunction returns aConstellationInfoobject
to report which constellation corresponds with a given point in the sky.
Constellations are defined with respect to the B1875 equatorial system
per IAU standard. Although theConstellationfunction requires J2000 equatorial
coordinates as input, the returned object contains converted B1875 coordinates for reference.TypeAttributeDescriptionstringsymbol3-character mnemonic symbol for the constellation, e.g. "Ori".stringnameFull name of constellation, e.g. "Orion".floatra1875Right ascension expressed in B1875 coordinates.floatdec1875Declination expressed in B1875 coordinates.class EclipseEventHolds a time and the observed altitude of the Sun at that time.When reporting a solar eclipse observed at a specific location on the Earth
(a "local" solar eclipse), a series of events occur. In addition
to the time of each event, it is important to know the altitude of the Sun,
because each event may be invisible to the observer if the Sun is below
the horizon.
Ifaltitudeis negative, the event is theoretical only; it would be
visible if the Earth were transparent, but the observer cannot actually see it.
Ifaltitudeis positive but less than a few degrees, visibility will be impaired by
atmospheric interference (sunrise or sunset conditions).TypeAttributeDescriptionTimetimeThe date and time of the event.floataltitudeThe angular altitude of the center of the Sun above/below the horizon, attime, corrected for atmospheric refraction and expressed in degrees.class EclipticCoordinatesEcliptic angular and Cartesian coordinates.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).TypeAttributeDescriptionVectorvecEcliptic cartesian vector with the following components: x: in the direction of the equinox along the ecliptic plane. y: Cartesian y-coordinate: in the ecliptic plane 90 degrees prograde from the equinox. z: Cartesian z-coordinate: perpendicular to the ecliptic plane. Positive is north.floatelatLatitude in degrees north (positive) or south (negative) of the ecliptic plane.floatelonLongitude in degrees around the ecliptic plane prograde from the equinox.class ElongationEventContains information about the visibility of a celestial body at a given date and time.See theElongationfunction for more detailed information about the members of this class.
See alsoSearchMaxElongationfor how to search for maximum elongation events.TypeAttributeDescriptionTimetimeThe date and time of the observation.VisibilityvisibilityWhether the body is best seen in the morning or the evening.floatelongationThe angle in degrees between the body and the Sun, as seen from the Earth.floatecliptic_separationThe difference between the ecliptic longitudes of the body and the Sun, as seen from the Earth.class EquatorialEquatorial angular coordinatesCoordinates of a celestial body as seen from the Earth.
Can be geocentric or topocentric, depending on context.
The coordinates are oriented with respect to the Earth's
equator projected onto the sky.TypeAttributeDescriptionfloatraRight ascension in sidereal hours.floatdecDeclination in degrees.floatdistDistance to the celestial body in AU.VectorvecThe equatorial coordinates in cartesian form, using AU distance units. x = direction of the March equinox, y = direction of the June solstice, z = north.class GlobalSolarEclipseInfoReports the time and geographic location of the peak of a solar eclipse.Returned bySearchGlobalSolarEclipseorNextGlobalSolarEclipseto report information about a solar eclipse event.
The eclipse is classified as partial, annular, or total, depending on the
maximum amount of the Sun's disc obscured, as seen at the peak location
on the surface of the Earth.
Thekindfield thus holdsEclipseKind.Partial,EclipseKind.Annular, orEclipseKind.Total.
A total eclipse is when the peak observer sees the Sun completely blocked by the Moon.
An annular eclipse is like a total eclipse, but the Moon is too far from the Earth's surface
to completely block the Sun; instead, the Sun takes on a ring-shaped appearance.
A partial eclipse is when the Moon blocks part of the Sun's disc, but nobody on the Earth
observes either a total or annular eclipse.
IfkindisEclipseKind.TotalorEclipseKind.Annular, thelatitudeandlongitudefields give the geographic coordinates of the center of the Moon's shadow projected
onto the daytime side of the Earth at the instant of the eclipse's peak.
Ifkindhas any other value,latitudeandlongitudeare undefined and should
not be used.
For total or annular eclipses, theobscurationfield holds the fraction (0, 1]
of the Sun's apparent disc area that is blocked from view by the Moon's silhouette,
as seen by an observer located at the geographic coordinateslatitude,longitudeat the darkest timepeak. The value will always be 1 for total eclipses, and less than
1 for annular eclipses.
For partial eclipses,obscurationholds the valueNone.
This is because there is little practical use for an obscuration value of
a partial eclipse without supplying a particular observation location.
Developers who wish to find an obscuration value for partial solar eclipses should therefore useSearchLocalSolarEclipseand provide the geographic coordinates of an observer.TypeAttributeDescriptionEclipseKindkindThe type of solar eclipse:EclipseKind.Partial,EclipseKind.Annular, orEclipseKind.Total.floatorNoneobscurationThe peak fraction of the Sun's apparent disc area obscured by the Moon (total and annular eclipses only).TimepeakThe date and time when the solar eclipse is darkest. This is the instant when the axis of the Moon's shadow cone passes closest to the Earth's center.floatdistanceThe distance between the Sun/Moon shadow axis and the center of the Earth, in kilometers.floatlatitudeThe geographic latitude at the center of the peak eclipse shadow.floatlongitudeThe geographic longitude at the center of the peak eclipse shadow.class GravitySimulatorA simulation of zero or more small bodies moving through the Solar System.This class calculates the movement of arbitrary small bodies,
such as asteroids or comets, that move through the Solar System.
It does so by calculating the gravitational forces on the bodies
from the Sun and planets. The user of this class supplies a
list of initial positions and velocities for the small bodies.
Then the class can update the positions and velocities over small
time steps.member functionsGravitySimulator.init(self, originBody:Body, time:Time, bodyStates: List[StateVector]) → NoneCreates a gravity simulation object.TypeParameterDescriptionBodyoriginBodySpecifies the origin of the reference frame. All position vectors and velocity vectors will useoriginBodyas the origin of the coordinate system. This origin applies to all the input vectors provided in thebodyStatesparameter of this function, along with all output vectors returned byGravitySimulator.Update. Most callers will want to provide one of the following:Body.Sunfor heliocentric coordinates,Body.SSBfor solar system barycentric coordinates, orBody.Earthfor geocentric coordinates. Note that the gravity simulator does not correct for light travel time; all state vectors are tied to a Newtonian "instantaneous" time.TimetimeThe initial time at which to start the simulation.StateVector[]bodyStatesAn array of zero or more initial state vectors (positions and velocities) of the small bodies to be simulated. The caller must know the positions and velocities of the small bodies at an initial moment in time. Their positions and velocities are expressed with respect tooriginBody, using J2000 mean equator orientation (EQJ). Positions are expressed in astronomical units (AU). Velocities are expressed in AU/day. All the times embedded within the state vectors must exactly matchtime, or this constructor will throw an exception.GravitySimulator.GetTime(self) →TimeThe time represented by the current step of the gravity simulation.Returns:TimeGravitySimulator.OriginBody(self) →BodyThe origin of the reference frame. See constructor for more info.Returns:BodyGravitySimulator.SolarSystemBodyState(self, body:Body) →StateVectorGet the position and velocity of a Solar System body included in the simulation.In order to simulate the movement of small bodies through the Solar System,
the simulator needs to calculate the state vectors for the Sun and planets.
If an application wants to know the positions of one or more of the planets
in addition to the small bodies, this function provides a way to obtain
their state vectors. This is provided for the sake of efficiency, to avoid
redundant calculations.
The state vector is returned relative to the position and velocity
of theoriginBodyparameter that was passed to this object's constructor.TypeParameterDescriptionBodybodyThe Sun, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, or Neptune.Returns:StateVectorThe state vector of the requested Solar System body.GravitySimulator.Swap(self) → NoneExchange the current time step with the previous time step.Sometimes it is helpful to "explore" various times near a given
simulation time step, while repeatedly returning to the original
time step. For example, when backdating a position for light travel
time, the caller may wish to repeatedly try different amounts of
backdating. When the backdating solver has converged, the caller
wants to leave the simulation in its original state.
This function allows a single "undo" of a simulation, and does so
very efficiently.
Usually this function will be called immediately after a matching
call toGravitySimulator.Update. It has the effect of rolling
back the most recent update. If called twice in a row, it reverts
the swap and thus has no net effect.
The constructor initializes the current state and previous
state to be identical. Both states represent thetimeparameter that was
passed into the constructor. Therefore,Swapwill
have no effect from the caller's point of view when passed a simulator
that has not yet been updated by a call toGravitySimulator.Update.GravitySimulator.Update(self, time:Time) → List[StateVector]Advances the gravity simulation by a small time step.Updates the simulation of the user-supplied small bodies
to the time indicated by thetimeparameter.
Returns an array of state vectors for the simulated bodies.
The array is in the same order as the original array that
was used to construct this simulator object.
The positions and velocities in the returned array are
referenced to theoriginBodythat was used to construct
this simulator.TypeParameterDescriptionTimetimeA 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. Thetimevalue may be after or before the current simulation time to move forward or backward in time.Returns:StateVector[]An array of state vectors, one for each small body.class HorizontalCoordinatesCoordinates of a celestial body as seen by a topocentric observer.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.TypeAttributeDescriptionfloatazimuthThe compass direction laterally around the observer's horizon, measured in degrees. North is 0 degrees, east is 90 degrees, south is 180 degrees, etc.floataltitudeThe angle in degrees above (positive) or below (negative) the observer's horizon.floatraThe right ascension in sidereal hours.floatdecThe declination in degrees.class HourAngleEventInformation about a celestial body crossing a specific hour angle.Returned by the functionSearchHourAngleto report information about
a celestial body crossing a certain hour angle as seen by a specified topocentric observer.TypeAttributeDescriptionTimetimeThe date and time when the body crosses the specified hour angle.HorizontalCoordinateshorApparent coordinates of the body at the time it crosses the specified hour angle.class IlluminationInfoInformation about the brightness and illuminated shape of a celestial body.Returned by functionsIlluminationandSearchPeakMagnitudeto report the visual magnitude and illuminated fraction of a celestial
body at a given date and time.TypeAttributeDescriptionTimetimeThe date and time of the observation.floatmagThe visual magnitude of the body. Smaller values are brighter.floatphase_angleThe angle in degrees between the Sun and the Earth, as seen from the body. Indicates the body's phase as seen from the Earth.floatphase_fractionA value in the range [0.0, 1.0] indicating what fraction of the body's apparent disc is illuminated, as seen from the Earth.floathelio_distThe distance between the Sun and the body at the observation time, in AU.distgeo_distThe distance between the Earth and the both at the observation time, in AU.VectorhcThe body's heliocentric vector.VectorgcThe body's geocentric vector.floatring_tiltFor Saturn, the tilt angle in degrees of its rings as seen from Earth. When thering_tiltis very close to 0, it means the rings are edge-on as seen from observers on the Earth, and are thus very difficult to see. For bodies other than Saturn,ring_tiltisNone.class JupiterMoonsInfoHolds the positions and velocities of Jupiter's major 4 moons.TheJupiterMoonsfunction returns an object of this type
to report position and velocity vectors for Jupiter's largest 4 moons
Io, Europa, Ganymede, and Callisto. Each position vector is relative
to the center of Jupiter. Both position and velocity are oriented in
the EQJ system (that is, using Earth's equator at the J2000 epoch).
The positions are expressed in astronomical units (AU),
and the velocities in AU/day.TypeAttributeDescriptionStateVectorioThe position and velocity of Jupiter's moon Io.StateVectoreuropaThe position and velocity of Jupiter's moon Europa.StateVectorganymedeThe position and velocity of Jupiter's moon Ganymede.StateVectorcallistoThe position and velocity of Jupiter's moon Callisto.class LibrationInfoLunar libration angles, returned byLibration.Contains lunar libration angles and lunar position information
for a given moment in time. SeeLibrationfor more details.TypeAttributeDescriptionfloatelatSub-Earth libration ecliptic latitude angle, in degrees.floatelonSub-Earth libration ecliptic longitude angle, in degrees.floatmlatMoon's geocentric ecliptic latitude, in degrees.floatmlonMoon's geocentric ecliptic longitude, in degrees.floatdist_kmDistance between the centers of the Earth and Moon in kilometers.floatdiam_degThe apparent angular diameter of the Moon as seen from the center of the Earth.class LocalSolarEclipseInfoInformation about a solar eclipse as seen by an observer at a given time and geographic location.Returned bySearchLocalSolarEclipseorNextLocalSolarEclipseto report information about a solar eclipse as seen at a given geographic location.
When a solar eclipse is found, it is classified as partial, annular, or total.
Thekindfield thus holdsEclipseKind.Partial,EclipseKind.Annular, orEclipseKind.Total.
A partial solar eclipse is when the Moon does not line up directly enough with the Sun
to completely block the Sun's light from reaching the observer.
An annular eclipse occurs when the Moon's disc is completely visible against the Sun
but the Moon is too far away to completely block the Sun's light; this leaves the
Sun with a ring-like appearance.
A total eclipse occurs when the Moon is close enough to the Earth and aligned with the
Sun just right to completely block all sunlight from reaching the observer.
Theobscurationfield reports what fraction of the Sun's disc appears blocked
by the Moon when viewed by the observer at the peak eclipse time.
This is a value that ranges from 0 (no blockage) to 1 (total eclipse).
The obscuration value will be between 0 and 1 for partial eclipses and annular eclipses.
The value will be exactly 1 for total eclipses. Obscuration gives an indication
of how dark the eclipse appears.
There are 5 "event" fields, each of which contains a time and a solar altitude.
Fieldpeakholds the date and time of the center of the eclipse, when it is at its peak.
The fieldspartial_beginandpartial_endare always set, and indicate when
the eclipse begins/ends. If the eclipse reaches totality or becomes annular,total_beginandtotal_endindicate when the total/annular phase begins/ends.
When an event field is valid, the caller must also check itsaltitudefield to
see whether the Sun is above the horizon at the time indicated by thetimefield.
SeeEclipseEventfor more information.TypeAttributeDescriptionEclipseKindkindThe type of solar eclipse:EclipseKind.Partial,EclipseKind.Annular, orEclipseKind.Total.floatobscurationThe fraction of the Sun's apparent disc area obscured by the Moon at the eclipse peak.EclipseEventpartial_beginThe time and Sun altitude at the beginning of the eclipse.EclipseEventorNonetotal_beginIf this is an annular or a total eclipse, the time and Sun altitude when annular/total phase begins; otherwiseNone.EclipseEventpeakThe time and Sun altitude when the eclipse reaches its peak.EclipseEventorNonetotal_endIf this is an annular or a total eclipse, the time and Sun altitude when annular/total phase ends; otherwiseNone.EclipseEventpartial_endThe time and Sun altitude at the end of the eclipse.class LunarEclipseInfoReturns information about a lunar eclipse.Returned bySearchLunarEclipseorNextLunarEclipseto report information about a lunar eclipse event.
When a lunar eclipse is found, it is classified as penumbral, partial, or total.
Penumbral eclipses are difficult to observe, because the Moon is only slightly dimmed
by the Earth's penumbra; no part of the Moon touches the Earth's umbra.
Partial eclipses occur when part, but not all, of the Moon touches the Earth's umbra.
Total eclipses occur when the entire Moon passes into the Earth's umbra.
Thekindfield thus holds one of the valuesEclipseKind.Penumbral,EclipseKind.Partial,
orEclipseKind.Total, depending on the kind of lunar eclipse found.
Theobscurationfield holds a value in the range [0, 1] that indicates what fraction
of the Moon's apparent disc area is covered by the Earth's umbra at the eclipse's peak.
This indicates how dark the peak eclipse appears. For penumbral eclipses, the obscuration
is 0, because the Moon does not pass through the Earth's umbra. For partial eclipses,
the obscuration is somewhere between 0 and 1. For total lunar eclipses, the obscuration is 1.
Fieldpeakholds the date and time of the peak of the eclipse, when it is at its peak.
Fieldssd_penum,sd_partial, andsd_totalhold the semi-duration of each phase
of the eclipse, which is half of the amount of time the eclipse spends in each
phase (expressed in minutes), or 0 if the eclipse never reaches that phase.
By converting from minutes to days, and subtracting/adding withpeak, the caller
may determine the date and time of the beginning/end of each eclipse phase.TypeAttributeDescriptionEclipseKindkindThe type of lunar eclipse found.floatobscurationThe peak fraction of the Moon's apparent disc that is covered by the Earth's umbra.TimepeakThe time of the eclipse at its peak.floatsd_penumThe semi-duration of the penumbral phase in minutes.floatsd_partialThe semi-duration of the penumbral phase in minutes, or 0.0 if none.floatsd_totalThe semi-duration of the penumbral phase in minutes, or 0.0 if none.class MoonQuarterA lunar quarter event along with its date and time.An object of this type represents one of the four major
lunar phases that appear on calendars:
new moon, first quarter, full moon, or third quarter.
Along with thequarterattribute that specifies the
type of quarter, it contains atimefield that indicates
when the lunar quarter event happens.TypeAttributeDescriptionintquarter0=new moon, 1=first quarter, 2=full moon, 3=third quarter.TimetimeThe date and time of the lunar quarter.class NodeEventInfoInformation about an ascending or descending node of a body.This object is returned bySearchMoonNodeandNextMoonNodeto report information about the center of the Moon passing through the ecliptic plane.TypeAttributeDescriptionNodeEventKindkindWhether the node is ascending (south to north) or descending (north to south).TimetimeThe time when the body passes through the ecliptic plane.class ObserverRepresents the geographic location of an observer on the surface of the Earth.TypeParameterDescriptionfloatlatitudeGeographic latitude in degrees north of the equator.floatlongitudeGeographic longitude in degrees east of the prime meridian at Greenwich, England.floatheightElevation above sea level in meters.class PositionFunctionA function for which to solve a light-travel time problem.This abstract class defines the contract for wrapping a
position vector as a function of time. A class derived fromPositionFunctionmust define aPositionmethod that
returns a position vector for a given time.
The functionCorrectLightTravelsolves a generalized
problem of deducing how far in the past light must have
left a target object to be seen by an observer at a
specified time. It is passed an instance ofPositionFunctionthat expresses a relative position vector function.member functionsPositionFunction.Position(self, time:Time) →VectorReturns a relative position vector for a given time.TypeParameterDescriptionTimetimeThe time at which to evaluate a relative position vector.Returns:Vectorclass RotationMatrixContains a rotation matrix that can be used to transform one
coordinate system into another.TypeParameterDescriptionfloat[3][3]rotA normalized 3x3 rotation matrix.class SeasonInfoThe dates and times of changes of season for a given calendar year.CallSeasonsto calculate this data structure for a given year.TypeAttributeDescriptionTimemar_equinoxThe date and time of the March equinox for the specified year.Timejun_solsticeThe date and time of the June solstice for the specified year.Timesep_equinoxThe date and time of the September equinox for the specified year.Timedec_solsticeThe date and time of the December solstice for the specified year.class SphericalHolds spherical coordinates: latitude, longitude, distance.TypeParameterDescriptionfloatlatThe latitude angle: -90..+90 degrees.floatlonThe longitude angle: 0..360 degrees.floatdistDistance in AU.class StateVectorA combination of a position vector, a velocity vector, and a time.The position (x, y, z) is measured in astronomical units (AU).
The velocity (vx, vy, vz) is measured in AU/day.
The coordinate system varies and depends on context.
The state vector also includes a time stamp.TypeAttributeDescriptionfloatxThe x-coordinate of the position, measured in AU.floatyThe y-coordinate of the position, measured in AU.floatzThe z-coordinate of the position, measured in AU.floatvxThe x-component of the velocity, measured in AU/day.floatvyThe y-component of the velocity, measured in AU/day.floatvzThe z-component of the velocity, measured in AU/day.TimetThe date and time at which the position and velocity vectors are valid.member functionsStateVector.Position(self) →VectorExtracts a position vector from this state vector.StateVector.Velocity(self) →VectorExtracts a velocity vector from this state vector.class TimeRepresents a date and time used for performing astronomy calculations.All calculations performed by Astronomy Engine are based on
dates and times represented byTimeobjects.TypeParameterDescriptionfloatutUT1/UTC number of days since noon on January 1, 2000. See theutattribute of this class for more details.TypeAttributeDescriptionfloatutThe 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 inutis 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 asmean solar days.floatttTerrestrial 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 elapsedSI secondsdivided by 86400. Unlikeut,ttincreases uniformly without adjustments for changes in the Earth's rotation. The value inttis 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 termEphemeris Time(ET).member functionsTime.AddDays(self, days: float) →TimeCalculates the sum or difference of aTimewith a specified real-valued number of days.Sometimes we need to adjust a givenTimevalue by a certain amount of time.
This function adds the given real number of days indaysto the date and time
in the calling object.
More precisely, the result's Universal Time fieldutis exactly adjusted bydaysand the Terrestrial Time fieldttis adjusted for the resulting UTC date and time,
using a best-fit piecewise polynomial model devised byEspenak and Meeus.
The value of the calling object is not modified. This function creates a brand newTimeobject and returns it.TypeParameterDescriptionfloatdaysA floating point number of days by which to adjusttime. May be negative, 0, or positive.Returns:TimeTime.Calendar(self) → Tuple[int, int, int, int, int, float]Returns a tuple of the form (year, month, day, hour, minute, second).This is a convenience method for converting aTimevalue into
its Gregorian calendar date/time representation.
Unlike the built-indatetimeclass, this method can represent
dates over a nearly 2 million year range: the years -999999 to +999999.Time.FromTerrestrialTime(tt: float) →TimeCreates aTimeobject from a Terrestrial Time day value.TypeParameterDescriptionfloatttThe number of days after the J2000 epoch.Returns:TimeTime.Make(year: int, month: int, day: int, hour: int, minute: int, second: float) →TimeCreates aTimeobject from a UTC calendar date and time.TypeParameterDescriptionintyearThe UTC year value, e.g. 2019.intmonthThe UTC month in the range 1..12.intdayThe UTC day of the month, in the range 1..31.inthourThe UTC hour, in the range 0..23.intminuteThe UTC minute, in the range 0..59.floatsecondThe real-valued UTC second, in the range [0, 60).Returns:TimeTime.Now() →TimeReturns the computer's current date and time in the form of aTimeobject.Uses the computer's system clock to find the current UTC date and time.
Converts that date and time to aTimevalue and returns the result.
Callers can pass this value to other Astronomy Engine functions to
calculate current observational conditions.Returns:TimeTime.Parse(text: str) →TimeCreates aTimeobject from a string of the form 'yyyy-mm-ddThh:mm:ss.sssZ'Parses a UTC date and time from a string and returns aTimeobject.
Permits a subset of ISO 8601 format.
The year, month, and day are required.
Hours, minutes, seconds, and fractions of a second are optional.
If time is specified, there must be a 'T' between the date and the time
and a 'Z' at the end of the time.TypeParameterDescriptionstringtextA string of the following formats:yyyy-mm-ddyyyy-mm-ddThh:mmZyyyy-mm-ddThh:mm:ssZyyyy-mm-ddThh:mm:ss.sssZReturns:TimeTime.Utc(self) → datetime.datetimeReturns the UTC date and time as adatetimeobject.Uses the standarddatetimeclass
to represent the date and time in this Time object.Returns:datetimeclass TransitInfoInformation about a transit of Mercury or Venus, as seen from the Earth.Returned bySearchTransitorNextTransitto report
information about a transit of Mercury or Venus.
A transit is when Mercury or Venus passes between the Sun and Earth so that
the other planet is seen in silhouette against the Sun.
The calculations are performed from the point of view of a geocentric observer.TypeAttributeDescriptionTimestartThe date and time at the beginning of the transit. This is the moment the planet first becomes visible against the Sun in its background.TimepeakWhen the planet is most aligned with the Sun, as seen from the Earth.TimefinishThe date and time at the end of the transit. This is the moment the planet is last seen against the Sun in its background.floatseparationThe minimum angular separation, in arcminutes, between the centers of the Sun and the planet. This angle pertains to the time stored inpeak.class VectorA Cartesian vector with 3 space coordinates and 1 time coordinate.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.TypeAttributeDescriptionfloatxThe x-coordinate of the vector, measured in AU.floatyThe y-coordinate of the vector, measured in AU.floatzThe z-coordinate of the vector, measured in AU.TimetThe date and time at which the coordinate is valid.member functionsVector.Length(self) → floatReturns the length of the vector in AU.Vector.format(self, coord_format: str) → strReturns a custom format string representation of the vector.Enumerated Typesenum ApsisKindRepresents whether a satellite is at a closest or farthest point in its orbit.An apsis is a point in a satellite's orbit that is closest to,
or farthest from, the body it orbits (its primary).ApsisKindis an enumerated type that indicates which of these
two cases applies to a particular apsis event.ValueDescriptionPericenterThe satellite is at its closest point to its primary.ApocenterThe satellite is at its farthest point from its primary.InvalidA placeholder for an undefined, unknown, or invalid apsis.enum BodyThe celestial bodies supported by Astronomy Engine calculations.ValueDescriptionInvalidAn unknown, invalid, or undefined celestial body.MercuryThe planet Mercury.VenusThe planet Venus.EarthThe planet Earth.MarsThe planet Mars.JupiterThe planet Jupiter.SaturnThe planet Saturn.UranusThe planet Uranus.NeptuneThe planet Neptune.PlutoThe planet Pluto.SunThe Sun.MoonThe Earth's moon.EMBThe Earth/Moon Barycenter.SSBThe Solar System Barycenter.Star1User-defined star 1.Star2User-defined star 2.Star3User-defined star 3.Star4User-defined star 4.Star5User-defined star 5.Star6User-defined star 6.Star7User-defined star 7.Star8User-defined star 8.enum DirectionIndicates whether a body is rising above or setting below the horizon.Specifies the direction of a rising or setting event for a body.
For example,Direction.Riseis used to find sunrise times,
andDirection.Setis used to find sunset times.ValueDescriptionRiseFirst appearance of a body as it rises above the horizon.SetLast appearance of a body as it sinks below the horizon.enum EclipseKindThe different kinds of lunar/solar eclipses.ValueDescriptionInvalidNo eclipse found.PenumbralA penumbral lunar eclipse. (Never used for a solar eclipse.)PartialA partial lunar/solar eclipse.AnnularAn annular solar eclipse. (Never used for a lunar eclipse.)TotalA total lunar/solar eclipse.enum NodeEventKindIndicates whether a crossing through the ecliptic plane is ascending or descending.ValueDescriptionInvalidA placeholder for an invalid or undefined node.Ascendingindicates a body passing through the ecliptic plane from south to north.Descendingindicates a body passing through the ecliptic plane from north to south.enum RefractionSelects if/how to correct for atmospheric refraction.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.ValueDescriptionAirlessNo atmospheric refraction correction.NormalRecommended correction for standard atmospheric refraction.JplHorizonsUsed only for compatibility testing with JPL Horizons online tool.enum VisibilityIndicates whether a body (especially Mercury or Venus) is best seen in the morning or evening.ValueDescriptionMorningThe body is best visible in the morning, before sunrise.EveningThe body is best visible in the evening, after sunset.Error TypesBadVectorErrorA vector magnitude is too small to have a direction in space.DateTimeFormatErrorThe syntax of a UTC date/time string was not valid, or it contains invalid values.EarthNotAllowedErrorThe Earth is not allowed as the celestial body in this calculation.ErrorIndicates an error in an astronomical calculation.InternalErrorAn internal error occured that should be reported as a bug.Indicates an unexpected and unrecoverable condition occurred.
If you encounter this error using Astronomy Engine, it would be very
helpful to report it at theIssuespage on GitHub. Please include a copy of the stack trace, along with a description
of how to reproduce the error. This will help improve the quality of
Astronomy Engine for everyone! (Thank you in advance from the author.)InvalidBodyErrorThe celestial body is not allowed for this calculation.NoConvergeErrorA numeric solver did not converge.Indicates that there was a failure of a numeric solver to converge.
If you encounter this error using Astronomy Engine, it would be very
helpful to report it at theIssuespage on GitHub. Please include a copy of the stack trace, along with a description
of how to reproduce the error. This will help improve the quality of
Astronomy Engine for everyone! (Thank you in advance from the author.)FunctionsAngleBetween(a:Vector, b:Vector) → floatCalculates the angle in degrees between two vectors.Given a pair of vectors, this function returns the angle in degrees
between the two vectors in 3D space.
The angle is measured in the plane that contains both vectors.TypeParameterDescriptionVectoraThe first of a pair of vectors between which to measure an angle.VectorbThe second of a pair of vectors between which to measure an angle.Returns:floatThe angle between the two vectors expressed in degrees.
The value is in the range [0, 180].AngleFromSun(body:Body, time:Time) → floatReturns the angle between the given body and the Sun, as seen from the Earth.This function calculates the angular separation between the given body and the Sun,
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.TypeParameterDescriptionBodybodyThe celestial body whose angle from the Sun is to be measured. Not allowed to beBody.Earth.TimetimeThe time at which the observation is made.Returns:floatA numeric value indicating the angle in degrees between the Sun
and the specified body as seen from the center of the Earth.Atmosphere(elevationMeters: float) →AtmosphereInfoCalculates U.S. Standard Atmosphere (1976) variables as a function of elevation.This function calculates idealized values of pressure, temperature, and density
using the U.S. Standard Atmosphere (1976) model.COESA, U.S. Standard Atmosphere, 1976, U.S. Government Printing Office, Washington, DC, 1976.Jursa, A. S., Ed., Handbook of Geophysics and the Space Environment, Air Force Geophysics Laboratory, 1985.
See:https://hbcp.chemnetbase.com/faces/documents/14_12/14_12_0001.xhtmlhttps://ntrs.nasa.gov/api/citations/19770009539/downloads/19770009539.pdfhttps://www.ngdc.noaa.gov/stp/space-weather/online-publications/miscellaneous/us-standard-atmosphere-1976/us-standard-atmosphere_st76-1562_noaa.pdfTypeParameterDescriptionfloatelevationMetersThe elevation above sea level at which to calculate atmospheric variables. Must be in the range -500 to +100000, or an exception will occur.Returns:AtmosphereInfoBackdatePosition(time:Time, observerBody:Body, targetBody:Body, aberration: bool) →VectorSolve for light travel time correction of apparent position.When observing a distant object, for example Jupiter as seen from Earth,
the amount of time it takes for light to travel from the object to the
observer can significantly affect the object's apparent position.
This function solves the light travel time correction for the apparent
relative position vector of a target body as seen by an observer body
at a given observation time.
For geocentric calculations,GeoVectoralso includes light
travel time correction, but the timetembedded in its returned vector
refers to the observation time, not the backdated time that light left
the observed body. ThusBackdatePositionprovides direct
access to the light departure time for callers that need it.
For a more generalized light travel correction solver, seeCorrectLightTravel.TypeParameterDescriptionTimetimeThe time of observation.BodyobserverBodyThe body to be used as the observation location.BodytargetBodyThe body to be observed.boolaberrationTrueto correct for aberration, orFalseto leave uncorrected.Returns:VectorThe position vector at the solved backdated time.
Itstfield holds the time that light left the observed
body to arrive at the observer at the observation time.BaryState(body:Body, time:Time) →StateVectorCalculates barycentric position and velocity vectors for the given body.Given a body and a time, calculates the barycentric position and velocity
vectors for the center of that body at that time.
The vectors are expressed in J2000 mean equator coordinates (EQJ).TypeParameterDescriptionBodybodyThe celestial body whose barycentric state vector is to be calculated. Supported values areBody.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.TimetimeThe date and time for which to calculate position and velocity.Returns:StateVectorAn object that contains barycentric position and velocity vectors.BodyCode(name: str) →BodyFinds the Body enumeration value, given the name of a body.>>> astronomy.BodyCode('Mars')
<Body.Mars: 3>TypeParameterDescriptionstrnameThe common English name of a supported celestial body.Returns:BodyIfnameis a valid body name, returns the enumeration
value associated with that body.
Otherwise, returnsBody.Invalid.CombineRotation(a:RotationMatrix, b:RotationMatrix) →RotationMatrixCreates a rotation based on applying one rotation followed by another.Given two rotation matrices, returns a combined rotation matrix that is
equivalent to rotating based on the first matrix, followed by the second.TypeParameterDescriptionRotationMatrixaThe first rotation to apply.RotationMatrixbThe second rotation to apply.Returns:RotationMatrixThe combined rotation matrix.Constellation(ra: float, dec: float) →ConstellationInfoDetermines the constellation that contains the given point in the sky.Given J2000 equatorial (EQJ) coordinates of a point in the sky, determines the
constellation that contains that point.TypeParameterDescriptionfloatraThe right ascension (RA) of a point in the sky, using the J2000 equatorial system.floatdecThe declination (DEC) of a point in the sky, using the J2000 equatorial system.Returns:ConstellationInfoA 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.CorrectLightTravel(func:PositionFunction, time:Time) →VectorSolve for light travel time of a vector function.When observing a distant object, for example Jupiter as seen from Earth,
the amount of time it takes for light to travel from the object to the
observer can significantly affect the object's apparent position.
This function is a generic solver that figures out how long in the
past light must have left the observed object to reach the observer
at the specified observation time. It usesPositionFunctionto express an arbitrary position vector as a function of time.
This function repeatedly callsfunc.Position, passing a series of time
estimates in the past. Thenfunc.Positionmust return a relative state vector between
the observer and the target.CorrectLightTravelkeeps callingfunc.Positionwith more and more refined estimates of the time light must have
left the target to arrive at the observer.
For common use cases, it is simpler to useBackdatePositionfor calculating the light travel time correction of one body observing another body.
For geocentric calculations,GeoVectoralso backdates the returned
position vector for light travel time, only it returns the observation time in
the returned vector'stfield rather than the backdated time.
time : Time
The observation time for which to solve for light travel delay.TypeParameterDescriptionPositionFunctionfuncAn arbitrary position vector as a function of time.Returns:VectorThe position vector at the solved backdated time.
Thetfield holds the time that light left the observed
body to arrive at the observer at the observation time.DefineStar(body:Body, ra: float, dec: float, distanceLightYears: float) → NoneAssign equatorial coordinates to a user-defined star.Some Astronomy Engine functions allow theirbodyparameter to
be a user-defined fixed point in the sky, loosely called a "star".
This function assigns a right ascension, declination, and distance
to one of the eight user-defined starsBody.Star1..Body.Star8.
Stars are not valid until defined. Once defined, they retain their
definition until re-defined by another call toDefineStar.TypeParameterDescriptionBodybodyOne of the eight user-defined star identifiers:Body.Star1,Body.Star2, ...,Body.Star8.floatraThe right ascension to be assigned to the star, expressed in J2000 equatorial coordinates (EQJ). The value is in units of sidereal hours, and must be within the half-open range [0, 24).floatdecThe declination to be assigned to the star, expressed in J2000 equatorial coordinates (EQJ). The value is in units of degrees north (positive) or south (negative) of the J2000 equator, and must be within the closed range [-90, +90].floatdistanceLightYearsThe distance between the star and the Sun, expressed in light-years. This value is used to calculate the tiny parallax shift as seen by an observer on Earth. If you don't know the distance to the star, using a large value like 1000 will generally work well. The minimum allowed distance is 1 light-year, which is required to provide certain internal optimizations.DeltaT_EspenakMeeus(ut: float) → floatThe default Delta T function used by Astronomy Engine.Espenak and Meeus use a series of piecewise polynomials to
approximate DeltaT of the Earth in their "Five Millennium Canon of Solar Eclipses".
See:https://eclipse.gsfc.nasa.gov/SEhelp/deltatpoly2004.htmlThis is the default Delta T function used by Astronomy Engine.TypeParameterDescriptionfloatutThe floating point number of days since noon UTC on January 1, 2000.Returns:floatThe estimated difference TT-UT on the given date, expressed in seconds.Ecliptic(eqj:Vector) →EclipticCoordinatesConverts a J2000 mean equator (EQJ) vector to a true ecliptic of date (ETC) vector and angles.Given coordinates relative to the Earth's equator at J2000 (the instant of noon UTC
on 1 January 2000), this function converts those coordinates to true ecliptic coordinates of date,
which are relative to the plane of the Earth's orbit around the Sun.TypeParameterDescriptionVectoreqjEquatorial coordinates in the J2000 frame of reference. You can callGeoVectorto obtain suitable equatorial coordinates.Returns:EclipticCoordinatesSpherical and vector coordinates expressed in true ecliptic coordinates of date (ECT).EclipticGeoMoon(time:Time) →SphericalCalculates spherical ecliptic geocentric position of the Moon.Given a time of observation, calculates the Moon's geocentric position
in ecliptic spherical coordinates. Provides the ecliptic latitude and
longitude in degrees, and the geocentric distance in astronomical units (AU).
The ecliptic angles are measured in "ECT": relative to the true ecliptic plane and
equatorial plane at the specified time. This means the Earth's equator
is corrected for precession and nutation, and the plane of the Earth's
orbit is corrected for gradual obliquity drift.
This algorithm is based on the Nautical Almanac Office'sImproved Lunar Ephemerisof 1954,
which in turn derives from E. W. Brown's lunar theories from the early twentieth century.
It is adapted from Turbo Pascal code from the bookAstronomy on the Personal Computerby Montenbruck and Pfleger.
To calculate a J2000 mean equator vector instead, useGeoMoon.TypeParameterDescriptionTimetimeThe date and time for which to calculate the Moon's position.Returns:SphericalThe Moon's position as a distance, ecliptic latitude, and ecliptic longitude.EclipticLongitude(body:Body, time:Time) → floatCalculates heliocentric ecliptic longitude of a body.This function calculates the angle around the plane of the Earth's orbit
of a celestial body, as seen from the center of the Sun.
The angle is measured prograde (in the direction of the Earth's orbit around the Sun)
in degrees from the true equinox of date. The ecliptic longitude is always in the range [0, 360).TypeParameterDescriptionBodybodyA body other than the Sun.TimetimeThe date and time at which the body's ecliptic longitude is to be calculated.Returns:floatAn angular value in degrees indicating the ecliptic longitude of the body.Elongation(body:Body, time:Time) →ElongationEventDetermines visibility of a celestial body relative to the Sun, as seen from the Earth.This function returns anElongationEventobject, which provides the following
information about the given celestial body at the given time:visibilityis an enumerated type that specifies whether the body is more
easily seen in the morning before sunrise, or in the evening after sunset.elongationis the angle in degrees between two vectors: one from the center
of the Earth to the center of the Sun, the other from the center of the Earth
to the center of the specified body. This angle indicates how far away the body
is from the glare of the Sun. The elongation angle is always in the range [0, 180].ecliptic_separationis the absolute value of the difference between the body's
ecliptic longitude and the Sun's ecliptic longitude, both as seen from the center
of the Earth. This angle measures around the plane of the Earth's orbit, and ignores
how far above or below that plane the body is.
The ecliptic separation is measured in degrees and is always in the range [0, 180].TypeParameterDescriptionBodybodyThe celestial body whose visibility is to be calculated.TimetimeThe date and time of the observation.Returns:ElongationEventEquator(body:Body, time:Time, observer:Observer, ofdate: bool, aberration: bool) →EquatorialCalculates equatorial coordinates of a celestial body as seen by an observer on the Earth's surface.Calculates topocentric equatorial coordinates in one of two different systems:
J2000 or true-equator-of-date, depending on the value of theofdateparameter.
Equatorial coordinates include right ascension, declination, and distance in astronomical units.
This function corrects for light travel time: it adjusts the apparent location
of the observed body based on how long it takes for light to travel from the body to the Earth.
This function corrects fortopocentric parallax, meaning that it adjusts for the
angular shift depending on where the observer is located on the Earth. This is most
significant for the Moon, because it is so close to the Earth. However, parallax corection
has a small effect on the apparent positions of other bodies.
Correction for aberration is optional, using theaberrationparameter.TypeParameterDescriptionBodybodyThe celestial body to be observed. Not allowed to beBody.Earth.TimetimeThe date and time at which the observation takes place.ObserverobserverA location on or near the surface of the Earth.boolofdateSelects the date of the Earth's equator in which to express the equatorial coordinates. IfTrue, returns coordinates using the equator and equinox of date. IfFalse, returns coordinates converted to the J2000 system.boolaberrationIfTrue, corrects for aberration of light based on the motion of the Earth with respect to the heliocentric origin. IfFalse, does not correct for aberration.Returns:EquatorialEquatorial coordinates in the specified frame of reference.EquatorFromVector(vec:Vector) →EquatorialGiven an equatorial vector, calculates equatorial angular coordinates.TypeParameterDescriptionVectorvecA vector in an equatorial coordinate system.Returns:EquatorialAngular coordinates expressed in the same equatorial system asvec.GeoEmbState(time:Time) →StateVectorCalculates the geocentric position and velocity of the Earth/Moon barycenter.Given a time of observation, calculates the geocentric position and velocity vectors
of the Earth/Moon barycenter (EMB).
The position (x, y, z) components are expressed in AU (astronomical units).
The velocity (vx, vy, vz) components are expressed in AU/day.TypeParameterDescriptionTimetimeThe date and time for which to calculate the EMB's geocentric state.Returns:StateVectorThe EMB's position and velocity vectors in J2000 equatorial coordinates.GeoMoon(time:Time) →VectorCalculates equatorial geocentric position of the Moon at a given time.Given a time of observation, calculates the Moon's position as a vector.
The vector gives the location of the Moon's center relative to the Earth's center
with x-, y-, and z-components measured in astronomical units.
The coordinates are oriented with respect to the Earth's equator at the J2000 epoch.
In Astronomy Engine, this orientation is called EQJ.
This algorithm is based on the Nautical Almanac Office'sImproved Lunar Ephemerisof 1954,
which in turn derives from E. W. Brown's lunar theories from the early twentieth century.
It is adapted from Turbo Pascal code from the bookAstronomy on the Personal Computerby Montenbruck and Pfleger.TypeParameterDescriptionTimetimeThe date and time for which to calculate the Moon's position.Returns:VectorThe Moon's position as a vector in J2000 Cartesian equatorial coordinates (EQJ).GeoMoonState(time:Time) →StateVectorCalculates equatorial geocentric position and velocity of the Moon at a given time.Given a time of observation, calculates the Moon's position and velocity vectors.
The position and velocity are of the Moon's center relative to the Earth's center.
The position (x, y, z) components are expressed in AU (astronomical units).
The velocity (vx, vy, vz) components are expressed in AU/day.
The coordinates are oriented with respect to the Earth's equator at the J2000 epoch.
In Astronomy Engine, this orientation is called EQJ.
If you need the Moon's position only, and not its velocity,
it is much more efficient to useGeoMooninstead.TypeParameterDescriptionTimetimeThe date and time for which to calculate the Moon's position and velocity.Returns:StateVectorThe Moon's position and velocity vectors in J2000 equatorial coordinates (EQJ).GeoVector(body:Body, time:Time, aberration: bool) →VectorCalculates geocentric Cartesian coordinates of a body in the J2000 equatorial system.This function calculates the position of the given celestial body as a vector,
using the center of the Earth as the origin.  The result is expressed as a Cartesian
vector in the J2000 equatorial system: the coordinates are based on the mean equator
of the Earth at noon UTC on 1 January 2000.
If given an invalid value forbody, this function will raise an exception.
UnlikeHelioVector, this function corrects for light travel time.
This means the position of the body is "back-dated" by the amount of time it takes
light to travel from that body to an observer on the Earth.
Also, the position can optionally be corrected foraberration, an effect
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.TypeParameterDescriptionBodybodyA body for which to calculate a heliocentric position: the Sun, Moon, or any of the planets.TimetimeThe date and time for which to calculate the position.boolaberrationA boolean value indicating whether to correct for aberration.Returns:VectorA geocentric position vector of the center of the given body.HelioDistance(body:Body, time:Time) → floatCalculates the distance between a body and the Sun at a given time.Given a date and time, this function calculates the distance between
the center ofbodyand the center of the Sun.
For the planets Mercury through Neptune, this function is significantly
more efficient than callingHelioVectorfollowed by taking the length
of the resulting vector.TypeParameterDescriptionBodybodyA body for which to calculate a heliocentric distance: the Sun, Moon, any of the planets, or a user-defined star.TimetimeThe date and time for which to calculate the heliocentric distance.Returns:floatThe heliocentric distance in AU.HelioState(body:Body, time:Time) →StateVectorCalculates heliocentric position and velocity vectors for the given body.Given a body and a time, calculates the position and velocity
vectors for the center of that body at that time, relative to the center of the Sun.
The vectors are expressed in J2000 mean equator coordinates (EQJ).
If you need the position vector only, it is more efficient to callHelioVector.
The Sun's center is a non-inertial frame of reference. In other words, the Sun
experiences acceleration due to gravitational forces, mostly from the larger
planets (Jupiter, Saturn, Uranus, and Neptune). If you want to calculate momentum,
kinetic energy, or other quantities that require a non-accelerating frame
of reference, consider usingBaryStateinstead.TypeParameterDescriptionBodybodyThe celestial body whose heliocentric state vector is to be calculated. Supported values areBody.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. Also allowed to be a user-defined star created byDefineStar.TimetimeThe date and time for which to calculate position and velocity.Returns:StateVectorAn object that contains heliocentric position and velocity vectors.HelioVector(body:Body, time:Time) →VectorCalculates heliocentric Cartesian coordinates of a body in the J2000 equatorial system.This function calculates the position of the given celestial body as a vector,
using the center of the Sun as the origin.  The result is expressed as a Cartesian
vector in the J2000 equatorial system: the coordinates are based on the mean equator
of the Earth at noon UTC on 1 January 2000.
The position is not corrected for light travel time or aberration.
This is different from the behavior ofGeoVector.
If given an invalid value forbody, this function raises an exception.TypeParameterDescriptionBodybodyThe celestial body whose heliocentric position is to be calculated: The Sun, Moon, EMB, SSB, or any of the planets. Also allowed to be a user-defined star created byDefineStar.TimetimeThe time at which to calculate the heliocentric position.Returns:VectorA heliocentric position vector of the center of the given body
at the given time.Horizon(time:Time, observer:Observer, ra: float, dec: float, refraction:Refraction) →HorizontalCoordinatesCalculates the apparent location of a body relative to the local horizon of an observer on the Earth.Given a date and time, the geographic location of an observer on the Earth, and
equatorial coordinates (right ascension and declination) of a celestial body,
this function returns horizontal coordinates (azimuth and altitude angles) for the body
relative to the horizon at the geographic location.
The right ascensionraand declinationdecpassed in must beequator of datecoordinates, based on the Earth's true equator at the date and time of the observation.
Otherwise the resulting horizontal coordinates will be inaccurate.
Equator of date coordinates can be obtained by callingEquator, passing inTrueas itsofdateparameter. It is also recommended to enable
aberration correction by passing inTruefor theaberrationparameter.
This function optionally corrects for atmospheric refraction.
For most uses, it is recommended to passRefraction.Normalin therefractionparameter to
correct for optical lensing of the Earth's atmosphere that causes objects
to appear somewhat higher above the horizon than they actually are.
However, callers may choose to avoid this correction by passing inRefraction.Airless.
If refraction correction is enabled, the azimuth, altitude, right ascension, and declination
in theHorizontalCoordinatesobject returned by this function will all be corrected for refraction.
If refraction is disabled, none of these four coordinates will be corrected; in that case,
the right ascension and declination in the returned object will be numerically identical
to the respectiveraanddecvalues passed in.TypeParameterDescriptionTimetimeThe date and time for which to find horizontal coordinates.ObserverobserverThe location of the observer for which to find horizontal coordinates.floatraRight ascension in sidereal hours of the celestial object, referred to the mean equinox of date for the J2000 epoch.floatdecDeclination 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.RefractionrefractionThe option for selecting whether to correct for atmospheric lensing. IfRefraction.Normal, a well-behaved refraction model is used. IfRefraction.Airless, no refraction correct is performed.Refraction.JplHorizonsis used only for compatibility testing with the JPL Horizons online tool.Returns:HorizontalCoordinatesThe 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.HorizonFromVector(vector:Vector, refraction:Refraction) →SphericalConverts Cartesian coordinates to horizontal coordinates.Given a horizontal Cartesian vector, returns horizontal azimuth and altitude.IMPORTANT:This function differs fromSphereFromVectorin two ways:SphereFromVectorreturns alonvalue that represents azimuth defined counterclockwise
from north (e.g., west = +90), but this function represents a clockwise rotation
(e.g., east = +90). The difference is becauseSphereFromVectoris intended
to preserve the vector "right-hand rule", while this function defines azimuth in a more
traditional way as used in navigation and cartography.This function optionally corrects for atmospheric refraction, whileSphereFromVectordoes not.
The returned object contains the azimuth inlon.
It is measured in degrees clockwise from north: east = +90 degrees, west = +270 degrees.
The altitude is stored inlat.
The distance to the observed object is stored indist,
and is expressed in astronomical units (AU).TypeParameterDescriptionVectorvectorCartesian vector to be converted to horizontal angular coordinates.RefractionrefractionSee comments in theRefractionAnglefunction.HourAngle(body:Body, time:Time, observer:Observer) → floatFinds the hour angle of a body for a given observer and time.Thehour angleof 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's center 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 returns the hour angle of the body as seen at the given time and geogrpahic location.
The hour angle is a number in the half-open range [0, 24).TypeParameterDescriptionBodybodyThe body whose observed hour angle is to be found.TimetimeThe date and time of the observation.ObserverobserverThe geographic location where the observation takes place.Returns:floatIdentityMatrix() →RotationMatrixCreates an identity rotation matrix.Returns a rotation matrix that has no effect on orientation.
This matrix can be the starting point for other operations,
such as using a series of calls toPivotto
create a custom rotation matrix.Returns:RotationMatrixThe identity rotation matrix.Illumination(body:Body, time:Time) →IlluminationInfoFinds visual magnitude, phase angle, and other illumination information about a celestial body.This function calculates information about how bright a celestial body appears from the Earth,
reported as visual magnitude, which is a smaller (or even negative) number for brighter objects,
and a larger number for dimmer objects.
For bodies other than the Sun, it reports a phase angle, which is the angle in degrees between
the Sun and the Earth, as seen from the center of the body. Phase angle indicates what fraction
of the body appears illuminated as seen from the Earth. For example, when the phase angle is
near zero, it means the body appears "full" as seen from the Earth.  A phase angle approaching
180 degrees means the body appears as a thin crescent as seen from the Earth.  A phase angle
of 90 degrees means the body appears "half full".
For the Sun, the phase angle is always reported as 0; the Sun emits light rather than reflecting it,
so it doesn't have a phase angle.
When the body is Saturn, the returned object contains a fieldring_tiltthat holds
the tilt angle in degrees of Saturn's rings as seen from the Earth. A value of 0 means
the rings appear edge-on, and are thus nearly invisible from the Earth. Thering_tiltholds
0 for all bodies other than Saturn.TypeParameterDescriptionBodybodyThe Sun, Moon, or any planet other than the Earth.TimetimeThe date and time of the observation.Returns:IlluminationInfoInverseRefractionAngle(refraction:Refraction, bent_altitude: float) → floatCalculates the inverse of an atmospheric refraction angle.Given an observed altitude angle that includes atmospheric refraction,
calculates the negative angular correction to obtain the unrefracted
altitude. This is useful for cases where observed horizontal
coordinates are to be converted to another orientation system,
but refraction first must be removed from the observed position.TypeParameterDescriptionRefractionrefractionRefraction.Normal- corrects for atmospheric refraction (recommended).Refraction.Airless- no correction is performed.Refraction.JplHorizons- For JPL Horizons compatibility testing only.floatbent_altitudeThe apparent altitude that includes atmospheric refraction.Returns:floatThe 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.InverseRotation(rotation:RotationMatrix) →RotationMatrixCalculates the inverse of a rotation matrix.Given a rotation matrix that performs some coordinate transform,
this function returns the matrix that reverses that transform.TypeParameterDescriptionRotationMatrixrotationThe rotation matrix to be inverted.Returns:RotationMatrixThe inverse rotation matrix.JupiterMoons(time:Time) →JupiterMoonsInfoCalculates jovicentric positions and velocities of Jupiter's largest 4 moons.Calculates position and velocity vectors for Jupiter's moons
Io, Europa, Ganymede, and Callisto, at the given date and time.
The vectors are jovicentric (relative to the center of Jupiter).
Their orientation is the Earth's equatorial system at the J2000 epoch (EQJ).
The position components are expressed in astronomical units (AU), and the
velocity components are in AU/day.
To convert to heliocentric vectors, callHelioVectorwithBody.Jupiterto get Jupiter's heliocentric position, then
add the jovicentric vectors. Likewise, you can callGeoVectorto convert to geocentric vectors.TypeParameterDescriptionTimetimeThe date and time for which to calculate Jupiter's moons.Returns:JupiterMoonsInfoThe positions and velocities of Jupiter's 4 largest moons.LagrangePoint(point: int, time:Time, major_body:Body, minor_body:Body) →StateVectorCalculates one of the 5 Lagrange points for a pair of co-orbiting bodies.Given a more massive "major" body and a much less massive "minor" body,
calculates one of the five Lagrange points in relation to the minor body's
orbit around the major body. The parameterpointis an integer that
selects the Lagrange point as follows:
1 = the Lagrange point between the major body and minor body.
2 = the Lagrange point on the far side of the minor body.
3 = the Lagrange point on the far side of the major body.
4 = the Lagrange point 60 degrees ahead of the minor body's orbital position.
5 = the Lagrange point 60 degrees behind the minor body's orbital position.
The function returns the state vector for the selected Lagrange point
in J2000 mean equator coordinates (EQJ), with respect to the center of the
major body.
To calculate Sun/Earth Lagrange points, pass inBody.Sunformajor_bodyandBody.EMB(Earth/Moon barycenter) forminor_body.
For Lagrange points of the Sun and any other planet, pass in just that planet
(e.g.Body.Jupiter) forminor_body.
To calculate Earth/Moon Lagrange points, pass inBody.EarthandBody.Moonfor the major and minor bodies respectively.
In some cases, it may be more efficient to callLagrangePointFast,
especially when the state vectors have already been calculated, or are needed
for some other purpose.TypeParameterDescriptionintpointAn integer 1..5 that selects which of the Lagrange points to calculate.TimetimeThe time for which the Lagrange point is to be calculated.Bodymajor_bodyThe more massive of the co-orbiting bodies:Body.SunorBody.Earth.Bodyminor_bodyThe less massive of the co-orbiting bodies. See main remarks.Returns:StateVectorThe position and velocity of the selected Lagrange point with respect to the major body's center.LagrangePointFast(point: int, major_state:StateVector, major_mass: float, minor_state:StateVector, minor_mass: float) →StateVectorCalculates one of the 5 Lagrange points from body masses and state vectors.Given a more massive "major" body and a much less massive "minor" body,
calculates one of the five Lagrange points in relation to the minor body's
orbit around the major body. The parameterpointis an integer that
selects the Lagrange point as follows:
1 = the Lagrange point between the major body and minor body.
2 = the Lagrange point on the far side of the minor body.
3 = the Lagrange point on the far side of the major body.
4 = the Lagrange point 60 degrees ahead of the minor body's orbital position.
5 = the Lagrange point 60 degrees behind the minor body's orbital position.
The caller passes in the state vector and mass for both bodies.
The state vectors can be in any orientation and frame of reference.
The body masses are expressed as GM products, where G = the universal
gravitation constant and M = the body's mass. Thus the units formajor_massandminor_massmust be au^3/day^2.
UseMassProductto obtain GM values for various solar system bodies.
The function returns the state vector for the selected Lagrange point
using the same orientation as the state vector parametersmajor_stateandminor_state,
and the position and velocity components are with respect to the major body's center.
Consider callingLagrangePoint, instead of this function, for simpler usage in most cases.TypeParameterDescriptionintpointAn integer 1..5 that selects which of the Lagrange points to calculate.StateVectormajor_stateThe state vector of the major (more massive) of the pair of bodies.floatmajor_massThe mass product GM of the major body.StateVectorminor_stateThe state vector of the minor (less massive) of the pair of bodies.floatminor_massThe mass product GM of the minor body.Returns:StateVectorThe position and velocity of the selected Lagrange point with respect to the major body's center.Libration(time:Time) →LibrationInfoCalculates the Moon's libration angles at a given moment in time.Libration is an observed back-and-forth wobble of the portion of the
Moon visible from the Earth. It is caused by the imperfect tidal locking
of the Moon's fixed rotation rate, compared to its variable angular speed
of orbit around the Earth.
This function calculates a pair of perpendicular libration angles,
one representing rotation of the Moon in ecliptic longitudeelon, the other
in ecliptic latitudeelat, both relative to the Moon's mean Earth-facing position.
This function also returns the geocentric position of the Moon
expressed in ecliptic longitudemlon, ecliptic latitudemlat, the
distancedist_kmbetween the centers of the Earth and Moon expressed in kilometers,
and the apparent angular diameter of the Moondiam_deg.TypeParameterDescriptionTimetimeThe date and time for which to calculate the Moon's libration angles.Returns:LibrationInfoMassProduct(body:Body) → floatReturns the product of mass and universal gravitational constant of a Solar System body.For problems involving the gravitational interactions of Solar System bodies,
it is helpful to know the product GM, where G = the universal gravitational constant
and M = the mass of the body. In practice, GM is known to a higher precision than
either G or M alone, and thus using the product results in the most accurate results.
This function returns the product GM in the units au^3/day^2.
The values come from page 10 of aJPL memorandum regarding the DE405/LE405 ephemeris.TypeParameterDescriptionBodybodyThe 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:floatThe mass product of the given body in au^3/day^2.MoonPhase(time:Time) → floatReturns the Moon's phase as an angle from 0 to 360 degrees.This function determines the phase of the Moon using its apparent
ecliptic longitude relative to the Sun, as seen from the center of the Earth.
Certain values of the angle have conventional definitions:0 = new moon90 = first quarter180 = full moon270 = third quarterTypeParameterDescriptionTimetimeThe date and time of the observation.Returns:floatNextGlobalSolarEclipse(prevEclipseTime:Time) →GlobalSolarEclipseInfoSearches for the next global solar eclipse in a series.After usingSearchGlobalSolarEclipseto find the first solar eclipse
in a series, you can call this function to find the next consecutive solar eclipse.
Pass in thepeakvalue from theGlobalSolarEclipseInforeturned by the
previous call toSearchGlobalSolarEclipseorNextGlobalSolarEclipseto find the next solar eclipse.TypeParameterDescriptionTimeprevEclipseTimeA date and time near a new moon. Solar eclipse search will start at the next new moon.Returns:GlobalSolarEclipseInfoNextLocalSolarEclipse(prevEclipseTime:Time, observer:Observer) →LocalSolarEclipseInfoSearches for the next local solar eclipse in a series.After usingSearchLocalSolarEclipseto find the first solar eclipse
in a series, you can call this function to find the next consecutive solar eclipse.
Pass in thepeakvalue from theLocalSolarEclipseInforeturned by the
previous call toSearchLocalSolarEclipseorNextLocalSolarEclipseto find the next solar eclipse.TypeParameterDescriptionTimeprevEclipseTimeA date and time near a new moon. Solar eclipse search will start at the next new moon.ObserverobserverThe geographic location of the observer.Returns:LocalSolarEclipseInfoNextLunarApsis(apsis:Apsis) →ApsisFinds the next lunar perigee or apogee in a series.This function requires anApsisvalue obtained from a call toSearchLunarApsisorNextLunarApsis.
Given an apogee event, this function finds the next perigee event,
and vice versa.
SeeSearchLunarApsisfor more details.TypeParameterDescriptionApsisapsisReturns:ApsisNextLunarEclipse(prevEclipseTime:Time) →LunarEclipseInfoSearches for the next lunar eclipse in a series.After usingSearchLunarEclipseto find the first lunar eclipse
in a series, you can call this function to find the next consecutive lunar eclipse.
Pass in thepeakvalue from theLunarEclipseInforeturned by the
previous call toSearchLunarEclipseorNextLunarEclipseto find the next lunar eclipse.TypeParameterDescriptionTimeprevEclipseTimeA date and time near a full moon. Lunar eclipse search will start at the next full moon.Returns:LunarEclipseInfoNextMoonNode(prevNode:NodeEventInfo) →NodeEventInfoSearches for the next time when the Moon's center crosses through the ecliptic plane.CallSearchMoonNodeto find the first of a series of nodes.
Then callNextMoonNodeto find as many more consecutive nodes as desired.TypeParameterDescriptionNodeEventInfoprevNodeThe previous node find from callingSearchMoonNodeorNextMoonNode.Returns:NodeEventInfoNextMoonQuarter(mq:MoonQuarter) →MoonQuarterContinues searching for lunar quarters from a previous search.After callingSearchMoonQuarter, this function can be called
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 parametermq.TypeParameterDescriptionMoonQuartermqA value returned by a prior call toSearchMoonQuarterorNextMoonQuarter.Returns:MoonQuarterNextPlanetApsis(body:Body, apsis:Apsis) →ApsisFinds the next planetary perihelion or aphelion event in a series.This function requires anApsisvalue obtained from a call
toSearchPlanetApsisorNextPlanetApsis.
Given an aphelion event, this function finds the next perihelion event, and vice versa.
SeeSearchPlanetApsisfor more details.TypeParameterDescriptionBodybodyThe planet for which to find the next perihelion/aphelion event. Not allowed to beBody.SunorBody.Moon. Must match the body passed into the call that produced theapsisparameter.ApsisapsisAn apsis event obtained from a call toSearchPlanetApsisorNextPlanetApsis.Returns:ApsisNextTransit(body:Body, prevTransitTime:Time) →TransitInfoSearches for another transit of Mercury or Venus.After callingSearchTransitto find a transit of Mercury or Venus,
this function finds the next transit after that.
Keep calling this function as many times as you want to keep finding more transits.TypeParameterDescriptionBodybodyThe planet whose transit is to be found. Must beBody.MercuryorBody.Venus.TimeprevTransitTimeA date and time near the previous transit.Returns:TransitInfoObserverGravity(latitude: float, height: float) → floatCalculates the gravitational acceleration experienced by an observer on the Earth.This function implements the WGS 84 Ellipsoidal Gravity Formula.
The result is a combination of inward gravitational acceleration
with outward centrifugal acceleration, as experienced by an observer
in the Earth's rotating frame of reference.
The resulting value increases toward the Earth's poles and decreases
toward the equator, consistent with changes of the weight measured
by a spring scale of a fixed mass moved to different latitudes and heights
on the Earth.TypeParameterDescriptionfloatlatitudeThe 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.floatheightThe 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:floatThe effective gravitational acceleration expressed in meters per second squared [m/s^2].ObserverState(time:Time, observer:Observer, ofdate: bool) →StateVectorCalculates geocentric equatorial position and velocity of an observer on the surface of the Earth.This function calculates position and velocity vectors of an observer
on or near the surface of the Earth, expressed in equatorial
coordinates. It takes into account the rotation of the Earth at the given
time, along with the given latitude, longitude, and elevation of the observer.
The caller may passofdateasTrueto return coordinates relative to the Earth's
equator at the specified time, orFalseto use the J2000 equator.
The returned position vector has components expressed in astronomical units (AU).
To convert to kilometers, multiply thex,y, andzvalues by
the constant valueKM_PER_AU.
The returned velocity vector has components expressed in AU/day.TypeParameterDescriptionTimetimeThe date and time for which to calculate the observer's position and velocity vectors.ObserverobserverThe geographic location of a point on or near the surface of the Earth.boolofdateSelects the date of the Earth's equator in which to express the equatorial coordinates. The caller may passFalseto 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 thetimeparameter. Or the caller may passTrueto use the Earth's equator attimeas the orientation.Returns:StateVectorAn equatorial position vector and velocity vector relative to the center of the Earth.ObserverVector(time:Time, observer:Observer, ofdate: bool) →VectorCalculates geocentric equatorial coordinates of an observer on the surface of the Earth.This function calculates a vector from the center of the Earth to
a point on or near the surface of the Earth, expressed in equatorial
coordinates. It takes into account the rotation of the Earth at the given
time, along with the given latitude, longitude, and elevation of the observer.
The caller may passofdateasTrueto return coordinates relative to the Earth's
equator at the specified time, orFalseto use the J2000 equator.
The returned vector has components expressed in astronomical units (AU).
To convert to kilometers, multiply thex,y, andzvalues by
the constant valueKM_PER_AU.
The inverse of this function is also available:VectorObserver.TypeParameterDescriptionTimetimeThe date and time for which to calculate the observer's position vector.ObserverobserverThe geographic location of a point on or near the surface of the Earth.boolofdateSelects the date of the Earth's equator in which to express the equatorial coordinates. The caller may passFalseto 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 thetimeparameter. Or the caller may passTrueto use the Earth's equator attimeas the orientation.Returns:VectorAn equatorial vector from the center of the Earth to the specified location
on (or near) the Earth's surface.PairLongitude(body1:Body, body2:Body, time:Time) → floatReturns one body's ecliptic longitude with respect to another, as seen from the Earth.This function determines where one body appears around the ecliptic plane
(the plane of the Earth's orbit around the Sun) as seen from the Earth,
relative to the another body's apparent position.
The function returns an angle in the half-open range [0, 360) degrees.
The value is the ecliptic longitude ofbody1relative to the ecliptic
longitude ofbody2.
The angle is 0 when the two bodies are at the same ecliptic longitude
as seen from the Earth. The angle increases in the prograde direction
(the direction that the planets orbit the Sun and the Moon orbits the Earth).
When the angle is 180 degrees, it means the two bodies appear on opposite sides
of the sky for an Earthly observer.
Neitherbody1norbody2is allowed to beBody.Earth.
If this happens, the function throws an exception.TypeParameterDescriptionBodybody1The first body, whose longitude is to be found relative to the second body.Bodybody2The second body, relative to which the longitude of the first body is to be found.TimetimeThe date and time of the observation.Returns:floatAn angle in degrees in the range [0, 360).Pivot(rotation:RotationMatrix, axis: int, angle: float) →RotationMatrixRe-orients a rotation matrix by pivoting it by an angle around one of its axes.Given a rotation matrix, a selected coordinate axis, and an angle in degrees,
this function pivots the rotation matrix by that angle around that coordinate axis.
For example, if you have rotation matrix that converts ecliptic coordinates (ECL)
to horizontal coordinates (HOR), but you really want to convert ECL to the orientation
of a telescope camera pointed at a given body, you can usePivottwice:
(1) pivot around the zenith axis by the body's azimuth, then (2) pivot around the
western axis by the body's altitude angle. The resulting rotation matrix will then
reorient ECL coordinates to the orientation of your telescope camera.TypeParameterDescriptionRotationMatrixrotationThe input rotation matrix.intaxisAn integer that selects which coordinate axis to rotate around: 0 = x, 1 = y, 2 = z. Any other value will cause an exception.floatangleAn 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 keepinganglein the range [-360, +360].Returns:RotationMatrixA pivoted matrix object.PlanetOrbitalPeriod(body:Body) → floatReturns the average number of days it takes for a planet to orbit the Sun.TypeParameterDescriptionBodybodyOne of the planets: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, or Pluto.Returns:floatThe mean orbital period of the body in days.RefractionAngle(refraction:Refraction, altitude: float) → floatCalculates the amount of "lift" to an altitude angle caused by atmospheric refraction.Given an altitude angle and a refraction option, calculates
the amount of "lift" caused by atmospheric refraction.
This is the number of degrees higher in the sky an object appears
due to lensing of the Earth's atmosphere.
This function works best near sea level.
To correct for higher elevations, callAtmospherefor that
elevation and multiply the refraction angle by the resulting relative density.TypeParameterDescriptionRefractionrefractionThe option for selecting whether to correct for atmospheric lensing. IfRefraction.Normal, a well-behaved refraction model is used. IfRefraction.Airless, no refraction correct is performed.Refraction.JplHorizonsis used only for compatibility testing with the JPL Horizons online tool. Any other value raises an exception.floataltitudeThe number of degrees above (positive) or below (negative) the horizon an object is, before being corrected for refraction.Returns:floatThe number of additional degrees of altitude an object appears
to have, due to atmospheric refraction, depending on the
option selected by therefractionparameter.RotateState(rotation:RotationMatrix, state:StateVector) →StateVectorApplies a rotation to a state vector, yielding a rotated state vector.This function transforms a state vector in one orientation to a
state vector in another orientation. Both the position and velocity
vectors are rotated the same way.TypeParameterDescriptionRotationMatrixrotationA rotation matrix that specifies how the orientation of the vector is to be changed.StateVectorstateThe state vector whose orientation is to be changed.Returns:StateVectorA state vector in the orientation specified byrotation.RotateVector(rotation:RotationMatrix, vector:Vector) →VectorApplies a rotation to a vector, yielding a rotated vector.This function transforms a vector in one orientation to a vector
in another orientation.TypeParameterDescriptionRotationMatrixrotationA rotation matrix that specifies how the orientation of the vector is to be changed.VectorvectorThe vector whose orientation is to be changed.Returns:VectorA vector in the orientation specified byrotation.RotationAxis(body:Body, time:Time) →AxisInfoCalculates information about a body's rotation axis at a given time.Calculates the orientation of a body's rotation axis, along with
the rotation angle of its prime meridian, at a given moment in time.
This function uses formulas standardized by the IAU Working Group
on Cartographics and Rotational Elements 2015 report, as described
in the following document:https://astropedia.astrogeology.usgs.gov/download/Docs/WGCCRE/WGCCRE2015reprint.pdfSeeAxisInfofor more detailed information.TypeParameterDescriptionBodybodyOne 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.TimetimeThe time at which to calculate the body's rotation axis.Returns:AxisInfoThe body's north pole direction and angle of its prime meridian.Rotation_ECL_EQD(time:Time) →RotationMatrixCalculates a rotation matrix from J2000 mean ecliptic (ECL) to equatorial of-date (EQD).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: ECL = ecliptic system, using equator at J2000 epoch.
Target: EQD = equatorial system, using equator of date.TypeParameterDescriptionTimetimeThe date and time of the desired equator.Returns:RotationMatrixA rotation matrix that converts ECL to EQD.Rotation_ECL_EQJ() →RotationMatrixCalculates a rotation matrix from J2000 mean ecliptic (ECL) to J2000 mean equator (EQJ).This is one of the family of functions that returns a rotation matrix
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:RotationMatrixA rotation matrix that converts ECL to EQJ.Rotation_ECL_HOR(time:Time, observer:Observer) →RotationMatrixCalculates a rotation matrix from J2000 mean ecliptic (ECL) to horizontal (HOR).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: ECL = ecliptic system, using equator at J2000 epoch.
Target: HOR = horizontal system.
UseHorizonFromVectorto convert the return value
to a traditional altitude/azimuth pair.TypeParameterDescriptionTimetimeThe date and time of the desired horizontal orientation.ObserverobserverA location near the Earth's mean sea level that defines the observer's horizon.Returns:RotationMatrixA rotation matrix that converts ECL to HOR attimeand forobserver.
The components of the horizontal vector are:
x = north, y = west, z = zenith (straight up from the observer).
These components are chosen so that the "right-hand rule" works for the vector
and so that north represents the direction where azimuth = 0.Rotation_ECT_EQD(time:Time) →RotationMatrixCalculates a rotation matrix from true ecliptic of date (ECT) to equator of date (EQD).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: ECT = true ecliptic of date.
Target: EQD = equator of date.TypeParameterDescriptionTimetimeThe date and time of the ecliptic/equator conversion.Returns:RotationMatrixA rotation matrix that converts ECT to EQD.Rotation_ECT_EQJ(time:Time) →RotationMatrixCalculates a rotation matrix from true ecliptic of date (ECT) to J2000 mean equator (EQJ).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: ECT = ecliptic system, using true equinox of the specified date/time.
Target: EQJ = equatorial system, using equator at J2000 epoch.TypeParameterDescriptionTimetimeThe date and time at which the Earth's equator defines the target orientation.Returns:RotationMatrixA rotation matrix that converts ECT to EQJ attime.Rotation_EQD_ECL(time:Time) →RotationMatrixCalculates a rotation matrix from equatorial of-date (EQD) to J2000 mean ecliptic (ECL).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: EQD = equatorial system, using equator of date.
Target: ECL = ecliptic system, using equator at J2000 epoch.TypeParameterDescriptionTimetimeThe date and time of the source equator.Returns:RotationMatrixA rotation matrix that converts EQD to ECL.Rotation_EQD_ECT(time:Time) →RotationMatrixCalculates a rotation matrix from equator of date (EQD) to true ecliptic of date (ECT).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: EQD = equator of date.
Target: ECT = true ecliptic of date.TypeParameterDescriptionTimetimeThe date and time of the equator/ecliptic conversion.Returns:RotationMatrixA rotation matrix that converts EQD to ECT.Rotation_EQD_EQJ(time:Time) →RotationMatrixCalculates a rotation matrix from equatorial of-date (EQD) to J2000 mean equator (EQJ).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: EQD = equatorial system, using equator of the specified date/time.
Target: EQJ = equatorial system, using equator at J2000 epoch.TypeParameterDescriptionTimetimeThe date and time at which the Earth's equator defines the source orientation.Returns:RotationMatrixA rotation matrix that converts EQD attimeto EQJ.Rotation_EQD_HOR(time:Time, observer:Observer) →RotationMatrixCalculates a rotation matrix from equatorial of-date (EQD) to horizontal (HOR).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: EQD = equatorial system, using equator of the specified date/time.
Target: HOR = horizontal system.
UseHorizonFromVectorto convert the return value
to a traditional altitude/azimuth pair.TypeParameterDescriptionTimetimeThe date and time at which the Earth's equator applies.ObserverobserverA location near the Earth's mean sea level that defines the observer's location.Returns:RotationMatrixA rotation matrix that converts EQD to HOR attimeand forobserver.
The components of the horizontal vector are:
x = north, y = west, z = zenith (straight up from the observer).
These components are chosen so that the "right-hand rule" works for the vector
and so that north represents the direction where azimuth = 0.Rotation_EQJ_ECL() →RotationMatrixCalculates a rotation matrix from J2000 mean equator (EQJ) to J2000 mean ecliptic (ECL).This is one of the family of functions that returns a rotation matrix
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:RotationMatrixA rotation matrix that converts EQJ to ECL.Rotation_EQJ_ECT(time:Time) →RotationMatrixCalculates a rotation matrix from J2000 mean equator (EQJ) to true ecliptic of date (ECT).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: EQJ = equatorial system, using equator at J2000 epoch.
Target: ECT = ecliptic system, using true equinox of the specified date/time.TypeParameterDescriptionTimetimeThe date and time at which the Earth's equator defines the target orientation.Returns:RotationMatrixA rotation matrix that converts EQJ to ECT attime.Rotation_EQJ_EQD(time:Time) →RotationMatrixCalculates a rotation matrix from J2000 mean equator (EQJ) to equatorial of-date (EQD).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: EQJ = equatorial system, using equator at J2000 epoch.
Target: EQD = equatorial system, using equator of the specified date/time.TypeParameterDescriptionTimetimeThe date and time at which the Earth's equator defines the target orientation.Returns:RotationMatrixA rotation matrix that converts EQJ to EQD attime.Rotation_EQJ_GAL() →RotationMatrixCalculates a rotation matrix from J2000 mean equator (EQJ) to galactic (GAL).This is one of the family of functions that returns a rotation matrix
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:RotationMatrixA rotation matrix that converts EQJ to GAL.Rotation_EQJ_HOR(time:Time, observer:Observer) →RotationMatrixCalculates a rotation matrix from J2000 mean equator (EQJ) to horizontal (HOR).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: EQJ = equatorial system, using the equator at the J2000 epoch.
Target: HOR = horizontal system.
UseHorizonFromVectorto convert the return value to
a traditional altitude/azimuth pair.TypeParameterDescriptionTimetimeThe date and time of the desired horizontal orientation.ObserverobserverA location near the Earth's mean sea level that defines the observer's horizon.Returns:RotationMatrixA rotation matrix that converts EQJ to HOR attimeand forobserver.
The components of the horizontal vector are:
x = north, y = west, z = zenith (straight up from the observer).
These components are chosen so that the "right-hand rule" works for the vector
and so that north represents the direction where azimuth = 0.Rotation_GAL_EQJ() →RotationMatrixCalculates a rotation matrix from galactic (GAL) to J2000 mean equator (EQJ).This is one of the family of functions that returns a rotation matrix
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:RotationMatrixA rotation matrix that converts GAL to EQJ.Rotation_HOR_ECL(time:Time, observer:Observer) →RotationMatrixCalculates a rotation matrix from horizontal (HOR) to J2000 mean ecliptic (ECL).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: HOR = horizontal system.
Target: ECL = ecliptic system, using equator at J2000 epoch.TypeParameterDescriptionTimetimeThe date and time of the horizontal observation.ObserverobserverThe location of the horizontal observer.Returns:RotationMatrixA rotation matrix that converts HOR to ECL.Rotation_HOR_EQD(time:Time, observer:Observer) →RotationMatrixCalculates a rotation matrix from horizontal (HOR) to equatorial of-date (EQD).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: HOR = horizontal system (x=North, y=West, z=Zenith).
Target: EQD = equatorial system, using equator of the specified date/time.TypeParameterDescriptionTimetimeThe date and time at which the Earth's equator applies.ObserverobserverA location near the Earth's mean sea level that defines the observer's horizon.Returns:RotationMatrixA rotation matrix that converts HOR to EQD attimeand forobserver.Rotation_HOR_EQJ(time:Time, observer:Observer) →RotationMatrixCalculates a rotation matrix from horizontal (HOR) to J2000 equatorial (EQJ).This is one of the family of functions that returns a rotation matrix
for converting from one orientation to another.
Source: HOR = horizontal system (x=North, y=West, z=Zenith).
Target: EQJ = equatorial system, using equator at the J2000 epoch.TypeParameterDescriptionTimetimeThe date and time of the observation.ObserverobserverA location near the Earth's mean sea level that define's the observer's horizon.Returns:RotationMatrixA rotation matrix that converts HOR to EQJ attimeand forobserver.Search(func: Callable[[Any,Time], float], context: object, t1:Time, t2:Time, dt_tolerance_seconds: float) → Optional[Time]Searches for a time at which a function's value increases through zero.Certain astronomy calculations involve finding a time when an event occurs.
Often such events can be defined as the root of a function:
the time at which the function's value becomes zero.Searchfinds theascending rootof a function: the time at which
the function's value becomes zero while having a positive slope. That is, as time increases,
the function transitions from a negative value, through zero at a specific moment,
to a positive value later. The goal of the search is to find that specific moment.
The search function is specified by two parameters:funcandcontext.
Thefuncparameter is a function itself that accepts a time
and a context containing any other arguments needed to evaluate the function.
Thecontextparameter supplies that context for the given search.
As an example, a caller may wish to find the moment a celestial body reaches a certain
ecliptic longitude. In that case, the caller might create a type (class, tuple, whatever)
that contains aBodymember to specify the body and a numeric value to hold the target longitude.
A different function might use a completely different context type.
Every time it is called,funcreturns afloatvalue or it raises an exception.
Iffuncraises an exception, the search immediately fails and the exception is
propagated back to the caller.
Otherwise, the search proceeds until it either finds the ascending root or fails for some reason.
The search callsfuncrepeatedly to rapidly narrow in on any ascending
root within the time window specified byt1andt2. The search never
reports a solution outside this time window.Searchuses a combination of bisection and quadratic interpolation
to minimize the number of function calls. However, it is critical that the
supplied time window be small enough that there cannot be more than one root
(ascedning or descending) within it; otherwise the search can fail.
Beyond that, it helps to make the time window as small as possible, ideally
such that the function itself resembles a smooth parabolic curve within that window.
If an ascending root is not found, or more than one root
(ascending and/or descending) exists within the windowt1..t2,Searchwill returnNoneto indicate a normal search failure.
If the search does not converge within 20 iterations, it will raise
anErrorexception.TypeParameterDescriptionfunction(context, Time)funcA function that takes an arbitrary context parameter and aTimeparameter. Returns a float value.  See remarks above for more details.objectcontextAn arbitrary data structure needed to be passed to the functionfuncevery time it is called.floatt1The lower time bound of the search window. See remarks above for more details.floatt2The upper time bound of the search window. See remarks above for more details.floatdt_tolerance_secondsSpecifies 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:TimeorNoneIf the search is successful, returns a #Time object that is withindt_tolerance_secondsof 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 returnsNone.SearchAltitude(body:Body, observer:Observer, direction:Direction, startTime:Time, limitDays: float, altitude: float) → Optional[Time]Finds the next time the center of a body passes through a given altitude.Finds when the center of the given body ascends or descends through a given
altitude angle, as seen by an observer at the specified location on the Earth.
By using the appropriate combination ofdirectionandaltitudeparameters,
this function can be used to find when civil, nautical, or astronomical twilight
begins (dawn) or ends (dusk).
Civil dawn begins before sunrise when the Sun ascends through 6 degrees below
the horizon. To find civil dawn, passDirection.Risefordirectionand -6 foraltitude.
Civil dusk ends after sunset when the Sun descends through 6 degrees below the horizon.
To find civil dusk, passDirection.Setfordirectionand -6 foraltitude.
Nautical twilight is similar to civil twilight, only thealtitudevalue should be -12 degrees.
Astronomical twilight uses -18 degrees as thealtitudevalue.
By convention for twilight time calculations, the altitude is not corrected for
atmospheric refraction. This is because the target altitudes are below the horizon,
and refraction is not directly observable.SearchAltitudeis not intended to find rise/set times of a body for two reasons:
(1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers.
(2) Rise/set times are affected significantly by atmospheric refraction.
Therefore, it is better to useSearchRiseSetto find rise/set times, which
corrects for both of these considerations.SearchAltitudewill not work reliably for altitudes at or near the body's
maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude
angles, useSearchHourAngle.TypeParameterDescriptionBodybodyThe Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call toDefineStar.ObserverobserverThe location where observation takes place.DirectiondirectionEitherDirection.Riseto find an ascending altitude event orDirection.Setto find a descending altitude event.TimestartTimeThe date and time at which to start the search.floatlimitDaysLimits how many days to search for the body reaching the altitude angle, and defines the direction in time to search. WhenlimitDaysis positive, the search is performed into the future, afterstartTime. When negative, the search is performed into the past, beforestartTime. To limit the search to the same day, you can use a value of 1 day. In cases where you want to find the altitude event 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.floataltitudeThe 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:TimeorNoneIf the altitude event time is found within the specified time window,
this function returns that time. Otherwise, it returnsNone.SearchGlobalSolarEclipse(startTime:Time) →GlobalSolarEclipseInfoSearches for a solar eclipse visible anywhere on the Earth's surface.This function finds the first solar eclipse that occurs afterstartTime.
A solar eclipse may be partial, annular, or total.
SeeGlobalSolarEclipseInfofor more information.
To find a series of solar eclipses, call this function once,
then keep callingNextGlobalSolarEclipseas many times as desired,
passing in thepeakvalue returned from the previous call.TypeParameterDescriptionTimestartTimeThe date and time for starting the search for a solar eclipse.Returns:GlobalSolarEclipseInfoSearchHourAngle(body:Body, observer:Observer, hourAngle: float, startTime:Time, direction: int = 1) →HourAngleEventSearches for the time when the center of a body reaches a specified hour angle as seen by an observer on the Earth.Thehour angleof 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's center 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 bystartTime.
To find when a body culminates, pass 0 forhourAngle.
To find when a body reaches its lowest point in the sky, pass 12 forhourAngle.
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.TypeParameterDescriptionBodybodyThe Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call toDefineStar.ObserverobserverIndicates a location on or near the surface of the Earth where the observer is located.floathourAngleAn hour angle value in the range [0.0, 24.0) indicating the number of sidereal hours after the body's most recent culmination.TimestartTimeThe date and time at which to start the search.intdirectionThe direction in time to perform the search: a positive value searches forward in time, a negative value searches backward in time. The function throws an exception ifdirectionis zero.Returns:HourAngleEventSearchLocalSolarEclipse(startTime:Time, observer:Observer) →LocalSolarEclipseInfoSearches for a solar eclipse visible at a specific location on the Earth's surface.
This function finds the first solar eclipse that occurs afterstartTime.
A solar eclipse may be partial, annular, or total.
SeeLocalSolarEclipseInfofor more information.
To find a series of solar eclipses, call this function once,
then keep callingNextLocalSolarEclipseas many times as desired,
passing in thepeakvalue returned from the previous call.
IMPORTANT: An eclipse reported by this function might be partly or
completely invisible to the observer due to the time of day.
SeeLocalSolarEclipseInfofor more information about this topic.TypeParameterDescriptionTimestartTimeThe date and time for starting the search for a solar eclipse.ObserverobserverThe geographic location of the observer.Returns:LocalSolarEclipseInfoSearchLunarApsis(startTime:Time) →ApsisFinds the time of the first lunar apogee or perigee after the given time.Given a date and time to start the search instartTime, this function finds
the next date and time that the center of the Moon reaches the closest or
farthest point in its orbit with respect to the center of the Earth, whichever
comes first afterstartTime.  The return value (of typeApsis) also
contains an indicator of whether the event is apogee or perigee.
The closest point is calledperigeeand the farthest point is calledapogee.
The wordapsisrefers to either event.
To iterate through consecutive alternating perigee and apogee events,
callSearchLunarApsisonce, then use the return value to callNextLunarApsis.
After that, keep feeding the previous return value fromNextLunarApsisinto
another call ofNextLunarApsisas many times as desired.TypeParameterDescriptionTimestartTimeThe date and time at which to start searching for the next perigee or apogee.Returns:ApsisSearchLunarEclipse(startTime:Time) →LunarEclipseInfoSearches for a lunar eclipse.This function finds the first lunar eclipse that occurs afterstartTime.
A lunar eclipse may be penumbral, partial, or total.
SeeLunarEclipseInfofor more information.
To find a series of lunar eclipses, call this function once,
then keep callingNextLunarEclipseas many times as desired,
passing in thepeakvalue returned from the previous call.TypeParameterDescriptionTimestartTimeThe date and time for starting the search for a lunar eclipse.Returns:LunarEclipseInfoSearchMaxElongation(body:Body, startTime:Time) → Optional[ElongationEvent]Finds a date and time when Mercury or Venus reaches its maximum angle from the Sun as seen from the Earth.Mercury and Venus are are often difficult to observe because they are closer to the Sun than the Earth is.
Mercury especially is almost always impossible to see because it gets lost in the Sun's glare.
The best opportunities for spotting Mercury, and the best opportunities for viewing Venus through
a telescope without atmospheric interference, are when these planets reach maximum elongation.
These are events where the planets reach the maximum angle from the Sun as seen from the Earth.
This function solves for those times, reporting the next maximum elongation event's date and time,
the elongation value itself, the relative longitude with the Sun, and whether the planet is best
observed in the morning or evening. SeeElongationEventfor more details about the returned object.TypeParameterDescriptionBodybodyEitherBody.MercuryorBody.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), useSearchRelativeLongitudeto find the next opposition event.TimestartTimeThe 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:ElongationEventSearchMoonNode(startTime:Time) →NodeEventInfoSearches for a time when the Moon's center crosses through the ecliptic plane.Searches for the first ascending or descending node of the Moon afterstartTime.
An ascending node is when the Moon's center passes through the ecliptic plane
(the plane of the Earth's orbit around the Sun) from south to north.
A descending node is when the Moon's center passes through the ecliptic plane
from north to south. Nodes indicate possible times of solar or lunar eclipses,
if the Moon also happens to be in the correct phase (new or full, respectively).
CallSearchMoonNodeto find the first of a series of nodes.
Then callNextMoonNodeto find as many more consecutive nodes as desired.TypeParameterDescriptionTimestartTimeThe date and time for starting the search for an ascending or descending node of the Moon.Returns:NodeEventInfoSearchMoonPhase(targetLon: float, startTime:Time, limitDays: float) → Optional[Time]Searches for the time that the Moon reaches a specified phase.Lunar phases are conventionally defined in terms of the Moon's geocentric ecliptic
longitude with respect to the Sun's geocentric ecliptic longitude.
When the Moon and the Sun have the same longitude, that is defined as a new moon.
When their longitudes are 180 degrees apart, that is defined as a full moon.
This function searches for any value of the lunar phase expressed as an
angle in degrees in the range [0, 360).
If you want to iterate through lunar quarters (new moon, first quarter, full moon, third quarter)
it is much easier to call the functionsSearchMoonQuarterandNextMoonQuarter.
This function is useful for finding general phase angles outside those four quarters.TypeParameterDescriptionfloattargetLonThe 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.TimestartTimeThe beginning of the time window in which to search for the Moon reaching the specified phase.floatlimitDaysThe number of days away fromstartTimethat limits the time window for the search. If the value is negative, the search is performed into the past fromstartTime. Otherwise, the search is performed into the future fromstartTime.Returns:TimeorNoneSearchMoonQuarter(startTime:Time) →MoonQuarterFinds the first lunar quarter after the specified date and time.A lunar quarter is one of the following four lunar phase events:
new moon, first quarter, full moon, third quarter.
This function finds the lunar quarter that happens soonest
after the specified date and time.
To continue iterating through consecutive lunar quarters, call this function once,
followed by calls toNextMoonQuarteras many times as desired.TypeParameterDescriptionTimestartTimeThe date and time at which to start the search.Returns:MoonQuarterSearchPeakMagnitude(body:Body, startTime:Time) →IlluminationInfoSearches for the date and time Venus will next appear brightest as seen from the Earth.This function searches for the date and time Venus appears brightest as seen from the Earth.
Currently only Venus is supported for thebodyparameter, though this could change in the future.
Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see
from the Earth, so peak magnitude events have little practical value for that planet.
Planets other than Venus and Mercury reach peak magnitude at opposition, which can
be found usingSearchRelativeLongitude.
The Moon reaches peak magnitude at full moon, which can be found usingSearchMoonQuarterorSearchMoonPhase.
The Sun reaches peak magnitude at perihelion, which occurs each year in January.
However, the difference is minor and has little practical value.TypeParameterDescriptionBodybodyCurrently onlyBody.Venusis allowed. Any other value results in an exception. See remarks above for more details.TimestartTimeThe date and time to start searching for the next peak magnitude event.Returns:IlluminationInfoSearchPlanetApsis(body:Body, startTime:Time) →ApsisFinds the next planet perihelion or aphelion, after a given time.Given a date and time to start the search instartTime, this function finds the
next date and time that the center of the specified planet reaches the closest or farthest point
in its orbit with respect to the center of the Sun, whichever comes first afterstartTime.
The closest point is calledperihelionand the farthest point is calledaphelion.
The wordapsisrefers to either event.
To iterate through consecutive alternating perihelion and aphelion events,
callSearchPlanetApsisonce, then use the return value to callNextPlanetApsis.
After that, keep feeding the previous return value fromNextPlanetApsisinto another call ofNextPlanetApsisas many times as desired.TypeParameterDescriptionBodybodyThe planet for which to find the next perihelion/aphelion event. Not allowed to beBody.SunorBody.Moon.TimestartTimeThe date and time at which to start searching for the next perihelion or aphelion.Returns:ApsisSearchRelativeLongitude(body:Body, targetRelLon: float, startTime:Time) →TimeSearches for when the Earth and another planet are separated by a certain ecliptic longitude.Searches for the time when the Earth and another planet are separated by a specified angle
in ecliptic longitude, as seen from the Sun.
A relative longitude is the angle between two bodies measured in the plane of the
Earth's orbit (the ecliptic plane). The distance of the bodies above or below the ecliptic
plane is ignored. If you imagine the shadow of the body cast onto the ecliptic plane,
and the angle measured around that plane from one body to the other in the direction
the planets orbit the Sun, you will get an angle somewhere between 0 and 360 degrees.
This is the relative longitude.
Given a planet other than the Earth inbodyand a time to start the search instartTime,
this function searches for the next time that the relative longitude measured from the
planet to the Earth istargetRelLon.
Certain astronomical events are defined in terms of relative longitude between
the Earth and another planet:When the relative longitude is 0 degrees, it means both planets are in the same
direction from the Sun. For planets that orbit closer to the Sun (Mercury and Venus),
this is known asinferior conjunction, a time when the other planet becomes very
difficult to see because of being lost in the Sun's glare.
(The only exception is in the rare event of a transit, when we see the silhouette
of the planet passing between the Earth and the Sun.)When the relative longitude is 0 degrees and the other planet orbits farther from the Sun,
this is known asopposition. Opposition is when the planet is closest to the Earth,
and also when it is visible for most of the night, so it is considered the best time
to observe the planet.When the relative longitude is 180 degrees, it means the other planet is on the opposite
side of the Sun from the Earth.  This is calledsuperior conjunction.  Like inferior
conjunction, the planet is very difficult to see from the Earth.
Superior conjunction is possible for any planet other than the Earth.TypeParameterDescriptionBodybodyA planet other than the Earth. Ifbodyis not a planet, or if it isBody.Earth, an error occurs.floattargetRelLonThe desired relative longitude, expressed in degrees. Must be in the range [0, 360).TimestartTimeThe date and time at which to begin the search.Returns:TimeThe date and time of the relative longitude event.SearchRiseSet(body:Body, observer:Observer, direction:Direction, startTime:Time, limitDays: float, metersAboveGround: float = 0.0) → Optional[Time]Searches for the next time a celestial body rises or sets as seen by an observer on the Earth.This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth.
Rise time is when the body first starts to be visible above the horizon.
For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon.
Set time is the moment when the body appears to vanish below the horizon.
Therefore, this function adjusts for the apparent angular radius of the observed body
(significant only for the Sun and Moon).
This function corrects for typical atmospheric refraction, which causes celestial
bodies to appear higher above the horizon than they would if the Earth had no atmosphere.
It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon).
Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based
on air temperature, pressure, and humidity; such weather-based conditions are outside
the scope of Astronomy Engine.
Note that rise or set may not occur in every 24 hour period.
For example, near the Earth's poles, there are long periods of time where
the Sun stays below the horizon, never rising.
Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day.
This is because the Moon sets nearly an hour later each day due to orbiting the Earth a
significant amount during each rotation of the Earth.
Therefore callers must not assume that the function will always succeed.TypeParameterDescriptionBodybodyThe Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call toDefineStar.ObserverobserverThe location where observation takes place.DirectiondirectionEitherDirection.Riseto find a rise time orDirection.Setto find a set time.TimestartTimeThe date and time at which to start the search.floatlimitDaysLimits how many days to search for a rise or set time, and defines the direction in time to search. WhenlimitDaysis positive, the search is performed into the future, afterstartTime. When negative, the search is performed into the past, beforestartTime. 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.floatmetersAboveGroundDefault value = 0.0. Usually the observer is located at ground level. Then this parameter should be zero. But if the observer is significantly higher than ground level, for example in an airplane, this parameter should be a positive number indicating how far above the ground the observer is. An exception occurs ifmetersAboveGroundis negative.Returns:TimeorNoneIf the rise or set time is found within the specified time window,
this function returns that time. Otherwise, it returnsNone.SearchSunLongitude(targetLon: float, startTime:Time, limitDays: float) → Optional[Time]Searches for the time when the Sun reaches an apparent ecliptic longitude as seen from the Earth.This function finds the moment in time, if any exists in the given time window,
that the center of the Sun reaches a specific ecliptic longitude as seen from the center of the Earth.
This function can be used to determine equinoxes and solstices.
However, it is usually more convenient and efficient to callSeasonsto calculate all equinoxes and solstices for a given calendar year.
The function searches the window of time specified bystartTimeandstartTime+limitDays.
The search will returnNoneif the Sun never reaches the longitudetargetLonor
if the window is so large that the longitude ranges more than 180 degrees within it.
It is recommended to keep the window smaller than 10 days when possible.TypeParameterDescriptionfloattargetLonThe desired ecliptic longitude in degrees, relative to the true equinox of date. This may be any value in the range [0, 360), although certain values have conventional meanings: 0 = March equinox, 90 = June solstice, 180 = September equinox, 270 = December solstice.TimestartTimeThe date and time for starting the search for the desired longitude event.floatlimitDaysThe real-valued number of days, which when added tostartTime, 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:TimeorNoneSearchTransit(body:Body, startTime:Time) →TransitInfoSearches for the first transit of Mercury or Venus after a given date.Finds the first transit of Mercury or Venus after a specified date.
A transit is when an inferior planet passes between the Sun and the Earth
so that the silhouette of the planet is visible against the Sun in the background.
To continue the search, pass thefinishtime in the returned structure toNextTransit.TypeParameterDescriptionBodybodyThe planet whose transit is to be found. Must beBody.MercuryorBody.Venus.TimestartTimeThe date and time for starting the search for a transit.Returns:TransitInfoSeasons(year: int) →SeasonInfoFinds both equinoxes and both solstices for a given calendar year.The changes of seasons are defined by solstices and equinoxes.
Given a calendar year number, this function calculates the
March and September equinoxes and the June and December solstices.
The equinoxes are the moments twice each year when the plane of the
Earth's equator passes through the center of the Sun. In other words,
the Sun's declination is zero at both equinoxes.
The March equinox defines the beginning of spring in the northern hemisphere
and the beginning of autumn in the southern hemisphere.
The September equinox defines the beginning of autumn in the northern hemisphere
and the beginning of spring in the southern hemisphere.
The solstices are the moments twice each year when one of the Earth's poles
is most tilted toward the Sun. More precisely, the Sun's declination reaches
its minimum value at the December solstice, which defines the beginning of
winter in the northern hemisphere and the beginning of summer in the southern
hemisphere. The Sun's declination reaches its maximum value at the June solstice,
which defines the beginning of summer in the northern hemisphere and the beginning
of winter in the southern hemisphere.TypeParameterDescriptionintyearThe 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:SeasonInfoSiderealTime(time:Time) → floatCalculates Greenwich Apparent Sidereal Time (GAST).Given a date and time, this function calculates the rotation of the
Earth, represented by the equatorial angle of the Greenwich prime meridian
with respect to distant stars (not the Sun, which moves relative to background
stars by almost one degree per day).
This angle is called Greenwich Apparent Sidereal Time (GAST).
GAST is measured in sidereal hours in the half-open range [0, 24).
When GAST = 0, it means the prime meridian is aligned with the of-date equinox,
corrected at that time for precession and nutation of the Earth's axis.
In this context, the "equinox" is the direction in space where the Earth's
orbital plane (the ecliptic) intersects with the plane of the Earth's equator,
at the location on the Earth's orbit of the (seasonal) March equinox.
As the Earth rotates, GAST increases from 0 up to 24 sidereal hours,
then starts over at 0.
To convert to degrees, multiply the return value by 15.TypeParameterDescriptionTimetimeThe date and time for which to find GAST. As an optimization, this function caches the sidereal time value intime, unless it has already been cached, in which case the cached value is reused.Returns:floatGAST expressed in sidereal hours.SphereFromVector(vector:Vector) →SphericalConverts Cartesian coordinates to spherical coordinates.Given a Cartesian vector, returns latitude, longitude, and distance.TypeParameterDescriptionVectorvectorCartesian vector to be converted to spherical coordinates.Returns:SphericalSpherical coordinates that are equivalent to the given vector.SunPosition(time:Time) →EclipticCoordinatesCalculates geocentric ecliptic coordinates for the Sun.This function calculates the position of the Sun as seen from the Earth.
The returned value includes both Cartesian and spherical coordinates.
The x-coordinate and longitude values in the returned object are based
on thetrue equinox of date: one of two points in the sky where the instantaneous
plane of the Earth's equator at the given date and time (theequatorial plane)
intersects with the plane of the Earth's orbit around the Sun (theecliptic plane).
By convention, the apparent location of the Sun at the March equinox is chosen
as the longitude origin and x-axis direction, instead of the one for September.SunPositioncorrects for precession and nutation of the Earth's axis
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 functionSeasonsdoes use this function for that purpose.TypeParameterDescriptionTimetimeThe date and time for which to calculate the Sun's position.Returns:EclipticCoordinatesThe ecliptic coordinates of the Sun using the Earth's true equator of date.VectorFromHorizon(sphere:Spherical, time:Time, refraction:Refraction) →VectorGiven apparent angular horizontal coordinates insphere, calculate horizontal vector.TypeParameterDescriptionSphericalsphereA structure that contains apparent horizontal coordinates:latholds the refracted altitude angle,lonholds the azimuth in degrees clockwise from north, anddistholds the distance from the observer to the object in AU.TimetimeThe 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.RefractionrefractionSee remarks in functionRefractionAngle.Returns:VectorA vector in the horizontal system:x= north,y= west, andz= zenith (up).VectorFromSphere(sphere:Spherical, time:Time) →VectorConverts spherical coordinates to Cartesian coordinates.Given spherical coordinates and a time at which they are valid,
returns a vector of Cartesian coordinates. The returned value
includes the time, as required by allTimeobjects.TypeParameterDescriptionSphericalsphereSpherical coordinates to be converted.TimetimeThe time that should be included in the returned vector.Returns:VectorThe vector form of the supplied spherical coordinates.VectorObserver(vector:Vector, ofdate: bool) →ObserverCalculates the geographic location corresponding to an equatorial vector.This is the inverse function ofObserverVector.
Given a geocentric equatorial vector, it returns the geographic
latitude, longitude, and elevation for that vector.TypeParameterDescriptionVectorvectorThe geocentric equatorial position vector for which to find geographic coordinates. The components are expressed in astronomical units (AU). The timevector.tdetermines the Earth's rotation.boolofdateSelects the date of the Earth's equator in whichvectoris expressed. The caller may passFalseto 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 timevector.t. Or the caller may passTrueto use the Earth's equator atvector.tas the orientation.Returns:ObserverThe geographic latitude, longitude, and elevation above sea level
that corresponds to the given equatorial vector.