Skip to content

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 usersSources: NASA, IMCCE astronomical data; 373 classical texts; 510 explainer articles; 206 festivals; 456 offering prayers. Compute: 4 lunar calendars; 24 solar terms, can chi; Zi Wei, BaZi stars, four pillars; Numerology Vietnamese names; 2,669 classical passages, knowledge datasets. Verify: 17,291 test cases, all pass; 0.9 min new moons late vs NASA, mean; 0.27 min solar terms vs IMCCE; SHA-256, DOI a hash for every file. Release: npm, PyPI 13 npm packages, 1 Python; GitHub MIT source code; 33 datasets, Zenodo DOI; 3.6 million charts, Hugging Face. Use: Apps calendars, charts; Websites lookup tools; AI training, citations; Research statistics, calendars1. SourcesNASA, IMCCEastronomical data373classical texts510explainer articles206festivals456offering prayers2. Compute4lunar calendars24solar terms, can chiZi Wei, BaZistars, four pillarsNumerologyVietnamese names2,669classical passages,knowledge datasets3. Verify17,291test cases, all pass0.9 minnew moons late vsNASA, mean0.27 minsolar terms vs IMCCESHA-256, DOIa hash for every file4. Releasenpm, PyPI13 npm packages, 1PythonGitHubMIT source code33datasets, Zenodo DOI3.6 millioncharts, Hugging Face5. UseAppscalendars, chartsWebsiteslookup toolsAItraining, citationsResearchstatistics, calendarsHow it is built: from sources to usersSources: NASA, IMCCE astronomical data; 373 classical texts; 510 explainer articles; 206 festivals; 456 offering prayers. Compute: 4 lunar calendars; 24 solar terms, can chi; Zi Wei, BaZi stars, four pillars; Numerology Vietnamese names; 2,669 classical passages, knowledge datasets. Verify: 17,291 test cases, all pass; 0.9 min new moons late vs NASA, mean; 0.27 min solar terms vs IMCCE; SHA-256, DOI a hash for every file. Release: npm, PyPI 13 npm packages, 1 Python; GitHub MIT source code; 33 datasets, Zenodo DOI; 3.6 million charts, Hugging Face. Use: Apps calendars, charts; Websites lookup tools; AI training, citations; Research statistics, calendars1. SourcesNASA, IMCCEastronomical data373classical texts510explainer articles206festivals456offering prayers2. Compute4lunar calendars24solar terms, can chiZi Wei, BaZistars, four pillarsNumerologyVietnamese names2,669classical passages,knowledge datasets3. Verify17,291test cases, all pass0.9 minnew moons late vs NASA,mean0.27 minsolar terms vs IMCCESHA-256, DOIa hash for every file4. Releasenpm, PyPI13 npm packages, 1 PythonGitHubMIT source code33datasets, Zenodo DOI3.6 millioncharts, Hugging Face5. UseAppscalendars, chartsWebsiteslookup toolsAItraining, citationsResearchstatistics, calendars
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 readingZi Wei Dou Shu (Tử Vi): 1. Sun and Moon (true positions in the sky): new moons 0.9 min late vs NASA on average; 2. Lunar calendar (on Vietnam time, UTC+7): 14,936 calendar test cases; 3. Can chi (year, month, day, hour): 73,414 days, 1900 to 2100; 4. The chart (cục, Mệnh and Thân, 14 main stars, minor stars, brightness, Tứ Hóa, Tuần and Triệt): 777 charts, every field; 5. Decades and years (transiting stars for the year): 12 decade periods of 10 years; 6. Patterns (from the Ziwei Doushu Quanshu): 24 built, 6 proven impossible; 7. Classical passages (matched to the chart): 885 passages in ziwei-knowledge; 8. The reading (13 sections, three languages): 3.6 million pre-read charts. BaZi (Bát Tự): 1. Solar terms to the minute: 0.27 min from IMCCE; 2. Four pillars: year at Lập Xuân, month at each term; 3. Hidden stems, ten gods: 777 charts, every field; 4. Luck pillars: 10 years each; 5. Classical passages: from 7 classics.Zi Wei Dou Shu (Tử Vi)1Sun and Moontrue positions in the skynew moons 0.9 min late vsNASA on average2Lunar calendaron Vietnam time, UTC+714,936 calendar test cases3Can chiyear, month, day, hour73,414 days, 1900 to 21004The chartcục, Mệnh and Thân, 14 main stars, minorstars, brightness, Tứ Hóa, Tuần and Triệt777 charts, every field5Decades and yearstransiting stars for the year12 decade periods of 10years6Patternsfrom the Ziwei Doushu Quanshu24 built, 6 provenimpossible7Classical passagesmatched to the chart885 passages inziwei-knowledge8The reading13 sections, three languages3.6 million pre-read chartsBaZi (Bát Tự)1Solar terms to the minute0.27 min from IMCCE2Four pillarsyear at Lập Xuân, month at eachterm3Hidden stems, ten gods777 charts, every field4Luck pillars10 years each5Classical passagesfrom 7 classicsDepth: from the Sun and Moon to the readingZi Wei Dou Shu (Tử Vi): 1. Sun and Moon (true positions in the sky): new moons 0.9 min late vs NASA on average; 2. Lunar calendar (on Vietnam time, UTC+7): 14,936 calendar test cases; 3. Can chi (year, month, day, hour): 73,414 days, 1900 to 2100; 4. The chart (cục, Mệnh and Thân, 14 main stars, minor stars, brightness, Tứ Hóa, Tuần and Triệt): 777 charts, every field; 5. Decades and years (transiting stars for the year): 12 decade periods of 10 years; 6. Patterns (from the Ziwei Doushu Quanshu): 24 built, 6 proven impossible; 7. Classical passages (matched to the chart): 885 passages in ziwei-knowledge; 8. The reading (13 sections, three languages): 3.6 million pre-read charts. BaZi (Bát Tự): 1. Solar terms to the minute: 0.27 min from IMCCE; 2. Four pillars: year at Lập Xuân, month at each term; 3. Hidden stems, ten gods: 777 charts, every field; 4. Luck pillars: 10 years each; 5. Classical passages: from 7 classics.Zi Wei Dou Shu (Tử Vi)1Sun and Moontrue positions in the skynew moons 0.9 min late vs NASA on average2Lunar calendaron Vietnam time, UTC+714,936 calendar test cases3Can chiyear, month, day, hour73,414 days, 1900 to 21004The chartcục, Mệnh and Thân, 14 main stars, minor stars,brightness, Tứ Hóa, Tuần and Triệt777 charts, every field5Decades and yearstransiting stars for the year12 decade periods of 10 years6Patternsfrom the Ziwei Doushu Quanshu24 built, 6 proven impossible7Classical passagesmatched to the chart885 passages in ziwei-knowledge8The reading13 sections, three languages3.6 million pre-read chartsBaZi (Bát Tự)1Solar terms to the minute0.27 min from IMCCE2Four pillarsyear at Lập Xuân, month at each term3Hidden stems, ten gods777 charts, every field4Luck pillars10 years each5Classical passagesfrom 7 classics
Depth: from the Sun and Moon to the reading
Solar term times against IMCCE, 4,824 instants, before and after 19 Nov 2026mean 0.27 min (before: 4.2); 95% within 0.6 min (before: 9.7); largest 0.9 min (before: 14.4). from 19 Nov 2026: -2…0: 2565; 0…2: 2259. before 19 Nov 2026: -16…-14: 8; -14…-12: 53; -12…-10: 138; -10…-8: 397; -8…-6: 603; -6…-4: 845; -4…-2: 893; -2…0: 821; 0…2: 544; 2…4: 338; 4…6: 126; 6…8: 52; 8…10: 6.mean0.27 minbefore: 4.295% within0.6 minbefore: 9.7largest0.9 minbefore: 14.4before 19 Nov 2026from 19 Nov 202601,0002,000−16−12−8−40481216minutes from IMCCE (negative: earlier); bars: countTerms on a different day from IMCCE: 10 before, 0 now
Solar 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.

