《皇极经世》数理结构·技术规格书

《皇极经世》数理结构技术规格书（程序实现工程级标准）

文档性质：软件工程系统设计与算法规格说明书（Software Architecture & Mathematical Engine Specification）
面向目标：为历史时空推演引擎、皇极象数推步算法、易学天道历法系统开发提供无歧义、数学化、确定性的工程实现基准。
依据底本：

  • 底本一：《皇极经世书》（文渊阁《四库全书》本，含《观物内篇》五十一至六十二、观物外篇衍义，本地路径：/home/lewin/@Sync/Casket/obsidian/lewin/raw/古籍/术数/皇极经世书.md）
  • 底本二：《皇极经世》（道藏/四库本《邵子全书》以运经世编年，本地路径：/home/lewin/@Sync/Casket/obsidian/lewin/raw/古籍/术数/皇极经世.md）
  • 参校文献：南宋·张行成《皇极经世观物外篇衍义》《皇极经世索隐》、南宋·祝泌《皇极经世解起数诀》、清·王植《皇极经世书解》十四卷。

模块零：核心设计理念与宇宙时空拓扑模型

邵雍《皇极经世》的数理核心，是建立在**“天人合一、大微同构、阴阳消长、以理寓数”**之上的宏大宇宙历史编年体系。其算法设计呈现三大特征：

  1. 分形同构（Fractal Isomorphism）：宇宙物理时间（元会运世，大四象）与人类日用时间（年月日时，小四象）在数学结构上严格等比放大。
  2. 二元交替嵌套（Alternating Radix）：以阳数基数 12（天统体）与阴数基数 30（地分用）交替相乘，驱动全元周期。
  3. 六十卦周天历度（Cyclic Hexagram Mapping）：去除乾、坤、坎、离四正卦以统四时，以其余六十卦三百六十爻配周天三百六十度与全元三百六十运。

模块一：元会运世单位制完整定义（数学公式与全层级矩阵）

1.1 大小四象同构映射模型

邵雍在《观物内篇·五十一》指出：“天统乎体而托地以为体，地分乎用而承天以为用……四时体数也，三月三十日用数也。”
宇宙时间尺度（大四象）与地球日历尺度（小四象）形成严格映射：

1.2 各级单位定义与换算递推公式（写死）

系统固化以下基准换算关系：

由此可导出面向程序数据类型的绝对整型换算矩阵：

目标单位 \ 基准单位 1 元 (Yuan) 1 会 (Hui) 1 运 (Yun) 1 世 (Shi) 1 年 (Year) 1 月 (Month) 1 日 (Day)
会 (Hui) 12 1 — — — — —
运 (Yun) 360 30 1 — — — —
世 (Shi) 4,320 360 12 1 — — —
年 (Year) 129,600 10,800 360 30 1 — —
月 (Month) 1,555,200 129,600 4,320 360 12 1 —
日 (Day) 46,656,000 3,888,000 129,600 10,800 360 30 1
辰 (Hour) 559,872,000 46,656,000 1,555,200 129,600 4,320 360 12

1.3 核心数理常数（全系统写死）

模块二：以元经会 / 以会经运 / 以运经世 三层纪年表的结构规律

邵雍在《皇极经世》中构造了贯通古今的历史大年表。程序实现必须将其分解为标准的多级复合索引结构。

