1. Philosophy: Zi Wei Dou Shu is a treasure of traditional Chinese astrology, and Ni Haixia laid out its authentic system in Tian Ji (《天纪》). We hope technology can bring more people to learn it.

We open-source the charting algorithm and the knowledge base because we believe algorithms are openly shared traditional wisdom and shouldn’t be locked behind walls. The real value lies in the depth of interpretation, a carefully polished user experience, and what we build up by running the service day after day.

2. About the project: A Zi Wei Dou Shu (紫微斗数, "Purple Star Astrology") charting engine following the teaching system of Ni Haixia's Tian Ji (倪海厦《天纪》). It includes the full charting algorithm, the Four Transformations (四化), a pattern knowledge base, public-domain classical texts, and a 518,400-chart sample dataset, plus a 674,976-chart × 13-topic interpretation dataset (v4.0, 2026-10-15): 8.77 million readings, about 20.4 billion characters of text, 56.6 GB uncompressed — up from 518,400 charts and 33.1 GB in v3.0.

Dataset	Charts	Readings	Uncompressed	Years	Characters per chart
v4.0 interpretations (2026-10-15)	674,976	8,774,688	56.6 GB	1950–2026 (real dates only)	~30,000
v3.0 samples	518,400	6,739,200	33.1 GB	1924–1983	~21,000
Change	+30%	+30%	+71%	+17 years	+44%

_{v3.0 characters per chart estimated from a 2,160-chart sample; all other figures are full counts. Both versions have 13 topics per chart.}

This repo is an open snapshot of the engine behind ouranic.cn, synced from production periodically.

Note: on readings of family relations

Zi Wei Dou Shu has known limits when it comes to family relations (parents, siblings, children and so on). In Tian Ji, Master Ni Haixia said that "Dou Shu has always been somewhat weaker at reading family relations" (lecture 2, part 1 · 00:25:27). Among traditional methods, Tie Ban Shen Shu has its own strengths in checking family relations (00:03:15); Master Ni still kept Zi Wei Dou Shu at the core because it can be read together with geography, surroundings and human affairs, forming a complete system that knows the heavens above, the earth below and human affairs in between (00:25:43). Readings about family relations are therefore for reference only; the Parents, Siblings and Children sections on ouranic.cn carry the same note.

Latest update (2026-10-15)

