OpenFOAM CFD（孔隙尺度流动模拟）插件用户手册

OpenFOAM CFD - User Manual

Dragonfly Prototype Apps · OpenFOAM CFD...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

OpenFOAM CFD 插件让您直接在 Dragonfly 中，对已分割的三维数据运行孔隙尺度的计算流体动力学（CFD）模拟。您选择一个用于描述固体/孔隙结构的 ROI、MultiROI 或 Channel 对象，设定流动方向以及网格和求解器选项，插件即会自动对孔隙（空隙）相划分网格，并求解定常、不可压缩、层流流动。计算得到的速度场和压力场会作为 Channel 导入回场景，同时给出估算的达西（Darcy）渗透率。

底层计算引擎为开源 OpenFOAM（v2412，ESI 版本，来自 conda-forge）。整条流水线的关键步骤是：从所选对象读取固体掩膜，用 marching cubes（移动立方体，scikit-image） 提取固体表面并生成 STL 曲面；用 blockMesh 生成背景网格，用 snappyHexMesh 在固体周围雕刻出孔隙空间并把颗粒表面设为壁面；再用 simpleFoam（定常不可压缩层流求解器）求解流场；最后把速度/压力采样回原体素网格，并根据入口流量与进出口压降计算达西渗透率。

重要说明：CFD 计算不在 Dragonfly 自带的 Python 中运行。 插件把所选结构导出为固体掩膜文件，交给一个专用的 Linux（WSL2）计算环境去完成繁重的网格划分与求解；Dragonfly 仅负责准备输入、显示进度日志、以及最终把结果作为 Channel 导入。这样既避免了污染 Dragonfly 的运行环境，又能充分利用成熟的 OpenFOAM 工具链。

许可证要点： OpenFOAM 是开源软件（GPL 许可）。本插件通过随附的 WSL2 计算镜像调用 OpenFOAM，不修改其源代码。请遵循 OpenFOAM 各自的开源许可条款。

2. 适用场景

本插件面向数字岩石物理和多孔介质研究，尤其适合基于显微 CT（micro-CT）数据、希望从分割图像而非实体流动实验中获得流场和输运特性的工作流程。

• 估算岩石、土壤、砂岩等地质样品的渗透率；
• 研究膜材料、过滤器、泡沫、堆积床（packed bed）的流动阻力与孔隙连通性；
• 评估电池电极、催化剂载体、支架（scaffold）等多孔功能材料的输运性能；
• 分析增材制造点阵结构（AM lattice）的通流能力；
• 任何需要“从一张分割好的三维图像直接得到速度场、压力场和渗透率”的材料科学或地球科学任务。

本插件求解的是层流、不可压缩、定常流动，适用于孔隙尺度低雷诺数（缓慢）流动。它不用于湍流、可压缩流、瞬态或多相流分析。

3. 安装与启用

本插件随 Prototype Labs 完整安装包（Full Package） 一起分发。安装分为两部分：一次性安装 Dragonfly 插件本体（面板），以及一次性导入 OpenFOAM 的 WSL2 计算镜像（见第 4 章）。

3.1 通过完整安装包安装插件

1. 把完整安装包解压到一个较短的目录（例如 C:\PL\），避免路径过长报错。

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式（Fresh 全新 / Compatible 兼容），并在 Prototype Apps 列表中勾选 “OpenFOAM CFD”。默认情况下所有插件均为未勾选状态，需要您手动勾选后才会部署。

4. 点击 Install，等待控制台完成。

5. 完全退出并重启 Dragonfly（菜单只在启动时扫描）。

重启后，插件出现在菜单：Prototype Apps ▸ OpenFOAM CFD...（位于 “Simulation & Meshing / 仿真与网格” 分组）。点击后打开一个可自由移动、可缩放的浮动窗口。

3.2 以后修改勾选（Menu Item Manager）

如需以后启用或停用本插件，最方便的方式是在 Dragonfly 内操作：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部的 “Prototype Apps (Full Package)” 列表里勾选/取消 “OpenFOAM CFD”，然后重启 Dragonfly 生效。

