研究笔记 · Research Note

数值模式源代码修改

Zhenyu He · Jobs Stroustrup 阅读约 4 分钟

数值模式源代码修改 (Numerical Model Source Code Modification)

熟练度

熟练 (source-code 修改实践) → 向精通过渡 (最小侵入式设计方法论)

跨 2 个 major project (PKU Walker + UC Berkeley Nuclear Winter) 完成 20+ NCAR CAM3 .F90 mods + DAM LES tracer/surface extension + Lin et al. 1983 6-class microphysics (microphysics module) 系统化整理 — 本科生 + 博士生阶段 3 个 domain 的 source-level 修改实例。

描述

1. NCAR CAM3 大气模式源代码修改 (PKU Walker 项目, 本科 2020-2021)

项目规模: 20 个 .F90 source mods, 共 143 KB (SourceMods.zip), 分布在 radiation / cloud / microphysics / transport / ocean 5 大模块

关键 mods (6 个核心):

somoce: Slab ocean mixed-layer depth MLDANN from 50m → 30m (Q-flux 实验设计的 key dependency)
cloud_fraction: Low-cloud 诊断输出 + Walker feedback 诊断
cldinti, cldsav: 云初始化 + 保存逻辑 patch
hb_diff: Horizontal diffusion coefficient 调整
physpkg, stratiform: 物理参数化 package 级 forcing logic

全 20 mods 清单: cldinti / cldsav / cloud_fraction / comctl / ghg_defaults / hb_diff / history / hycoef / ice_constants / inidat / initext / ocn_srf / physpkg / radiation / radlw / runtime_opts / somoce / stratiform / tphysbc

技术特点:

CAM3 v3.1 namelist + 参数化修改为主 (conservative approach, 保持 NCAR 原 code 结构)
20 mods 跨 5 个 code modules — 需要理解整个 radiation/cloud/microphysics/transport/ocean 调用栈
Fortran 77/90 混合, 理解 legacy code convention 必需
本科生 source-code 级 GCM 修改: 在 PKU / NSCC-GZ Tianhe-II (undergraduate Tianhe-II account) account 下编译 + SLURM 48-PE 运行

2. DAM LES 模式源代码扩展 (UC Berkeley Nuclear Winter Phase 3/4, 博士 2023-2024)

项目范围: tracer module + surface forcing module 的新 diagnostic 与 physics extension

具体修改:

tracer_mod.f90: 加 qv_source (soot 加热引发的水汽源项)
surface_mod.f90: 空间变化热通量图 forcing (Aoyama 2011 Fig 3 CV digitization + Rusen affine transformation → spatially varying boundary condition)
Q_latent 诊断输出: tracer-induced latent heat release diagnostic variable
I/O 节奏优化: snapshot cadence 从 1h → adaptive (focusing soot lofting phase)

技术特点:

DAM 是 Fortran 90 modern module-based architecture (比 CAM3 改进)
Tracer 被 5+ modules consume, 修改需 propagate through call graph
8 production runs × ~46k core-hours each ≈ 44 days HPC wall time (Lawrencium cluster, LBNL)

3. `(microphysics module)` 蚂蚁啃骨头方法论 (UC Berkeley Nuclear Winter Phase 4.5, 2024-2025)

代码规模: ~3000 行 Fortran, Lin et al. 1983 6-class microphysics scheme

挑战: 陌生 codebase + 无充分 documentation + must preserve all conserved properties + cross-module coupling (与 tracer_mod + surface_mod + I/O 耦合)

Zhenyu 的 3-stage 方法论:

Stage 1 — 表格摊开 (structured documentation): 11 个 section table 逐行整理 equations + descriptions + variable meanings: Initialization / Terminal velocities / Warm-temperature / Cold-temperature / Conservation / SAT subroutine / Function definitions / BERGRN / IDW / SETUPM / Key constants. Output: 11-table reference document, future 读者不需重读原代码。

Stage 2 — 找 minimal insertion point:

新功能 (aerosol scavenging) 的 dependencies 分析: 需 PREVP (已计算 precipitation rate), 需访问 both TC >= 0 和 TC < 0 分支的 source-sink block
唯一最小位置: PREVP 计算之后、300 IF(TC .LT. 0.0) 分支之前
定位准则: (1) 所有 dependency 已 available (2) 还未进入 mutually-exclusive 分支 (3) 输出在两分支都能被 consume

Stage 3 — COMMON block 跨模块通信:

不改 USE statement (too invasive)
不加参数 (caller stack 太深)
用 COMMON block (最小侵入): COMMON /SCAVENG/ LAMBDA_SCAV_OUT — 1 行声明 + 2 行赋值 in (microphysics module) + ~5 行 consume in tracer_mod.f90

4-step 新物理扩展 (aerosol scavenging):

$Λ_{sc a v} = Λ_{B r} + Λ_{T h} + Λ_{D F} + Λ_{G r}$

Brownian: $4 π \overset{ˉ}{R} D_{B r} N_{C}$ , Stokes-Einstein diffusivity
Thermophoresis: $π \overset{ˉ}{R}^{2} V_{T h} N_{C}$ , thermal gradient
Diffusiophoresis: $4 π \overset{ˉ}{R} V_{D I F U} ρ ∣ D QS ∣ N_{C}$
Gravitational: $π \overset{ˉ}{R}^{2} ∣ V_{T R} - V_{T S, soo t} ∣ E_{im p} N_{C}$ (impaction efficiency)

Total modification < 20 lines for entire cross-module new physics.

🌟 跨项目 signature discipline

项目	规模	方法论	signature
Walker CAM3 (本科)	20 mods, 143 KB	Namelist + parameter tuning	Minimal perturbation preserving NCAR structure
DAM Phase 3-4 (博士)	tracer + surface + I/O	Module-aware insertion points	Diagnostic + physics parallel expansion
(microphysics module) Phase 4.5 (博士)	3k lines, 11-section table	Table-first understanding → COMMON block minimal invasive	< 20 lines new physics for cross-module aerosol scavenging

共同 discipline: “understand first, then modify” — 反对 “加 1 行看 1 个 bug” 的 trial-and-error spiral。

工具链

语言: Fortran 77/90 (legacy + modern syntax)
编译: make + namelist 参数化 + gfortran/ifort
模型: NCAR CAM3 v3.1 source tree (615 .F90 files) + DAM LES source (40+ modules)
版本控制: git + source-level diff 追踪
调试: Fortran runtime error 诊断 + print statement tracing + gdb (sparingly)
HPC: Tianhe-II SLURM ((undergraduate Tianhe-II account) Walker) + Lawrencium (DAM LES)

在哪些经历中用到

PKU-Walker-Circulation-Research — CAM3 20 .F90 mods + Tianhe-II 48-PE SLURM (2020-2021)
— DAM Phase 3/4/4.5 tracer + surface + (microphysics module) (2023-2025)
— (microphysics module) 蚂蚁啃骨头 3-stage 方法论 flagship instance
可迁移到: GEOS-Chem / CESM / WRF / GFDL AM4 / 任何 module-based GCM/LES 扩展

方法论 patterns (内嵌于本 skill page, 不建独立 concept page)

蚂蚁啃骨头 cross-project methodology (3-stage 读码纪律, 详见本页 Domain 3 (microphysics module) 实例)
< 20 lines new physics design discipline (minimal-invasive code extension pattern)