Ephemerides

Everything is computed on the hub, offline, in the hub's time zone. The positions of the sun and the moon come from suncalc, a library that follows Jean Meeus's algorithms (Astronomical Algorithms); the equinoxes, the solstices, the new and full moons and the moon's distance, which suncalc does not provide, are computed by the app from the matching chapters of the same book, and checked against its worked examples. Since suncalc's documentation still describes an earlier version, its actual behaviour was checked step by step: three gaps between what it states and what it returns had to be corrected before the app said anything true, and they are described below.

1. 01

   Where the sun is

   λ = L₀ + C − 0,00569° − 0,00478° · sin Ω · sin δ = sin ε · sin λ

   The computation starts from the number of days since noon on 1 January 2000, corrected by ΔT, the gap between clock time and the time that governs the motion of the sky. The sun's mean longitude L₀ receives the equation of the centre C, which accounts for the ellipse of the Earth's orbit, then two small corrections, aberration and nutation: this is the apparent ecliptic longitude λ. The tilt of the Earth's axis ε, a little over 23.4°, carries it onto the celestial equator and gives the declination δ and the right ascension. With the local sidereal time, these give the hour angle, then the azimuth and the height.

2. 02

   Solar noon, and the equation of time without naming it

   H = θ − α = 0

   Solar noon is the moment the sun crosses the local meridian, when its hour angle H, the gap between the sidereal time θ and its right ascension α, falls to zero. suncalc starts from the mean noon of the longitude, recomputes the sun's position at the instant found and corrects it by the remaining angle, three times. The gap between this true noon and noon by mean time, what is called the equation of time, is thus built into the result without being computed separately. The nadir, or solar midnight, is twelve hours away from it.

3. 03

   Sunrise and sunset

   cos H₀ = (sin h₀ − sin φ · sin δ) ⁄ (cos φ · cos δ) · h₀ = −0,833° − 2,076′ · √a

   Official sunrise and sunset are the moments when the centre of the sun is at −0.833° of geometric height: 34 minutes of arc of refraction, which lift the sun's image, and 16 of semi-diameter, so that the upper limb touches the horizon. The formula gives the hour angle H₀ on either side of solar noon, for the latitude φ and the declination δ, then two successive corrections account for the sun's motion in the meantime. If the observer's height a, in metres, is set, the horizon dips by 2.076 minutes of arc times its square root: seen from a tower, the sun rises earlier. When the cosine falls outside the range from −1 to 1, there is no sunrise or sunset that day: polar night if the sun stays below −0.833° at noon, midnight sun otherwise.

4. 04

   From apparent height to geometric height

   hauteur géométrique = hauteur apparente − réfraction(max(hauteur géométrique, 0))

   suncalc returns an apparent height, atmospheric refraction included, while sunrise, sunset and the twilights are defined on the geometric height, that of the disc's true centre. But its refraction formula first clamps the height to zero, which adds a constant 0.484° everywhere below the horizon, at −18° as much as at −1°. Exposing the apparent height would have made a “below −6°” threshold fire two minutes after civil dawn, for the same definition. Below the horizon, removing the refraction is thus a plain subtraction; above it, where it varies with height, it takes iteration, and a single pass crossing the kink oscillates without converging: six are needed.

5. 05

   Which way the sun is moving, even with no sunrise or sunset

   montant = maintenant < midi solaire

   A height of −3° is a dawn in the morning, a dusk in the evening: the sky's phase therefore depends on which way the sun is moving, not on its height alone. That direction cannot be read off sunrise, which does not exist in every season or at every latitude, but off solar noon, the only reference that stays defined even on a day of midnight sun or polar night.

6. 06

   Three ways of saying nothing

   événement absent = null, undefined, ou Invalid Date selon le champ

   An event that does not happen that day, an astronomical dusk in the middle of a Nordic summer, say, does not always take the same absent shape: depending on the field, suncalc returns `null`, `undefined`, or an invalid date. A plain `instanceof Date` does not catch all three, and reading the time of an invalid date throws rather than signals it. All three shapes are therefore reduced to one single signal before reaching the rest of the code.

