字典语法与 include 机制：工程设置与诊断验证

OpenFOAM 的字典是纯文本、声明式的键值容器，#include 家族让你把一份配置同时喂给几十个算例，代价是"我改的那一行到底生效没有"变得难以肉眼确认。本文给出 FoamFile 头的必需字段、include 的四个指令与路径解析顺序、#inputMode 决定的覆盖优先级，以及一套按共享层级组织 system/ 的目录方案。源文件里写着 nu 1.5e-5; 不等于求解器用了 $1.5\times 10^{-5}$：它可能被后置的 include 覆盖，可能因为键名拼错而根本没被读取，也可能被默认值静默替换。

未定义键的相对偏差可以量化

键缺失时的后果取决于读键的代码有没有给默认值。定义相对偏差

$$\delta_{k} = \frac{\lvert v_{\text{eff}} - v_{\text{target}} \rvert}{\lvert v_{\text{target}} \rvert}$$

目标运动粘度 $v_{\text{target}} = 1.5\times 10^{-5}\ \mathrm{m^2/s}$，而求解器因键名拼写错误落回某个 $1.0\times 10^{-6}\ \mathrm{m^2/s}$ 的默认值，则 $\delta_k = \lvert 1.0\times 10^{-6} - 1.5\times 10^{-5}\rvert / 1.5\times 10^{-5} = 0.933$，偏差 93.3%。这不是 10% 量级的调参误差，而是把流态整体挪动：以 $\rho = 998.2\ \mathrm{kg/m^3}$、$U = 1.5\ \mathrm{m/s}$、$L = 0.05\ \mathrm{m}$ 计，$Re = \rho U L/\mu = 998.2\times 1.5\times 0.05/1.002\times 10^{-3} \approx 7.5\times 10^{4}$；若 $\nu$ 被取成 $1.0\times 10^{-6}$，等效 $Re$ 变为 $1.1\times 10^{5}$，湍流模型的第一层网格要求随之改变。凡是 $\delta_k$ 超过 $10^{-2}$ 的偏差，都应按"配置错误"而非"参数敏感"处理。

配置片段与核对命令

foamDictionary -entry solvers/p/solver -value system/fvSolution
foamDictionary -entry adjustTimeStep -value system/controlDict
foamDictionary -expand system/fvSolution > expanded.fvSolution
grep -rn "#include" system/ constant/ 0/

-expand 会输出展开 include 与变量之后的完整字典，把它与源文件对照，就能看出哪些条目来自共享层。第三条命令用于快速盘点算例实际引用了哪些外部文件，避免共享仓库被移动后无人察觉。

把展开字典变成配置指纹

把每次运行的展开结果与哈希一起归档，可以让"两次结果不同"的归因变成一次字符串比较：

for f in system/controlDict system/fvSchemes system/fvSolution constant/physicalProperties; do
    foamDictionary -expand "$f" > "expanded.$(basename $f)"
    md5sum "expanded.$(basename $f)" >> config.fingerprint
done
sort config.fingerprint -o config.fingerprint

同一算例两次运行的 config.fingerprint 应完全一致。若目标量差异超过 1% 而指纹相同，差异就只能来自初始场、网格或随机种子；指纹不同则先定位到具体文件再谈物理。这比逐文件 diff 快得多，因为它把展开、排序与哈希合并成一步。

字典由哪些语法单元构成

一个字典文件由可选的 FoamFile 头、若干键值对、以及若干以 # 开头的指令组成。FoamFile 头的四个字段各有职责：version 声明格式版本，format 取 ascii 或 binary，class 决定解析器构造哪种容器类型，object 是该对象在对象注册表（objectRegistry）中的名字。class 与 object 会被校验，把 volScalarField 写成 volVectorField，或在 U 文件中声明 object p，都会在启动时被拒绝。

键值对的常见形态有四种：标量 deltaT 1e-4;、带量纲的 nu 1.5e-5; 与 dimensions [0 2 -1 0 0 0 0]; 分离写法、列表 nonuniform List<scalar>、以及嵌套子字典。嵌套字典的键名不能重复，重复时后者覆盖前者并可能触发警告。

include 家族的四个指令

FoamFile
{
    version     2.0;
    format      ascii;
    class       dictionary;
    object      fvSolution;
}

