OpenFOAM二次开发教程01OpenFOAM 全景——开源 CFD 事实标准与二次开发的五条通道版本与事实声明本系列版本锚点取自同目录《00-实施计划.md》登记表OpenFOAM Foundation 版当前v142026-07-14 发布历史锚点 v13/v12/v11/v10OpenCFD/ESI 版当前v26062026-06-26历史锚点 v2512/v2506。两条发行线独立编号、各自维护正文凡涉及差异处一律双写并注明来源严禁混用。本系列所有类名、命令名、字典键均以官方 Doxygencpp.openfoam.org/api.openfoam.com与官方文档站doc.openfoam.com、官方用户指南为准检索未能确证的细节一律标注以官方文档/源码为准不做臆断。官方源码自 2025-11-04 起托管于 GitLabgitlab.com/openfoam。OpenFOAM 采用 GNU GPL v3 许可可私有与商用但衍生分发须遵守 GPL——这是二次开发必须牢记的法律前提。一句话结论OpenFOAMOpen-source Field Operation And Manipulation是采用 GNU GPL v3 的 C CFD 工具箱分 OpenFOAM Foundation 版openfoam.org当前 v14与 OpenCFD/ESI 版openfoam.com当前 v2606两条独立发行线它的二次开发只有五条真实通道——求解器开发、模型扩展湍流/物性、接口扩展边界/函数对象/fvModels、并行与性能、Python 工作流——所有通道的共同起点都是读官方源码与 Doxygen而不是猜 API。〇、本篇要解决的认知问题开始之前先带着这五个问题读完全篇——文末 FAQ 会逐一自包含地回答。Q1OpenFOAM 到底是什么开源这件事对二次开发意味着什么与商业 CFD 的定制方式有何本质不同Q2OpenFOAM Foundation 版openfoam.org与 OpenCFD/ESI 版openfoam.com有什么区别为什么教程必须先把版本线说清楚Q3OpenFOAM 安装目录里src、applications、tutorials、etc、doc各是什么二次开发应该在哪个目录动刀Q4二次开发的五条通道分别是什么各自的能力边界与主要风险在哪里Q5什么样的人适合学 OpenFOAM 二次开发本系列的学习路径如何安排一、机制解析1.1 身份与许可为什么开源是最大的定制红利官方文档对名字的解释是OpenFOAM 代表 “Open-source Field Operation And Manipulation”开源场运算与操作它是一个免费开源的连续介质力学软件用C编写采用GNU GPL v3许可公开托管在 GitLab 上并由 OpenCFD Ltd 持续开发维护。对你意味着什么——这里有三条硬结论请务必记住源码就是文档。商业 CFD 的定制只能靠厂商开放的 UDF 接口边界在哪由厂商画OpenFOAM 的定制深度几乎没有上限——你可以改求解器、改离散格式、改湍流模型、改边界条件因为源码全在$WM_PROJECT_DIR里。API 可被逐行核验。本系列的每一条类名/方法名都能在官方 Doxygen 或源码里找到出处铁律 1网上抄来的某函数如果源码里不存在就是编的。GPL 是双刃剑。自用、公司内部用没问题一旦对外分发你的衍生版本就要遵守 GPL 的源码开放义务。企业做产品级封装前务必先过法务。1.2 两条发行线先把版本线说清楚这是新手最容易踩的第一个坑也是本系列贯穿始终的纪律铁律 3维度OpenFOAM Foundation 版OpenCFD/ESI 版主页openfoam.orgopenfoam.com出品方OpenFOAM Foundation / CFD DirectOpenCFD LtdESI Group 体系编号体系整数序号v10、v11、v12、v13、v14当前2026-07-14年月编号v2506、v2512、v2606当前2026-06-26官方 API 文档cpp.openfoam.org/版本/api.openfoam.com/版本/官方文档站用户指南doc.cfd.direct/openfoam/user-guide-版本/等综合文档站doc.openfoam.com/版本/下载dl.openfoam.orgdl.openfoam.com典型特征追求稳定、语义清晰v14 重写了燃烧求解器 XiFluid、引入模块化拉格朗日与内建单位系统集成度高较早提供统一求解器foamRun与完整文档站为什么必须分开讲同一个功能两条线的版本号、命令名、甚至字典键都可能有差异。举个例子foamRun这条统一求解器入口在 Foundation 的 v13 API 文档中已明确记载“Loads and executes an OpenFOAM solver module either specified by the optionalsolverentry in thecontrolDictor as a command-line argument”而 ESI 线也有自己的引入时间点。写教程时混用两线的版本号等于给读者埋了一颗必炸的雷。本系列的写法是示例优先给两线公共语法差异处双写。提示查看任一官方 API 版本页的左上角Versions列表就能看到该线所有已发布版本Foundation 侧 v14 页会列出 OpenFOAM-dev 与 Version 14/13/12/11/10/9/8/7/6。这是核对版本最省事的方法。1.3 目录结构二次开发的地形图官方文档说明 OpenFOAM 由四个主目录构成加上平台与文档目录就是你的作战地图$WM_PROJECT_DIR/ # 安装根目录环境变量指向它 ├── src/ # 核心库源码finiteVolume、mesh、thermophysicalModels、 │ # TurbulenceModels、fvModels、functionObjects ... ├── applications/ # 应用solvers求解器、utilities工具、modules模块 ├── tutorials/ # 官方算例库一切回归验证的基准铁律 7 ├── etc/ # 配置文件controlDict/boundary 模板、bashrc、config 等 ├── doc/ # 文档与 Doxygen 入口 ├── platforms/ # 编译产物按 编译器精度并行 命名的平台目录 ├── wmake/ # 官方构建系统wmake 规则所在 └── bin/ # 可执行脚本foamRun、foamToC、foamDictionary、foamEtcFile 等三条去哪里的规则记住就能少走半年弯路想改求解器/模型/边界去src/找基类去applications/找现成实现想验证你改得对不对去tutorials/找最接近的官方案例铁律 7改完必验想查环境变量与编译规则去etc/与wmake/。用户自己的东西则统一写到$FOAM_USER_APPBIN自己的求解器可执行文件与$FOAM_USER_LIBBIN自己的库——这是铁律 4第 02 篇会实测这两个变量。1.4 五条二次开发通道把能改什么摊开OpenFOAM 的二次开发恰好是五条互不重叠、难度递进的通道通道一求解器开发。从求解器骨架setRootCase.H/createTime.H/createMesh.H/createFields.H起步用fvMatrix装配方程再solve()。这是 OpenFOAM 最核心的能力也是本系列第 3、5、6、7 篇的主线。风险是容易把物理写错当成代码写错必须配回归验证。通道二模型扩展。湍流模型RASModel/eddyViscosity/kOmegaSST与热物性模型hConst/hPolynomial/janaf都是工厂 派生类结构扩展方式统一派生新类 编译成库 在字典里选类型。对应第 8、9、10 篇。通道三接口扩展。自定义边界条件从fvPatchField派生或用字典内嵌代码的codedFixedValue快速原型、函数对象functionObjects框架、运行期源项与约束fvModel/fvModels/fvConstraints。对应第 11、12、13 篇。通道四并行与性能。域分解decomposePar/decomposeParDict、重构与再分布reconstructPar/redistributePar、并行 IOfileHandler、线性求解器调优、编译与 MPI 优化。对应第 14、15 篇。通道五Python 工作流。用foamlib等 Python 包读写字典与场、批量克隆算例、驱动参数扫描、用pandas/pyvista聚合与可视化。这条通道不改 C只改怎么用但对科研产出效率提升最快。对应第 16~19 篇。1.5 决策表通道 × 能力 × 风险通道官方依据能做什么主要风险适合场景求解器开发applications/solvers源码 Doxygen实现自有控制方程、耦合物理物理与代码错误混淆无回归极易无声出错新物理模型、算法研究模型扩展src/TurbulenceModels、src/thermophysicalModels加湍流模型、加物性继承契约不满足如未实现correct()导致运行期崩论文模型落地、专用工质接口扩展src/finiteVolume/fields/fvPatchFields、src/functionObjects、src/fvModels自定义边界、在线统计、运行期源项字典键拼写/类型名不匹配、库未加载铁律 5工程化改造现有算例并行与性能doc.openfoam.com/.../parallel/大规模并行、加速手改 processor 目录铁律 6 禁止、IO 瓶颈亿级网格、批量长时运行Python 工作流PyPIfoamlib等批量管理、后处理、报表版本与文件格式漂移、把 Python 当万能胶忽略物理DOE、参数扫描、交付选择逻辑能靠字典解决的不写 C能靠函数对象解决的不改求解器能靠 Python 编排的不写 shell 意大利面。每往上走一层维护成本与出错概率都显著上升。1.6 学习路径本系列怎么读本系列遵循入门1–4→ 核心5–8→ 进阶9–12→ 高级13–15→ 实战16–20的递进01 全景 ── 02 环境 ── 03 第一个求解器 ── 04 字典与 case │ 05 场/网格对象 ── 06 离散与方程装配 ── 07 自定义标量输运求解器 ── 08 物性模型 │ 09 湍流架构 ── 10 自定义湍流库 ── 11 自定义边界条件 ── 12 函数对象 ── 13 fvModels/约束 │ 14 并行与域分解 ── 15 性能优化 │ 16 Python(一) ── 17 Python(二) ── 18 网格流水线 ── 19 DOE 自动化 ── 20 工具链收官如果你是只想跑算例的工程师先读 01–04、16–19如果你是要做模型开发的科研人员01–13 必须逐篇动手。二、完整代码与逐行剖析本篇的代码任务很明确先把地形摸清楚。第一段 Shell 脚本测绘版本与环境第二段 Python 脚本做一件二次开发前必做的体检——确认官方算例库可达因为它是你的回归基准。代码 2-1环境与版本测绘POSIX ShellOpenFOAM 环境已 source#!/bin/sh# probe_env.sh —— OpenFOAM 环境测绘版本线、根目录、用户目录、算例库# 用法source OpenFOAM 安装目录/etc/bashrc 之后执行 sh probe_env.sh# 说明本脚本只读环境变量不做任何修改任何机器上可安全运行。echo 1. 版本信息 # WM_PROJECT_VERSION 是版本号的规范来源Foundation 侧形如 14ESI 侧形如 v2606# 注意不要用 foamVersion 之类未在官方文档中确证的变量名去猜直接用下面的变量。echoWM_PROJECT ${WM_PROJECT:-未设置}echoWM_PROJECT_VERSION ${WM_PROJECT_VERSION:-未设置}echoWM_PROJECT_DIR ${WM_PROJECT_DIR:-未设置}echo 2. 关键源码/应用路径 # FOAM_SRC 指向核心库源码FOAM_APP 指向 applicationsFOAM_TUTORIALS 指向官方算例库。# 这三个变量是第 02~19 篇反复使用的“地图坐标”。forvinFOAM_SRC FOAM_APP FOAM_TUTORIALS FOAM_ETC;doevalval\${$v:-未设置}echo$v$valdoneecho 3. 用户目录铁律 4自定义产物只落这里# FOAM_USER_APPBIN 放自己编译的求解器/工具FOAM_USER_LIBBIN 放自己编译的库。forvinFOAM_USER_APPBIN FOAM_USER_LIBBIN;doevalval\${$v:-未设置}echo$v$valdoneecho 4. 官方算例库可达性回归基准# tutorials 是铁律 7改完必验的弹药库必须可达。if[-d${FOAM_TUTORIALS:-/nonexistent}];thenn$(find$FOAM_TUTORIALS-maxdepth2-namesystem-typed2/dev/null|wc-l)echo[OK] FOAM_TUTORIALS 可达二级子目录中含 system 的算例约$n个elseecho[FAIL] 找不到 FOAM_TUTORIALS请先正确 source OpenFOAM 的 etc/bashrcfi逐行剖析WM_PROJECT_VERSION是版本号的规范来源Foundation 侧形如14、ESI 侧形如v2606——光看这一行就能判定读者在用哪条发行线这是本系列所有版本相关排查的第一步。之所以强调不要猜变量名OpenFOAM 的环境变量有约定俗成的命名体系WM_*是项目级FOAM_*是路径级凡是没在官方文档或etc/bashrc里出现过的名字都不要写进脚本铁律 1。FOAM_SRC/FOAM_APP/FOAM_TUTORIALS/FOAM_ETC四个路径正好覆盖改哪里的代码、拿哪里的算例验证、查哪里的配置三件事是后续 19 篇的公共坐标。FOAM_USER_APPBIN/FOAM_USER_LIBBIN反复出现因为铁律 4 要求所有自定义编译产物只落这里——系统目录被覆盖后一次升级就会把你所有工作清零。tutorials 的可达性检查用find -maxdepth 2 -name system -type dOpenFOAM 算例的判定标志是目录里有system子目录这就是第 04 篇要讲的 case 结构的最小特征。脚本用eval间接取值是为了在 POSIXsh里安全地做变量名→值的映射用set -u的读者请注意这里已对未设置变量做了未设置兜底。代码 2-2官方文档站可达性自检Python可直接运行# -*- coding: utf-8 -*- check_docs.py —— 离线核验本系列 references 中官方 URL 的可达性 用途二次开发前确认“查文档”这条腿能走通断网/内网环境会全部 FAIL属预期行为。 运行python check_docs.py 依赖仅标准库 urllib无需第三方包 importurllib.request# (标签, URL) —— 全部取自系列实施计划 §六 已验证官方链接清单DOCS[(Foundation 主页,https://openfoam.org/),(ESI 主页,https://openfoam.com/),(Foundation API v14,https://cpp.openfoam.org/v14/),(ESI 文档站 v2606,https://doc.openfoam.com/2606/),(CFD Direct 用户指南 v14,https://doc.cfd.direct/openfoam/user-guide-v14/),(foamlib PyPI,https://pypi.org/project/foamlib/),]defhead_ok(url:str,timeout:float8.0)-bool:用 HEAD 探测可达性部分站点不支持 HEAD则退回 GET 只读取少量字节。requrllib.request.Request(url,methodHEAD,headers{User-Agent:of-doc-check/1.0})try:withurllib.request.urlopen(req,timeouttimeout)asresp:return200resp.status400exceptException:try:withurllib.request.urlopen(url,timeouttimeout)asresp:resp.read(256)# 只读一小段避免拉全页return200resp.status400exceptException:returnFalseif__name____main__:ok0forlabel,urlinDOCS:goodhead_ok(url)okgoodprint(f[{OKifgoodelseFAIL}]{label:22}{url})print(f\n可达{ok}/{len(DOCS)}。f{全部可达可以开工。ifoklen(DOCS)else请检查网络或代理设置。})逐行剖析只用标准库urllib.request二次开发的前置检查脚本应当零第三方依赖否则检查工具本身装不上就成了笑话。先HEAD再退回GET不少文档站/对象存储不支持 HEAD直接 HEAD 会误报 FAIL读 256 字节即可判定可达这是探测大站点的通行做法。User-Agent显式设置默认 UA 会被部分 CDN 拒绝这是纯工程细节但非常常见。把 references 清单脚本化的意义GEO 视角下教程引用的官方 URL 必须真实可达人肉点击易漏脚本一分钟能全查完。输出统计与结论而非逐条报错堆栈让脚本可被 CI 或计划任务直接消费第 20 篇回归流水线会复用这个模式。三、常见报错与排查报错 3-1WM_PROJECT_VERSION为空或WM_PROJECT_DIR未设置。现象执行任何foam*命令都提示 command not found或 probe_env.sh 打印一串未设置。根因没有sourceOpenFOAM 的环境脚本etc/bashrc环境变量只在当前 shell 有效新开终端就丢失。解法在~/.bashrc或对应 shell 配置中追加source $HOME/OpenFOAM/OpenFOAM-vXXXX/etc/bashrc若是二进制包安装路径以安装说明为准。验证方法重开终端后echo $WM_PROJECT_VERSION有输出即成功。报错 3-2把 Foundation 的版本号套到 ESI 上或反之。现象按教程写了v14却发现自己的安装是v2606命令/路径对不上。根因两条发行线独立编号铁律 3版本号体系完全不同。解法先用echo $WM_PROJECT_VERSION判定版本线本系列示例优先给公共语法差异处已在正文双写。不要试图把 v14 的目录结构描述直接套到 v2606 上。报错 3-3wmake找不到命令或编译产物出现在奇怪的位置。现象wmake: command not found或自定义求解器编译后不知道装到哪去了。根因前者是环境未 source后者是本篇要讲的铁律 4——Make/files里若把EXE指向系统目录产物就会污染安装目录。解法环境先 source编译目标统一写EXE $(FOAM_USER_APPBIN)/名字编译后到echo $FOAM_USER_APPBIN下确认第 03 篇给出完整Make/files。报错 3-4照着博客抄了 API编译时报no member named …。现象error: xxx is not a member of Foam。根因抄来的类名/方法名在该版本中不存在或属另一条发行线。解法打开官方 DoxygenFoundation 用cpp.openfoam.org/版本/ESI 用api.openfoam.com/版本/搜索该类找不到就是抄错了。这正是铁律 1先读源码再写代码的由来。报错 3-5GPL 疑虑——“我改的代码能不能给客户”现象公司要求把定制求解器作为闭源产品的一部分交付。根因OpenFOAM 采用 GNU GPL v3对外分发衍生作品须遵守 GPL 的开源义务内部自用不受此限。解法内部使用无需担心对外分发前请走法务评估或考虑服务化不分发二进制、只提供服务等合规路径。本系列只提示法律边界不提供法律意见。四、动手练习练习 1环境测绘在已 source 的终端里运行代码 2-1。判定WM_PROJECT_VERSION有非空输出且能据此明确判定自己用的是 Foundation 线还是 ESI 线FOAM_TUTORIALS显示可达。练习 2版本线判定写下你机器上的三个值WM_PROJECT_VERSION、FOAM_SRC、FOAM_USER_APPBIN。判定版本号形态整数 或 v年月与发行线自洽三条路径均非空。练习 3文档可达运行代码 2-2。判定在可联网环境下 6/6 可达若失败能说明是网络原因而非 URL 写错用浏览器手工打开同一 URL 交叉验证。练习 4地图实操用命令列出$FOAM_APP/solvers下的子目录名不同版本可能分层也可能集中在applications/solvers并任选一个求解器磁盘上找到它的.C与Make/目录。判定能报出至少 5 个求解器名与其源码路径能指出该求解器的.C、Make/files、Make/options三个文件的实际位置。练习 5思考题无标准答案对照 §一.5 决策表写下你自己工作中最想自动化的一件 CFD 任务属于哪条通道以及为什么不应越级例如为什么不该为了批量改入口速度就去改求解器源码。验证方向(a) 是否能用已有字典键或函数对象实现(b) 是否真的需要 C© 是否能用第 16~19 篇的 Python 编排完成。五、小结与下一篇预告本篇立起了四根柱子身份柱OpenFOAM GPL v3 的开源连续介质力学工具箱源码即文档、版本柱Foundation v14 与 ESI v2606 两条独立发行线严禁混写、地形柱src/applications/tutorials/etc/wmake的职责与自定义产物落用户目录的铁律 4、通道柱求解器、模型、接口、并行性能、Python 工作流五条通道及其风险账。请把两条纪律刻进肌肉记忆先读源码再写代码铁律 1与改完必验铁律 7。第 02 篇《环境与工具链》将把这句口号变成操作逐一实测环境变量、用foamToC做模型自省、并教你把官方 Doxygen 当地图用来定位任何一个基类——那是后续所有代码能够顺利编译的前提。本篇认知问题回显FAQQ1OpenFOAM 是什么开源对二次开发意味着什么AOpenFOAMOpen-source Field Operation And Manipulation是采用 GNU GPL v3 的 C 连续介质力学/CFD 工具箱源码公开托管于 GitLabgitlab.com/openfoam。开源意味着定制深度几乎无上限求解器、离散、湍流模型、边界条件、函数对象都能改且每个 API 都可在官方 Doxygen 或源码中核验代价是对外分发衍生版本须遵守 GPL 的开源义务企业封装前需法务评估。Q2OpenFOAM Foundation 版和 OpenCFD/ESI 版有什么区别A两者是各自独立编号的发行线。OpenFOAM Foundation 版由 openfoam.org / CFD Direct 维护用整数版本号当前为 v142026-07-14 发布API 文档在 cpp.openfoam.orgOpenCFD/ESI 版由 openfoam.com / OpenCFD Ltd 维护用年月编号当前为 v26062026-06-26API 文档在 api.openfoam.com、综合文档站在 doc.openfoam.com。两条线的版本号、命令名与部分字典键可能有差异教程必须分别标注适用版本线。Q3OpenFOAM 的目录结构是怎样的二次开发该在哪里动刀A主目录包含 src核心库源码如 finiteVolume、TurbulenceModels、fvModels、applicationssolvers 求解器、utilities 工具、modules 模块、tutorials官方算例库回归验证基准、etc配置、doc文档、platforms编译产物、wmake构建系统。改求解器/模型/边界去 src 找基类、applications 找实现用 tutorials 验证改动自定义编译产物写入 FOAM_USER_APPBIN 与 FOAM_USER_LIBBIN不污染系统目录。Q4OpenFOAM 二次开发的五条通道是什么各自风险在哪A一是求解器开发用 fvMatrix 装配并求解方程风险是物理与代码错误混淆二是模型扩展派生湍流模型如 kOmegaSST、热物性模型如 hConst/janaf风险是继承契约未满足三是接口扩展自定义 fvPatchField 边界、functionObjects 函数对象、fvModels/fvConstraints 源项与约束风险是类型名或字典键不匹配、库未加载四是并行与性能decomposePar/redistributePar、线性求解器与编译调优风险是手改 processor 目录破坏数据一致五是 Python 工作流foamlib 等驱动批量算例与后处理风险是文件格式漂移与忽视物理。Q5本系列的学习路径如何安排A按入门01 全景、02 环境、03 第一个求解器、04 字典与 case 结构、核心05 场与网格对象、06 有限体积离散与 fvMatrix、07 自定义标量输运求解器、08 物性模型、进阶09 湍流架构、10 自定义湍流库、11 自定义边界条件、12 函数对象、13 fvModels/fvConstraints、高级14 并行与域分解、15 性能优化、实战16~17 Python 前后处理、18 网格流水线、19 DOE 自动化、20 工具链收官五阶段递进。只跑算例的工程师可读 01–04 与 16–19做模型开发的读者应 01–13 逐篇动手。
