fallback getin 文件来源、key 表初始化和 Mars 无 IOIPSL 条件经过

输入范围

LMDZ.COMMON-6.3\LMDZ.COMMON\libf\misc\ioipsl_getincom.F90
LMDZ.COMMON-6.3\LMDZ.COMMON\libf\phy_common\ioipsl_getin_p_mod.F90

本页范围

本页深入 ioipsl_getincom.F90 的 fallback getin 实现，覆盖：.def 文件如何被读入内存、key 表如何构建和缓存、keystatus 语义、向量 key 和压缩字段的处理方式，以及 Mars 在 CPP_IOIPSL 未定义时经由 getin_p 调到此 fallback 的完整链路。ioipsl-getin-system 组页给出系统级概述；本页聚焦文件来源和 key 表内部机制。

编译守卫与 fallback 选择

ioipsl_getin_p_mod.F90 的编译守卫决定 getin 的来源：

#ifdef CPP_IOIPSL
USE ioipsl, ONLY: getin        ! IOIPSL 库版本
#else
USE ioipsl_getincom, ONLY: getin ! 本 fallback 版本
#endif

Mars 编译通常不定义 CPP_IOIPSL，因此 getin_p 的每个 specific procedure 在 master 线程上调用的是本页描述的 ioipsl_getincom:getin。动力侧 conf_gcm.F90 直接 USE ioipsl_getincom 或 IOIPSL getin，取决于动力编译选项。

文件来源

初始文件列表

getin_read 将 filelist(1) 硬编码为 'run.def'，nbfiles=1。filelist 是 CHARACTER(LEN=100) 的 SAVE 数组，容量 max_files=100。

INCLUDEDEF 机制

当 getin_readdef 遇到 INCLUDEDEF 关键字时，getin_decrypt 将该行所有空格分隔的文件名追加到 filelist。getin_read 的 DO WHILE (current <= nbfiles) 循环会随之读取新增文件，形成深度优先的包含链。

run.def
  INCLUDEDEF phys_mars.def watercloud.def
    → filelist(2) = 'phys_mars.def'
    → filelist(3) = 'watercloud.def'

文件打开与缺失处理

getin_readdef 用 OPEN(UNIT=22, FILE=filelist(current), STATUS="OLD", IOSTAT=io_err) 打开文件。若 io_err /= 0，调用 ipslerr(2,...)（warning 级别）并 RETURN，不终止程序。因此 Mars 运行时若某 .def 文件不存在，该文件被静默跳过，后续 key 查找将使用调用方提供的默认值。

文件解析管线

行读取与注释跳过

getin_skipafew 逐行读取，跳过以 # 开头的注释行。遇到注释行时重置 nb_lastkey = 0，终止向量续行上下文。空行同样终止续行。

key=value 解析

getin_readdef 用 INDEX(READ_str, '=') 分割 key 和 value：

1. key 提取：key_str = TRIM(ADJUSTL(READ_str(1:ptn-1)))。
2. __NNN 向量下标规整：若 key 含 __，将下标部分重格式化为 c_i_fmt = '(I5.5)'（5 位零填充），确保 key__1 和 key__00001 匹配。
3. value 清洗：nocomma 去逗号，cmpblank 压缩多余空白。

压缩字段表示

getin_decrypt 检测 value 中的 * 号（非引号开头时）：N*value 表示该值重复 N 次。compline(nb_lines) 存储重复次数（> 0），否则 -1。

多值行拆分

若 value 含空格且非引号包裹，getin_decrypt 按空格拆分为多个 TARGET__00001, TARGET__00002, ... 条目。每个条目独立存入 targetlist/fichier/fromfile。

向量续行

无 = 号的非空行被视为上一个 key 的续行。若上一个 key 是标量（nb_lastkey == 1），自动转换为 TARGET__00001 向量表示并继续递增下标。

文本存储层

文件解析结果存入三组并行数组：

初始分配 i_txtslab=1000 行，getin_alloctxt 按 slab 扩容。nb_lines 跟踪当前行数。

一致性检查

getin_read 在所有文件读取完成后调用 getin_checkcohe。该子程序对 targetlist 做 O(n²) 逐对比较，发现重复 key 时：

1. 打印两个值的来源和文本。
2. 将先出现的 targetlist(line) 置为空白（' '），保留后出现的值。
3. 打印 "We will keep only the last value"。

这意味着后读入的文件覆盖先读入的同名 key，同一文件内后面的行覆盖前面的行。

key 表结构

t_key 类型

TYPE :: t_key
  CHARACTER(LEN=l_n) :: keystr         ! key 名（30 字符）
  INTEGER :: keystatus                 ! 1=文件, 2=默认, 3=部分默认
  INTEGER :: keytype                   ! k_i=1, k_r=2, k_c=3, k_l=4
  INTEGER :: keycompress               ! >0: 压缩重复次数; <0: 未压缩
  INTEGER :: keyfromfile               ! 来源文件索引
  INTEGER :: keymemstart               ! typed memory 起始位置
  INTEGER :: keymemlen                 ! typed memory 占用长度
