Skip to content
Get packs

Guide · Open source

How to use ziwei-doushu: clone the Zi Wei Dou Shu chart engine

Updated · written with AI from the project's own documentation and checked against our catalogue data

ziwei-doushu is an open-source engine that calculates Zi Wei Dou Shu (紫微斗数), a traditional Chinese astrology chart, based on Ni Haixia's Tianji teaching system. This guide is for developers who want to study or reuse the TypeScript chart engine, and for students of traditional Chinese astrology who read Chinese. By the end you will know how to get the code, run its regression tests, and find the main parts of the project.

紫微斗数Renhuai123/ziwei-doushu · ★ 13.8k · MIT

Quick start

  1. 1Clone the repository. Run git clone on the GitHub repository URL to get the source code onto your machine.
  2. 2Check prerequisites. Make sure Node.js and npm are installed. The README excerpt does not state a minimum Node.js version.
  3. 3Read the full README. Open the README in the cloned folder for any build steps beyond the excerpt.
  4. 4Run the tests. Run npm test to execute the regression tests for the chart engine.
  5. 5Explore the engine files. Look at algorithm.ts, true-solar-time.ts and the other modules to see how the chart is calculated.
  6. 6Download a dataset year if needed. Pick one year file from the release, decompress it with zstd using --long=27, and verify it with the SHA256 sums.

What ziwei-doushu includes

According to the README, the project contains a full chart calculation algorithm, a four transformations (四化) system, a pattern knowledge base, and classical text data, all based on Ni Haixia's Tianji system.

It also publishes a large dataset of pre-generated charts with Chinese interpretive text. The README describes the dataset as one set of about 675,000 charts with 13 analysis dimensions each.

  • Chart calculation algorithm (algorithm.ts)
  • True solar time correction (true-solar-time.ts)
  • China daylight saving time rules (dst-cn.ts)
  • Clock time to standard time conversion (clock-adjust.ts)
  • Lunar and solar calendar conversion (lunar-solar.ts)
  • Star brightness school data (school-data.ts)

Install ziwei-doushu by cloning the repository

The README's install method is clone-and-build. The prerequisites are Node.js and npm. The README excerpt does not state a required Node.js version, so check the repository before you start.

Clone the repository from GitHub with the command below. The README does not show any further setup command in the excerpt, so read the full README in the cloned folder for build steps.

git clone https://github.com/Renhuai123/ziwei-doushu

Run the regression tests with npm test

The project has regression tests for chart calculation. Run them with npm test. According to the README, the tests run on every push and pull request through GitHub Actions, so you can use the same command to confirm the engine works on your machine.

If a test fails after you change the code, the regression tests are the first place to look.

npm test

Understand the birth hour index in the dataset

The most common mistake with the dataset is the hour field. In the dataset, hour is a Chinese double-hour index from 0 to 11, not a clock hour from 0 to 23. Index 0 is 子, 1 is 丑, and so on up to 11 for 亥.

Dataset files are named by date, hour index and gender. For example, an hour index of 11 means 亥 (21:00–23:00), not 11 a.m.

  • 0 = 子 (23:00–01:00)
  • 1 = 丑 (01:00–03:00)
  • 2 = 寅 (03:00–05:00)
  • 3 = 卯 (05:00–07:00)
  • 4 = 辰 (07:00–09:00)
  • 5 = 巳 (09:00–11:00)
  • 6 = 午 (11:00–13:00)
  • 7 = 未 (13:00–15:00)
  • 8 = 申 (15:00–17:00)
  • 9 = 酉 (17:00–19:00)
  • 10 = 戌 (19:00–21:00)
  • 11 = 亥 (21:00–23:00)

Use the dataset and check its licence

The dataset is released as zstd-compressed files split by year, so you can download only the years you need. The README gives commands for decompressing one year file and for checking SHA256 sums. The zstd command needs the --long=27 flag, which the README says is required.

The dataset is licensed CC BY 4.0, which allows commercial use if you keep the source attribution. The README says quotations from Ni Haixia's lectures are outside that licence and fall under CC BY-NC-SA 4.0.

  • Dataset license: CC BY 4.0, with attribution
  • Code license: MIT
  • Quoted Ni Haixia lecture text: CC BY-NC-SA 4.0
zstd -d --long=27 year-1990.jsonl.zst

Know the limits before you rely on the results

The README says Zi Wei Dou Shu has limits for family-relationship judgments, and that analysis involving parents, siblings and children is for reference only. It also says the bundled interface is only a demo, not the online product.

The interpretation text is in Chinese. The README is primarily in Chinese, though it links to an English summary at README.en.md. Do not treat the output as scientifically validated prediction.

What people use it for

  • Study how a traditional Zi Wei Dou Shu chart is calculated in TypeScript
  • Reuse the chart engine as a base for your own Chinese astrology tool, within the MIT licence
  • Browse or analyze the pre-generated chart interpretation dataset for one birth year
  • Research how Ni Haixia's Tianji system is organized in code and text

Frequently asked questions

What are the requirements to run ziwei-doushu?

The README lists Node.js and npm as prerequisites. It does not state the Node.js version in the excerpt, so check the full README or the project files before installing.

Is ziwei-doushu free to use?

The code is licensed under MIT. The dataset is licensed under CC BY 4.0, which allows commercial use with attribution. Quoted lecture text from Ni Haixia falls under CC BY-NC-SA 4.0.

How do I install ziwei-doushu?

Clone the GitHub repository with git clone https://github.com/Renhuai123/ziwei-doushu, then follow the README in the cloned folder. The README excerpt shows clone and npm test as the main commands.

How do I run the tests?

Run npm test from the project folder. The README says the regression tests also run automatically on pushes and pull requests through GitHub Actions.

Are there alternatives to ziwei-doushu?

Our analysis lists no comparable projects for this repository. The README does not compare it with other Zi Wei Dou Shu software.

Why does my chart or dataset hour look wrong?

The hour field is a double-hour index from 0 to 11, not a 24-hour clock value. For example, 11 means 亥, which is 21:00 to 23:00.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use ziwei-doushu if you are a developer who wants to study or reuse a TypeScript Zi Wei Dou Shu engine, or a Chinese-reading student who wants the chart dataset. Pick something else if you need English interpretations, validated predictions, or a polished end-user app, because the README says the bundled interface is only a demo.

Install options & downloads