Star placement

Use this layer when you do not want a whole chart and only need "which palace does Lucun land in?" or "how are the adjective stars distributed on this chart?".

from x_iztro import star

Every index is a palace index: 0 is the Yin palace, 11 the Chou palace.

Shared parameters

The entry points that take birth data all share one parameter set:

birth = dict(solar_date="2000-8-16", time_index=2, gender="female", language="en-US")

get_start_index

Purpose Find the starting palaces of Ziwei and Tianfu.

Zi Wei meaning Ziwei is the anchor of the whole chart, located from the five elements class and the lunar day by the Ziwei placement rule; the other thirteen major stars then spread out from Ziwei and Tianfu. Tianfu's position mirrors Ziwei's.

Signature

def get_start_index(solar_date, time_index, gender="male", fix_leap=True,
                    language="zh-CN", config=None, from_stem=None, from_branch=None) -> StartIndex

Return value StartIndex, with the fields ziwei_index and tianfu_index.

Example

s = star.get_start_index(**birth)
print(s)
print(s.ziwei_index, s.tianfu_index)

Output

StartIndex(ziwei_index=4, tianfu_index=8)
4 8

Landing indices per group

The following six entry points share a shape: they take birth data and return a dataclass whose fields are all palace indices.

Example

print(star.get_lu_yang_tuo_ma_index(**birth))
print(star.get_chang_qu_index(**birth))
print(star.get_luan_xi_index(**birth))

Output

LuYangTuoMaIndex(lu_index=6, yang_index=7, tuo_index=5, ma_index=0)
ChangQuIndex(chang_index=6, qu_index=4)
LuanXiIndex(hongluan_index=9, tianxi_index=3)

Qingyang sits one palace ahead of Lucun and Tuoluo one behind — the direct expression of the mnemonic "Qingyang before Lucun, Tuoluo after".

get_daily_star_index / get_monthly_star_index / get_yearly_star_index

Purpose Get the landing palaces of the adjective stars placed by day, month and year.

Zi Wei meaning Adjective stars are grouped by how they are placed: day-based stars count forward from a minor star's position, starting at day one, to the birth day; month-based stars are located from the lunar month; year-based stars are the largest group and start from the year stem or year branch.

Return value

Example

d = star.get_daily_star_index(**birth)
m = star.get_monthly_star_index(**birth)
y = star.get_yearly_star_index(**birth)

print(d)
print(m.yuejie_index, m.tianyao_index, m.tianxing_index)
print(y.xianchi_index, y.huagai_index, y.tianshang_index, y.tianshi_index)

Output

DailyStarIndex(santai_index=0, bazuo_index=10, enguang_index=9, tiangui_index=7)
0 5 1
7 2 9 11

Edge cases and pitfalls

get_major_star / get_minor_star / get_adjective_star

Purpose Get the complete distribution of major, minor and adjective stars across the twelve palaces.

Signature

def get_major_star(...) -> list[list[Star]]
def get_minor_star(...) -> list[list[Star]]
def get_adjective_star(...) -> list[list[Star]]

Return value A list of twelve, indexed by palace index. Each item is that palace's list of Stars, possibly empty.

Example

major = star.get_major_star(**birth)

for i, stars in enumerate(major[:5]):
    print(i, [s.name for s in stars])

Output

0 ['general', 'minister']
1 ['sun', 'sage']
2 ['marshal']
3 ['advisor']
4 ['emperor']

Edge cases and pitfalls

get_changsheng12 / get_boshi12 / get_yearly12

Purpose Get how the four groups of twelve gods are arranged across the twelve palaces.

Zi Wei meaning Each group is twelve marks filling the twelve palaces, exactly one per palace: the Changsheng gods start from the five elements class with direction from gender and year-branch polarity; the Boshi gods start from Lucun with the same direction rule; the Sui-qian gods run forward from the year branch, and the Jiang-qian gods start from the trine group of the year branch.

Signature

def get_changsheng12(...) -> list[str]
def get_boshi12(...) -> list[str]
def get_yearly12(...) -> dict[str, list[str]]

