Open-Source Ziwei Doushu Engine: Charting the Ancient Art
An MIT-licensed engine plus an enormous CC BY dataset turns traditional Purple Star astrology into reproducible code.
What the Repository Contains
Why This Matters for Developers
Trade-Offs and Caveats
Ziwei Doushu (紫微斗数), often called Purple Star Astrology, has historically lived in proprietary tools, textbooks, and oral tradition. The Renhuai123/ziwei-doushu repository takes a different stance: it makes the chart-casting algorithm available under the MIT license and pairs it with a large interpretation dataset released under CC BY 4.0. The guiding idea, stated plainly in the project README, is that the algorithm is public traditional wisdom and should not be locked behind a wall.
## What the Repository Contains
The engine follows the Ziwei Doushu system taught in Ni Haixia's Tianji series. It includes the complete chart-building algorithm, the Four Transformations (四化) system, a pattern knowledge base, and source material from classical texts. Beyond the code, the v4.0 interpretation dataset is the standout: 674,976 charts, a 13-dimensional interpretation record for each, 8,774,688 total segments, about 30,000 Chinese characters per chart, and roughly 56.6 GB when decompressed. It covers real calendar dates from 1950 through 2026, which makes it a substantial resource for research or application prototypes.
## Why This Matters for Developers
Most developers who want to build astrology tools face the same problem: recreating the chart rules from fragmented references is slow and error-prone. This project reduces that work to cloning a repository. The MIT license makes integration into web apps, mobile apps, or backend APIs straightforward, while the dataset is separately licensed and can power search, recommendations, or exploratory language-model work. It also serves as a bridge between Chinese cultural heritage and modern software engineering.
## Trade-Offs and Caveats
Large generated datasets are not the same as verified expert advice. The interpretation content is produced systematically and reflects one specific teaching lineage; some practitioners may disagree with the Tianji approach or with how ambiguous cases are resolved. As a developer, you should treat the chart engine as deterministic, useful logic, and the dataset as source material that needs curation before being exposed directly to end users. Cultural and ethical care matters here, especially because people sometimes consult such systems for personal decisions.
Overall, this is a rare combination of open code, open data, and clear licensing in a niche area. If you are working on Chinese metaphysics, astrology, or culturally grounded AI products, it is worth studying the repository and adapting the pieces that fit your use case.
A rare, well-licensed open-source foundation for Ziwei Doushu development and dataset research.