动力时间推进主题页

源码范围：LMDZ.COMMON-6.3\LMDZ.COMMON 中 dyn3d 主链，并引用 MARS phymars/nogcm 与 phymars/leapfrog_nogcm.F 的实际使用边界。 Mars 运行参与度：必经 + 条件经过。Mars 3D gcm 经过 COMMON conf_gcm/leapfrog 主链；Mars nogcm 类入口位于 MARS 树，但也使用 COMMON 状态模块和初始化接口。完整动力 tendency、tracer 输送、耗散、dynav/history/restart 由入口形态、编译选项和运行开关决定。

读法

这个页面回答一个问题：Mars run 的“一个动力步”如何从配置参数变成 leapfrog 内部的动力、物理、耗散、诊断和 restart 调度。

推荐阅读顺序：

common-gcm-mars-run-entry：从 makelmdz_fcm -p mars gcm、run.def 和 start.nc 进入主链。
conf_gcm：读取 day_step/iperiod/iphysiq/nday/ndynstep/purmats/ecritstart 等时间推进控制。
leapfrog-state-contract：确认 ucov/vcov/teta/ps/masse/phis/q/time_0 的状态约定。
leapfrog-time-scheduler：读 Matsuno forward/backward 和 leapfrog 的 label 调度。
分段追踪：dynamics-transport、physics-coupling、dissipation-conservation、output-restart。

总览

run.def
  |
  v
conf_gcm
  |-- day_step / nday / ndynstep / less1day
  |-- iperiod / purmats
  |-- iphysiq / nsplit_phys / iflag_phys
  |-- dissip_period / iconser
  |-- iecri / periodav / ecritstart
  v
gcm or nogcm entry
  |-- infotrac_init + q allocation
  |-- dynetat0("start.nc") or idealized init
  |-- iniconst / inigeom / inidissip
  |-- iniphysiq(..., dtphys, nsplit_phys, ...)
  v
leapfrog / leapfrog_nogcm
  |-- Matsuno forward/backward reset by iperiod
  |-- complete GCM: caldyn -> caladvtrac -> integrd
  |-- physics gate: calfis -> addfi
  |-- dissipation gate: sponge -> dissip
  |-- output/restart gate: bilan_dyn, writehist, writedynav, dynredem1

配置到调度的映射

配置/状态	写入点	影响的时间推进行为
`nday`, `less1day`, `fractday`, `ndynstep`	`conf_gcm` -> `control_mod`	决定 `itaufin`；`ndynstep>0` 最终覆盖运行步数。
`day_step`	`conf_gcm` -> `control_mod`	决定 `dtvr=daysec/day_step`，也参与 Mars 日期和 restart 时间换算。
`iperiod`	`conf_gcm` -> `control_mod`	控制 Matsuno forward 重启周期，也参与平均/纬向诊断周期。
`purmats`	`conf_gcm` -> `logic_mod`	只在 forward/backward 间往返，不进入常规 leapfrog 步。
`iphysiq`, `iflag_phys`, `nsplit_phys`	`conf_gcm` -> `control_mod/logic_mod`	控制 `apphys`、`dtphys`、`iniphysiq` 和 `calfis/addfi` 调用。
`dissip_period`, `callsponge`	`conf_gcm/inidissip`	控制 `apdiss`、`sponge` 和 `dissip` 段。
`iconser`	`conf_gcm`	控制 `conser` 守恒诊断门。
`iecri`, `periodav`, `ok_dyn*`, `ecritstart`	`conf_gcm`	控制 history/dynav、`bilan_dyn` 和中途 restart 写出。
`read_start`, `timestart`, `starttime`, `raz_date`	`conf_gcm`	决定是否读 `start.nc` 及 restart 时间处理。

复现时先把这些键对应到 control_mod/logic_mod/temps_mod/comconst_mod，再看 leapfrog 当前步的 itau/forward/leapf 状态。只知道 day_step 或 iphysiq 不足以判断一次 physics 是否会发生。

入口初始化

COMMON gcm 在进入 leapfrog 前做的关键工作：

