int = PlanetAtMaximumElongation(nDate, nSunSourceIndex, nPlanetID)

 

Elongation is a body's angular separation from the Sun as seen from Earth. This macro function calculates the time on nDate when Mercury or Venus reaches a greatest eastern or western elongation: a local maximum of its geocentric angular separation from the Sun. The calculation uses the full separation on the sky, not merely a difference in right ascension or ecliptic longitude.

 

•The allowed values for nPlanetID are the 2 inner planets only; n_MERCURY and n_VENUS.

•The sign of the result is positive if the planet is at the maximal eastern elongation, and negative if the planet is at the maximal western elongation, on nDate. If the date nDate does not correspond to either case, then the function returns 0.

•The absolute value of a nonzero result is the local time expressed in millionths of a day. The fractional day is multiplied by 1000000 and truncated. If this would give 0, the function returns +1 or -1, preserving the event's sign and reserving 0 for no event.

 

Use a calculated Sun data source, selected by nSunSourceIndex. Dates and returned times use that source's local-time settings. The event is geocentric (as seen from the centre of the Earth): the observer's position on Earth does not change its instant, although the local date and time can differ between sources.

 

“Greatest” refers to an individual eastern or western elongation in the planet's cycle, not a search for the largest elongation of the calendar year. The event is returned without requiring the planet to be above the local horizon or visible from the selected location.

 

The macro code below checks whether Mercury or Venus reaches its greatest eastern or western elongation from the Sun on the date of the incoming macro token.

sResult = ''
for nPlanetID = n_MERCURY to n_VENUS step 1
    sBuffer = ''
    nCurResIdx = PlanetAtMaximumElongation(n_TokenDate, 1, nPlanetID)
    if nCurResIdx > 0
       sBuffer = PlanetName(nPlanetID) + ' at max. elongation east'
    endif
    if nCurResIdx < 0
       sBuffer = PlanetName(nPlanetID) + ' at max. elongation west'
    endif
    // add the time it occurs in parentheses
    if nCurResIdx <> 0
       sBuffer = sBuffer + FormatTime('" ("hh:nn")"', Abs(nCurResIdx), true)
    endif
    if sBuffer <> ''
       if sResult <> ''
          sResult = sResult + ', '
       endif
       sResult = sResult + sBuffer
    endif
endfor

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: PlanetAtExtremalDistanceFromSun and planetary macro functions.

 

---

Topic 177605, last updated on 12-Oct-2026