docs: bilingual module docs for the orbit layer

crates/orbit/apsis-ephemeris/src/ephemeris.rs

@@ -1,4 +1,6 @@
 //! The ephemeris table and its Hermite interpolation.
+//!
+//! 星历表及其 Hermite 插值。
 
 use crate::error::{EphemerisError, EphemerisErrorKind};
 use apsis_math::Vec3;

crates/orbit/apsis-ephemeris/src/error.rs

@@ -1,4 +1,6 @@
 //! Errors reported while building or querying an ephemeris.
+//!
+//! 构建或查询星历时报告的错误。
 
 use core::fmt;
 

crates/orbit/apsis-ephemeris/src/lib.rs

@@ -60,6 +60,28 @@
 //! let state = ephemeris.state_at(30.0).expect("the time is covered");
 //! assert!(state.position.norm() > 6_900.0);
 //! ```
+//!
+//! 星历采样与插值。
+//!
+//! 传播器给出卫星在任意瞬时的状态，但当结果只用于绘制轨迹或搜索穿越时，调用
+//! 它数百万次是浪费的。本 crate 在一组时刻网格上记录状态（称为样本），并用
+//! 插值回答其间的查询。
+//!
+//! 两半是有意独立的：
+//!
+//! - [`Ephemeris`] 是时刻与状态的表。它对状态来自何处一无所知，故由 SGP4
+//!   传播、由二体理论计算，或从文件读取的表都以相同方式工作。
+//! - [`Sampler`] 通过调用一个由时刻产生状态的函数来填充表。在本工作区中该
+//!   函数通常是 `apsis_sgp4::Satellite::propagate_at`，但采样器只需要一个
+//!   闭包，故测试可用解析函数。
+//!
+//! 插值是 Hermite 三次插值，它同时使用区间两端的位与速度。使用速度正是它
+//! 准确的原因：只过两个位置的三次式没有卫星移动多快的信息，而 Hermite 重构
+//! 匹配两端的斜率，故在相同采样间距下能好得多地复现光滑轨道。在圆轨道上误差
+//! 是步长的四阶量，故步长减半使误差约减为十六分之一。
+//!
+//! 时间以距调用方所选原点的秒数计，与 orbit 层其余部分一致。位置以千米计，
+//! 速度以千米每秒计。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/orbit/apsis-ephemeris/src/sampler.rs

@@ -1,4 +1,6 @@
 //! Filling an ephemeris by calling a state function on a grid.
+//!
+//! 通过在网格上调用状态函数来填充星历。
 
 use crate::ephemeris::{Ephemeris, Sample};
 use crate::error::{EphemerisError, EphemerisErrorKind};

crates/orbit/apsis-kepler/src/anomaly.rs

@@ -20,6 +20,22 @@
 //!
 //! All angles are in radians. The functions reduce their results into
 //! `[-pi, pi)` so that a value is comparable without further wrapping.
+//!
+//! 三种近点角之间的换算。
+//!
+//! 近点角是度量卫星绕其轨道走了多远的角。此处所用的三种形式是：
+//!
+//! - 真近点角，自近地点到卫星的角，从中心天体所在的焦点看。它是唯一具有
+//!   直接几何意义者。
+//! - 偏近点角，自近地点到卫星在椭圆辅助圆上的投影的角，从椭圆中心看。
+//! - 平近点角，时间的线性函数，与自近地点起扫过的面积成正比。它没有直接的
+//!   几何意义，但它是轨道随时间传播所采用的形式。
+//!
+//! 开普勒方程联系平近点角与偏近点角，且没有闭式解。此处用牛顿法求解，其
+//! 初值足够准确，对小于一的每个偏心率都能在几次迭代内收敛。
+//!
+//! 所有角度都以弧度计。各函数把结果归约到 `[-pi, pi)`，使值无需再作环绕即可
+//! 比较。
 
 use core::f64::consts::PI;
 

crates/orbit/apsis-kepler/src/elements.rs

@@ -1,4 +1,6 @@
 //! Keplerian elements and their conversion to a Cartesian state.
+//!
+//! 开普勒根数及其到直角坐标状态的换算。
 
 use crate::anomaly::{eccentric_from_mean, mean_from_eccentric, true_from_eccentric, wrap_to_pi};
 use crate::parameter::GravityParameter;

crates/orbit/apsis-kepler/src/lib.rs

