From 800a1b02f875991c1dbe8dfd8d9cd5afc49c3520 Mon Sep 17 00:00:00 2001 From: ApsisRS contributors Date: Fri, 2 Oct 2026 01:48:55 +0800 Subject: [PATCH] docs: bilingual module docs for the rf layer --- crates/rf/apsis-antenna/src/lib.rs | 27 +++++++++++++++++++ crates/rf/apsis-antenna/src/parabolic.rs | 2 ++ crates/rf/apsis-antenna/src/pattern.rs | 2 ++ crates/rf/apsis-antenna/src/reference.rs | 17 ++++++++++++ crates/rf/apsis-atmosphere/src/gaseous.rs | 2 ++ .../rf/apsis-atmosphere/src/gaseous_path.rs | 2 ++ crates/rf/apsis-atmosphere/src/geometry.rs | 2 ++ crates/rf/apsis-atmosphere/src/lib.rs | 25 +++++++++++++++++ crates/rf/apsis-atmosphere/src/p835.rs | 2 ++ crates/rf/apsis-atmosphere/src/p839.rs | 2 ++ crates/rf/apsis-atmosphere/src/rain.rs | 2 ++ crates/rf/apsis-doppler/src/lib.rs | 12 +++++++++ crates/rf/apsis-doppler/src/shift.rs | 2 ++ crates/rf/apsis-interference/src/lib.rs | 20 ++++++++++++++ crates/rf/apsis-interference/src/ratio.rs | 2 ++ crates/rf/apsis-link/src/budget.rs | 2 ++ crates/rf/apsis-link/src/lib.rs | 20 ++++++++++++++ crates/rf/apsis-noise/src/cascade.rs | 2 ++ crates/rf/apsis-noise/src/lib.rs | 18 +++++++++++++ crates/rf/apsis-noise/src/temperature.rs | 2 ++ crates/rf/apsis-rf/src/decibel.rs | 2 ++ crates/rf/apsis-rf/src/free_space.rs | 2 ++ crates/rf/apsis-rf/src/gain.rs | 2 ++ crates/rf/apsis-rf/src/lib.rs | 17 ++++++++++++ crates/rf/apsis-rf/src/power.rs | 2 ++ 25 files changed, 190 insertions(+) diff --git a/crates/rf/apsis-antenna/src/lib.rs b/crates/rf/apsis-antenna/src/lib.rs index 8a4f307..385dbbe 100644 --- a/crates/rf/apsis-antenna/src/lib.rs +++ b/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)] diff --git a/crates/rf/apsis-antenna/src/parabolic.rs b/crates/rf/apsis-antenna/src/parabolic.rs index 768e6a6..738b6cb 100644 --- a/crates/rf/apsis-antenna/src/parabolic.rs +++ b/crates/rf/apsis-antenna/src/parabolic.rs @@ -1,4 +1,6 @@ //! The parabolic aperture model. +//! +//! 抛物面孔径模型。 use apsis_rf::Gain; use core::f64::consts::PI; diff --git a/crates/rf/apsis-antenna/src/pattern.rs b/crates/rf/apsis-antenna/src/pattern.rs index a332aa0..1b4cf8f 100644 --- a/crates/rf/apsis-antenna/src/pattern.rs +++ b/crates/rf/apsis-antenna/src/pattern.rs @@ -1,4 +1,6 @@ //! Off-axis gain patterns. +//! +//! 偏轴增益方向图。 use crate::parabolic::ParabolicAperture; use apsis_rf::{Decibel, Gain}; diff --git a/crates/rf/apsis-antenna/src/reference.rs b/crates/rf/apsis-antenna/src/reference.rs index dd6aea8..882fea1 100644 --- a/crates/rf/apsis-antenna/src/reference.rs +++ b/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; diff --git a/crates/rf/apsis-atmosphere/src/gaseous.rs b/crates/rf/apsis-atmosphere/src/gaseous.rs index 0cdafe6..06d4c9a 100644 --- a/crates/rf/apsis-atmosphere/src/gaseous.rs +++ b/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 diff --git a/crates/rf/apsis-atmosphere/src/gaseous_path.rs b/crates/rf/apsis-atmosphere/src/gaseous_path.rs index 0bc676f..ec1595f 100644 --- a/crates/rf/apsis-atmosphere/src/gaseous_path.rs +++ b/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 diff --git a/crates/rf/apsis-atmosphere/src/geometry.rs b/crates/rf/apsis-atmosphere/src/geometry.rs index 4aa3149..6b42d43 100644 --- a/crates/rf/apsis-atmosphere/src/geometry.rs +++ b/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; diff --git a/crates/rf/apsis-atmosphere/src/lib.rs b/crates/rf/apsis-atmosphere/src/lib.rs index 3dd59c0..a5addb8 100644 --- a/crates/rf/apsis-atmosphere/src/lib.rs +++ b/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)] diff --git a/crates/rf/apsis-atmosphere/src/p835.rs b/crates/rf/apsis-atmosphere/src/p835.rs index fa9a2d5..f3ca001 100644 --- a/crates/rf/apsis-atmosphere/src/p835.rs +++ b/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. diff --git a/crates/rf/apsis-atmosphere/src/p839.rs b/crates/rf/apsis-atmosphere/src/p839.rs index 1ce2b20..b472c8f 100644 --- a/crates/rf/apsis-atmosphere/src/p839.rs +++ b/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 diff --git a/crates/rf/apsis-atmosphere/src/rain.rs b/crates/rf/apsis-atmosphere/src/rain.rs index 920ada0..e5a7ca7 100644 --- a/crates/rf/apsis-atmosphere/src/rain.rs +++ b/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 diff --git a/crates/rf/apsis-doppler/src/lib.rs b/crates/rf/apsis-doppler/src/lib.rs index 0f6eb63..2ccbffa 100644 --- a/crates/rf/apsis-doppler/src/lib.rs +++ b/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)] diff --git a/crates/rf/apsis-doppler/src/shift.rs b/crates/rf/apsis-doppler/src/shift.rs index a670e8a..41444af 100644 --- a/crates/rf/apsis-doppler/src/shift.rs +++ b/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; diff --git a/crates/rf/apsis-interference/src/lib.rs b/crates/rf/apsis-interference/src/lib.rs index 62eff4a..7bfad41 100644 --- a/crates/rf/apsis-interference/src/lib.rs +++ b/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)] diff --git a/crates/rf/apsis-interference/src/ratio.rs b/crates/rf/apsis-interference/src/ratio.rs index a951daa..8d9c408 100644 --- a/crates/rf/apsis-interference/src/ratio.rs +++ b/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}; diff --git a/crates/rf/apsis-link/src/budget.rs b/crates/rf/apsis-link/src/budget.rs index 72a4573..5e5eb79 100644 --- a/crates/rf/apsis-link/src/budget.rs +++ b/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; diff --git a/crates/rf/apsis-link/src/lib.rs b/crates/rf/apsis-link/src/lib.rs index 062b2df..2e88908 100644 --- a/crates/rf/apsis-link/src/lib.rs +++ b/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)] diff --git a/crates/rf/apsis-noise/src/cascade.rs b/crates/rf/apsis-noise/src/cascade.rs index 7625498..4c27f24 100644 --- a/crates/rf/apsis-noise/src/cascade.rs +++ b/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; diff --git a/crates/rf/apsis-noise/src/lib.rs b/crates/rf/apsis-noise/src/lib.rs index 1722704..d593ae8 100644 --- a/crates/rf/apsis-noise/src/lib.rs +++ b/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)] diff --git a/crates/rf/apsis-noise/src/temperature.rs b/crates/rf/apsis-noise/src/temperature.rs index 2f78daf..73ff7ca 100644 --- a/crates/rf/apsis-noise/src/temperature.rs +++ b/crates/rf/apsis-noise/src/temperature.rs @@ -1,4 +1,6 @@ //! Noise temperature. +//! +//! 噪声温度。 use apsis_core::constant::BOLTZMANN; use apsis_rf::Power; diff --git a/crates/rf/apsis-rf/src/decibel.rs b/crates/rf/apsis-rf/src/decibel.rs index 3d3cc29..0e822d8 100644 --- a/crates/rf/apsis-rf/src/decibel.rs +++ b/crates/rf/apsis-rf/src/decibel.rs @@ -1,4 +1,6 @@ //! The decibel scale. +//! +//! 分贝尺度。 use core::fmt; diff --git a/crates/rf/apsis-rf/src/free_space.rs b/crates/rf/apsis-rf/src/free_space.rs index 424ceeb..32be3aa 100644 --- a/crates/rf/apsis-rf/src/free_space.rs +++ b/crates/rf/apsis-rf/src/free_space.rs @@ -1,4 +1,6 @@ //! Free space propagation. +//! +//! 自由空间传播。 use crate::decibel::Decibel; use crate::gain::Gain; diff --git a/crates/rf/apsis-rf/src/gain.rs b/crates/rf/apsis-rf/src/gain.rs index 2f95361..e8a3e5d 100644 --- a/crates/rf/apsis-rf/src/gain.rs +++ b/crates/rf/apsis-rf/src/gain.rs @@ -1,4 +1,6 @@ //! Antenna gain. +//! +//! 天线增益。 use crate::decibel::Decibel; use core::f64::consts::PI; diff --git a/crates/rf/apsis-rf/src/lib.rs b/crates/rf/apsis-rf/src/lib.rs index 098f8a1..b5a80db 100644 --- a/crates/rf/apsis-rf/src/lib.rs +++ b/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)] diff --git a/crates/rf/apsis-rf/src/power.rs b/crates/rf/apsis-rf/src/power.rs index 6ea7dca..eb196d3 100644 --- a/crates/rf/apsis-rf/src/power.rs +++ b/crates/rf/apsis-rf/src/power.rs @@ -1,4 +1,6 @@ //! Radio frequency power. +//! +//! 射频功率。 use crate::decibel::Decibel; use core::fmt;