停用插件从不删除已导入的 WSL 计算环境；重新启用后立即可用，无需再次导入镜像。

4. 运行环境与首次配置

OpenFOAM 需要在 Linux 下运行。本插件把整套 OpenFOAM 环境打包成一个 WSL2 应用镜像（appliance），您只需一次性双击导入即可，无需自己编译 conda 环境或联网下载。

4.1 前置条件

• Windows 10 / 11（64 位）；
• 已启用并更新到最新的 WSL2（在管理员 PowerShell 中执行 wsl --install 后重启，或 wsl --update）；
• Dragonfly 2025.1 / 2027.1，且至少启动过一次；
• 约 8–10 GB 可用磁盘空间用于存放 WSL 镜像（镜像压缩包本身约 0.99 GB）；
• 仅使用 CPU，无需 GPU；导入过程为本地文件操作，无需联网（前提是压缩包已随安装包一并提供）。

4.2 导入 OpenFOAM WSL 计算镜像

1. 打开随附的 OpenFOAM-WSL-Package 文件夹。

2. 双击 `install_openfoam_wsl.bat`（或用 PowerShell 运行 install_openfoam_wsl.ps1）。

3. 安装脚本会导入名为 OpenfoamCFD 的 WSL 发行版（默认解压到 %LOCALAPPDATA%\OpenfoamCFD\wsl），对其中的 Python 环境做冒烟测试，创建 Windows 端作业文件夹 C:\CFDJobs，并写入配置文件 %LOCALAPPDATA%\OpenfoamCfd\config.json。

4. 等待出现 “Install complete” 即完成。

镜像内使用一个中性用户 dragonfly，不携带任何个人账户信息。OpenFOAM 求解器通过如下解释器被调用：

/home/dragonfly/miniconda3/envs/openfoam/bin/python openfoam_runner.py config.json

常用安装选项（在 PowerShell 中作为参数传入 install_openfoam_wsl.ps1）：

4.3 面板中的环境检测（Setup / Detect OpenFOAM）

首次在面板中运行时，插件会自动读取上述 config.json 并填入 WSL 发行版名与解释器路径。如果面板中 “OpenFOAM interpreter” 一栏为空，请点击 Setup / Detect OpenFOAM 按钮：它会先读取配置文件，若未找到，则在 WSL 内探测名为 openfoam 的 conda 环境（如 $HOME/miniconda3/envs/openfoam/bin/python 等常见位置）。

失败时的替代方案： 若自动检测仍为空，请先按 4.2 导入 WSL 镜像；或在 “OpenFOAM interpreter” 输入框中手动粘贴解释器路径 /home/dragonfly/miniconda3/envs/openfoam/bin/python。检测成功后，配置会被自动保存，下次无需重复。

5. 界面说明

面板顶部有一段说明文字，概述插件功能。顶栏有一个 ◀ Hide demo / Show demo ▶ 按钮，用于折叠或展开左侧的新手演示栏。窗口整体分为左右两栏：左侧为“新手演示”，右侧为“配置 + 日志”。

5.1 左栏：新手演示（Beginner demo）

此栏无需任何分割数据即可体验完整流程。它会自动生成一个合成的多孔固体，对其孔隙空间划分网格并推动流体通过。

该栏还内嵌了“如何解读结果”和“可尝试改变哪些参数”的图文说明。

5.2 右栏之一：输入结构（Input structure）

规则：ROI / MultiROI 中非零标签为固体；Channel 中大于阈值的体素为固体。其余（孔隙）区域即为求解流动的空间。

5.3 右栏之二：WSL OpenFOAM 环境

5.4 右栏之三：Flow（流动：不可压缩、层流）

面板底部固定说明：出口压力固定为 0（作为参考基准）。

5.5 右栏之四：Mesh + solver（网格 + 求解器）

5.6 底部：运行与日志