@@ -33,6 +33,19 @@
 //! let state = elements.to_state(GravityParameter::WGS84).expect("valid elements");
 //! assert!((state.velocity.norm() - 7.909).abs() < 0.01);
 //! ```
+//!
+//! 开普勒轨道根数与二体传播。
+//!
+//! 开普勒根数集把轨道描述为空间中具有固定取向的椭圆、抛物线或双曲线。由
+//! 六个根数与引力参数，本 crate 在二体假定下计算任意时刻的位置与速度，并
+//! 作反方向换算。
+//!
+//! 二体模型只包含中心天体的质点引力。它略去地球扁率、阻力与第三体摄动，故
+//! 随时间偏离现实。对分析已知根数的轨道（例如求真近点角处的半径），它是恰当
+//! 的模型；对传播两行根数集，它是错误的模型，后者是 `apsis-sgp4` 的事。
+//!
+//! 角度以弧度计。长度以千米计，引力参数以立方千米每平方秒计，与 orbit 层
+//! 其余部分一致。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/orbit/apsis-kepler/src/parameter.rs

@@ -1,4 +1,6 @@
 //! The Earth gravitational parameter.
+//!
+//! 地球引力参数。
 
 /// The gravitational parameter of the central body, in cubic kilometers per
 /// second squared.

crates/orbit/apsis-maneuver/src/burn.rs

@@ -1,4 +1,6 @@
 //! The finite burn.
+//!
+//! 有限点火。
 
 use crate::error::{ManeuverError, ManeuverErrorKind};
 use apsis_kepler::{GravityParameter, KeplerianElements, State};

crates/orbit/apsis-maneuver/src/error.rs

@@ -1,4 +1,6 @@
 //! Errors reported while building or applying a maneuver.
+//!
+//! 构建或施加机动时报告的错误。
 
 use core::fmt;
 

crates/orbit/apsis-maneuver/src/hohmann.rs

@@ -1,4 +1,6 @@
 //! The two impulse Hohmann transfer between coplanar circular orbits.
+//!
+//! 共面圆轨道之间的双脉冲 Hohmann 转移。
 
 use crate::error::{ManeuverError, ManeuverErrorKind};
 use apsis_kepler::GravityParameter;

crates/orbit/apsis-maneuver/src/impulse.rs

@@ -1,4 +1,6 @@
 //! The impulsive maneuver.
+//!
+//! 脉冲机动。
 
 use crate::error::{ManeuverError, ManeuverErrorKind};
 use apsis_math::Vec3;

crates/orbit/apsis-maneuver/src/lib.rs

@@ -48,6 +48,32 @@
 //! assert!(transfer.first_burn > 0.0);
 //! assert!(transfer.total_delta_v() > 0.0);
 //! ```
+//!
+//! 脉冲式与有限式轨道机动模型。
+//!
+//! 机动通过施加推力改变轨道。此处的两个模型是谱系的两端。
+//!
+//! 脉冲机动 [`Impulse`] 瞬时施加速度变化，故位置不变、只有速度跃变。这是
+//! 化学推进点火所用的模型，其持续时间相对轨道周期很短，也是每本教科书
+//! delta-v 预算所写的模型。它在点火时间为零的极限下精确，也是两轨道之间
+//! 转移各闭式结果的来源。
+//!
+//! 有限机动 [`FiniteBurn`] 在一段时长上施加恒定加速度，故位置在点火期间
+//! 漂移，且当推力须对抗引力时，所达到的速度变化小于推力在自由空间中会给出
+//! 的。这是电推进器所用的模型，其点火可能持续轨道的很大一部分，也适用于
+//! 任何短时近似不够好的点火。
+//!
+//! 二者在极限下一致：加速度为 `a`、时长为 `t` 的有限点火给出冲量 `a t`，
+//! 故时长趋于零的 [`FiniteBurn`] 收敛到相应的 [`Impulse`]。测试检查该极限，
+//! 正是它把两个模型联系起来。
+//!
+//! 脉冲模型还提供两个共面圆轨道之间经典的双脉冲转移
+//! [`hohmann_transfer`]，它是每个低推力结果所比较的参照。它给出给定半径的
+//! 两个圆轨道之间转移的两次点火与总 delta-v，以及转移时间，即转移椭圆的
+//! 半个周期。
+//!
+//! 约定与 orbit 层其余部分一致：长度以千米计，速度以千米每秒计，角度以
+//! 弧度计。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/orbit/apsis-orbit/src/lib.rs

