docs: bilingual module docs for the rf layer

crates/rf/apsis-antenna/src/lib.rs

@@ -44,6 +44,33 @@
 //! assert!(peak.dbi().expect("positive") > 45.0);
 //! assert!(peak.dbi().expect("positive") < 50.0);
 //! ```
+//!
+//! 天线辐射方向图与增益模型。
+//!
+//! 天线并非向各个方向均匀辐射。本 crate 为几乎每条卫星链路都会出现的两种
+//! 形状建模增益随角度的变化：抛物面反射体，其波束是窄笔形；以及具有宽方向图
+//! 的理想化单元。
+//!
+//! 实践中有三种波束宽度约定，它们不可互换：
+//!
+//! - 半功率波束宽度是增益降到峰值一半（即低三分贝）的两个方向之间的角。
+//! - 零点到零点波束宽度是主瓣两侧头两个零点之间的角。对均匀照射孔径，它约
+//!   为半功率宽度的两倍。
+//! - 第一旁瓣电平是主瓣之外的峰值增益。对均匀照射的圆孔径，它约为负
+//!   17.6 dB。
+//!
+//! 此处的每个函数都以弧度接收或返回角度，以 [`apsis_rf::Gain`] 接收或返回
+//! 增益，故结果可直接送入链路预算。
+//!
+//! 出处：
+//!
+//! - 抛物面孔径增益：`G = eta (pi D / lambda)^2`，其中 `eta` 是孔径效率，
+//!   对调准良好的天线通常在 0.55 与 0.70 之间。
+//! - 圆孔径的半功率波束宽度：`theta = k lambda / D`，均匀照射时 `k` 约为
+//!   1.02，典型照射锥削时接近 1.2。
+//! - 简单地球站天线的同极化参考方向图，其随偏轴角的平方下降到旁瓣底限。
+//!   这是 ITU-R 建议书 S.465 为限定从一个卫星系统到另一个的干扰所用的
+//!   形式。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/rf/apsis-antenna/src/parabolic.rs

@@ -1,4 +1,6 @@
 //! The parabolic aperture model.
+//!
+//! 抛物面孔径模型。
 
 use apsis_rf::Gain;
 use core::f64::consts::PI;

crates/rf/apsis-antenna/src/pattern.rs

@@ -1,4 +1,6 @@
 //! Off-axis gain patterns.
+//!
+//! 偏轴增益方向图。
 
 use crate::parabolic::ParabolicAperture;
 use apsis_rf::{Decibel, Gain};

crates/rf/apsis-antenna/src/reference.rs

@@ -19,6 +19,23 @@
 //! Source: ITU-R Recommendation S.465-6, *Reference earth-station radiation
 //! pattern for use in coordination and interference assessment in the
 //! frequency range from 2 to about 30 GHz*.
+//!
+//! ITU-R S.465 参考天线方向图。
+//!
+//! 建议书 S.465 为地球站天线定义了一个参考方向图，用于评估卫星网络之间的
+//! 干扰。该方向图有三个区：随偏轴角平方下降的主瓣、随角度对数下降的旁瓣
+//! 区，以及一个底限。
+//!
+//! 该方向图仅由天线口径与波长之比选择。该建议书为 `D / lambda` 至少为 100
+//! 的天线给出一个方向图，为更小的天线给出另一个，后者主瓣更宽，故其旁瓣区
+//! 开始得更晚。
+//!
+//! 主瓣表达式正是本方向图与《无线电规则》附录 8 通用参考方向图相区别之处，
+//! 后者只建模旁瓣区并把主瓣宽度作为输入。二者共享旁瓣区的形状。
+//!
+//! 出处：ITU-R 建议书 S.465-6，*Reference earth-station radiation pattern
+//! for use in coordination and interference assessment in the frequency range
+//! from 2 to about 30 GHz*。
 
 use apsis_rf::Decibel;
 use core::f64::consts::PI;

crates/rf/apsis-atmosphere/src/gaseous.rs

@@ -1,5 +1,7 @@
 //! Specific attenuation of atmospheric gases.
 //!
