Patterns

For: everyone. The full table of 64 patterns is at the end of the page

What a pattern is

When a particular set of stars lands on a chart in a particular arrangement, tradition gives that combination a name — 紫府同宫 ("Emperor and Empress in One Palace"), 杀破狼 ("Marshal, Rebel and Wolf"), 阳梁昌禄 ("Sun, Sage, Scholar and Money"). A named star arrangement like this is a pattern (格局).

A pattern is not a separate algorithm. It is pattern matching on a chart that has already been cast: are these stars in these palaces, are they bright enough, do they carry a transformation. Once the chart is cast, its patterns are already determined.

How x-iztro judges

Sources disagree about patterns. The same name often has both a loose and a strict reading. The principles this engine follows:

1. Findings of fact only. The output says "this arrangement holds, and here are the stars and palaces that evidence it". No auspiciousness, no strength, no score.
2. Every rule cites its source. Each rule carries the classical quotation it comes from, the reading adopted, and why that reading was chosen over the alternative.
3. Multiple readings are reported as a variant, not hidden behind a switch. When a pattern has several forms, the engine records which one matched in the variant field and lets you decide whether to accept it. 机巨同临 (Advisor and Advocator Together, ji_ju_tong_lin) in the You palace, for instance, reports variant "you", because some sources hold that the You placement does not count — the engine reports it and labels it.
4. "Broken" is a flag, not a veto. When a source's "spoiled by malefics" condition fires, the pattern is still reported, with broken set true. Whether the arrangement holds is a fact; whether it is good is interpretation.
5. "Body-or-Soul" patterns record whichever palace matched. Classical texts often say "in the Soul or Body palace", meaning either qualifies. Such patterns are judged at both palaces; palace_index records the one that actually matched, and if both match, two hits are reported.
6. Empty palaces borrow from the opposite palace. When a palace holds no major star, tradition borrows the opposite palace's majors. The evidence still records the palace the star actually occupies, not the one it was borrowed into.
7. No golden data, so the evidence is home-grown. iztro has no pattern API, so unlike chart casting there is no field-for-field golden dataset here. In its place, four layers of tests: positive and negative unit tests per rule (around 80 of them); a reproduction of all 32 example charts from the source page on real charts; a bulk sanity and invariant sweep over the 1,560 tier-1 charts, including a per-pattern count of how many charts it hits; and output snapshots of 4 charts across 6 languages — Rust writes the baseline, Python and Go read the same files back, and all three sides must agree byte for byte.

What one hit looks like

