ziwei 0.1.0__py3-none-any.whl

ziwei/__init__.py

@@ -0,0 +1 @@
+"""紫微斗数排盘与知识库。"""

ziwei/birth.py

@@ -0,0 +1,253 @@
+"""原始出生记录与解析后计算输入；本模块不转换公历和农历。"""
+
+from dataclasses import dataclass
+from datetime import date, datetime, time
+from enum import StrEnum
+
+from ziwei.calendar import LunarAlgorithm
+from ziwei.config import ChartConfig, DayRollover, YearBoundary
+from ziwei.ganzhi import Dizhi, Ganzhi, Yinyang, year_ganzhi
+from ziwei.timezone import FixedOffset, IanaTimezone, ResolvedTime, resolve_civil_time
+
+
+class Gender(StrEnum):
+  """出生记录中的性别，未知不代填。"""
+
+  MALE = "男"
+  FEMALE = "女"
+  UNKNOWN = "未知"
+  男 = MALE
+  女 = FEMALE
+  未知 = UNKNOWN
+
+
+class TimePrecision(StrEnum):
+  """原始民用钟点的记录精度；仅有日期时使用日。"""
+
+  DAY = "日"
+  HOUR = "时"
+  MINUTE = "分"
+  SECOND = "秒"
+  MICROSECOND = "微秒"
+  日 = DAY
+  时 = HOUR
+  分 = MINUTE
+  秒 = SECOND
+  微秒 = MICROSECOND
+
+
+def shichen_from_time(clock: time) -> Dizhi:
+  """按无时区民用钟面取时辰；不改变日期或应用换日口径。
+
+  时辰范围取香港天文台《天干和地支》表三，子时跨23:00至次日01:00；本接口采用左闭右开区间。
+  """
+  if type(clock) is not time:
+    raise TypeError("钟点须为 time")
+  if clock.tzinfo is not None or clock.fold != 0:
+    raise ValueError("钟点不得携带时区或 fold")
+  return tuple(Dizhi)[((clock.hour + 1) // 2) % 12]
+
+
+def _check_metadata(longitude_deg: float | None, place: str | None, source: str | None) -> None:
+  if longitude_deg is not None:
+    if isinstance(longitude_deg, bool) or not isinstance(longitude_deg, int | float):
+      raise TypeError("经度须为数值或 None")
+    if not -180 <= longitude_deg <= 180:
+      raise ValueError("经度须为-180至180之间的有限值，东经为正")
+  for value in (place, source):
+    if value is not None and not isinstance(value, str):
+      raise TypeError("地点与来源说明须为字符串或 None")
+
+
+def _check_lunar_date(
+  year: int, month: int, day: int, is_leap_month: bool, shichen: Dizhi | None
+) -> None:
+  for value, maximum, name in ((year, 9999, "年"), (month, 12, "月"), (day, 30, "日")):
+    if type(value) is not int:
+      raise TypeError(f"农历{name}须为整数，不接受 bool")
+    if not 1 <= value <= maximum:
+      raise ValueError(f"农历{name}须在1至{maximum}之间")
+  if type(is_leap_month) is not bool:
+    raise TypeError("闰月标志须为 bool")
+  if shichen is not None and not isinstance(shichen, Dizhi):
+    raise TypeError("时辰须为 Dizhi 成员或 None")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class GregorianBirthRecord:
+  """原始公历日期、钟点、精度与时区；不携带派生的年干支。
+
+  birth_time=None 表示钟点未知，精度须为日。经度仅保存，不在此执行真太阳时换算。
+  """
+
+  birth_date: date
+  birth_time: time | None
+  time_precision: TimePrecision
+  timezone: IanaTimezone | FixedOffset
+  gender: Gender
+  longitude_deg: float | None = None
+  place: str | None = None
+  source: str | None = None
+
+  def __post_init__(self) -> None:
+    if type(self.birth_date) is not date:
+      raise TypeError("公历日期须为 date，不接受 datetime")
+    if not isinstance(self.time_precision, TimePrecision):
+      raise TypeError("精度须为 TimePrecision 成员")
+    if not isinstance(self.timezone, IanaTimezone | FixedOffset):
+      raise TypeError("时区须为 IanaTimezone 或 FixedOffset")
+    if not isinstance(self.gender, Gender):
+      raise TypeError("性别须为 Gender 成员")
+    _check_metadata(self.longitude_deg, self.place, self.source)
+    if self.birth_time is None:
+      if self.time_precision is not TimePrecision.日:
+        raise ValueError("钟点未知时精度须为日")
+      return
+    shichen_from_time(self.birth_time)
+    if self.time_precision is TimePrecision.日:
+      raise ValueError("日精度的记录不得携带钟点")
+    components = (self.birth_time.minute, self.birth_time.second, self.birth_time.microsecond)
+    lower = {
+      TimePrecision.时: components,
+      TimePrecision.分: components[1:],
+      TimePrecision.秒: components[2:],
+      TimePrecision.微秒: (),
+    }
+    if any(lower[self.time_precision]):
+      raise ValueError("钟点包含低于所声明记录精度的分量")
+
+  @property
+  def shichen(self) -> Dizhi | None:
+    """原始民用钟面的时辰；未应用真太阳时或换日口径。"""
+    return None if self.birth_time is None else shichen_from_time(self.birth_time)
+
+  def resolve_time(self) -> ResolvedTime:
+    """消歧民用钟点；未知钟点或不支持的历史时标显式失败。"""
+    if self.birth_time is None:
+      raise ValueError("出生钟点未知，不能解析民用时刻")
+    return resolve_civil_time(datetime.combine(self.birth_date, self.birth_time), self.timezone)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LunarBirthRecord:
+  """原始农历年月日、闰月标志与时辰；只核值域，不核该月存在性及月长。"""
+
+  year: int
+  month: int
+  day: int
+  is_leap_month: bool
+  shichen: Dizhi | None
+  gender: Gender
+  longitude_deg: float | None = None
+  place: str | None = None
+  source: str | None = None
+
+  def __post_init__(self) -> None:
+    _check_lunar_date(self.year, self.month, self.day, self.is_leap_month, self.shichen)
+    if not isinstance(self.gender, Gender):
+      raise TypeError("性别须为 Gender 成员")
+    _check_metadata(self.longitude_deg, self.place, self.source)
+
+
+BirthRecord = GregorianBirthRecord | LunarBirthRecord
+"""公历与农历的原始出生记录，保留各自不同的输入信息。"""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CalculationInput:
+  """解析层的输出形状，由resolver.resolve从原始记录生成。
+
+  ganzhi_year 是解析层按所选换年口径得到的纪年编号，不一定等于 lunar_year。
+  原始记录和实际口径随值保存；阴阳及年干支由该编号派生，不维护可互相矛盾的副本。
+  原始时辰未知时，解析时辰不得变为已知。
+  lunar_algorithm 与 lunar_algorithm_version 记录所用农历算法及 celestial 版本；
+  apparent_solar 记录是否采用真太阳时路径；day_rolled 记录晚子时归次日是否顺延；
+  ut1_jd 与 lichun_jd 记录立春换年所比较的出生瞬间与立春时刻（UT1 日数），
+  纯民用正月初一路径为 None。
+  resolved_time保留解析层实际取得的钟面、UTC、偏移和时区数据版本；没有取得瞬间时为None。
+  为兼容直接构造，对resolved_time只检查它是ResolvedTime或None；完整盘另核其存在性及与原始记录的关系。
+  """
+
+  record: BirthRecord
+  lunar_year: int
+  month: int
+  day: int
+  is_leap_month: bool
+  shichen: Dizhi | None
+  ganzhi_year: int
+  config: ChartConfig
+  lunar_algorithm: LunarAlgorithm
+  lunar_algorithm_version: str
+  apparent_solar: bool
+  day_rolled: bool
+  ut1_jd: float | None
+  lichun_jd: float | None
+  resolved_time: ResolvedTime | None = None
+
+  def __post_init__(self) -> None:
+    if not isinstance(self.record, BirthRecord):
+      raise TypeError("原始记录须为公历或农历出生记录")
+    if self.resolved_time is not None and not isinstance(self.resolved_time, ResolvedTime):
+      raise TypeError("已解析时刻须为 ResolvedTime 或 None")
+    _check_lunar_date(self.lunar_year, self.month, self.day, self.is_leap_month, self.shichen)
+    if self.record.shichen is None and self.shichen is not None:
+      raise ValueError("原始记录的未知时辰不得变为已知")
+    year_ganzhi(self.ganzhi_year)
+    if not isinstance(self.config, ChartConfig):
+      raise TypeError("口径须为显式 ChartConfig")
+    if not isinstance(self.lunar_algorithm, LunarAlgorithm):
+      raise TypeError("农历算法须为 LunarAlgorithm 成员")
+    if not isinstance(self.lunar_algorithm_version, str) or not self.lunar_algorithm_version:
+      raise ValueError("农历算法版本不得为空")
+    for value, label in (
+      (self.apparent_solar, "真太阳时路径"),
+      (self.day_rolled, "晚子时顺延"),
+    ):
+      if type(value) is not bool:
+        raise TypeError(f"{label}标志须为 bool")
+    for instant, label in ((self.ut1_jd, "出生瞬间"), (self.lichun_jd, "立春时刻")):
+      if instant is not None and not isinstance(instant, float):
+        raise TypeError(f"{label} UT1 日数须为 float 或 None")
+    if self.config.year_boundary is YearBoundary.立春 and self.ut1_jd is None:
+      raise ValueError("立春换年必须记录出生瞬间的 UT1 日数")
+    if self.ut1_jd is not None and self.lichun_jd is None:
+      raise ValueError("记录出生瞬间时必须同时记录立春时刻")
+    if self.lichun_jd is not None and self.config.year_boundary is not YearBoundary.立春:
+      raise ValueError("立春时刻只属于立春换年口径")
+    if self.day_rolled and self.shichen is not Dizhi.子:
+      raise ValueError("晚子时顺延只发生在子时")
+    if self.day_rolled and self.config.day_rollover is DayRollover.早晚子时同日:
+      raise ValueError("晚子时顺延与早晚子时同日口径矛盾")
+    if self.day_rolled:
+      if not isinstance(self.record, GregorianBirthRecord) or self.record.birth_time is None:
+        raise ValueError("晚子时顺延需要原始记录含公历钟点")
+      if not self.apparent_solar and self.record.birth_time.hour != 23:
+        raise ValueError("民用路径的晚子时顺延需要原始钟点在 23 时")
+    if self.apparent_solar and (
+      not isinstance(self.record, GregorianBirthRecord) or self.record.longitude_deg is None
+    ):
+      raise ValueError("真太阳时路径需要公历记录与经度")
+    if (
+      self.config.year_boundary is YearBoundary.农历正月初一 and self.ganzhi_year != self.lunar_year
+    ):
+      raise ValueError("正月初一换年口径下干支纪年须等于农历年")
+
+  @property
+  def gender(self) -> Gender:
+    """保留原始记录的性别，不代填未知项。"""
+    return self.record.gender
+
+  @property
+  def year_ganzhi(self) -> Ganzhi:
+    """按已经确定的干支纪年编号查表。"""
+    return year_ganzhi(self.ganzhi_year)
+
+  @property
+  def yinyang(self) -> Yinyang:
+    """用于性别阴阳组合的年干阴阳，不作性别推断。"""
+    return self.year_ganzhi.tiangan.yinyang
+
+  def require_complete(self) -> None:
+    """拒绝未知时辰或性别，供完整命盘入口调用；本方法不排盘。"""
+    if self.shichen is None or self.gender is Gender.未知:
+      raise ValueError("完整命盘需要已知时辰与性别")

ziwei/bureau.py

@@ -0,0 +1,54 @@
+"""五行局。
+
+五行局由命宫干支的纳音五行定：水二局、木三局、金四局、土五局、火六局。
+《紫微斗數全書》卷二《安身命例》以「丙寅丁卯炉中火」断火局（维基文库修订1963110），
+同页局图以水二局、木三局、金四局、土五局、火六局分列；王亭之中州派《紫微斗数初级讲义》
+定五行局一节同样列举水二木三金四土五火六。局数即大限首限起始虚岁。
+"""
+
+from enum import StrEnum
+
+from ziwei.ganzhi import Ganzhi, Wuxing, nayin
+
+
+class WuxingJu(StrEnum):
+  """具名五行局；局数即大限首限起始虚岁。"""
+
+  SHUI_ER = "水二局"
+  MU_SAN = "木三局"
+  JIN_SI = "金四局"
+  TU_WU = "土五局"
+  HUO_LIU = "火六局"
+  水二局 = SHUI_ER
+  木三局 = MU_SAN
+  金四局 = JIN_SI
+  土五局 = TU_WU
+  火六局 = HUO_LIU
+
+  @property
+  def number(self) -> int:
+    """局数（水二木三金四土五火六），即大限首限起始虚岁。"""
+    return tuple(WuxingJu).index(self) + 2
+
+
+_BUREAU_BY_ELEMENT: dict[Wuxing, WuxingJu] = {
+  Wuxing.水: WuxingJu.SHUI_ER,
+  Wuxing.木: WuxingJu.MU_SAN,
+  Wuxing.金: WuxingJu.JIN_SI,
+  Wuxing.土: WuxingJu.TU_WU,
+  Wuxing.火: WuxingJu.HUO_LIU,
+}
+
+
+def bureau_of(minggong_ganzhi: Ganzhi) -> WuxingJu:
+  """由命宫干支的纳音五行定五行局。"""
+  if not isinstance(minggong_ganzhi, Ganzhi):
+    raise TypeError("五行局须查命宫干支")
+  return _BUREAU_BY_ELEMENT[nayin(minggong_ganzhi)]
+
+
+def bureau_number(ju: WuxingJu) -> int:
+  """局数（水二木三金四土五火六）。"""
+  if not isinstance(ju, WuxingJu):
+    raise TypeError("五行局须为 WuxingJu 成员")
+  return ju.number

ziwei/calendar.py

@@ -0,0 +1,305 @@
+"""celestial-calendar 0.8.0 的具体适配；导入本模块不初始化 celestial。
+
+公开函数在函数体内 `import celestial_calendar`，包导入与知识查询不会加载原生历法库。
+所选农历算法、支持范围与 celestial 版本随解析结果保存；超出支持范围或闰月/日组合
+不存在时显式失败。
+
+## 时标合同
+
+celestial 的节气时刻是 UT1，民用输入是 UTC 或固定偏移；本模块只比较同一时标下的值。
+
+- 立春比较：出生瞬间换算到 UT1 日数（`utc_to_ut1_jd`），与立春 UT1 时刻
+  （`lichun_jd`）直接比较，不直接比较钟面数值。
+- 换算采用 celestial 的 modelled-UT1 定义：TT=UTC+(ΔAT+32.184s)，UT1=TT-ΔT；
+  ΔAT 取 1972 年起闰秒表（最后一步 2017-01-01 后恒 37s，与 celestial 的 leap_second
+  表一致），ΔT 取 `delta_t` 的 DEFAULT 模型（ALGO5），在 TT 处估一次。该定义已与
+  `chart_snapshot` 返回的 `jd_ut1` 在 1972-2099 网格对拍（亚毫秒级一致）。
+- 1972 年以前的 UTC 时刻由解析层拒绝；本模块只在解析层已取得 UTC 瞬间时被调用。
+
+## 真太阳时
+
+`apparent_solar_time` 以 UTC 民用时刻与东经经度换算当地真太阳钟；结果仍为 UTC 标
+民用时刻（保留 UT1-UTC 的亚秒差距，取时辰时通常不影响）。
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, date, datetime, timedelta
+from enum import StrEnum
+from typing import Any, Final
+
+
+class LunarAlgorithm(StrEnum):
+  """农历算法的具名选项；算法与版本随解析结果保存。"""
+
+  ALGO1 = "HKO 表"
+  ALGO2 = "天文计算"
+  ALGO3 = "混合"
+  HKO表 = ALGO1
+  天文计算 = ALGO2
+  混合 = ALGO3
+
+
+_ALGORITHM_RANGE: Final[dict[LunarAlgorithm, tuple[int, int]]] = {
+  LunarAlgorithm.ALGO1: (1901, 2099),
+  LunarAlgorithm.ALGO2: (410, 2500),
+  LunarAlgorithm.ALGO3: (1600, 2199),
+}
+"""三种算法的农历年范围；与 celestial 的 supported_lunar_year_range 一致。"""
+
+_DELTA_T_MODEL = "DEFAULT(ALGO5)"
+"""立春比较固定使用的 ΔT 模型；与 celestial 的 jieqi_moment UT1 换算一致。"""
+
+
+def celestial_version() -> str:
+  """已安装 celestial-calendar 的版本字符串。"""
+  import celestial_calendar as celestial
+
+  return celestial.__version__
+
+
+def supported_lunar_year_range(algorithm: LunarAlgorithm) -> tuple[int, int]:
+  """所选农历算法的支持范围（农历年，含端点）。"""
+  if not isinstance(algorithm, LunarAlgorithm):
+    raise TypeError("农历算法须为 LunarAlgorithm 成员")
+  return _ALGORITHM_RANGE[algorithm]
+
+
+def _check_algorithm(algorithm: LunarAlgorithm) -> None:
+  if not isinstance(algorithm, LunarAlgorithm):
+    raise TypeError("农历算法须为 LunarAlgorithm 成员")
+
+
+def _check_day(day: date) -> None:
+  if type(day) is not date:
+    raise TypeError("公历日期须为 date，不接受 datetime")
+
+
+def _native_algorithm(algorithm: LunarAlgorithm, celestial: Any) -> Any:
+  """把本仓算法枚举映射到 celestial 的 LunarAlgorithm 成员。"""
+  return {
+    LunarAlgorithm.ALGO1: celestial.LunarAlgorithm.ALGO1,
+    LunarAlgorithm.ALGO2: celestial.LunarAlgorithm.ALGO2,
+    LunarAlgorithm.ALGO3: celestial.LunarAlgorithm.ALGO3,
+  }[algorithm]
+
+
+def gregorian_to_lunar(algorithm: LunarAlgorithm, day: date) -> tuple[int, int, int, bool]:
+  """公历日期标签换农历年月日与闰月标志。
+
+  换算以传入的当地民用日标签为基准：民用路径传 `BirthRecord.birth_date`，真太阳时
+  路径由解析层传真太阳钟的民用日（见 resolver）。超出算法支持范围或日期不可表示时
+  抛ValueError；年历查询或原生转换的内部故障原样传播。
+  """
+  _check_algorithm(algorithm)
+  _check_day(day)
+  first_year, last_year = supported_lunar_year_range(algorithm)
+  first_day, _, _ = lunar_year_info(algorithm, first_year)
+  last_first_day, _, last_lengths = lunar_year_info(algorithm, last_year)
+  end = last_first_day + timedelta(days=sum(last_lengths))
+  if not first_day <= day < end:
+    raise ValueError(f"公历日期{day}超出{algorithm.value}支持范围")
+  import celestial_calendar as celestial
+
+  lunar = celestial.gregorian_to_lunar(_native_algorithm(algorithm, celestial), day)
+  return lunar.year, lunar.month, lunar.day, lunar.is_leap
+
+
+def lunar_to_gregorian(
+  algorithm: LunarAlgorithm, year: int, month: int, day: int, is_leap: bool
+) -> date:
+  """农历年月日与闰月标志换公历标签；组合不存在时抛ValueError，内部故障原样传播。"""
+  validate_lunar_date(algorithm, year, month, day, is_leap)
+  import celestial_calendar as celestial
+
+  lunar = celestial.LunarDate(year, month, day, is_leap)
+  return celestial.lunar_to_gregorian(_native_algorithm(algorithm, celestial), lunar).to_date()
+
+
+def lunar_year_info(
+  algorithm: LunarAlgorithm, year: int
+) -> tuple[date, int | None, tuple[int, ...]]:
+  """农历年的首日、闰月与逐月长（闰月直接排在同名月之后）。"""
+  _check_algorithm(algorithm)
+  import celestial_calendar as celestial
+
+  info = celestial.lunar_year_info(_native_algorithm(algorithm, celestial), year)
+  return info.first_day.to_date(), info.leap_month, info.month_lengths
+
+
+def validate_lunar_date(
+  algorithm: LunarAlgorithm, year: int, month: int, day: int, is_leap: bool
+) -> None:
+  """核对农历年月日与闰月组合存在于所选算法；不存在或超范围显式失败。"""
+  _check_algorithm(algorithm)
+  for value, label in ((year, "农历年"), (month, "农历月"), (day, "农历日")):
+    if type(value) is not int:
+      raise TypeError(f"{label}须为整数，不接受 bool")
+  if type(is_leap) is not bool:
+    raise TypeError("闰月标志须为 bool")
+  if year < _ALGORITHM_RANGE[algorithm][0] or year > _ALGORITHM_RANGE[algorithm][1]:
+    raise ValueError(f"农历年{year}超出{LunarAlgorithm(algorithm).value}支持范围")
+  if not 1 <= month <= 12:
+    raise ValueError(f"农历月须在1至12之间：{month}")
+  if day < 1:
+    raise ValueError(f"农历{year}年{month}月没有第{day}日")
+  _, leap_month, month_lengths = lunar_year_info(algorithm, year)
+  if is_leap and month != leap_month:
+    raise ValueError(f"农历{year}年不存在闰{month}月")
+  # 月长元组把闰月插在同名月之后：闰月与其后的平月下标都要后移一位。
+  effective_month = month + (
+    1 if leap_month is not None and (month > leap_month or (is_leap and month == leap_month)) else 0
+  )
+  if effective_month > len(month_lengths):
+    raise ValueError(f"农历{year}年不存在第{month}月")
+  if day > month_lengths[effective_month - 1]:
+    raise ValueError(f"农历{year}年{month}月没有第{day}日")
+
+
+#: 闰秒表（TAI-UTC，秒），1972-01-01 起；2017-01-01 后恒为 37 秒。
+#: 与 celestial-calendar 的 leap_second 表一致（IERS 闰秒数据，公开资料）。
+_LEAP_SECOND_TABLE: Final[tuple[tuple[date, int], ...]] = (
+  (date(1972, 1, 1), 10),
+  (date(1972, 7, 1), 11),
+  (date(1973, 1, 1), 12),
+  (date(1974, 1, 1), 13),
+  (date(1975, 1, 1), 14),
+  (date(1976, 1, 1), 15),
+  (date(1977, 1, 1), 16),
+  (date(1978, 1, 1), 17),
+  (date(1979, 1, 1), 18),
+  (date(1980, 1, 1), 19),
+  (date(1981, 7, 1), 20),
+  (date(1982, 7, 1), 21),
+  (date(1983, 7, 1), 22),
+  (date(1985, 7, 1), 23),
+  (date(1988, 1, 1), 24),
+  (date(1990, 1, 1), 25),
+  (date(1991, 1, 1), 26),
+  (date(1992, 7, 1), 27),
+  (date(1993, 7, 1), 28),
+  (date(1994, 7, 1), 29),
+  (date(1996, 1, 1), 30),
+  (date(1997, 7, 1), 31),
+  (date(1999, 1, 1), 32),
+  (date(2006, 1, 1), 33),
+  (date(2009, 1, 1), 34),
+  (date(2012, 7, 1), 35),
+  (date(2015, 7, 1), 36),
+  (date(2017, 1, 1), 37),
+)
+
+
+def _delta_at(day: date) -> int:
+  """UTC 民用日的闰秒数；2017-01-01 后恒为 37。"""
+  value = 37
+  for boundary, leap in _LEAP_SECOND_TABLE:
+    if day < boundary:
+      break
+    value = leap
+  return value
+
+
+def _civil_to_jd(year: int, month: int, day: int, fraction: float) -> float:
+  """公历（无历标）转儒略日；fraction 为当日小数。"""
+  a = (14 - month) // 12
+  y = year + 4800 - a
+  m = month + 12 * a - 3
+  julian = day + (153 * m + 2) // 5 + 365 * y + y // 4 - y // 100 + y // 400 - 32045
+  return julian + fraction - 0.5
+
+
+def _jd_to_civil(jd: float) -> tuple[int, int, int, float]:
+  """儒略日转公历年月日与当日小数（与 _civil_to_jd 互逆）。"""
+  adjusted = jd + 0.5
+  z = int(adjusted)
+  fraction = adjusted - z
+  if z < 2299161:
+    a = float(z)
+  else:
+    alpha = (z - 1867216.25) // 36524.25
+    a = z + 1 + alpha - alpha // 4
+  b = a + 1524
+  c = (b - 122.1) // 365.25
+  d = int(365.25 * c)
+  e = (b - d) // 30.6001
+  day_float = b - d - int(30.6001 * e) + fraction
+  day = int(day_float)
+  month = int(e) - 1 if e < 14 else int(e) - 13
+  year = int(c) - 4716 if month > 2 else int(c) - 4715
+  return year, month, day, day_float - day
+
+
+def _days_in_year(year: int) -> int:
+  return 366 if (year % 4 == 0 and year % 100 != 0) or year % 400 == 0 else 365
+
+
+def _decimal_year(jd: float) -> float:
+  """儒略日对应的十进制公历年，供 delta_t 取 ΔT。"""
+  year, month, day, fraction = _jd_to_civil(jd)
+  day_of_year = int(_civil_to_jd(year, month, 1, 0) - _civil_to_jd(year, 1, 1, 0)) + day
+  return year + (day_of_year - 1 + fraction) / _days_in_year(year)
+
+
+def _check_utc(utc: datetime) -> None:
+  if type(utc) is not datetime:
+    raise TypeError("UTC 时刻须为 datetime")
+  if utc.tzinfo is None or utc.utcoffset() is None:
+    raise ValueError("UTC 时刻须带时区")
+
+
+def utc_to_ut1_jd(utc: datetime) -> float:
+  """把 UTC 瞬间按 modelled-UT1 定义换算到 UT1 日数。
+
+  TT=UTC+(ΔAT+32.184s)，UT1=TT-ΔT；ΔT 在 TT 处估一次，固定 DEFAULT(ALGO5)。
+  该值与 celestial 的 chart_snapshot(jd_ut1) 在 1972-2099 网格上一致（亚毫秒级）。
+  """
+  _check_utc(utc)
+  utc_utc = utc.astimezone(UTC)
+  if utc_utc < datetime(1972, 1, 1, tzinfo=UTC):
+    raise ValueError("UTC 早于1972-01-01的时刻须另定时标合同")
+  fraction = (
+    utc_utc.hour * 3600 + utc_utc.minute * 60 + utc_utc.second + utc_utc.microsecond / 1e6
+  ) / 86400.0
+  jd_utc = _civil_to_jd(utc_utc.year, utc_utc.month, utc_utc.day, fraction)
+  tt = jd_utc + (_delta_at(utc_utc.date()) + 32.184) / 86400.0
+  import celestial_calendar as celestial
+
+  delta_t = celestial.delta_t(_decimal_year(tt), celestial.DeltaTModel.DEFAULT)
+  return tt - delta_t / 86400.0
+
+
+def lichun_jd(year: int) -> float:
+  """农历（干支）年 year 的立春 UT1 时刻（UT1 日数）。
+
+  jieqi_moment 返回的立春时刻为 UT1；返回日数可直接与 utc_to_ut1_jd 比较。
+  立春在某公历年内，出生瞬间 ≥ 该年立春即归该干支年。
+  """
+  if type(year) is not int:
+    raise TypeError("立春查询年份须为整数")
+  import celestial_calendar as celestial
+
+  moment = celestial.jieqi_moment(year, celestial.Jieqi.LICHUN)
+  return celestial.ut1_to_jd(moment.moment_ut1)
+
+
+def utc_civil(utc: datetime) -> tuple[int, int, int, float]:
+  """UTC 瞬间转民用年月日与当日小数，供真太阳时换算。"""
+  _check_utc(utc)
+  utc_utc = utc.astimezone(UTC)
+  fraction = (
+    utc_utc.hour * 3600 + utc_utc.minute * 60 + utc_utc.second + utc_utc.microsecond / 1e6
+  ) / 86400.0
+  return utc_utc.year, utc_utc.month, utc_utc.day, fraction
+
+
+def apparent_solar(utc: datetime, longitude_deg: float) -> tuple[int, int, int, float]:
+  """当地真太阳钟的年月日与当日小数；经度为东经正。"""
+  _check_utc(utc)
+  import celestial_calendar as celestial
+
+  year, month, day, fraction = utc_civil(utc)
+  result = celestial.apparent_solar_time(
+    celestial.CivilDateTime(year, month, day, fraction), longitude_deg
+  )
+  return result.year, result.month, result.day, result.fraction