FEniCSx 有限元仿真 插件用户手册

FEniCSx FEM - User Manual

Dragonfly Prototype Apps · FEniCSx FEM...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

FEniCSx FEM 插件让你在不离开 Dragonfly 的情况下,直接在由 CGAL Mesh_3 插件从分割后的 CT 数据生成的四面体网格上运行有限元(FEM)仿真。当前版本(v1)支持线弹性物理场:你在面板中指定网格、设置材料参数(杨氏模量 E 和泊松比 nu)、选择固定面和加载面,点击 Run FEM;计算得到的位移场和 von Mises 应力场会被重采样回原始 CT 体素网格,并作为与原始数据完全对齐的新 Channel 导入场景,可与图像数据一起查看和分析。

底层求解引擎是开源有限元框架 FEniCSx(dolfinx)0.9(conda-forge 包 fenics-dolfinx=0.9.*),配套组件包括 PETSc(实数标量版)、meshio(读取 .vtu 网格)、numpy/scipy、h5py 与 pyvista,运行于 Python 3.12。求解器默认使用迭代法(CG + GAMG 预条件),也可切换为直接法(LU/MUMPS)。

架构上,插件采取严格的进程隔离:Dragonfly 侧只负责组装配置(config.json)、启动求解和把结果导回 Channel;真正的 PDE 求解由 fenicsx_runner.py 在 WSL2 中的专用 conda 环境里完成,绝不在 Dragonfly 自带的 Python 里加载求解器。两侧通过作业文件夹中的文件通信(config.json 下发任务、status.json 汇报进度),因此求解崩溃不会影响 Dragonfly 本身。

为什么必须用 WSL2:FEniCSx 没有 Windows 安装包(dolfinx/petsc4py/mpi4py 无 pip wheel,conda-forge 也没有 win-64 版本),该软件栈只能在 Linux 上运行。插件因此借助 Windows 自带的 WSL2 子系统运行 Linux 求解环境。

许可证要点:本插件的全部计算组件(FEniCSx/dolfinx、PETSc、meshio 等)均为开源软件,通过 conda-forge 官方渠道安装,不包含任何商业求解器;插件本身随 Prototype Apps Full Package 分发。

2. 适用场景

本插件面向材料科学和工业 CT 的基于图像的仿真(image-based simulation):无需把网格导出到独立的有限元软件,即可在 Dragonfly 内评估扫描对象在载荷下的力学响应。典型场景包括:

• 评估扫描零件、增材制造(AM)部件在载荷下的变形与应力分布;
• 泡沫、点阵(lattice)等多孔结构的等效力学响应估计;
• 岩石、骨类结构等地质/生物材料样本的受载分析;
• 多材料结构:CGAL 网格携带的 MaterialID 标签允许对每种分割材料赋予不同的 E 和 nu(例如复合材料中的基体与增强相);
• 教学与入门:面板左侧内置四种标准结构(悬臂梁、双材料悬臂梁、门式框架、L 形支架)的一键演示,不需要任何 CT 数据即可体验完整流程。

3. 安装与启用

本插件通过 Prototype Labs & Apps Full Package(完整安装包)安装:

1. 将安装包 zip 解压到任意较短路径(例如 C:\PL\,避免过深的目录导致 Windows 260 字符路径限制)。

2. 双击 `Install_FullPackage.bat` 启动安装器。

3. 在弹出的组件列表中勾选 FEniCSx FEM...。注意:所有插件默认不勾选,必须手动勾选本插件才会安装。

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

5. 完全重启 Dragonfly(彻底退出后重新打开)——菜单只在 Dragonfly 启动时扫描一次。

重启后,菜单入口出现在 Prototype Apps ▸ FEniCSx FEM...(位于 Simulation & Meshing 分组)。点击后打开一个可自由缩放的浮动面板窗口。

以后如需启用/停用本插件,最方便的方式是在 Dragonfly 内打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部 "Prototype Apps (Full Package)" 列表中勾选或取消勾选 FEniCSx FEM...,然后重启 Dragonfly 生效。停用从不删除插件已搭好的 WSL 计算环境,重新启用立即可用。也可以随时重跑安装器(即使 zip 已删除,可运行 %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat)。

前置依赖:本插件消费 CGAL Mesh_3 插件的输出(.vtu 四面体网格 + 同目录 metadata.json)。做真实 CT 数据仿真前,请先安装并使用 CGAL Mesh_3 插件生成网格;仅运行新手演示则不需要 CGAL。

4. 运行环境与首次配置

插件的求解环境运行在 WSL2 中,首次使用前需要一次性搭建。整个过程不需要 GPU;联网仅在搭建环境时需要,日常求解不联网。

4.1 前提:安装 WSL2

需要 Windows 10/11 且已安装并更新 WSL2。如尚未安装,在管理员 PowerShell 中执行:

wsl --install (安装后需重启电脑)

