Palace object

Palaces are where most Zi Wei analysis happens. chart.palace(...) returns a Palace, which both holds the palace's data and can trace back to its astrolabe, its opposite palace and its surrounded set.

soul = chart.palace("soulPalace")

Fields

has / not_have / has_one_of

Purpose Test which stars sit in this palace.

Zi Wei meaning Where stars fall is the basic information on a chart. "The Soul palace holds Ziwei and Tianxiang" is has(["ziweiMaj", "tianxiangMaj"]). The search covers all three groups of major, minor and adjective stars.

Signature

def has(self, stars: list[str]) -> bool
def not_have(self, stars: list[str]) -> bool
def has_one_of(self, stars: list[str]) -> bool

Parameters

Return value

Example

from x_iztro import MajorStar, MinorStar

soul = chart.palace("soulPalace")

print(soul.has([MajorStar.ZIWEI, MajorStar.TIANXIANG]))
print(soul.has_one_of([MajorStar.QISHA, MajorStar.ZIWEI]))
print(soul.not_have([MinorStar.HUOXING, MinorStar.LINGXING]))

Output

False
True
True

On this chart the Soul palace holds only Ziwei, with Tianxiang in the Wealth palace, so has — which demands both — is false.

Edge cases and pitfalls

has_mutagen / not_have_mutagen

Purpose Test whether this palace carries a given mutagen.

Zi Wei meaning Natal mutagens are determined by the birth-year stem and marked on the corresponding stars. A palace "having lu" means some star sitting in it was given lu by the birth-year stem. Note this differs from flying stars — flying looks at the palace stem, while this looks at the mark already on the star.

Signature

def has_mutagen(self, mutagen: Mutagen) -> bool
def not_have_mutagen(self, mutagen: Mutagen) -> bool

Parameters

Return value bool. Only major_stars and minor_stars are scanned — adjective stars are not considered.

Example

from x_iztro import Mutagen

children = chart.palace("childrenPalace")

print("Children palace has lu:", children.has_mutagen(Mutagen.LU))
print("Children palace lacks ji:", children.not_have_mutagen(Mutagen.JI))

Output

Children palace has lu: True
Children palace lacks ji: True

Edge cases and pitfalls

is_empty

Purpose Test whether this palace is empty.

Zi Wei meaning An "empty palace" holds none of the fourteen major stars. Empty palaces are read by borrowing the major stars of the opposite palace, and the test is a very common branch in Zi Wei analysis. Minor and adjective stars do not by default prevent a palace from counting as empty.

Signature

def is_empty(self, exclude_stars: list[str] | None = None) -> bool

Parameters

Return value bool. The order of decision is: major stars first — any present and it is not empty; then exclude_stars — a hit and it is not empty; only if neither holds is the palace empty.

Example

parents = chart.palace("parentsPalace")
print("Parents palace empty:", parents.is_empty())
print("Friends palace empty:", chart.palace("friendsPalace").is_empty())

# the Parents palace has no major star but does hold Tuoluo — counting Tuoluo makes it non-empty
print("Parents palace counting Tuoluo:", parents.is_empty(["tuoluoMin"]))

Output

Parents palace empty: True
Friends palace empty: False
Parents palace counting Tuoluo: False

On this chart only the Parents and Property palaces lack major stars. The Friends palace holds Taiyin and so is not empty.

Edge cases and pitfalls

flies_to / flies_one_of_to / not_fly_to

Purpose Test whether the mutagens flown by this palace's stem land in a target palace.

Zi Wei meaning The core technique of the flying-star school. Every palace has its own stem, and the stem determines through the mutagen table which four stars take lu, quan, ke and ji. If a transformed star happens to sit in the target palace, that is "this palace flies X into the target palace". "The Soul palace flies lu into Wealth" says that the smooth going of the Soul palace's affairs lands on wealth.

Signature

def flies_to(self, target: Palace | int | str, mutagens: Mutagen | list[Mutagen]) -> bool
def flies_one_of_to(self, target: Palace | int | str, mutagens: Mutagen | list[Mutagen]) -> bool
def not_fly_to(self, target: Palace | int | str, mutagens: Mutagen | list[Mutagen]) -> bool

Parameters

Return value

Example

from x_iztro import Mutagen, PalaceName

soul = chart.palace("soulPalace")