Further reading

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 21001903: VN 28 Jan, CN 29 Jan; 1916: VN 3 Feb, CN 4 Feb; 1935: VN 3 Feb, CN 4 Feb; 1965: VN 1 Feb, CN 2 Feb; 1968: VN 29 Jan, CN 30 Jan; 1969: VN 16 Feb, CN 17 Feb; 1985: VN 21 Jan, CN 20 Feb; 2007: VN 17 Feb, CN 18 Feb; 2030: VN 2 Feb, CN 3 Feb; 2053: VN 18 Feb, CN 19 Feb1903VN 28 JanCN 29 Jan+1 day1916VN 3 FebCN 4 Feb+1 day1935VN 3 FebCN 4 Feb+1 day1965VN 1 FebCN 2 Feb+1 day1968VN 29 JanCN 30 Jan+1 day1969VN 16 FebCN 17 Feb+1 day1985VN 21 JanCN 20 Feb+30 days2007VN 17 FebCN 18 Feb+1 day2030VN 2 FebCN 3 Feb+1 day2053VN 18 FebCN 19 Feb+1 day190019502000205021002,814 days fall on different lunar datesVN: Vietnam time (UTC+7); CN: Beijing time (UTC+8)10 years when Tết differs between Vietnam time and Beijing time, 1900 to 21001903: VN 28 Jan, CN 29 Jan; 1916: VN 3 Feb, CN 4 Feb; 1935: VN 3 Feb, CN 4 Feb; 1965: VN 1 Feb, CN 2 Feb; 1968: VN 29 Jan, CN 30 Jan; 1969: VN 16 Feb, CN 17 Feb; 1985: VN 21 Jan, CN 20 Feb; 2007: VN 17 Feb, CN 18 Feb; 2030: VN 2 Feb, CN 3 Feb; 2053: VN 18 Feb, CN 19 Feb1900200021001903VN 28 Jan · CN 29 Jan+1 day1916VN 3 Feb · CN 4 Feb+1 day1935VN 3 Feb · CN 4 Feb+1 day1965VN 1 Feb · CN 2 Feb+1 day1968VN 29 Jan · CN 30 Jan+1 day1969VN 16 Feb · CN 17 Feb+1 day1985VN 21 Jan · CN 20 Feb+30 days2007VN 17 Feb · CN 18 Feb+1 day2030VN 2 Feb · CN 3 Feb+1 day2053VN 18 Feb · CN 19 Feb+1 day2,814 days fall on different lunar datesVN: Vietnam time (UTC+7); CN: Beijing time (UTC+8)
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.