2.1 三层纪年表分层定义

  1. 第一层：以元经会（宏观大运表，观物篇一至五）
    • 索引范围：会编号 H ∈ [1, 12]，以十二地支命名：
      • 子会(1)、丑会(2)、寅会(3)、卯会(4)、辰会(5)、巳会(6)、午会(7)、未会(8)、申会(9)、酉会(10)、戌会(11)、亥会(12)。
    • 每一会冠以天干会名，如“经会之子一”、“经会之丑二”……“经会之巳六”、“经会之午七”等。
  2. 第二层：以会经运（中观运度表，观物篇六至二十四）
    • 索引范围：全元全局运编号 Y_global ∈ [1, 360]。
    • 会内局部运编号 y_local ∈ [1, 30]。
    • 换算公式：Y_global = (H - 1) × 30 + y_local。
    • 运之天干地支排布规则：
      • 运以六十甲子顺行排布。
      • 子会（1~30运）：甲子(1)至癸巳(30)；
      • 丑会（31~60运）：甲午(31)至癸亥(60)；
      • 寅会（61~90运）：甲子(1)至癸巳(30)；
      • 卯会（91~120运）：甲午(31)至癸亥(60)；
      • 其余各会依次交替类推。
  3. 第三层：以运经世（微观编年表，观物篇二十五至三十四）
    • 索引范围：全元全局世编号 S_global ∈ [1, 4320]。
    • 运内局部世编号 s_local ∈ [1, 12]，以十二地支标示（子、丑、寅、卯、辰、巳、午、未、申、酉、戌、亥）。
    • 换算公式：S_global = (Y_global - 1) × 12 + s_local。
    • 世内三十年排布规则（关键数学定理）：
      • 每一世恒定包含 30 年。
      • 奇数世（S_global % 2 == 1）：固定取六十甲子前半部，即 甲子(1) 至 癸巳(30)。
      • 偶数世（S_global % 2 == 0）：固定取六十甲子后半部，即 甲午(31) 至 癸亥(60)。
      • 两世合为一甲子（60年），一运十二世合为六个甲子循环（360年）。

2.2 绝对年份到四级坐标的转换算法

给定从本元开辟起的绝对累积年份 N_year ∈ [1, 129600]：

该年份干支在六十甲子中的索引 GZ ∈ [0, 59] 为：

2.3 历史年份定位与现代公历转换锚定（Anchor Points）

邵雍《以运经世》年表记录了自帝尧肇位于平阳至五代周世宗柴荣终、宋太祖即位的信史纪年。

【巳会之末】（第180运，癸巳运）
  ├── 第2149世（子）至 第2155世（午）：史前传疑时代
  └── 第2156世（未，偶数世）：第11年为【甲辰年】—— 唐帝尧肇位元年（公元前2357年）！
        │
【午会之始】（第181运，甲午运，夏至一阴生）
  ├── 第2161世（子）至 第2172世（亥）：夏朝历年
  ├── 第182运（乙未运）：商朝立国
  ├── 第183运（丙申运）：周朝立国
  └── 第184运（丁酉运）：唐宋变革期
        └── 第2266世（酉，偶数世）：第27年为【庚申年】—— 宋太祖建隆元年（公元960年）！

核心历史锚定表（写死参数，经原文精确对勘）

历史事件 邵雍年表坐标 世内年序与干支 全元绝对年数 N_year 对应公历纪年
唐帝尧即位元年 巳会·第180运·第2156世（未） 第11年（甲辰） 64,661 公元前 2357 年 (BCE 2357)
虞舜受禅元年 巳会·第180运·第2158世（酉） 第21年（甲午） 64,731 公元前 2287 年 (BCE 2287)
夏禹受禅元年 巳会·第180运·第2159世（戌） 第24年（丁未） 64,764 公元前 2254 年 (BCE 2254)
商汤立国元年 午会·第182运·第2176世（辰） 第16年（乙亥） 65,266 公元前 1752 年 (BCE 1752)
周武王克商元年 午会·第183运·第2197世（子） 第16年（己卯） 65,896 公元前 1122 年 (BCE 1122)
宋太祖建隆元年 午会·第184运·第2266世（酉） 第27年（庚申） 67,977 公元 960 年 (CE 960)
宋神宗熙宁十年（邵子卒年） 午会·第184运·第2267世（戌） 第14年（丁巳） 68,094 公元 1077 年 (CE 1077)

公元纪年双向转换公式（标准基准常数：Offset = 67017）

注：天文历法计算无公元 0 年，公元前 1 年直接衔接公元 1 年。

模块三：先天六十四卦圆图配值运世年规则

3.1 伏羲先天六十四卦圆图基础与四正卦去取

圆图六十卦序列表（去乾、坤、坎、离后，自复卦顺行）

3.2 值会卦（元之会卦，12会）

3.3 值运卦（会之运卦，360运）

3.4 值世卦（运之世卦，4320世）

一运管 12 世（360年），如何由值运卦推导 12 世之卦？

3.5 值年卦（世之流年卦，129600年）

一世 30 年，每年值何卦？

模块四：开物与闭物时间窗口

“开物”与“闭物”是邵雍界定宇宙万物生死存亡、人类文明活跃期与蛮荒混沌期的绝对分水岭。