• Run CFD 按钮（蓝色）：对所选输入对象运行完整 CFD。
• Open Output Folder 按钮：在资源管理器中打开本次（或默认）作业文件夹。
• 日志区：只读文本框，实时显示进度百分比、网格与求解阶段信息、渗透率、导入的 Channel 名称以及输出目录。

6. 使用步骤

6.1 工作流 A：新手演示（无需数据）

1. 菜单 Prototype Apps ▸ OpenFOAM CFD... 打开浮动窗口。

2. 在左侧演示栏选择一个 Phantom（例如 Parallel channels）和 Resolution（如 40）。

3. 确认右栏 “OpenFOAM interpreter” 已填好（若为空，先点 Setup / Detect OpenFOAM）。

4. 点击 Generate phantom + Run demo，在右侧日志中观察进度。

5. 完成后，速度/压力 Channel 出现在 Dragonfly 中，渗透率打印在日志里。

6.2 工作流 B：在自己的分割数据上运行

1. 先准备输入：把固体结构分割为 ROI / MultiROI（非零 = 固体），或准备一个灰度 Channel（配合阈值使用）。

2. 打开面板，在右栏 “Input structure” 中点击 Refresh，从下拉框选择你的对象。

3. 若输入为 Channel，在 Channel threshold 中填入把体素判为“固体”的灰度阈值。

4. 在 Flow 中设置流动方向、入口速度和运动黏度。

5. 在 Mesh + solver 中按需调整表面细化级别、基础网格、最大迭代与收敛残差；保持 “Import result fields...” 勾选。

6. 确认 WSL OpenFOAM 环境 三栏正确（发行版、解释器、作业根目录）。

7. 点击 Run CFD。插件读取固体掩膜（并在日志报告孔隙率），导出 STL、划分网格、求解流动，最后把结果作为 Channel 导入并打印渗透率。

OpenFOAM 案例本身在 WSL 原生的 /tmp 下运行以获得快速 I/O；只有掩膜文件 mask.npy 和结果文件会跨越 /mnt 边界。每次运行的输出保存在 C:\CFDJobs\cfd_<时间戳>\ 之类的作业文件夹中。

7. 参数说明

下表汇总所有可调参数及其默认值，供快速查阅。

8. 输出结果

求解完成并勾选导入选项后，插件会把采样回体素网格的结果场作为 Dragonfly Channel 导入场景。这些 Channel 与原始对象网格对齐（保留体素间距与原点）。

在新手演示中，除上述结果外，还会额外导入一个名为 Phantom_<类型> 的 Channel（合成固体本身），且各结果 Channel 会带 Demo_ 前缀（如 Demo_Velocity_Magnitude）。

日志中的数值结果包括：

• Permeability（渗透率） — 根据入口流量、进出口压降和运动黏度用达西定律计算，单位为“（输入长度单位）的平方”；数值越大表示越易渗透；
• Darcy velocity（达西速度） 与 dP (kinematic)（运动学压降）；
• Mesh cells（网格单元数） — snappyHexMesh 生成的孔隙网格规模。

所有原始 OpenFOAM 案例、日志（log.blockMesh、log.snappyHexMesh、log.simpleFoam 等）和结果文件（foam_result.json、field_*.npy）保存在 Windows 端的作业文件夹里；点击 Open Output Folder 可直接查看。

9. 常见问题与故障排除

10. 注意事项与已知限制

• 仅支持 Windows + WSL2；CFD 计算完全在 WSL 的 Linux 环境中进行，不使用 Dragonfly 自带的 Python。
• 求解的物理为定常、不可压缩、层流（simpleFoam）；不适用于湍流、可压缩流、瞬态或多相流。
• 出口压力固定为 0，无法在面板中修改；入口为固定速度边界，侧壁为滑移边界，固体表面为无滑移壁面。
• 渗透率结果依赖网格质量与孔隙连通性；对分辨率、细化级别较敏感，建议对关键结果做网格无关性检查。
• 计算耗时随体素规模、细化级别和迭代数快速增长；首次评估建议用较小分辨率/较低细化级别。
• 仅使用 CPU；无需也不使用 GPU。
• 菜单只在 Dragonfly 启动时扫描，任何启用/停用改动都需要重启一次 Dragonfly 才能生效。