END TYPE t_key

类型常量

typed memory 池

四组一维 SAVE 数组分别存储各类型值：

i_mempos/r_mempos/c_mempos/l_mempos 跟踪各池当前末尾位置。getin_allocmem 按需扩容，每次增加 MAX(memslabs, len_wanted) 个元素，使用 tmp 数组复制旧数据。

key_tab 分配

getin_allockeys 初始分配 memslabs=200 个 t_key 条目。空间不足时按 memslabs 增量扩容。key_tab(:)%keycompress 初始化为 -1。

getin 调用流（首次 vs 缓存命中）

每个 typed specific procedure（getinis/getini1d/getini2d/getinrs/getinr1d/getinr2d/getincs/getinc1d/getinc2d/getinls/getinl1d/getinl2d）遵循相同模式。以 getinis 为例：

SUBROUTINE getinis (target, ret_val)
  CALL get_findkey (1, target, pos)     ! ① 在 key_tab 中查找
  tmp_ret_val(1) = ret_val              ! ② 保存调用方默认值
  IF (pos < 0) THEN
    CALL get_fil (target, status, fileorig, i_val=tmp_ret_val)  ! ③ 从文件文本解析
    CALL get_wdb (target, status, fileorig, 1, i_val=tmp_ret_val) ! ④ 写入 key 表
  ELSE
    CALL get_rdb (pos, 1, target, i_val=tmp_ret_val)  ! ⑤ 从 key 表读取
  ENDIF
  ret_val = tmp_ret_val(1)              ! ⑥ 回写
END SUBROUTINE getinis

流程阶段

懒初始化

getin_read 由 SAVE 变量 allread 守卫，仅在首次调用时执行：分配文本、key 表和四组 typed memory → 读取 run.def 及所有 INCLUDEDEF 文件 → getin_checkcohe → allread=1。后续调用直接返回。

keystatus 语义

get_fil 根据解析结果设置 status：

keystatus=2 时打印 "USING DEFAULT BEHAVIOUR FOR <target>"。部分默认时逐个打印 "USING DEFAULTS : <target>__<n> = <value>"，超过 max_msgs=15 条后缩写为 "USING DEFAULTS ..."。

值解码

get_fil 按 get_qtyp 返回的类型解码：

IOSTAT 非零时调用 ipslerr(3,...) fatal 终止。

压缩字段展开

当 compline(pos) > 0 时，get_fil 将解析到的单值 i_cmpval/r_cmpval 填充到所有 found(it) == .FALSE. 的位置。get_rdb 中压缩字段也使用单值填充：i_val(1:size_of_in) = i_mem(key_tab(pos)%keymemstart)。

get_wdb 在写入时判断压缩条件：MINVAL(val) == MAXVAL(val) 且 size_of_in > compress_lim=20，满足则 keycompress = size_of_in、keymemlen = 1。

向量 key 索引格式

向量 key 使用 TARGET__NNNNN 格式，NNNNN 为 5 位零填充整数（c_i_fmt = '(I5.5)'）。get_fil 查找时先尝试 target 原名，失败后尝试 target//__NNN（it 从 1 到 nb_to_ret）。

l_n=30 限制 key 名最长 30 字符。向量 key 的基名部分截断至 l_n - n_d_fmt - 2 = 30 - 5 - 2 = 23 字符，为 __NNNNN 后缀预留空间。

并行 wrapper（getin_p）

ioipsl_getin_p_mod.F90 将 getin 包装为并行安全版本。每个 specific procedure 遵循：

!$OMP BARRIER
IF (is_master) THEN
  CALL getin(VarIn, VarOut)
ENDIF
CALL bcast(VarOut)

character 1D 逐元素广播是因为 Fortran CHARACTER(LEN=*) 数组在内存中不连续，不能直接整体 bcast。

bcast 来自 mod_phys_lmdz_transfert_para，is_master 来自 mod_phys_lmdz_para。因此 getin_p 的前提是物理侧并行基础设施已初始化。

Mars 无 IOIPSL 条件经过

Mars 编译不定义 CPP_IOIPSL 时：

1. ioipsl_getin_p_mod.F90 使用 USE ioipsl_getincom, ONLY: getin。
2. 物理配置（phymars/conf_phys.F 等）调用 getin_p。
3. master 线程触发 getin → get_findkey(1) 查 key_tab → 首次 miss → getin_read 懒初始化（读 run.def + INCLUDEDEF 文件） → get_fil 解析 → get_wdb 写表 → bcast。
4. 后续同 key 调用命中 key_tab → get_rdb 直接读 typed memory → bcast。

Mars 动力侧（conf_gcm.F90）可能使用 IOIPSL getin 或 ioipsl_getincom getin，取决于动力编译路径，但 fallback 行为一致。

关键常量汇总

相关页面

• ioipsl-getin-system
• ioipsl_getin_p_mod
• mod_phys_lmdz_para
• getin-typed-parser
• history-xios-getin-boundary
• common-gcm-mars-run-entry