@@ -49,6 +49,29 @@
 //! let osculating = orbit.osculating_elements(60.0).expect("state exists");
 //! assert!(osculating.eccentricity < 0.01);
 //! ```
+//!
+//! 整合 orbit 层的轨道状态门面。
+//!
+//! 本 crate 是 orbit 层的单一入口。它重导出根数解析、解析传播器与二体模型，
+//! 并加入一个把它们联系起来的类型。
+//!
+//! [`Orbit`] 保存为传播准备好的卫星，连同其初始化所用的引力模型，并提供该层
+//! 所支持的两种轨道描述之间的换算：
+//!
+//! - 由 SGP4 传播的平根数，这是两行根数集所针对的模型，也是复现已编目卫星
+//!   已发布位置的唯一方式。
+//! - 瞬时开普勒根数，它描述某一瞬时的密切二体轨道，对检视与规划机动有用。
+//!
+//! 两种描述不可互换。用二体模型传播平根数，或用 SGP4 传播密切根数，会给出
+//! 不同且错误的答案；此处的换算明确说明它们朝哪个方向进行。
+//!
+//! 另有两项操作建立在传播之上并在此公开，因为它们需要同一引力参数以保持
+//! 一致：
+//!
+//! - [`Orbit::sample_ephemeris`] 在时间网格上记录轨迹，使其可经插值而非
+//!   传播查询，这正是覆盖或可见性搜索所需的。
+//! - [`Orbit::apply_burn`] 对密切状态施加有限机动并返回所得根数，这正是
+//!   机动规划所产生的。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/orbit/apsis-orbit/src/orbit.rs

@@ -1,4 +1,6 @@
 //! The combined orbit type.
+//!
+//! 合并后的轨道类型。
 
 use apsis_ephemeris::EphemerisError;
 use apsis_kepler::{GravityParameter, KeplerianElements};

crates/orbit/apsis-sgp4/src/batch.rs

@@ -8,6 +8,15 @@
 //!
 //! The parallel entry point produces the same values as the sequential one,
 //! in the same order. It differs only in how the work is distributed.
+//!
+//! 在许多瞬时上的批量传播，可选跨多个线程。
+//!
+//! 单颗卫星的轨迹是覆盖运行或可见性搜索的常见情形：调用方想要某一天每一
+//! 分钟、某一壳层每颗卫星的状态。每个状态与其他独立，故该循环是多核的
+//! 候选，且工作量大到启动线程本身就值回代价。
+//!
+//! 并行入口产生与顺序入口相同的值，次序也相同。它只在工作的分配方式上
+//! 不同。
 
 use crate::{Satellite, State};
 use apsis_math::parallel::map_index;

crates/orbit/apsis-sgp4/src/deep_space.rs

@@ -20,6 +20,23 @@
 //! and `znl`, the tesseral coefficients such as `q22`, and the resonance
 //! coefficients are quoted to the precision the reference uses, because
 //! reproducing its output requires the same rounding.
+//!
+//! 传播器的深空分支。
+//!
+//! 轨道周期为 225 分钟及以上的卫星用 SDP4 理论传播，它以日月摄动及与地球
+//! 引力场的共振扩展 SGP4。
+//!
+//! 各摄动分为三组。长期项随时间线性增长，累积在各速率字段中。长周期项随
+//! 太阳与月球的位置变化，由 [`dpper`] 施加。当轨道周期与地球自转成简单
+//! 整数比（每天一圈或两圈）时出现共振项，由于没有闭式，由 [`dspace`] 数值
+//! 积分。
+//!
+//! 各系数在初始化时计算一次，因为它们只依赖于历元根数与历元时间。
+//!
+//! 出处：每个表达式都遵循 Vallado 等，*Revisiting Spacetrack Report #3*，
+//! AIAA 2006-6753，2006，以及随该论文分发的参考实现。诸如 `zes` 与 `znl`
+//! 的摄动幅度、诸如 `q22` 的田谐系数，以及共振系数都取参考实现所用的精度，
+//! 因为复现其输出需要相同的舍入。
 
 use crate::satellite::{Satellite, TWO_PI};
 use core::f64::consts::PI;

crates/orbit/apsis-sgp4/src/error.rs

@@ -1,4 +1,6 @@
 //! Errors reported by the propagator.
