int = HeliacalEventOnDate(nDate,nSunSourceIndex,nPlanetOrStarID,nEventType)
Heliacal rising and setting mark a body's reappearance from, or disappearance into, the Sun's glare. This macro function checks whether the selected first- or last-visibility event occurs on nDate for nPlanetOrStarID, at Sun data source nSunSourceIndex. It returns the model's optimum visibility time on that event date, rather than an ordinary daily rising or setting time at the horizon.
•Supported bodies are Mercury through Pluto and the catalogued stars (indices 2–29 in astronomical bodies). The Sun and Moon are excluded.
•The event types are: 1, first morning visibility (heliacal rise); 2, last evening visibility (heliacal setting); 3, first evening visibility; and 4, last morning visibility. Types 3 and 4 are supported here only for Mercury and Venus.
•A successful result is the optimum visibility time in local millionths of a day, obtained by multiplying the fractional day by 1000000 and truncating. The range is 0 to 999999; 0 is valid midnight.
•If no event of the selected type falls on nDate, the result is -1. Test for >= 0 before using the returned time.
Use a calculated Sun data source, selected by nSunSourceIndex. Dates and returned times use that source's local-time settings. The predicted date and time depend on the observer's location and the calculation's built-in atmospheric and observer assumptions. Actual first or last visibility can differ with weather, haze, eyesight and obstructions. The model can miss events or give unreliable results in unusual cases at high latitudes or for circumpolar bodies (bodies that do not set at the selected location).
A last-visibility event denotes the final morning or evening on which the model predicts visibility; it is not the first day on which the body is already invisible.
The macro code below uses HeliacalEventOnDate to look for the Maori New Year (Matariki), which corresponds to the new Moon which follows the heliacal rise of the Pleiades star cluster (see historical follow-up below).
➢This historical example does not calculate the statutory Matariki public holiday dates introduced in New Zealand in 2022.
For this example, Sun data source 1 and Moon data source 1 must refer to the intended New Zealand location and use consistent local-time settings.
nEventType = 1 // heliacal rise
nAstroBody = 29 // Alcyone, the brightest star in the Pleiades
// look from mid-May to the end of June
nHeliacalDate = 0
for nRunDate = EncodeDate(nYear,5,15) to EncodeDate(nYear,6,30)
nHeliacalTime = HeliacalEventOnDate(nRunDate,1,nAstroBody,nEventType)
if nHeliacalTime >= 0
nHeliacalDate = nRunDate
break // found it
endif
endfor
Assert(nHeliacalDate > 0, 'heliacal event not found', true)
// now look for the new Moon that follows
nMatarikiDate = 0
for nRunDate = nHeliacalDate to nHeliacalDate + 35
nNewMoonTime = MoonPhaseAndTimeOf(nRunDate,1,false)
// do we have a phase and if so a new Moon ?
if (nNewMoonTime > 0) and (nNewMoonTime div 1000000 == 1)
// if the new Moon is on the exact date of the heliacal rise
// make sure that the time of the new Moon is after it
if nRunDate == nHeliacalDate
// New Moon must be after heliacal rise
if (nNewMoonTime mod 1000000) > nHeliacalTime
nMatarikiDate = nRunDate
break // found it
else
// too early keep looking for the next new Moon
endif
else
nMatarikiDate = nRunDate
break // found it
endif
endif
endfor
Assert(nMatarikiDate > 0, 'Matariki not found', true)
// at the end
sResult = 'Maori New Year on ' + FormatDate('Dddd, Mmmmm d, yyyy', nMatarikiDate)
Historical Follow-Up
The above code is based on the way Matariki was calculated up to, and including, 2021. But, when Matariki was added as an official non-working public holiday in New Zealand, beginning in 2022, a Matariki Advisory Group was created, comprising experts in Mātauranga Māori (Māori knowledge), tasked with the determination of the dates of the Matariki public holiday for the period 2022–2052. The result was a list of hard-coded dates for the occurrence of Matariki in the period 2022–2052.
One millionth of a day represents 0.0864 seconds in the time encoding; this specifies the units, not a guarantee of subsecond calculation accuracy.
See also: astronomical bodies indices and heliacal event types.
Topic 180070, last updated on 12-Oct-2026
