LMDZ.COMMON Wiki

Mars utility COMMON 状态使用链路

输入范围

LMDZ.MARS\libf\dynphy_lonlat\phymars\newstart.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\start2archive.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\lect_start_archive.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\ini_archive.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\readhead_NC.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\datareadnc.F
LMDZ.MARS\libf\phymars\dyn1d\testphys1d.F90
LMDZ.MARS\libf\phymars\dyn1d\init_testphys1d_mod.F90

Mars 运行参与度：必经 到 接口兼容。这些文件不是 COMMON 源文件本身，但它们是 Mars 运行和工具链使用 COMMON 状态模块的主要证据：newstart/start2archive 负责 start、startfi、start_archive 互转，lect_start_archive/readhead_NC/ini_archive/datareadnc 负责 archive/header/surface 数据读写，testphys1d/init_testphys1d 通过 dyn1d 路径转发使用 COMMON 常量、垂直坐标、网格接口和并行占位模块。

NetCDF helper 边界：这些 Mars utility 的 archive/surface NetCDF 读写主要直接走 netcdf.inc/NF_*，不是 COMMON netcdf95/handle_err wrapper 调用链；详见 Mars utility NetCDF 和 COMMON helper 边界。

参与文件

Mars 文件 COMMON 使用类型 角色
newstart.F control_mod, comconst_mod, comvert_mod, temps_mod, geometry_mod, mod_const_mpi, ioipsl_getincom 从 start_archive.nc 或 start/startfi 创建、修改、重写 Mars 初始状态。
start2archive.F control_mod, comconst_mod, comvert_mod, temps_mod, mod_const_mpi 把 start.nc 和 startfi.nc 追加或写入统一 start_archive.nc。
lect_start_archive.F comconst_mod, comvert_mod, geometry_mod, COMMON 插值/格点转换接口 读取旧网格 archive，水平/垂直插值到当前 GCM 网格。
ini_archive.F comconst_mod, comvert_mod, logic_mod, serre_mod, ener_mod 创建 archive 文件头、controle 表、网格、垂直坐标和固定维度变量。
readhead_NC.F comconst_mod, comvert_mod, temps_mod, ener_mod 从 NetCDF header/control 表恢复动力维度、常量、时间和垂直坐标。
datareadnc.F ioipsl_getincom, comconst_mod, COMMON 插值接口 读取 surface.nc，把地形、反照率、热惯量等插值到 GCM 网格。
testphys1d.F90 dyn1d 直接路径转发的 COMMON 模块、mod_const_mpi, parallel_lmdz 1D Mars physics 驱动程序，按 COMMON 接口准备 physiq 输入。
init_testphys1d_mod.F90 comvert_mod, logic_mod, geometry_mod, regular_lonlat_mod, vertical_layers_mod, mod_interface_dyn_phys 1D 初始化：重建行星常量、垂直层、物理网格、tracer 和 surface 状态。

COMMON 状态提供者

COMMON 提供者 被使用状态 Mars 使用点
control_mod day_step, iphysiq, anneeref, planet_type newstart.F 设置 day_step=180 后调 defrun_new，start2archive.F 设置 planet_type='mars' 后再 defrun_new。
comconst_mod lllm, daysec, dtphys, dtvr, rad, omeg, g, r, cpp, kappa, pi, im, jm archive/header 读写、iniconst/inigeom/iniphysiq 前后常量传递、readhead_NC 尺寸一致性检查。
comvert_mod ap, bp, aps, bps, pa, preff, presnivs, pseudoalt, scaleheight ini_archive 写垂直坐标，lect_start_archive 读旧/新垂直坐标，testphys1d 构造 1D plev/play。
temps_mod day_ini, hour_ini newstart/start2archive/readhead_NC 从 control/header 恢复初始 sol 和 sol 内时间，再写 restart/archive 时间。
logic_mod hybrid, fxyhypb, ysinus init_testphys1d 选择 hybrid 垂直坐标；ini_archive 写 zoom/网格控制信息，细节见 inigeom zoom/map 几何约定。
geometry_mod longitude, latitude, cell_area, init_geometry* newstart 写 restartfi.nc，lect_start_archive 重建 watercaptag，1D 初始化物理几何。
mod_const_mpi / parallel_lmdz COMM_LMDZ, MPI/OMP 初始化占位 utilities 以串行假并行状态调用 physics 或 XIOS 相关初始化。
ioipsl_getincom getin datareadnc 读取 datadir，1D 初始化读取 day0/time/day_step/ndt/psurf/hybrid 等参数。

newstart.F 流程

newstart.F 的入口说明是创建或修改 Mars GCM 初始状态文件，源码第 11-12 行标注输出为 NetCDF start 和 startfi。它在第 17-57 行同时 USE COMMON 配置读取、tracer、控制、几何、MPI 常量、垂直坐标、动力常量和时间状态。

