Documentation

A Zi Wei Dou Shu chart engine, field-for-field identical to JS iztro, plus pattern judgement, knowledge packs and reverse birth-date lookup — with LLM-ready text output. A Rust core, callable from Rust, Python and Go.

Zi Wei Dou Shu — Chinese "Purple Star" astrology — charts a life from a birth date and hour. This library turns that birth moment into a complete chart, and into text a language model can read in one call — let the library get the chart right; let the AI do the reading.

One call produces the Markdown below — the full basic info, palace overview, patterns and the first palace, with the other eleven palaces following in the same shape. Paste it into any language model and start asking questions:

# Natal Chart 2000-8-16 Tiger hour female

## Basic Info
- Solar: 2000-8-16 · Lunar: 二〇〇〇年七月十七 · Hour: Tiger hour (03:00~05:00)
- Pillars: geng chen - jia shen - bing woo - geng yin · Zodiac: dragon · Sign: leo
- Five Elements Class: wood 3rd · Soul Star: rebel · Body Star: scholar
- Soul Palace: woo · Body Palace: xu (career) · Original Palace: chen (spouse)
- Birth-Year Mutagen: sun [A]→children, warrior [B]→wealth, moon [C]→friends, fortunate [D]→health

## Palace Overview
| Palace | Major Stars | Minor Stars | Decadal |
|---|---|---|---|
| **soul** woo | emperor([+3]) | artist([-3]) | 3-12 |
| siblings si | advisor([-1]) | — | 13-22 |
| spouse chen [Original Palace] | marshal([+3]) | helper, impulsive([-3]) | 23-32 |
| children mao | sun([+3]) [A], sage([+3]) | — | 33-42 |
| wealth yin | warrior([+1]) [B], minister([+3]) | horse | 43-52 |
| health chou | fortunate([-2]) [D], advocator([-2]) | assistant, fickle | 53-62 |
| surface zi | wolf([+2]) | spark([-3]) | 63-72 |
| friends hai | moon([+3]) [C] | — | 73-82 |
| career xu [Body Palace] | judge([0]), empress([+3]) | officer | 83-92 |
| property you | — | ideologue, driven([-3]) | 93-102 |
| spirit shen | rebel([+1]) | scholar([+1]), money | 103-112 |
| parents wei | — | aide, tangled([+3]) | 113-122 |

## Patterns
- **Empress and Minister Facing the Palace** (soul): empress([+3]), minister([+3])

## Palaces

### soul (ren woo) · Decadal 3-12
- Major Stars: emperor([+3])
- Minor Stars: artist([-3])
- Adjective Stars: refined, lucky, intercepted, instigated, considery(Y)
- Trine & Opposite: Opposite surface · Trine wealth, career
- Stem ren Flying: sage [A]→children, emperor [B]→soul, officer [C]→career, warrior [D]→wealth
- Twelve Gods: Changsheng·weak, Boshi·dragon, Suiqian·downcast, Jiangqian·disastery
- Age Fortune Years: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113

… (the other eleven palaces)

Reading the sample

Lunar is the only field that stays in Chinese in an English chart — the lunar date is rendered with Chinese numerals (二〇〇〇年七月十七 = the 17th day of the 7th lunar month, 2000). Pillars is the four pillars in iztro's own romanization — close to pinyin, but note 午 renders as woo to avoid clashing with 戊 wu. Bracket notation: ([+3]) is brightness on a -3…+3 scale, [A]/[B]/[C]/[D] are the four mutagens, and →children names the palace the mutagen star sits in. The full conventions are on the to_text page.

Whether a chart is correct has one hard standard here: zero field-level divergence from JS iztro v2.6.1, held by 716,314 golden test cases — see Accuracy. Defaults match iztro exactly; the Zhongzhou school and every boundary convention are switchable, because parity with iztro is an engineering standard, not a claim that any one school is the only correct one.

Where to start

x-iztro Guide

Installation, your first chart, Zi Wei concepts, configuration and data model. Applies to all three bindings.

Using it without writing code

What it can do, where it fits, and what to hand your engineers.

Rust API

The core library. Both the Python and Go bindings call into it.

Python API

A typed API built from dataclasses and StrEnums, with no external dependencies.

Go API

Embedded WebAssembly on a pure Go runtime, no cgo.

Semantic text (to_text)

How the text above is produced, its format, and how to wire it into a model.

Three things iztro doesn't have

These are the semantic layers above the raw chart — the part an AI pipeline actually consumes — and upstream iztro has no equivalent API for any of them:

Pattern judgement (64 rules)

One rule set shared by natal charts and horoscopes; every hit names its palace, variant and evidencing stars.

Knowledge packs

Reading texts and school attributes in swappable JSON, default pack included — doubles as RAG corpus.

Reverse lookup

From BaZi pillars or chart features back to candidate birth dates, each verified by re-charting.

Find your path

A practitioner, not a programmer → Using it without writing code
Backend / AI application engineer → Getting started, then the LLM guide
New to Zi Wei Dou Shu → the concepts, starting from stems, branches and the twelve palaces

Three programming languages, one result

All three bindings call the same Rust core, so charts come out identical field for field. The predicate methods are built on language-independent keys, so one analysis rule — written in Rust, Python or Go — yields the same answer on a chart rendered in any output language.

use x_iztro::*;

let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::EnUS, Config::default())?;
let soul = chart.palace(Palace::Soul).unwrap();

println!("{}", soul.has(&[StarKey::ZiweiMaj]));

All three report the same answer — the Soul palace of this chart holds Ziwei, the Emperor star (Python prints True; Rust and Go print true). All three use the language-independent key ziweiMaj: render the same chart in English or Japanese and the answer doesn't change.