Luminder is an iPhone app that shows the lunar calendar and reminds you of dates that follow the moon: memorial days, lunar birthdays, the 1st and 15th of each lunar month. Everything in the app depends on one function: given a solar date, return the lunar date. If that function is off by a single day, a memorial reminder arrives on the wrong morning.
This post is about why that function is not a one-line call to Foundation, even though iOS now has one.
Foundation has a Vietnamese calendar now
iOS 26 and macOS 26 added two calendar identifiers: .vietnamese and .dangi (Korean). .chinese has been there for years. The obvious plan was to use all three and write no astronomy at all.
Before committing to that, I ran a few known dates through the real SDK, on macOS and in the iOS 26.1 simulator. The results were the same on both, and one of them was wrong.
Tết Ất Sửu, the Vietnamese New Year of 1985, fell on 21 January 1985, and that lunar year had a leap second month. Foundation’s .vietnamese calendar says 21 January 1985 is the 1st day of the 12th month and puts New Year on 20 February, which is the Chinese date. A calendar app that gets Tết wrong is not something I wanted to ship, so Luminder does not use Foundation for the Vietnamese calendar.
Why a time zone changes the calendar
The Vietnamese and Chinese lunar calendars follow the same rules. A month starts on the day of the new moon, and the leap month is placed using the solar terms. The difference is where “the day” is measured. The Vietnamese calendar uses UTC+7, the Chinese one UTC+8, the Korean one UTC+9. When a new moon falls close to midnight, one hour decides which date the month starts on, and from there the whole year can shift.
So the calendar is really one algorithm with a time zone parameter. Luminder uses Hồ Ngọc Đức’s well-known astronomical algorithm: it computes new moons and the sun’s longitude with simplified formulas, finds the month containing the winter solstice (the 11th lunar month), and works out the leap month from there. The engine takes the UTC offset as input, which means the same code can also produce the Chinese and Korean calendars for testing.
All arithmetic runs on Julian Day Numbers, plain integers for days. No Date or TimeZone is involved inside the engine, so there is no chance of a solar date sliding by one day because of the device’s settings.
A boundary bug in the original algorithm
Porting the algorithm surfaced a bug in the reference code. To find the lunar month that contains a given day, it takes the next new moon and, if that is after the day, steps back once to the previous new moon. Near month boundaries, one step back is not always enough, and the result is a lunar date with day 0. One case: 26 March 2009 with the UTC+8 offset.
The fix is to keep stepping back until the month has actually started:
var k = estimatedNewMoonIndex(for: jdn) + 1
var monthStart = newMoonDay(k, utcOffsetHours: offset)
// The reference code steps back once with `if`; near a month boundary
// that can still land after `jdn` and produce "day 0".
while monthStart > jdn {
k -= 1
monthStart = newMoonDay(k, utcOffsetHours: offset)
}
Checking against two independent sources
An engine like this is only as good as its tests. Luminder checks it two ways: against reference tables of New Year dates and leap months, and day by day against Foundation, used as an independent oracle.
The day-by-day comparison over 1900–2100 gave this:
- UTC+8 against
.chinese: 0 days differ from 1900 to 2056. The differences in 2057 and 2097 are on days where Foundation returnsday = 0, which is a Foundation bug. - UTC+7 against
.vietnamese: 0 days differ from 1986 to 2053. Before that, Foundation is wrong around Tết 1985 (from 22 December 1984 into 1985), and before 1968 the two disagree because Foundation follows the calendar used historically while the engine computes UTC+7 astronomically. A few years from 2054 on also differ. - UTC+9 against
.dangi: two misses: 2 December 2005, and the leap month of 2017 (Korea has a leap 5th month, the engine gives a leap 6th). In both cases the new moon or a solar term falls close to midnight in Korea, and the simplified formulas are not precise enough to decide which side it lands on.
That last result settled the design. Luminder uses its own engine for the Vietnamese calendar only, and Foundation’s .chinese and .dangi for the Chinese and Korean ones. Each choice is the source that matches the official calendar.
The supported range is 1 January 1901 to 31 December 2050, the span checked against both sources; the app does not show dates outside it. Before 1968 the Vietnamese result may differ from the calendar people actually used in some years, and the project notes say so plainly.
What I took from it
A system API is still something to test, not something to trust. A handful of known dates run through the real SDK was enough to change the plan. The second lesson is that a hand-written engine and a system calendar make good oracles for each other: wherever they disagree, one of them has a bug, and the comparison tells you exactly which days to look at.