astro::planet::phenomena Namespace Reference

Namespaces
namespace	detail

Classes
struct	Event
	A planetary event and its TT-scale instant. More...

Enumerations
enum class	Kind : uint8_t {   INFERIOR_CONJUNCTION , SUPERIOR_CONJUNCTION , CONJUNCTION , OPPOSITION ,   EASTERN_QUADRATURE , WESTERN_QUADRATURE , GREATEST_EASTERN_ELONGATION , GREATEST_WESTERN_ELONGATION ,   STATION_RETROGRADE , STATION_DIRECT }
	An observer-facing planetary event. More...

Functions
auto	events (const Planet planet, const int32_t year) -> std::vector< Event >
	Find all applicable observer-facing events for a planet in a Gregorian year.

Enumeration Type Documentation

Kind

enum class astro::planet::phenomena::Kind : uint8_t

strong

An observer-facing planetary event.

Enumerator
INFERIOR_CONJUNCTION
SUPERIOR_CONJUNCTION
CONJUNCTION
OPPOSITION
EASTERN_QUADRATURE
WESTERN_QUADRATURE
GREATEST_EASTERN_ELONGATION
GREATEST_WESTERN_ELONGATION
STATION_RETROGRADE
STATION_DIRECT

Function Documentation

events()

auto astro::planet::phenomena::events ( const Planet planet, const int32_t year )->std::vector< Event >

inlinenodiscard

Find all applicable observer-facing events for a planet in a Gregorian year.

Parameters

planet	The planet to search, from Mercury through Pluto.
year	The Gregorian year, in the selected planet's documented domain.

Returns

Events in strictly increasing JDE(TT) order.

Searches apparent geocentric ecliptic-of-date positions on a one-day candidate grid, then refines each event independently.

Exceptions

std::invalid_argument	If year is outside the selected planet's documented domain or planet is not a named enumerator.
std::runtime_error	If an event cannot be refined or an internal event-consistency check fails.

Note

Pluto supports complete Gregorian years [1886, 2098]; the Mercury-Neptune computational year domain remains [1, 32766].

The year is the half-open interval [Jan 1, next Jan 1) in UTC; before 1972, UTC degrades to the library's UT1 substitute. The declared year range is a computational input domain, not an accuracy guarantee for the underlying ephemeris at remote dates.

Inner planets receive inferior/superior conjunctions, greatest elongations, and stations. Outer planets receive conjunctions, oppositions, quadratures, and stations.

Conjunction, opposition, and quadrature solve the unwrapped apparent longitude difference planet minus Sun at 360°·k, 180° + 360°·k, and ±90° + 360°·k. Conjunction means equal longitude, not minimum separation, distance, or equal right ascension.

Greatest elongations are local maxima of great-circle Sun-planet separation, east or west by wrapped longitude difference. STATION_RETROGRADE marks the direct-to-retrograde turn and STATION_DIRECT the reverse; latitude may still be changing. Inferior conjunctions have phase angle at least 90°.

See also

Jean Meeus, "Astronomical Algorithms", Second Edition, Chapter 36 (planetary phenomena).

Note

These definitions use the position models directly, not Chapter 36's approximate event-time series.

Stations here are longitude extrema, not zeros of ephemeris::longitude_rate. The interval searches in ephemeris_events.hpp retain their separate rate domain, certificates and endpoint policy; see docs/EPHEMERIS_EVENTS.md.