+//! 大气气体的比衰减。
+//!
 //! The attenuation caused by oxygen and water vapour is computed by the
 //! line-by-line summation of ITU-R Recommendation P.676. Each absorption
 //! line contributes a resonance whose strength depends on the temperature

crates/rf/apsis-atmosphere/src/gaseous_path.rs

@@ -1,5 +1,7 @@
 //! Slant path attenuation through the atmosphere.
 //!
+//! 穿过大气的斜路径衰减。
+//!
 //! The attenuation along a slant path is not simply the specific attenuation
 //! divided by the sine of the elevation, because the atmosphere thins with
 //! height and the path is curved. ITU-R Recommendation P.676 reduces the

crates/rf/apsis-atmosphere/src/geometry.rs

@@ -1,4 +1,6 @@
 //! The geometry of a slant path through the atmosphere.
+//!
+//! 穿过大气的斜路径的几何。
 
 use core::f64::consts::PI;
 

crates/rf/apsis-atmosphere/src/lib.rs

@@ -43,6 +43,31 @@
 //! let low = slant_path_attenuation(12.0, 0.2, Atmosphere::REFERENCE).expect("valid");
 //! assert!(low > zenith);
 //! ```
+//!
+//! 大气衰减与折射模型。
+//!
+//! 穿过大气的卫星信号被两种机制削弱，它们被分开处理，因为其行为随频率、
+//! 仰角与天气而异。
+//!
+//! 气体吸收来自氧与水汽的吸收谱线。氧在 50 与 70 GHz 之间有一组密集谱线，
+//! 并在 118.75 GHz 处有一条孤立线；水汽在 22.235 GHz 处有一条强线，在
+//! 183.31 GHz 处有一条强得多的线。衰减即对上述各线的逐线求和，这使它在
+//! 约 10 GHz 以下可忽略，而在各吸收带中很严重。
+//!
+//! 降雨衰减由降水中的散射与吸收造成。它在约 4 GHz 以下可忽略，随降雨率的
+//! 幂次增大，并强烈依赖仰角与极化。
+//!
+//! 二者都经相同的路径几何依赖仰角：低仰角的信号穿过更多大气。
+//!
+//! 出处：
+//!
+//! - 气体比衰减与等效高度：ITU-R 建议书 P.676-12，*Attenuation by
+//!   atmospheric gases*。
+//! - 降雨比衰减系数：ITU-R 建议书 P.838-3，*Specific attenuation model for
+//!   rain for use in prediction methods*。
+//! - 降雨路径与仰角依赖：ITU-R 建议书 P.618-13，*Propagation data and
+//!   prediction methods required for the design of Earth-space
+//!   telecommunication systems*。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/rf/apsis-atmosphere/src/p835.rs

@@ -1,5 +1,7 @@
 //! The reference standard atmosphere of ITU-R Recommendation P.835.
 //!
+//! ITU-R 建议书 P.835 的参考标准大气。
+//!
 //! The exact slant path method of Recommendation P.676 integrates the
 //! specific attenuation through a stack of layers, so it needs the
 //! temperature, pressure, and water vapour density at each layer height.

crates/rf/apsis-atmosphere/src/p839.rs

@@ -1,5 +1,7 @@
 //! The rain height model of ITU-R Recommendation P.839.
 //!
+//! ITU-R 建议书 P.839 的雨顶高度模型。
+//!
 //! The height of the rain layer is taken as the height of the zero degree
 //! isotherm above sea level. The recommendation tabulates that height on a
 //! global grid, and the value at a given location is found by bilinear

crates/rf/apsis-atmosphere/src/rain.rs

@@ -1,5 +1,7 @@
 //! Rain attenuation.
 //!
+//! 降雨衰减。
+//!
 //! The specific attenuation of rain is modelled as a power law in the rain
 //! rate, `gamma = k R^alpha`, where `k` and `alpha` depend on the frequency,
 //! on the polarisation, and on the elevation. The coefficients are given by

crates/rf/apsis-doppler/src/lib.rs

@@ -31,6 +31,18 @@
 //! let shift = DopplerShift::from_range_rate(12.0e9, 1_000.0).expect("valid");
 //! assert!(shift.shifted_frequency() < 12.0e9);
 //! ```