+//!
+//! 传播器报告的错误。
 
 use core::fmt;
 

crates/orbit/apsis-sgp4/src/init.rs

@@ -13,6 +13,18 @@
 //!
 //! Source: the correction and the coefficient definitions follow Vallado et
 //! al., *Revisiting Spacetrack Report #3*, AIAA 2006-6753, 2006.
+//!
+//! 由两行根数集初始化传播器。
+//!
+//! 根数集给出以度、每天圈数计的平根数与一个阻力项。传播器以弧度、每分钟
+//! 弧度与地球半径工作，故初始化换算各输入并预计算只依赖于根数的每个系数。
+//!
+//! 量 `no_unkozai` 是去掉根数集所用 Kozai 平运动约定影响后的修正平运动。
+//! 该修正由二阶带谐项得出，并用不动点迭代求解，因为修正后的值出现在关系的
+//! 两侧。
+//!
+//! 出处：该修正与各系数定义遵循 Vallado 等，*Revisiting Spacetrack
+//! Report #3*，AIAA 2006-6753，2006。
 
 use crate::error::{PropagationError, PropagationErrorKind};
 use crate::model::GravityModel;

crates/orbit/apsis-sgp4/src/lib.rs

@@ -49,6 +49,28 @@
 //! assert!(state.position.norm() > 6_600.0);
 //! assert!(state.position.norm() < 7_200.0);
 //! ```
+//!
+//! SGP4 与 SDP4 解析轨道传播器。
+//!
+//! 该传播器接收两行根数集的平轨道根数，返回卫星在所请求瞬时的位置与速度。
+//! 它是各根数集所拟合的模型，故是使用它们的正确方式；给同一个根数集一个
+//! 通用数值积分器会偏离已发布的位置。
+//!
+//! 有两条分支，传播器按轨道周期在二者之间选择。周期低于 225 分钟的卫星用
+//! SGP4 传播，它建模地球扁率的长期效应与一个阻力项。周期不低于该值的卫星
+//! 用 SDP4 传播，它加入在该高度占主导的共振与日月摄动。
+//!
+//! 输入与输出：
+//!
+//! - 根数是来自 [`apsis_tle::TwoLineElement`] 的平根数。根数集中的角度以度
+//!   计，平运动以每天圈数计；本 crate 内部换算为弧度与每分钟弧度。
+//! - 输出表达在真赤道平春分点（TEME）坐标系中，位置以千米计、速度以千米
+//!   每秒计。TEME 是该模型所定义的坐标系；把它换算到地固系需要地球自转与
+//!   分点方程式，不属于本 crate。
+//! - 时间自根数集历元起以分钟计。
+//!
+//! 出处：该算法遵循 Vallado 等，*Revisiting Spacetrack Report #3*，
+//! AIAA 2006-6753，2006，以及随该论文分发的修订实现。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/orbit/apsis-sgp4/src/model.rs

@@ -20,6 +20,23 @@
 //!   Vallado et al., *Revisiting Spacetrack Report #3*, AIAA 2006-6753,
 //!   appendix. The values match the WGS 72 gravity field.
 //! - WGS 84 values: NIMA TR8350.2, third edition, 2000.
+//!
+//! 传播器所用的引力模型。
+//!
+//! 传播器需要描述地球的四个数：引力参数、赤道半径，以及二阶与三阶带谐项。
+//! SGP4 模型是 fitted 到 WGS 72 值的，而 Space-Track 分发的标准根数集意在
+//! 与它们一起使用，故 WGS 72 是缺省。
+//!
+//! 提供 WGS 84 是因为也有 fitted 到它的根数。把模型与 fitted 到另一模型的
+//! 根数集混用会使位置偏移数千米，故该选择应与根数的来源相匹配。
+//!
+//! 导出值 `xke`、`tumin` 与 `j3oj2` 由这四个定义数得出，在构造时计算一次。
+//!
+//! 出处：
+//!
+//! - WGS 72 值，即 Vallado 等，*Revisiting Spacetrack Report #3*，
+//!   AIAA 2006-6753 附录中 SGP4 参考实现所用者。各值与 WGS 72 引力场一致。
+//! - WGS 84 值：NIMA TR8350.2，第三版，2000。
 
 /// A gravity model: the Earth constants used by the propagator.
 ///

crates/orbit/apsis-sgp4/src/propagate.rs