主要顺序：

  1. 第 231-237 行手动把物理并行状态设为串行根进程，保证后面先于 iniphysiq 调用的 tabfi 可运行。
  2. 第 240-243 行调用 infotrac_init 并按 nqtot 分配动力 tracer 数组。
  3. 第 265-305 行选择输入：start_archive.nc 或 start.nc + startfi.nc。
  4. 第 311-350 行读取 controle 表；第 355-360 行把 kappa 和能量守恒量写回 COMMON 状态。
  5. 第 370-380 行通过 Mars tabfi 读取物理控制参数，再把 rad/omeg/g/daysec 写入 comconst_mod。
  6. 第 394-407 行设置 day_step、调用 defrun_new、计算 dtvr=daysec/day_step、调用 iniconst 和 inigeom，再以 dtphys、网格、常量调用 iniphysiq。
  7. 当从 archive 创建 start 时，第 424-440 行用 datareadnc 和 gr_dyn_fi 把 surface 数据转到物理网格，第 453-456 行调用 lect_start_archive。
  8. 当从 start/startfi 读取时，第 470-475 行调用 dynetat0 和 phyetat0 恢复动力/物理状态。
  9. 第 1998-2013 行设置 day_ini/hour_ini，调用 geopot/caldyn0 后写 restart.nc；第 2017 行以后调用 physdem0/physdem1 写 restartfi.nc。

复现要点：newstart 不是单纯文件转换器。它会重建 COMMON 的动力常量、时间步、几何和垂直状态，再把 Mars surface/archive 变量投影到当前网格。若 controle 表与当前 dimensions.h/paramet.h 不一致，后续插值和 restart 写出会继承这个不一致风险。

start2archive.F 流程

start2archive.F 第 10-15 行说明它把 start 和 startfi 合并到 start_archive。源码第 21-39 行使用 infotrac, control_mod, comvert_mod, comconst_mod, temps_mod, mod_const_mpi 和 Mars 物理状态模块。

主要顺序：

  1. 第 157-160 行先调 defrun_new(99,.TRUE.)，随后显式设置 planet_type='mars'。
  2. 第 165-172 行初始化 tracer 并从 start.nc 调 dynetat0 恢复动力场。
  3. 第 178-185 行再次 defrun_new(99,.FALSE.)，调用 iniconst, inigeom, inifilr，再把 daysec/day_ini/dtphys 等传给 iniphysiq。
  4. 第 312-361 行把物理网格字段通过 gr_fi_dyn 转回动力 scalar 网格，包括 tsurf/tsoil/inertiesoil/emis/albedo/qsurf/q2/tauscaling/totcloudfrac 和 SSO 字段。
  5. 第 419-425 行如果 start_archive.nc 不存在，则创建文件并调用 ini_archive 写 header、control 表和坐标。
  6. 第 432-468 行写 Time 并开始写 archive 变量。

复现要点：start2archive 的 COMMON 状态来自两层恢复：dynetat0 读动力 start，phyetat0/tabfi 读物理 startfi，然后 ini_archive/write_archive 把二者合成 archive。这里 temps_mod%day_ini/hour_ini 决定追加的 Time=day_ini+hour_ini。

lect_start_archive.F 流程

lect_start_archive 是 newstart 从 archive 建 start 的核心读入例程。第 26-37 行使用 infotrac%tname、comvert_mod 的 ap/bp/aps/bps/preff、comconst_mod 的 kappa/g/pi、geometry_mod%longitude/latitude，并调用插值和 surface 初始化辅助。

关键逻辑：

  1. 先读取旧 archive 的维度、坐标、垂直层和变量，判断是否需要水平或垂直插值。
  2. 第 1248-1258 行先插值地形、CO2 ice、surface temperature，并用 gr_dyn_fi 转到物理网格。
  3. 第 1268-1281 行同样处理 emis/tauscaling/totcloudfrac。
  4. 第 1283-1320 行处理 watercap/peren_co2ice/watercaptag/albedo；如果 watercaptag 缺失或网格改变，则用 geometry_mod 的经纬度调用 locate_watercaptag 重建。
  5. 第 1329-1369 行插值 surface pressure 后，用 aire/g 计算并缩放大气总质量和 CO2 ice 总量，保持旧 archive 总量。
  6. 第 1382-1428 行根据土壤层定义对 thermal inertia 做垂直插值或用 reference surface inertia 外推。

复现要点：lect_start_archive 对 COMMON 的依赖集中在坐标和守恒量。g 进入质量守恒换算，ap/bp/aps/bps/preff 决定 3D 变量垂直重映射，rlonu/rlatv 与 geometry_mod 决定水平插值和物理网格布尔 mask。

