HPC FEniCS

将 FEniCS 视为一个包含两个主要技术栈的家族：经典 FEniCS（classic FEniCS）与 DOLFINx。

入门指南

1. 首先阅读 references/runtime-selection.md。
2. 若需处理 DOLFINx 的边界条件，请阅读 references/dolfinx-boundary-workflow.md。
3. 在对偏微分方程（PDE）进行弱形式转化、选择函数空间或构建变分形式时，请阅读 references/ufl-and-solver-patterns.md。
4. 当需将常见 PDE 类别映射至已知的变分表述模式时，请阅读 references/pde-template-cookbook.md。
5. 在构建瞬态（time-dependent）或非线性（nonlinear）求解器时，请阅读 references/time-dependent-and-nonlinear-patterns.md。
6. 当需要经典 FEniCS 或 DOLFINx 的具体脚本骨架时，请阅读 references/implementation-skeletons.md。
7. 在选择线性、非线性或块状（block）求解器配置时，请阅读 references/petsc-solver-playbook.md。
8. 在处理混合空间（mixed spaces）、XDMF 输出或后处理任务时，请阅读 references/mixed-problems-and-output.md。
9. 当需为调度器驱动的集群环境（scheduler-backed cluster）部署 FEniCS 或 DOLFINx 脚本时，请阅读 references/cluster-execution-playbook.md。
10. 当修复运行时失败（runtime failures）或排查 IO 问题时，请阅读 references/boundary-io-and-errors.md。

工作流程顺序

1. 选定一个技术栈并保持一致性：
   • 经典 FEniCS：使用 fenics 或 dolfin
   • 现代技术栈：使用 dolfinx
2. 编码前，先将 PDE 正确转化为对应的弱形式。
3. 确保未知量类型与其所属函数空间匹配：
   • 标量场（scalar field）→ 标量空间（scalar space）
   • 矢量场（vector field）→ 矢量空间（vector space）
   • 混合格式（mixed formulation）→ 混合空间（mixed space），并显式处理子空间（subspace）
4. 对于线性问题，使用 TrialFunction 和 TestFunction。
5. 对于非线性问题，使用 Function 表示未知量，并求解残差形式（residual form）。
6. 输出格式应适配预期的后处理器；通常对网格耦合场（mesh-coupled fields）采用 XDMF 格式。

安全准则（Guardrails）

• 切勿在同一脚本中混用经典 FEniCS 的 import 语句与 DOLFINx 的 API。
• 切勿对非线性未知量使用 TrialFunction。
• 若 PDE 欠定（under-constrained），不得随意猜测边界条件；请明确指出缺失项。
• 切勿忽略 UFL 表达式中形状（shape）与秩（rank）不匹配的问题。

补充参考资料

按需加载以下文档：

• references/gmsh-meshtags-and-refinement.md：适用于导入网格、物理组（physical groups）、标记（markers）及细化信息（refinement transfer）
• references/io-visualization-and-writers.md：涵盖 XDMF、VTK、VTX 及可视化安全（visualization-safe）输出方案
• references/parallel-and-mpi-caveats.md：涉及数据所有权（ownership）、边界标记（boundary marking）及并行一致性（parallel consistency）等注意事项
• references/space-boundary-output-matrix.md：提供函数空间、边界条件与输出写入器（writer）选择的对照矩阵
• references/cluster-execution-playbook.md：涵盖 MPI 启动、运行时环境绑定（environment pinning）及集群端 IO 规划

可复用模板

当需要具体脚本框架（concrete script scaffold）时，请使用 assets/templates/ 目录下的模板，尤其是：

• poisson_dolfinx.py
• transient_diffusion_dolfinx.py
• fenics-dolfinx-slurm.sh

输出要求

请报告以下内容：

• 所选技术栈及其版本族（version family），若已知
• PDE 形式与函数空间选择依据
• 所施加的边界条件
• 预期生成的输出文件
• 若正在修复脚本，则需明确指出具体的异常类（failure class）