# 精度与适用范围

[返回首页](../README.md) · [模型修正](./model-corrections.md)

## 日期范围

主要星历模型面向天文年 `-6000..10000`，小行星可选包为 `-3000..3000`，
冥王星仅推荐 `1600..2200`。
需要前后年度数据的接口使用更窄的查询范围，例如黄历日期入口为 `-5999..9999`。
接口能够返回结果，不代表该日期的结果满足任意精度要求。

小行星的逐对象数据来源、三维误差统计和官方 SPK 覆盖区间见
[小行星与半人马小行星](./asteroids.md)。

## 几何位置

几何位置采用 J2000 平黄道坐标，不包含光行时、光行差或观测者视差。
八大行星和月球的轨道校准包含在系数中，没有运行时校准开关。

| 对象 | 位置约定 |
| --- | --- |
| 地球 | 物理地球中心；与地月质心接口分别提供 |
| 月球 | 地心几何位置使用 km；日心位置使用 AU |
| 木星、土星、天王星、海王星 | 对应行星系统质心 |
| 冥王星 | 冥王星系统质心，不是本体中心或光心 |

精度随天体和年代变化，库不提供覆盖整个时段的统一误差上限。
速度由模型解析求导；位置误差不能直接换算为速度误差或事件时刻误差。
接口与单位见[天体位置](./positions.md)。

### 对照 DE441 与完整理论

[完整模型对照](./model-comparison.md)列出了本库三档位置计算，以及全量 VSOP87A、
VSOP2013、TOP2013、ELP/MPP02、ELP2000-82B 相对 DE441 的实测结果。
每个区间使用相同的 2,050 个日期，分别报告 1600～2200、−1000～3000 和 −6000～10000 年。
结果按模型自身的中心、原生坐标系及发布的方向联系统一后比较；不混用地球中心和地月质心。
该页包含 RMS、样本最大值、来源和复现步骤；这些统计不是连续误差保证或事件定时误差。

### 位置计算档位

几何位置函数直接接受可选的 `accuracy` 字符串，例如
`planetHeliocentricState('mars', jdTT, 'fast')`；视位置因另有参考系和物理修正
选项，使用 `{ accuracy: 'fast' }`。省略时均为 `accurate`。三档共享同一套
系数；fast／mid 只按档位计数表读取生成阶段排好的各阶开头部分，不设置模块级状态。

下表是 fast／mid **相对本库 accurate 档**的位置差，不是相对真实星历的误差。
水星至海王星、地球和月球在天文年 `-6000..10000` 每 25 年取样；冥王星在
推荐的 `1600..2200` 每年取样，单位均为 km。它用于说明截断代价，不能与模型对 DE441
的误差直接相加或当作逐日上限。

| 对象 | Fast RMS / 最大 | Mid RMS / 最大 |
| --- | ---: | ---: |
| 水星 | 21.6 / 59.5 | 5.3 / 16.2 |
| 金星 | 31.1 / 72.0 | 6.9 / 18.3 |
| 地球 | 242 / 650 | 26.6 / 103 |
| 火星 | 82.7 / 259 | 13.3 / 40.7 |
| 木星 | 554 / 1,375 | 69.3 / 200 |
| 土星 | 1,372 / 3,923 | 223 / 540 |
| 天王星 | 9,128 / 25,540 | 1,070 / 3,259 |
| 海王星 | 9,179 / 23,537 | 1,238 / 3,131 |
| 月球 | 4.08 / 20.7 | 0.57 / 1.60 |
| 冥王星（1600..2200） | 295 / 766 | 144 / 295 |

外行星的长期小项较多，所以 mid 为维持宽年代表现仍保留了大部分系数，速度收益
会小于 fast。定气定朔的三档还会切换事件专用模型、求根步骤及视位置修正链，
其速度倍率不能用这张单次位置表推断。

### 冥王星

**推荐范围为 1600..2200 年。范围外使用低精度后备模型，不适用于精密天象定时。**

