Metadata-Version: 2.5
Name: tianzhi-core
Version: 0.1.1
Summary: 东方术数的核心算法：以典籍为据，把可推算的部分还原成可检验的算法
Project-URL: Homepage, https://github.com/zaoxu001/tianzhi-core
Project-URL: Issues, https://github.com/zaoxu001/tianzhi-core/issues
Author: zaoxu001
License: MIT
License-File: LICENSE
Keywords: bazi,four-pillars,ganzhi,jieqi,metaphysics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: lunar-python>=1.4.8
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# tianzhi-core · 东方术数核心算法

术数是一套以干支为坐标的推演体系。八字、六壬、六爻、奇门、紫微、梅花，各有典籍与推演之法，底下却共用同一套坐标：干支、五行、节气、长生、旺相休囚死。

tianzhi-core 把这套共用的底座做成代码，再在其上按门类展开。它是各类术数软件与 AI 应用的计算基座。

## 术数计算的三段

**一、历法与纪时。** 公历农历互转、二十四节气的精确时刻、真太阳时修正、干支纪年月日时。这一段是天文计算，规则明确，只有对错。

**二、起局与排盘。** 把干支组织成盘，取出藏干、十神、纳音、地势、旬空、命宫身宫胎元，推出起运与大运流年。这一段是查表与推导，同样只有对错。

**三、判断与推演。** 五行力量如何量化、日主旺衰如何分档、用神如何取、格局如何定、岁运如何引动原局。这一段有流派、有分歧、有取舍，也是做命理产品真正耗时的地方。