@@ -14,6 +14,18 @@
 //! Source: the sequence follows Vallado et al., *Revisiting Spacetrack
 //! Report #3*, AIAA 2006-6753, 2006, and the reference implementation
 //! distributed with that paper.
+//!
+//! 近地传播步。
+//!
+//! 给定一条卫星记录与一个距历元的时间，本模块求 SGP4 理论的长期项与周期
+//! 项，并返回真赤道平春分点坐标系中的状态。
+//!
+//! 平根数随时间以多项式推进：平近点角、近地点幅角与赤经是线性的，赤经另有
+//! 一个二次项，而对高于简化阈值的轨道，半长轴、偏心率与平近点角还会获得
+//! 更多阻力项。随后用牛顿法解轨道求偏近点角，并施加短周期项。
+//!
+//! 出处：该序列遵循 Vallado 等，*Revisiting Spacetrack Report #3*，
+//! AIAA 2006-6753，2006，以及随该论文分发的参考实现。
 
 use crate::error::{PropagationError, PropagationErrorKind};
 use crate::satellite::{Method, Satellite, TWO_PI};

crates/orbit/apsis-sgp4/src/satellite.rs

@@ -1,4 +1,6 @@
 //! The satellite record and its initialisation from mean elements.
+//!
+//! 卫星记录及其由平根数的初始化。
 
 use crate::error::{PropagationError, PropagationErrorKind};
 use crate::init::{self, Elements};

crates/orbit/apsis-sgp4/src/state.rs

@@ -1,4 +1,6 @@
 //! The propagated state of a satellite.
+//!
+//! 卫星被传播后的状态。
 
 use apsis_math::Vec3;
 

crates/orbit/apsis-tle/src/checksum.rs

@@ -7,6 +7,13 @@
 //!
 //! The checksum digit itself is the last character of the line and is not
 //! part of the sum.
+//!
+//! 两行根数格式的行校验和。
+//!
+//! 每行以一个数字结尾，它是前面各列的校验和。该校验和是该行十进制数字之和
+//! 模十，其中负号贡献一，其余每个字符贡献零。
+//!
+//! 校验和数字本身是该行的最后一个字符，不属于该和。
 
 use crate::field::{ElementError, ElementErrorKind, Result};
 

crates/orbit/apsis-tle/src/element.rs

@@ -1,4 +1,6 @@
 //! Structured fields of a two-line element set.
+//!
+//! 两行根数集的结构化字段。
 
 use crate::checksum::verify_line_checksum;
 use crate::field::{ElementError, ElementErrorKind, Result};

crates/orbit/apsis-tle/src/field.rs

@@ -1,4 +1,6 @@
 //! The error type and result alias for element parsing.
+//!
+//! 根数解析的错误类型与结果别名。
 
 use core::fmt;
 

crates/orbit/apsis-tle/src/lib.rs

@@ -37,6 +37,27 @@
 //! assert_eq!(element.satellite_number, 25544);
 //! assert!((element.eccentricity - 0.0006703).abs() < 1e-12);
 //! ```
+//!
+//! 两行根数集的解析。
+//!
+//! 两行根数集（TLE）以北美防空司令部所用、由 Space-Track 分发的形式描述
+//! 卫星轨道。卫星名称携带在可选的第一行，其后两行携带轨道数据。
+//!
+//! 该格式是定宽的。每个字段占据固定的列范围，每行的校验和是其各位数字之和
+//! 模十，其中负号计为一。本 crate 把 TLE 解析为结构化字段，并校验各行校验和
+//! 与相匹配的根数集编号。它不解释各字段；平根数及其单位是 `apsis-sgp4` 的
+//! 事。
+//!
+//! 列位置以 1 为基，与该格式的文档一致。该格式有两条约定值得明确写出，因为
+//! 它们容易误读：
+//!
+//! - 指数字段写为一个带符号的单数字后接幅度。例如 ` 12345-3` 意为
+//!   `0.12345e-3`，而非 `12345e-3`。
+//! - 隐含小数点不写小数点。例如偏心率字段 `0006703` 意为 `0.0006703`。
+//!
+//! 出处：字段布局遵循 CelesTrak 发布的格式说明，*FAQs: Two-Line Element Set
+//! Format*，它记录了原 NORAD 规范所定义的各列。校验和规则即其中所述、
+//! Space-Track 所用者。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]