Method & accuracy

How the lunar calendar is computed

The Vietnamese calendar is lunisolar. Each lunar month starts on the local date of a new moon; the lunar day is the number of days since the latest new moon not after the date, plus 1.

• Gregorian dates are converted to a Julian Day Number (JDN) with the Fliegel & Van Flandern (1968) formula, as given in Meeus, Astronomical Algorithms (2nd ed., 1998).
• New moons: a mean synodic month of 29.530588853 days, plus a truncated periodic series, minus a polynomial ΔT approximation.
• Solar longitude: a truncated three-term series, with no nutation or aberration correction.
• The conversion (new moons, month 11, leap month) is the Vietnamese lunar calendar algorithm published by Hồ Ngọc Đức and reused by many libraries.
• The default time zone is UTC+7 (Vietnam), whatever the device time zone. Chinese (UTC+8) and Korean (UTC+9) lunar calendars can differ by a day, and so by a month or a year, when a new moon or principal term falls near midnight.
• Gregorian only: dates before 1582-10-15 are proleptic Gregorian.

Leap months

1. Month 11 is the lunar month containing the winter solstice.
2. If month 11 to the next month 11 spans more than 365 days, the year has 13 lunar months.
3. The leap month is then the first month after month 11 with no principal term. It takes the number of the month before it; for example, lunar 2025 has a leap 6th month.
4. The lunar year changes on the first day of month 1.

Converting a leap month the year does not have (for example a leap 6th month in 2026) returns no date.

Solar terms

• The 24 solar terms divide the Sun’s ecliptic longitude into 15° sectors: the spring equinox at 0°, the winter solstice at 270°.
• A day carries the term in effect at its local midnight, so the crossing day is the last day of the previous term. The list of calendar events puts the new term on the crossing day, as printed calendars do.

Can Chi (stems and branches)

• Day: stem = (JDN + 9) mod 10, branch = (JDN + 1) mod 12. Anchor: 2024-02-10 is a Giáp Thìn day.
• Lunar year: 1984 is Giáp Tý; stem and branch follow from the number of years since 1984.
• Lunar month: by the ngũ hổ độn rule, the stem of month 1 follows from the year stem, one stem per month; branches are fixed, month 1 = Dần … month 12 = Sửu. A leap month uses the Can Chi of the month with the same number.

Lucky days and hours (hoàng đạo)

• 12 spirits in fixed order: Thanh Long, Minh Đường, Thiên Hình, Chu Tước, Kim Quỹ, Kim Đường (Bảo Quang), Bạch Hổ, Ngọc Đường, Thiên Lao, Huyền Vũ (Nguyên Vũ), Tư Mệnh, Câu Trận. Six are lucky: Thanh Long, Minh Đường, Kim Quỹ, Kim Đường, Ngọc Đường, Tư Mệnh.
• The table as printed day by day in Vietnamese almanacs: branch Dần/Thân → Thanh Long on Tý; Mão/Dậu → Dần; Thìn/Tuất → Thìn; Tỵ/Hợi → Ngọ; Ngọ/Tý → Thân; Mùi/Sửu → Tuất; the rest follow in branch order.
• Lucky days follow the branch of the lunar month; a leap month uses the branch of the month with the same number. On 9 days where the lunar month and the solar-term month give different results, every Vietnamese almanac checked used the lunar month.
• Lucky hours follow the day’s branch; the 12 hours are clock hours: Tý 23–1, Sửu 1–3, …, Hợi 21–23. Whether 23:00–24:00 belongs to that date’s Tý hour or the next day’s depends on the school; the library treats it as that date’s.
• The twelve day officers (thập nhị trực: Kiến, Trừ, Mãn, Bình, Định, Chấp, Phá, Nguy, Thành, Thu, Khai, Bế) follow the solar-term month, which changes at each term (Lập xuân → Dần, Kinh trập → Mão, …), not at the new moon.

Verification: conversion and Can Chi

The library’s test suite (75 tests) checks the values below. The source column says exactly what the test code records.

Verification: lucky days, day officers, solar terms

Day spirits checked against calendar websites, fetched 2026-10-28. All 9 are days where the lunar month and the solar-term month give different results.

Lucky hours checked for 2025-02-01 (all 12 hours, baoquocte.vn), 2025-05-01 (vtcnews.vn, baolamdong.vn), 2026-02-10 (xemlicham.com, baohatinh.vn, ngaydep.com), 2026-10-09 (xemlicham.com, ngaydep.com) and 2026-10-28 (xemlicham.com). For every day of 2025–2026 the tests check exactly 6 lucky hours.

Day officers: 2026-10-28 and 2026-02-10 are Trừ (xemlicham.com, ngaydep.com). 2026-02-10 is lunar 23/12 but after Lập xuân: the solar-term month gives Trừ, the lunar month would give Mãn.

Solar terms: for every day of 2026–2027, term spans are 14–16 days long and their bounds are real term changes; this is an internal consistency check. Term dates have not yet been checked against an official astronomical source in the library. The Qelunai app checks the solar longitude function against the U.S. Naval Observatory 2024 equinox and solstice times.

The other sample dates in the tests (first and fifteenth days, sample death anniversaries, the start of leap month 6 of 2025) are values computed by the algorithm, not yet checked against an external source.

Limitations

• Checked against published calendars: the dates above, within 2023–2027. Outside that range results use the same method but are not checked.
• The figure "reliable for roughly 1200–3000" is stated by another library for the same family of algorithms; qelunai-lunar has not checked it.
• The truncated series and ΔT approximation can, in rare cases, move a new moon or solar term across midnight and shift a month boundary by one day.
• No test compares Vietnamese dates with Chinese or Korean ones.
• Not suitable for high-precision astronomy.

Cultural content is for reference

Lucky days and hours, the twelve day officers and death anniversaries are traditional conventions. The library follows the Vietnamese calendars checked in its tests; other traditions may differ.

The death-anniversary rules are chosen by the library and not checked against an external source: a death in a leap month is remembered in the regular month with the same number; a death on day 30 is remembered on day 30 in a 30-day month and on day 29 in a 29-day month.

This content is cultural reference, not professional advice.

Open-source library

qelunai-lunar is written in pure Dart, extracted from the Qelunai app and released under the MIT license. Source code, tests and the full methodology: https://github.com/qelunai/qelunai-lunar