LMDZ COMMON / MARS 5.3 到 6.3 版本差异

全量入口： 5.3→6.3 全量变更矩阵逐项登记 419 个变化路径，并链接到 21 个逻辑主题详情页；来源与方法记录哈希、官方 Changelog 边界与证据等级。

页面定位与比较边界

本页比较两组由使用者指定的源码快照：一组作为 5.3 基线，另一组作为 6.3 当前版。每组都同时包含 LMDZ.COMMON 与 LMDZ.MARS。这里的“5.3”“6.3”是这两组目录的使用者版本标识；快照内没有可独立核验的统一 release tag，因此本页不把比较结果外推到所有同名发行包。

比较在 2026-07-12 完成，分两层：

对源码树建立“相对路径 + SHA-256”清单，统计新增、删除、同路径修改和字节不变文件。
对关键差异继续核验模块、调用点、配置读取和输出路径；只有经过源码调用链核验的内容才写成行为变化。

清单排除了任一路径段为 .git、build、bin、obj、__pycache__ 的文件，也排除了 .DS_Store 以及常见编译产物（.o、.obj、.mod、.a、.so、.dll、.exe、.pyc、.pdb）。重命名在机械统计中表现为“一项删除 + 一项新增”，后文会单独指出已核验的重命名或迁移。

一页结论

从 5.3 到 6.3，COMMON 仍以动力核心和公共运行时为主，文件总量变化不大；主要变化集中在动力—物理接口、并行边界、tracer 文件基础设施、FCM 构建和机器配置。MARS 的变化更广：物理配置从 include 状态转向模块化，tracer 初始化改为物理侧解析，write_output 统一桥接 diagfi 与 XIOS，1D 驱动重构，水云、尘埃、热层和质量守恒路径均有实质更新。

因此，5.3 运行目录不能只替换可执行文件后直接用于 6.3。至少要成组迁移构建选项、callphys.def、tracer 定义、XIOS XML、初始/重启文件与诊断变量名，并重新做一次短积分守恒检查。

量化总览

源码树	5.3 文件数	6.3 文件数	6.3 新增	6.3 删除	同路径修改	字节不变
COMMON	472	483	33	22	57	393
MARS	324	362	93	55	159	110

COMMON 的新增文件主要落在 arch（23）、ioipsl（6）和 libf（4）；同路径修改主要落在 libf（35）。MARS 的新增文件主要落在 libf（59）与 deftank（22），同路径修改则以 libf（125）为主。文件计数说明 MARS 的升级不是局部补丁，但不能单独证明物理行为变化；行为结论以以下源码证据为准。

COMMON：公共动力与构建层

1. tracer 基础设施进入公共层

6.3 COMMON 新增：

libf/misc/readTracFiles_mod.f90
libf/misc/strings_mod.f90
libf/misc/program_options.F90
libf/misc/job.F90

MARS 6.3 的 libf/phymars/parse_tracer_file.F90 直接使用 strings_mod 和 readTracFiles_mod::{tracers,readTracersFiles}，并在 master rank 解析后广播。因此这不只是文件存在性变化，而是 MARS 新式 tracer.def 解析链的 COMMON 依赖。

边界需要说清：5.3 COMMON 的 dyn3d_common/infotrac.F90 已能识别旧式和 #ModernTrac-v1 格式。本次升级的关键不是“6.3 才首次支持现代 tracer”，而是 MARS 物理侧开始通过新的公共解析设施自行取得 tracer 信息，减少动力侧向物理侧传递 tracer 元数据的耦合。

2. 动力—物理接口与 1D 并行特例

libf/dynphy_lonlat/inigeomphy_mod.F90 调用 mod_interface_dyn_phys::init_interface_dyn_phys。6.3 的接口对 klon_mpi == 1 增加物理列索引重置，这是源码注释明确标出的 1D parallel 特例。

同一接口链上的 calfis.F、calfis_p.F 和 inigeomphy_mod.F90 都发生修改：

calfis.F 继续通过 call_physiq(...) 进入 MARS 物理。
calfis_p.F 把 Venus 移出原先与 Titan 共用的 AllGather 分支；新分支只对 planet_type == 'titan' 执行。
calfis_p.F 在网格转换前由 OMP master 清零 zphi/zphis，用于避免 debug 条件下对未定义值的操作。
inigeomphy_mod.F90 新增 aire_glo/airefi_for_outputs，用 gr_dyn_fi 保存适合输出的极点面积，并调用 geometry_mod::init_geometry_cell_area_for_outputs。这使计算几何面积与经纬网诊断输出面积有了显式边界。