阶段	作用	主题影响
检查 `run.def`	缺失即 `abort_gcm`	时间推进参数必须来自运行目录。
`conf_gcm(99,.TRUE.)`	写运行长度、步长、physics、输出、restart 和开关	后续所有调度门控的来源。
`infotrac_init` + `q` 分配	确定 `nqtot` 和 tracer 表	`leapfrog`、`caladvtrac`、physics 和 history 都使用同一第三维。
`dynetat0("start.nc")` 或 `iniacademic`	读入或构造动力初态	Mars 标准 3D run 通常依赖 `start.nc`。
`iniconst/inigeom/inifilr/inidissip`	初始化常量、几何、滤波和耗散参数	physics、动力算子、耗散和输出都使用这些状态。
`iniphysiq`	把网格、常量、`dtphys/nsplit_phys` 交给 Mars physics	physics 的 `calfis` 前置初始化。

并行 dyn3dpar/gcm 有 MPI/OMP、band、halo 和并行 domain 初始化，但时间推进概念仍对应同一组控制参数。并行主循环见 leapfrog_p，它在同一 Matsuno/leapfrog 门控上增加 SetDistrib、halo/swap、physics band 和 gather 写出约束。

Matsuno/leapfrog 调度

leapfrog 主循环不是单一 do 块，而是用 label 1/2 和逻辑标志管理阶段：

标志	含义
`forward`	Matsuno forward 步，`dt=dtvr`，保存上一时刻状态。
`leapf`	常规 leapfrog 步，`dt=2*dtvr`。
`purmats`	纯 Matsuno 模式，不进入常规 leapfrog。
`apphys`	当前步是否调用 physics。
`apdiss`	当前步是否施加耗散；nogcm 不使用。
`conser`	当前步是否做守恒诊断。
`lafin`	传给 physics 的最后一次调用标志。

非 purmats 的直观顺序：

label 1: forward=.TRUE., leapf=.FALSE., dt=dtvr
label 2: 执行当前 forward 步
if MOD(itau-1, iperiod)==0:
    backward: forward=.FALSE., leapf=.FALSE., dt=dtvr
then:
    leapfrog: forward=.FALSE., leapf=.TRUE., dt=2*dtvr
every MOD(itau, iperiod)==0:
    return to label 1

这也是为什么输出、physics 和耗散不能只按“每 N 步”理解：它们还受 forward/backward/leapfrog 阶段影响。

完整 GCM 的一步

完整 leapfrog.F 的主体可按以下顺序理解：

段	关键调用	状态变化
压力/热力刷新	`pression`, `exner_hyb` 或 `exner_milieu`, `geopot`	从 `ps/teta/phis` 重算 `p/pk/phi`。
动力 tendency	`caldyn`	计算 `du/dv/dteta/dp/w/pbaru/pbarv`。
tracer 输送	`caladvtrac`	按 `iadv` 和 mass flux 更新 `dq`。
状态积分	`integrd`	把动力 tendency 写回 `ucov/vcov/teta/q/ps/masse`。
physics	`calfis -> addfi`	Mars physics tendency 写回动力状态；之后必须刷新 `p/masse/pk`。
耗散/sponge	`sponge`, `dissip`	风场耗散和 conservative heat correction。
诊断/I/O	`bilan_dyn`, `writehist`, `writedynav`, `dynredem1`	输出 history/dynav/diagnostics/restart。

caldyn、caladvtrac、integrd、dissip 等具体数值公式由各细节页展开；主题页只给调用顺序和状态传递。

Physics 和 Mars 日期

physics 段由 apphys 控制。调用前要重算 pressure、Exner 和 geopotential，并构造传给 Mars physics 的日期：

完整 GCM 对 Mars/generic 使用 jD_cur=int(day_ini+itau/day_step)。
Mars 小时使用 hour_ini + mod(itau,day_step)/day_step，不是简单的 itau+1。
calfis 只产生 physics tendency；addfi 才把 dufi/dvfi/dtetafi/dqfi/dpfi 写回状态。
physics 后若 ps 改变，必须重算 p/masse/pk，否则后续耗散、输出和 restart 会看到不一致状态。

这解释了为什么动力时间推进主题和动力-物理接口主题相互依赖：时间门控在 COMMON leapfrog，physics 字段含义在 Mars physics。

耗散、守恒和诊断