+//!
+//! 多普勒频移计算。
+//!
+//! 卫星与地面站相对运动，故到达接收机的频率不同于离开发射机的频率。本 crate
+//! 由相对速度计算该频移。
+//!
+//! 存在两种效应，它们是分开的。经典频移与距离变化率除以光速成正比，它是
+//! 多普勒跟踪器所补偿的。两个时钟之间的相对论时间膨胀是二阶改正，对轨道
+//! 速度而言小得多，它被分开提供，使调用方在应用需要时可以计入它。
+//!
+//! 此处所用的符号约定是：正的距离变化率（即两终端正在远离）产生负频移，
+//! 因而接收频率更低。这与日常观察——远离的声源听起来更低——一致。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/rf/apsis-doppler/src/shift.rs

@@ -1,4 +1,6 @@
 //! The Doppler shift and the range rate that causes it.
+//!
+//! 多普勒频移以及造成它的距离变化率。
 
 use apsis_core::constant::SPEED_OF_LIGHT;
 use apsis_math::Vec3;

crates/rf/apsis-interference/src/lib.rs

@@ -42,6 +42,26 @@
 //! let combined = combine(ratio, Decibel::from_db(15.0)).expect("valid");
 //! assert!(combined.db() < ratio.db());
 //! ```
+//!
+//! 干扰与载干比计算。
+//!
+//! 有用信号很少独自到达。本 crate 把有用载波与一个或多个干扰载波以及噪声
+//! 合并，并报告决定该有用链路是否可用的各比值。
+//!
+//! 此处计算的数字是：
+//!
+//! - 载干比，对一个或若干干扰源。
+//! - 载波与噪声加干扰之比，这是接收机实际所见，因为它无法把二者分开。
+//! - 某干扰源的等效噪声温度，它使干扰贡献可以像噪声一样折算进链路预算。
+//!
+//! 来自共享同一频率的第二颗卫星的干扰，由自地面站看两颗卫星之间的角描述。
+//! 接收天线在该方向上有旁瓣响应，而干扰源功率与有用功率之比由两个增益与
+//! 两个路径损耗得出。本 crate 把两个增益作为输入，故它与 `apsis-antenna`
+//! 中的方向图模型可组合。
+//!
+//! 出处：载干比与载波噪声加干扰比的定义，以及把干扰表达为等效噪声温度的
+//! 做法，都是卫星链路设计中的标准内容，例如见于 ITU-R Handbook on Satellite
+//! Communications。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/rf/apsis-interference/src/ratio.rs

@@ -1,4 +1,6 @@
 //! Carrier to interference ratios and their combination with noise.
+//!
+//! 载干比及其与噪声的合成。
 
 use apsis_core::constant::BOLTZMANN;
 use apsis_rf::{Decibel, Power};

crates/rf/apsis-link/src/budget.rs

@@ -1,4 +1,6 @@
 //! The link budget and the figures derived from it.
+//!
+//! 链路预算以及由它导出的各数字。
 
 use apsis_core::constant::BOLTZMANN;
 use apsis_noise::NoiseTemperature;

crates/rf/apsis-link/src/lib.rs

@@ -51,6 +51,26 @@
 //! assert!(ratio.db() > 70.0);
 //! assert!(ratio.db() < 80.0);
 //! ```
+//!
+//! 链路预算计算。
+//!
+//! 链路预算把发射机与接收机之间的每项增益与损耗相加，并把所得载波功率与同
+//! 它竞争的噪声比较。本 crate 计算该和以及由它导出的各数字：载噪比、每比特
+//! 能量与噪声密度之比，以及链路余量。
+//!
+//! 运算次序要紧，故该链被明确写出：
+//!
+//! 1. 发射机功率减去发射损耗、加上发射天线增益，给出等效全向辐射功率。
+//! 2. 它除以自由空间路径损耗、加上接收天线增益，给出接收机输入端的载波
+//!    功率。
+//! 3. 系统噪声温度乘以玻尔兹曼常量，换算为噪声密度。
+//! 4. 载噪密度比是载波功率除以该密度，载噪比则进一步除以接收机带宽。
+//!
+//! 出处：
+//!
+//! - 此形式的链路方程是卫星通信实践中通篇所用的，例如见 ITU-R Handbook on
+//!   Satellite Communications。
+//! - 玻尔兹曼常量与光速来自 SI 定义，由 `apsis-rf` 重导出。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/rf/apsis-noise/src/cascade.rs

