How does Nhat Nguyet check its data and computations?

Every number from Nhat Nguyet comes from one source of truth, the reference engine, and then passes five layers of checks: external comparison, invariants, mutation, a shared test set for every programming language, and hashed releases. The test set now has 17,291 cases; on 19 November 2026 both the TypeScript and Python ports passed all of them. "Scientific basis" here means a method anyone can recheck, not a promise that the traditional arts predict correctly.

What does one source of truth mean?
- The engine, written in Go and running nhatnguyet.org and the apps every day, is the source. The TypeScript and Python libraries are ports and never set their own answers.
- Lookup tables in articles are generated by the engine, never typed by hand, so the table in an article and the tool's result are the same thing.
- Test cases are machine-generated from the engine and never edited by hand. If a case fails and the original answer looks wrong, the case is not changed to match; the issue is recorded and reported.
What does the test set contain?
| Subject | Cases | Contents |
|---|---|---|
| Lunar calendar, solar terms | 14,936 | solar to lunar 11,039, lunar to solar 3,696, the 24 solar terms for 201 years; includes UTC+8 and UTC+9 cases |
| Bát Tự | 777 | four pillars, hidden stems, ten gods, life stages, symbolic stars, luck pillars, 2026 annual pillar |
| Tử Vi | 777 | bureau, Mệnh, Thân, every star, transformations, Tuần Triệt, ten-year periods, 2026 yearly period, patterns |
| Numerology | 600 | profiles by name and birth date, year 2026 |
| Festivals | 201 | the solar date of every lunar and solar festival, each year from 1900 to 2100 |
| Total | 17,291 |
How comparison works: deep field-by-field comparison, skipping prose fields; floats within 1e-9; arrays compared in order; every field present in the original must be present in the port, and vice versa.
Why must it be deterministic?
The same input must give the same bytes, or nothing can be compared. The code never reads the clock, the reading year is fixed at 2026, and sampling uses a fixed seed. As a result the readings for about 3.6 million charts rerun to identical bytes, and anyone who downloads them can check.
What do invariant tests catch that test cases do not?
Test cases only say two versions agree; invariants say the original agrees with something independent. Expectations are computed from rules or classical texts, never copied from the table under test:
- The 64 hexagrams: the eight trigrams by Zhu Xi's mnemonic; number, Chinese name, upper and lower trigrams and palace of all 64 by the two verses in Zhu Xi's Zhouyi benyi; inverse, reverse, nuclear and changed hexagrams by bit operations; the 32 King Wen pairs.
- Calendar: the lunar calendar rebuilt from NASA and IMCCE data alone and compared with the engine, matching 2,459 of 2,461 months (see the lunar calendar and the 24 solar terms).
- Stems and branches: the 60-cycle never breaks on any day from 1900 to 2100; the 28 mansions stay locked to weekdays (see stems, branches and cycles).
- Tử Vi: charts are scanned to keep six Toàn Thư patterns provably impossible (see patterns from the Toàn Thư).
What are mutation tests for?
To be sure a test fails when the data is wrong. A test that has never failed may be testing nothing. For the 64-hexagram tables we deliberately broke each table in turn and confirmed the test caught it; the numerology suite feeds in wrong answers to make sure the comparison never lets a mismatch slip by.
What are hashed releases and the DOI?
- Every open-data release has a code: the date plus the first eight characters of the manifest's sha256 hash, such as 2026.10.27-cd6fca71. The same content always gives the same code, whatever day it is built.
- Every file has its own sha256 in the manifest. A published release is never overwritten; changed data means a new release.
- The 33 datasets have the concept DOI 10.5281/zenodo.23009396, are declared on Wikidata (Q141589952), and can be downloaded on the Open data page.
- A model profile comes with each release: formulas, comparison files with sha256 hashes, and measured errors.
Why does "the rows are there" not mean "it is right"?
Because a check only catches the errors its author thought of. Three stumbles, all since fixed, taught us this:
- Lines with vertical bars are not always a table. A review in September 2026 counted as "having a table" articles in which readers saw only a block of text: tables missing the separator row, tables cut in two by a line break inside a cell, two adjacent tables merged into one. 22 articles in all three languages; the first check only measured "has a separator row" and reported clean while 12 articles still had broken tables.
- The tables were right but the prose was wrong. The rule "tables come from the engine" protects tables, but a sentence such as "Đại Trạch Thổ is the nạp âm of Ất Mùi and Canh Tý" is not a table; a review the same month found 40 wrong nạp âm statements in the prose of 18 of 30 articles. Prose is now checked against the engine.
- A table having a column does not mean the column is used. In five independent places a translation sat in the table but the function reading the table never returned it; only measuring the output revealed it.
So we measure output, on real pages, and along a dimension other than the one we already had in mind, rather than trusting the source code. Fixes and open issues are listed on the Corrections page.
How can you check for yourself?
- Run the test set against your own library, in any language: the post on testing a library with the test cases.
- The code, test cases and manifests are on the Open code and data page.
If you reuse these figures, please credit: Data: Nhat Nguyet (nhatnguyet.org).





