b612/astro
1
1
Fork 0
Code Issues Pull Requests Projects Releases 21 Wiki Activity

21 Releases 21 Tags

RSS Feed
  • v0.4.0 0e3825d5ba
    Compare

    v0.4.0 Stable

    b612 released this 2026-10-16 08:06:13 +08:00 | 0 commits to master since this release

    中文

    v0.4.0

    v0.4.0 是一次包含破坏性行为变更的版本。本版本最重要的变化是：观测数据覆盖范围之外的默认民用时标政策由闰秒外推改为闰时外推，对应 2027年5月20日起生效的连续 UTC 口径。

    1972–2026 年仍使用确定的历史闰秒表，历史结果保持不变；但在内置数据窗口结束后，库不再默认按 ±0.9 秒约束周期性插入整数秒，而是允许 |UT1−UTC| 在 ±3600 秒范围内变化，并在必要时施加整小时校正。本版本同时将默认星历模型切换为半解析模型，并新增显式星历实例、外部 SPK 和通用天象接口。

    破坏性变更

    • 默认未来民用时标政策由 TimeScaleLeapSecond 改为 TimeScaleLeapHour：
      • TimeScaleLeapHour 现在是零值和默认值；
      • 四个常量的数值随之改变：TimeScaleLeapSecond 0→1、TimeScaleAssumeUT1Tracking 1→2、TimeScaleFreezeUTCOffset 2→3、TimeScaleLeapHour 3→0（TimeScaleUT1Civil 不变）；
      • 传入裸整数的 SetTimeScaleFuturePolicy 调用方需要更新。
    • 内置时标数据窗口截至 2026 年 10 月 1 日：
      • 1972–2026 年继续使用确定的闰秒表；
      • 窗口之后默认采用闰时策略；
      • 默认情况下，未来 TT−UTC 将在很长时间内保持 69.184 秒，直到外推的 DUT1 达到或超过 ±1 小时。
    • 包级天文计算默认模型改为半解析模型。太阳、月球和行星的数值结果可能与旧版级数模型存在差异：
      • 需要复现旧结果时，可调用 astro.SetModel(astro.ModelLegacy)（返回 error）；
      • 或用 ctx, err := astro.NewContext(astro.ModelLegacy) 固定一个旧模型上下文。
    • TimeScaleUTC 与 TimeScaleUT1 只决定输出标签的时标，不改变未来民用时标政策；需要区分“未来换算政策”和“输出标签时标”。

    主要变更

    • 新增 Legacy、半解析、自定义和多源堆叠星历模型，提供 Context、Instance、SPK 文件读取和外部星历引擎接口。
    • 支持在同一进程中并行使用多个星历上下文，并为太阳、月球和七大行星提供统一的实例化访问接口。
    • 新增黄经穿越、留、相位、最近角距、偕日可见、任意高度升落、近远日点、轨道节点和行星凌日等通用天象查询。
    • 完善日食、月食、恒星月掩和行星月掩的月缘剖面、有限盘面接触、站心修正、局地可见性和全球路径计算。
    • 扩展 SVG、GeoJSON 和 KML 天象输出，增加凌日地图、时间标记、月缘地形和局地接触数据。
    • 新增恒星星表模块，支持 CSV、Hipparcos、BSC5、Stellarium 等格式，以及名称解析、交叉标识、锥面检索、星等过滤和升落计算。
    • 补充 IAU 2006、地球定向、折射、消光、大气观测、轨道传播和半解析行星/月球数据支持。
    • 增加跨模型回归、事件基线、几何边界、月缘地形、SPK 和输出契约测试。
    • 更新中英文 README 与全部手册，以及示例图片、测试数据和发布 NOTICE。

    修正

    • calendar.GanZhiOfDay 先换算到东八区，非东八区宿主上的干支日结果可能与旧版不同。
    • 星表 Strict 模式改为一并拒绝非有限视差（±Inf），此前会被静默当作无视差；这是收紧，可能导致原本通过的输入报错。
    • calendar.Time.Add 越界时保留公历时刻、农历部分为空，不再返回零值。
    • phenomena 的事件时刻改用显式时区，不再依赖宿主 Local，非本地时区宿主上的结果可能改变。
    • 偕日事件不再越过请求的 endJD；星座判定不再对边界坐标返回空串；KML 读取跨反经线多边形时按 ±180° 拆分并补接缝交点。
    • lite/sun、lite/moon 的地平俯角此前错误把纬度当弧度计算使用，现已改正并与主链 basic.HeightDegreeByLat 完全一致。只影响传入了观测高度的升落计算：在高度 10 km 处旧值偏差最大约 14″、且误差随纬度改变符号，对应时刻差约 0.9 秒。

    闰时与未来时标

    2026 年 10 月 15 日，第 28 届国际计量大会通过第 5 号决议《关于确保 UTC 连续性所需的技术行动》（Resolution-CGPM-28-5，DOI 10.59161/CGPM2026RES5E）：连续 UTC 自 2027 年 5 月 20 日起生效，允许的 |UT1−UTC| 范围由 ±0.9 秒放宽到 ±3600 秒。

    本版本据此将 TimeScaleLeapHour 设为默认政策：

    • TimeScaleLeapHour：按外推 ΔT 计算，在 DUT1 达到或超过 ±3600 秒时施加最少整小时校正，匹配连续 UTC 的闰时制度。
    • TimeScaleLeapSecond：继续提供旧的整数秒外推，仅用于复现 1972–2026 年确定的闰秒口径或进行对照。
    • TimeScaleAssumeUT1Tracking：保持末端 DUT1，令民用时标平滑跟随 UT1。
    • TimeScaleFreezeUTCOffset：冻结内置窗口末端的 TT−UTC 偏移。
    • TimeScaleUT1Civil：将全时轴上的民用时标视为 UT1。

    观测数据覆盖范围内始终优先使用实测的 UTC、UT1、DUT1 和显式注入的 TT−UTC 数据。除 TimeScaleUT1Civil 替换全时轴定义外，上述未来政策只影响覆盖范围之外的预测与模拟。需要某个具体日期的精确民用时刻时，应使用该日期发布的官方时标数据。

    升级建议

    升级前请重点检查：

    1. 是否依赖 TimeScaleFuturePolicy 的裸整数值；TimeScaleLeapHour 现在是零值。
    2. 是否假定未来日期默认按闰秒外推；需要旧行为时显式设置 TimeScaleLeapSecond。
    3. 是否依赖旧版级数模型的数值结果；需要复现时设置 ModelLegacy。
    4. 是否将输出标签时标与未来民用时标政策混为一谈。
    5. 是否需要使用 Context 固定星历模型，避免进程级模型切换影响结果。
    6. GeoJSON、SVG 和 KML 消费方是否能处理新增的天象角色、时间标记和地图要素。

    English

    v0.4.0

    v0.4.0 introduces breaking behavioral changes. The most important change is that the default civil-time policy beyond the observed data range changes from leap-second extrapolation to leap-hour extrapolation, matching continuous UTC effective from 20 May 2027.

    The definitive leap-second table remains unchanged for 1972–2026. Beyond the built-in data window, however, the library no longer assumes periodic integer-second corrections to keep |UT1−UTC| within ±0.9 seconds. The default policy now allows |UT1−UTC| to reach ±3600 seconds and applies whole-hour corrections when required. This release also makes the semianalytic ephemeris the default model and adds explicit ephemeris contexts, external SPK support, and generic sky-event APIs.

    Breaking Changes

    • The default future civil-time policy changes from TimeScaleLeapSecond to TimeScaleLeapHour:
      • TimeScaleLeapHour is now the zero value and the default;
      • four constant values change accordingly: TimeScaleLeapSecond 0→1, TimeScaleAssumeUT1Tracking 1→2, TimeScaleFreezeUTCOffset 2→3, TimeScaleLeapHour 3→0 (TimeScaleUT1Civil is unchanged);
      • callers passing raw integers to SetTimeScaleFuturePolicy must update.
    • The built-in time-scale data window ends on 1 October 2026:
      • 1972–2026 continues to use the definitive leap-second table;
      • dates beyond the window use the leap-hour policy by default;
      • under the default policy, TT−UTC remains at 69.184 seconds for a long time, until extrapolated DUT1 reaches or exceeds one hour.
    • Package-level astronomical calculations now use the semianalytic model by default. Solar, lunar, and planetary values may differ from the legacy series model:
      • use astro.SetModel(astro.ModelLegacy) (returns an error) to reproduce legacy package-level results;
      • or fix one with ctx, err := astro.NewContext(astro.ModelLegacy).
    • TimeScaleUTC and TimeScaleUT1 control output labels only. They are independent from the future civil-time conversion policy; keep the future conversion policy distinct from the output label scale.

    Highlights

    • Added legacy, semianalytic, custom, and multi-source stacked ephemeris models, with Context, Instance, SPK loading, and external engine interfaces.
    • Added multiple independent ephemeris contexts that can coexist in one process, with consistent instance-based APIs for the Sun, Moon, and seven planets.
    • Added generic searches for longitude crossings, stations, phases, closest approaches, heliacal visibility, arbitrary-altitude rise/set, apsides, orbital nodes, and planetary transits.
    • Expanded solar eclipses, lunar eclipses, stellar occultations, and planetary occultations with lunar-limb profiles, finite-disk contacts, topocentric corrections, local visibility, and global paths.
    • Expanded SVG, GeoJSON, and KML exports with transit maps, time markers, lunar-limb terrain, and local-contact data.
    • Added star-catalog loading and search for CSV, Hipparcos, BSC5, and Stellarium formats, including name resolution, cross-identifiers, cone searches, magnitude filters, and rise/set calculations.
    • Added IAU 2006, Earth-orientation, refraction, extinction, atmospheric-observation, orbit-propagation, and semianalytic planetary/lunar data support.
    • Added cross-model regression tests, event baselines, geometry-boundary tests, lunar-limb tests, SPK tests, and output-contract coverage.
    • Updated the bilingual README and all manuals, plus example assets, test data, and the release NOTICE.

    Fixes

    • calendar.GanZhiOfDay now converts to UTC+8 first; sexagenary-day results on non-UTC+8 hosts may differ from previous releases.
    • Star-catalog Strict mode now also rejects non-finite parallax (±Inf), which used to be silently treated as no parallax; this is a tightening and may make previously accepted input fail.
    • calendar.Time.Add keeps the solar instant with an empty lunisolar part instead of returning a zero Time when out of range.
    • phenomena event instants now use an explicit zone rather than the host Local, so results on non-local hosts may change.
    • Heliacal events no longer fall beyond the requested endJD; constellation lookup no longer returns an empty string for boundary coordinates; KML splits polygons that cross the antimeridian at ±180° and adds the seam vertex.
    • The horizon dip in lite/sun and lite/moon previously treated latitude as radians; it now matches basic.HeightDegreeByLat exactly. Only rise/set calls that pass an observer height are affected: the old value was off by up to about 14″ at 10 km height, with the error changing sign with latitude, shifting the computed time by about 0.9 s.

    Leap Hours and Future Time Scales

    On 15 October 2026 the 28th General Conference on Weights and Measures adopted Resolution 5, "On the technical actions needed to ensure the continuity of UTC" (Resolution-CGPM-28-5, DOI 10.59161/CGPM2026RES5E): continuous UTC becomes effective on 20 May 2027, widening the allowed |UT1−UTC| range from ±0.9 seconds to ±3600 seconds.

    Accordingly, this release makes TimeScaleLeapHour the default policy:

    • TimeScaleLeapHour: extrapolates ΔT and applies the fewest whole-hour corrections when DUT1 reaches or exceeds ±3600 seconds, matching the continuous-UTC leap-hour policy.
    • TimeScaleLeapSecond: retains the previous integer-second extrapolation for reproducing the definitive 1972–2026 convention or for comparison.
    • TimeScaleAssumeUT1Tracking: preserves the terminal DUT1 value and lets civil time follow UT1 smoothly.
    • TimeScaleFreezeUTCOffset: freezes TT−UTC at the end of the built-in window.
    • TimeScaleUT1Civil: treats civil time as UT1 throughout the full timeline.

    Observed UTC, UT1, DUT1, and explicitly injected TT−UTC data remain authoritative inside the covered range. Except for TimeScaleUT1Civil, which replaces the scale across the whole timeline, these policies affect only predictions and simulations outside that range. For precise civil timing on a specific date, use the official time-scale data published for that date.

    Upgrade Checklist

    • Check for code that depends on raw TimeScaleFuturePolicy integer values; TimeScaleLeapHour is now zero.
    • Explicitly select TimeScaleLeapSecond wherever the old future extrapolation is required.
    • Check golden values that depend on the legacy ephemeris model; select ModelLegacy when reproducing them.
    • Keep output-label selection separate from future civil-time policy selection.
    • Use Context when a calculation must remain pinned to a specific ephemeris model.
    • Ensure SVG, GeoJSON, and KML consumers accept the additional sky-event roles, time markers, and map features.
    Downloads