Moon phase calculator (geocentric approximation). More...

#include <MoonPhase.hpp>

Public Types
using	quarters_unix_s_t = std::array<double, 8>
	Quarter instants as Unix UTC seconds ({new, firstQ, full, lastQ} for previous and next cycles).

Public Member Functions
MoonPhaseResult	compute (double unix_utc_s) const noexcept
	Compute full set of Moon phase parameters for given UTC timestamp.

double	compute_phase (double unix_utc_s) const noexcept
	Compute only phase fraction in [0..1) for given UTC timestamp.

quarters_unix_s_t	quarter_times_unix (double unix_utc_s) const noexcept
	Compute quarter/new/full instants around given timestamp.

quarters_unix_s_t	quarter_times (double unix_utc_s) const noexcept
	Compatibility wrapper returning quarter instants as Unix UTC seconds.

MoonQuarterInstants	quarter_instants_unix (double unix_utc_s) const noexcept
	Quarter instants around the provided timestamp as a structured result (Unix UTC seconds).

bool	is_new_moon_window (double unix_utc_s, double window_seconds=kDefaultQuarterWindow_s) const noexcept
	Check whether timestamp is inside a window around new moon.

bool	is_full_moon_window (double unix_utc_s, double window_seconds=kDefaultQuarterWindow_s) const noexcept
	Check whether timestamp is inside a window around full moon.

bool	is_first_quarter_window (double unix_utc_s, double window_seconds=kDefaultQuarterWindow_s) const noexcept
	Check whether timestamp is inside a window around first quarter.

bool	is_last_quarter_window (double unix_utc_s, double window_seconds=kDefaultQuarterWindow_s) const noexcept
	Check whether timestamp is inside a window around last quarter.

Static Public Attributes
static constexpr double	kDefaultQuarterWindow_s = 43200.0
	Default window around phase events (12h).

Private Member Functions
double	mean_phase_jd (double julian_day, double lunation_index) const noexcept

double	true_phase_jd (double lunation_index, double phase_fraction) const noexcept

Static Private Member Functions
static double	julian_day_from_unix_seconds (double unix_utc_s) noexcept

static int	year_from_unix_seconds (double unix_utc_s) noexcept

static int	month_from_unix_seconds (double unix_utc_s) noexcept

static double	jd_to_unix_seconds (double julian_day) noexcept

static double	deg2rad (double deg) noexcept

static double	rad2deg (double rad) noexcept

static double	fix_angle (double a) noexcept

static double	kepler (double m_deg, double ecc) noexcept

static bool	is_within_window (double unix_utc_s, double previous_instant, double next_instant, double window_seconds) noexcept

Static Private Attributes
static constexpr double	kEpochJd = 2444238.5

static constexpr double	kElonge = 278.833540

static constexpr double	kElongp = 282.596403

static constexpr double	kEccent = 0.016718

static constexpr double	kSunSmax = 1.495985e8

static constexpr double	kSunAngSiz = 0.533128

static constexpr double	kMmLong = 64.975464

static constexpr double	kMmLongp = 349.383063

static TIME_SHIELD_MAYBE_UNUSED constexpr double	kMNode = 151.950429

static TIME_SHIELD_MAYBE_UNUSED constexpr double	kMInc = 5.145396

static constexpr double	kMecc = 0.054900

static constexpr double	kMAngSiz = 0.5181

static constexpr double	kMsMax = 384401.0

static TIME_SHIELD_MAYBE_UNUSED constexpr double	kMParallax = 0.9507

static constexpr double	kSynMonth = 29.53058868

static constexpr double	kPi = 3.14159265358979323846

Detailed Description

Moon phase calculator (geocentric approximation).

References:

John Walker, "moontool" (Fourmilab). See: https://www.fourmilab.ch/moontoolw/
solarissmoke/php-moon-phase (port). See: https://github.com/solarissmoke/php-moon-phase/blob/master/Solaris/MoonPhase.php

Notes:

Input timestamps are assumed to be UTC Unix seconds (can be floating).
Computation is geocentric (no observer latitude/longitude corrections).

Example usage:

using namespace time_shield;
MoonPhase calculator{};
double ts = 1704067200.0; // 2024-01-01T00:00:00Z
MoonPhaseResult res = calculator.compute(ts);          // illumination, angles, sin/cos
MoonPhase::quarters_unix_s_t quarters = calculator.quarter_times_unix(ts); // Unix seconds as double
MoonQuarterInstants mapped = calculator.quarter_instants_unix(ts); // structured view
bool near_full = calculator.is_full_moon_window(ts, 3600.0); // +/-1h window check

Definition at line 68 of file MoonPhase.hpp.

Member Typedef Documentation

◆ quarters_unix_s_t

using time_shield::astronomy::MoonPhase::quarters_unix_s_t = std::array<double, 8>

Quarter instants as Unix UTC seconds ({new, firstQ, full, lastQ} for previous and next cycles).

Definition at line 70 of file MoonPhase.hpp.

Member Function Documentation

◆ compute()

MoonPhaseResult time_shield::astronomy::MoonPhase::compute ( double unix_utc_s ) const

inlinenoexcept

Compute full set of Moon phase parameters for given UTC timestamp.

Parameters

unix_utc_s Timestamp in Unix UTC seconds (can be fractional).

Returns: Geocentric Moon phase parameters for the given instant.

Definition at line 76 of file MoonPhase.hpp.

◆ compute_phase()

double time_shield::astronomy::MoonPhase::compute_phase ( double unix_utc_s ) const

inlinenoexcept

Compute only phase fraction in [0..1) for given UTC timestamp.

Parameters

unix_utc_s Timestamp in Unix UTC seconds (can be fractional).

Returns: Phase fraction in the \([0, 1)\) interval where 0=new moon, 0.5=full moon.

Definition at line 138 of file MoonPhase.hpp.

◆ deg2rad()

static double time_shield::astronomy::MoonPhase::deg2rad ( double deg )

inlinestaticprivatenoexcept

Definition at line 293 of file MoonPhase.hpp.

◆ fix_angle()

static double time_shield::astronomy::MoonPhase::fix_angle ( double a )

inlinestaticprivatenoexcept

Definition at line 296 of file MoonPhase.hpp.

◆ is_first_quarter_window()

bool time_shield::astronomy::MoonPhase::is_first_quarter_window	(	double	unix_utc_s,
		double	window_seconds = kDefaultQuarterWindow_s ) const

inlinenoexcept

Check whether timestamp is inside a window around first quarter.

Parameters

unix_utc_s	Timestamp in Unix UTC seconds (can be fractional).
window_seconds	Symmetric window size in seconds around the event time.

Returns: true if the timestamp lies within the window of the previous or next first quarter.

Definition at line 241 of file MoonPhase.hpp.

◆ is_full_moon_window()

bool time_shield::astronomy::MoonPhase::is_full_moon_window	(	double	unix_utc_s,
		double	window_seconds = kDefaultQuarterWindow_s ) const

inlinenoexcept

Check whether timestamp is inside a window around full moon.

Parameters

unix_utc_s	Timestamp in Unix UTC seconds (can be fractional).
window_seconds	Symmetric window size in seconds around the event time.

Returns: true if the timestamp lies within the window of the previous or next full moon.

Definition at line 232 of file MoonPhase.hpp.

◆ is_last_quarter_window()

bool time_shield::astronomy::MoonPhase::is_last_quarter_window	(	double	unix_utc_s,
		double	window_seconds = kDefaultQuarterWindow_s ) const

inlinenoexcept

Check whether timestamp is inside a window around last quarter.

Parameters

unix_utc_s	Timestamp in Unix UTC seconds (can be fractional).
window_seconds	Symmetric window size in seconds around the event time.

Returns: true if the timestamp lies within the window of the previous or next last quarter.

Definition at line 250 of file MoonPhase.hpp.

◆ is_new_moon_window()

bool time_shield::astronomy::MoonPhase::is_new_moon_window	(	double	unix_utc_s,
		double	window_seconds = kDefaultQuarterWindow_s ) const

inlinenoexcept

Check whether timestamp is inside a window around new moon.

Parameters

unix_utc_s	Timestamp in Unix UTC seconds (can be fractional).
window_seconds	Symmetric window size in seconds around the event time.

