b612
044f2f4381
- 新增半解析、旧模型、自定义与多源堆叠星历实例，提供 Context、Instance、SPK 读取及状态与视位置计算 - 统一太阳、月球和行星实例接口，扩展黄经穿越、留、相位、最近角距、偕日可见、任意高度升落、轨道节点及凌日等天象查询 - 完善日月食、月掩与凌日的月缘剖面、有限盘面接触、站心修正、局地可见性、全球路径和地图输出 - 新增 SVG、GeoJSON、KML 天象输出及凌日、月掩和月缘地形相关缓存与几何求解 - 新增恒星星表导入与查询，支持 CSV、Hipparcos、BSC5、Stellarium 等格式及名称、交叉标识、锥面检索和星等过滤 - 补充 IAU 2006、地球定向、折射消光、大气观测、轨道传播及半解析行星/月球数据支持 - 将默认未来民用时标切换为 TimeScaleLeapHour，更新 2027–2400 农历速查表、中文日期解析和时区边界处理 - 增加事件基线、跨模型回归、几何边界、月缘地形和输出契约测试，完善中英文手册、示例资源、NOTICE 与忽略规则
10 KiB
精度与性能
内置两套星历，误差随模型、年代与计算项目变化。表头注明的模型与区间之外，数值不可直接套用。
目录
星历模型
本库内置两套星历，默认是半解析模型（ModelSemianalytic）：保留行星理论的幅角结构（整数乘子）和初始振幅，把振幅、基本幅角多项式与少量修正项重新拟合到 DE441，全部折叠进同一张级数表。运行时不再挂残差层，也不需要外部星历文件。
- 基准理论：水星、金星、地球、火星用 VSOP2013；木星、土星、天王星、海王星用 TOP2013；月球用 ELP/MPP02。
- 拟合真值：长时段用 DE441；行星现代段用 DE440。
- 可用区间：TT JD
-1931455.0 … 5373545.0（J2000 前后 12000、8000 儒略年），越界仍外推，精度不保证。 - 现代段（仅行星）：J2000 ±1000 儒略年（TT JD
2086295.0 … 2816795.0）按 DE440 单独拟合一张表，与长时段表在两端各 100 年内平滑过渡，近代精修优先使用它。 - 求值规模：
n < 0用完整级数，与不带N的接口一致；所有n >= 0共用同一张快速表，供粗搜索使用。只有 Legacy 的n才按项数截断。 - 数据量：行星表约 452 KiB、月球表约 42 KiB，随程序编译进去；即使只用到部分天体，行星表和月球表也都会链接，显式实例不减小二进制体积。
- 坐标系：表内是 J2000 平黄道几何位置，使用时旋转到当日平黄道，再走与 Legacy 相同的视位置链路（光行时、光行差、岁差与章动）。
旧模型 ModelLegacy 使用 VSOP87/ELP2000-82 截断级数，并在级数之外叠加订正项：行星为地球的三次多项式与其余天体的常数订正，月球为额外的多项式项、岁差项和公元 3000–5000 年的拟合项。lite/sun、lite/moon 使用的是另一套简化公式，两者不要混用。
模型选择
| 模型 | 内容 | 适用 |
|---|---|---|
ModelSemianalytic |
内置半解析表，默认构建（不加 astro_legacy 标签）的模型 |
日常位置、历法、观测和天象计算 |
ModelLegacy |
VSOP87/ELP2000-82 截断级数，叠加长期项与逐天体订正，n 按项数截断 |
复现旧数值和模型对照；astro_legacy 构建下为默认 |
ModelCustom |
SPK 或调用方提供的只读引擎 | 精度由外部核、其可用区间和上层转换共同决定 |
lite/sun、lite/moon |
独立近似链路 | 资源受限环境；不随模型切换 |
显式 Context/Instance 固定星历，但 ΔT、TT−UTC 和民用时标政策仍是进程级设置。签名不变、默认数值可变，这一点与旧版不同；需要旧模型数值时显式选择 Legacy。用法见显式星历实例。
测量口径
除另有说明，以下数据都是与 DE440/DE441 的 TT 格点对比，单位角秒：
- 参考端用 Skyfield 1.55，只做 TT 到 TDB 的换算，不引入 UTC、UT1 或 ΔT 差异。表中的"半解析全量"指
n < 0，"半解析快速"指n >= 0。 - 现代区间：TT JD
2415020.5 … 2488434.25，步长 0.25 日，共293656点，约 1900–2100 年。 - 长区间：TT JD
990545.0 … 3912545.0，J2000 ±4000 儒略年，共365252点；DE441 两段核在 JD2440416.5切换。 - 几何量用日期平黄道/平春分点，视赤经/视赤纬用日期真赤道/真春分点。
- 表中 MAE 是平均绝对误差，RMS 是均方根误差，P95 是绝对误差的 95 分位，最大是采样最大值；角度是地心视方向夹角，不是单个坐标分量的误差。最大值只是样本最大值，不是连续时间上的误差上界。
地心视方向
太阳：
| 区间/模型 | MAE | RMS | P95 | 最大 |
|---|---|---|---|---|
| 现代 DE440/Legacy | 0.03895 |
0.04475 |
0.08013 |
0.1372 |
| 现代 DE440/半解析全量 | 0.00556 |
0.00682 |
0.01329 |
0.02680 |
| 现代 DE440/半解析快速 | 0.1783 |
0.2219 |
0.4415 |
0.9675 |
| 长区间 DE441/Legacy | 2.659 |
4.171 |
9.751 |
16.68 |
| 长区间 DE441/半解析全量 | 1.774 |
3.187 |
7.908 |
14.08 |
| 长区间 DE441/半解析快速 | 2.431 |
4.050 |
9.878 |
17.15 |
月球：
| 区间/模型 | MAE | RMS | P95 | 最大 |
|---|---|---|---|---|
| 现代 DE440/Legacy | 0.7431 |
0.7499 |
0.9171 |
1.3297 |
| 现代 DE440/半解析全量 | 0.06302 |
0.07591 |
0.1437 |
0.4418 |
| 现代 DE440/半解析快速 | 3.455 |
3.991 |
7.092 |
18.18 |
| 长区间 DE441/Legacy | 42.16 |
67.10 |
156.35 |
233.58 |
| 长区间 DE441/半解析全量 | 1.788 |
3.182 |
7.920 |
14.08 |
| 长区间 DE441/半解析快速 | 6.098 |
7.359 |
14.30 |
39.74 |
现代样本中半解析全量的视方向 RMS 是 0.00682″（太阳）与 0.07591″（月球），低于 Legacy 的 0.04475″ 与 0.7499″；快速表是 0.2219″ 与 3.991″，比 Legacy 更差，月球尤其明显。长区间的结果包含整条高层转换链和参考框架差异，不能全部归因于级数本身。
固定 ICRF 几何方向
下表单独比较半解析全量 Instance.State(target, BodyEarth, jd) 与 DE 的地心 ICRF 几何向量，不经过日期岁差/章动转换。库内以 TT 数值近似 TDB，参考端仍从同一 TT 转 TDB，所以这一组是近似 TDB 下的对比。单位角秒：
| 区间/天体 | MAE | RMS | P95 | 样本最大值 |
|---|---|---|---|---|
| 现代 DE440/太阳 | 0.00551 |
0.00677 |
0.01320 |
0.02655 |
| 现代 DE440/月球 | 0.06301 |
0.07591 |
0.1437 |
0.4414 |
| 长区间 DE441/太阳 | 0.04100 |
0.05754 |
0.1214 |
0.3613 |
| 长区间 DE441/月球 | 0.09163 |
0.1129 |
0.2170 |
0.8825 |
长区间中固定框架误差远小于高层日期框架的视方向差异，说明整条计算链的误差不能用一个"模型精度"数字概括。Legacy 没有几何引擎，不列入此表。
几何月地距离
单位 km，取地心距：
| 区间/模型 | MAE | P95 | 最大 |
|---|---|---|---|
| 现代 DE440/Legacy | 0.1434 |
0.3633 |
0.9143 |
| 现代 DE440/半解析全量 | 0.04674 |
0.1172 |
0.3312 |
| 现代 DE440/半解析快速 | 1.730 |
4.356 |
9.818 |
| 长区间 DE441/Legacy | 2.204 |
9.834 |
26.90 |
| 长区间 DE441/半解析全量 | 0.06496 |
0.1669 |
0.5576 |
| 长区间 DE441/半解析快速 | 2.005 |
5.160 |
16.10 |
Legacy 截断误差
下表是 Legacy 相对完整 VSOP87 的截断误差参考，不是半解析精度，也不是相对 DE440/DE441 的综合误差：
| 目标 | 黄经/黄纬 | 距离 |
|---|---|---|
| 太阳/地球 | 约 0.1″ |
约 0.1 × 10^-6 AU |
| 水星、金星 | 约 0.2″ |
约 0.2 × 10^-6 AU |
| 火星 | 约 0.5″ |
约 1 × 10^-6 AU |
| 木星 | 约 0.5″ |
约 3 × 10^-6 AU |
| 土星 | 约 0.5″ |
约 5 × 10^-6 AU |
| 天王星 | 约 1″ |
约 20 × 10^-6 AU |
| 海王星 | 约 1″ |
约 40 × 10^-6 AU |
Lite 轻量链路
lite/sun 是简化太阳公式，lite/moon 是含少量摄动项的近似月球链；升落搜索用固定步长扫描加二分，太阳 30 分钟、月球 15 分钟。两者不使用主链表，也不随模型切换。下表是 2026 全年、8 个站点相对 Legacy 主链的误差（统计量含义同测量口径）：
| 计算项 | 平均绝对误差 | P95 | 最大 |
|---|---|---|---|
| 太阳日出/日落 | 0.02 / 0.02 min |
0.04 / 0.06 min |
0.31 / 0.35 min |
| 月出/月落 | 0.28 / 0.36 min |
0.57 / 0.86 min |
1.44 / 1.24 min |
Phase() |
0.00089 |
0.00185 |
0.00243 |
PhaseAge() |
0.003 d |
0.010 d |
0.014 d |
这些样本并非全部事件语义一致：太阳日落有 2 个高纬跨午夜日期归属差异，月落有 1 个高纬"当天是否发生"的分歧。升落每 7 或 15 天采样，月相/月龄每 6 小时。表里的时间差只能说明已有事件的一致性，不能用来判断事件是否存在。日月食、物理天平动和高纬事件边界不走 lite 链路，由主链计算。
性能
Linux/WSL、Intel i7-12700、Go 1.25.9，基准并行度 20、每项 300 ms。重复查询同一时刻和站点，属于热缓存测量，不含首次加载：
| 入口 | 半解析全量 | Legacy 全量 | Lite |
|---|---|---|---|
Sun ApparentRaDec |
0.606 µs |
8.988 µs |
0.213 µs |
Sun Altitude |
0.770 µs |
9.134 µs |
0.627 µs |
Sun RiseTime |
628.6 µs |
144.8 µs |
25.88 µs |
Moon ApparentRaDec |
0.855 µs |
9.373 µs |
1.003 µs |
Moon Phase |
1.171 µs |
14.81 µs |
0.914 µs |
Moon Altitude |
1.006 µs |
9.520 µs |
1.136 µs |
Moon RiseTime |
487.4 µs |
135.0 µs |
117.4 µs |
半解析的热缓存位置接口与 Lite 互有快慢；升落搜索每次都要在新历元求值，速度会下降，Legacy 在部分升落入口反而更快。以上是单次运行的绝对值，会随机器和调用形态变化。
半解析的 Sun/Moon RiseTime 分别有 60/36 次分配，表中其余求值接口为 0 次分配。零分配只覆盖这些路径，其他接口不做保证。
换算与注意事项
- 升落差异要先统一折射模型、视半径口径、观测点高度和当地日归属，地平线定义的影响常大于星历差异。
- 节气、朔望和食接触直接比较 TT 事件时刻；把位置角秒说成时间误差前，要先除以该处的局部角速度。
- 民用日期还取决于时区和时标政策，接近子夜的事件尤其敏感。
- 自定义 SPK 的几何状态使用 ICRF、km、km/日和 TDB；高层标量与视位置入口接收 TT，当前以 TT 近似 TDB。需要严格 TDB 时直接调用
Instance.State；换用更精确的核不会自动提升上层的坐标框架、大气与地形模型。 - IAU 2006/2000A、极移、CPO 和月缘剖面都需要显式调用或显式设置，默认链路不会自动启用；见坐标工具、公式和日月食与凌日。