docs: bilingual module docs for the physics layer

crates/physics/apsis-coord/src/frames.rs

@@ -1,4 +1,6 @@
 //! Positions that carry their reference frame in the type.
+//!
+//! 在类型中携带其参考系的各类位置。
 
 use apsis_frames::{EarthRotationAngle, rotation_ecef_to_eci, rotation_eci_to_ecef};
 use apsis_geodesy::{

crates/physics/apsis-coord/src/lib.rs

@@ -39,6 +39,29 @@
 //!   implemented by `apsis-frames`.
 //! - Geodetic conversions and the WGS 84 ellipsoid: NIMA TR8350.2, third
 //!   edition, 2000, as implemented by `apsis-geodesy`.
+//!
+//! 坐标系及它们之间的变换。
+//!
+//! 本 crate 定义在类型中携带其参考系的各类位置，故在某坐标系中表达的位置
+//! 无法传递到期望另一坐标系之处。这两个坐标系是地心惯性（ECI）系与地心
+//! 地固（ECEF）系。
+//!
+//! 提供三种位置表示：
+//!
+//! - [`Eci`]，以米计的惯性直角坐标位置
+//! - [`Ecef`]，以米计的地固直角坐标位置
+//! - [`Geodetic`]，WGS 84 椭球之上的纬度、经度与高度
+//!
+//! [`Eci`] 与 [`Ecef`] 之间的变换是由地球自转角定义的转动，由
+//! `apsis-frames` 计算。[`Ecef`] 与 [`Geodetic`] 之间的变换使用来自
+//! `apsis-geodesy` 的 WGS 84 椭球。
+//!
+//! 出处：
+//!
+//! - 地球自转角：*IERS Conventions（2010）*，式 8.32，由 `apsis-frames`
+//!   实现。
+//! - 大地坐标换算与 WGS 84 椭球：NIMA TR8350.2，第三版，2000，由
+//!   `apsis-geodesy` 实现。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/physics/apsis-frames/src/earth_rotation.rs

@@ -1,5 +1,7 @@
 //! The Earth Rotation Angle and the rotation it defines between the
 //! inertial and Earth-fixed frames.
+//!
+//! 地球自转角，以及它定义的惯性系与地固系之间的转动。
 
 use apsis_math::Mat3;
 use core::f64::consts::PI;

crates/physics/apsis-frames/src/iau2000/fundamental.rs

@@ -28,6 +28,29 @@
 //! `eraNut00a`, with the planetary longitudes from `eraFame03`,
 //! `eraFave03`, `eraFae03`, `eraFama03`, `eraFaju03`, `eraFasa03` and
 //! `eraFaur03`.
+//!
+//! IAU 2000 章动理论的基本辐角。
+//!
+//! 章动级数是周期项之和，其辐角是时间的线性函数。每一项由施加于这些辐角的
+//! 整数乘数标识，故辐角必须按固定次序求值。
+//!
+//! 该理论中出现两套辐角，它们并不相同，这是一个容易出错的细节：
+//!
+//! - **日月**级数按 `l`、`l'`、`F`、`D`、`Om` 的次序使用五个 Delaunay
+//!   辐角：月球的平近点角、太阳的平近点角、月球的平纬度参数、月球相对太阳
+//!   的平距角，以及月球升交点的平黄经。
+//! - **行星**级数使用 `l`、`F`、`D`、`Om`、水星到天王星的平黄经、海王星的
+//!   平黄经，以及黄经上的一般累积岁差。
+//!
+//! 参考实现对 `l'` 与 `D` 用内联表达式求值，而对其他用函数，且这些内联
+//! 表达式在最后几位上不同于旧 IERS 2003 约定中同名函数。此处各值即该级数
+//! 所拟合的那些，故内联形式被再现。
+//!
+//! 所有辐角都以弧度计，并归约到 `[0, 2 pi)`。
+//!
+//! 出处：MHB2000 模型的辐角定义，如 `eraNut00a` 所实现，行星黄经取自
+//! `eraFame03`、`eraFave03`、`eraFae03`、`eraFama03`、`eraFaju03`、
+//! `eraFasa03` 与 `eraFaur03`。
 
 use core::f64::consts::PI;
 

crates/physics/apsis-frames/src/iau2000/mod.rs

@@ -31,6 +31,28 @@
 //! Source: the models and the order of the rotations follow the IAU SOFA
 //! library and its ERFA derivative. The specific functions are named in each
 //! module.
+//!
+//! IAU 2000/2006 地球定向模型。
+//!
+//! 从惯性系到地固系的变换是一串转动，每一个都来自不同的模型：
+//!
+//! 1. **坐标架偏差**，从国际天球参考系到 J2000.0 动力学平赤道与平春分点
+//!    的常值转动。
+//! 2. **岁差**，极的长期运动，来自 2006 年采纳的 P03 理论。
+//! 3. **章动**，极的周期运动，来自 2000 年采纳的 MHB2000 级数。
+//! 4. **地球自转角**，把坐标系从天球子午线带到地球子午线。
+//! 5. **极移**，极在地球内部的小运动，由调用方提供，因为它作为每日测量的
+//!    量发布。
+//!
+//! 前三者的合成是天球到中间坐标系的矩阵，再与自转角及极移合成则是天球到
+//! 地球坐标系的矩阵。对卫星工作，极移常被略去，因为它不到十分之一角秒，
+//! 但章动与岁差不能略去：章动达十七角秒，对低轨卫星即半千米的地面位置。
+//!
+//! 除非某函数另有说明，所有时间都是自 J2000.0 起、在地球时时标上的儒略
+//! 世纪。调用方提供给极移的各角以弧度计。
+//!
+//! 出处：各模型与转动的次序遵循 IAU SOFA 库及其 ERFA 衍生物。各具体函数在
+//! 各模块中指名。
 
 mod eect_table;
 mod fundamental;

crates/physics/apsis-frames/src/iau2000/nutation.rs

@@ -18,6 +18,21 @@
 //! Source: the MHB2000 model of Mathews, Herring and Buffett, adopted by the
 //! International Astronomical Union in 2000, as implemented in the IAU SOFA
 //! library and its ERFA derivative, functions `eraNut00a` and `eraNut06a`.
+//!
+//! IAU 2000A 章动模型。
+//!
+//! 章动是地球自转轴绕其平均位置的周期运动部分。它主要由月球与太阳对赤道
+//! 隆起的力矩造成，行星的贡献较小。该模型把真极相对平极的偏移给出为两个
+//! 角：黄经方向的章动与黄赤交角方向的章动。
+//!
+//! 该级数有两部分，其辐角与系数组都不同。日月部分有 678 项，由 Delaunay
+//! 辐角构成，其黄赤交角系数把余弦与常数项及时间项配对，而正弦独自成立。
+//! 行星部分有 687 项，由行星黄经构成，那里正弦与常数项配对而余弦独自成立。
+//! 把这两种分组弄反会产生角秒级的误差，故此处将它们分开。
+//!
+//! 出处：Mathews、Herring 与 Buffett 的 MHB2000 模型，2000 年由国际天文
+//! 学联合会采纳，如 IAU SOFA 库及其 ERFA 衍生物所实现，函数 `eraNut00a`
+//! 与 `eraNut06a`。
 
 use super::fundamental::{DelaunayArguments, PlanetaryArguments};
 use super::nutation_table::{LUNI_SOLAR, PLANETARY};

crates/physics/apsis-frames/src/iau2000/precession.rs

@@ -16,6 +16,20 @@
 //! adopted by the International Astronomical Union in 2006, as implemented
 //! in the IAU SOFA library and its ERFA derivative, functions `eraPfw06`,
 //! `eraPmat06`, `eraFw2m`, `eraBi00` and `eraObl06`.
+//!
+//! IAU 2006 岁差模型与坐标架偏差。
+//!
+//! 岁差是地球自转轴绕黄极缓慢的长期运动，主要由月球与太阳对赤道隆起的
+//! 力矩造成。IAU 2006 模型把它表达为从天球参考系到该日平赤道与平春分点的
+//! 转动，由四个角构成。
+//!
+//! 坐标架偏差计入了国际天球参考系的取向与 J2000.0 动力学平赤道与平春分点
+//! 之间的小偏移。它是常值转动，略去它会把位置放偏约二十毫角秒，这远高于
+//! 现代转换的精度。
+//!
+//! 出处：Capitaine、Wallace 与 Chapront 的 P03 岁差理论，2006 年由国际
+//! 天文学联合会采纳，如 IAU SOFA 库及其 ERFA 衍生物所实现，函数
+//! `eraPfw06`、`eraPmat06`、`eraFw2m`、`eraBi00` 与 `eraObl06`。
 
 use apsis_math::Mat3;
 use core::f64::consts::PI;

crates/physics/apsis-frames/src/iau2000/teme.rs

@@ -21,6 +21,23 @@
 //! edition, microcosm Press, 2013, section 3.7. The sidereal time
 //! expression is the one used by the SGP4 reference implementation, as
 //! given in the same work and implemented by `eraGmst82`.
+//!
+//! 真赤道平春分点坐标系及其到地固系的变换。
+//!
+//! SGP4 传播器在真赤道平春分点（TEME）坐标系中产生其状态。TEME 是该日的
+//! 真赤道，故其第三轴是真天极并携带章动，但它的第一轴指向平春分点而非真
+//! 春分点。
+//!
+//! 因为第一轴是平春分点，到地固系的变换使用格林尼治平恒星时而非视值。这
+//! 正是容易出错的细节：若像对真春分点坐标系那样再减去分点方程式，会把结果
+//! 转动约千分之一度，对低轨卫星即一千米的地面位置。
+//!
+//! 因此时间是 UT1 儒略日，由它得出平恒星时，最后施加极移。
+//!
+//! 出处：TEME 与地固系之间的关系见 Vallado, D. A.，*Fundamentals of
+//! Astrodynamics and Applications*，第 4 版，microcosm Press，2013，第 3.7
+//! 节。恒星时表达式即 SGP4 参考实现所用者，见同一著作，由 `eraGmst82`
+//! 实现。
 
 use super::terrestrial::PolarMotion;
 use apsis_math::Mat3;

crates/physics/apsis-frames/src/iau2000/terrestrial.rs

@@ -22,6 +22,23 @@
 //! is `eraNumat`, the rotation angle is `eraEra00`, the sidereal time for
 //! the equinox-based composition is `eraGmst06`, and the polar motion is
 //! `eraPom00`, composed by `eraC2t00b`.
+//!
+//! 天球到地球坐标系的变换。
+//!
+//! 本模块把坐标架偏差、岁差、章动、地球自转角与极移合成为把矢量从惯性系
+//! 带到地固系的转动。
+//!
+//! 合成中出现两个中间坐标系。**天球中间坐标系**是该日的真赤道与真春分点；
+//! 从惯性系到它的转动即偏差、岁差与章动。**地球中间坐标系**是经地球自转角
+//! 带到地球本初子午线的该坐标系。极移最后施加，因为它是极在地球内部的运动
+//! 而非地球在空间中的运动。
+//!
+//! 基本转动遵循参考实现的约定：`rz` 绕其第三轴转动坐标系，且合成 `a * b`
+//! 时先施加 `b`。正是该约定使下面的各乘积按各转动实际施加的次序阅读。
+//!
+//! 出处：该合成遵循 IAU SOFA 库及其 ERFA 衍生物。偏差与岁差是 `eraPmat06`，
+//! 章动矩阵是 `eraNumat`，自转角是 `eraEra00`，基于春分点合成的恒星时是
+//! `eraGmst06`，极移是 `eraPom00`，由 `eraC2t00b` 合成。
 
 use super::nutation::nutation_2000a_with_2006_adjustment;
 use super::precession::{frame_to_mean_of_date, mean_obliquity, rotation_z};

crates/physics/apsis-frames/src/lib.rs

@@ -41,6 +41,26 @@
 //! // The rotation is ready to apply to a vector.
 //! let _ = rotation_eci_to_ecef(first);
 //! ```
+//!
+//! 参考系定义，以及惯性系与地固系之间的转动。
+//!
+//! 参考系固定了矢量所相对表达的取向与原点。本 crate 为近地工作所用的两个
+//! 坐标系命名，并计算它们之间的转动。携带坐标系的具位置类型定义在
+//! `apsis-coord` 中；本 crate 处理转动矩阵以及定义它的角。
+//!
+//! 惯性系是与 J2000.0 平赤道与平春分点对齐的地心惯性（ECI）系。其各轴在
+//! 惯性空间中固定，故在其中传播的轨道不受地球转动影响。
+//!
+//! 转动坐标系是地心地固（ECEF）系。其第三轴是地球自转轴，第一轴随本初
+//! 子午线，故固定于地面的点在其中具有恒定坐标。
+//!
+//! 二者由绕公共第三轴转动 [`EarthRotationAngle`] 相联系。本 crate 用地球
+//! 自转角为地球自转建模，它仅是 UT1 的函数。它不施加岁差或章动，因为精确
+//! 到百分之几度的角对指向与覆盖工作已足够，而完整模型需要天极的取向，那是
+//! 另一项单独的计算。
+//!
+//! 出处：地球自转角表达式来自国际天文学联合会，如 *IERS Conventions
+//! （2010）* 式 8.32 所给出。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/physics/apsis-geodesy/src/ellipsoid.rs

@@ -1,4 +1,6 @@
 //! Reference ellipsoids.
+//!
+//! 参考椭球。
 
 /// A biaxial reference ellipsoid: an ellipse of revolution about its minor
 /// axis.

crates/physics/apsis-geodesy/src/geodetic.rs

@@ -6,6 +6,12 @@
 //! frame whose third axis is the ellipsoid's minor axis, and the choice of
 //! frame is the responsibility of the caller. `apsis-coord` supplies
 //! position types that carry the frame.
+//!
+//! 大地位置及其到地固直角坐标的换算。
+//!
+//! 此处的直角坐标位置是以米计的普通 [`Vec3`]。本 crate 有意不为该坐标系
+//! 命名：同一换算适用于第三轴为椭球短轴的任何坐标系，坐标系的选择是调用方
+//! 的责任。`apsis-coord` 提供携带坐标系的各位置类型。
 
 use crate::ellipsoid::Ellipsoid;
 use apsis_math::Vec3;

crates/physics/apsis-geodesy/src/lib.rs

@@ -23,6 +23,19 @@
 //! let cartesian = point.to_cartesian(WGS84);
 //! assert!((cartesian.norm() - WGS84.semi_major_axis()).abs() < 1e-9);
 //! ```
+//!
+//! 参考椭球与大地计算。
+//!
+//! 大地位置写为某椭球之上的纬度、经度与高度。此处的纬度总是大地纬度，即
+//! 椭球法线与赤道面之间的角，而非地心纬度。在中纬度处二者相差至多约 0.19
+//! 度，故该区别对指向与测距是要紧的。
+//!
+//! [`WGS84`] 是 GPS 以及几乎所有卫星工作所用的椭球。其定义参数是半长轴与
+//! 扁率倒数；其余每个量都由这两个导出，故各导出值与标准中发布的值在定义
+//! 参数的精度内一致。
+//!
+//! 出处：National Imagery and Mapping Agency，*Department of Defense World
+//! Geodetic System 1984*，技术报告 TR8350.2，第三版，2000。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/physics/apsis-leap/src/lib.rs

@@ -29,6 +29,22 @@
 //! assert_eq!(last.tai_minus_utc, 37.0);
 //! assert_eq!(tai_minus_utc_at_mjd(60_000.0), Some(37.0));
 //! ```
+//!
+//! 为 UTC 时标内嵌的闰秒表。
+//!
+//! 协调世界时（UTC）通过插入或删除闰秒保持在 UT1 的 0.9 秒以内。因为 UTC
+//! 不是均匀时标，在 UTC 与均匀时标 TAI、TT、GPS 之间换算需要所关注瞬时
+//! 生效的偏移 `TAI - UTC`。
+//!
+//! 本 crate 把该偏移内嵌为编译期表格，并对其作答查询。日期按约化儒略日
+//! （MJD）处理，它是儒略日减去 2 400 000.5。MJD 是自 1858-11-17T00:00:00
+//! 起的天数，故它自身不携带时标；调用方通过选择调用哪个函数来指明时标。
+//!
+//! 该表始于 1972-01-01，那是 UTC 采用当前整数秒偏移方案的时刻。该日之前的
+//! 偏移是小数并遵循不同规则，故早于首项的查询返回 `None` 而非误导性的值。
+//!
+//! 出处：IERS Bulletin C，它在国际地球自转与参考系服务确认之后宣布闰秒。
+//! 本表最近的一项是 2017-01-01 的闰秒；此后未再宣布闰秒。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/physics/apsis-leap/src/table.rs

@@ -1,5 +1,7 @@
 //! The compile time leap second table and the calendar helpers that place
 //! its entries on the Modified Julian Date scale.
+//!
+//! 编译期闰秒表，以及把其各项放到约化儒略日尺度上的日历辅助函数。
 
 /// One leap second announcement.
 ///

crates/physics/apsis-leap/src/time.rs

@@ -1,5 +1,7 @@
 //! Conversions between UTC and TAI expressed on the Modified Julian Date
 //! scale.
+//!
+//! 在约化儒略日尺度上表达的 UTC 与 TAI 之间的换算。
 
 use crate::table::{
     LEAP_SECONDS, TABLE_COVERS_FROM_MJD, TAI_MINUS_UTC_AFTER_LAST_ENTRY, mjd_from_ymd,

crates/physics/apsis-time/src/calendar.rs

@@ -14,6 +14,19 @@
 //! be represented as second 60. Values are not constrained here; callers
 //! that require a valid calendar date must check the fields they care
 //! about.
+//!
+//! 外推格里高利历换算。
+//!
+//! 该日历是外推格里高利历，在其历史采用之前也向前延伸。一天由其约化儒略日
+//! （MJD）标识，后者从 1858-11-17 起计天。MJD 0 是该日的起点，故某日的
+//! MJD 是整数，而日内某瞬时会加上一个零头。
+//!
+//! 该换算使用 Howard Hinnant 在 *chrono-Compatible Low-Level Date
+//! Algorithms*（2015）中发表的算法，它对格里高利历的整个范围都精确且无需
+//! 查找表。
+//!
+//! 秒字段是浮点数，以便闰秒可表示为第 60 秒。此处不对值施加约束；要求有效
+//! 日历日期的调用方必须检查它所关心的字段。
 
 use core::fmt;
 

crates/physics/apsis-time/src/epoch.rs

@@ -9,6 +9,15 @@
 //! epochs exact regardless of the scales they were created in. The scale is
 //! therefore not part of an epoch's identity; it is a parameter of the
 //! conversion methods that read or write a number.
+//!
+//! 瞬时类型及其时标换算。
+//!
+//! [`Epoch`] 把瞬时存为国际原子时中的约化儒略日。选用 TAI 作为内部表示，
+//! 因为它均匀，且本 crate 中其余每个时标要么是相对它的常值偏移，要么（对
+//! UTC 而言）是可查表的阶跃偏移。
+//!
+//! 存储统一时标使两个历元之间的比较与求差精确，与它们创建时所处的时标无关。
+//! 因此时标不属于历元的身份；它是读取或写入某数的各换算方法的参数。
 
 use crate::calendar::{
     Calendar, SECONDS_PER_DAY, mjd_from_ymd, seconds_of_day_from_mjd, ymd_from_mjd,

crates/physics/apsis-time/src/julian.rs

@@ -8,6 +8,14 @@
 //!
 //! The offset is exact, so these conversions introduce no rounding beyond
 //! the representation of the input.
+//!
+//! 约化儒略日与儒略日之间的换算。
+//!
+//! 儒略日自外推儒略历中 4713-01-01 的正午起计天。约化儒略日自 1858-11-17
+//! 的午夜起计天。故二者相差固定的天数，而半日的偏移计入了两种尺度开始一天
+//! 的时刻不同。
+//!
+//! 该偏移是精确的，故这些换算除输入的表示之外不引入舍入。
 
 /// The number of days between the start of the Julian Date scale and the
 /// start of the Modified Julian Date scale.

crates/physics/apsis-time/src/lib.rs

@@ -31,6 +31,24 @@
 //! - Leap seconds: IERS Bulletin C, embedded by `apsis-leap`.
 //! - Calendar algorithms: Howard Hinnant, *chrono-Compatible Low-Level Date
 //!   Algorithms*, 2015.
+//!
+//! 时标、历元与日历换算。
+//!
+//! 本 crate 提供工作区其余部分所用的时间模型。[`Epoch`] 是以国际原子时时标
+//! 上的约化儒略日存储的瞬时，[`TimeScale`] 指名某数所表达的时标。
+//!
+//! 存储单一的均匀时标使算术精确：两个历元之差即它们之间流逝的 SI 时间，
+//! 与它们创建时所处的时标无关。UTC 不均匀，因为插入闰秒以使其接近地球的
+//! 转动，故 UTC 换算经由 `apsis-leap` 中的表格。
+//!
+//! 出处：
+//!
+//! - 儒略日与约化儒略日约定：IAU，如 *Explanatory Supplement to the
+//!   Astronomical Almanac* 所述。
+//! - 地球时相对 TAI 的偏移：IAU 2000 Resolution B1.9。
+//! - 闰秒：IERS Bulletin C，由 `apsis-leap` 内嵌。
+//! - 日历算法：Howard Hinnant，*chrono-Compatible Low-Level Date
+//!   Algorithms*，2015。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/physics/apsis-time/src/scale.rs

@@ -14,6 +14,20 @@
 //! Source: IAU 2000 Resolution B1.9 for Terrestrial Time; the GPS interface
 //! specification for GPS time. Neither relation has changed since those
 //! definitions took effect, so both are treated as constants here.
+//!
+//! 时标及它们之间的固定偏移。
+//!
+//! 表示四种时标。TAI、TT 与 GPS 是均匀的：其中一秒即一个 SI 秒，它们只相差
+//! 由定义固定的常值偏移。UTC 不均匀，因为它由闰秒调整以保持接近地球的转动。
+//!
+//! 均匀时标之间的偏移是精确的：
+//!
+//! - `TT = TAI + 32.184 s`，由地球时的定义。
+//! - `TAI = GPS + 19 s`，由 GPS 时的定义，其原点被设为与 1980-01-06 的 UTC
+//!   重合。
+//!
+//! 出处：地球时见 IAU 2000 Resolution B1.9；GPS 时见 GPS 接口规范。自这些
+//! 定义生效以来两个关系都未改变，故此处二者都被当作常量。
 
 use core::fmt;