Returns: true if the timestamp lies within the window of the previous or next new moon.

Definition at line 223 of file MoonPhase.hpp.

◆ is_within_window()

static bool time_shield::astronomy::MoonPhase::is_within_window	(	double	unix_utc_s,
		double	previous_instant,
		double	next_instant,
		double	window_seconds )

inlinestaticprivatenoexcept

Definition at line 389 of file MoonPhase.hpp.

◆ jd_to_unix_seconds()

static double time_shield::astronomy::MoonPhase::jd_to_unix_seconds ( double julian_day )

inlinestaticprivatenoexcept

Definition at line 268 of file MoonPhase.hpp.

◆ julian_day_from_unix_seconds()

static double time_shield::astronomy::MoonPhase::julian_day_from_unix_seconds ( double unix_utc_s )

inlinestaticprivatenoexcept

Definition at line 256 of file MoonPhase.hpp.

◆ kepler()

static double time_shield::astronomy::MoonPhase::kepler	(	double	m_deg,
		double	ecc )

inlinestaticprivatenoexcept

Definition at line 302 of file MoonPhase.hpp.

◆ mean_phase_jd()

double time_shield::astronomy::MoonPhase::mean_phase_jd	(	double	julian_day,
		double	lunation_index ) const

inlineprivatenoexcept

Definition at line 314 of file MoonPhase.hpp.

◆ month_from_unix_seconds()

static int time_shield::astronomy::MoonPhase::month_from_unix_seconds ( double unix_utc_s )

inlinestaticprivatenoexcept

Definition at line 264 of file MoonPhase.hpp.

◆ quarter_instants_unix()

MoonQuarterInstants time_shield::astronomy::MoonPhase::quarter_instants_unix ( double unix_utc_s ) const

inlinenoexcept

Quarter instants around the provided timestamp as a structured result (Unix UTC seconds).

Parameters

unix_utc_s Timestamp in Unix UTC seconds (can be fractional).

Returns: Previous/next quarter instants mapped into a structured result with Unix UTC seconds.

Definition at line 205 of file MoonPhase.hpp.

◆ quarter_times()

quarters_unix_s_t time_shield::astronomy::MoonPhase::quarter_times ( double unix_utc_s ) const

inlinenoexcept

Compatibility wrapper returning quarter instants as Unix UTC seconds.

Parameters

unix_utc_s Timestamp in Unix UTC seconds (can be fractional).

Returns: Same payload as quarter_times_unix() for compatibility.

Definition at line 198 of file MoonPhase.hpp.

◆ quarter_times_unix()

quarters_unix_s_t time_shield::astronomy::MoonPhase::quarter_times_unix ( double unix_utc_s ) const

inlinenoexcept

Compute quarter/new/full instants around given timestamp.

Parameters

unix_utc_s Timestamp in Unix UTC seconds (can be fractional).

Returns: Array of 8 instants (Unix UTC seconds as double): {prev new, prev firstQ, prev full, prev lastQ, next new, next firstQ, next full, next lastQ}.

Definition at line 145 of file MoonPhase.hpp.

◆ rad2deg()

static double time_shield::astronomy::MoonPhase::rad2deg ( double rad )

inlinestaticprivatenoexcept

Definition at line 294 of file MoonPhase.hpp.

◆ true_phase_jd()

double time_shield::astronomy::MoonPhase::true_phase_jd	(	double	lunation_index,
		double	phase_fraction ) const

inlineprivatenoexcept

Definition at line 325 of file MoonPhase.hpp.

◆ year_from_unix_seconds()

static int time_shield::astronomy::MoonPhase::year_from_unix_seconds ( double unix_utc_s )

inlinestaticprivatenoexcept

Definition at line 260 of file MoonPhase.hpp.

Member Data Documentation

◆ kDefaultQuarterWindow_s

double time_shield::astronomy::MoonPhase::kDefaultQuarterWindow_s = 43200.0

staticconstexpr

Default window around phase events (12h).

Definition at line 71 of file MoonPhase.hpp.

◆ kEccent

double time_shield::astronomy::MoonPhase::kEccent = 0.016718

staticconstexprprivate

Definition at line 277 of file MoonPhase.hpp.

