Features
Everything from the calendar to the horizon.
The open-source core covers time, positions and events – the foundation for astronomy apps, planetariums, almanacs, calendars and research tools.
Time scales
Julian day ↔ Julian and Gregorian calendars, ΔT from −720 to today (extrapolated beyond), UT, TT and TDB.
Apparent positions
Sun, Moon, planets and Pluto; Chiron and the first four asteroids. Light-time, light deflection, relativistic aberration, IAU 2000A nutation.
Long-term precession
The Vondrák–Capitaine–Wallace model, valid for ±200 000 years – and within 0.02″ of IAU 2006 in modern times.
Lunar points
Mean and true node, mean and osculating apogee; speeds in longitude and retrograde motion.
Events
Sign ingresses, stations, equinoxes and solstices, lunar phases, risings, settings, transits and twilight.
Eclipses
Global solar and lunar eclipses, local circumstances of solar eclipses, contacts of lunar eclipses and their visibility.
Horizontal coordinates
Topocentric altitude and azimuth for any place – with parallax and optional refraction. Ready for sky maps.
Fixed stars
Proper motion, annual parallax, deflection and aberration; 22 bright stars included, any catalogue position supported.
JPL SPK files
Reader and writer for NASA JPL binary ephemerides – DE440, DE441 (−13 200 … +17 191) and DE442.
Accuracy
Verified against the references.
Every result is tested against an independent source. The full list of formulas, constants and comparisons is published with the package.
| Compared with | What | Agreement |
|---|---|---|
| JPL test files (testpo.440, .441, .442) | Reading of DE440, DE441 and DE442 – over 320 000 official values | ≤ 4.3 mm |
| JPL Horizons | Apparent geocentric positions | < 0.01″ |
| JPL Horizons | Topocentric altitude and azimuth, with and without refraction | ≤ 0.7″ |
| NASA eclipse canon (Espenak & Meeus) | All solar and lunar eclipses 2021–2030: type, magnitude, time of greatest eclipse | ≤ 1.5 s |
| NASA Besselian elements and lunar eclipse plots | Contacts of solar and lunar eclipses | ≤ 3.3 s |
| J. Meeus, Astronomical Algorithms | Worked examples: sidereal time, rising and setting of Venus, new moon | ≤ 0.6 s |
The figures describe the calculation itself. The ephemerides have their own uncertainties, and for dates long before the telescopic era the uncertainty of ΔT – the irregular rotation of the Earth – dominates.
Get started
Three steps.
- Add the package –
dart pub add hevelius_ephemeris(available after the first release). - Download the JPL files – the ephemerides are published by NASA JPL and are not bundled; a small tool fetches them and checks their SHA-256 sums.
- Compute – positions, events and eclipses with plain function calls; times in Julian days, angles in degrees.
// Sign ingresses of the Sun in 2027. final list = ingresses( bodyLongitude(ephemeris, Naif.sun), julianDay(2027, 1, 1), julianDay(2028, 1, 1), ); for (final i in list) print(i);
Data sources & acknowledgements
Built on the work of others – and saying so.
All calculation code is written from scratch from published scientific sources, cited formula by formula. No code from Swiss Ephemeris, SOFA or ERFA is used.
- NASA JPL planetary and lunar ephemeridesR. S. Park, W. M. Folkner, J. G. Williams, D. H. Boggs, “The JPL Planetary and Lunar Ephemerides DE440 and DE441”, Astron. J. 161:105 (2021). Courtesy of NASA/JPL-Caltech, Solar System Dynamics.
- IERS Conventions (2010)G. Petit, B. Luzum (eds.), IERS Technical Note No. 36 – nutation IAU 2000A, Earth rotation angle, sidereal time.
- Long-term precessionJ. Vondrák, N. Capitaine, P. Wallace, “New precession expressions, valid for long time intervals”, A&A 534, A22 (2011).
- ΔTL. V. Morrison, F. R. Stephenson, C. Y. Hohenkerk, M. Zawilski, Proc. R. Soc. A 477 (2021), table S15.2020 (CC BY 4.0); U.S. Naval Observatory measurements since 1973.
- Fixed starsThis research has made use of the SIMBAD database, CDS, Strasbourg Astronomical Observatory, France.
- Eclipse test dataEclipse Predictions by Fred Espenak, NASA's GSFC.
- Algorithms and test casesJ. Meeus, Astronomical Algorithms, 2nd ed. (1998); Explanatory Supplement to the Astronomical Almanac (2013).
Hevelius Pro
For commercial and professional use.
Hevelius Pro extends the open core with capabilities for professional software, together with a hosted API. It is in development – if you would like to use it in your product, get in touch.
- Astrological house systems
- An extended fixed-star catalogue
- Further capabilities for professional software
- Hosted API at api.hevelius.dev – in development
The name
Named after Johannes Hevelius (1611–1687), the astronomer of Gdańsk, who mapped the Moon in Selenographia and charted the sky in Firmamentum Sobiescianum – precise observation, carefully recorded. We try to work in the same spirit.