11. 参考资料

• OpenFOAM（ESI 版本）官网：https://www.openfoam.com/
• OpenFOAM 用户指南（simpleFoam、snappyHexMesh 等）：https://www.openfoam.com/documentation/
• scikit-image（marching cubes 表面提取）：https://scikit-image.org/
• WSL（Windows Subsystem for Linux）文档：https://learn.microsoft.com/windows/wsl/
• 达西定律（Darcy's law）：https://en.wikipedia.org/wiki/Darcy%27s_law

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Environment & First-Run Setup

5. Interface Guide

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

The OpenFOAM CFD plugin lets you run a pore-scale computational fluid dynamics (CFD) simulation directly on your segmented 3D data inside Dragonfly. You select a ROI, MultiROI, or Channel that defines the solid/pore structure, choose the flow direction and mesh/solver options, and the plugin automatically meshes the pore (void) phase and solves steady, incompressible, laminar flow. The resulting velocity and pressure fields are imported back into the scene as Channels, together with an estimated Darcy permeability value.

The underlying engine is the open-source OpenFOAM (v2412, the ESI build from conda-forge). The pipeline reads a solid mask from the chosen object, extracts the solid surface with marching cubes (scikit-image) to produce an STL surface, builds a background mesh with blockMesh, carves out the pore space and marks grain surfaces as walls with snappyHexMesh, solves the flow with simpleFoam (the steady incompressible laminar solver), then samples the velocity/pressure back onto the original voxel grid and computes the Darcy permeability from the inlet flow rate and the inlet-to-outlet pressure drop.

Important: the CFD does not run inside Dragonfly's own Python. The plugin exports the chosen structure as a solid mask file and hands the heavy meshing and solving to a dedicated Linux (WSL2) compute environment; Dragonfly only prepares the input, streams the progress log, and finally imports the results as Channels. This keeps Dragonfly's runtime clean while leveraging the mature OpenFOAM toolchain.

Licensing note: OpenFOAM is open-source software (GPL). This plugin invokes OpenFOAM through the bundled WSL2 compute image without modifying its source; please observe OpenFOAM's own open-source license terms.

2. Use Cases

The plugin targets digital rock physics and porous-media research, and is especially suited to workflows built on micro-CT data that need flow fields and transport properties from a segmented image rather than a physical flow experiment.

• Estimate the permeability of geological samples such as rocks, soils, and sandstones;
• Study the flow resistance and pore connectivity of membranes, filters, foams, and packed beds;
• Assess transport in porous functional materials such as battery electrodes, catalyst supports, and scaffolds;
• Analyse the through-flow of additively manufactured lattices;
• Any materials-science or geoscience task that needs velocity fields, pressure fields, and permeability straight from a segmented 3D image.

The plugin solves laminar, incompressible, steady flow, appropriate for low-Reynolds-number (slow) pore-scale flow. It is not intended for turbulent, compressible, transient, or multiphase analysis.

3. Installation & Enabling

The plugin ships with the Prototype Labs Full Package. Installation has two parts: a one-time install of the Dragonfly plugin (the panel), and a one-time import of the OpenFOAM WSL2 compute image (see Chapter 4).

3.1 Install the plugin via the Full Package

1. Unzip the Full Package into a short folder (e.g. C:\PL\) to avoid path-length errors.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick a core install mode (Fresh / Compatible) and tick "OpenFOAM CFD" in the Prototype Apps list. By default all plugins are unchecked and must be ticked to deploy.

4. Click Install and wait for the console to finish.

5. Quit Dragonfly completely and restart it (menus are scanned only at startup).

After the restart the plugin appears at Prototype Apps ▸ OpenFOAM CFD... (in the "Simulation & Meshing" group). Clicking it opens a movable, resizable floating window.

