hevelius_ephemeris library

Hevelius – an ephemeris engine in pure Dart.

Positions of solar system bodies come from NASA JPL ephemerides; all calculation code is written from scratch from published scientific sources (see SOURCES.md).

Classes

Angles
Ascendant and MC – intersections of the ecliptic with the horizon and the meridian.
CalendarDateTime
A date and time in a specific calendar.
CombinedEphemeris
Several ephemeris sources together, e.g. a compact file for the planets and an SPK file with small bodies. Each body is taken from the first source in sources that covers it.
Corrections
Which corrections to apply when computing a position.
EclipticPosition
A position on the ecliptic of date as seen from the Earth's centre.
Ephemeris
A source of positions and velocities of solar system bodies: JPL SPK files (SpkEphemeris) or any other implementation, e.g. a compact format. All calculations of the engine take an Ephemeris.
EquatorialPosition
Apparent geocentric position on the true equator and equinox of date.
FixedStar
A star (or another object outside the solar system) from a catalogue: ICRS position at epoch J2000.0 and space motion.
HorizonEvent
A rising, setting or meridian transit.
HorizontalPosition
Position of a body in the sky of an Observer.
Ingress
An entry of a body into a zodiac sign.
LocalLunarEclipse
A lunar eclipse as seen from one place: the Moon's position at each contact and at greatest eclipse. The times are those of the LunarEclipse – the same for the whole Earth.
LocalSolarEclipse
Local circumstances of a solar eclipse: how it looks from one place.
LongitudeCrossing
A moment when a longitude reaches one of the searched values.
LunarEclipse
A lunar eclipse.
LunarEclipseContact
The Moon at one moment of a lunar eclipse as seen from a place.
LunarPhase
A moment of a principal lunar phase.
Naif
NAIF codes of the bodies in JPL planetary ephemerides.
Observer
A place on the Earth: geodetic latitude and longitude (degrees, north and east positive) and height above sea level in metres.
SolarEclipse
A solar eclipse, seen from the Earth as a whole.
SolarEclipseContact
The Sun at one moment of a solar eclipse as seen from a place.
SpkEphemeris
Body positions from one or more SPK files.
SpkFile
An ephemeris file in SPK format (e.g. de440s.bsp from NASA JPL).
SpkSegment
A segment of an SPK file: motion of target relative to center over the time span startEt…endEt.
SpkSource
Source of SPK file bytes: the whole file in memory (SpkFile.fromBytes) or on-demand reads from disk (openSpkFile in spk_io.dart).
SpkType2Segment
An SPK type 2 segment for writing: motion of target relative to center as Chebyshev polynomials for position.
StateVector
Position (km) and velocity (km/s) of a body in rectangular coordinates.
Station
A station: the moment when a body turns retrograde or direct.
Vector3
A vector in three-dimensional space.

Enums

Calendar
The calendar a date is expressed in.
HorizonEventKind
What happens at a HorizonEvent.
LunarEclipseType
Kind of a lunar eclipse.
LunarPoint
Points of the lunar orbit used in astrology.
MoonPhase
The principal phases of the Moon.
Season
The equinoxes and solstices.
ShadowEnlargement
How the Earth's shadow is enlarged for the atmosphere in lunar eclipse calculations.
SolarEclipseType
Kind of a solar eclipse.
Twilight
Twilight: the Sun's centre at a given altitude below the horizon.

Constants

