docs: bilingual comments for the link budget and antenna patterns

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

@@ -32,6 +32,26 @@ use core::f64::consts::PI;
 ///
 /// Returns `None` when the peak gain has no decibel form, or when the beam
 /// width or floor is not positive and finite.
+///
+/// 返回给定峰值增益与半功率波束宽度时，天线在偏离视轴某角度处的增益。
+///
+/// 这是若干干扰评估所用的角平方模型，以半功率波束宽度表达，使任何天线
+/// 都能由链路预算手头的两个数描述。以分贝计，
+///
+/// ```text
+/// G(theta) = G_peak - min(12 (theta / theta_0)^2, G_floor)
+/// ```
+///
+/// 其中 `theta_0` 是半功率波束宽度，`G_floor` 是所要降到的旁瓣电平，
+/// 相对峰值以分贝计。角平方律来自均匀照射孔径 Airy 图案的首项，直到
+/// 第一旁瓣都是良好近似。
+///
+/// 系数十二的选取使衰减在 `theta_0 / 2` 处达到三分贝，这正是半功率
+/// 波束宽度的定义。在建议书适用之处，应改用取自建议书的图案：ITU-R
+/// S.465 图案见 [`reference_pattern_gain`](crate::reference_pattern_gain)，
+/// 它在主瓣上以及旁瓣区的形状上都与本模型不同。
+///
+/// 峰值增益没有分贝形式，或波束宽度、底限非正且非有限时返回 `None`。
 pub fn off_axis_attenuation(
     peak: Gain,
     beam_width: f64,
@@ -82,6 +102,33 @@ pub fn off_axis_attenuation(
 ///
 /// Source: ITU, *Radio Regulations*, Appendix 8, which reproduces the
 /// reference pattern of ITU-R Recommendation S.465.
+///
+/// 返回天线在偏离视轴某角度处不得超出的增益，相对各向同性辐射体以分贝
+/// 计。
+///
+/// 这是《无线电规则》附录 8 的参考方向图，用于检查地球站是否满足保护
+/// 邻近卫星的偏轴发射限值。该方向图是分段的：
+///
+/// ```text
+/// for  D/lambda >= 100:
+///   G = 29 - 25 log10(theta)            for 1   <= theta < 36 degrees
+///   G = -10                             for 36  <= theta <= 180 degrees
+/// for  D/lambda <  100:
+///   G = 32 - 25 log10(theta)            for 1   <= theta < 48 degrees
+///   G = -10                             for 48  <= theta <= 180 degrees
+///   G = 32 - 25 log10(48)               for theta < 1 degree
+/// ```
+///
+/// 角度以弧度计，口径与波长之比决定适用哪一支，因为小天线主瓣更宽，
+/// 故须受控的角度范围也更大。
+///
+/// 本函数返回限值，即允许的最大增益。当实际偏轴增益不高于它时天线即
+/// 合规。
+///
+/// 角度为负、比值为非正，或角度非有限时返回 `None`。
+///
+/// 出处：ITU，*Radio Regulations*，附录 8，其中再现了 ITU-R 建议书
+/// S.465 的参考方向图。
 pub fn mask_gain(diameter_over_wavelength: f64, off_axis_angle: f64) -> Option<f64> {
     if !diameter_over_wavelength.is_finite() || diameter_over_wavelength <= 0.0 {
         return None;
@@ -93,6 +140,7 @@ pub fn mask_gain(diameter_over_wavelength: f64, off_axis_angle: f64) -> Option<f
     let large_aperture = diameter_over_wavelength >= 100.0;
     // The break point is where the pattern reaches its floor, and the cap
     // angle is where the falling branch begins.
+    // 折点是方向图到达其底限之处，封顶角是下降支开始之处。
     let (cap_angle, floor_angle) = if large_aperture {
         (1.0_f64.to_radians(), 36.0_f64.to_radians())
     } else {
@@ -103,6 +151,7 @@ pub fn mask_gain(diameter_over_wavelength: f64, off_axis_angle: f64) -> Option<f
     if off_axis_angle < cap_angle {
         // Inside the first degree the pattern is taken at its value at one
         // degree, which is the most restrictive point on the falling branch.
+        // 在一度以内，方向图取其一度的值，这是下降支上限制最严的点。
         Some(head - 25.0 * cap_angle.to_degrees().log10())
     } else if off_axis_angle <= floor_angle {
         Some(head - 25.0 * off_axis_angle.to_degrees().log10())
@@ -116,21 +165,42 @@ pub fn mask_gain(diameter_over_wavelength: f64, off_axis_angle: f64) -> Option<f
 /// A pattern is either described by its geometry, in which case the peak
 /// gain and beam width are derived from the aperture, or given directly as
 /// measured or published values. The enum lets a link budget accept either.
+///
+/// 天线方向图的形状。
+///
+/// 方向图或由其几何描述（此时峰值增益与波束宽度由孔径导出），或作为
+/// 实测或已发表的值直接给出。该枚举使链路预算能接受二者。
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum Pattern {
     /// A parabolic aperture, described by its diameter and efficiency.
+    ///
+    /// 抛物面孔径，由其直径与效率描述。
     Parabolic {
         /// The reflector diameter, in meters.
+        ///
+        /// 反射面直径，单位为米。
         diameter: f64,
         /// The aperture efficiency, dimensionless.
+        ///
+        /// 孔径效率，无量纲。
         efficiency: f64,
     },
     /// An antenna described directly by its peak gain and half power beam
     /// width.
+    ///
+    /// 直接由其峰值增益与半功率波束宽度描述的天线。
     Direct {
         /// The peak gain on boresight.
+        ///
+        /// 视轴上的峰值增益。
+        ///
+        /// 视轴上的峰值增益。
         peak: Gain,
         /// The half power beam width, in radians.
+        ///
+        /// 半功率波束宽度，单位为弧度。
+        ///
+        /// 半功率波束宽度，单位为弧度。
         beam_width: f64,
     },
 }
@@ -140,6 +210,10 @@ impl Pattern {
     ///
     /// The wavelength is ignored for a directly specified pattern, which
     /// already carries its peak gain.
+    ///
+    /// 返回本方向图在给定波长处的峰值增益。
+    ///
+    /// 对直接指定的方向图，波长被忽略，因为它已带有其峰值增益。
     pub fn peak_gain(self, wavelength: f64) -> Option<Gain> {
         match self {
             Self::Parabolic {
@@ -156,6 +230,8 @@ impl Pattern {
 
     /// Returns the half power beam width of this pattern at the given
     /// wavelength, in radians.
+    ///
+    /// 返回本方向图在给定波长处的半功率波束宽度，单位为弧度。
     pub fn beam_width(self, wavelength: f64) -> Option<f64> {
         match self {
             Self::Parabolic {
@@ -177,6 +253,11 @@ impl Pattern {
 ///
 /// This is the form a link budget needs: the two numbers that describe the
 /// beam, plus the model that gives the gain at any angle from boresight.
+///
+/// 由峰值增益与半功率波束宽度构造的增益方向图。
+///
+/// 这是链路预算所需的形式：描述波束的两个数，加上给出偏离视轴任意角度
+/// 处增益的模型。
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct ElementPattern {
     /// The peak gain on boresight.
@@ -184,12 +265,16 @@ pub struct ElementPattern {
     /// The half power beam width, in radians.
     pub beam_width: f64,
     /// The sidelobe floor, in decibels below the peak.
+    ///
+    /// 旁瓣底限，相对峰值以分贝计。
     pub floor_db: f64,
 }
 
 impl Default for ElementPattern {
     /// Returns a pattern for an isotropic antenna, with a floor that makes
     /// the attenuation zero in every direction.
+    ///
+    /// 返回各向同性天线的方向图，其底限使各方向的衰减为零。
     fn default() -> Self {
         Self {
             peak: Gain::ISOTROPIC,
@@ -205,6 +290,11 @@ impl ElementPattern {
     /// The sidelobe floor is set to the value of the Radio Regulations
     /// reference pattern, 32 decibels below the peak, which is a common
     /// worst case for a small Earth station.
+    ///
+    /// 由峰值增益与半功率波束宽度创建方向图。
+    ///
+    /// 旁瓣底限被设为《无线电规则》参考方向图的值，即相对峰值低
+    /// 32 分贝，这是小型地球站常见的坏情形。
     pub const fn new(peak: Gain, beam_width: f64) -> Self {
         Self {
             peak,
@@ -216,6 +306,10 @@ impl ElementPattern {
     /// Creates a pattern from a parabolic aperture at a wavelength.
     ///
     /// Returns `None` when the aperture or wavelength is not usable.
+    ///
+    /// 由某波长处的抛物面孔径创建方向图。
+    ///
+    /// 孔径或波长不可用时返回 `None`。
     pub fn from_parabolic(aperture: ParabolicAperture, wavelength: f64) -> Option<Self> {
         Some(Self {
             peak: aperture.peak_gain(wavelength)?,
@@ -225,6 +319,8 @@ impl ElementPattern {
     }
 
     /// Returns this pattern with a different sidelobe floor.
+    ///
+    /// 返回本方向图的一个具有不同旁瓣底限的副本。
     pub const fn with_floor(mut self, floor_db: f64) -> Self {
         self.floor_db = floor_db;
         self
@@ -234,6 +330,10 @@ impl ElementPattern {
     ///
     /// Returns `None` when the pattern is not usable or the angle is not
     /// finite.
+    ///
+    /// 返回偏离视轴某角度处的增益。
+    ///
+    /// 方向图不可用或角度非有限时返回 `None`。
     pub fn gain_at(self, off_axis_angle: f64) -> Option<Gain> {
         let attenuation =
             off_axis_attenuation(self.peak, self.beam_width, off_axis_angle, self.floor_db)?;
@@ -242,6 +342,8 @@ impl ElementPattern {
 
     /// Returns `true` when the beam width and floor describe a usable
     /// pattern.
+    ///
+    /// 当波束宽度与底限描述一个可用方向图时返回 `true`。
     pub fn is_valid(self) -> bool {
         self.peak.dbi().is_some()
             && self.beam_width.is_finite()

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

@@ -6,11 +6,17 @@ use apsis_rf::{Decibel, Gain, Power, free_space_path_loss, wavelength};
 
 /// The geometric part of a link: how far apart the terminals are and at what
 /// frequency they operate.
+///
+/// 链路的几何部分：两端相距多远，以及在什么频率上工作。
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct LinkGeometry {
     /// The distance between the terminals, in meters.
+    ///
+    /// 两端之间的距离，单位为米。
     pub distance: f64,
     /// The carrier frequency, in hertz.
+    ///
+    /// 载波频率，单位为赫兹。
     pub frequency: f64,
 }
 
@@ -18,11 +24,17 @@ impl LinkGeometry {
     /// Returns the free space path loss for this geometry.
     ///
     /// Returns `None` when the distance or frequency is not usable.
+    ///
+    /// 返回该几何的自由空间路径损耗。
+    ///
+    /// 距离或频率不可用时返回 `None`。
     pub fn path_loss(self) -> Option<Decibel> {
         free_space_path_loss(self.distance, self.frequency)
     }
 
     /// Returns `true` when the geometry is usable.
+    ///
+    /// 当该几何可用时返回 `true`。
     pub fn is_valid(self) -> bool {
         self.distance.is_finite()
             && self.distance > 0.0
@@ -36,25 +48,46 @@ impl LinkGeometry {
 /// The losses are given as positive decibel values that are subtracted,
 /// which is the convention in link budgets: a three decibel loss is entered
 /// as three decibels, not as minus three.
+///
+/// 无线电链路一个方向的完整链路预算。
+///
+/// 各损耗以被减去的正分贝值给出，这是链路预算中的约定：三分贝的损耗记
+/// 为三，而非负三。
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct LinkBudget {
     /// The power delivered to the transmit antenna, in watts.
+    ///
+    /// 送到发射天线的功率，单位为瓦特。
     pub transmit_power: Power,
     /// The transmit antenna gain on the relevant path.
+    ///
+    /// 相关路径上的发射天线增益。
     pub transmit_gain: Gain,
     /// Every loss between the transmitter and the transmit antenna, as a
     /// positive decibel value.
+    ///
+    /// 发射机与发射天线之间的每一项损耗，为正分贝值。
     pub transmit_loss: Decibel,
     /// The receive antenna gain on the relevant path.
+    ///
+    /// 相关路径上的接收天线增益。
     pub receive_gain: Gain,
     /// Every loss between the receive antenna and the receiver input, as a
     /// positive decibel value.
+    ///
+    /// 接收天线与接收机输入之间的每一项损耗，为正分贝值。
     pub receive_loss: Decibel,
     /// The system noise temperature referred to the receiver input.
+    ///
+    /// 折算到接收机输入端的系统噪声温度。
     pub system_temperature: NoiseTemperature,
     /// The receiver noise bandwidth, in hertz.
+    ///
+    /// 接收机噪声带宽，单位为赫兹。
     pub bandwidth: f64,
     /// The distance and frequency of the link.
+    ///
+    /// 链路的距离与频率。
     pub geometry: LinkGeometry,
 }
 
@@ -102,6 +135,13 @@ impl LinkBudget {
     /// rather than of the receiver.
     ///
     /// Returns `None` when the system temperature is not usable.
+    ///
+    /// 返回接收机输入端的噪声功率密度，单位为瓦特每赫兹。
+    ///
+    /// 这是 `k T`，即把噪声温度换算为单位带宽的功率。它不依赖于接收机
+    /// 带宽，这正是载噪密度比成为链路属性而非接收机属性的原因。
+    ///
+    /// 系统温度不可用时返回 `None`。
     pub fn noise_density(&self) -> Option<f64> {
         if !self.system_temperature.is_valid() {
             return None;
@@ -127,6 +167,7 @@ impl LinkBudget {
         }
         // The ratio is a power ratio, and the numerator and denominator
         // carry different bandwidths, so the ratio is formed directly.
+        // 该比值是功率比，且分子与分母带有不同的带宽，故直接构成该比。
         let ratio = carrier.watts() / density;
         Decibel::from_ratio(ratio)
     }
@@ -156,6 +197,13 @@ impl LinkBudget {
     ///
     /// Returns `None` when the data rate is not positive, or when the
     /// carrier to noise density ratio is not usable.
+    ///
+    /// 返回某数据速率下每比特能量与噪声密度之比。
+    ///
+    /// 它是载噪密度比减去数据速率，因为每比特能量是载波功率除以比特
+    /// 速率。
+    ///
+    /// 数据速率非正，或载噪密度比不可用时返回 `None`。
     pub fn energy_per_bit_over_noise(&self, data_rate: f64) -> Option<Decibel> {
         if !data_rate.is_finite() || data_rate <= 0.0 {
             return None;
@@ -172,6 +220,13 @@ impl LinkBudget {
     /// Earth, the Sun, or a rain cell in the beam.
     ///
     /// Returns `None` when the added temperature is not usable.
+    ///
+    /// 返回接收天线看到给定温度的噪声源所引起的系统噪声上升。
+    ///
+    /// 天线噪声按功率加到系统温度上，在温度上即求和。这是用于计入波束中
+    /// 的地球、太阳或雨胞的形式。
+    ///
+    /// 所加温度不可用时返回 `None`。
     pub fn with_added_noise(&self, added: NoiseTemperature) -> Option<Self> {
         if !added.is_valid() {
             return None;
@@ -185,11 +240,17 @@ impl LinkBudget {
     /// Returns the wavelength of the carrier, in meters.
     ///
     /// Returns `None` when the frequency is not usable.
+    ///
+    /// 返回载波的波长，单位为米。
+    ///
+    /// 频率不可用时返回 `None`。
     pub fn carrier_wavelength(&self) -> Option<f64> {
         wavelength(self.geometry.frequency)
     }
 
     /// Returns `true` when every input describes a usable link.
+    ///
+    /// 当每个输入都描述一条可用链路时返回 `true`。
     pub fn is_valid(&self) -> bool {
         self.transmit_power.is_valid()
             && self.transmit_gain.dbi().is_some()
@@ -204,11 +265,17 @@ impl LinkBudget {
 }
 
 /// The result of comparing a link against a requirement.
+///
+/// 把链路与某项要求比较所得的结果。
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct LinkMargin {
     /// The ratio the link achieves, in decibels.
+    ///
+    /// 该链路所达到的比，单位为分贝。
     pub achieved: Decibel,
     /// The ratio the link requires, in decibels.
+    ///
+    /// 该链路所要求的比，单位为分贝。
     pub required: Decibel,
 }
 
@@ -217,11 +284,17 @@ impl LinkMargin {
     ///
     /// A positive margin means the link closes with room to spare; a
     /// negative margin means it does not.
+    ///
+    /// 返回余量，单位为分贝。
+    ///
+    /// 正余量意味着链路闭合并有余，负余量意味着不能闭合。
     pub fn margin(self) -> Decibel {
         self.achieved - self.required
     }
 
     /// Returns `true` when the margin is not negative.
+    ///
+    /// 当余量非负时返回 `true`。
     pub fn closes(self) -> bool {
         self.margin().db() >= 0.0
     }
@@ -230,6 +303,10 @@ impl LinkMargin {
 /// Returns the margin between an achieved ratio and a required one.
 ///
 /// This is the comparison that decides whether a link closes.
+///
+/// 返回所达到的比与所要求的比之间的余量。
+///
+/// 这一比较决定链路是否闭合。
 pub fn link_margin(achieved: Decibel, required: Decibel) -> LinkMargin {
     LinkMargin { achieved, required }
 }
@@ -240,6 +317,12 @@ pub fn link_margin(achieved: Decibel, required: Decibel) -> LinkMargin {
 /// [`LinkBudget::carrier_to_noise_density`].
 ///
 /// Returns `None` when the budget is not usable.
+///
+/// 返回某预算的载噪密度比。
+///
+/// 这是 [`LinkBudget::carrier_to_noise_density`] 的自由函数形式。
+///
+/// 预算不可用时返回 `None`。
 pub fn carrier_to_noise_density(budget: &LinkBudget) -> Option<Decibel> {
     budget.carrier_to_noise_density()
 }
@@ -256,6 +339,16 @@ pub fn carrier_to_noise_density(budget: &LinkBudget) -> Option<Decibel> {
 /// the logarithm of the temperature, which is the form usually quoted.
 ///
 /// Returns `None` when the gain or temperature is not usable.
+///
+/// 返回接收链路的增益与系统温度之比，单位为每开尔文。
+///
+/// 该品质因数写作 `G / T`，是比较接收站的标准方式。它把接收天线增益与
+/// 系统噪声温度结合起来，故天线更大、接收机更安静的站得分更高。
+///
+/// 以分贝表示时，`G / T` 是接收增益（以 dBi 计）减去温度的十倍对数，
+/// 这是通常引用的形式。
+///
+/// 增益或温度不可用时返回 `None`。
 pub fn gain_to_temperature(gain: Gain, temperature: NoiseTemperature) -> Option<f64> {
     if !temperature.is_valid() || temperature.kelvin() <= 0.0 {
         return None;