4.1 宇宙演化十二会全景与相变窗口

根据《观物内篇·五十二》与《皇极经世心易发微》记载：

 会序:   子会(1)    丑会(2)    寅会(3)    卯~巳(4~6)   午会(7)    未~酉(8~10)  戌会(11)   亥会(12)
 状态: ［ 天开 ］ ［ 地辟 ］ ［ 人生 ］ ［ 阳升发展 ］ ［ 阴生 ］ ［ 阴长收敛 ］ ［ 物闭 ］ ［ 地闭 ］
        └──────────────────┘                                            └──────────────────┘
           【开辟准备期】                 【万物繁茂活跃期】                  【衰退闭塞期】
           (21,600年)                     (86,400年)                      (21,600年)

4.2 开物 / 闭物数学时间窗口（写死参数）

模块五：声律唱和（可执行规格）

本模块依据王植《皇极经世书解》卷四的《声音唱和》图说（原文行 1837–1865、1923–1935、2105–2113）。它是声音/文字的特征层，不反向修改梅花年月日时或皇极元会运世主干坐标。

5.1 坐标、体数与用数

王植的基本约定是“声为律、音为吕；律为唱、吕为和”（1857），天声主动，地音受动。天、地各先取四象，再展开各自的序号轴：

维度 四象顺序（固定） 序号轴 单格总数 语义
天声 日、月、星、辰 声位 1–10（甲–癸） 4 × 10 = 40 天之体声
地音 水、火、土、石 音位 1–12（子–亥） 4 × 12 = 48 地之体音
天声×地象 日月星辰 × 水火土石 每格 10 声位 16 × 10 = 160 天声全数
地音×天象 日月星辰 × 水火土石 每格 12 音位 16 × 12 = 192 地音全数

四象的先天对应固定为：

天声象 阴阳刚柔名 地音象 阴阳刚柔名
日 太阳 水 太柔
月 太阴 火 太刚
星 少阳 土 少柔
辰 少阴 石 少刚

工程中同时保留“体数”和“用数”两层：从天声全数 160 中扣除地之体数 48，得天声用数 112；从地音全数 192 中扣除天之体数 40，得地音用数 152。王植原文的总数校验为：

动植全数 = 160 × 192 = 30,720
天声用数 = 160 - 48 = 112
地音用数 = 192 - 40 = 152
动物用数 = 112 × 152 = 17,024
植物用数 = 152 × 112 = 17,024
动植通数 = 17,024 × 17,024 = 289,816,576

这里的“体数扣除”是图中的无声/无音位置，不得把 112、152 误当成四声或十二音的数量；图外的空位仍属于全图拓扑，但不进入用数乘法（1837–1849、1853–1859、2105–2107）。

5.2 天声、地音的完整状态表

轴 状态顺序 数值编码 与四象的配合
天声调 平、上、去、入 tone = 1、2、3、4 分别以日、月、星、辰配四声，形成 4 × 4 的声象格
地音开合 开、发、收、闭 opening = 1、2、3、4 分别以水、火、土、石配四音，形成 4 × 4 的音象格
天声序号 甲、乙、丙、丁、戊、己、庚、辛、壬、癸 voice = 1…10 每一声图纵向十位
地音序号 子、丑、寅、卯、辰、巳、午、未、申、酉、戌、亥 sound = 1…12 每一音图横向十二位
声性质 奇声 / 偶声 odd / even 奇声清、偶声浊；对应律的闢/翕
音性质 闢 / 翕 open / closed 阳主闢而出，阴主翕而入；对应吕的开/闭行

图表层的固定规模为：四声图 4 ×（四象 × 十声位）= 160 个天声格，四音图 4 ×（四象 × 十二音位）= 192 个地音格；扣除体数后，天声用格 112、地音用格 152。十声图与十二音图的交叉方向分别为 10 × 12 = 120 个“唱吕”图和 12 × 10 = 120 个“和律”图；四声/四音状态展开后总目录为 16 × 240 = 3,840 图（例言行 151–153，瑞节注行 1861–1863）。

5.3 唱和计算规则

输入必须是一个声坐标和一个音坐标：