3.2 Change your choice later (Menu Item Manager)

To enable or disable the plugin later, the easiest way is from inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, tick/untick "OpenFOAM CFD" in the "Prototype Apps (Full Package)" list at the bottom, then restart Dragonfly to apply.

Disabling the plugin never deletes the imported WSL compute environment; re-enabling is instant and requires no re-import.

4. Environment & First-Run Setup

OpenFOAM runs on Linux. The plugin packages the whole OpenFOAM environment as a WSL2 appliance that you import once with a double-click — there is no conda environment to build and no download over the internet.

4.1 Prerequisites

• Windows 10 / 11 (64-bit);
• WSL2 enabled and up to date (in an admin PowerShell: wsl --install then reboot, or wsl --update);
• Dragonfly 2025.1 / 2027.1, launched at least once;
• About 8–10 GB of free disk for the WSL image (the compressed tarball itself is ~0.99 GB);
• CPU only, no GPU needed; the import is a local file operation and requires no internet (assuming the tarball is provided with the package).

4.2 Import the OpenFOAM WSL compute image

1. Open the bundled OpenFOAM-WSL-Package folder.

2. Double-click `install_openfoam_wsl.bat` (or run install_openfoam_wsl.ps1 in PowerShell).

3. The installer imports a WSL distro named OpenfoamCFD (default location %LOCALAPPDATA%\OpenfoamCFD\wsl), smoke-tests its Python environment, creates the Windows job folder C:\CFDJobs, and writes the config file %LOCALAPPDATA%\OpenfoamCfd\config.json.

4. Wait for "Install complete".

The image runs as a neutral user dragonfly and carries no personal account information. The OpenFOAM solver is invoked through this interpreter:

/home/dragonfly/miniconda3/envs/openfoam/bin/python openfoam_runner.py config.json

Common installer options (passed as parameters to install_openfoam_wsl.ps1):

4.3 Detecting the environment in the panel (Setup / Detect OpenFOAM)

On first run the plugin reads the config.json above and fills in the WSL distro name and interpreter path. If the "OpenFOAM interpreter" field is empty, click Setup / Detect OpenFOAM: it first reads the config file, and if nothing is found it probes WSL for a conda env named openfoam in common locations (e.g. $HOME/miniconda3/envs/openfoam/bin/python).

Fallback if it fails: if auto-detection still comes up empty, import the WSL image per 4.2 first, or paste the interpreter path manually into the "OpenFOAM interpreter" box: /home/dragonfly/miniconda3/envs/openfoam/bin/python. Once detected, the configuration is saved automatically for next time.

5. Interface Guide

The panel has a short description at the top. A top-bar button ◀ Hide demo / Show demo ▶ collapses or expands the left-hand demo column. The window is split into two columns: the left is the beginner demo, the right is configuration + log.

5.1 Left column: Beginner demo

This column lets you experience the full pipeline with no segmentation. It generates a synthetic porous solid, meshes its pore space, and pushes fluid through it.

The column also includes inline "how to read the result" and "what to try changing" guidance.

5.2 Right column, part 1: Input structure

Rule: nonzero labels in a ROI/MultiROI are solid; Channel voxels above the threshold are solid. Everything else (the pore) is where flow is solved.

5.3 Right column, part 2: WSL OpenFOAM environment

5.4 Right column, part 3: Flow (incompressible, laminar)

A fixed note at the bottom states: the outlet pressure is fixed at 0 (reference).

5.5 Right column, part 4: Mesh + solver

5.6 Bottom: run + log

• Run CFD button (blue): runs the full CFD on the selected input object.
• Open Output Folder button: opens the current (or default) job folder in Explorer.
• Log area: a read-only text box showing live progress percentages, mesh/solve stage messages, the permeability, imported Channel names, and the output directory.

6. Step-by-Step Usage

6.1 Workflow A: Beginner demo (no data needed)

