Research Note

Numerical Model Source Code Modification

Zhenyu He · Jobs Stroustrup 5 min read

Proficiency

Proficient (source-code modification practice) → transitioning toward expert (minimal-invasive design methodology)

Across 2 major projects (PKU Walker + UC Berkeley Nuclear Winter): completed 20+ NCAR CAM3 .F90 mods + DAM LES tracer/surface extension + systematic organization of Lin et al. 1983 6-class microphysics (microphysics module) — source-level modification instances across 3 domains spanning undergraduate + PhD stages.

Description

1. NCAR CAM3 GCM Source Code Modifications (PKU Walker Project, undergraduate 2020-2021)

Project scale: 20 .F90 source mods, totaling 143 KB (SourceMods.zip), distributed across radiation / cloud / microphysics / transport / ocean — 5 major modules

Key mods (6 core):

somoce: Slab ocean mixed-layer depth MLDANN from 50m → 30m (key dependency of the Q-flux experiment design)
cloud_fraction: Low-cloud diagnostic output + Walker feedback diagnostic
cldinti, cldsav: Cloud initialization + save logic patch
hb_diff: Horizontal diffusion coefficient adjustment
physpkg, stratiform: Physics-parameterization package-level forcing logic

Full 20-mod list: 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

Technical features:

Mostly CAM3 v3.1 namelist + parameterization mods (conservative approach, preserving NCAR’s original code structure)
20 mods spanning 5 code modules — required understanding of the entire radiation/cloud/microphysics/transport/ocean call stack
Fortran 77/90 mixed; understanding legacy code conventions is essential
Source-code-level GCM modifications by an undergraduate: compiled + ran with SLURM 48-PE under PKU / NSCC-GZ Tianhe-II (undergraduate Tianhe-II account) account

2. DAM LES Source Code Extension (UC Berkeley Nuclear Winter Phase 3/4, PhD 2023-2024)

Project scope: new diagnostics and physics extensions to the tracer module + surface-forcing module

Specific modifications:

tracer_mod.f90: added qv_source (water-vapor source term induced by soot heating)
surface_mod.f90: spatially varying heat-flux map forcing (Aoyama 2011 Fig 3 CV digitization + Rusen affine transformation → spatially varying boundary condition)
Q_latent diagnostic output: tracer-induced latent-heat-release diagnostic variable
I/O cadence optimization: snapshot cadence from 1h → adaptive (focusing on the soot-lofting phase)

Technical features:

DAM uses Fortran 90 modern module-based architecture (an improvement over CAM3)
Tracer is consumed by 5+ modules; modifications must propagate through the call graph
8 production runs × ~46k core-hours each ≈ 44 days HPC wall time (Lawrencium cluster, LBNL)

3. `(microphysics module)` “Ants Nibbling a Bone” Methodology (UC Berkeley Nuclear Winter Phase 4.5, 2024-2025)

Code scale: ~3000 lines of Fortran, Lin et al. 1983 6-class microphysics scheme

Challenges: unfamiliar codebase + insufficient documentation + must preserve all conserved properties + cross-module coupling (with tracer_mod + surface_mod + I/O)

Zhenyu’s 3-stage methodology (蚂蚁啃骨头, idiom gloss: “ants nibbling a bone”):

Stage 1 — Tabular layout (structured documentation): Line-by-line organization of equations + descriptions + variable meanings into 11 section tables: Initialization / Terminal velocities / Warm-temperature / Cold-temperature / Conservation / SAT subroutine / Function definitions / BERGRN / IDW / SETUPM / Key constants. Output: 11-table reference document; future readers do not need to re-read the original code.

Stage 2 — Find minimal insertion point:

Dependency analysis for the new feature (aerosol scavenging): needs PREVP (precipitation rate already computed); needs access to source-sink blocks in both the TC >= 0 and TC < 0 branches
Unique minimal location: after PREVP computation, before the 300 IF(TC .LT. 0.0) branch
Localization criteria: (1) all dependencies already available (2) before entering mutually-exclusive branches (3) output can be consumed in both branches

Stage 3 — COMMON-block cross-module communication:

Don’t change USE statements (too invasive)
Don’t add parameters (caller stack too deep)
Use COMMON block (minimal-invasive): COMMON /SCAVENG/ LAMBDA_SCAV_OUT — 1-line declaration + 2-line assignment in (microphysics module) + ~5 lines consume in tracer_mod.f90

4-step new-physics extension (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.

Cross-Project Signature Discipline

Project	Scale	Methodology	Signature
Walker CAM3 (undergrad)	20 mods, 143 KB	Namelist + parameter tuning	Minimal perturbation preserving NCAR structure
DAM Phase 3-4 (PhD)	tracer + surface + I/O	Module-aware insertion points	Diagnostic + physics parallel expansion
(microphysics module) Phase 4.5 (PhD)	3k lines, 11-section table	Table-first understanding → COMMON block minimal invasive	< 20 lines new physics for cross-module aerosol scavenging

Common discipline: “understand first, then modify” — opposed to “add 1 line, watch 1 bug” trial-and-error spirals.

Toolchain

Languages: Fortran 77/90 (legacy + modern syntax)
Compilation: make + namelist parameterization + gfortran/ifort
Models: NCAR CAM3 v3.1 source tree (615 .F90 files) + DAM LES source (40+ modules)
Version control: git + source-level diff tracking
Debugging: Fortran runtime-error diagnosis + print-statement tracing + gdb (sparingly)
HPC: Tianhe-II SLURM ((undergraduate Tianhe-II account) Walker) + Lawrencium (DAM LES)

Used In

Walker Circulation Dynamics @ PKU — 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) “ants nibbling a bone” 3-stage methodology flagship instance
Transferable to: GEOS-Chem / CESM / WRF / GFDL AM4 / any module-based GCM/LES extension

Methodology patterns (embedded in this skill page, not separate concept pages)

“Ants nibbling a bone” cross-project methodology (3-stage code-reading discipline; see Domain 3 (microphysics module) instance on this page)
< 20 lines new-physics design discipline (minimal-invasive code extension pattern)