Mars start/restart/archive 文件职责边界

输入范围

LMDZ.COMMON-6.3\LMDZ.COMMON\libf\dyn3d_common\dynetat0.F90
LMDZ.COMMON-6.3\LMDZ.COMMON\libf\dyn3d_common\dynredem.F90
LMDZ.COMMON-6.3\LMDZ.COMMON\libf\dyn3d_common\dynredem_mod.F90
LMDZ.MARS\libf\phymars\phyetat0_mod.F90
LMDZ.MARS\libf\phymars\phyredem.F90
LMDZ.MARS\libf\phymars\iostart.F90
LMDZ.MARS\libf\phymars\tabfi.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\newstart.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\start2archive.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\ini_archive.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\write_archive.F
LMDZ.MARS\libf\dynphy_lonlat\phymars\lect_start_archive.F

Mars 运行参与度：条件经过。普通 Mars 3D run 读取 start.nc/startfi.nc 或写 restart.nc/restartfi.nc 时经过；newstart/start2archive/start_archive.nc 是初始化、重网格和归档工具链，不是每个时间步必经。

NetCDF helper 边界：newstart/start2archive/ini_archive/write_archive/lect_start_archive/readhead_NC 的 Mars archive 层主要直接调用 netcdf.inc/NF_*，不直接使用 COMMON netcdf95/handle_err wrapper；详见 Mars utility NetCDF 和 COMMON helper 边界。

文件职责总览

COMMON 动力 start/restart

dynetat0.F90 是动力初始场读取器。它打开 fichnom，读取 controle，并在 planet_type=="mars" 或 generic 时进入 planeto-like 分支：

1. controle(1:3) 恢复 im/jm/lllm。
2. planeto-like 文件把 controle(4) 写入 day_ini，并以 idecal=4 读取 rad/omeg/g/cpp/kappa/daysec/dtvr 等。
3. 读取 rlonu/rlatu/rlonv/rlatv, cu/cv, aire, phisinit。
4. 优先查找 temps，缺失时改查 Time；Mars planeto 文件通常用 Time。
5. 若 timestart < 0，选最后一个时间；否则按 timestart 匹配时间值。
6. Mars 分支把 time(indextime)+hour_ini 合并进 day_ini/hour_ini/time0，保证后续动力用新的 sol 内时间。
7. 按选中的 indextime 读 vcov/ucov/teta/tracer/masse/ps。缺失 tracer 在 Mars 分支中初始化为 0。

dynredem.F90 写动力 restart，分两步：

1. dynredem0(fichnom,iday_end,phis) 创建文件、写 invariant 字段和定义变量。Mars/generic 分支用 longitude/latitude/altitude/interlayer/Time 维名，写 controle, ap/bp/aps/bps/presnivs, geometry 和 phisinit。
2. dynredem1(fichnom,time,vcov,ucov,teta,q,masse,ps) 打开文件，追加 Time 或 temps，重写 controle，再写 ucov/vcov/teta/masse/ps 和所有 tracer。

复现边界：COMMON 动力 restart 不知道 tsurf/tsoil/albedo/qsurf/q2/tauscaling/watercap 等 Mars physics 字段；这些必须从 startfi/restartfi 或 start_archive 的物理部分恢复。

Mars physics start/restart

phyetat0_mod.F90 读取 startfi.nc。入口参数中的 fichnom 注释为 "startfi.nc" file，输出包括 tsurf/tsoil/albedo/emis/q2/qsurf/qsoil/tauscaling/totcloudfrac/wstar/watercap/perennial_co2ice/def_slope/subslope_dist。

主要读入顺序：

1. 若 startphy_file 为真，调用 iostart:open_startphy(fichnom)，然后 tabfi 读取 controle，恢复 physics 层数、day_ini/time0、Mars 常量、dtphys、轨道和 surface/radiative 默认参数。
2. 读取 def_slope/subslope_dist；若缺失且 nslope==1 可用默认，否则要求通过 newstart 修正。
3. 读取 invariant 或弱时变 surface/topography 字段：phisfi, albedodat, ZMEA/ZSTD/ZSIG/ZGAM/ZTHE, hmons/summit/base。
4. 查询 Time 维；默认使用最后一条记录，或按 timestart 选择。和动力类似，time(indextime)+time0 会合并进 day_ini/time0。
5. 读取时变 physics memory：tauscaling, dust_rad_adjust_*, dtau, totcloudfrac, wstar, tsurf, albedo, emis, q2, non-orographic GW memory。
6. 若 call_mass_fixer_dyn，读取 mass_predyn_<tracer> 标量并设置 found flags。
7. 逐 tracer 读取 surface tracer；h2o_vap 映射到 h2o_ice surface tracer，co2 先兼容旧变量 co2ice。
8. 读取 watercap；若缺失，会把负的 surface h2o_ice 转移到 watercap。
9. 通过 soil_settings 读土壤温度、热惯量和 subsurface tracers；再读 watercaptag、paleoclimate 字段和 perennial_co2ice。

phyredem.F90 写 physics restart，也分两步：

1. physdem0 调用 iostart:open_restartphy(filename) 创建文件和维度，写 controle, controle_descriptor, soildepth, longitude/latitude/area, phisfi, albedodat, topography fields, watercaptag, def_slope, subslope_dist。
2. physdem1 再打开同一文件，第一件事写 Time，由 iostart:put_var 建立或追加时间索引；随后写 watercap, perennial_co2ice, tsurf, inertiesoil, tsoil, albedo, emis, q2, totcloudfrac, tauscaling, dust/thermal/GW memory, surface tracers, flux_geo, adsorption/paleoclimate fields 和 mass_predyn_*。