声坐标 = (sky ∈ {日,月,星,辰}, tone ∈ {平,上,去,入}, voice ∈ 1..10)
音坐标 = (earth ∈ {水,火,土,石}, opening ∈ {开,发,收,闭}, sound ∈ 1..12)

计算步骤固定如下：

  1. 将 sky 映射为 1–4，将 tone 映射为 1–4，将 earth 映射为 1–4，将 opening 映射为 1–4；序号越界直接拒绝。
  2. 以 voice（1–10）在相应天声图取“律”，以 sound（1–12）在相应地音图取“吕”。
  3. 唱和的正向结果为 律唱吕，反向结果为 吕和律；两者使用同一对坐标，不交换奇偶规则。
  4. 声位为奇数时标记 清/闢，为偶数时标记 浊/翕；这两个标签是结构字段，不是现代普通话声调判断。
  5. 若文字有反切资料，反切上字进入天声坐标、反切下字进入地音坐标；若只有现代拼音，不得假称已经完成古音反切定位，应保留 音位未定。
  6. 只在去除体数后的有效格中输出 use_voice_index、use_sound_index；空位输出 usable=false 和原因，不以 0 冒充一个音数。
  7. 对有效格输出 animal_number = use_voice_index × use_sound_index（范围 1–17,024）；反向“植物”计算为 use_sound_index × use_voice_index，数值相同但方向不同。

王植举例的图读法是：直看第一维为日声水音、第二维为月声火音、第三维为星声土音、第四维为辰声石音；横看同样按日/月/星/辰行进（1850–1851）。因此一个可复现的结果至少必须回显四元组坐标、声/音序号、清浊/闢翕标签、是否体数空位和乘积，不能只返回一个汉字或吉凶判断。

5.4 与元会运世的衔接

声律层沿用与元会运世相同的四象递推，但不把声音乘积直接当作年份：王植明确给出“日日声即元之元，日月声即元之会，日星声即元之运，日辰声即元之世”（2105–2107）。因此接口映射固定为：

声象 元会运世层 接口字段
日声 元之元 yuan
月声 元之会 hui
星声 元之运 yun
辰声 元之世 shi

给定皇极坐标 (yuan, hui, yun, shi) 时，可将四层标签作为声音图的四层寻址上下文；给定声音坐标时，只能生成对应的声律特征，不能反推出唯一历史年份，除非另有完整的元会运世输入。yun_gua(year) 的值运卦/值世卦计算不调用声律模块，保证主干确定性与声律特征层解耦。

5.5 工程边界

模块六：工程实现核心 Python 类库与算法参考（标准实现范式）

以下提供生产级 Python 算法参考实现，可直接集成进排卦与天文历推步系统：

# coding: utf-8
from dataclasses import dataclass
from typing import Tuple, Dict, Any

# 1. 常量定义
TIAN_GAN = ["", "甲", "乙", "丙", "丁", "戊", "己", "庚", "辛", "壬", "癸"]
DI_ZHI = ["", "子", "丑", "寅", "卯", "辰", "巳", "午", "未", "申", "酉", "戌", "亥"]

# 六十甲子表
SIXTY_JIAZI = [
    "甲子", "乙丑", "丙寅", "丁卯", "戊辰", "己巳", "庚午", "辛未", "壬申", "癸酉",
    "甲戌", "乙亥", "丙子", "丁丑", "戊寅", "己卯", "庚辰", "辛巳", "壬午", "癸未",
    "甲申", "乙酉", "丙戌", "丁亥", "戊子", "己丑", "庚寅", "辛卯", "壬辰", "癸巳",
    "甲午", "乙未", "丙申", "丁酉", "戊戌", "己亥", "庚子", "辛丑", "壬寅", "癸卯",
    "甲辰", "乙巳", "丙午", "丁未", "戊申", "己酉", "庚戌", "辛亥", "壬子", "癸丑",
    "甲寅", "乙卯", "丙辰", "丁巳", "戊午", "己未", "庚申", "辛酉", "壬戌", "癸亥"
]

# 十二辟卦（会卦）
HUI_GUA = ["", "复", "临", "泰", "大壮", "夬", "乾", "姤", "遁", "否", "观", "剥", "坤"]