Return value get_changsheng12 and get_boshi12 return a list of twelve keys, indexed by palace index. get_yearly12 returns Yearly12, whose fields suiqian12 and jiangqian12 are each a list of twelve keys.

Example

print(star.get_changsheng12(**birth)[:4])
print(star.get_boshi12(**birth)[:4])

y = star.get_yearly12(**birth)
print(y.suiqian12[:4])
print(y.jiangqian12[:4])

Output

['jue', 'mu', 'si', 'bing']
['faylian', 'zhoushu', 'jiangjun', 'xiaohao']
['diaoke', 'bingfu', 'suijian', 'huiqi']
['suiyi', 'xiishen', 'huagai', 'jiesha']

These are keys rather than translated names; use i18n.translate(key) to display them.

get_changsheng12_start_index / get_jiangqian12_start_index

Purpose Get just the starting palace of two of the god groups, without laying out the whole cycle.

Zi Wei meaning The Changsheng starting point is set by the five elements class: water 2nd starts at Shen, wood 3rd at Hai, metal 4th at Si, earth 5th at Shen, fire 6th at Yin. The Jiangxing starting point is set by the trine group of the year branch: yin/woo/xu years at Woo, shen/zi/chen years at Zi, si/you/chou years at You, hai/mao/wei years at Mao.

Signature

def get_changsheng12_start_index(five_elements_class: FiveElementsClass | str) -> int
def get_jiangqian12_start_index(branch: EarthlyBranch | str) -> int

Return value int, 0–11. Neither function needs birth data.

Example

print(star.get_changsheng12_start_index("water2nd"), star.get_changsheng12_start_index("fire6th"))
print(star.get_jiangqian12_start_index("ziEarthly"), star.get_jiangqian12_start_index("wuEarthly"))

Output

6 0
10 4

Water 2nd puts Changsheng in Shen (index 6), fire 6th in Yin (index 0).

get_horoscope_star

Purpose Get the scope-star distribution of a horoscope layer.

Zi Wei meaning Scope stars are the ten stars a horoscope produces: Tiankui, Tianyue, Wenchang, Wenqu, Lucun, Qingyang, Tuoluo, Tianma, Hongluan and Tianxi. Where they land is fixed by that layer's stem and branch, and their names change with the layer. The yearly layer carries one extra star, Nianjie.

Signature

def get_horoscope_star(
    stem: HeavenlyStem | str,
    branch: EarthlyBranch | str,
    scope: Scope | str,
    language: str = "zh-CN",
) -> list[list[Star]]

Parameters

Return value A list of twelve, indexed by palace index.

Star names per layer

The keys take the form yunlu (decadal Lucun), liulu (yearly), yuelu (monthly), rilu (daily), shilu (hourly).

Example

decadal = star.get_horoscope_star("jiaHeavenly", "ziEarthly", "decadal", "en-US")
print([[s.name for s in p] for p in decadal[:4]])

origin = star.get_horoscope_star("jiaHeavenly", "ziEarthly", "origin", "en-US")
print([[s.name for s in p] for p in origin[:2]])

Output

[['money(D)', 'horse(D)'], ['driven(D)', 'attractive(D)'], [], ['scholar(D)']]
[['money', 'horse'], ['driven', 'attractive']]

In en-US the layer shows up as the suffix on the name — (D) for the decadal layer — rather than as a different word, while the keys stay yunlu, yunma and so on.

Edge cases and pitfalls

Low-level placement

The functions above all start from birth data, deriving the year pillar, the Soul palace and the corrected lunar month internally before placing anything. This group takes those intermediates directly and is reusable in a pipeline of your own.

Example

from x_iztro import star

chart = Astro().by_solar("2000-8-16", 2, "female", language="en-US")
year_branch = chart.raw_dates.chinese_date.yearly_keys[1]

print(star.get_huo_ling_index(year_branch, 2))
print(star.get_gu_gua_index(year_branch))
print(star.get_chang_qu_index_by_heavenly_stem("jiaHeavenly"))

Output

HuoLingIndex(huo_index=2, ling_index=10)
GuGuaIndex(guchen_index=3, guasu_index=11)
ChangQuIndex(chang_index=3, qu_index=7)

Edge cases and pitfalls