iostart.F90 是 Mars physics start/restart I/O 层：

• open_startphy 只读打开 startfi.nc，并把 nid_start 广播给物理并行进程。
• open_restartphy 创建或重新打开 restartfi.nc，定义 scalar/index/physical_points/subsurface_layers/nlayer_plus_1/number_of_advected_fields/nlayer/Time/nslope/inter_slope/descriptor/description_size。
• put_field 会 gather 到 global physical grid 后写；put_var("Time",...) 是特殊路径，会追加 unlimited Time 并更新 timeindex。

复现边界：Mars physics restart 保存的是 physics column state 和 surface/soil memory，不保存动力风、温度、质量和 surface pressure 的动力网格版本。

start_archive.nc 合并层

start_archive.nc 是 Mars 工具链中的合并初始态文件。start2archive.F 第 10-15 行说明它把 start 和 startfi 合成单一 archive，并允许多个初始态存在同一个 archive 中。

写 archive 的流程：

start2archive
  -> dynetat0("start.nc")       # 读 COMMON 动力状态
  -> phyetat0("startfi.nc")     # 读 Mars physics 状态
  -> gr_fi_dyn                  # 物理网格字段转动力 scalar 网格
  -> open/create start_archive.nc
  -> ini_archive                # 写 header/control/coord/vertical
  -> write_archive              # 按 ntime 写每个字段

ini_archive.F 构造 archive header。它把 tab_cntrl(1:50) 作为动力控制表，且注释说明从 51 开始写入 tab_cntrl_fi 的物理控制值。它写经纬度、ap/bp/aps/bps/presnivs、surface geopotential、土壤层和 slope 维度等；其中 tab_cntrl(19:26) 和 rlonu/rlatu/rlonv/rlatv/cu/cv/aire 的 zoom/map 几何约定见 inigeom zoom/map 几何约定。

write_archive.F 是通用变量追加器：按 dim=3/2/-3 等不同情况创建变量并写入 Time 的第 ntime 条记录。start2archive.F 用它写 watercap, perennial_co2ice, watercaptag, tauscaling, totcloudfrac, emis, albedo, ps, tsurf, temp, u, v, q2surf/q2atm, SSO fields, atmospheric tracer, surface tracer, tsoil, inertiesoil, inertiedat 等。

读 archive 的流程：

newstart
  -> open start_archive.nc
  -> tabfi(..., tab0=50, ...)   # 从 archive 的物理控制段读参数
  -> datareadnc + gr_dyn_fi     # 可读取 surface.nc 并准备当前网格 surface fields
  -> lect_start_archive         # archive 变量插值到当前动力/物理网格
  -> dynredem0/1("restart.nc")
  -> physdem0/1("restartfi.nc")

lect_start_archive.F 从 archive 读旧网格变量，做水平/垂直插值，并用 gr_dyn_fi 转换到物理列。它对 ps 和 CO2 ice 做总量缩放，保持旧网格大气质量和 CO2 ice 总量；对 watercaptag 缺失或网格改变的情况，会调用 locate_watercaptag 重建。

复现边界：start_archive.nc 不是运行中 restart 的直接替代品。它是转换层：从 start/startfi 生成，或由 newstart 转回 restart/restartfi。跨网格时，archive 读取会引入插值和质量重标定。

newstart 两条入口路径

newstart.F 让用户选择输入类型：

两条路径最后都会调用：

• dynredem0("restart.nc",day_ini,phis)
• dynredem1("restart.nc",hour_ini,vcov,ucov,teta,q,masse,ps)
• physdem0("restartfi.nc",...)
• physdem1("restartfi.nc",...)

因此 newstart 的输出命名是 restart*，但其语义是为后续 Mars run 准备新的初始动力/物理状态。

1D 边界

testphys1d 的 restart 体系独立：

• 若 startfiles_1D 为真，它检查 start1D.txt 和 startfi.nc。
• start1D.txt 提供 ps/pa/preff、tracer profile、u/v/teta 等 1D 列变量。
• startfi.nc 仍用于 physics surface/soil/qsurf 等状态。
• writerestart1D 写 restart1D.txt，不是 NetCDF restart.nc。
• testphys1d 若没有 startfi.nc，会用 physdem0/1("startfi.nc",...) 生成一个 physics start 文件。

复现清单

风险和待确认

• start.nc 与 startfi.nc 的 Time 选择都受 timestart 影响；若两者时间轴不一致，代码会分别选中各自的记录，没有统一文件级校验。
• dynetat0 缺失 Mars tracer 时置零；phyetat0 对 surface tracer 缺失多为置零或 fallback。复现实验时应检查缺失字段日志。
• start_archive 跨网格读取会改变 ps 和 CO2 ice 的局部分布以保持总量，不能与原始格点逐点比较。
• phyetat0 有 startphy_file=.false. 的无 startfi 初始化路径，但 nslope!=1 会 abort；当前 wiki 只把它当条件路径。

相关页面

• dynredem restart 写出串并行对照
• Mars utility COMMON 状态使用链路
• inigeom zoom/map 几何约定
• Mars utility 常量和垂直坐标使用链路
• Mars utility NetCDF 和 COMMON helper 边界
• dyn3d 水平面积交叠插值
• Mars dyn1d COMMON 直接转发约定
• COMMON 状态/控制约定
• 垂直离散构造
• 物理侧几何、regular lon-lat、垂直层和网格互转