推荐范围内使用直接拟合 DE441 的 L/B/R Chebyshev 模型；所谓“后备模型”是
`mixed-low-w95` 低阶混合频率拟合，只用于避免把近代高阶多项式外推到远端。
它不是 C++ 半解析表，也没有全时段精度承诺。1590..1600、2200..2210 年为
近代模型与后备模型的平滑过渡区。
范围判断使用儒略年 `2000 + (jdTT - 2451545) / 365.25`；
`PLUTO_MODEL_INFO` 提供模型范围和警告。

视直径使用冥王星本体的约定半径，位置仍为系统质心，不能据此预测精密掩星。

## 视位置与地平观测

视位置在几何星历上加入光行时、光行差、适用的太阳光线偏折和参考面变换。
其精度同时受底层星历与这些计算步骤限制。
模型不包含太阳绕太阳系质心的运动、Shapiro 延迟或多体光线偏折，并以 TT 近似 TDB。

地平位置还依赖观测时刻、地点和大气参数，并计算观测者视差。
实时大气条件、地形、地平俯角、极移和周日光行差未纳入通用观测模型。
日出日落在高纬及接近相切时对折射和地平高度尤其敏感。
参数见[视位置与地平观测](./sky-events.md)。

## 天文事件与时间尺度

事件求解使用 JD(TT)。`toleranceSeconds` 控制模型内的数值求根误差，
不表示相对真实天象的绝对误差；实际精度还取决于星历、参考面和事件定义。
近远点附近的距离曲线较平，同样大小的位置误差可能产生较大的时刻差异。

TT 与 UT1 通过 ΔT 转换。时间层采用 UTC≈UT1，未包含闰秒和地球定向参数（EOP）。
远古和远期的 ΔT 不确定性会影响民用时刻，接近午夜的天象还可能因此改变归日。
历史模式的历书归日与实际天象时刻可分别读取。

## 定气设置

`solveSolarLongitude()` 默认使用 `mid`。三档区别如下：

| 档位 | 计算方式 | 使用限制 |
| --- | --- | --- |
| `fast` | 最终太阳／月球主黄经完整级数、简化物理修正与固定次数迭代 | 不接受数值容差；不保证与其他档位的分钟取整结果一致 |
| `mid` | 专用事件黄经模型，按容差迭代 | 地球黄经、黄纬使用完整级数，光行差采用 30 个完整同频率包络 |
| `accurate` | 完整库内视位置模型，按容差迭代 | 保留光行时、光行差与完整坐标变换，仍受底层星历限制 |

对精度敏感的事件定时，应显式选择 `accurate`。
`mid` 和 `accurate` 的 `toleranceSeconds` 默认值为 `0.01` 秒，
无法达到的容差可能导致求解失败；小于浮点 JD 分辨率的容差没有保证。
两档均可用 `solver: 'safeguarded'` 选择带区间保护的求解器。

直接在 `solve…` 中传入 `{ accuracy }`；中国历法和上层包通过各自的 `eventAccuracy` 选项传递档位。
带 `Fast`、`Accurate` 后缀的累计角度函数固定使用对应档位。
调用方式见[定朔定气档位](./time-and-calendar.md#定朔定气档位fast--mid--accurate)。

## 定朔设置

`solveNewMoon()` 和 `solveLunarPhase()` 使用相同的三档设置。
仅在 `mid` 档可指定 `moonLatitudeTerms`，用于控制日期参考系变换中的月球黄纬项数：

| 值 | 含义 |
| --- | --- |
| `0`、`5`、`10`、`20` | 按指定项数计算黄纬，默认 `10` |
| `'full'` | 使用完整黄纬级数 |

增加项数可减小黄纬截断的影响，但不能消除底层星历误差。
`fast` 固定为 `10`，`accurate` 固定为 `'full'`；这两档不接受自定义项数。
此选项不影响通用月球位置与状态接口。

## 事件搜索

通用搜索通过离散扫描定位变号区间，再细化求根。
`stepDays` 应足够小，以分辨目标事件；同一扫描间隔内的多个根及相切根可能漏检。
较长区间宜分段搜索，并根据天体运动速度选择步长。

事件定义、参考面和参数见[天象搜索](./sky-events.md)，
模型来源见[第三方声明](../THIRD_PARTY_NOTICES.md)。