CalendarTime zoneUsed in
VietnamdefaultUTC+7VietnamVN
ChinaUTC+8China, Taiwan, Hong Kong, Macau; Chinese New Year in Singapore, Malaysia, Indonesia and the PhilippinesCN, TW, HK, MO, SG, MY, ID, PH
KoreaUTC+9KoreaKR
JapanUTC+9The 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.

PackageWhat it does
@nhatnguyet/lunaralso @nhatnguyet/am-lichLunar 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-viZi 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-tuBaZi: four pillars by solar term, hidden stems, Ten Gods, symbolic stars, luck pillars, minor luck; SVG
@nhatnguyet/numerologyalso @nhatnguyet/than-so-hocPythagorean numerology, Vietnamese names with diacritics; SVG
@nhatnguyet/festivalsalso @nhatnguyet/le-hoi206 Vietnamese festivals with their dates in any year, provinces, ethnic groups, venues; iCalendar (.ics) export
@nhatnguyet/cliCommand line: charts as grids, JSON, SVG or an .ics file; Python has the same nhatnguyet command
@nhatnguyet/mcpMCP server for AI assistants, runs locally
@nhatnguyet/widgets5 web components: today, month grid, auspicious hours, Tết countdown, converter
nhatnguyet (PyPI)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.

OptionValues (default first)What changes
fireBellvietnamese, quanshu, swap-for-female, swap-for-yin-male-yang-femaleFire Star and Bell Star
leapMonthwhole, split-at-15, next-monthThe month used for a birth in a leap month
transformationsvietnamese, quanshu, zhongzhouFour Transformations of the Geng stem
heavenlyKitchenvietnamese, chineseCelestial Kitchen in a Gui year
injuryMessengerstandard, zhongzhouCelestial Injury and Messenger
ziHournext-day-from-23, split-at-midnightBaZi: day pillar of a birth from 23:00 to 24:00

Datasets