# 先天六十四卦圆图去四正后之六十卦序（复至剥）
SIXTY_ROUND_GUA = [
    # 阳升三十卦
    "复", "颐", "屯", "益", "震", "噬嗑", "随", "无妄", "明夷", "贲",
    "既济", "家人", "丰", "革", "同人", "临", "损", "节", "中孚", "归妹",
    "睽", "兑", "履", "泰", "大畜", "需", "小畜", "大壮", "大有", "夬",
    # 阴降三十卦
    "姤", "大过", "鼎", "恒", "巽", "井", "蛊", "升", "讼", "困",
    "未济", "解", "涣", "蒙", "师", "遁", "咸", "旅", "小过", "渐",
    "蹇", "艮", "谦", "否", "萃", "晋", "豫", "观", "比", "剥"
]

# 公元纪年与皇极元绝对年数转换常量
CE_OFFSET = 67017

@dataclass
class HuangjiCoordinate:
    absolute_year: int     # 全元绝对年数 [1, 129600]
    hui_index: int         # 会序号 [1, 12]
    hui_name: str          # 会地支 (子~亥)
    hui_gua: str           # 会卦 (十二辟卦)
    yun_global: int        # 全局运序号 [1, 360]
    yun_local: int         # 会内运序号 [1, 30]
    yun_gua: str           # 值运卦
    yun_yao: int           # 值运卦爻位 [1, 6]
    shi_global: int        # 全局世序号 [1, 4320]
    shi_local: int         # 运内世序号 [1, 12]
    shi_name: str          # 世地支 (子~亥)
    year_in_shi: int       # 世内年序号 [1, 30]
    ganzhi: str            # 流年干支
    year_gua: str          # 流年值年卦 (六十花甲配圆图卦)
    is_kaiwu: bool         # 是否处于开物活跃期
    ce_year: int           # 公元年份 (负数表示公元前)

class HuangjiEngine:
    @staticmethod
    def ce_to_absolute_year(ce: int) -> int:
        # 公元年份转皇极绝对年数
        if ce > 0:
            return ce + CE_OFFSET
        elif ce < 0:
            return 67018 + ce
        else:
            raise ValueError("公元年份无公元0年，请使用 -1 表示公元前1年，1 表示公元1年。")

    @staticmethod
    def absolute_year_to_ce(ay: int) -> int:
        # 皇极绝对年数转公元年份
        if ay > CE_OFFSET:
            return ay - CE_OFFSET
        else:
            return ay - 67018

    @classmethod
    def calculate(cls, absolute_year: int) -> HuangjiCoordinate:
        # 根据全元绝对年数推导皇极四级坐标与全部卦象
        if not (1 <= absolute_year <= 129600):
            raise ValueError("绝对年数必须在 [1, 129600] 之间。")

        ay = absolute_year

        # 1. 会推导
        h_idx = (ay - 1) // 10800 + 1
        h_name = DI_ZHI[h_idx]
        h_gua = HUI_GUA[h_idx]

        # 2. 运推导
        y_global = (ay - 1) // 360 + 1
        y_local = (y_global - 1) % 30 + 1
        
        # 值运卦推导（圆图60卦，每爻管一运，6运管一卦）
        gua_idx = (y_global - 1) // 6
        yao_idx = (y_global - 1) % 6 + 1
        y_gua = SIXTY_ROUND_GUA[gua_idx]

        # 3. 世推导
        s_global = (ay - 1) // 30 + 1
        s_local = (s_global - 1) % 12 + 1
        s_name = DI_ZHI[s_local]

        # 4. 年与干支推导
        year_in_shi = (ay - 1) % 30 + 1
        if s_global % 2 == 1:
            # 奇数世，走前半部 0~29
            gz_idx = year_in_shi - 1
        else:
            # 偶数世，走后半部 30~59
            gz_idx = year_in_shi + 29
        ganzhi_str = SIXTY_JIAZI[gz_idx]

        # 流年值年卦（标准圆图配六十花甲）
        year_gua_str = SIXTY_ROUND_GUA[gz_idx]

        # 5. 开物与闭物状态判定 (开物27000年，闭物113400年)
        is_kaiwu_status = (27000 <= ay <= 113400)

        # 6. 对应公元年份
        ce = cls.absolute_year_to_ce(ay)

        return HuangjiCoordinate(
            absolute_year=ay,
            hui_index=h_idx,
            hui_name=h_name,
            hui_gua=h_gua,
            yun_global=y_global,
            yun_local=y_local,
            yun_gua=y_gua,
            yun_yao=yao_idx,
            shi_global=s_global,
            shi_local=s_local,
            shi_name=s_name,
            year_in_shi=year_in_shi,
            ganzhi=ganzhi_str,
            year_gua=year_gua_str,
            is_kaiwu=is_kaiwu_status,
            ce_year=ce
        )