@@ -1,4 +1,6 @@
 //! Noise in a cascade of stages, by the Friis formula.
+//!
+//! 按 Friis 公式计算的级联各级噪声。
 
 use crate::temperature::{NoiseTemperature, REFERENCE_TEMPERATURE_K};
 use apsis_rf::Gain;

crates/rf/apsis-noise/src/lib.rs

@@ -30,6 +30,24 @@
 //! let power = thermal_noise_power(temperature, 36.0e6).expect("valid arguments");
 //! assert!((power.dbw().expect("positive") + 128.0).abs() < 1.0);
 //! ```
+//!
+//! 噪声温度与噪声系数模型。
+//!
+//! 噪声从三处进入接收机：源、天线及其馈源，以及接收机自身。它们通过相加噪声
+//! 温度而非功率来合并，因为温度是经玻尔兹曼关系折算到固定带宽的功率，而不同
+//! 增益各级的级联并不能简单地把功率相加。
+//!
+//! 核心关系是：
+//!
+//! - 某带宽内的热噪声功率 `P = k T B`，其中 `k` 是玻尔兹曼常量。
+//! - 噪声系数作为温度 `T = T_0 (F - 1)`，其中 `T_0` 是 290 K 的参考温度。
+//! - Friis 级联，它按本级之前的增益对每级的噪声加权。
+//!
+//! 出处：
+//!
+//! - 290 K 的参考温度与噪声系数定义来自 IEEE 噪声系数标准定义，IEEE Std
+//!   161。
+//! - 级联即噪声的 Friis 公式，见任何接收机设计教材。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/rf/apsis-noise/src/temperature.rs

@@ -1,4 +1,6 @@
 //! Noise temperature.
+//!
+//! 噪声温度。
 
 use apsis_core::constant::BOLTZMANN;
 use apsis_rf::Power;

crates/rf/apsis-rf/src/decibel.rs

@@ -1,4 +1,6 @@
 //! The decibel scale.
+//!
+//! 分贝尺度。
 
 use core::fmt;
 

crates/rf/apsis-rf/src/free_space.rs

@@ -1,4 +1,6 @@
 //! Free space propagation.
+//!
+//! 自由空间传播。
 
 use crate::decibel::Decibel;
 use crate::gain::Gain;

crates/rf/apsis-rf/src/gain.rs

@@ -1,4 +1,6 @@
 //! Antenna gain.
+//!
+//! 天线增益。
 
 use crate::decibel::Decibel;
 use core::f64::consts::PI;

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

@@ -31,6 +31,23 @@
 //! let lambda = wavelength(299_792_458.0).expect("the frequency is positive");
 //! assert!((lambda - 1.0).abs() < 1e-12);
 //! ```
+//!
+//! 核心射频原语。
+//!
+//! 本 crate 保存射频层其余部分据以书写的各量：功率、增益，以及二者通常所
+//! 用的分贝尺度，连同每次链路计算所起的两条关系——某频率的波长与自由空间
+//! 路径损耗。
+//!
+//! 全程使用 SI 单位。功率以瓦特计，频率以赫兹计，距离以米计，温度以开尔文
+//! 计。分贝值是功率比，按该比的十进对数的十倍计算。
+//!
+//! 有两条约定值得写出，因为它们容易混淆：
+//!
+//! - 分贝是两个功率之比。以 `dBi` 表示的增益是相对各向同性辐射体的比值，
+//!   以 `dBd` 表示的则是相对半波振子的比值，后者比各向同性辐射体更具方向性
+//!   2.15 dB。[`Gain`] 携带该比值以及两种具名形式。
+//! - 自由空间路径损耗既随频率也随距离增大，因为固定增益天线的有效孔径与其
+//!   所张立体角都随波长变短而缩小。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/rf/apsis-rf/src/power.rs

@@ -1,4 +1,6 @@
 //! Radio frequency power.
+//!
+//! 射频功率。
 
 use crate::decibel::Decibel;
 use core::fmt;