1. Open the floating window via Prototype Apps ▸ OpenFOAM CFD....

2. In the left demo column choose a Phantom (e.g. Parallel channels) and a Resolution (e.g. 40).

3. Make sure the "OpenFOAM interpreter" field on the right is filled (if empty, click Setup / Detect OpenFOAM first).

4. Click Generate phantom + Run demo and watch the progress in the log on the right.

5. When done, velocity/pressure Channels appear in Dragonfly and the permeability is printed in the log.

6.2 Workflow B: Run on your own segmentation

1. Prepare the input: segment the solid structure as a ROI / MultiROI (nonzero = solid), or prepare a grayscale Channel (used with a threshold).

2. Open the panel, click Refresh in the "Input structure" group, and pick your object from the dropdown.

3. If the input is a Channel, enter the grayscale threshold that separates "solid" in Channel threshold.

4. Set the flow axis, inlet velocity, and kinematic viscosity in Flow.

5. Adjust surface refinement level, base cell, max iterations, and convergence residual in Mesh + solver as needed; keep "Import result fields..." checked.

6. Confirm the three WSL OpenFOAM environment fields (distro, interpreter, job root) are correct.

7. Click Run CFD. The plugin reads the solid mask (and reports porosity in the log), exports the STL, meshes, solves the flow, then imports the results as Channels and prints the permeability.

The OpenFOAM case itself runs under WSL-native /tmp for fast I/O; only the mask file mask.npy and the result files cross the /mnt boundary. Each run's output is saved in a job folder such as C:\CFDJobs\cfd_<timestamp>\.

7. Parameter Reference

The table below summarises every adjustable parameter and its default value for quick reference.

8. Outputs

When solving finishes and the import option is checked, the plugin imports the result fields — sampled back onto the voxel grid — as Dragonfly Channels aligned with the original object's grid (preserving voxel spacing and origin).

In the beginner demo, an extra Channel named Phantom_<type> (the synthetic solid itself) is also imported, and the result Channels carry a Demo_ prefix (e.g. Demo_Velocity_Magnitude).

Numeric results in the log include:

• Permeability — computed from the inlet flow rate, the inlet-to-outlet pressure drop, and the kinematic viscosity via Darcy's law, in (input length unit)^2; larger = more permeable;
• Darcy velocity and dP (kinematic) (the kinematic pressure drop);
• Mesh cells — the size of the pore mesh produced by snappyHexMesh.

All raw OpenFOAM cases, logs (log.blockMesh, log.snappyHexMesh, log.simpleFoam, etc.) and result files (foam_result.json, field_*.npy) are kept in the Windows job folder; click Open Output Folder to inspect them.

9. FAQ & Troubleshooting

10. Notes & Known Limitations

• Supported on Windows + WSL2 only; the CFD runs entirely in the WSL Linux environment, never in Dragonfly's own Python.
• The physics solved is steady, incompressible, laminar flow (simpleFoam); it is not for turbulent, compressible, transient, or multiphase flow.
• The outlet pressure is fixed at 0 and cannot be edited in the panel; the inlet is a fixed-velocity boundary, the side walls are slip, and the solid surface is no-slip.
• Permeability results depend on mesh quality and pore connectivity, and are sensitive to resolution and refinement level; do a mesh-independence check for critical results.
• Compute time grows quickly with voxel count, refinement level, and iterations; use a small resolution / low refinement for a first estimate.
• CPU only; no GPU is used or required.
• Menus are scanned only at Dragonfly startup, so any enable/disable change requires one restart to take effect.

11. References

• OpenFOAM (ESI build) home page: https://www.openfoam.com/
• OpenFOAM user guide (simpleFoam, snappyHexMesh, etc.): https://www.openfoam.com/documentation/
• scikit-image (marching cubes surface extraction): https://scikit-image.org/
• WSL (Windows Subsystem for Linux) documentation: https://learn.microsoft.com/windows/wsl/
• Darcy's law: https://en.wikipedia.org/wiki/Darcy%27s_law