#include            "solverSettings"          // 相对 case 路径
#includeIfPresent     "turbulenceOverrides"    // 缺失时静默跳过
#includeEtc          "caseDicts/setConstraintTypes"
#includeFunc        residuals                 // 从 etc/caseDicts 取函数对象

solvers
{
    p
    {
        solver          GAMG;
        tolerance       1e-7;
        relTol          0.01;
    }
}

四个指令的差别在于"文件不存在时怎么办"和"从哪里找"。#include 找不到文件立即报错并打印尝试过的路径；#includeIfPresent 静默跳过，适合放可选的团队覆盖文件；#includeEtc 专门搜索 $WM_PROJECT_DIR/etc/；#includeFunc 搜索 $FOAM_CASE/system/ 与 $WM_PROJECT_DIR/etc/caseDicts/，后处理函数对象通常用它引入。

路径解析按固定顺序进行：

$$p_{\text{resolve}} = \begin{cases} p & \text{若 } p \text{ 以 / 开头} \\ \$FOAM\_CASE/p & \text{若相对路径在算例根下存在} \\ \$FOAM\_CASE/system/p & \text{若相对路径在 system 下存在} \\ \$WM\_PROJECT\_DIR/etc/p & \text{否则回落到安装目录} \end{cases}$$

路径中可以直接使用环境变量，"$FOAM_CASE/system/fvSolution.base" 与 "$WM_PROJECT_DIR/etc/caseDicts/postProcessing/forces" 都能被展开。写相对路径比写绝对路径更利于算例搬迁，但前提是算例根目录固定——始终从算例根启动求解器。

inputMode 决定谁覆盖谁

同名键出现两次时，结果由 #inputMode 决定：

$$v_{\text{eff}} = v_{i^{*}}, \quad i^{*} = \max\{\, i : k_i = k \,\}$$

在默认的 merge 模式下 $v_{\text{eff}}$ 就是最后一次出现的值，因此"先写通用值、再用 include 覆盖"是可行的写法。overwrite 与 merge 在多数场景下行为接近，区别在列表与子字典的处理；protect 禁止后续覆盖，用于锁住关键条目；error 则在检测到重复键时直接报错，适合评审严格的交付算例。把 #inputMode error 放在共享字典里，能在配置被误改的第一时间暴露问题，而不是等到结果异常才回头翻文件。

按共享层级组织 system 目录

跨算例复用的配置适合分成三层：全项目通用的数值与求解设置放在一个共享仓库，按物理类型（不可压湍流、可压、多相）各自一份；单个算例只保留真正个性化的条目，例如几何相关的 patch 名与边界值。收益可以用重复行数直接衡量：

$$R = 1 - \frac{n_{\text{case}} + L_{\text{shared}}}{n_{\text{case}}\,L_{\text{shared}}}$$

以 20 个算例、共享字典 120 行、每算例原需复制一份计，$R = 1 - (20+120)/(20\times 120) = 1 - 140/2400 = 0.942$，即重复内容减少约 94.2%。剩下 20 行是每个算例自己的入口速度、patch 名与时间控制，这部分不该共享，因为一旦共享就失去了对照能力。

配合 #includeFunc 还能把后处理定义也集中起来：在 controlDict 里写 #includeFunc mag(U)、#includeFunc CourantNo、#includeFunc residuals，函数对象定义由安装目录提供，算例里不再出现几十行的 functions 子字典。

故障模式与判定试验

现象	根因	判定试验
cannot open file 后打印 .../system/fvSolution.base	#include 相对路径基准不在预期目录	从算例根运行，并用 -expand 查看实际解析路径
改了共享字典但结果不变	#include 位置在覆盖段之后，或 #inputMode protect 生效	用 foamDictionary -entry <key> -value 回显生效值
keyword ... is undefined in dictionary	键名拼写错误或该键在被 include 的文件里	grep -rn "<key>" system/ 定位定义位置
出现 Unknown directive '#includeIf'	指令名不存在，正确名为 #includeIfPresent	修正后重跑，启动阶段不应再报指令错误
两个算例结果莫名相同	个性化条目被写进了共享字典	对比两算例的 expanded.* 展开文件差异
foamDictionary -entry nu -value 回显值与源文件不一致	键被后置 include 覆盖	对 -expand 输出做 grep -c "^nu"，出现两次即为覆盖
键报"未定义"但源文件里能看到	键名大小写或层级写错，实际从未被读取	grep -rn "<key>" 对照展开文件中的路径
两个算例结果相同且都偏离预期	个性化条目被写进共享字典，两边读同一份	比较两份 config.fingerprint 的差异行
残差在固定步数后跳变一个量级	某键回退到默认值，改变了线性求解行为	逐键 -value 回显，与设计值做 $\delta_k$ 量化
修改 include 文件后报解析中断	展开链存在环引用或路径失效	grep -rn "#include" 画引用图，检查环

