fmq/SpectraRust
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
59404207c3
SpectraRust/.learnings/LEARNINGS.md
Asfmq 59404207c3 重构4
2026-03-22 00:30:20 +08:00

10 KiB
Raw Blame History

Learnings

Corrections, insights, and knowledge gaps captured during development.

Categories: correction | insight | knowledge_gap | best_practice Areas: frontend | backend | infra | tests | docs | config Statuses: pending | in_progress | resolved | wont_fix | promoted | promoted_to_skill

Status Definitions

Status Meaning
pending Not yet addressed
in_progress Actively being worked on
resolved Issue fixed or knowledge integrated
wont_fix Decided not to address (reason in Resolution)
promoted Elevated to CLAUDE.md, AGENTS.md, or copilot-instructions.md
promoted_to_skill Extracted as a reusable skill

[LRN-20260321-F01] correction

Logged: 2026-03-21T19:55:00Z Priority: high Status: resolved Area: backend

Summary

Fortran 1-indexed 转 Rust 0-indexed 的关键规则

Details

  • 数组访问: arr(i) → arr[i-1]
  • 循环范围: DO I=1,N → for i in 0..n
  • 边界条件: Fortran jl=0 表示"在第一个有效索引之前"，Rust jl=0 就是第一个有效索引

Suggested Action

重构时删除类似 IF (J.EQ.0) J = J+1 的调整逻辑

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: ylintp.f, locate.f
  • Tags: indexing, fortran, rust

[LRN-20260321-F02] correction

Logged: 2026-03-21T19:55:00Z Priority: high Status: resolved Area: backend

Summary

Fortran 表达式 -LOG(X) 是 -(LOG(X))，不是 LOG(-X)

Details

XL=-LOG(X) 应翻译为 let xl = -x.ln()，不是 let xl = (-x).ln() 后者对 x>0 会返回 NaN

Suggested Action

翻译数学表达式时注意运算符优先级

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: erfcin.f
  • Tags: expression, fortran, rust

[LRN-20260321-F03] insight

Logged: 2026-03-21T19:55:00Z Priority: medium Status: resolved Area: backend

Summary

(z1 - z2).powi(2) 编译错误 - 类型推断失败

Details

编译器无法推断中间表达式的类型，使用显式乘法 (z1 - z2) * (z1 - z2) 代替

Metadata

  • Source: fortran-to-rust refactoring
  • Tags: rust, type_inference, powi

[LRN-20260321-F04] best_practice

Logged: 2026-03-21T19:55:00Z Priority: medium Status: resolved Area: tests

Summary

多项式近似精度容差：简单函数 1e-10，多项式 1e-7

Details

Abramowitz-Stegun 多项式近似本身精度有限

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: eint.f
  • Tags: precision, polynomial, testing

[LRN-20260321-F05] correction

Logged: 2026-03-21T19:55:00Z Priority: high Status: resolved Area: backend

Summary

递减循环变量用 isize 不用 usize，避免溢出

Details

当循环变量递减到负数时，无符号整数会溢出

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: collhe.f
  • Tags: overflow, rust, loop

[LRN-20260321-F06] best_practice

Logged: 2026-03-21T19:55:00Z Priority: high Status: resolved Area: backend

Summary

重构前必须检查所有 INCLUDE 语句，不仅是 IMPLIC.FOR

Details

已确认有 COMMON 依赖的"纯函数"文件： gamsp.f, sgmer1.f, sgmerd.f, cross.f, gfree0.f, gfreed.f, gfree1.f, wn.f, crossd.f, dopgam.f, verner.f, sbfhe1.f

Suggested Action

添加新结构体前先 grep 检查是否已存在

Metadata

  • Source: fortran-to-rust refactoring
  • Tags: common, fortran, dependency

[LRN-20260321-F07] correction

Logged: 2026-03-21T19:55:00Z Priority: high Status: resolved Area: tests

Summary

测试数组值不能全部相同，会导致除零

Details

// 错误：全部相同 → ddm = 0 → dtm = 1/0 = inf
let dm = vec![0.01; MDEPTH];

// 正确：递增模拟物理分布
let dm: Vec<f64> = (0..MDEPTH).map(|i| 0.01 + i as f64 * 0.01).collect();

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: rybmat.rs
  • Tags: testing, data_design

[LRN-20260321-F08] insight

Logged: 2026-03-21T19:55:00Z Priority: medium Status: resolved Area: backend

Summary

Fortran 修改 COMMON 块数组 → Rust 需要 &mut 引用

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: tabint.f
  • Tags: rust, mutability, reference

[LRN-20260321-F09] correction

Logged: 2026-03-21T19:55:00Z Priority: high Status: resolved Area: config

Summary

analyze_fortran.py 只匹配 CALL 语句，漏掉 FUNCTION 调用

Details

需要两遍扫描：1) 收集所有已定义函数名 2) 只匹配已知函数名

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: scripts/analyze_fortran.py
  • Tags: dependency, analysis, python

[LRN-20260321-F10] correction

Logged: 2026-03-21T19:55:00Z Priority: high Status: resolved Area: tests

Summary

测试参数设置时避免矩阵列重叠

Details

主循环更新列和温度/密度列可能重叠，设置 inre=0, inpc=0 避免重叠

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: bpopf.rs
  • Tags: testing, matrix, indexing

[LRN-20260321-F11] correction

Logged: 2026-03-21T19:55:00Z Priority: high Status: resolved Area: backend

Summary

公式中 1/x 和 x 的顺序要仔细核对

Details

5.484e-14 / x2 * (...) 其中 x2=1/x²，等于乘以 x²，不是除以

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: rayleig.f
  • Tags: formula, rust, physics

[LRN-20260321-F12] best_practice

Logged: 2026-03-21T19:55:00Z Priority: medium Status: resolved Area: backend

Summary

大型 COMMON 块函数使用生命周期结构体

Details

pub struct Alifr3ModelState<'a> {
    pub elec: &'a [f64],      // 输入
    pub heit: &'a mut [f64],  // 输出
}

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: alifr3.rs, alifr6.rs
  • Tags: rust, struct, lifetime

[LRN-20260321-F13] insight

Logged: 2026-03-21T19:55:00Z Priority: medium Status: resolved Area: backend

Summary

Fortran GOTO 分支 → Rust if-else + early return

Details

每个 GOTO 标签对应一个 if 块

Metadata

  • Source: fortran-to-rust refactoring
  • Tags: fortran, goto, control_flow

[LRN-20260321-F14] correction

Logged: 2026-03-21T19:55:00Z Priority: medium Status: resolved Area: backend

Summary

循环中重新赋值的变量必须声明为 mut

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: alifr6.rs
  • Tags: rust, mutability

[LRN-20260321-F15] correction

Logged: 2026-03-21T12:00:00Z Priority: high Status: resolved Area: backend

Summary

Fortran 3D 数组转 Rust 扁平数组时，必须知道所有维度才能正确计算索引

Details

Fortran absopac(jt,jr,jf) 是 3D 数组 (numtemp × numrh × nfreq)，转 Rust 扁平数组时：

  • 错误: 用 jt_idx * numtemp * nfreq (用了 numtemp 作为第二维度)
  • 正确: 用 jt_idx * max_numrh * nfreq (必须用实际维度 max_numrh)

类似地，2D 数组 rhomat(jt,jr) 转扁平时：

  • 错误: rhomat[jt_idx * numtemp]
  • 正确: rhomat[jt_idx * max_numrh]

Suggested Action

重构多维数组时，结构体必须包含所有维度信息，特别是可能变化的维度（如每个温度有不同的密度数）

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: opctab.rs, opctab.f
  • Tags: array, indexing, fortran, rust, multi-dimensional

[LRN-20260321-F16] correction

Logged: 2026-03-21T12:00:00Z Priority: high Status: resolved Area: backend

Summary

Fortran 条件 if(a.eq.b) 转 Rust 时不要误用其他变量

Details

Fortran if(numtemp.eq.nd) 检查表温度数是否等于总深度数：

  • 错误: if table.numtemp == params.id (用了当前深度索引)
  • 正确: if table.numtemp == table.nd (用总深度数)

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: opctab.rs, opctab.f
  • Tags: condition, variable, fortran, rust

[LRN-20260321-F17] correction

Logged: 2026-03-21T12:00:00Z Priority: high Status: resolved Area: backend

Summary

分支条件相同代码是 bug，必须对照 Fortran 完整实现

Details

if params.ibc == 0 { ... } else { ... } 两个分支代码完全相同时是错误的。

Fortran 原代码 ELSE 分支有额外项：

REIT(ID)=REIT(ID)+WW*(D0*(DSFT1-DBDT)+E0*DABT1(ID)+
     *                  RAD1(ID)*DABT1(ID)-DEMT1(ID)+
     *                  ALI1(ID)/ABST*DBDT)

变量 DBDT 和 E0 在边界条件块中计算，需要在更大作用域中声明才能在积分方程块中使用。

Suggested Action

重构时如果看到 if-else 分支代码相同，立即检查 Fortran 原代码

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: alifr1.rs, alifr1.f
  • Tags: branch, bug, fortran, rust

[LRN-20260321-F18] best_practice

Logged: 2026-03-21T12:00:00Z Priority: medium Status: resolved Area: docs

Summary

模块文档应完整描述所有功能，不仅是主要功能

Details

opctab.rs 原文档只提到"插值计算"，漏掉了：

  • Rayleigh 散射计算（简单公式或调用 rayleigh 函数）
  • 电子散射计算

Suggested Action

重构完成后对照 Fortran 原代码检查文档是否完整

Metadata

  • Source: fortran-to-rust refactoring
  • Related Files: opctab.rs, opctab.f
  • Tags: documentation, completeness

Quick Reference - Refactoring Checklist

重构新函数前检查：

  • 是否有 INCLUDE 语句 (除 IMPLIC.FOR 外)
  • 是否使用 COMMON 块
  • COMMON 块结构体是否已存在于其他模块
  • 是否有文件 I/O (OPEN, READ, WRITE)
  • 数组索引是否需要 -1 调整
  • 循环变量是否可能变负 (用 isize/i32)
  • 多项式近似精度是否需要放宽
  • 是否有嵌套 IF 分支遗漏
  • 矩阵列索引是否可能与温度/密度列重叠
  • 公式中 1/x 和 x 的顺序是否正确
  • 大型 COMMON 块函数是否需要创建综合输入结构体
  • 多分支 GOTO 是否正确转换为 if-else
  • 循环中重新赋值的变量是否声明为 mut
  • 多维数组扁平化时是否使用了正确的维度（不是第一个维度）
  • 条件语句中的变量是否与 Fortran 原代码一致
  • 模块文档是否描述了所有功能（包括次要功能）
  • if-else 分支代码是否完全相同（相同则是 bug）
  • 边界条件块中计算的变量是否在积分方程块中可用（作用域问题）