QuanTAlib/lib/cycles/lunar/Lunar.md

LUNAR: Lunar Phase Indicator

"The Moon moves markets—or at least it moves traders who believe the Moon moves markets."

The Lunar Phase indicator calculates the Moon's illumination phase using orbital mechanics, outputting values from 0.0 (new moon) through 0.5 (quarters) to 1.0 (full moon). This implementation uses the Meeus astronomical algorithms with perturbation corrections for accuracy within arcminutes across centuries.

Historical Context

Lunar cycle trading dates to ancient civilizations who observed correlations between lunar phases and agricultural markets. Modern quantitative finance occasionally revisits this theme—some studies suggest slight behavioral effects around full moons (heightened risk-taking) and new moons (conservatism), though effect sizes remain small and contested.

The algorithm here derives from Jean Meeus' Astronomical Algorithms (1991), which provides high-precision orbital calculations suitable for ephemeris computation. The perturbation terms correct for gravitational interactions between the Moon, Sun, and Earth that cause the Moon's orbit to deviate from a simple ellipse.

Architecture & Physics

1. Time Conversion

The indicator converts input timestamps to Julian Date (JD), the continuous day count from 4713 BCE:

JD = \frac{t_{unix}}{86400000} + 2440587.5

Julian centuries from J2000 epoch (2000-01-01 12:00 TT):

T = \frac{JD - 2451545.0}{36525.0}

2. Orbital Elements

Five fundamental arguments describe the Moon-Sun-Earth geometry:

Element	Symbol	Description
Mean longitude	L_p	Moon's average position along ecliptic
Mean elongation	D	Angular separation Moon-Sun
Sun's anomaly	M	Sun's position relative to perigee
Moon's anomaly	M_p	Moon's position relative to perigee
Argument of latitude	F	Moon's position relative to ascending node

Each element follows a polynomial in T:

L_p = 218.3164477 + 481267.88123421T - 0.0015786T^2 + \frac{T^3}{538841} - \frac{T^4}{65194000}

3. Perturbation Corrections

The Moon's longitude receives corrections for gravitational perturbations:

\Delta L = 6288.016 \sin(M_p) + 1274.242 \sin(2D - M_p) + 658.314 \sin(2D) + \ldots

These six principal terms account for:

• Evection (largest perturbation from Sun)
• Variation (Sun-induced elongation effects)
• Annual equation (Earth's orbital eccentricity)
• Parallactic inequality (Earth-Moon distance variation)

4. Phase Calculation

The phase angle is the ecliptic longitude difference:

\phi = L_{moon} - L_{sun}

Illumination fraction uses the cosine formula:

phase = \frac{1 - \cos(\phi)}{2}

This produces:

• phase = 0 at new moon (\phi = 0°)
• phase = 0.5 at quarters (\phi = 90°, 270°)
• phase = 1 at full moon (\phi = 180°)

Mathematical Foundation

Julian Date Conversion

From Unix milliseconds t:

JD = \frac{t}{86400000} + 2440587.5

Orbital Element Polynomials

All angles in degrees, normalized to [0°, 360°):

Moon's mean longitude:

L_p = 218.3164477 + 481267.88123421T - 0.0015786T^2 + \frac{T^3}{538841} - \frac{T^4}{65194000}

Mean elongation:

D = 297.8501921 + 445267.1114034T - 0.0018819T^2 + \frac{T^3}{545868} - \frac{T^4}{113065000}

Sun's mean anomaly:

M = 357.5291092 + 35999.0502909T - 0.0001536T^2 + \frac{T^3}{24490000}

Moon's mean anomaly:

M_p = 134.9633964 + 477198.8675055T + 0.0087414T^2 + \frac{T^3}{69699} - \frac{T^4}{14712000}

Argument of latitude:

F = 93.2720950 + 483202.0175233T - 0.0036539T^2 - \frac{T^3}{3526000} + \frac{T^4}{863310000}

Perturbation Series

Longitude correction (arcseconds):

\Delta L = 6288.016 \sin(M_p) + 1274.242 \sin(2D - M_p) + 658.314 \sin(2D)

+ 214.818 \sin(2M_p) + 186.986 \sin(M) + 109.154 \sin(2F)

True Moon longitude:

L_{moon} = L_p + \frac{\Delta L}{1000000}

Sun's Longitude

L_{sun} = 280.46646 + 36000.76983T + 0.0003032T^2

Performance Profile

Operation Count (Streaming Mode, Scalar)

Operation	Count	Cost (cycles)	Subtotal
FMA	22	4	88
ADD/SUB	8	1	8
MUL	12	3	36
DIV	8	15	120
MOD	8	15	120
SIN	7	50	350
COS	1	50	50
Total	66	—	~772 cycles

Uses Math.FusedMultiplyAdd() for polynomial evaluations and perturbation summations. Trigonometric operations dominate at ~52% of total cost.

Batch Mode

SIMD vectorization applies naturally to batch timestamp processing—each calculation is independent. With AVX-512 (8-wide double):

Operation	Scalar	SIMD (AVX-512)	Speedup
Full calculation	755	~110	~6.9×

Quality Metrics

Metric	Score	Notes
Accuracy	9/10	Within arcminutes of JPL ephemeris
Determinism	10/10	Pure function of timestamp
Timeliness	N/A	No lag—not a filter
Stability	10/10	No numerical drift

Validation

Source	Status	Notes
USNO	✅	Naval Observatory moon phase data
timeanddate.com	✅	Cross-referenced known dates
JPL Horizons	✅	Within expected tolerance

Known lunar events validated:

• New Moon: January 29, 2025 12:36 UTC → phase < 0.05
• Full Moon: February 12, 2025 13:53 UTC → phase > 0.95
• Quarters: phase ≈ 0.5

Common Pitfalls

1. Timezone confusion: The indicator uses UTC timestamps internally. Local time inputs will produce offset results. Always pass UTC or use DateTimeKind.Utc.

2. Phase interpretation: Phase 0.5 occurs at both first quarter (waxing) and last quarter (waning). To distinguish, compare current vs. previous phase values.

3. Computational cost: At ~755 cycles per bar, the indicator is moderately expensive. For high-frequency analysis with millions of bars, consider pre-computing and caching results.

4. Century limits: The polynomial coefficients are optimized for dates within a few centuries of J2000. For dates before 1800 or after 2200, accuracy degrades.

5. No warmup period: Unlike filter-based indicators, Lunar has no warmup—each output depends only on its timestamp.

6. Trading interpretation: Lunar phase correlations with market behavior are weak at best. Use as a curiosity or sentiment proxy, not as a primary signal.

References

• Meeus, J. (1991). Astronomical Algorithms. Willmann-Bell.
• Chapront-Touzé, M., & Chapront, J. (1988). "ELP 2000-85: A semi-analytical lunar ephemeris adequate for historical times." Astronomy and Astrophysics, 190, 342-352.
• U.S. Naval Observatory. "Phases of the Moon." https://aa.usno.navy.mil/data/MoonPhases