447 lines
10 KiB
Markdown
447 lines
10 KiB
Markdown
# 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
|
||
```rust
|
||
// 错误：全部相同 → 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
|
||
```rust
|
||
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 分支有额外项：
|
||
```fortran
|
||
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）
|
||
- [ ] 边界条件块中计算的变量是否在积分方程块中可用（作用域问题）
|