LongPd.Dates.Julian 1.1.0

LongPd.Dates.Julian

A high-performance .NET library for converting between Gregorian, Astronomical Julian Date (JD), Modified Julian Date (MJD), Ordinal Dates, Vietnamese Lunar Calendar (Âm Lịch), and 24 Solar Terms (Tiết Khí). Engineered for low-latency systems and zero-allocation workflows.

🚀 Key Features

• Ultra-Fast: Leverages Meeus algorithms with AggressiveInlining for near-native execution speed.
• Native AOT Ready: Fully compatible with .NET 8+ Native AOT publishing.
• Zero Allocation: All conversions are allocation-free — zero GC pressure.
• Vietnamese Lunar Calendar: Full Solar → Lunar → Solar conversion using astronomical algorithms.
• 24 Solar Terms (Tiết Khí): Pure-function calculation based on Sun's ecliptic longitude.
• ReadOnlySpan LUT: Pre-computed lunar month data (2000–2100) for O(1) lookups.
• Lightweight: Zero external dependencies.

📦 Installation

dotnet add package LongPd.Dates.Julian

🛠 Usage

1. Astronomical Julian Date (JD)

using LongPd.Dates.Julian;

DateTime date = new DateTime(2026, 4, 29, 9, 30, 0, DateTimeKind.Utc);

// DateTime → JD
double jd = date.ToAstronomicalJD();        // e.g. 2461161.8958333

// JD → DateTime
DateTime back = jd.FromAstronomicalJD();    // 2026-04-29 09:30:00 UTC

2. Modified Julian Date (MJD)

// DateTime → MJD
double mjd = DateTime.UtcNow.ToModifiedJulianDate();

// MJD → DateTime
DateTime back = mjd.FromModifiedJulianDate();

3. Ordinal Date (YYYYDDD)

// DateTime → Ordinal
int ordinal = new DateTime(2026, 4, 29).ToOrdinalDate(); // 2026119

// Ordinal → DateTime
DateTime back = 2026119.FromOrdinalDate();               // 2026-04-29

4. Vietnamese Lunar Calendar (Âm Lịch) 🌙

// Gregorian → Vietnamese Lunar
var tet2025 = new DateTime(2025, 1, 29);
LunarDate lunar = tet2025.ToVietnameseLunar();
// lunar.Day=1, lunar.Month=1, lunar.Year=2025, lunar.IsLeapMonth=false

// Vietnamese Lunar → Gregorian
DateTime solar = JulianExtensions.FromVietnameseLunar(15, 8, 2024);
// Returns: 2024-09-17 (Tết Trung Thu)

Console.WriteLine(lunar); // "01/01/2025"

5. Solar Terms (Tiết Khí) ☀️

// Get Solar Term index (0–23)
int term = new DateTime(2025, 3, 21).GetSolarTerm();        // 0 = Xuân Phân

// Get Vietnamese name
string name = new DateTime(2025, 6, 22).GetSolarTermName(); // "Hạ Chí"

📊 Performance Benchmarks

Measured with BenchmarkDotNet v0.14.0 — .NET 8.0.24, X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI MediumRunJob (15 iterations × 2 launches, 10 warmup). Run on Windows 11.

✅ Zero allocations across all methods — safe for hot paths, tight loops, and real-time systems.

Note: LutDecode and NewMoon show ~0 ns because the JIT eliminates them as compile-time constants — ideal behavior. ToVietnameseLunar at ~1.2 µs and FromVietnameseLunar at ~1.1 µs reflect full astronomical computation with a pre-computed Month-11 cache (~2× faster than uncached), with zero heap allocations.

📐 Architecture

JulianExtensions (Extension Methods)
├── ToAstronomicalJD / FromAstronomicalJD
├── ToModifiedJulianDate / FromModifiedJulianDate
├── ToOrdinalDate / FromOrdinalDate
├── ToVietnameseLunar / FromVietnameseLunar
└── GetSolarTerm / GetSolarTermName

VietnameseLunarCalendar (Pure Static)
├── SunLongitude(jd)      ← pure function
├── NewMoon(k)            ← pure function
├── ToLunar / FromLunar   ← astronomical algorithm
├── GetSolarTermIndex     ← based on Sun longitude
└── ReadOnlySpan LUT      ← zero-alloc month data 2000–2100

LunarDate (readonly struct)
├── Day, Month, Year, IsLeapMonth
└── IEquatable, ToString()

🗺 Roadmap

• Full JD / MJD Support
• Inverse Conversion (JD → DateTime)
• ISO 8601 Ordinal Date (YYYYDDD)
• Vietnamese Lunar Calendar (Âm Lịch)
• 24 Solar Terms (Tiết Khí)
• ReadOnlySpan LUT (2000–2100)
• Can Chi / Heavenly Stems & Earthly Branches (v1.2.0)
• Holiday Detection — Tết, Trung Thu (v1.2.0)

📄 License

Licensed under the MIT License.
Maintained by Phạm Đình Long