CC BY 4.0: usable in commercial products and for AI training, with credit.

  • nhatnguyet/ziwei-readings: 1,761,936 Zi Wei charts with readings in three languages: every day 1900 to 2100, 12 hours, both genders
  • nhatnguyet/bazi-readings: 1,761,936 BaZi charts with readings, same range
  • nhatnguyet/numerology-readings: 73,414 numerology profiles, one per birth date
  • nhatnguyet/ziwei-knowledge: 2,787 Zi Wei knowledge units (a star in a palace, a pattern...), texts in three languages, 885 classical passages
  • nhatnguyet/bazi-knowledge: 973 BaZi units, 1,589 classical passages
  • nhatnguyet/numerology-knowledge: 143 numerology units, 195 passages
  • 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 coveredLunar calendars (Eastern): Code library (npm, PyPI), Open data (33 sets); 24 solar terms (Eastern): Code library (npm, PyPI), Open data (33 sets); Can chi (Eastern): Code library (npm, PyPI), Open data (33 sets); 28 lunar mansions (Eastern): Code library (npm, PyPI); Date selection (Eastern): Code library (npm, PyPI), Open data (33 sets), Code library coming; Zi Wei (Tử Vi) (Eastern): Code library (npm, PyPI); BaZi (Bát Tự) (Eastern): Code library (npm, PyPI); I Ching (Eastern): Open data (33 sets), Code library coming; Feng shui (Eastern): Open data (33 sets), Code library coming; Numerology (Western): Code library (npm, PyPI), Open data (33 sets); Astrology (Western): Open data (33 sets), Code library coming; Tarot (Western): Open data (33 sets), Code library coming; Festivals (Eastern): Code library (npm, PyPI), Open data (33 sets); Offering prayers (Eastern): Open data (33 sets), Code library comingEasternWesternCalendarLunar calendarsVN, CN, KR, JP24 solar terms4,824 term timesCan chi60-year cycle28 lunar mansionsmansion of each dayDate selectionauspicious hours; 12 day officers comingInterpretivesystemsZi Wei (Tử Vi)14 main starsBaZi (Bát Tự)four pillarsI Ching64 hexagramsFeng shuiBát Trạch, Lỗ Ban rulerNumerologyVietnamese namesAstrology12 zodiac signsTarot78 cardsBelief andcultureFestivals206, dated each yearOffering prayers456 texts, 155 ritesCode library (npm, PyPI)Open data (33 sets)Code library comingBreadth: the fields coveredLunar calendars (Eastern): Code library (npm, PyPI), Open data (33 sets); 24 solar terms (Eastern): Code library (npm, PyPI), Open data (33 sets); Can chi (Eastern): Code library (npm, PyPI), Open data (33 sets); 28 lunar mansions (Eastern): Code library (npm, PyPI); Date selection (Eastern): Code library (npm, PyPI), Open data (33 sets), Code library coming; Zi Wei (Tử Vi) (Eastern): Code library (npm, PyPI); BaZi (Bát Tự) (Eastern): Code library (npm, PyPI); I Ching (Eastern): Open data (33 sets), Code library coming; Feng shui (Eastern): Open data (33 sets), Code library coming; Numerology (Western): Code library (npm, PyPI), Open data (33 sets); Astrology (Western): Open data (33 sets), Code library coming; Tarot (Western): Open data (33 sets), Code library coming; Festivals (Eastern): Code library (npm, PyPI), Open data (33 sets); Offering prayers (Eastern): Open data (33 sets), Code library comingEasternWesternCalendarLunar calendarsVN, CN, KR, JP24 solar terms4,824 term timesCan chi60-year cycle28 lunar mansionsmansion of each dayDate selectionauspicious hours; 12 day officers comingInterpretive systemsZi Wei (Tử Vi)14 main starsBaZi (Bát Tự)four pillarsI Ching64 hexagramsFeng shuiBát Trạch, Lỗ Ban rulerNumerologyVietnamese namesAstrology12 zodiac signsTarot78 cardsBelief and cultureFestivals206, dated each yearOffering prayers456 texts, 155 ritesCode library (npm, PyPI)Open data (33 sets)Code library coming
Breadth: the fields covered

Get started in three steps

  1. Install

    One command for JavaScript, one for Python. No server, no API key.

    Terminal
    npm i @nhatnguyet/ziwei @nhatnguyet/lunar
    pip install nhatnguyet
    One engine, three things to useOriginal enginerunning on nhatnguyet.org and the appmatches every field in 17,291 test casesTypeScriptnpmPythonpipOpen data33 sets, with DOI
  2. Call one function

    Build a Zi Wei Dou Shu chart from a Gregorian birth date and clock time. lang picks English, Vietnamese or Chinese for the result.

    TypeScript
    import { castZiWei, findPatterns } from "@nhatnguyet/ziwei";
    
    // 19 Sep 1990, 8 pm (Tuất hour)
    const chart = castZiWei({ date: "1990-09-19", time: "20:00", gender: "male", lang: "en" });
    const patterns = findPatterns(chart);
    Python
    from nhatnguyet import cast_zi_wei, find_patterns
    
    # 19 Sep 1990, 8 pm (Tuất hour)
    chart = cast_zi_wei(date="1990-09-19", time="20:00", gender="male", lang="en")
    patterns = find_patterns(chart)
    Birth date in, chart out19 Sep 1990, Tuất hourMalecastZiWei()Cục, Mệnh and Thân palaces12 palaces, 14 main stars, minor starsTứ Hóa, decade and yearly periodsPatterns from the Toàn Thư
  3. Read the result

    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
    A trimmed Zi Wei Dou Shu (Tử Vi) chart: 12 palaces and main starsParentsTýTham LangFortuneSửuThiên ĐồngKhoaCự MônPropertyDầnVũ KhúcQuyềnThiên TướngCareerMãoThái DươngLộcThiên LươngFriendsThìnThất SátTravelTỵThiên CơHealthNgọTử ViWealthMùiThânChildrenThânPhá QuânSpouseDậuSiblingsTuấtLiêm TrinhThiên PhủLifeHợiThái ÂmKỵCanh Ngọ19 Sep 1990, Tuất hourThổ Ngũ Cục (Earth 5)Mệnh at Hợi

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.

Cite the library
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.