astroceleste_engine/chinese/
bazi.rs

1//! Ba Zi (八字), the Four Pillars of Destiny of a birth, cast from its
2//! [`ChineseCalendar`]. No kernel is needed.
3//!
4//! - The year pillar changes at 立春 and the month pillar at each jie term; both compare
5//!   instants, so they do not depend on the clock the birth was recorded in.
6//! - The day and hour pillars are cast on true solar time at the birthplace (the default)
7//!   or on civil time. The Zi hour (23:00-01:00) belongs to the next day by default; with
8//!   `zi_hour = "split"` the day changes at midnight and the late Zi hour keeps its day,
9//!   its stem still taken from the next day's.
10//! - The luck pillars (大運) run forward from the month pillar for a yang year and a man
11//!   or a yin year and a woman, backward otherwise. They start after the days from the
12//!   birth to the next (forward) or previous (backward) jie term, three days to a year.
13
14use serde::Serialize;
15
16use super::calendar::{day_number, ChineseCalendar, SolarTerm, LICHUN};
17use super::{
18    branch_element, cycle_index, polarity, stem_element, year_cycle_index, ANIMALS, BRANCHES,
19    ELEMENTS, STEMS,
20};
21use crate::error::EngineError;
22use crate::instant::UtcInstant;
23
24const TROPICAL_YEAR: f64 = 365.242_19;
25const MICROS_PER_MINUTE: f64 = 60_000_000.0;
26
27/// The stems hidden in each branch (藏干): main qi first, then middle and residual qi.
28const HIDDEN_STEMS: [&[usize]; 12] = [
29    &[9],       // 子 癸
30    &[5, 9, 7], // 丑 己癸辛
31    &[0, 2, 4], // 寅 甲丙戊
32    &[1],       // 卯 乙
33    &[4, 1, 9], // 辰 戊乙癸
34    &[2, 6, 4], // 巳 丙庚戊
35    &[3, 5],    // 午 丁己
36    &[5, 3, 1], // 未 己丁乙
37    &[6, 8, 4], // 申 庚壬戊
38    &[7],       // 酉 辛
39    &[4, 7, 3], // 戌 戊辛丁
40    &[8, 0],    // 亥 壬甲
41];
42
43/// Share of its branch each hidden stem carries in the element balance, by how many the
44/// branch holds.
45fn hidden_weights(count: usize) -> &'static [f64] {
46    match count {
47        1 => &[1.0],
48        2 => &[0.7, 0.3],
49        _ => &[0.6, 0.3, 0.1],
50    }
51}
52
53/// NaYin (納音) of each pair of the sexagenary cycle, 甲子乙丑 first.
54const NAYIN: [&str; 30] = [
55    "sea_metal",
56    "furnace_fire",
57    "forest_wood",
58    "roadside_earth",
59    "sword_metal",
60    "mountain_fire",
61    "stream_water",
62    "rampart_earth",
63    "wax_metal",
64    "willow_wood",
65    "spring_water",
66    "roof_earth",
67    "thunder_fire",
68    "pine_wood",
69    "river_water",
70    "sand_metal",
71    "foothill_fire",
72    "plain_wood",
73    "wall_earth",
74    "gold_leaf_metal",
75    "lamp_fire",
76    "heavenly_river_water",
77    "highway_earth",
78    "hairpin_metal",
79    "mulberry_wood",
80    "creek_water",
81    "sand_earth",
82    "sky_fire",
83    "pomegranate_wood",
84    "ocean_water",
85];
86
87/// The NaYin code of a pair of the sexagenary cycle (0-29).
88pub(crate) fn nayin(pair: usize) -> &'static str {
89    NAYIN[pair]
90}
91
92/// The twelve stages of life (十二長生), from Birth.
93const LIFE_STAGES: [&str; 12] = [
94    "birth",
95    "bath",
96    "cap_and_belt",
97    "coming_of_age",
98    "prosperity",
99    "decline",
100    "sickness",
101    "death",
102    "tomb",
103    "extinction",
104    "conception",
105    "nurture",
106];
107
108/// The branch where each stem is born (長生); yang stems go forward through the
109/// branches, yin stems backward.
110const BIRTH_BRANCH: [usize; 10] = [11, 6, 2, 9, 2, 9, 5, 0, 8, 3];
111
112/// The Ten Gods (十神) by the element relation to the Day Master (same, produced by it,
113/// controlled by it, controlling it, producing it) and same or opposite polarity.
114const TEN_GODS: [[&str; 2]; 5] = [
115    ["friend", "rob_wealth"],
116    ["eating_god", "hurting_officer"],
117    ["indirect_wealth", "direct_wealth"],
118    ["seven_killings", "direct_officer"],
119    ["indirect_resource", "direct_resource"],
120];
121
122/// When the day changes around the Zi hour.
123#[derive(Debug, Clone, Copy, PartialEq, Eq)]
124enum ZiHour {
125    /// 23:00: the whole Zi hour belongs to the next day.
126    NextDay,
127    /// Midnight: the late Zi hour (夜子時) keeps its day.
128    Split,
129}
130
131/// How to cast the pillars.
132#[derive(Debug, Clone)]
133pub struct BaziOptions<'a> {
134    /// Cast the day and hour on true solar time at the birthplace (`true`, the default)
135    /// or on civil time.
136    pub solar_time: bool,
137    /// "next_day" (default): the day changes at 23:00; "split": at midnight.
138    pub zi_hour: &'a str,
139    /// "male" or "female": sets the direction of the luck pillars, which are left out
140    /// without it.
141    pub sex: Option<&'a str>,
142    /// How many ten-year luck pillars to list (default 10).
143    pub luck_pillars: u8,
144}
145
146impl Default for BaziOptions<'_> {
147    fn default() -> Self {
148        BaziOptions {
149            solar_time: true,
150            zi_hour: "next_day",
151            sex: None,
152            luck_pillars: 10,
153        }
154    }
155}
156
157/// A stem hidden in a branch.
158#[derive(Debug, Clone, PartialEq, Serialize)]
159pub struct HiddenStem {
160    /// Stem code, e.g. "gui".
161    pub stem: &'static str,
162    /// Its element.
163    pub element: &'static str,
164    /// Its relation to the Day Master.
165    pub ten_god: &'static str,
166    /// Its share of the branch in the element balance.
167    pub weight: f64,
168}
169
170/// A stem and a branch: one of the four pillars, or a luck pillar.
171#[derive(Debug, Clone, PartialEq, Serialize)]
172pub struct Pillar {
173    /// Heavenly Stem code, e.g. "jia".
174    pub stem: &'static str,
175    /// Earthly Branch code, e.g. "zi".
176    pub branch: &'static str,
177    /// Position in the sexagenary cycle, 0 (甲子) to 59 (癸亥).
178    pub cycle: u8,
179    /// Element of the stem.
180    pub element: &'static str,
181    /// "yang" or "yin", of the stem and the branch alike.
182    pub polarity: &'static str,
183    /// Element of the branch.
184    pub branch_element: &'static str,
185    /// Animal of the branch.
186    pub animal: &'static str,
187    /// The stem's relation to the Day Master; `None` for the Day Master itself.
188    pub ten_god: Option<&'static str>,
189    /// The stems hidden in the branch, main qi first.
190    pub hidden_stems: Vec<HiddenStem>,
191    /// NaYin element of the pair, e.g. "sea_metal".
192    pub nayin: &'static str,
193    /// The Day Master's stage of life in this branch.
194    pub life_stage: &'static str,
195}
196
197/// Weight of each element among the eight characters (stems count 1, each branch 1
198/// shared among its hidden stems).
199#[derive(Debug, Clone, PartialEq, Serialize)]
200pub struct ElementBalance {
201    /// 木
202    pub wood: f64,
203    /// 火
204    pub fire: f64,
205    /// 土
206    pub earth: f64,
207    /// 金
208    pub metal: f64,
209    /// 水
210    pub water: f64,
211}
212
213/// A solar term the pillars refer to.
214#[derive(Debug, Clone, PartialEq, Serialize)]
215pub struct TermMoment {
216    /// Pinyin code, e.g. "jingzhe".
217    pub name: String,
218    /// ISO 8601 UTC.
219    pub utc: String,
220}
221
222/// A date of the lunisolar calendar.
223#[derive(Debug, Clone, PartialEq, Serialize)]
224pub struct LunarDate {
225    /// The lunar year: the Gregorian year its New Year falls in.
226    pub year: i32,
227    /// Month number, 1-12.
228    pub month: u8,
229    /// Whether the month is intercalary.
230    pub leap: bool,
231    /// Day of the month, 1-30.
232    pub day: u8,
233    /// Stem of the lunar year.
234    pub year_stem: &'static str,
235    /// Branch of the lunar year.
236    pub year_branch: &'static str,
237    /// Animal of the lunar year: the popular "Chinese zodiac sign", which changes at the
238    /// New Year rather than at 立春.
239    pub animal: &'static str,
240}
241
242/// A ten-year luck pillar.
243#[derive(Debug, Clone, PartialEq, Serialize)]
244pub struct LuckPillar {
245    /// Age at which it starts, years.
246    pub start_age: f64,
247    /// Start, ISO 8601 UTC.
248    pub start: String,
249    /// End (the next one's start), ISO 8601 UTC.
250    pub end: String,
251    /// Its stem and branch.
252    pub pillar: Pillar,
253}
254
255/// The luck pillars (大運).
256#[derive(Debug, Clone, PartialEq, Serialize)]
257pub struct Luck {
258    /// "forward" or "backward" through the sexagenary cycle from the month pillar.
259    pub direction: &'static str,
260    /// Age at which the first one starts, years.
261    pub start_age: f64,
262    /// The pillars in order.
263    pub pillars: Vec<LuckPillar>,
264}
265
266/// The Four Pillars of a birth.
267#[derive(Debug, Clone, PartialEq, Serialize)]
268pub struct Bazi {
269    /// "solar" or "civil": the clock the day and hour pillars were cast on.
270    pub time_basis: &'static str,
271    /// "next_day" or "split".
272    pub zi_hour: &'static str,
273    /// Local civil time of birth, `YYYY-MM-DDTHH:MM:SS`.
274    pub civil_time: String,
275    /// True solar time of birth at the birthplace, `YYYY-MM-DDTHH:MM:SS`.
276    pub solar_time: String,
277    /// Year pillar (changes at 立春).
278    pub year: Pillar,
279    /// Month pillar (changes at each jie term).
280    pub month: Pillar,
281    /// Day pillar; its stem is the Day Master.
282    pub day: Pillar,
283    /// Hour pillar.
284    pub hour: Pillar,
285    /// Stem of the day pillar, the self.
286    pub day_master: &'static str,
287    /// Element of the Day Master.
288    pub day_master_element: &'static str,
289    /// The weight of each element among the eight characters.
290    pub elements: ElementBalance,
291    /// The jie term that opened the birth month.
292    pub month_term: TermMoment,
293    /// The next jie term after the birth.
294    pub next_term: TermMoment,
295    /// The birth date in the lunisolar calendar; `None` when the calendar lacks it.
296    pub lunar_date: Option<LunarDate>,
297    /// The luck pillars; `None` without the native's sex.
298    pub luck: Option<Luck>,
299}
300
301fn invalid(message: &str) -> EngineError {
302    EngineError::InvalidInput(message.to_string())
303}
304
305/// `YYYY-MM-DDTHH:MM:SS` of a wall-clock instant.
306fn wall_clock(instant: UtcInstant) -> String {
307    let (y, m, d, hh, mm, ss, _) = instant.civil();
308    format!("{y:04}-{m:02}-{d:02}T{hh:02}:{mm:02}:{ss:02}")
309}
310
311/// The relation of `stem` to the Day Master `master`.
312fn ten_god(master: usize, stem: usize) -> &'static str {
313    let relation = (stem_element(stem) + 5 - stem_element(master)) % 5;
314    TEN_GODS[relation][usize::from(master % 2 != stem % 2)]
315}
316
317/// The stage of life of `stem` in `branch`.
318fn life_stage(stem: usize, branch: usize) -> &'static str {
319    let birth = BIRTH_BRANCH[stem] as i64;
320    let steps = if stem % 2 == 0 {
321        branch as i64 - birth
322    } else {
323        birth - branch as i64
324    };
325    LIFE_STAGES[steps.rem_euclid(12) as usize]
326}
327
328/// The pillar at `cycle` (0-59), seen from the Day Master `master`.
329fn pillar(cycle: usize, master: usize, is_master: bool) -> Pillar {
330    let (stem, branch) = (cycle % 10, cycle % 12);
331    let hidden = HIDDEN_STEMS[branch];
332    Pillar {
333        stem: STEMS[stem],
334        branch: BRANCHES[branch],
335        cycle: cycle as u8,
336        element: ELEMENTS[stem_element(stem)],
337        polarity: polarity(stem),
338        branch_element: ELEMENTS[branch_element(branch)],
339        animal: ANIMALS[branch],
340        ten_god: (!is_master).then(|| ten_god(master, stem)),
341        hidden_stems: hidden
342            .iter()
343            .zip(hidden_weights(hidden.len()))
344            .map(|(&h, &weight)| HiddenStem {
345                stem: STEMS[h],
346                element: ELEMENTS[stem_element(h)],
347                ten_god: ten_god(master, h),
348                weight,
349            })
350            .collect(),
351        nayin: NAYIN[cycle / 2],
352        life_stage: life_stage(master, branch),
353    }
354}
355
356fn balance(cycles: [usize; 4]) -> ElementBalance {
357    let mut weights = [0.0f64; 5];
358    for cycle in cycles {
359        let (stem, branch) = (cycle % 10, cycle % 12);
360        weights[stem_element(stem)] += 1.0;
361        let hidden = HIDDEN_STEMS[branch];
362        for (&h, &w) in hidden.iter().zip(hidden_weights(hidden.len())) {
363            weights[stem_element(h)] += w;
364        }
365    }
366    let round = |x: f64| (x * 100.0).round() / 100.0;
367    ElementBalance {
368        wood: round(weights[0]),
369        fire: round(weights[1]),
370        earth: round(weights[2]),
371        metal: round(weights[3]),
372        water: round(weights[4]),
373    }
374}
375
376/// A solar term with its parsed moment.
377type Dated<'a> = (UtcInstant, &'a SolarTerm);
378
379/// The last term at or before `birth` matching `pick`, and the first after it.
380fn around<'a>(
381    terms: &'a [Dated<'a>],
382    birth: UtcInstant,
383    pick: impl Fn(&SolarTerm) -> bool,
384) -> (Option<&'a Dated<'a>>, Option<&'a Dated<'a>>) {
385    let before = terms.iter().rev().find(|(t, s)| *t <= birth && pick(s));
386    let after = terms.iter().find(|(t, s)| *t > birth && pick(s));
387    (before, after)
388}
389
390fn term_moment((instant, term): &Dated) -> TermMoment {
391    TermMoment {
392        name: term.name.clone(),
393        utc: instant.isoformat(),
394    }
395}
396
397fn lunar_date(calendar: &ChineseCalendar, day: i64) -> Result<Option<LunarDate>, EngineError> {
398    for month in &calendar.lunar_months {
399        let start = month.start_day()?;
400        if start <= day && day < start + i64::from(month.days) {
401            let cycle = year_cycle_index(month.year);
402            return Ok(Some(LunarDate {
403                year: month.year,
404                month: month.month,
405                leap: month.leap,
406                day: (day - start + 1) as u8,
407                year_stem: STEMS[cycle % 10],
408                year_branch: BRANCHES[cycle % 12],
409                animal: ANIMALS[cycle % 12],
410            }));
411        }
412    }
413    Ok(None)
414}
415
416/// Cast the Four Pillars of a birth at `birth` (UTC), at `longitude` (degrees east) where
417/// civil time was `utc_offset_minutes` ahead of UTC, from its `calendar`
418/// ([`chinese_calendar`](super::calendar::chinese_calendar) of the same moment).
419pub fn bazi(
420    calendar: &ChineseCalendar,
421    birth: UtcInstant,
422    longitude: f64,
423    utc_offset_minutes: f64,
424    options: &BaziOptions,
425) -> Result<Bazi, EngineError> {
426    let zi_hour = match options.zi_hour {
427        "" | "next_day" => ZiHour::NextDay,
428        "split" => ZiHour::Split,
429        _ => return Err(invalid("zi_hour must be \"next_day\" or \"split\"")),
430    };
431    let male = match options.sex {
432        None | Some("") => None,
433        Some("male") => Some(true),
434        Some("female") => Some(false),
435        Some(_) => return Err(invalid("sex must be \"male\" or \"female\"")),
436    };
437
438    let terms = calendar
439        .solar_terms
440        .iter()
441        .map(|t| Ok((t.instant()?, t)))
442        .collect::<Result<Vec<_>, EngineError>>()?;
443    let (lichun, _) = around(&terms, birth, |t| t.longitude == LICHUN);
444    let (month_term, next_term) = around(&terms, birth, |t| t.jie);
445    let (Some(lichun), Some(month_term), Some(next_term)) = (lichun, month_term, next_term) else {
446        return Err(invalid("the calendar does not cover the birth"));
447    };
448
449    // Year and month: by the solar terms.
450    let year_cycle = year_cycle_index(lichun.0.civil().0);
451    let month_offset = usize::from((month_term.1.longitude + 360 - LICHUN) % 360 / 30);
452    let month_stem = ((year_cycle % 10) % 5 * 2 + 2 + month_offset) % 10;
453    let month_cycle = cycle_index(month_stem, (2 + month_offset) % 12);
454
455    // Day and hour: by the local clock.
456    let to_micros = |minutes: f64| (minutes * MICROS_PER_MINUTE).round() as i64;
457    let civil = birth.add_micros(to_micros(utc_offset_minutes));
458    let solar = birth.add_micros(to_micros(longitude * 4.0 + calendar.equation_of_time));
459    let local = if options.solar_time { solar } else { civil };
460    let hour = local.civil().3;
461    let date = day_number(local);
462    let late_zi = hour >= 23;
463    let day = if late_zi && zi_hour == ZiHour::NextDay {
464        date + 1
465    } else {
466        date
467    };
468    let day_cycle_of = |day: i64| (day - 11).rem_euclid(60) as usize;
469    let day_cycle = day_cycle_of(day);
470    let master = day_cycle % 10;
471    // 子 is 23:00-01:00, 丑 01:00-03:00, …
472    let hour_branch = (hour as usize).div_ceil(2) % 12;
473    let hour_day_stem = day_cycle_of(if late_zi { date + 1 } else { date }) % 10;
474    let hour_cycle = cycle_index((hour_day_stem % 5 * 2 + hour_branch) % 10, hour_branch);
475
476    let luck = male.map(|male| {
477        let forward = male == (year_cycle % 2 == 0);
478        let days = if forward {
479            next_term.0.seconds_since(&birth)
480        } else {
481            birth.seconds_since(&month_term.0)
482        } / 86_400.0;
483        let start_age = days / 3.0;
484        let at_age = |age: f64| birth.plus_days(age * TROPICAL_YEAR).isoformat();
485        let pillars = (1..=i64::from(options.luck_pillars))
486            .map(|k| {
487                let cycle = (month_cycle as i64 + if forward { k } else { -k }).rem_euclid(60);
488                let age = start_age + 10.0 * (k - 1) as f64;
489                LuckPillar {
490                    start_age: age,
491                    start: at_age(age),
492                    end: at_age(age + 10.0),
493                    pillar: pillar(cycle as usize, master, false),
494                }
495            })
496            .collect();
497        Luck {
498            direction: if forward { "forward" } else { "backward" },
499            start_age,
500            pillars,
501        }
502    });
503
504    Ok(Bazi {
505        time_basis: if options.solar_time { "solar" } else { "civil" },
506        zi_hour: match zi_hour {
507            ZiHour::NextDay => "next_day",
508            ZiHour::Split => "split",
509        },
510        civil_time: wall_clock(civil),
511        solar_time: wall_clock(solar),
512        year: pillar(year_cycle, master, false),
513        month: pillar(month_cycle, master, false),
514        day: pillar(day_cycle, master, true),
515        hour: pillar(hour_cycle, master, false),
516        day_master: STEMS[master],
517        day_master_element: ELEMENTS[stem_element(master)],
518        elements: balance([year_cycle, month_cycle, day_cycle, hour_cycle]),
519        month_term: term_moment(month_term),
520        next_term: term_moment(next_term),
521        lunar_date: lunar_date(calendar, day)?,
522        luck,
523    })
524}
astroceleste_engine/chinese/bazi.rs

astroceleste_engine/chinese/
bazi.rs