验证计算：从残差跳变反查字典

一次典型的静默回退表现为残差曲线在若干步后突然抬高一个量级。取某算例：前 200 步 p 的初始残差稳定在 $3.2\times 10^{-4}$，第 201 步跳到 $2.8\times 10^{-3}$，放大约 8.8 倍。此时用 foamDictionary -entry <疑似键> -value 逐个回显，比读 log.run 更直接。常见嫌疑是松弛因子与线性求解器容差：若 relTol 从 0.01 被默认值 0 取代，p 方程每步被解到 $10^{-7}$ 绝对容差，代价上升而残差曲线形态改变；反之若 tolerance 被放大到 $10^{-4}$，残差会提前走平，看起来"收敛更快"。

展开后回显才是实际生效值

foamDictionary 的 -entry 与 -value 组合直接从求解器使用的同一套解析器取值，因此它回显的内容就是运行时会读到的内容：

foamDictionary -entry nu -value constant/physicalProperties
foamDictionary -entry solvers/p/relTol -value system/fvSolution
foamDictionary -entry boundaryField/inlet/value -value 0/U
foamDictionary -expand system/controlDict > expanded.controlDict
foamDictionary -write-all -entry maxCo -value 0.6 system/controlDict

-expand 把 include 与变量全部展开后打印，是最直接的"实际配置"证据。最后一条 -write-all 会就地改写源文件，只在明确要固化成默认值时使用，评审场景下应避免——它会抹掉"这一行来自共享字典"的信息。

若回显值与源文件肉眼所见不同，先判断是覆盖还是回退。覆盖表现为展开文件里同一键出现两次且最后一次来自 include；回退表现为键在展开文件里完全缺席，foamDictionary -entry 会报该键未定义。

展开链的深度与环

一份字典可能经过多层 include。定义展开后的文件总数

$$n_{\text{exp}} = 1 + \sum_{i=1}^{m} n_i$$

其中 $m$ 是直接引用的文件数，$n_i$ 是第 $i$ 个文件自身再展开得到的文件数。controlDict 引用 3 个文件、其中 1 个又引用 2 个、另一个引用 1 个，则 $n_{\text{exp}} = 1+3+2+1 = 7$ 个文件参与构成最终配置。链深度超过 3 层时，人眼追踪覆盖关系已经不可靠，应当改为只保留一层共享（项目级）+ 一层个性化，并把中间层内容直接并入上一层。

环引用不会死循环——解析器会检测到并中止，报错信息通常指出无法解析的指令位置。但它常以"改了 A 文件却影响 B 算例"的形式间接表现，因此排查配置来源时应先 grep -rn "#include" system/ constant/ 0/ 画出引用图，再动手改。

参考资料

1. OpenFOAM Foundation, OpenFOAM User Guide, v14, Section 4.1 “Dictionaries” and “Include directives”.
2. OpenFOAM Foundation, OpenFOAM Programmer’s Guide, v14, Chapter on “Dictionaries and I/O”.
3. C. J. Greenshields, Notes on Computational Fluid Dynamics: General Principles, CFD Direct, 2022.
4. Weller, H. G., Tabor, G., Jasak, H., Fureby, C., “A tensorial approach to computational continuum mechanics using object-oriented techniques”, Computers in Physics, 12(6):620–631, 1998.
5. H. K. Versteeg, W. Malalasekera, An Introduction to Computational Fluid Dynamics: The Finite Volume Method, 2nd ed., Pearson, 2007.
6. IEEE, POSIX.1-2017 Standard for Information Technology — Portable Operating System Interface, IEEE Std 1003.1-2017, 2017.
7. OpenFOAM Foundation, OpenFOAM User Guide, v14, Section “Dictionary utilities” (foamDictionary).
8. J. H. Ferziger, M. Perić, R. L. Street, Computational Methods for Fluid Dynamics, 4th ed., Springer, 2020.
9. S. V. Patankar, Numerical Heat Transfer and Fluid Flow, Hemisphere Publishing, 1980.