◆ kElonge

double time_shield::astronomy::MoonPhase::kElonge = 278.833540

staticconstexprprivate

Definition at line 275 of file MoonPhase.hpp.

◆ kElongp

double time_shield::astronomy::MoonPhase::kElongp = 282.596403

staticconstexprprivate

Definition at line 276 of file MoonPhase.hpp.

◆ kEpochJd

double time_shield::astronomy::MoonPhase::kEpochJd = 2444238.5

staticconstexprprivate

Definition at line 273 of file MoonPhase.hpp.

◆ kMAngSiz

double time_shield::astronomy::MoonPhase::kMAngSiz = 0.5181

staticconstexprprivate

Definition at line 286 of file MoonPhase.hpp.

◆ kMecc

double time_shield::astronomy::MoonPhase::kMecc = 0.054900

staticconstexprprivate

Definition at line 285 of file MoonPhase.hpp.

◆ kMInc

TIME_SHIELD_MAYBE_UNUSED constexpr double time_shield::astronomy::MoonPhase::kMInc = 5.145396

staticconstexprprivate

Definition at line 284 of file MoonPhase.hpp.

◆ kMmLong

double time_shield::astronomy::MoonPhase::kMmLong = 64.975464

staticconstexprprivate

Definition at line 281 of file MoonPhase.hpp.

◆ kMmLongp

double time_shield::astronomy::MoonPhase::kMmLongp = 349.383063

staticconstexprprivate

Definition at line 282 of file MoonPhase.hpp.

◆ kMNode

TIME_SHIELD_MAYBE_UNUSED constexpr double time_shield::astronomy::MoonPhase::kMNode = 151.950429

staticconstexprprivate

Definition at line 283 of file MoonPhase.hpp.

◆ kMParallax

TIME_SHIELD_MAYBE_UNUSED constexpr double time_shield::astronomy::MoonPhase::kMParallax = 0.9507

staticconstexprprivate

Definition at line 288 of file MoonPhase.hpp.

◆ kMsMax

double time_shield::astronomy::MoonPhase::kMsMax = 384401.0

staticconstexprprivate

Definition at line 287 of file MoonPhase.hpp.

◆ kPi

double time_shield::astronomy::MoonPhase::kPi = 3.14159265358979323846

staticconstexprprivate

Definition at line 291 of file MoonPhase.hpp.

◆ kSunAngSiz

double time_shield::astronomy::MoonPhase::kSunAngSiz = 0.533128

staticconstexprprivate

Definition at line 279 of file MoonPhase.hpp.

◆ kSunSmax

double time_shield::astronomy::MoonPhase::kSunSmax = 1.495985e8

staticconstexprprivate

Definition at line 278 of file MoonPhase.hpp.

◆ kSynMonth

double time_shield::astronomy::MoonPhase::kSynMonth = 29.53058868

staticconstexprprivate

Definition at line 289 of file MoonPhase.hpp.

The documentation for this class was generated from the following file:

include/time_shield/astronomy/MoonPhase.hpp

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Static Private Attributes

Detailed Description

Member Typedef Documentation

◆ quarters_unix_s_t

Member Function Documentation

◆ compute()

◆ compute_phase()

◆ deg2rad()

◆ fix_angle()

◆ is_first_quarter_window()

◆ is_full_moon_window()

◆ is_last_quarter_window()

◆ is_new_moon_window()

◆ is_within_window()

◆ jd_to_unix_seconds()

◆ julian_day_from_unix_seconds()

◆ kepler()

◆ mean_phase_jd()

◆ month_from_unix_seconds()

◆ quarter_instants_unix()

◆ quarter_times()

◆ quarter_times_unix()

◆ rad2deg()

◆ true_phase_jd()

◆ year_from_unix_seconds()

Member Data Documentation

◆ kDefaultQuarterWindow_s

◆ kEccent

◆ kElonge

◆ kElongp

◆ kEpochJd

◆ kMAngSiz

◆ kMecc

◆ kMInc

◆ kMmLong

◆ kMmLongp

◆ kMNode

◆ kMParallax

◆ kMsMax

◆ kPi

◆ kSunAngSiz

◆ kSunSmax

◆ kSynMonth