Config in depth

For: developers · Zi Wei enthusiasts (the school differences in the first half need no code)

Everything charting genuinely disagrees about is gathered into Config: six switches, plus two data tables that can be replaced wholesale. The defaults match JS iztro exactly, so passing no config at all gives you the same chart iztro gives.

There are two override tables besides: mutagens (a custom mutagen table) and brightness (a custom brightness table) — see Custom mutagen and brightness tables.

How to pass it

use x_iztro::data::types::*;

let config = Config {
    algorithm: Algorithm::Zhongzhou,
    year_divide: YearDivide::Exact,
    ..Config::default()
};
by_solar("2000-8-16", 2, Gender::Female, true, Language::EnUS, config)?;

from x_iztro import ChartConfig
from x_iztro.enums import Algorithm, YearDivide

config = ChartConfig(
    algorithm=Algorithm.ZHONGZHOU,
    year_divide=YearDivide.EXACT,
)
astro.by_solar("2000-8-16", 2, "female", language="en-US", config=config)

cfg := &iztro.Config{
    Algorithm:  "zhongzhou",
    YearDivide: "exact",
}
iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageEnUS, cfg)

Python and Go take only the keys you want to change and default the rest; Rust achieves the same with ..Config::default().

Year boundary: year_divide

Decides which day the year stem and branch used for charting turn over on.

The year's stem and branch are the source of a whole chain: the natal mutagens, the soul and body stars, the stems of the twelve palaces. So changing this switch can move a great deal of the chart.

When you would notice: for someone born between lunar New Year and the Beginning of Spring. Those two dates are usually a few days to a couple of weeks apart, and a birthday inside that window gets year stem-branch pairs one step apart under the two settings.

Horoscope boundary: horoscope_divide

Decides which day horoscope stems and branches, the natal month pillar and stem-branch month numbering divide on.

When you would notice: when the query date lands early in the year (between lunar New Year and the Beginning of Spring) or around any solar-term changeover, the yearly and monthly stem-branch pairs shift by one step, which in turn changes the horoscope mutagens.

Nominal-age boundary: age_divide

Decides when nominal age increments, which directly moves which palace age fortune lands on.

When you would notice: when the query date falls between lunar New Year and the person's lunar birthday. In that stretch the two settings differ by one nominal year, which puts age fortune on adjacent palaces.

Late Zi hour attribution: day_divide

Decides which day the day pillar is taken from for someone born between 23:00 and 24:00 (hour index 12).

When you would notice: only on charts with hour index 12; every other hour is unaffected.

Algorithm school: algorithm

Zhongzhou differs from the default school in four places, and the mutagen table is not one of them:

astro.by_solar("1990-11-5", 4, "male", language="en-US",
               config=ChartConfig(algorithm=Algorithm.ZHONGZHOU))

Charting perspective: astro_type

The Zhongzhou school reads one set of birth data as three charts, differing only in which palace's stem and branch the Five Elements class is taken from:

Change the Five Elements class and the placement of Ziwei and Tianfu, the twelve palace names, the Body palace branch, the twelve Changsheng gods, the decadals and the age fortune all move with it. The minor stars, the adjective stars (Tianshang, Tianshi and Tiancai follow the Soul palace and are re-placed), the twelve Boshi gods and the twelve Sui-qian and Jiang-qian gods carry over from the heaven plate.

earth = astro.by_solar("2000-8-16", 2, "female", language="en-US",
                       config=ChartConfig(astro_type=AstroType.EARTH))

earth, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageEnUS,
    &iztro.Config{AstroType: iztro.AstroEarth})

let earth = by_solar("2000-8-16", 2, Gender::Female, true, Language::EnUS,
    Config::default().with_astro_type(AstroType::Earth))?;

Rearranging onto an arbitrary stem and branch

Beyond the heaven, earth and human plates, you can rearrange onto any stem and branch as the Soul palace:

body = chart.palace(PalaceName.BODY)
earth = chart.rearranged(body.heavenly_stem_key, body.earthly_branch_key)

earth, _ := chart.Rearranged(body.HeavenlyStemKey, body.EarthlyBranchKey)

let earth = chart.rearranged(body.heavenly_stem, body.earthly_branch)?;

Rearranging onto the Body palace's stem and branch gives the same result as astro_type = earth.

Custom mutagen and brightness tables

Mutagens and brightness are where school disagreement is most concentrated. Config lets you replace tables wholesale, by key: supply the four mutagens for one heavenly stem and only that stem changes, with every other stem still on the default table. Brightness works the same way.

The mutagen table

One heavenly stem takes four stars, always in the order Lu, Quan, Ke, Ji, and all four must be given.

let config = Config::default().with_mutagens(
    HeavenlyStem::Geng,
    [StarKey::TaiyangMaj, StarKey::WuquMaj, StarKey::TiantongMaj, StarKey::TianfuMaj],
);
by_solar("2000-8-16", 2, Gender::Female, true, Language::EnUS, config)?;

cfg = ChartConfig(mutagens={
    "gengHeavenly": ["taiyangMaj", "wuquMaj", "tiantongMaj", "tianfuMaj"],
})
chart = astro.by_solar("2000-8-16", 2, "female", language="en-US", config=cfg)

cfg := &iztro.Config{Mutagens: map[string][]string{
    "gengHeavenly": {"taiyangMaj", "wuquMaj", "tiantongMaj", "tianfuMaj"},
}}

With geng switched to "Tiantong takes Ke, Tianfu takes Ji", the mutagens on this geng-year chart become:

wealth general B
children sun A
career empress D
health fortunate C

A custom mutagen table also changes every flying-star predicate — which four stars a palace stem flies out comes from the same table.

The brightness table

One star takes twelve brightness values, ordered by slot on the chart (slot 0 is the Yin palace), and all twelve must be given; use an empty value (an empty string in Python and Go) where a slot has no brightness.

cfg = ChartConfig(brightness={
    "ziweiMaj": ["miao", "wang", "de", "li", "ping", "bu",
                 "xian", "miao", "wang", "de", "li", "ping"],
})

The config travels with the chart

The config used for charting is stored on the astrolabe and horoscopes read it from there, so a horoscope always uses the same config as the chart it came from — you cannot end up with a Zhongzhou natal chart and a default-school horoscope.

chart = astro.by_solar("2000-8-16", 2, "female", language="en-US",
                       config=ChartConfig(age_divide="birthday"))
h = chart.horoscope("2024-10-1", 0)   # inherits age_divide=birthday

chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageEnUS,
    &iztro.Config{AgeDivide: "birthday"})
h, _ := chart.Horoscope("2024-10-1", 0)   // as above

Test coverage

The non-default values of the four boundary switches have 9,696 dedicated golden cases (covering combinations at both the charting and horoscope layers), and the Zhongzhou chart types have another 12,488, spanning the Beginning-of-Spring window day by day, the late Zi hour, and the days around a birthday — every boundary that produces a divergence. The custom mutagen and brightness tables have a dedicated set of tests of their own. See Accuracy.