现有 COMMON 依赖入口和接口图见 COMMON dependency boundary。

3. 并行运行时修复

6.3 修改了 libf/dyn3dpar/parallel_lmdz.F90 以及 libf/phy_common/mod_phys_lmdz_mpi.F90、mod_phys_lmdz_omp.F90、mod_phys_lmdz_para.F90、mod_phys_lmdz_transfert_para.F90。

其中 parallel_lmdz.F90 新增 omp_chunk 收缩循环。源码注释说明：某些 llm/omp_size 组合会让空闲线程未发出 send/recv 就进入 MPI_Waitall，从而触发 request error；6.3 通过缩小 chunk 避免这种组合，并在 chunk 过小时告警。升级后的 MPI × OpenMP 结果应至少覆盖一种非整除垂直层分配，而不能只测纯 MPI。

4. 构建系统与机器配置

COMMON 根目录的旧 makegcm 被删除；build_gcm、makelmdz_fcm 和 bld.cfg 有修改，并新增多组 ADASTRA、BAO_YGG、MESOIPSL、MESU 的 arch.path/.env/.fcm 配置。

makelmdz_fcm 的 6.3 行为包括：

-io 接受 ioipsl、mix、xios。
mix 与 xios 定义 CPP_XIOS；纯 xios 还定义 CPP_IOIPSL_NO_OUTPUT。
1D + XIOS 组合强制使用 MPI。
bld.cfg 对 XIOS 模块采用专门的依赖扫描排除规则。

这意味着旧 makegcm 命令行和新 FCM 构建不能视为同一接口的简单别名。迁移时要保存完整编译命令、-io 模式、MPI/OpenMP 组合和所用 arch 三件套。

5. 目录职责调整

5.3 COMMON 的 libf/evolution/ 在 6.3 快照中整体删除，其中包括 pem.F90 与 compute_tendencies_mod*.F90 等 15 个文件。另一个已核验的迁移是旧 COMMON libf/dyn3d/nogcm.F90、leapfrog_nogcm.F 被删除，而 MARS 6.3 在 libf/dynphy_lonlat/phymars/ 下提供同名驱动；新 nogcm.F90 仍调用 COMMON infotrac_init，随后调用 MARS iniphysiq。这是无完整 GCM 驱动的职责下沉到行星包，不应把它误写成算法凭空新增。

MARS：物理、配置与输出层

1. 配置状态模块化

5.3 的 libf/phymars/callkeys.h 被 6.3 的 callkeys_mod.F90 取代。配置主链为：

iniphysiq
  -> conf_phys(klon_omp, nlayer, nqtot)
       -> getin_p 读取 callphys.def
       -> callkeys_mod 保存跨物理过程开关
  -> physiq 按开关调度各过程

conf_phys.F 从 callkeys_mod 导入状态并读取配置；physiq_mod.F 再导入这些开关。已核验的新路径包括：

callatke 的读取及与 callyamada4 的互斥检查；
dust_coagulation 的读取与参数检查；
call_mass_fixer_dyn 的读取；
physiq 初始化 ATKE、调用 dust_coagulation_main 和 tracer_mass_fixer_dyn。

1D 也调用同一个 conf_phys(1,llm,nq)，所以 3D 与 1D 的配置语义更一致，但旧 1D 配置文件中的已弃用键也会更直接地触发新校验。配置模块详见 callkeys_mod 与 config system。

2. tracer 初始化边界重构

5.3 的 initracer.F 被模块化的 6.3 initracer.F90 取代，并新增：

parse_traceur_file.F90：解析旧式 traceur.def；
parse_tracer_file.F90：解析新式 tracer.def；
tracer_mass_fixer_dyn_mod.F90：修正指定化学 tracer 的动力质量不守恒。

tracer_mod.F90 同时导入两个 parser。新式 parser 调 COMMON 的 readTracFiles_mod，两个 parser 都由 master rank 读取后广播。与 5.3 相比，6.3 的物理初始化不再依赖动力把完整 tracer 元数据作为实参传入，而是优先在物理侧解析配置文件。

迁移规则：