7. 07

   The ladder of sky phases

   jour ≥ 6° > heure dorée ≥ −0,833° > crépuscule civil ≥ −6° > nautique ≥ −12° > astronomique ≥ −18° > nuit

   Ten phases follow one another between full daylight and full night, each bounded by a geometric height of the sun: daylight above 6°, golden hour down to the official sunrise at −0.833°, then the three twilights, civil, nautical and astronomical, at −6°, −12° and −18°, before night. The same ladder, read the other way, gives the morning phases. This is the ladder the tile's own capability reads, its ten labels coming from the manifest rather than being duplicated in the translations.

8. 08

   The golden hour and the blue hour

   −0,833° ≤ h < 6° · −6° ≤ h < −4°

   The golden hour is when the sun, low on the horizon, lights things at a slant: the app bounds it between the official sunrise, −0.833°, and 6° of height, so that it contains sunrise and sunset themselves. The blue hour is the darkest part of civil twilight, between −6° and −4°, when the sky stays blue without the sun. Both are read on the same geometric height as the twilights; the daylight band, the capabilities and the Flow cards use the same bounds, and therefore say the same thing at the same moment.

9. 09

   Day length, and what it gains

   D = t↓ − t↑ · ΔD = D(j) − D(j − 1)

   Day length runs from official sunrise to sunset, computed for each civil day at local noon, in the hub's time zone. Its variation is the difference from the day before, to the second: that is what the tile reports as minutes and seconds gained or lost. Midnight sun counts as twenty-four hours and polar night as zero: these are real values, not gaps, and the yearly curve holds them flat without overshooting.

10. 10

    The equinoxes and the solstices

    JDE = JDE₀ + 0,00001 · S ⁄ Δλ · Δλ = 1 + 0,0334 · cos W + 0,0007 · cos 2W · W = 35 999,373° · T − 2,47°

    They follow chapter 27 of Meeus. A polynomial first gives a mean instant for each of the four, valid from the year 1000 to the year 3000; twenty-four periodic terms, whose sum is S, then correct it, weighted by Δλ. The result is in ephemeris time: ΔT is subtracted, taken as a fixed 69 seconds, whose real error stays below ten seconds until 2035. A test checks it against Meeus's worked example, the June solstice of 1962, then against the published instants for 2026: all four land within two minutes.