arcsecond → const double
One arcsecond in radians.
astronomicalUnit → const double
The astronomical unit in km (IAU 2012 Resolution B2).
daysPerJulianCentury → const double
Days in a Julian century; many formulas take time in centuries since j2000.
daysPerJulianYear → const double
The Julian year in days.
earthEquatorialRadius → const double
Equatorial radius of the Earth in km (IERS Conventions 2010, table 1.1), for the Moon's horizontal parallax.
earthFlattening → const double
Flattening of the Earth (IERS Conventions 2010, table 1.1).
earthMoonGM → const double
Gravitational parameter of the Earth–Moon system G(M⊕ + M☾) in km³/s².
gregorianReformJulianDay → const double
Julian day of 15 October 1582, 0:00 – the first day of the Gregorian calendar. Earlier moments use the Julian calendar by default.
j2000 → const double
The J2000.0 epoch as a Julian day: 1 January 2000, 12:00 TT.
meanLunarInclination → const double
Mean inclination of the lunar orbit to the ecliptic, in degrees.
moonRadius → const double
Mean radius of the Moon in km (IAU 2015).
moonRadiusRatio → const double
Ratio of the Moon's radius to the Earth's equatorial radius used for the penumbral cone of solar eclipses (k = 0.2725076, IAU 1982).
moonRadiusRatioUmbra → const double
Smaller ratio used for the umbral cone of solar eclipses (k = 0.2722810), which allows for the valleys on the lunar limb.
solarGM → const double
Solar gravitational parameter GM in km³/s² (IAU 2015 Resolution B3).
solarRadius → const double
Nominal solar radius in km (IAU 2015 Resolution B3).
speedOfLight → const double
Speed of light in km/s (SI definition).
starHorizonAltitude → const double
Standard altitude of the centre of a star or planet at rising and setting in degrees: refraction 34′.
sunHorizonAltitude → const double
Standard altitude of the Sun's centre at sunrise and sunset in degrees: refraction 34′ plus semidiameter 16′.

Functions