wsl --update (已安装时更新)

4.2 方式一:面板内一键搭建(Setup FEniCSx Environment)

打开面板,确认 WSL distro 字段填的是你已有的发行版名称(默认 Ubuntu),点击 Setup FEniCSx Environment。该按钮在所选 WSL 发行版内执行随插件附带的搭建脚本,具体做以下事情:

1. 查找发行版内已有的 mamba / conda / micromamba;若完全没有 conda,自动从 GitHub 下载 Miniforge 并安装到 $HOME/miniforge3;

2. 用 environment.yml 创建(或更新)名为 fenicsx 的 conda 环境:Python 3.12、fenics-dolfinx=0.9.*、实数标量 PETSc、meshio>=5、scipy、numpy、h5py、pyvista;

3. 运行导入自检(import dolfinx 等),确认环境可用;

4. 输出 FENICSX_PYTHON=<解释器路径>,面板捕获该路径填入 FEniCSx interpreter 字段并保存到配置,供以后自动复用。

首次搭建需要联网下载约 1-2 GB,耗时约 10-30 分钟。日志实时显示在面板下方的日志区;完成后日志出现 "FEniCSx environment ready. Interpreter: ..."。

4.3 方式二:导入预构建 WSL 镜像(免联网搭建)

如果随插件提供了 FEniCSx-WSL-Package 压缩包(内含约 1.5 GB 的 fenicsx-rootfs.tar.gz),可以跳过在线搭建,直接导入一个现成的 Linux 镜像(Ubuntu + 已建好的 fenicsx conda 环境):

1. 双击包内的 `install_fenicsx_wsl.bat`(或运行 install_fenicsx_wsl.ps1);

2. 安装器把镜像导入为名为 `FenicsxFEM` 的 WSL 发行版(磁盘文件默认放在 %LOCALAPPDATA%\FenicsxFEM\wsl),并自动做一次 dolfinx 冒烟测试;

3. 安装器自动写入 %LOCALAPPDATA%\FenicsxFem\config.json,Dragonfly 面板会自动填好 WSL 发行版名和解释器路径(/home/dragonfly/miniconda3/envs/fenicsx/bin/python),无需任何手动配置;

4. 打开 Dragonfly 面板,点 Generate Phantom + Run Demo FEA 做端到端验证。

安装器支持的命令行选项:-DistroName <名称>(改用其他发行版名)、-InstallDir <路径>(改磁盘存放位置)、-Force(覆盖同名发行版)、-Uninstall(移除发行版和插件配置)。镜像内使用中性用户 dragonfly,不携带任何个人账户信息。

4.4 配置的保存与自动恢复

面板把 CGAL 输出目录、网格路径、WSL 发行版、解释器路径和作业根目录保存在两处(互为备份):%LOCALAPPDATA%\FenicsxFem\config.json 和插件代码目录内的 fenicsx_config.json。若解释器字段为空,点击 Run 时面板会自动:先读取配置文件恢复;仍未找到时,自动在 WSL 内探测常见 conda 安装位置(miniconda3 / miniforge3 / anaconda3 / /opt/conda 等)中名为 fenicsx 的环境。也可以手动把解释器路径粘贴进 FEniCSx interpreter 字段。

失败时的替代方案:在线搭建失败(网络受限)时改用方式二导入预构建镜像;镜像不可用时,也可在任意 WSL 发行版内手动执行 bash setup_fenicsx_env.sh 后把打印的解释器路径粘贴到面板。

5. 界面说明

面板是一个可缩放、可最大化的浮动窗口,顶部有一行蓝色说明文字,下方分为左右两栏(可拖动分隔条调整比例):左栏是新手演示区,右栏是常规配置区。顶部的 ◀ Hide demo / Show demo ▶ 按钮可整体折叠/展开左栏。两栏各自带滚动条。

5.1 左栏:新手演示(① Beginner Demo — Phantom + Linear-Elasticity FEA)

演示区内置图解(流程图、悬臂梁示意图、参数影响图),让没有 CT 数据的用户也能一键体验"体素结构 → 四面体网格 → FEniCSx 求解 → 结果 Channel"的完整四步流程。控件如下:

• 结构下拉框,四种标准结构:Cantilever beam (uniform) 均匀悬臂梁(一端固定、自由端下压,经典弯曲演示);Cantilever beam (2 materials: stiff top) 双材料悬臂梁(上半部刚度 5 倍,观察硬层挠度更小);Building portal frame (lateral load) 门式框架(两柱一梁,底部固定,顶部侧向推力,侧移演示);L-bracket (stress concentration) L 形支架(顶部固定、水平臂端部加载,观察内角应力集中);
• Stiffness E (Young's modulus) 文本框,默认 1.0e9;
• Applied load 文本框,默认 1.0e6;
• Resolution (voxels, 4-16) 文本框,默认 8——数值越大网格越细、应力峰值越准,但求解越慢,建议 6-10;
• Generate Phantom + Run Demo FEA 按钮(绿色):生成体素模型、剖分四面体、在 WSL 中求解并把结果导入为 Channel;
• 结果摘要标签:完成后显示最大位移、最大 von Mises 应力、四面体数量和已导入的 Channel 名。

5.2 右栏:Mesh (from CGAL Mesh_3 plugin)

• CGAL output folder:CGAL Mesh_3 插件的输出根目录,默认 C:\CGALMeshJobs,带 … 浏览按钮;
• Mesh .vtu (override):可选,指定某一个具体的 .vtu 网格文件;留空则自动使用输出目录下(递归搜索)最新的、且同目录存在 metadata.json 的 .vtu。

5.3 右栏:FEniCSx Environment (WSL2)

• WSL distro:承载求解环境的 WSL 发行版名,默认 Ubuntu(导入预构建镜像后自动变为 FenicsxFEM);
• FEniCSx interpreter:WSL 内 fenicsx conda 环境的 python 路径,由 Setup 按钮自动填写(占位提示 "set by 'Setup FEniCSx Environment'"),也可手动粘贴;
• Job root (Windows):作业根目录,默认 C:\FEAJobs,每次求解在其下新建一个带时间戳的作业文件夹;
• Setup FEniCSx Environment 按钮:一次性搭建/更新求解环境(见第 4 章)。

5.4 右栏:Material (Linear Elasticity)

• Young's modulus E (default):默认材料的杨氏模量,默认 1.0e9;
• Poisson ratio nu (default):默认材料的泊松比,默认 0.3;
• Per-material overrides (JSON):按 CGAL 网格的 MaterialID 逐材料覆盖,例如 {"2": {"E": 5e9, "nu": 0.25}};未覆盖的材料使用上面的默认值。填写的 JSON 无效时会被忽略并在日志中提示。

5.5 右栏:Boundary Conditions (bounding-box faces)

边界条件按网格包围盒的整面施加(轴 x/y/z + 侧 min/max),因为 CGAL 四面体网格没有命名表面:

• Fixed face (u=0):固定面(位移为零),轴下拉 + 侧下拉,默认 z / min;
• Load face:加载面,默认 z / max;
• Traction on load face (x,y,z):加载面上的表面牵引力矢量(力/面积),三个分量,默认 0, 0, -1.0e6;三个分量全为 0 时不施加载荷;
• Body force (x,y,z):体力矢量,默认 0, 0, 0。

5.6 右栏:Solver & Output

• Direct solver (LU/MUMPS) instead of CG+GAMG 复选框,默认不勾选:勾选后改用直接法求解(小中型网格更稳健),不勾选用迭代法(默认收敛容差 1e-8,最多 2000 步);
• Import result fields as Dragonfly Channels 复选框,默认勾选:求解后把结果场自动导入为 Channel;取消勾选则只在作业文件夹留下文件。

5.7 右栏底部:运行按钮与日志

• Run FEM 按钮(蓝色):按当前配置启动一次完整求解;
• Open Output Folder 按钮:在资源管理器中打开最近一次的作业文件夹(尚无作业时打开作业根目录);
• 日志区(只读):实时显示环境搭建输出、求解进度百分比与状态消息、导入的 Channel 名和错误信息。

6. 使用步骤

6.1 工作流 A:新手演示(无需 CT 数据)

1. 确认求解环境已就绪(第 4 章;FEniCSx interpreter 字段非空或配置可自动恢复)。

2. 在左栏下拉框选择一种结构(建议从 Cantilever beam (uniform) 开始)。

3. 按需修改 Stiffness E、Applied load、Resolution(默认即可)。

4. 点击 Generate Phantom + Run Demo FEA,观察日志中的进度。

5. 完成后,场景中出现三个 Channel:Phantom_<结构名>(输入形状)、Demo_Displacement_Field(位移幅值)、Demo_VonMises_Stress(应力集中位置);结果摘要显示最大位移与最大应力。

6. 改变一个参数再跑一次并对比:载荷翻倍 → 位移与应力约翻倍;刚度 E 翻倍 → 位移约减半(应力基本不变);切换结构对比不同力学行为。

6.2 工作流 B:真实 CT 数据的线弹性仿真

1. 在 Dragonfly 中完成分割,并用 CGAL Mesh_3 插件从标签数据生成四面体网格——得到 .vtu 文件和同目录的 metadata.json(默认在 C:\CGALMeshJobs 下)。

2. 打开 Prototype Apps ▸ FEniCSx FEM... 面板;确认 CGAL output folder 指向 CGAL 的输出目录,或用 Mesh .vtu (override) 直接选定某个网格文件(留空 = 自动取最新)。

3. 在 Material 组设置默认 E 和 nu;多材料网格可在 Per-material overrides 中按 MaterialID 逐材料覆盖。

4. 在 Boundary Conditions 组选择固定面(如 z/min)、加载面(如 z/max)并填写牵引力矢量(至少一个分量非零);按需填写体力。

5. 在 Solver & Output 组按网格规模选择求解方式;保持 Import result fields as Dragonfly Channels 勾选。

6. 点击 Run FEM。日志先显示所用网格路径,然后是求解进度(百分比 + 阶段消息);求解在 WSL 中进行,规模大时需要等待。

7. 完成后,Displacement_Field 和 VonMises_Stress 两个 Channel 出现在场景中,与原 CT 数据坐标完全对齐,可直接叠加查看;点击 Open Output Folder 可查看本次作业的全部输出文件。

6.3 作业文件夹

每次运行在作业根目录(默认 C:\FEAJobs)下新建一个文件夹:常规求解为 fea_<时间戳>,演示为 fea_demo_<结构>_<时间戳>。其中包含本次的配置、进度、网格求解结果与栅格化场文件(详见第 8 章),便于追溯与重现。

7. 参数说明

主面板(右栏)参数一览:

新手演示(左栏)参数一览:

8. 输出结果

导入 Dragonfly 的对象(Channel):求解成功且勾选导入时,以下 Channel 出现在场景中,几何(体素间距与原点)取自 CGAL 的 metadata.json,与原始 CT 数据完全对齐:

• Displacement_Field —— 位移幅值场(float32,z/y/x 排列);
• VonMises_Stress —— von Mises 等效应力场;
• 演示模式下名称带前缀:Demo_Displacement_Field、Demo_VonMises_Stress,外加输入形状 Phantom_<结构名>。

网格之外的体素值为 NaN(不在实体内),显示为空/透明属正常现象。把结果 Channel 与原 CT Channel 叠加显示,即可直观看到应力集中和变形分布的位置。

作业文件夹中的文件(点 Open Output Folder 查看):

9. 常见问题与故障排除

问 1:点 Run FEM 提示 "ERROR: FEniCSx interpreter not set"?

答:求解环境还没就绪。先点 Setup FEniCSx Environment 完成一次性搭建(或导入预构建 WSL 镜像);若环境其实已存在,面板会先读配置文件、再自动探测 WSL 内名为 fenicsx 的 conda 环境,也可以手动把解释器路径粘贴进字段。

问 2:日志报 "'wsl' not found. Install WSL2."?

答:本机没有安装 WSL2。在管理员 PowerShell 执行 wsl --install 并重启电脑(已安装则 wsl --update),然后确认 wsl -d <发行版名> 能正常进入 Linux。

问 3:报 "no .vtu with a sibling metadata.json under ..."?

答:插件在 CGAL output folder 下找不到合格的网格。合格网格必须是 .vtu 文件且同目录存在 `metadata.json`(CGAL Mesh_3 插件的标准输出)。请先用 CGAL Mesh_3 生成网格、确认输出目录填写正确,或用 Mesh .vtu (override) 直接选中文件。

问 4:环境搭建很慢或失败?

答:首次搭建要联网下载约 1-2 GB,正常耗时 10-30 分钟,请耐心等待并保持网络畅通。若因网络受限反复失败,改用预构建 WSL 镜像(FEniCSx-WSL-Package,双击 install_fenicsx_wsl.bat),导入后面板配置自动填好,完全不需要在线搭建。

问 5:求解时间很长或迭代不收敛?

答:迭代法(默认)对超大网格更省内存,但可能收敛慢;中小网格建议勾选 Direct solver (LU/MUMPS) 改用直接法。演示模式下可先调低 Resolution。另外冷启动的 WSL 虚拟机首次响应较慢,面板会先做一次预热,属正常现象。

问 6:设置了加载面但结果没有变形?

答:检查 Traction on load face (x,y,z) 三个分量——只要全为 0,插件就不会施加载荷面边界条件。至少填一个非零分量(注意符号即方向)。

10. 注意事项与已知限制

• v1 仅支持线弹性物理场;热、静电等物理场是未来扩展方向。
• 边界条件只能施加在包围盒的整面上(轴 + min/max),不支持命名表面、部分面加载、分量式/对称边界条件——CGAL 四面体网格没有命名表面。
• 真实数据工作流依赖 CGAL Mesh_3 插件的输出格式(.vtu + metadata.json);其他来源的网格若缺少 metadata.json 将无法被自动发现。
• 结果以体素 Channel 形式导入(Dragonfly 展示规则体素数据);如需在四面体网格上做节点级后处理,请用 ParaView 打开作业文件夹中的 fem.xdmf / fem.vtu。
• E、载荷与长度单位由用户自行保持一致(插件不做单位换算);材料覆盖按 CGAL 的 MaterialID 匹配,default 条目覆盖所有未列出的材料号。
• 求解环境只在 Linux(WSL2)运行;不需要 GPU,联网仅搭建环境时需要。
• 菜单只在 Dragonfly 启动时扫描——启用/停用插件后需重启一次;停用不会删除已搭建的 WSL 环境。
• 迭代求解器参数(容差 1e-8、最大 2000 步)当前不在界面上开放修改。

11. 参考资料

• FEniCSx / dolfinx 项目(开源有限元框架;conda-forge 包名 fenics-dolfinx,本插件使用 0.9 系列):https://fenicsproject.org
• Miniforge(环境搭建脚本在缺少 conda 时自动安装):https://github.com/conda-forge/miniforge
• ParaView(打开作业文件夹中的 fem.xdmf / fem.vtu 做网格级后处理)
• CGAL Mesh_3 插件用户手册(生成本插件所需的四面体网格 + metadata.json)
• Microsoft WSL2 文档(wsl --install / wsl --update 的官方说明)

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Runtime Environment and First-Time Setup

5. User Interface

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

The FEniCSx FEM plugin lets you run finite-element (FEM) simulations directly on the tetrahedral meshes that the CGAL Mesh_3 plugin generates from your segmented CT data — without leaving Dragonfly. The current version (v1) solves linear elasticity: you point the panel at a mesh, set material properties (Young's modulus E and Poisson's ratio nu), choose which bounding-box face is fixed and which is loaded, and click Run FEM. The computed displacement field and von Mises stress field are sampled back onto the original CT voxel grid and imported as new Channels that are perfectly aligned with the original data, ready to view and analyze alongside your images.

The solver engine is the open-source finite-element framework FEniCSx (dolfinx) 0.9 (conda-forge package fenics-dolfinx=0.9.*), together with PETSc (real-scalar build), meshio (reads the .vtu mesh), numpy/scipy, h5py and pyvista, running on Python 3.12. The solver defaults to an iterative method (CG + GAMG preconditioning) and can be switched to a direct method (LU/MUMPS).

Architecturally the plugin enforces strict process isolation: the Dragonfly side only assembles the configuration (config.json), launches the solve, and imports results back as Channels; the actual PDE solve is performed by fenicsx_runner.py inside a dedicated conda environment in WSL2 — the solver is never loaded into Dragonfly's own Python. The two sides communicate through files in the job folder (config.json for the task, status.json for live progress), so a solver crash can never take Dragonfly down.

Why WSL2 is required: FEniCSx has no Windows distribution (no pip wheels for dolfinx/petsc4py/mpi4py, and no win-64 build on conda-forge) — the stack runs on Linux only. The plugin therefore uses Windows' built-in WSL2 subsystem to host the Linux compute environment.

Licensing: all compute components (FEniCSx/dolfinx, PETSc, meshio, etc.) are open-source software installed from the official conda-forge channel; no commercial solver is included. The plugin itself ships with the Prototype Apps Full Package.

2. Use Cases

The plugin targets image-based simulation for materials science and industrial CT: estimating the mechanical response of scanned objects under load without exporting to a separate FEM package. Typical scenarios include:

• Estimating deformation and stress distributions of scanned parts and additively manufactured (AM) components under load;
• Effective mechanical response of porous structures such as foams and lattices;
• Load analysis of geological/biological samples such as rocks and bone-like structures;
• Multi-material structures: the MaterialID labels carried by the CGAL mesh allow a different E and nu per segmented material (e.g. matrix vs. reinforcement in a composite);
• Teaching and onboarding: the left-hand side of the panel ships a one-click demo with four standard structures (cantilever beam, two-material cantilever, portal frame, L-bracket) — no CT data needed to experience the full pipeline.

3. Installation and Enabling

The plugin is installed through the Prototype Labs & Apps Full Package:

1. Unzip the package to a short path (e.g. C:\PL\; avoid deep folders because of the Windows 260-character path limit).

2. Double-click `Install_FullPackage.bat`.

3. In the component list, tick FEniCSx FEM.... Note: all plugins are unchecked by default — you must tick this plugin explicitly.

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

5. Restart Dragonfly completely (quit and reopen) — menus are scanned only at Dragonfly startup.

After the restart, the menu entry appears under Prototype Apps ▸ FEniCSx FEM... (in the Simulation & Meshing section). Clicking it opens a freely resizable floating panel window.

To enable or disable the plugin later, the easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager and tick/untick FEniCSx FEM... in the "Prototype Apps (Full Package)" list at the bottom, then restart Dragonfly. Disabling never deletes the plugin's WSL compute environment — re-enabling is instant. You can also re-run the installer at any time (even after deleting the zip: run %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat).

Prerequisite: this plugin consumes the output of the CGAL Mesh_3 plugin (a .vtu tetrahedral mesh plus a sibling metadata.json). Install and use CGAL Mesh_3 first for real CT workflows; the beginner demo alone does not need CGAL.

4. Runtime Environment and First-Time Setup

The compute environment runs in WSL2 and must be built once before first use. No GPU is needed; internet access is required only while building the environment, not for day-to-day solves.

4.1 Prerequisite: install WSL2

Windows 10/11 with WSL2 installed and up to date is required. If it is missing, run in an administrator PowerShell:

wsl --install (reboot afterwards)

wsl --update (if already installed)

4.2 Option A: one-click build in the panel (Setup FEniCSx Environment)

Open the panel, make sure the WSL distro field names an existing distribution (default Ubuntu), and click Setup FEniCSx Environment. The button runs the setup script shipped with the plugin inside the chosen WSL distro; concretely it:

1. Looks for an existing mamba / conda / micromamba in the distro; if none is found, it automatically downloads Miniforge from GitHub and installs it into $HOME/miniforge3;

2. Creates (or updates) a conda environment named fenicsx from environment.yml: Python 3.12, fenics-dolfinx=0.9.*, real-scalar PETSc, meshio>=5, scipy, numpy, h5py, pyvista;

3. Runs an import self-test (import dolfinx etc.) to verify the environment;

4. Prints FENICSX_PYTHON=<interpreter path>; the panel captures the path into the FEniCSx interpreter field and saves it to the config for automatic reuse.

The first build downloads roughly 1-2 GB and takes about 10-30 minutes. Output streams live into the log area; on success the log shows "FEniCSx environment ready. Interpreter: ...".

4.3 Option B: import the prebuilt WSL image (no online build)

If the FEniCSx-WSL-Package archive is provided with the plugin (containing the ~1.5 GB fenicsx-rootfs.tar.gz), you can skip the online build and import a ready-made Linux image (Ubuntu plus the prebuilt fenicsx conda environment):

1. Double-click `install_fenicsx_wsl.bat` in the package (or run install_fenicsx_wsl.ps1);

2. The installer imports the image as a WSL distribution named `FenicsxFEM` (its disk lives under %LOCALAPPDATA%\FenicsxFEM\wsl by default) and smoke-tests dolfinx;

3. The installer writes %LOCALAPPDATA%\FenicsxFem\config.json automatically, so the Dragonfly panel auto-fills the WSL distro and interpreter path (/home/dragonfly/miniconda3/envs/fenicsx/bin/python) — no manual configuration needed;

4. Open the Dragonfly panel and click Generate Phantom + Run Demo FEA for an end-to-end verification.

Installer command-line options: -DistroName <name> (use a different distro name), -InstallDir <path> (where the distro's disk lives), -Force (replace an existing distro of the same name), -Uninstall (remove the distro and the plugin config). The image runs as a neutral user dragonfly and carries no personal account information.

4.4 Where settings are saved, and self-healing

The panel saves the CGAL output folder, mesh path, WSL distro, interpreter path and job root in two places (mutual backups): %LOCALAPPDATA%\FenicsxFem\config.json and a fenicsx_config.json next to the plugin code. If the interpreter field is empty when you click Run, the panel first restores it from the config file; failing that, it probes common conda locations inside WSL (miniconda3 / miniforge3 / anaconda3 / /opt/conda, etc.) for an environment named fenicsx. You can also paste the interpreter path manually into FEniCSx interpreter.

Fallbacks on failure: if the online build fails (restricted network), use Option B and import the prebuilt image; if the image is unavailable, you can run bash setup_fenicsx_env.sh manually in any WSL distro and paste the printed interpreter path into the panel.

5. User Interface

The panel is a resizable, maximizable floating window. A blue information line sits at the top; below it the window splits into two columns (draggable splitter): the left column is the beginner demo, the right column is the general configuration. The ◀ Hide demo / Show demo ▶ button at the top collapses/restores the left column. Each column has its own scrollbar.

5.1 Left column: ① Beginner Demo — Phantom + Linear-Elasticity FEA

The demo area includes illustrated diagrams (workflow, cantilever sketch, parameter effects) so that users without CT data can experience the full four-step pipeline — voxel structure → tetrahedral mesh → FEniCSx solve → result Channels — in one click. Controls:

• Structure drop-down with four standard structures: Cantilever beam (uniform) — fixed at one end, pushed down at the free end, the classic bending demo; Cantilever beam (2 materials: stiff top) — the top half is 5x stiffer, showing the stiff layer deflecting less; Building portal frame (lateral load) — two columns plus a top beam, fixed at the bases, pushed sideways on top (sway); L-bracket (stress concentration) — mounted at the top, loaded at the tip, showing the stress spike at the inner corner;
• Stiffness E (Young's modulus) text field, default 1.0e9;
• Applied load text field, default 1.0e6;
• Resolution (voxels, 4-16) text field, default 8 — higher values mean a finer, more accurate mesh (especially stress peaks) but slower solves; 6-10 recommended;
• Generate Phantom + Run Demo FEA button (green): generates the voxel phantom, tetrahedralizes it, solves in WSL, and imports the results as Channels;
• Result summary label: shows the maximum displacement, maximum von Mises stress, tetrahedron count and imported Channel names after completion.

5.2 Right column: Mesh (from CGAL Mesh_3 plugin)

• CGAL output folder: root output folder of the CGAL Mesh_3 plugin, default C:\CGALMeshJobs, with a … browse button;
• Mesh .vtu (override): optional; select one specific .vtu mesh file. Leave blank to automatically use the latest .vtu (searched recursively) that has a sibling metadata.json.

5.3 Right column: FEniCSx Environment (WSL2)

• WSL distro: name of the WSL distribution hosting the solver environment, default Ubuntu (becomes FenicsxFEM after importing the prebuilt image);
• FEniCSx interpreter: path to the python of the fenicsx conda env inside WSL; filled automatically by the Setup button (placeholder "set by 'Setup FEniCSx Environment'"), can also be pasted manually;
• Job root (Windows): job root folder, default C:\FEAJobs; each solve creates a new time-stamped job folder inside it;
• Setup FEniCSx Environment button: one-time build/update of the compute environment (see chapter 4).

5.4 Right column: Material (Linear Elasticity)

• Young's modulus E (default): Young's modulus of the default material, default 1.0e9;
• Poisson ratio nu (default): Poisson's ratio of the default material, default 0.3;
• Per-material overrides (JSON): per-material overrides keyed by the CGAL mesh's MaterialID, e.g. {"2": {"E": 5e9, "nu": 0.25}}; materials without an entry use the defaults above. Invalid JSON is ignored with a log message.

5.5 Right column: Boundary Conditions (bounding-box faces)

Boundary conditions are applied on whole faces of the mesh bounding box (axis x/y/z + side min/max), because a CGAL tet mesh has no named surfaces:

• Fixed face (u=0): the face with zero displacement; axis + side drop-downs, default z / min;
• Load face: the loaded face, default z / max;
• Traction on load face (x,y,z): surface traction vector (force/area) with three components, default 0, 0, -1.0e6; if all three components are 0, no load is applied;
• Body force (x,y,z): body force vector, default 0, 0, 0.

5.6 Right column: Solver & Output

• Direct solver (LU/MUMPS) instead of CG+GAMG checkbox, unchecked by default: check for a direct solve (more robust on small/medium meshes); unchecked uses the iterative solver (tolerance 1e-8, at most 2000 iterations);
• Import result fields as Dragonfly Channels checkbox, checked by default: automatically imports the result fields as Channels after the solve; uncheck to only keep the files in the job folder.

5.7 Right column bottom: run buttons and log

• Run FEM button (blue): starts a full solve with the current configuration;
• Open Output Folder button: opens the most recent job folder in Explorer (or the job root if no job has run yet);
• Log area (read-only): live output of the environment setup, solve progress percentage and status messages, imported Channel names, and error messages.

6. Step-by-Step Usage

6.1 Workflow A: beginner demo (no CT data required)

1. Make sure the compute environment is ready (chapter 4; the FEniCSx interpreter field is filled, or the saved config can restore it automatically).

2. Pick a structure in the left-column drop-down (start with Cantilever beam (uniform)).

3. Optionally adjust Stiffness E, Applied load and Resolution (the defaults are fine).

4. Click Generate Phantom + Run Demo FEA and watch the progress in the log.

5. When finished, three Channels appear in the scene: Phantom_<structure> (the input shape), Demo_Displacement_Field (displacement magnitude) and Demo_VonMises_Stress (where stress concentrates); the result summary shows the maximum displacement and stress.

6. Change one parameter and re-run to compare: doubling the load roughly doubles displacement and stress; doubling E roughly halves the displacement (stress stays about the same); switch structures to compare behaviors.

6.2 Workflow B: linear elasticity on real CT data

1. Segment your data in Dragonfly and generate a tetrahedral mesh from the labels with the CGAL Mesh_3 plugin — this produces a .vtu file with a sibling metadata.json (by default under C:\CGALMeshJobs).

2. Open the Prototype Apps ▸ FEniCSx FEM... panel; make sure CGAL output folder points at the CGAL output directory, or select a specific mesh via Mesh .vtu (override) (blank = latest mesh automatically).

3. Set the default E and nu in the Material group; for multi-material meshes, add per-MaterialID entries in Per-material overrides.

4. In the Boundary Conditions group choose the fixed face (e.g. z/min), the load face (e.g. z/max) and enter the traction vector (at least one non-zero component); optionally set a body force.

5. In Solver & Output choose the solver according to mesh size; keep Import result fields as Dragonfly Channels checked.

6. Click Run FEM. The log first shows which mesh is used, then the solve progress (percentage + stage messages); the solve runs in WSL and can take a while for large meshes.

7. When finished, the Displacement_Field and VonMises_Stress Channels appear in the scene, perfectly aligned with the original CT data for direct overlay; click Open Output Folder to inspect all output files of the job.

6.3 Job folders

Each run creates a new folder under the job root (default C:\FEAJobs): fea_<timestamp> for regular solves and fea_demo_<structure>_<timestamp> for demos. It contains the configuration, live status, mesh-level results and rasterized field files of that run (see chapter 8), making every result traceable and reproducible.

7. Parameter Reference

Main panel (right column) parameters:

Beginner demo (left column) parameters:

8. Outputs

Objects imported into Dragonfly (Channels): on a successful solve with import enabled, the following Channels appear in the scene; their geometry (voxel spacing and origin) comes from the CGAL metadata.json, so they align exactly with the original CT data:

• Displacement_Field — displacement-magnitude field (float32, z/y/x order);
• VonMises_Stress — von Mises equivalent-stress field;
• In demo mode the names carry a prefix: Demo_Displacement_Field, Demo_VonMises_Stress, plus the input shape Phantom_<structure>.

Voxels outside the mesh are NaN (not inside the solid) and appear empty/transparent — this is expected. Overlay the result Channels on the original CT Channel to see directly where stress concentrates and how the part deforms.

Files in the job folder (click Open Output Folder):

9. FAQ and Troubleshooting

Q1: Clicking Run FEM shows "ERROR: FEniCSx interpreter not set"?

A: The compute environment is not ready yet. Click Setup FEniCSx Environment for the one-time build (or import the prebuilt WSL image). If the environment actually exists, the panel first restores the path from the config file and then probes WSL for a conda environment named fenicsx; you can also paste the interpreter path manually.

Q2: The log says "'wsl' not found. Install WSL2."?

A: WSL2 is not installed on this machine. Run wsl --install in an administrator PowerShell and reboot (wsl --update if already installed), then confirm that wsl -d <distro> opens a Linux shell.

Q3: "no .vtu with a sibling metadata.json under ..."?

A: No qualifying mesh was found under the CGAL output folder. A qualifying mesh is a .vtu file with a `metadata.json` in the same folder (the standard CGAL Mesh_3 output). Generate a mesh with CGAL Mesh_3 first, check the folder path, or select the file directly via Mesh .vtu (override).

Q4: Environment setup is slow or fails?

A: The first build downloads about 1-2 GB and normally takes 10-30 minutes — keep the network connection up and be patient. If it keeps failing on a restricted network, switch to the prebuilt WSL image (FEniCSx-WSL-Package, double-click install_fenicsx_wsl.bat); after the import, the panel configuration is filled in automatically and no online build is needed.

Q5: The solve takes very long or does not converge?

A: The iterative solver (default) uses less memory on very large meshes but may converge slowly; for small/medium meshes tick Direct solver (LU/MUMPS). In demo mode, lower the Resolution first. Also note that a cold-started WSL virtual machine responds slowly at first — the panel performs a warm-up, which is normal.

Q6: A load face is set but the result shows no deformation?

A: Check the three components of Traction on load face (x,y,z) — if all of them are 0, the plugin does not apply the load boundary condition at all. Enter at least one non-zero component (the sign encodes the direction).

10. Notes and Known Limitations

• v1 supports linear elasticity only; thermal and electrostatic physics are future extensions.
• Boundary conditions can only be applied on whole bounding-box faces (axis + min/max); named surfaces, partial-face loads and component-wise/symmetry BCs are not supported — a CGAL tet mesh has no named surfaces.
• The real-data workflow depends on the CGAL Mesh_3 plugin output format (.vtu + metadata.json); meshes from other sources without a metadata.json are not auto-discovered.
• Results import as voxel Channels (Dragonfly displays regular voxel data); for node-level post-processing on the tetrahedral mesh, open fem.xdmf / fem.vtu from the job folder in ParaView.
• Units for E, load and length are the user's responsibility (the plugin performs no unit conversion); material overrides match the CGAL MaterialID, and the default entry covers every id without an explicit entry.
• The compute environment runs on Linux (WSL2) only; no GPU is needed, and internet access is required only for the environment build.
• Menus are scanned only at Dragonfly startup — enabling/disabling the plugin requires one restart; disabling never deletes the built WSL environment.
• The iterative-solver settings (tolerance 1e-8, max 2000 iterations) are currently not exposed in the UI.

11. References

• FEniCSx / dolfinx project (open-source finite-element framework; conda-forge package fenics-dolfinx, this plugin uses the 0.9 series): https://fenicsproject.org
• Miniforge (installed automatically by the setup script when no conda is present): https://github.com/conda-forge/miniforge
• ParaView (opens fem.xdmf / fem.vtu from the job folder for mesh-level post-processing)
• CGAL Mesh_3 plugin user manual (generates the tetrahedral mesh + metadata.json this plugin consumes)
• Microsoft WSL2 documentation (official reference for wsl --install / wsl --update)