# 单元测试验证
if __name__ == "__main__":
    engine = HuangjiEngine()
    
    # 验证唐尧即位元年 (公元前2357年)
    yao_ay = 64661
    res_yao = engine.calculate(yao_ay)
    print(f"唐尧即位年(64661): 会={res_yao.hui_name}, 运={res_yao.yun_global}, 世={res_yao.shi_global}({res_yao.shi_name}), 年序={res_yao.year_in_shi}, 干支={res_yao.ganzhi}")
    assert res_yao.ganzhi == "甲辰", "唐尧即位年必须为甲辰！"
    assert res_yao.shi_global == 2156, "唐尧即位年必须在第2156世！"
    assert res_yao.yun_global == 180, "唐尧即位年必须在第180运！"
    assert res_yao.ce_year == -2357, "唐尧即位年必须对应公元前2357年！"

    # 验证宋太祖建隆元年 (公元960年)
    song_ay = 67977
    res_song = engine.calculate(song_ay)
    print(f"宋建隆元年(67977): 会={res_song.hui_name}, 运={res_song.yun_global}, 世={res_song.shi_global}({res_song.shi_name}), 年序={res_song.year_in_shi}, 干支={res_song.ganzhi}")
    assert res_song.ganzhi == "庚申", "宋建隆元年必须为庚申！"
    assert res_song.shi_global == 2266, "宋建隆元年必须在第2266世！"
    assert res_song.ce_year == 960, "宋建隆元年必须对应公元960年！"

    # 验证公元2026年 (丙午年)
    ay_2026 = 69043
    res_2026 = engine.calculate(ay_2026)
    print(f"公元2026年(69043): 会={res_2026.hui_name}, 运={res_2026.yun_global}, 世={res_2026.shi_global}({res_2026.shi_name}), 年序={res_2026.year_in_shi}, 干支={res_2026.ganzhi}")
    assert res_2026.ganzhi == "丙午", "公元2026年必须为丙午年！"
    assert res_2026.ce_year == 2026, "必须对应公元2026年！"

    print("皇极经世数理引擎单元测试全部通过！")

模块七：工程实现采信决策汇总表（系统规约终审）

规则项 核心考辨与注家分歧 工程实现采信决策（写死标准）
单位制进位 12与30交替嵌套（元12会、会30运、运12世、世30年）。 写死算法进位矩阵，支持大数秒级精准双向转换。
四正卦去取 乾坤坎离是否参与值运值世。 坚决去除四正卦，以圆图六十卦三百六十爻配周天运数。
会卦标准 十二消息卦派（张行成/王植） vs 圆图平分派（祝泌）。 采信十二辟卦/消息卦（子复、丑临、寅泰、巳乾、午姤、戌剥、亥坤）。
值运卦规则 六十卦三百六十爻配360运 vs 祝泌挂一变卦。 采信圆图六十卦爻值运法：GuaIdx = (Y-1)//6，YaoIdx = (Y-1)%6 + 1。
值世卦规则 值运卦动爻生变卦分统12世 vs 祝泌统宗世卦。 采信值运卦动爻生变卦分统12世（王植《皇极经世书解》法）。
值年卦规则 六十花甲一对一顺配圆图六十卦 vs 候卦五年一爻动。 采信六十花甲顺配圆图六十卦法，保证每年有明确独立主卦。
开物闭物窗口 寅会中惊蛰（第27000年）开物，戌会中立冬（第113400年）闭物。 硬编码窗口参数：有效生命期为中间 8 会共 86,400 年。
声音律吕 天声地音十六位反切矩阵。 作为外围辅助音韵模块，主干引擎仅提供四声量化接口。
版本号 #1
由 Admin 创建于 2026-09-08 13:51:19 CST
由 Admin 更新于 2026-09-08 13:51:19 CST