OpenFOAM二次开发教程10湍流模型扩展实战——编译自己的 RAS 模型库版本与事实声明自定义库的安装位置约定来自官方插件仓库示例./Allwmake -prefixuser安装到$FOAM_USER_APPBIN与$FOAM_USER_LIBBIN对应Make/options中sinclude $(GENERAL_RULES)/module-path-user。kOmegaSST属Foam::RASModels命名空间kOmegaSSTLM官方说明见第 09 篇 references本文以复制并最小改动为方法主线。本系列不给出任何未经核验的类成员清单类名、构造签名、模板参数必须来自你本机安装版本的源码$FOAM_SRC/TurbulenceModels/。文中算例与系数均为示例回归对拍必须在你自己的算例上进行。一句话结论扩展湍流模型的最小可行路径是复制官方模型目录 → 改类名与TypeName→ 改Make/files/Make/options→wmake libso→ 在controlDict的libs中加载 → 字典type换名 → 与原模型同设置对拍编译产物必须落$FOAM_USER_LIBBIN库必须显式加载。〇、本篇要解决的认知问题Q1把一个官方湍流模型变成我自己的模型需要改哪几处哪些绝对不能动Q2Make/files与Make/options编译库时该怎么写与第 03 篇写求解器有何不同Q3wmake libso之后为什么运行还是报未知类型加载机制在哪里Q4怎么证明我改的模型跑起来和官方一致在没做实质改动时Q5改完之后如何干净地回滚、如何与团队共享这份扩展一、机制解析1.1 扩展的最小改动集改什么、不改什么复制一个官方 RAS 模型后有五处需要动还有三处绝对不能动必须改的5 处#改什么原因1目录名kOmegaSST→myKOmegaSST便于管理避免与系统源码混淆2类名与文件名.H/.C内类名C 同名类会与系统库符号冲突3TypeName(...)字符串工厂机制的类型名必须与字典type一致4Make/files的产物路径落$FOAM_USER_LIBBIN铁律 45需要自定制的逻辑这才是你真正想改的部分扩展的目的所在绝对不能动的3 处#不能动后果1基类的构造签名参数个数、类型、顺序编译或链接失败或无法与求解器对接2公共接口函数的名字与返回类型如correct()、nut()违反继承契约编译失败或行为缺失3#include的基类头除非你确实要换基类编译失败或语义错误为什么要这么严格OpenFOAM 的模型是通过基类指针 虚函数被求解器使用的。求解器只知道基类接口不认识你的类。你改坏了接口代码就无法被装进那个插槽里。1.2 编译库Make 文件与求解器的差异第 03 篇写求解器用的是可执行文件变量组本篇编译库用的是库变量组——两组变量不能混用这是第 02 篇埋下的坑这里闭环场景Make/files 产物Make/options 变量组编译命令求解器/工具可执行EXE $(FOAM_USER_APPBIN)/名字EXE_INC/EXE_LIBSwmake模型/库动态库LIB $(FOAM_USER_LIBBIN)/lib名字LIB_INC/LIB_LIBSwmake libso关键差异库的Make/files要列出所有需要编译的.C模型可能有多个源文件wmake libso生成共享库.so而不是可执行文件若模型是每个文件一个类的组织方式通常有若干.C与对应的.H官方插件仓库的做法是sinclude $(GENERAL_RULES)/module-path-user把产物路径规则对齐到用户目录。1.3 加载机制为什么会未知类型回到第 08 篇的工厂机制把它落到湍流模型上求解器启动 │ ├─ 读 system/controlDict → libs ( libmyKOmegaSST.so ) │ │ │ ▼ 动态加载这个 .so │ ┌──────────────────────────┐ │ │ 加载时执行静态注册 │ │ │ TypeName 注册进 RAS 类型表│ │ └──────────────────────────┘ │ ├─ 读 constant/momentumTransport → type myKOmegaSST │ │ │ ▼ └─ 在类型表里查 myKOmegaSST → 找到则构造对象 → 找不到则报 Unknown ... type结论库编译成功与类型可用是两件事。前者只说明.so生成了后者还要求求解器启动时加载了这个.so。这就是铁律 5的完整机制解释。最佳实践把 “自定义库清单 对应libs条目” 写进项目 README并在 CI 里检查controlDict的libs是否包含所有自定义库。批量跑算例时漏加载一个库会造成整批结果错误且只在特定模型被选中时暴露。1.4 验证为什么必须对拍铁律 7改完必验在模型扩展上的具体形式是对拍无实质改动的复制版 vs 官方版同一个算例、同一套fvSchemes/fvSolution两者结果应在容差内一致。不一致说明你复制过程中漏了东西或注册/加载错位。有实质改动的版本 vs 官方版差异应能用你改动的内容解释。无法解释的差异 bug。网格无关性检查至少两套网格确认结论与网格无关研究场景必备。为什么对拍如此重要湍流模型改错时的表现常常是数值稳定但物理偏差 5%。没有对拍你无法区分这是我的新物理还是这是我的 bug。1.5 回滚与共享把扩展做成可维护资产回滚因为是复制 改回滚只需删除用户库目录下的.so并把字典type改回官方名——永远不要修改系统源码否则回滚只能重装。共享把扩展库目录 一份libs片段 一份改动清单改了哪几处、为什么一起交付。没有改动清单的扩展库是不敢用的扩展库。版本绑定扩展库与 OpenFOAM 版本、WM_OPTIONS平台强绑定第 02 篇。交付时必须注明基于哪个版本、哪个平台编译。二、完整代码与逐行剖析代码 2-1扩展工程目录与 Make 文件myTurbulence/ # 用户扩展工程根目录放在你自己的代码仓库里 └── myKOmegaSST/ ├── myKOmegaSST.H # 头文件类声明复制的官方 .H 改名而来 ├── myKOmegaSST.C # 实现构造 correct()复制的官方 .C 改名而来 └── Make/ ├── files # 列出所有要编译的 .C 与产物库名 └── options # 头文件路径与要链接的库# ---------------- myKOmegaSST/Make/files ---------------- # 列出该库的所有源文件模型可能不止一个 .C按实际增删 myKOmegaSST.C # 产物动态库落用户库目录铁律 4 LIB $(FOAM_USER_LIBBIN)/libmyKOmegaSST# ---------------- myKOmegaSST/Make/options ---------------- # 库编译用 LIB_INC / LIB_LIBS不是 EXE_*第 02 篇的坑 # 用户模块路径规则官方插件仓库的约定做法保证产物落用户目录 sinclude $(GENERAL_RULES)/module-path-user LIB_INC \ -I$(LIB_SRC)/finiteVolume/lnInclude \ -I$(LIB_SRC)/meshTools/lnInclude \ -I$(LIB_SRC)/TurbulenceModels/turbulenceModels/lnInclude \ -I$(LIB_SRC)/TurbulenceModels/incompressible/lnInclude \ -I$(LIB_SRC)/transportModels/lnInclude \ -I$(LIB_SRC)/thermophysicalModels/basic/lnInclude LIB_LIBS \ -lincompressibleTurbulenceModels \ -ltransportModels \ -lfiniteVolume逐行剖析Make/files里LIB $(FOAM_USER_LIBBIN)/libmyKOmegaSST这是库的产物声明对比求解器的EXE ...。漏写LIB一行wmake libso不知道该生成什么。Make/options用LIB_INC/LIB_LIBS混用EXE_*会导致链接缺库第 02 篇的报错 3-2。sinclude $(GENERAL_RULES)/module-path-user来自官方插件仓库的做法用于把模块产物路径对齐到用户目录。sinclude的s表示文件不存在也不报错这是官方 Make 规则文件里的常见用法。LIB_INC里列出的是官方湍流与输运库的lnInclude目录具体需要哪些取决于你复制的模型依赖了哪些头文件——实践建议直接复制官方同族模型的Make/options再按编译报错增减报错会明确告诉你缺哪个头文件。LIB_LIBS里的库名如-lincompressibleTurbulenceModels随版本与发行线不同必须以本机官方同族模型的Make/options为准。这也是本文只给模板结构而非可复制即过清单的原因。代码 2-2库编译与加载的一站式脚本#!/bin/sh# build_and_load_turb.sh —— 编译扩展湍流库、在算例中加载、切换字典类型# 用法sh build_and_load_turb.sh 库源码目录 算例路径set-eulibdir${1:?用法:sh build_and_load_turb.sh 库源码目录 算例}case${2:?缺少算例路径}echo 1. 编译库 cd$libdirwmake libso# 编译共享库库用 libso不是普通 wmakels-l$FOAM_USER_LIBBIN/libmyKOmegaSST*2/dev/null\echo[OK] 库已生成于$FOAM_USER_LIBBIN\||{echo[FAIL] 未生成库请查看上方编译输出;exit1;}echo 2. 在算例 controlDict 的 libs 中加载铁律 5CD$case/system/controlDict# 用 foamDictionary 结构化改写避免破坏字典第 04 篇的工具# 若 libs 为空列表先 add 再 set若已存在则直接 setfoamDictionary-entrylibs-add-set( libmyKOmegaSST.so )$CD2/dev/null\||foamDictionary-entrylibs-set( libmyKOmegaSST.so )$CDecho 当前 libs:$(foamDictionary-entrylibs-value$CD2/dev/null||echo(读取失败))echo 3. 把 momentumTransport 字典的 type 切到自定义模型 # 注意字典文件名/路径随版本与发行线而异可能是 constant/momentumTransport 或# constant/turbulenceProperties 之类先探测存在的那个再改 type。MTforcandin$case/constant/momentumTransport$case/constant/turbulenceProperties;do[-f$cand]MT$candbreakdoneif[-z$MT];thenecho[WARN] 未找到动量输运/湍流字典请按你的版本确认文件名后手动设置 typeelseecho 使用字典:$MTfoamDictionary-entryRAS.type-setmyKOmegaSST$MT2/dev/null\||foamDictionary-entrysimulationType-value$MT||trueecho 当前 type:$(foamDictionary-entryRAS.type-value$MT2/dev/null||echo(请手动核对))fiecho 4. 提示模型字典块 echo 请确认该字典中存在 myKOmegaSST 的系数块可复制官方模型的同名块再改名逐行剖析wmake libso库的专用编译命令。用错成wmake可能不生成共享库导致加载失败。第 1 步用ls -l $FOAM_USER_LIBBIN/libmyKOmegaSST*做产物存在性硬判据铁律 4。第 2 步用foamDictionary改libs-add -set先尝试新增、失败则-set这是兼容不同版本行为差异的稳妥写法第 04 篇同一技巧。第 3 步探测字典文件名momentumTransport或turbulenceProperties因为该字典的文件名与层级在不同版本/发行线中确实存在差异硬编码一个名字会让脚本在一半环境下失效。这是不臆造路径的工程体现。foamDictionary -entry RAS.type -set myKOmegaSST用点号路径精确修改嵌套子字典里的type不影响其他键——这正是第 04 篇强调foamDictionary优于sed的场景。第 4 步只做提示不做自动改因为系数块的必需项取决于你的模型实现脚本无法臆断留给人工核对更安全。代码 2-3对拍验证脚本核心回归#!/bin/sh# crosscheck_turb.sh —— 同设置对拍自定义模型 vs 官方模型# 用法sh crosscheck_turb.sh 算例路径 官方type名 自定义type名set-eucase${1:?用法:sh crosscheck_turb.sh 算例 官方type 自定义type}official${2:?缺少官方 type如 kOmegaSST}custom${3:?缺少自定义 type如 myKOmegaSST}MTforcandin$case/constant/momentumTransport$case/constant/turbulenceProperties;do[-f$cand]MT$candbreakdone[-n$MT]||{echo[FAIL] 未找到动量输运字典;exit1;}run_case(){label$1;tname$2# 复制算例隔离两次运行不污染原始算例铁律 7work${case}_run_${label}rm-rf$work;cp-r$case$work# 切换模型类型foamDictionary-entryRAS.type-set$tname$work/constant/$(basename$MT)2/dev/null||truecd$workmySolver-case.log.${label}21||echo[WARN]$label运行异常见 log.${label}# 抽取一个可观测量作为对拍指标示例末态日志中的某个统计行grep-iESolving for U|ExecutionTime|nutlog.${label}|tail-n3metric.${label}.txt||truecd-/dev/nullecho [$label] 记录:$work/metric.${label}.txt}echo 运行官方模型 run_case official$officialecho 运行自定义模型 run_case custom$customecho 对拍提示 echo 1) 若自定义模型是‘无实质改动的复制’两个 metric 文件应基本一致echo 2) 若存在差异差异必须能被你的改动解释否则视为 bugecho 3) 强建议再用两套网格重复确认结论与网格无关。逐行剖析run_case每次都复制算例再跑这是对拍的前提——两次运行必须在独立目录、独立字典下进行否则互相污染铁律 7。抽取可观测量这里的示例是日志行作为对拍指标对拍必须有客观指标。实际项目中更硬的做法是让 function object 输出监测点的 CSV第 12、17 篇再做数值比较。脚本末尾三条提示明确了无实质改动应一致“差异必须可解释”网格无关性三层验证——把方法论写进脚本的提示里是对团队的隐性培训。三、常见报错与排查报错 3-1-- FOAM FATAL ERROR: Unknown momentumTransport type myKOmegaSST即使编译成功。现象库生成了运行仍报未知类型。根因controlDict的libs未加载你的库铁律 5或加载的库名与实际生成的文件名不一致lib前缀、.so后缀容易写错。解法ls $FOAM_USER_LIBBIN确认实际文件名把libs写成同名如libmyKOmegaSST.so再核对字典type与TypeName是否逐字符一致。报错 3-2undefined reference to ...链接失败。现象编译库时链接报错。根因Make/options的LIB_LIBS缺库或误用了EXE_LIBS变量名库应使用LIB_*组。解法对照官方同族模型的Make/options逐行补齐确认变量名正确。另需注意WM_OPTIONS平台不一致也会引发此类错误第 02 篇。报错 3-3fatal error: xxx.H: No such file or directory。现象编译找不到头文件。根因LIB_INC缺少某个lnInclude路径。解法把编译输出里提到的缺失头文件名拿去find $FOAM_SRC -name 名字.H定位把其所在库的lnInclude加进LIB_INC。这是最机械也最快的解决方式。报错 3-4库加载了、模型选中了但湍流量不更新。现象日志显示选中了模型但k/omega数值始终不变。根因求解器没调用correct()第 09 篇的反直觉点或你在重写correct()时没有调用基类实现导致更新逻辑被跳过。解法确认求解器在动量方程前有turbulence-correct();若覆盖了correct()确认是否需要在合适位置调用基类版本以本机源码契约与官方同族模型为准。报错 3-5换回官方模型后仍然报错怀疑环境坏了。现象把字典type改回官方名后仍失败。根因libs里还加载着你的库且该库可能与系统库符号冲突例如你没有彻底改名类名与系统类同名。解法从libs中移除自定义库后测试确认你的类名、TypeName、文件名都已彻底改名。这也是必须改名这条纪律的实战意义。四、动手练习练习 1复制与改名复制一个官方 RAS 模型目录完成目录名、类名、文件名、TypeName四处改名。判定grep -rn 旧类名 .在你的工程目录内零命中说明改名彻底TypeName字符串与新类名一致。练习 2编译成库写好Make/files与Make/options执行wmake libso。判定命令成功$FOAM_USER_LIBBIN下出现libmyKOmegaSST*.so产物不在系统库目录铁律 4。练习 3加载与切换运行代码 2-2把库加载进controlDict的libs并把字典type切到自定义名。判定求解器日志中出现模型选择记录且不再报Unknown ... type用foamDictionary -entry libs -value能看到库条目。练习 4对拍运行代码 2-3 做无实质改动的复制版 vs 官方版对拍。判定两次运行的可观测量差异在合理容差内工程常取 1%~5%按问题自定若差异大能定位到复制时漏改了哪一处或加载错位。练习 5思考题无标准答案设计一个给现有 SST 模型加一个系数开关新字典项“的最小改动方案。验证要点(a) 是否只改类实现而不动基类构造签名(b) 是否为新字典项设置了合理默认值无该键时仍能运行© 是否更新了write()之类的配置回写以保持可复现(d) 是否用对拍验证开关关闭时与官方一致”。五、小结与下一篇预告本篇把第 09 篇的架构落地成可运行的扩展五处改名目录/类名/文件/TypeName/产物路径、库变量组LIB_INC/LIB_LIBSwmake libso 产物落$FOAM_USER_LIBBIN、加载机制controlDict的libs否则报未知类型、对拍验证无实质改动应在容差内一致、可维护性永不改系统源码、交付带改动清单与版本绑定说明。第 11 篇《自定义边界条件》将转向接口扩展的另一条主线从fvPatchField派生自定义边界场类并用字典内嵌代码的codedFixedValue做快速原型——那是把壁面/入口的特殊物理变成可复用部件的必经之路。本篇认知问题回显FAQQ1把官方湍流模型变成自己的模型需要改哪几处哪些不能动A必须改五处目录名、类名与文件名.H/.C 内的类名、TypeName 字符串须与字典 type 一致、Make/files 的产物路径落 FOAM_USER_LIBBIN、以及你真正想定制的逻辑。绝对不能动三处基类的构造签名参数个数、类型、顺序公共接口函数的名字与返回类型如 correct()、nut()以及基类头文件 include除非确实要换基类。原因在于 OpenFOAM 通过基类指针与虚函数使用模型求解器只认基类接口改坏接口会导致无法编译或无法被装载。Q2编译库的 Make 文件与求解器有何不同A两者使用两组不同变量。求解器是可执行文件Make/files 用EXE $(FOAM_USER_APPBIN)/名字Make/options 用 EXE_INC/EXE_LIBS命令为 wmake。库用LIB $(FOAM_USER_LIBBIN)/lib名字Make/options 用 LIB_INC/LIB_LIBS并常 sinclude $(GENERAL_RULES)/module-path-user 对齐用户路径命令为 wmake libso 生成 .so 共享库。库的 Make/files 需列出所有要编译的 .C。混用两组变量不会立即报错但会在链接期缺库。Q3wmake libso 成功了为什么运行还报未知类型A因为库编译成功与类型可用是两件事。类型注册发生在库被动态加载时而加载由 system/controlDict 的 libs 条目控制。若 libs 中未列出你的库或列出的库名与实际文件名不一致如漏写 lib 前缀或 .so 后缀运行期类型表中就没有你的类型名于是报 Unknown … momentumTransport type。这就是自定义库必须显式加载铁律 5的完整机制排查时先 ls $FOAM_USER_LIBBIN 确认实际文件名。Q4怎么证明改的模型与官方一致A做同设置对拍。把自定义模型未做实质改动与官方模型在同一算例、同一套 fvSchemes/fvSolution 下分别运行抽取一个可观测量如监测点速度、壁面剪应力或 function object 输出的 CSV 统计量比较差异应在合理容差内工程常取 1%~5%按问题自定。对拍必须在独立复制的算例目录中进行以避免互相污染。有实质改动的版本则要求差异能被改动解释无法解释的差异视为 bug并建议用至少两套网格重复以确认结论与网格无关。Q5如何回滚与共享这份扩展A因为采用复制 改而非修改系统源码回滚只需删除 $FOAM_USER_LIBBIN 下的对应 .so并把字典 type 改回官方名即可修改系统源码则只能重装因此绝不能污染系统目录。共享时交付三样扩展库源码目录、一份 controlDict 的 libs 片段、一份改动清单改了哪几处及原因。同时必须注明该库绑定的 OpenFOAM 版本与 WM_OPTIONS 平台标识因为扩展库与版本及平台强绑定跨平台或不一致版本使用会导致链接失败。