print("Soul flies lu into Wealth:", soul.flies_to(PalaceName.WEALTH, Mutagen.LU))
print("Soul flies lu or ji into Surface:", soul.flies_one_of_to(PalaceName.SURFACE, [Mutagen.LU, Mutagen.JI]))
print("Soul does not fly quan into Children:", soul.not_fly_to(PalaceName.CHILDREN, Mutagen.QUAN))

Output

Soul flies lu into Wealth: False
Soul flies lu or ji into Surface: False
Soul does not fly quan into Children: True

Edge cases and pitfalls

self_mutaged / self_mutaged_one_of / not_self_mutaged

Purpose Test whether this palace self-mutates.

Zi Wei meaning A self-mutagen is when a star transformed by the palace's own stem happens to sit in that palace. It reads as "releasing its own energy back into itself", unlike the directed action of flying into another palace.

Signature

def self_mutaged(self, mutagens: Mutagen | list[Mutagen]) -> bool
def self_mutaged_one_of(self, mutagens: Mutagen | list[Mutagen] | None = None) -> bool
def not_self_mutaged(self, mutagens: Mutagen | list[Mutagen] | None = None) -> bool

Parameters

Return value

Example

career = chart.palace("careerPalace")

print("Career self-mutates lu:", career.self_mutaged(Mutagen.LU))
print("Career self-mutates ji:", career.self_mutaged(Mutagen.JI))
print("Career has any self-mutagen:", career.self_mutaged_one_of())
print("Career has no self-mutagen:", career.not_self_mutaged())

Output

Career self-mutates lu: False
Career self-mutates ji: True
Career has any self-mutagen: True
Career has no self-mutagen: False

The Career palace's stem is bing, bing sends ji to Lianzhen, and Lianzhen sits right in the Career palace — hence a self-mutated ji.

Edge cases and pitfalls

mutaged_places / mutagen_stars

Purpose Get which palaces the four stars transformed by this palace's stem land in, or get those four stars themselves.

Zi Wei meaning The panoramic version of flying-star analysis: instead of asking "does it fly to that palace?", collect all four landing places for lu, quan, ke and ji at once.

Signature

def mutaged_places(self, all_palaces: list[Palace] | None = None) -> list[Palace | None]
def mutagen_stars(self, mutagens: Mutagen | list[Mutagen]) -> list[str]

Parameters

Return value mutaged_places returns a list of length 4 in the order lu, quan, ke, ji, with None in a slot whose transformed star is not on the chart. mutagen_stars returns a list of star keys in the order the mutagens were passed.

Example

soul = chart.palace("soulPalace")

for m, place in zip(["lu", "quan", "ke", "ji"], soul.mutaged_places()):
    print(f"{m} →", place.name if place else "not on this chart")

print(soul.mutagen_stars([Mutagen.LU, Mutagen.JI]))

Output

lu → children
quan → soul
ke → career
ji → wealth
['tianliangMaj', 'wuquMaj']

The Soul palace's stem is ren, whose four mutagens are Tianliang to lu, Ziwei to quan, Zuofu to ke and Wuqu to ji; those four stars sit in the Children, Soul, Career and Wealth palaces respectively.

opposite_palace / surrounded_palaces / astrolabe

Purpose Trace from a palace to its opposite palace, its surrounded set and its astrolabe.

Signature

def opposite_palace(self) -> Palace | None
def surrounded_palaces(self) -> SurroundedPalaces | None
def astrolabe(self) -> Astrolabe | None

Return value A palace constructed on its own, detached from a chart, returns None; a palace obtained from a chart query never does.

Example

soul = chart.palace("soulPalace")

print("the opposite of", soul.name, "is", soul.opposite_palace().name)
print("malefics in the surrounded set:", soul.surrounded_palaces().have_one_of(["huoxingMin", "lingxingMin"]))
print(soul.astrolabe().five_elements_class)

Output

the opposite of soul is surface
malefics in the surrounded set: True
wood 3rd

to_text

Purpose The palace's semantic text, identical to that palace's section in the natal text.

Signature

def to_text(self) -> str

Example

print(chart.palace("soul").to_text())

Output

--- soul ---
Stem-Branch: renwoo
Decadal: 3-12
Age Fortune Years: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
Twelve Gods: weak, dragon, downcast, disastery
Major Stars: emperor([+3])
Minor Stars: artist([-3])
Adjective Stars: refined, lucky, intercepted, instigated, considery(Y)

A palace constructed detached from a chart has no charting context and raises ValueError. The full format is on Semantic text.