def_var.F90

路径

LMDZ.MARS\libf\phymars\def_var.F90

所属目录 / 模块

libf/phymars

文件定位

def_var.F90 提供一个外部子程序 def_var，用于在已经打开的 NetCDF 文件中定义一个新变量，并写入 title 与 units 两个文本属性。它不是 Fortran module，不保存共享状态，也不直接写变量数据；实际数据写入由 writediagfi.F、writediagmicrofi.F、writediagsoil.F90、write_archive.F、ini_archive.F 和 iniwrite.F 等调用者完成。

该例程封装了传统 NetCDF Fortran 接口的一段重复流程：切回 define mode，调用 NF_DEF_VAR 定义变量，写属性，再退出 define mode。2010 年注释说明输出被强制为 real*4；源码中 NC_DOUBLE 分支已经被注释掉，实际始终使用 NF_FLOAT 定义新变量。

定义的符号

依赖的模块

调用的关键例程

输入

输出

共享状态与副作用

• 本文件没有 module 变量、common block、SAVE 局部状态或 OpenMP 声明。
• 它会修改 nid 指向的 NetCDF 文件结构：新增变量、写入 title 与 units 属性，并在成功路径结束时退出 define mode。
• 三类失败会立即 abort_physic：NF_DEF_VAR 失败、写 title 属性失败、写 units 属性失败。
• 源码没有在 NF_REDEF 和最终 NF_ENDDEF 后检查 ierr；复现失败时需要结合调用者传入的文件状态和 NetCDF 返回码定位。

核心逻辑

1. 调用 NF_REDEF(nid)，把已打开的 NetCDF 文件切到定义模式。
2. 调用 NF_DEF_VAR(nid, adjustl(name), NF_FLOAT, nbdim, dimids, nvarid) 定义新变量。
3. 如果变量定义失败，打印变量名和 NF_STRERROR(ierr)，再调用 abort_physic("def_var", "netcdf definition problem", 1)。
4. 用 NF_PUT_ATT_TEXT 写 title 属性，长度为 len_trim(adjustl(title))。
5. 如果 title 写入失败，打印诊断并以 netcdf title attribute problem 中止。
6. 用 NF_PUT_ATT_TEXT 写 units 属性，长度为 len_trim(adjustl(units))。
7. 如果 units 写入失败，打印诊断并以 netcdf units attribute problem 中止。
8. 调用 NF_ENDDEF(nid) 退出定义模式。

伪代码

subroutine def_var(nid, name, title, units, nbdim, dimids, nvarid, ierr)
  ierr = NF_REDEF(nid)

  ierr = NF_DEF_VAR(nid, adjustl(name), NF_FLOAT, nbdim, dimids, nvarid)
  if ierr is not NF_NOERR:
    print variable-definition failure and NetCDF error text
    abort physics

  ierr = NF_PUT_ATT_TEXT(nid, nvarid, "title",
                         len_trim(adjustl(title)), adjustl(title))
  if ierr is not NF_NOERR:
    print title-attribute failure and NetCDF error text
    abort physics

  ierr = NF_PUT_ATT_TEXT(nid, nvarid, "units",
                         len_trim(adjustl(units)), adjustl(units))
  if ierr is not NF_NOERR:
    print units-attribute failure and NetCDF error text
    abort physics

  ierr = NF_ENDDEF(nid)
end

参与的主题流程

主要调用点

写法特点

• 外部子程序而非 module：文件只有一个 subroutine def_var，没有 contains、module 或显式接口。
• 传统 NetCDF Fortran 77 风格接口：通过 include "netcdf.inc" 使用 NF_* 常量和函数。
• 强制单精度输出定义：虽然保留了 NC_DOUBLE 条件编译痕迹，但相关代码被注释掉，当前总是 NF_FLOAT。
• 属性名使用 title 而不是 long_name：源码注释明确说 long_name 更合适，但实现仍写 title。
• 调用者负责维度准备：本例程不创建维度，只消费 dimids；维度缺失通常会在调用者的 NF_INQ_DIMID 或后续定义阶段暴露。

复现要点

• 调用 def_var 前，nid 必须指向已创建并打开的 NetCDF 文件。
• dimids 必须已经按变量维度顺序填好，且数组长度与 nbdim 一致。
• 新变量数据类型固定为 NF_FLOAT；即使编译时定义 NC_DOUBLE，当前源码也不会用 NF_DOUBLE 定义变量。
• name、title、units 会先 adjustl，属性长度用 len_trim(adjustl(...))，因此左侧空格会被移除，右侧空格不写入属性。
• 如果变量已经存在，正常调用者通常不会调用 def_var，而是在 NF_INQ_VARID 成功后直接写数据或在初始时刻触发重复变量错误。

待确认

• NF_REDEF 和最终 NF_ENDDEF 的返回码没有立即检查；在异常文件状态下错误会如何传播，需结合具体 NetCDF 库行为和调用者后续检查确认。
• abort_physic 在本文件中未显式声明接口；编译链接依赖外部符号解析，具体来源需从全局构建系统确认。

相关页面

• writediagsoil
• iniwritesoil
• phymars 目录
• 项目结构
• XIOS 配置