A hit is a PatternHit. The fields have the same names in all three programming languages (casing follows each language's convention; the one exception is Rust, whose struct calls palace_index simply palace — the serialized DTO key is palaceIndex everywhere):

Listing every pattern on a chart:

let en = Language::EnUS;
let chart = by_solar("1985-5-3", 9, Gender::Male, true, en, Config::default())?;

for hit in chart.patterns() {
    println!("{} | {}",
        translate_pattern(hit.key, en),
        translate_palace(chart.palaces[hit.palace].name, en));
}

Output

General and Wolf Together | surface
Empress and Minister Facing the Palace | soul
Marshal, Rebel and Wolf | surface
Money and Horse Galloping Together | soul
Officer and Helper Flanking Life | soul
Literary Nobility and Brilliance | surface
Literary Stars Facing Life | soul
Literary Stars in Hidden Support | soul
Literary Stars in Hidden Support | soul

This chart's Body palace sits on the Surface (Travel) palace, so the three "Body-or-Soul" patterns here (General and Wolf Together, Marshal-Rebel-Wolf, Literary Nobility and Brilliance) record the Surface palace rather than the Soul palace.

variant and broken come from the same set of hits:

for hit in chart.patterns():
    if hit.variant or hit.broken:
        print(f"{hit.name}: variant={hit.variant} broken={hit.broken}")

Empress and Minister Facing the Palace: variant=soul_empty broken=False
Money and Horse Galloping Together: variant=surround broken=False
Literary Stars Facing Life: variant=None broken=True
Literary Stars in Hidden Support: variant=opposite broken=False
Literary Stars in Hidden Support: variant=surround broken=False

soul_empty records that this chart's Soul palace really is empty (the classical "no major star in the Soul palace" branch, which x-iztro notes rather than requires); broken on Literary Stars Facing Life records that malefics or a Ji transformation appear in the surrounded palaces; the surround on the galloping pattern and the opposite / surround on Hidden Support are each one reading of that pattern — see the full table at the end of the page.

Natal and horoscope run the same rules

Internally the engine abstracts "the natal twelve palaces" and "the composed twelve palaces of one horoscope level" into a single view, and the rules only ever see that view. A horoscope view swaps three things and then runs every rule again:

• The Soul palace becomes that level's Soul palace. Whichever palace the decadal has moved to is the Soul palace of that level, and the twelve palace names are re-derived from it.
• That level's flowing stars are merged in. Flowing stars (the decadal/annual Lucun 运禄/流禄, the decadal/annual Wenchang 运昌/流昌 and the rest) count as their natal counterparts during judgement: seeing a flowing Lucun on a horoscope chart is, to the rules, seeing Lucun.
• Mutagens become that level's mutagens. The natal view reads birth-year transformations; the decadal view reads the transformations flown by the decadal stem, and so on.

This is why the sources' "if the natal chart has the arrangement and the decadal then arrives at it, its benefit is enjoyed" falls out for free — it is just the natal rules re-run in the decadal view. A horoscope view has no Body palace, so "Body-or-Soul" patterns are judged only at that level's Soul palace there.

let h = chart.horoscope("2025-6-1", 0)?;
for hit in h.patterns(Scope::Decadal) {
    println!("{} {:?}", translate_pattern(hit.key, en), hit.variant);
}

For the female chart of 2000-8-16, hour index 2, in the decadal view (Python version):

Marshal, Rebel and Wolf decadal None
Meeting of Wind and Cloud decadal None
Meeting of Wind and Cloud decadal yearly

The natal view of that same chart holds only "Empress and Minister Facing the Palace" — the Marshal-Rebel-Wolf pattern holds at this level only because the decadal moved the Soul palace.

Two patterns that exist only in horoscope views

Two of the 64 are transit patterns: judged only in a horoscope view, never reported on the natal chart.

风云际会's variant records both the pair of limits and how strictly they "meet": no variant or same_palace takes decadal + minor limit, yearly or yearly_same_palace takes decadal + annual (a reading some schools prefer); the same_palace forms are the strict reading — both limits' Soul palaces hold Lucun, Tianma or the Lu transformation in-palace — while the plain forms accept the surrounded set. Each pair reports one hit, two at most; on the chart above both pairs hold.

Which table decides Sun and Moon brightness

日月并明 (Sun and Moon Both Bright), 日月反背 (Sun and Moon Both Dim) and 丹墀桂墀 (Cinnabar and Cassia Steps) turn on whether the Sun and the Moon are bright, and there are two traditions for deciding that, which do not always agree:

from x_iztro import Astro, PatternConfig, BrightnessSource

chart = Astro().by_solar("1985-1-5", 11, "female", language="en-US")

print([h.name for h in chart.patterns()])
print([h.name for h in chart.patterns(
    PatternConfig(brightness_source=BrightnessSource.POSITIONAL))])

['Money and Horse Galloping Together', 'Officer and Helper Flanking Life', 'Sitting on and Facing Nobility']
['Sun and Moon Both Bright', 'Money and Horse Galloping Together', 'Officer and Helper Flanking Life', 'Sitting on and Facing Nobility']

The three switches

PatternConfig has exactly three fields. Anything that is merely a second reading of a pattern goes through variant instead; only data readings that change the finding of fact itself live here.

Turn borrow off and an empty palace stays empty, so patterns that relied on borrowing stop being reported. Turn flow_stars off and horoscope views recognise natal auxiliaries only. Neither affects chart casting.

All 64 patterns

In the order of the source page's entries. In the Class column, transit means the pattern is judged only in horoscope views; everything else is judged in both the natal and the horoscope views.

The condition column gives the gist of the formal condition. Each rule's full reading, its classical quotation, and the reasoning behind choosing between competing readings live in the implementation's doc comments (src/pattern/rules/).

Easily misread points

API reference

• Rust — patterns
• Python — patterns
• Go — Patterns

Pattern readings live in a knowledge pack

This page and the three API references cover judgement: which stars in which arrangement make a pattern form. What a formed pattern then means is interpretation, and interpretation is a school's opinion, so it lives in a knowledge pack — the bundled default pack carries classical quotations, a prose description of the conditions and a reading for each of the 64 patterns.

A hit's key is exactly the key used in the pack's patterns section:

pack = KnowledgePack.builtin()

for hit in chart.patterns():
    print(hit.name, "|", pack.pattern(hit.key).quotes[0])

Disagree with a reading? Write an overlay pack replacing those entries; the judgement is unaffected.

Sources and credit

The pattern entries, example charts and classical quotations come from the 格局 (Patterns) page of iztro-docs (MIT License, by Sylar Long); the quotations themselves are from 《紫微斗数全书》 (the Complete Book of Ziwei Doushu). The judgement engine, the pattern names in six languages, and the choices made between competing readings are x-iztro's own work — iztro itself has no corresponding API.