• Interpretation dataset v4.0 released: 674,976 charts (every real solar date 1950–2026 × 12 double-hours × male/female) × 13 topics = 8,774,688 readings; 161 MB compressed, 56.6 GB uncompressed (v3.0: 33.1 GB), 77 per-year files plus an all-years bundle. See Release v4.0-13d and the dataset section below.
• The 13 topics were revised sentence by sentence against the verbatim transcripts of Ni Haixia's Tian Ji and the original Complete Book: untraceable citations removed or replaced with verbatim quotes (with episode and timestamp), sentences about impossible transformations removed, conditions spelled out, two-sided sentences resolved per chart, and health now follows Master Ni's whole-chart method instead of mapping stars to organs by Five Element. (The judgment library itself stays closed; the results are in the v4.0 dataset.)
• Engine sync (PR #39): chinaDSTSpan(year) in dst-cn.ts; longitudes for province-administered county-level cities in cities.ts.
• License: DATASET-LICENSE now covers v4.0; quotations from Tian Ji inside the readings are not covered by the dataset license.

2026-11-02 addendum: the late Zi hour day change now uses true solar time, the same clock as the hour branch (#63). With a birthplace, 23:30 by the clock at 100°E (22:10 true solar time, the Hai hour) stays on the same day instead of becoming "Hai hour of the next day"; without a birthplace there is no correction and results are unchanged, matching ouranic.cn. An invalid leap-month policy now throws instead of silently charting as "same month" (#71). Thanks to Bortlesboat and xunguangzlj-cloud for the PRs and Verchiel666 for reviewing.

2026-10-31 addendum: the live platform is now OURANIC and has moved from metisziwei.com to ouranic.cn; old links redirect automatically. Code, datasets and licenses in this repo are unchanged.

2026-10-27 addendum: engine sync. true-solar-time.ts accepts utcOffsetMinutes (the birthplace's standard UTC offset) for births outside China; results inside China are unchanged. New clock-adjust.ts converts a clock reading taken under daylight saving time (or an older time zone) to standard time; it never crosses midnight and is meant to run only when the user confirms. Correction: the engine detects China DST but has never subtracted it automatically; the table below said otherwise.

What the engine handles

Feature	Notes
True solar time	Longitude offset plus the equation of time, so births near hour boundaries are not off by one double-hour
China DST	1986–1991 daylight-saving periods are detected (not subtracted automatically; convert the clock reading with clock-adjust.ts once the user confirms)
Leap months	Four configurable conventions (previous month / next month / split by day / same month)
Late Zi hour	23:00–23:59 is charted on the next day, 00:00–00:59 on the same day; with a birthplace the cutoff uses true solar time (same as the hour branch); switchable
Star brightness	7 levels (庙 旺 得 利 平 不 陷); brightness tables of different schools are switchable, not hard-coded
Four Transformations	Natal, decade (大限) and annual (流年) transformations, plus flying-star self-transformations
Twelve spirits	Natal layer by year branch, annual layer by the annual branch
Patterns	1,100+ lines of pattern rules (紫府同宫, 日月并明, 七杀朝斗, …)

Engine code lives in lib/ziwei/ (entry point: generateChart() in algorithm.ts). Inputs are a Gregorian date and an hour branch index 0–11 (子 = 0 … 亥 = 11), not a clock hour.

Quick start

git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm ci
npm run dev          # charting demo at http://localhost:3000/chart

npm run typecheck    # TypeScript check
npm test             # charting regression tests

No API key is needed for charting. The open-source version contains no backend routes: AI interpretation (/api/interpret) and compatibility analysis (/api/heming) return 404 until you implement them yourself.

What is not included

The interpretation database (lib/ziwei/db-analysis.ts is a placeholder), AI prompts, all /api/* backend routes, user accounts, payments, and deployment configuration.

Interpretation dataset v4.0 (674,976 charts × 13 topics, 2026-10-15)

Download from Releases → v4.0-13d: 77 per-year files year-YYYY.jsonl.zst (161 MB compressed, 56.6 GB uncompressed (v3.0: 33.1 GB)), plus SHA256SUMS.txt and MANIFEST.json.

• Every solar date from 1950 to 2026 (only dates that actually exist) × 12 double-hours × male/female; one chart per line (JSON Lines).
• Fields: k key, y/m/d solar date, h double-hour index 0–11 (not clock hours), g gender, ms first major star of the Life Palace (null if empty), t character counts, c the 13 topic readings in Markdown.
• Generated deterministically by the charting engine and the 2026-10-15 judgment library (content version ca268829f7a9), no AI involved. The 13 topics were revised sentence by sentence against the verbatim transcripts of Ni Haixia's Tian Ji and the original Complete Book of Zi Wei Dou Shu.
• Natal-chart view only: age-based rewording, the appended Master Ni rule sections and AI readings shown on the website are not included. Charts use the double-hour index directly, without true-solar-time correction.
• Decompress with zstd -d --long=27 year-1990.jsonl.zst (--long=27 is required).
• Quotations from Ni Haixia's Tian Ji inside the readings are not covered by the dataset license: they are short citations with episode and timestamp, and copyright in the original lectures remains with the rights holder; bulk reuse of those quotations falls under the CC BY-NC-SA 4.0 terms of chapter 5. The Complete Book is in the public domain.
• License: same as v3.0 — CC BY 4.0, commercial use OK with attribution (except the quotations above).
• A single all-years bundle ziwei-interp-v4-all.tar is also provided.

Sample dataset (518,400 charts)

Download from Releases (3 parts, 5.5 GB in total). Each sample is generated from birthInfo:

• year / month / day: Gregorian date, 1924–1983 (one full 60-year cycle), days 1–30 of every month
• hour: hour branch index 0–11 (子 = 0 … 亥 = 11), not a clock hour; the hHH part of each file name is the same index
• gender: male / female; longitude is fixed at 120 (no local true-solar-time correction)

Known issue: about 2,520 samples (0.49%) carry dates that do not exist: Feb 30, and Feb 29 in non-leap years. The engine silently rolled them over to Mar 1–2, so their content duplicates the Mar 1–2 samples. Filter out month = 2 && day = 30, and month = 2 && day = 29 in non-leap years. From 2026-10-03 the engine rejects non-existent dates.

Ni Haixia's original words (Tian Ji, Zi Wei part)

docs/tianji-ziwei/ holds 1,848 quotes from the Zi Wei lectures of Tian Ji (14 lectures plus 2 supplements), each linked to the second it was said in the video. Taken from the sister repo nihai-tianji-corpus.

License

Part	License
Code (lib/, app/, components/)	MIT
Sample dataset (Releases)	CC BY 4.0: commercial use OK with attribution
Classical texts	Public domain
Ni Haixia quotes (docs/tianji-ziwei/)	CC BY-NC-SA 4.0: non-commercial only

Contributions are welcome. Please read CONTRIBUTING.md; questions go to Discussions.