耗散只在完整 GCM 中由 apdiss 触发；nogcm 删除了这一段。完整路径中：

sponge 如果启用，先于水平耗散执行。
dissip 产生 dudis/dvdis/dtetadis。
dissip_conservative 默认开启，把动能损失转成热力修正。
conser 和 bilan_dyn 等诊断在独立门控下输出守恒/通量信息。

bilan_dyn 不是主推进器，但它是复现中检查质量、动量、能量和通量趋势的重要输出点。串行见 bilan_dyn，并行见 bilan_dyn_p。

restart/history 发生在哪里

时间推进内的输出与 H1 restart/I/O 主题衔接：

输出	门控	关键页
instant history	`MOD(itau,iecri)==0` 且非半步状态	leapfrog-output-restart
dynav / zonal diagnostic	`MOD(itau,iperiod)==0` 或最终步	history-output-serial-parallel
restart	最终步或 `ecritstart>0` 中途步	restart-io
physics diagfi/stats/XIOS	physics 配置和 Mars 输出开关	history-xios-getin-boundary

writehist 不在 forward Matsuno 半步写出，避免输出半步状态。完整 GCM 的 Mars restart 时间还包含 time_0 和 day_end-day_ini 修正，不能直接用 itau/day_step 替代。

Mars nogcm 差异

Mars nogcm 类路径保留时间调度和 physics 骨架，但不是完整动力：

完整 GCM	nogcm
`caldyn` 计算动力 tendency	tendency 置零，不调用完整动力段。
`caladvtrac` 做 tracer 输送	不调用 tracer advection。
`integrd` 写回动力 tendency	不调用 `integrd`。
`sponge/dissip` 可执行耗散	删除 `apdiss` 和耗散段。
支持 `ecritstart` 中途 restart	只在最终步写 restart。
状态变化来自 dynamics + physics + dissipation	状态变化主要来自 physics tendency 和 pressure/CO2/teta 松弛混合。

因此按 Mars 运行判断“哪些地球/完整动力部分不走”时，关键不是文件名里有 leapfrog，而是入口到底是完整 gcm 还是 Mars nogcm 变体。

guide/nudging 边界

conf_gcm 读取 ok_guide，COMMON gcm 和 MARS phymars/nogcm 可在 planet_type=="generic" 且 ok_guide 时读取 relax.nc；完整 leapfrog 中也有 Earth/IOIPSL 条件下的 guide_main 路径和 generic uforc nudging 分支。串行 guide_mod 与并行 guide_p_mod 已按当前源码确认：guide_main 调用不属于 Mars 标准 3D 主线，因此本主题只把 guide 作为条件边界记录：

Mars 标准 3D 运行是否启用 guide 取决于具体配置。
guide/nudging 的串行主文件页见 guide_mod，并行主文件页见 guide_p_mod；输入读取、压力层插值、湿度限制和状态叠加细节页分别见 guide-input-fields、guide-interpolation-pressure 和 guide-tendency-application。
本页不把 guide 作为 Mars 主时间推进的必经段。

复现检查表

从 run.def 抽出 day_step/nday/ndynstep/iperiod/iphysiq/purmats/dissip_period/ecritstart。
判断入口是完整 gcm、并行 gcm，还是 Mars nogcm。
确认 q 的第三维来自 infotrac%nqtot，而不是物理 tracer 个数。
对单步问题，先确定当前步是 forward、backward 还是 leapfrog。
对 physics 问题，检查 apphys 和 Mars 日期 jD_cur/jH_cur，再追 calfis/addfi。
对耗散问题，确认不是 nogcm，并检查 dissip_period/callsponge/dissip_conservative。
对输出或 restart 问题，先看 iecri/periodav/ecritstart，再回到 restart-io。

待确认

Mars 生产配置中完整 gcm、并行 gcm 和 Mars nogcm 的使用比例需由具体运行脚本确认。
guide_mod/guide_p_mod 已确认主要是 Earth/IOIPSL 条件路径和 Mars/generic relax.nc 边界；若运行分支有本地补丁，仍需结合具体源码再确认。
dissip_conservative 对 dtetadis 的逐行热力修正仍需由 dissip.F 深度页确认。