ini_archive.F 和 readhead_NC.F

ini_archive.F 创建 start_archive.nc 文件头。第 37-43 行使用土壤层、垂直坐标、动力常量、逻辑网格开关、zoom 参数和能量状态。第 94-118 行把 COMMON 状态写入 100 长度 tab_cntrl：

第 266-327 行定义并写出 ap/bp/aps/bps，使 archive 可被后续 lect_start_archive 和 readhead_NC 恢复。

readhead_NC.F 是相反方向的 header/control 读取器。第 5-9 行使用 comvert_mod, comconst_mod, temps_mod, ener_mod；第 57-100 行从 controle 写回 im/jm/lllm/day_ini/rad/omeg/g/cpp/kappa/daysec/dtvr/energy，并设置 r=kappa*cpp。第 101-110 行检查文件维度与当前编译维度一致；第 112-220 行读取经纬度和 aps/bps 等垂直层。

复现要点：archive 的 control 表是 Mars utility 和 COMMON 动力状态的桥。ini_archive 写出的字段顺序必须和 readhead_NC/newstart 读取顺序一致。

datareadnc.F surface 数据链

datareadnc.F 第 45-50 行使用 ioipsl_getincom:getin、comconst_mod:g/pi、datafile_mod:datadir 和水平映射 helper。第 120-137 行默认 datadir="/u/lmdz/WWW/planets/mars/datadir"，然后允许 callphys.def 通过 getin("datadir",datadir) 覆盖，最后打开 surface.nc。

第 261-275 行把 360x180 数据补周期列后调用 interp_horiz(..., rlonud, rlatvd, rlonu, rlatv) 插值到当前动力网格；第 281-283 行恢复周期端点。newstart 再用 gr_dyn_fi 把这些动力网格字段转为物理网格字段。interp_horiz/iniinterp_horiz 的面积交叠算法见 dyn3d/interp_horiz。

复现要点：surface.nc 不是 COMMON 文件，但它依赖 COMMON/Mars 共享的 getin、rlonu/rlatv 和水平插值接口。rlonu/rlatv/rlonv/rlatu 来自 inigeom 当前 run 的 zoom/map 几何，详见 inigeom zoom/map 几何约定。没有正确 datadir 时，newstart 的 surface 分支会直接 abort。

testphys1d 和 init_testphys1d 1D 路径

testphys1d.F90 第 31-37 行说明它是 Mars GCM 物理包的 1D column driver，需要 testphys1d.def、callphys.def、run.def 和垂直层文件。第 13-24 行使用 COMMON 转发模块 comvert_mod、mod_const_mpi、parallel_lmdz，并调用 init_testphys1d。

init_testphys1d_mod.F90 的 COMMON 使用与 3D utility 不同：

  1. 第 131-170 行直接给 Mars 常量赋值：rad/daysec/omeg/g/mugaz/rcp/r/cpp/year_day 等，而不是从 controle 恢复。
  2. 第 177-220 行读取 traceur.def，设置 nqtot=nq，分配 tname/nqfils/nqperes。
  3. 第 255-259 行初始化 physics distribution，XIOS 编译时使用 COMM_LMDZ。
  4. 第 263-310 行通过 getin 读取 day0/time/day_step/ndt，并计算 dttestphys=daysec/steps_per_sol。
  5. 第 314-339 行设置 psurf/pa/preff/hybrid，调用 disvert_noterre 和 init_vertical_layers，再由 ap/bp/aps/bps 构造 plev/play。
  6. 第 423-433 行初始化 dyn-phys 接口、regular lon-lat 网格、geometry、dimphy、physics state、fillgeom、conf_phys 和 tracer。
  7. 第 435-440 行强制 iphysiq=1，因为 1D 每一步都调用 physics。
  8. 第 505-512 行按 nslope 重新分配 surface、soil、radiation 和 paleoclimate slope 相关数组。
  9. 第 762-768 行为 inichim_newstart 临时构造类似动力 scalar 网格的 qdyn/psdyn。

复现要点：1D 路径属于 接口兼容。它通过 LMDZ.MARS\libf\phymars\dyn1d 的直接路径转发拿到 COMMON 模块名和接口，但不会走完整 3D gcm -> leapfrog 主链。写 wiki 时不能把 1D iphysiq=1 或手写 Mars 常量误读成 3D GCM 的 COMMON 初始化顺序。

与 COMMON 页面关系

Mars utility
  -> COMMON 状态/控制约定
  -> 垂直离散和 vertical_layers
  -> 动力/物理格点互转
  -> geometry/grid layer 状态
  -> restart/archive/I/O 边界

已有页面链接：

边界和风险