不要只复制 tracer 名称；要保留父子/输运关系和目标 section。
若同时存在 traceur.def 与 tracer.def，必须记录实际被选中的文件与 section；经纬网默认 section 是 lmdz，非结构网格默认是 dynamico。
旧字段 nqperes/nqfils/qperemin 在 6.3 后期命名为 nqparents/nqchildren/qparentmin；自有补丁和外部接口需要同步。
启用 call_mass_fixer_dyn 时，应保存第一步之前的 tracer 柱质量；初始 mass_predyn <= 0 时首个物理步会跳过修正。

详见 tracer_mod。

3. 输出由一个 API 桥接 diagfi 与 XIOS

6.3 新增 write_output_mod。physiq_mod.F 导入 write_output，各类重载执行：

write_output(field)
  |-- output_diagfi = true  -> writediagfi
  `-- CPP_XIOS             -> send_xios_field

与此对应，旧 writeg1d.F、eofdump_mod.F90 及 calleofdump 被删除，output_diagfi 成为是否生成 diagfi.nc 的显式开关。XIOS XML 从 deftank 根目录的旧文件布局迁到：

deftank/xios/
  context_pcm_physics.xml
  field_def_physics.xml
  file_def_physics.xml
  iodef.xml

风险点：当前 write_output_mod.F90 把 xios_is_active_field 查询注释掉并把 is_active 强制设为真。功能上仍由统一 API 发送字段，但大量未被目标文件引用的调用可能带来额外组合、通信或性能开销。XIOS 文件布局和输出选择见 xios config。

4. 1D 驱动成为独立模块群

6.3 在 libf/phymars/dyn1d/ 下形成完整支撑模块群，并新增 startfiles/start1D.txt。旧 dyn1d/testphys1d.F 与 profile.F 被模块化/重写后的 testphys1d.F90、init_testphys1d_mod.F90、profile_temp_mod.F90 等替代。

已核验的主链为：

init_testphys1d
  -> conf_phys(1, llm, nq)
  -> initracer
  -> read_profile_mod 读取 profile_<tracer>
testphys1d 时间循环
  -> physiq
  -> writerestart1D 生成 restart1D.txt

因此 5.3 的 1D 输入不能只按文件名复制。profile 已改名为 profile_temp，水汽/水冰可使用独立 profile 与松弛时间，start1D.txt 位置也移到 startfiles/。详见 testphys1d config 和 dyn1d 目录页。

5. 物理过程的代表性变化

主题	5.3 -> 6.3 的已核验变化	主要入口
水云	`watercloud_mod` 在 improved/simple 两方案间分派；improved 方案引入自适应微时间步并修正 tendency 注入；水冰 profile、地表/地下冰与热惯量反馈继续扩展	water cycle、watercloud_mod
CO2 云	`co2cloud.F90` 模块化为 `co2cloud_mod.F90`，由 `physiq` 调用；地表 CO2 冰最大反照率改为配置项	CO2 cycle、co2cloud_mod
尘埃	新增凝并 `dust_coagulation_mod.F90`；抬升和尘卷风例程模块化；加入可配置抬升尘埃有效半径	dust cycle、dust coagulation
边界层	新增 ATKE 模块群与 `vdif_cd_mod.F90`、`pbl_parameters_mod.F90`；配置校验禁止 ATKE 与 Yamada4 同时启用	`conf_phys.F`、`physiq_mod.F`
热层/分子扩散	`physiq -> thermosphere_mod::thermosphere -> moldiff_MPF`；6.3 修正前序 tendency 传递，并可启用分子扩散质量修正	`thermosphere_mod.F`、`moldiff_MPF.F90`
光化学	`calchim_mod -> photochemistry_mod::photochemistry`，旧非模块化文件被替换	`calchim_mod.F90`、`photochemistry_mod.F90`
动力质量守恒	新增 `tracer_mass_fixer_dyn_mod`，对选定非 CO2 tracer 的动力质量误差作修正，并以 CO2 补偿	`physiq_mod.F`、`tracer_mass_fixer_dyn_mod.F90`

这些条目同时包含“模块化重构”和“新行为”。迁移测试应针对输出或守恒量验证，不能用文件名变化代替数值验证。

光化学还有一项构建契约：photochemistry_mod.F90 调用 LAPACK dgesv，缺少对应实现时会明确中止。启用光化学的 6.3 构建必须把 LAPACK 链接测试纳入冒烟检查。

6. GCM6 样例配置不是 GCM5 配置的原样延续

6.3 deftank/callphys.def.GCM6 的代表性变化包括：

datadir 使用可移植的 ./datadir；
新增 outputs_per_sol；
新增非地形重力波参数组；
新增 reff_lift_dust、cloud_adapt_ts、call_mass_fixer_dyn；
temp_dependant_m 更名为 temp_dependent_m；
nuice_sed、albedo_h2o_cap、albedo_h2o_frost 等默认或样例值发生变化。

此外，max_icecap_albedo、output_diagfi、slow_diagfi、1D 水汽/水冰 profile 控制和 XIOS 文件布局都需要在旧运行目录中显式处理。6.3 新增 callphys.def.MCD6、traceur.def.MCD6、run.def.64x48x73.MCD6、z2sig.def.MCD6；其中旧 z2sig.def 与新 z2sig.def.MCD6 在本快照中哈希相同，属于命名/样例组织变化，不能据此声称垂直坐标算法改变。

迁移与复现实验清单

A. 构建

用 6.3 makelmdz_fcm/build_gcm 重建，不复用 5.3 .o/.mod。
记录 -io ioipsl|mix|xios、MPI/OpenMP 进程线程组合和 arch 三件套。
混合并行至少测试一种 llm 不能被线程数整除的组合。
1D + XIOS 使用 MPI 构建，并确认 XML 在运行目录可见。
启用光化学时确认 LAPACK dgesv 可链接并完成一次实际调用。
检查 dyn1d 中指向 COMMON 的相对链接/占位文件在复制或打包后仍能解析。

B. 配置与 tracer

以 6.3 样例为底稿逐项移植旧 callphys.def，不要整文件覆盖。
替换已弃用或改名键，特别是 temp_dependent_m、albedo_h2o_cap 和输出相关开关。
明确使用 traceur.def 还是 tracer.def，核对 section、顺序、父子关系与 advection 信息。
将物理开关与 tracer 成组检查：水云、CO2 云、化学、尘埃凝并和质量修正各自需要相应 tracer。
比较 z2sig.def 的内容而不是只比较文件名，并确保层数与编译维度一致。

C. 初始场、重启与 1D

用 6.3 newstart/start2archive 转换或至少读取检查旧 start 文件。
检查 mass_predyn_<tracer>、totcloudfrac、watercaptag、坡面和地下水冰相关字段的缺失回退。
1D 更新 start1D.txt 位置、profile_temp 名称、profile_<tracer> 与松弛时间配置。
做一次 restart 连续性测试，比较跨重启前后的表压、总水、总 CO2 冰和 tracer 柱质量。

D. 输出与科学回归

把旧 XIOS XML 映射到 deftank/xios/ 新布局，核对 field 定义与 file 引用两层。
明确 output_diagfi，并检查下游脚本依赖的是 diagfi、XIOS 还是两者。
核对变量重命名（例如 phisfi/phisinit）和新增/删除诊断字段。
用相同初始场做短积分，对比全球平均表压、TOA 能量、总水、总 CO2 冰、尘埃光学厚度及选定 tracer 柱质量。
对新启用过程分别做开/关成对试验；不要把多个新开关一次性全部打开后再定位偏差。

证据等级与仍待确认项

结论类型	本页处理方式
SHA-256 相同/不同、文件新增/删除	已核验的快照事实
`use`、`call`、`getin_p`、条件分支	已核验的源码行为
删除 + 新增且调用链连续	可写为迁移或模块化重构
只有新文件名、尚未追到调用点	只写“存在性变化”，不声称运行时启用
对气候统计量、性能或科学偏差的影响	必须经编译和数值试验确认

仍需运行验证的问题：

两个快照缺少统一可核验的 release tag；本页结论严格绑定到所比较目录。
本次没有编译两版，也没有做 bit-identical 或气候统计回归。
write_output 强制把 XIOS 字段视为 active 的实际性能代价依赖运行配置。
tracer 质量修正、分子扩散修正、尘埃凝并和新水云时间步对守恒量与气候均值的净影响需要成对实验。
COMMON libf/evolution/ 的删除只证明当前 6.3 快照不再携带该目录；其功能是否迁到外部仓库需结合项目发布记录确认。