11. 11

    The moon's phase and age

    k = (1 + cos i) ⁄ 2 · phase ∈ [0, 1[, 0 = nouvelle lune, 0,5 = pleine lune · âge = phase × 29,530588853 j

    The illumination is the fraction of the disc lit as seen from the Earth; it follows from the phase angle i, the angle between the sun and the Earth as seen from the moon, computed from the positions of both bodies. suncalc returns the lunar phase as a fraction of the cycle between 0 and 1, where 0 is new moon and 0.5 is full moon. That single fraction is turned into one of the eight usual names, new moon, waxing crescent, first quarter…, by a plain series of boundaries. Multiplied by the mean length of a lunation, 29.530588853 days, it also gives the moon's age, with no separate calculation: the same fraction carries both pieces of information.

12. 12

    New and full moons, to the minute

    JDE = 2 451 550,09766 + 29,530588861 · k + … · k entier : ● · k + ½ : ○

    The phase says where the moon is in its cycle, not the exact moment it becomes full. That moment follows chapter 49 of Meeus: from a lunation number k, counted from the new moon of 6 January 2000, a formula gives the mean instant, which twenty-five terms tied to the orbits of the moon and the sun, then fourteen planetary terms, correct. It is then dated in the hub's time zone, which matters near midnight. A test checks it against Meeus's worked example, the new moon of February 1977, then against the published new and full moons of 2026, thirteen full moons among them: within two minutes.

13. 13

    The moon's distance, and the supermoon

    r = 385 000,56 km + Σ rᵢ · cos(dᵢ·D + mᵢ·M + m′ᵢ·M′ + fᵢ·F) · ○ et r < 360 000 km → super-lune

    The distance from the centre of the Earth to the centre of the moon follows chapter 47 of Meeus: a mean value of 385,000.56 km, corrected by forty-six terms that depend on the elongation D, the mean anomalies of the sun M and of the moon M′, and the argument of latitude F. A test checks it against Meeus's worked example, 368,409.7 km on 12 April 1992. A full moon is called a supermoon when the moon is closer than 360,000 km at the very instant of full moon, the most widely used threshold. The one on 24 December 2026, at 356,740 km, is one; the one on 24 November, at 360,768 km, is not, by 768 km.

14. 14

    The blue moon

    2ᵉ ○ du mois civil, dans le fuseau de la box

    A blue moon is the second full moon in the same calendar month. The month is counted in the hub's time zone, so the same full moon can be blue in one place and not in another: the one on 31 December 2028 at 16:48 UTC is December's second in Paris, but falls on 1 January in Kiritimati, at UTC+14, where it is January's first. In 2026, the full moon of 31 May, which follows the one of 1 May, is blue; it is also one of the most distant, at more than 406,000 km.

15. 15

    Moonrise and moonset

    h = h_géo − arcsin(R ⁄ r · cos h_géo)

    The moon is close enough for the observer's position to matter: seen from the surface rather than from the centre of the Earth, it appears lower, by nearly a degree at the horizon. This parallax is subtracted using its current distance, R being the Earth's radius and r the distance. Moonrise and moonset are the moments the upper limb of the disc touches the horizon, refraction included: suncalc looks for them hour by hour by parabolic interpolation, then refines them twice. Since it always scans one UTC day, the app queries every UTC day that the civil day overlaps, so as not to lose a moonrise that falls on the other side of UTC midnight.

16. 16

    The compass

    A = atan2(sin H, cos H · sin φ − tan δ · cos φ) + 180°

    Azimuth is counted in degrees from north towards east, and height is geometric, as everywhere in the app. The compass rounds the azimuth to the nearest eighth of the compass rose, from north to north-west, and the page writes it with the letters of the hub's language, O for west in French, W in English. A body counts as up above −0.833°.

17. 17

    The seasons and the clock change

    décalage(t) ≠ décalage(t + 1 j) → dichotomie, arrondi à la minute

    An astronomical season runs from one equinox or solstice to the next; its name depends on the hemisphere, and the March equinox opens spring in the north, autumn in the south. The next clock change is not hard-coded: the app reads the hub's time zone database day by day, over a little more than a year, narrows down the instant by bisection and rounds it to the minute. A country that gives up daylight saving stops showing one as soon as that database knows.

18. 18

    The stargazing night

    h☉ < −18° · gêne : h☾ > −0,833° et k ≥ 15 %

    The night chosen is the current astronomical night, sun below −18°, or the next one starting within twenty-four hours. The moon is followed through it every five minutes; it gets in the way if it is up during the night and lit at 15 % or more, its illumination k being taken at the middle of the night. Below that, a thin crescent lights little more than the sky itself, and counting it would deprive the observer of the best nights of the month. Above roughly 48.5° of latitude, summer has no astronomical night: the tile says so. Clouds are not taken into account, since nothing leaves the hub.

19. 19

    Easter Sunday, and its cross-check

    algorithme grégorien anonyme (Meeus, Jones, Butcher), confronté à l'algorithme de Gauss de 1900 à 2200

    The eleven public holidays of the general regime all follow from a fixed date or from Easter Sunday, computed offline by the anonymous Gregorian algorithm, valid for any year of the Gregorian calendar. Rather than taking it on trust, a test checks it against Gauss's algorithm, formulated independently, across the three hundred and one years from 1900 to 2200: the two agree every single year. Alsace-Moselle adds two days to the general regime, Good Friday and 26 December, under local law.

20. 20

    The right instant, in the right time zone

    instant local = mur UTC − décalage(fuseau), décalage recalculé deux fois après un premier essai

    Scheduling an announcement for six in the evening local time requires knowing that zone's offset at that very instant, yet the offset itself depends on the instant still being sought, because of daylight saving. The first guess starts from a wall-clock hour treated as UTC, then the real offset is recomputed at that corrected instant, twice in a row: the process converges even on a clock-change day, and a test checks it over three hundred and sixty-five days and three time zones.