前两段已有成熟实现，[lunar-python](https://github.com/6tail/lunar-python) 做得完整而准确，tianzhi-core 直接采用，不作重复实现。第三段目前缺少可被检验的公共实现，各家自写、彼此矛盾，这是 tianzhi-core 补的部分。

同时 tianzhi-core 把三段统一在一致的类型与契约之下：排盘产出的结构可以直接送进量化与取用，流派分歧处收敛为显式参数，全链路为纯函数、可测试、跨进程一致。三段因此成为一条可组合的流水线，而不是三处各自为政的调用。

**给谁用**

- **命理网站、App、小程序** — 旺衰怎么量化、用神怎么取、格局怎么定、岁运怎么引动，这几层不必自己从头实现，也不必在各家说法里反复权衡。
- **AI 应用** — 模型不会算八字，让它自行推演会编出一套看似合理的东西，而且同一张盘问两次答案不一样。由这个包算出确定的结果喂给模型，模型只负责把结果说成人话，幻觉就没有落脚点。
- **研究与教学** — 每条规则注明典籍出处，工程取值单独标注，同一输入永远同一输出，可以对着原文逐条印证。

## 架构

```
tianzhi_core/
  calendar/    历法    真太阳时、二十四节气时刻、距节天数
  core/        通用    五行生克、干支属性藏干、合冲刑害、十二长生、
                       旺相休囚死、人元司令
  bazi/        八字    排盘 → 量化 → 取用 → 引动 → 双盘
  ...                  其余各门依同样的次第展开
```

底下两层是所有术数共用的。任一门类接进来，都不必重做历法与干支，它要的只是在这套坐标上定义自己的起局方式与推演之法。

## 安装

```bash
pip install tianzhi-core
```

## 用

以八字为例。

```python
from datetime import datetime
from tianzhi_core.bazi import chart, strength, yongshen, score

c = chart.build_chart(datetime(1996, 4, 18, 14, 6), longitude=114.93, gender=0)
print(c.bazi)                              # 丙子 壬辰 乙酉 癸未

s = strength.day_master_strength(c.quad, month_siling=c.siling)
print(s.label, round(s.ratio, 3))          # 中和 0.453

y = yongshen.select(c.quad, month_siling=c.siling)
print(y.yong, y.xi, y.ji, y.chou)          # 土 火 木 水
print(y.evidence)                          # ('旺衰·中和', '格·偏印格', '病·水最旺', '药·土制之', ...)

r = score.score_year(c.quad, "丙午", favorable=y.favorable, unfavorable=y.unfavorable)
print(r.score, r.breakdown)                # 58.8 {'base': 50.0, 'year_gan|丙(火)喜用': 8.0, ...}
```

排完盘 `c.quad` 直接往下传，量化、取用、引动、双盘都收这个结构。返回的是结构化数据与术语标签。

## 八字模块

| 层 | 模块 | 提供 |
|---|---|---|
| 排盘 | `bazi.chart` | 四柱、藏干、司令、十神、纳音、地势、命宫身宫胎元 |
| 排运 | `bazi.luck_cycle` | 起运岁数与交运时刻、大运、流年、流月 |
| 量化 | `bazi.strength` | 五行力量、日主旺衰五档、十神力量、寒暖燥湿 |
| 取用 | `bazi.tiaohou` `geju` `yongshen` | 调候、月令格局与相神、通用规则与本盘成象的相抵之处、用喜忌仇闲 |
| 引动 | `bazi.interact` `score` | 岁运对原局的作用、可解释的逐年评分与曲线 |
| 双盘 | `bazi.hepan` | 两张盘的关系指标 |
| 参考 | `bazi.shensha` | 神煞落点。取用逻辑不采信 |

## 依据

调候查《穷通宝鉴》（又名《栏江网》）十天干乘十二月令一百二十格，忌神另参《金不换大运》。格局按《子平真诠》月令取格与顺用逆用，八条相神规则照原文编成判据。病药依《神峰通考》。旺衰不以月令独断，取《滴天髓》「得時俱為旺論，失令便作衰看，雖是至理，亦死法也」之意，兼看通根、透干与全盘力量之比。

有出处的规则在代码里注明篇名。无法从典籍直接推出的系数标注为本包取值、可以调整。

流派分歧之处做成参数：晚子时归哪一天、阴干有没有刃、取用以格局为先还是调候为先，默认值另附理由。

## 计算契约

提供干支纪时、五行力量、旺衰分档、调候取用、月令格局、岁运引动、逐年评分的计算，返回结构化数据与术语标签。

纯函数：不读系统时间，不访问网络与文件系统（包内数据表除外）。同一输入永远得到同一输出，跨进程一致。

## 致谢

[lunar-python](https://github.com/6tail/lunar-python) 提供历法与排盘：公历农历互转、二十四节气的精确时刻、干支纪时、藏干、十神、纳音、地势、旬空、命宫身宫胎元、大运排布。这一层完整且准确，tianzhi-core 在其上建立类型化的数据结构与统一契约，并将流派分歧处显式化为参数。

调候与喜忌两张一百二十格对照表、人元司令分日表，整理自 [china-testing/bazi](https://github.com/china-testing/bazi) 与 [qianye-wuyu/yueyuan-bazi](https://github.com/qianye-wuyu/yueyuan-bazi) 的公开数据；原始出处为《穷通宝鉴》《金不换大运》等公版古籍。

## 参与

这门学问的公共实现需要很多人一起校对。以下三类贡献尤其欢迎。

**规则有误。** 某条判据与典籍原文不符，或者理解偏了。请在 issue 中写明：涉及哪个模块的哪个函数、依据哪一部书的哪一篇、原文怎么说、你认为应当如何。

**流派分歧。** 同一件事各家说法不同，而本包只实现了其中一种。请说明另一派的主张与出处，以及它与现有默认值的差别。经确认的分歧会做成参数，两派并存交由使用者选择，本包不替人选边。

**案例佐证。** 拿具体命例说明某条规则算得不对，远比空泛的论断有力。请附上四柱、本包当前的输出、你认为正确的结论及其推导。多个命例指向同一结论，更佳。

经核实的意见会合入计算逻辑，并在代码注释与「依据」一节中注明出处与提出者。改动打分权重这类工程取值时，请附上对拍数据：在多少命例上产生多大差异。

传统文化要传下去，靠的不是各说各话，是把推演过程摊开让人检验。欢迎通命理的同道、研究者、工程师一起把这件事做成可以对质的公共资产。

**关于 AI 生成的内容。** 欢迎用 AI 辅助整理与表达，但禁止 AI 灌水。

## 相关项目

**[天秩](https://tianzhi.live)** · 东方术数的研究与学习平台，涵盖八字、六壬、六爻、奇门、紫微、梅花，以典籍为据，把术数里属于推算的那一部分还原成可检验的算法。此开源项目为天秩的计算核心。

## 许可

MIT