aberrate(Vector3 u, Vector3 v) → Vector3
Relativistic aberration: direction u as seen by an observer moving with velocity v (in units of c).
altitude(Ephemeris ephemeris, int target, double latitude, double longitude, double jdTT) → double
Geometric altitude (no refraction) of body target above the horizon of a place at latitude and geographic longitude (degrees, east positive) at jdTT, in degrees, as seen from the Earth's centre.
angles(double jdUt, double latitude, double longitude, {double? deltaTSeconds}) → Angles
Ascendant and MC at jdUt (Julian day in UT) for a place at latitude and geographic longitude (degrees, east positive).
anglesFromArmc(double armc, double latitude, double obliquity) → Angles
Ascendant and MC for sidereal time armc (right ascension of the meridian), latitude and ecliptic obliquity – all in degrees.
bodyLongitude(Ephemeris ephemeris, int naif) → LongitudeFunction
Apparent geocentric ecliptic longitude of body naif (NAIF code) as a LongitudeFunction, for use with longitudeCrossings, ingresses and stations.
calendarDateTime(double jd, {Calendar? calendar}) → CalendarDateTime
The date and time of the Julian day jd.
centuriesSinceJ2000(double jd) → double
Julian centuries since J2000 for Julian day jd – the time argument t of the precession and nutation functions (IAU 2006 precession, IAU 2000A nutation with R06 adjustments, IERS Conventions 2010, chapter 5). Pass a TT Julian day.
chebyshevBasis(double s, int n) → List<double>
Values T₀(s)…Tₙ₋₁(s) of the Chebyshev polynomials.
daysInMonth(int year, int month, Calendar calendar) → int
Number of days in month of year in calendar.
deflectLight(Vector3 u, Vector3 sunToBody, Vector3 sunToEarth) → Vector3
Deflection of light by the Sun (general relativity).
delaunayArguments(double t) → ({double d, double f, double l, double lPrime, double omega})
Delaunay arguments (radians, not reduced to 0–2π), eq. 5.43: l – mean anomaly of the Moon, l′ – mean anomaly of the Sun, F = L − Ω, D – mean elongation of the Moon from the Sun, Ω – mean longitude of the Moon's ascending node (mean equinox of date).
deltaT(double jdUt) → double
ΔT = TT − UT in seconds at jdUt (Julian day in UT).
earthRotationAngle(double jdUt) → double
Earth rotation angle θ (radians, 0 ≤ θ < 2π) for jdUt – a Julian day in UT1, IERS Conventions (2010), chapter 5 (table 5.2e): θ = 2π·(0.7790572732640 + 1.00273781191135448·Tu), Tu = JD(UT1) − 2451545.0.
eclipticOfDate(Vector3 direction, double distance, double jdTT, {Corrections corrections = const Corrections()}) → EclipticPosition
Direction direction in the GCRS/ICRF frame as a position on the ecliptic of date jdTT (with nutation unless corrections turns it off).
equationOfEquinoxesComplementaryTerms(double t) → double
Complementary terms of the equation of the equinoxes (radians): the non-polynomial part of Greenwich sidereal time beyond Δψ·cos ε_A, IERS Conventions (2010), table 5.2e. Together below 0.003″.
equatorialOfDate(Ephemeris ephemeris, int target, double jdTT) → EquatorialPosition
Apparent geocentric right ascension and declination of body target (NAIF code) on the true equator and equinox of date at jdTT.
equatorialToHorizontal(double rightAscension, double declination, Observer observer, double jdTT, {bool withRefraction = false, double pressure = 1010, double temperature = 10, double? deltaTSeconds}) → HorizontalPosition
Horizontal coordinates of a direction given by apparent right ascension and declination of date (rightAscension, declination, degrees; true equator and equinox of date) for observer at jdTT. No parallax – for stars, galaxies and other distant objects.
evaluateChebyshev(List<double> c, double s) → double
Value of the Chebyshev polynomial with coefficients c at s.
fitChebyshev(List<double> points, List<double> values, int degree) → List<double>
Coefficients c₀…cₙ of the Chebyshev polynomial of degree that best approximates (least squares) values at points in the interval −1 ≤ s ≤ 1.
fixedStarDirection(Ephemeris ephemeris, FixedStar star, double jdTT, {Corrections corrections = const Corrections()}) → ({Vector3 direction, double distance})
Geocentric direction (unit vector, GCRS/ICRF) to star at jdTT and its distance in km (infinite for zero parallax).
fixedStarEcliptic(Ephemeris ephemeris, FixedStar star, double jdTT, {Corrections corrections = const Corrections()}) → EclipticPosition
Position of star on the ecliptic of date jdTT as seen from the Earth's centre (apparent, like planets in geocentricEcliptic).
fixedStarHorizontal(Ephemeris ephemeris, FixedStar star, Observer observer, double jdTT, {bool withRefraction = false, double pressure = 1010, double temperature = 10, double? deltaTSeconds}) → HorizontalPosition
Horizontal coordinates of star for observer at jdTT (apparent place as in fixedStarEcliptic: space motion, annual parallax, light deflection, aberration, precession and nutation).
fukushimaWilliams(double t) → ({double gamma, double phi, double psi})
Fukushima–Williams angles (radians), eq. 5.40: γ̄, φ̄, ψ̄.
gcrsToEclipticOfDate(Vector3 r, double t, {required double nutationInLongitude}) → Vector3
Transforms vector r from the GCRS (ICRF) to the ecliptic and equinox of date.
gcrsToEclipticOfDateIau2006(Vector3 r, double t, {required double nutationInLongitude}) → Vector3
As gcrsToEclipticOfDate, with the IAU 2006 precession: the matrix R₁(−ε)·R₃(−ψ)·R₁(φ̄)·R₃(γ̄) of the IERS Conventions, section 5.4.5, without the final rotation R₁(−ε) (to the equator). Accurate only within about ±1000 years of J2000.
geocentricDirection(Ephemeris ephemeris, int target, double jdTT, {Corrections corrections = const Corrections()}) → ({Vector3 direction, double distance})
Direction (unit vector in the GCRS/ICRF frame) and distance (km) from the Earth's centre to body target at jdTT, with corrections applied (except nutation, which only affects the rotation to the frame of date).
geocentricEcliptic(Ephemeris ephemeris, int target, double jdTT, {Corrections corrections = const Corrections()}) → EclipticPosition
Geocentric position of body target (NAIF code) on the ecliptic of date at jdTT (Julian day in Terrestrial Time).
greenwichApparentSiderealTime(double jdUt, {double? deltaTSeconds}) → double
Greenwich apparent sidereal time (radians, 0 ≤ GAST < 2π) for jdUt: GMST plus the equation of the equinoxes Δψ·cos ε_A and its complementary terms (IERS Conventions 2010, table 5.2e). deltaTSeconds overrides the ΔT model.
greenwichMeanSiderealTime(double jdUt, double jdTT) → double
Greenwich mean sidereal time (radians, 0 ≤ GMST < 2π): the Earth rotation angle θ for jdUt plus the angle from the CIO to the mean equinox of date at jdTT, from the long-term precession model (Vondrák, Capitaine and Wallace 2011; see longTermGmstMinusEra).
greenwichMeanSiderealTimeIau2006(double jdUt, double jdTT) → double
Greenwich mean sidereal time (radians, 0 ≤ GMST < 2π), IERS Conventions (2010), table 5.2e: θ plus the IAU 2006 precession polynomial in time jdTT. Accurate only within about ±1000 years of J2000.
horizonEvents(Ephemeris ephemeris, int target, double latitude, double longitude, double startJdTT, double endJdTT, {double? horizonAltitude}) → List<HorizonEvent>
Risings, settings and meridian transits of body target for a place at latitude and geographic longitude (degrees, east positive) in startJdTT … endJdTT, in time order.
horizontalPosition(Ephemeris ephemeris, int target, Observer observer, double jdTT, {bool withRefraction = false, double pressure = 1010, double temperature = 10, double? deltaTSeconds}) → HorizontalPosition
Horizontal coordinates of body target (NAIF code: Sun, Moon, planets, or a small body from an added file) for observer at jdTT.
ingresses(LongitudeFunction longitudeAt, double startJdTT, double endJdTT, {double step = 1}) → List<Ingress>
Entries of longitudeAt into zodiac signs in startJdTT … endJdTT, including re-entries during retrograde motion. See longitudeCrossings for step.
julianDay(int year, int month, int day, {int hour = 0, int minute = 0, double second = 0, Calendar? calendar}) → double
Julian day for the date year-month-day and time in calendar.
julianDayTT(double jdUt, {double? deltaTSeconds}) → double
Julian day in Terrestrial Time (TT) for jdUt.
julianDayUT(double jdTT, {double? deltaTSeconds}) → double
Julian day in UT for jdTT; the inverse of julianDayTT.
localLunarEclipse(Ephemeris ephemeris, LunarEclipse eclipse, {required double latitude, required double longitude, double height = 0, double? deltaTSeconds}) → LocalLunarEclipse
The Moon's position at each contact of lunar eclipse eclipse for a place at geodetic latitude and longitude (degrees, east positive) and height above sea level in metres. deltaTSeconds overrides the ΔT model.
localSolarEclipse(Ephemeris ephemeris, SolarEclipse eclipse, {required double latitude, required double longitude, double height = 0, double? deltaTSeconds}) → LocalSolarEclipse?
Local circumstances of solar eclipse eclipse for a place at geodetic latitude and longitude (degrees, east positive) and height above sea level in metres; null if the eclipse is not seen there at all (the penumbra misses the place).
longitudeCrossings(LongitudeFunction longitudeAt, double startJdTT, double endJdTT, {required double period, double offset = 0, double step = 1}) → List<LongitudeCrossing>
All moments in startJdTT … endJdTT when longitudeAt reaches offset + k·period degrees for any integer k, in time order.
longitudeSpeed(double longitudeAt(double jdTT), double jdTT, {double step = 0.005}) → double
Rate of change of ecliptic longitude in degrees per day.
longTermCioLocator(double t) → double
CIO locator s_A due to precession at t (radians), equation (26) of the long-term model.
longTermEclipticPole(double t) → Vector3
Pole of the mean ecliptic of date at t (Julian centuries TT since J2000) as a unit vector in the J2000 mean equator and equinox frame; long-term model valid for ±200 000 years (Vondrák, Capitaine and Wallace 2011).
longTermEclipticPoleAngles(double t) → (double, double)
P_A i Q_A (radiany), równ. (8).
longTermEquatorPole(double t) → Vector3
Pole of the mean equator of date at t as a unit vector in the J2000 mean equator and equinox frame (long-term model, as longTermEclipticPole).
longTermEquatorPoleAngles(double t) → (double, double)
X_A i Y_A (radiany), równ. (9).
longTermGcrsToMeanEclipticOfDate(Vector3 r, double t) → Vector3
Transforms vector r from the GCRS to the mean ecliptic and equinox of date at t, with the long-term precession model.
longTermGmstMinusEra(double t) → double
Greenwich mean sidereal time minus the Earth rotation angle at t (radians): the angle from the CIO to the mean equinox of date along the equator, from the long-term precession model.
longTermMeanEclipticOfDateToGcrs(Vector3 v, double t) → Vector3
Inverse of longTermGcrsToMeanEclipticOfDate: vector v in the mean ecliptic and equinox of date at t back to the GCRS.
longTermMeanObliquity(double t) → double
Mean obliquity of the ecliptic of date (radians): the angle between the long-term mean equator and ecliptic poles.
lunarEclipses(Ephemeris ephemeris, double startJdTT, double endJdTT, {ShadowEnlargement enlargement = ShadowEnlargement.danjon}) → List<LunarEclipse>
Lunar eclipses with greatest eclipse in startJdTT … endJdTT, penumbral ones included.
lunarElongation(Ephemeris ephemeris) → LongitudeFunction
Elongation of the Moon from the Sun in ecliptic longitude: the apparent geocentric longitude of the Moon minus that of the Sun, in degrees (0 ≤ x < 360) – 0° at New Moon, 180° at Full Moon.
lunarPhases(Ephemeris ephemeris, double startJdTT, double endJdTT) → List<LunarPhase>
New Moons, First Quarters, Full Moons and Last Quarters in startJdTT … endJdTT, in time order: the moments when the excess of the apparent geocentric longitude of the Moon over that of the Sun is 0°, 90°, 180° and 270°.
lunarPoint(Ephemeris ephemeris, LunarPoint point, double jdTT) → EclipticPosition
Position of point on the true ecliptic and equinox of date at jdTT.
meanObliquity(double t) → double
Mean obliquity of the ecliptic of date ε_A (radians), from the long-term precession model (Vondrák, Capitaine and Wallace 2011): the angle between the mean equator and ecliptic poles of date.
meanObliquityIau2006(double t) → double
Mean obliquity of the ecliptic of date ε_A (radians) of the IAU 2006 precession, IERS Conventions (2010) eq. 5.40 – accurate only within about ±1000 years of J2000.
nutation(double t) → ({double longitude, double obliquity})
Nutation in longitude Δψ and in obliquity Δε (radians), tables 5.3a and 5.3b.
onSolarDisk(Vector3 direction, Vector3 sunFromEarth) → bool
Whether direction (from the Earth's centre) falls on the disk of the Sun seen in direction sunFromEarth.
refraction(double altitude, {double pressure = 1010, double temperature = 10}) → double
Atmospheric refraction in degrees for the geometric (airless) altitude altitude in degrees: Sæmundsson's formula (J. Meeus, Astronomical Algorithms, eq. 16.4, made exactly zero at the zenith), scaled for air pressure (millibars) and temperature (°C).
seasons(Ephemeris ephemeris, int year) → Map<Season, double>
The equinoxes and solstices of year (calendar year as in julianDay), as Julian days in Terrestrial Time: the moments when the apparent geocentric longitude of the Sun is 0°, 90°, 180° and 270°.
solarEclipses(Ephemeris ephemeris, double startJdTT, double endJdTT) → List<SolarEclipse>
Solar eclipses with greatest eclipse in startJdTT … endJdTT.
stations(LongitudeFunction longitudeAt, double startJdTT, double endJdTT, {double step = 1}) → List<Station>
Stations of longitudeAt in startJdTT … endJdTT: moments when the speed in longitude changes sign. See longitudeCrossings for step.
tdbMinusTT(double jdTT) → double
Approximate TDB − TT in seconds for jdTT.
trueObliquity(double t) → double
True obliquity of the ecliptic of date ε = ε_A + Δε (radians).
twilights(Ephemeris ephemeris, Twilight twilight, double latitude, double longitude, double startJdTT, double endJdTT) → List<HorizonEvent>
Dawns and dusks of twilight for a place at latitude and longitude in startJdTT … endJdTT: moments when the centre of the Sun is at Twilight.altitude. Dawn is a HorizonEventKind.rise, dusk a HorizonEventKind.set; transits of the Sun are left out.
writeSpk(String internalName, List<SpkType2Segment> segments) → Uint8List
Writes an SPK file (DAF format, little-endian) with segments in the J2000/ICRF frame.

Typedefs

LongitudeFunction = double Function(double jdTT)
A function giving an ecliptic longitude in degrees for a Julian day in Terrestrial Time.