Hevelius

Guides

Guides

Each guide is a complete program from the package's example/ folder; the output shown is what it prints. All examples use de440s (1849–2150).

Positions and points

geocentricEcliptic(ephemeris, body, jdTT) returns the apparent ecliptic longitude, latitude and distance. Lunar points come from lunarPoint: the mean and true node, the mean and osculating apogee (Lilith). angles(jdUt, latitude, longitude) gives the ascendant, the MC and local sidereal time. Speeds (and retrograde motion) come from longitudeSpeed. See the first program.

Events

Ingresses, stations and any longitude crossing are found by longitudeCrossings and friends; nothing is missed, including re-entries during retrograde motion. lunarPhases finds the four principal phases, horizonEvents risings, settings and meridian transits.

example/events.dart
final sun = bodyLongitude(ephemeris, Naif.sun);
for (final i in ingresses(sun, julianDay(2027, 1, 1), julianDay(2027, 7, 1))) {
  print('${ut(i.jdTT)}  ${signs[i.sign]}');
}
for (final p in lunarPhases(ephemeris, julianDay(2027, 3, 1), julianDay(2027, 4, 1))) {
  print('${ut(p.jdTT)}  ${p.phase.name}');
}
final day = julianDay(2027, 6, 21);
for (final e in horizonEvents(ephemeris, Naif.sun, 52.2297, 21.0122, day, day + 1)) {
  print('${ut(e.jdTT)}  ${e.kind.name}');
}
The Sun enters a sign (first half of 2027):
  2027-01-20 07:29 UT  Aquarius
  2027-02-18 21:33 UT  Pisces
  2027-03-20 20:24 UT  Aries
  2027-04-20 07:17 UT  Taurus
  2027-05-21 06:18 UT  Gemini
  2027-06-21 14:10 UT  Cancer
Lunar phases (March 2027):
  2027-03-08 09:29 UT  newMoon
  2027-03-15 16:25 UT  firstQuarter
  2027-03-22 10:43 UT  fullMoon
  2027-03-30 00:53 UT  lastQuarter
Sunrise and sunset in Warsaw (21 June 2027):
  2027-06-21 02:14 UT  rise
  2027-06-21 19:01 UT  set

Event times are Julian days in TT; ut() in the example converts them to a UT date. Rising and setting follow the almanac convention: standard refraction, and for the Sun and Moon the upper limb on the horizon.

Eclipses

solarEclipses and lunarEclipses list eclipses with their type, magnitude and contacts. localSolarEclipse gives the circumstances for one place – contacts, maximum, magnitude, obscuration and the Sun's altitude, with a flag for phases below the horizon.

example/eclipses.dart
final valencia = localSolarEclipse(
  ephemeris, august,
  latitude: 39.4699, longitude: -0.3763, height: 15,
)!;
print(valencia.type);            // total
print(valencia.centralDuration); // seconds of totality
print(valencia.secondContact);   // totality begins
Solar eclipses in 2026:
  2026-02-17 12:11:56 UT  annular, magnitude 0.963
  2026-08-12 17:45:56 UT  total, magnitude 1.039
Lunar eclipses in 2026:
  2026-03-03 11:33:42 UT  total, umbral magnitude 1.151
  2026-08-28 04:12:55 UT  partial, umbral magnitude 0.930
12 August 2026 from Valencia: total, magnitude 1.003, totality 62 s
  partial phase begins  2026-08-12 17:38:26 UT  Sun at 14.7°
  totality begins       2026-08-12 18:32:29 UT  Sun at 4.5°
  totality ends         2026-08-12 18:33:31 UT  Sun at 4.3°
  partial phase ends    2026-08-12 19:24:15 UT  Sun at -4.9° (below the horizon)
Lunar eclipse of 3 March 2026 – contacts:
  partial phase  2026-03-03 09:50:05 UT – 2026-03-03 13:17:16 UT
  total phase    2026-03-03 11:04:29 UT – 2026-03-03 12:02:53 UT

Global results agree with the NASA eclipse canon to 1.5 s, local contacts with NASA's Besselian elements to about 3 s. The Moon is treated as a sphere, so second and third contacts can differ from observations by a second or two because of the lunar limb profile.

The sky from a place

An Observer is a place on the Earth. horizontalPosition returns altitude and azimuth with parallax (up to about 1° for the Moon); refraction is optional and accepts air pressure and temperature. This is the data behind a sky map or a planetarium view.

example/sky.dart
final warsaw = Observer(latitude: 52.2297, longitude: 21.0122, height: 100);
final jd = julianDayTT(julianDay(2027, 1, 15, hour: 21));
final moon = horizontalPosition(
  ephemeris, Naif.moon, warsaw, jd, withRefraction: true);
print('${moon.altitude} ${moon.azimuth}');
Warsaw, 15 January 2027 21:00 UT (altitude with refraction):
  Moon     altitude  23.2°  azimuth 262.3°
  Venus    altitude -51.2°  azimuth  37.2°
  Mars     altitude  19.8°  azimuth  97.2°
  Jupiter  altitude  31.2°  azimuth 108.5°
  Saturn   altitude   6.2°  azimuth 264.4°
  Sirius   altitude  20.5°  azimuth 169.3°

For an object given by right ascension and declination of date – a galaxy, a nebula, a star from another catalogue – use equatorialToHorizontal. Results agree with JPL Horizons to 0.7″.

Fixed stars

A FixedStar holds an ICRS position at J2000 with proper motion, parallax and radial velocity. fixedStarEcliptic and fixedStarHorizontal apply space motion, annual parallax, light deflection, aberration, precession and nutation. The package includes 22 bright stars (in its data/stars/ folder, values from SIMBAD), read with FixedStar.parseCsv; any other catalogue position can be used by creating a FixedStar.