This page exists in all three languages. Each has its own address, so shared links open in the same language.
Ideas for today
Open code and data
Nhat Nguyet: open code and data for Zi Wei Dou Shu (Tử Vi), BaZi (Bát Tự) and numerology
JavaScript and Python libraries plus open data for building charts, converting lunar dates, finding auspicious hours and looking up festivals and offering prayers. For people building products, doing research or working on AI.
3.6 millionpre-read Zi Wei Dou Shu, BaZi and numerology charts
373full classical texts, 72.7 million characters
2,669classical passages in the knowledge datasets
510explainer articles
33datasets with a DOI
456offering prayers
206Vietnamese festivals
4lunar calendars: Vietnam, China, Korea, Japan
17,291test cases, all passing
How it is built: from sources to users
Where is the science?
In the method, not in predictions.
The calendar is astronomical computation: new moons checked against NASA, the 24 solar terms against IMCCE (Paris Observatory), 1900 to 2100.
Deterministic and checkable: the TypeScript and Python versions match every field of the original engine in all 17,291 test cases.
Where schools disagree, it says so and lets you switch: leap months, the Tý hour, Tứ Hóa for the Canh stem, Fire and Bell stars. The library names the book it follows; you can pick another named source's rule, and each option has its own test cases.
A technical paper documents the calendar computation: method, error budget, verification against NASA, IMCCE and JPL DE440, and an explanation for each day the Vietnamese and Chinese calendars differ.
Level of evidence: Zi Wei Dou Shu, BaZi and numerology are the rules of their schools and have not been scientifically verified.
Depth: from the Sun and Moon to the readingSolar term times against IMCCE, 4,824 instants, before and after 19 Nov 2026Data: IMCCE (Paris Observatory), 4,824 solar term instants, 1900 to 2100, 2-minute bins. Since 19 Nov 2026 solar terms are computed from the VSOP87D theory: every instant is now within a minute of IMCCE.
The Vietnamese lunar calendar differs from the Chinese one
2,814 days between 1900 and 2100 fall on different lunar dates in Vietnam time and Beijing time. Tết differs in 10 years, most visibly 1985: 21 January in Vietnam, 20 February in China.
10 years when Tết differs between Vietnam time and Beijing time, 1900 to 2100Computed with @nhatnguyet/lunar.
The library lets you choose each country's calendar; Vietnam is the default.
Calendar
Time zone
Used in
Vietnamdefault
UTC+7
VietnamVN
China
UTC+8
China, Taiwan, Hong Kong, Macau; Chinese New Year in Singapore, Malaysia, Indonesia and the PhilippinesCN, TW, HK, MO, SG, MY, ID, PH
Korea
UTC+9
KoreaKR
Japan
UTC+9
The old lunar calendar (kyūreki), used for traditional festivalsJP
Mongolia, Tibet, Thailand, Laos, Cambodia, Myanmar and India use calendars with different rules, not yet in the library.
Choose a calendar by country code
import { toLunar } from "@nhatnguyet/lunar";
toLunar("1985-01-21", { lang: "en" }); // day 1, month 1, 1985, Yi Chou
toLunar("1985-01-21", { lang: "en", country: "CN" }); // day 1, month 12, 1984, Jia Zi
What is in the repository?
Version 0.3.0: five computation packages with English names, each also published under its Vietnamese name; one Python package with the same results field by field.
Package
What it does
@nhatnguyet/lunaralso @nhatnguyet/am-lich
Lunar and Gregorian conversion for Vietnam, China, Korea, Japan and 7 more regions; stems and branches; 24 solar terms to the minute; 28 lunar mansions; na yin; auspicious hours
@nhatnguyet/ziweialso @nhatnguyet/tu-vi
Zi Wei Dou Shu: 12 palaces, star brightness, Four Transformations, Tuần and Triệt, ten-year and yearly periods, transiting stars, patterns with the classical line, school options; SVG; iztro-compatible layer
@nhatnguyet/bazialso @nhatnguyet/bat-tu
BaZi: four pillars by solar term, hidden stems, Ten Gods, symbolic stars, luck pillars, minor luck; SVG
All of the above in one Python package, same results field by field
School options
Where the books place stars differently, the library picks a default, names the book it follows, and lets you switch with schools. Defaults never change; 432 test cases cover the options. With the three Quan Shu options, the differences from iztro on 610 charts in Fire and Bell (484), the Geng-stem transformations (126) and the Gui-year Celestial Kitchen (59) drop to 0.
nhatnguyet/sach-co: 373 public domain classical texts, full text, 72.7 million characters
nhatnguyet/classical-parallel: 1,328 aligned I Ching segments: Classical Chinese with public domain English (952) and French (376) translations
terminology (in the repository): 416 terms in Vietnamese, traditional and simplified Chinese, pinyin and English
ai-eval (in the repository): 1,520 questions with computed answers (lunar dates, Tết, pillars, charts) in three languages, to test language models
history (in the repository): Tết 1900 to 2100 at UTC+7 and UTC+8, with the calendar Vietnam actually used and sources
For AI, and project templates
An MCP server (npx -y @nhatnguyet/mcp) lets AI assistants call the computations instead of guessing: calendar conversion, solar terms, auspicious hours, Zi Wei, BaZi, numerology, festivals, SVG charts. Four ready-to-use templates:
nextjs-lunar-calendar: Next.js lunar calendar page: month grid with lunar dates and solar terms, Tết countdown, Zi Wei chart from a form
telegram-bot: Telegram bot: /today, /tet, /ziwei, replies in three languages
google-sheets: Google Sheets functions =LUNARDATE(), =SEXAGENARY(), =SOLARTERM(), =SOLARDATE() in one file
jupyter: Jupyter notebook: Tết and leap months in Vietnam and China, 1900 to 2100, with charts
Where does the data come from?
Classics the readings quote: Ziwei Doushu Quanshu, Di Tian Sui, Qiongtong Baojian, Sanming Tonghui, Yuanhai Ziping, Huangji Jingshi and more. Text checked against printed editions; every passage names its book and chapter. Read more
Readings for 3.6 million charts: written by Nhat Nguyet, in three languages, in one format. Read more
Full classical texts: 373 public-domain texts (about 350 works), 72.7 million characters, mostly Classical Chinese. Read more
510 explainer articles linked to each star, pattern, useful element and life path number.
Festivals: 206 Vietnamese festivals, lunar dates converted to solar dates for each year by the same calendar library. Read more
Offering prayers: 456 texts across 155 kinds of rites. Collected from folk tradition; Nhat Nguyet edits and classifies them and does not claim authorship. Read more
No copyrighted books are included.
What can it be used for?
Breadth: the fields covered
Build products
Apps, websites and calendars: charts, lunar dates, auspicious hours and festivals computed on the user's device.
This chart has the Life palace in Hai, bureau Earth Five, and four patterns are detected.
Output
chart.bureau.name // "Earth Five"
chart.palaces[chart.lifePalace].branch // "Hai"
chart.palaces[chart.lifePalace].stars[0] // Moon (Exalted, Hua Ji)
patterns.map((p) => p.name)
// "Mechanism, Moon, Blessing and Beam", "Left and Right Assistants Meeting", "Sun Rising from Fusang", "Moon Setting in the Hai Palace"
Mechanism, Moon, Blessing and Beam
Left and Right Assistants Meeting
Sun Rising from Fusang
Moon Setting in the Hai Palace
How to reuse and credit
Code: MIT. Keep the line Copyright (c) 2026 Nhat Nguyet (nhatnguyet.org) in every copy.
Data and readings: CC BY 4.0. Commercial use and changes are allowed, as long as you credit the source.
Standard credit line: Data: Nhat Nguyet (nhatnguyet.org). Apps that show results write "According to Nhat Nguyet" where users can see it; research cites the DOI.
The Nhat Nguyet name and logo are trademarks and are not covered by the licences: do not name or present a product so that users take it for one of ours.
Privacy: the libraries compute on the device and send no data anywhere.
How to cite
Research that uses the library cites the library's DOI; research that uses the datasets cites the datasets' DOI. Both concept DOIs always resolve to the latest version.
Nhat Nguyet (2026). Nhat Nguyet: open source code and data for Zi Wei Dou Shu, BaZi and numerology. Zenodo. https://doi.org/10.5281/zenodo.24358013
BibTeX
@software{nhatnguyet_2026,
author = {{Nhat Nguyet}},
title = {Nhat Nguyet: open source code and data for Zi Wei Dou Shu, BaZi and numerology},
year = {2026},
url = {https://nhatnguyet.org/en/ma-nguon-mo},
doi = {10.5281/zenodo.24358013}
}
Questions and answers
What does the library's Zi Wei Dou Shu (Tử Vi) chart include?
A full chart: cục, the Mệnh and Thân palaces, the 14 main stars and minor stars, brightness, Tứ Hóa, Tuần and Triệt, decade and yearly periods, and transiting stars. Patterns include those of the Ziwei Doushu Quanshu.
Which packages are there?
Five npm packages for the computations and one Python package. npm: @nhatnguyet/lunar, ziwei, bazi, numerology, festivals (the same code as the Vietnamese-named am-lich, tu-vi, bat-tu, than-so-hoc, le-hoi), plus cli, mcp and widgets. Python: pip install nhatnguyet covers all five.
Can I use this data to train a commercial AI?
Yes, under CC BY 4.0. The only condition is the credit "Data: Nhat Nguyet (nhatnguyet.org)".
Does BaZi (Bát Tự) take the month pillar from the lunar month or the solar terms?
By the solar terms, as the Four Pillars method requires: the year pillar changes at Lập Xuân (Start of Spring), the month pillar on the day a new term begins, not on the first of the lunar month.
Which day counts for someone born in the Tý hour (11 pm to midnight)?
Each system keeps its own rule: BaZi starts the new day at 11 pm, Zi Wei Dou Shu uses the date as entered. The two charts can therefore land on different days; the Zi Wei Dou Shu chart carries a note about the Tý hour.
How does numerology handle Vietnamese names with diacritics?
Strip the diacritics, then use the Pythagorean table; "Đ" counts as "D". It gives the life path, expression, soul urge, personality, attitude, pinnacle and challenge numbers, plus personal year, month and day.