Time Shield Library
C++ library for working with time
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Attributes | Private Member Functions | Static Private Member Functions | Static Private Attributes | List of all members
time_shield::astronomy::MoonPhase Class Reference

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:

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
time_shield::astronomy::MoonPhase
Moon phase calculator (geocentric approximation).
Definition MoonPhase.hpp:68
time_shield::astronomy::MoonPhase::quarters_unix_s_t
std::array< double, 8 > quarters_unix_s_t
Quarter instants as Unix UTC seconds ({new, firstQ, full, lastQ} for previous and next cycles).
Definition MoonPhase.hpp:70
time_shield::ts
TIME_SHIELD_CONSTEXPR ts_t ts(year_t year, int month, int day)
Alias for to_timestamp.
Definition time_conversion_aliases.hpp:363
time_shield
Main namespace for the Time Shield library.
time_shield::astronomy::MoonPhaseResult
Result of Moon phase computation (geocentric approximation).
Definition MoonPhase.hpp:22
time_shield::astronomy::MoonQuarterInstants
Lunar quarter instants (Unix UTC seconds, floating).
Definition MoonPhase.hpp:37

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_sTimestamp 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_sTimestamp 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_sTimestamp in Unix UTC seconds (can be fractional).
window_secondsSymmetric 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_sTimestamp in Unix UTC seconds (can be fractional).
window_secondsSymmetric 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_sTimestamp in Unix UTC seconds (can be fractional).
window_secondsSymmetric 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_sTimestamp in Unix UTC seconds (can be fractional).
window_secondsSymmetric 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_sTimestamp 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_sTimestamp 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_sTimestamp 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: