FEM Notes and C++ Implementations

本项目围绕 Howard Elman、David Silvester 和 Andrew Wathen 的 Finite Elements and Fast Iterative Solvers: with Applications in Incompressible Fluid Dynamics，整理中文有限元学习笔记，并用 C++ 复现书中的 模型问题与快速迭代求解器。

仓库包含两条实现路径：

• deal.II：22 个基线算例，覆盖 Poisson、对流扩散、Stokes、Oseen 和 Navier--Stokes 问题。
• AFEPack：116 个可执行目标，覆盖 P1/P2 离散、稳定化、误差估计、 Krylov/AMG/多重网格、Schur 补、PCD/LSC，以及网格和参数扫描。

完整中文讲义可直接阅读 chinese/fastit.pdf。原书算例与实现目标的 对应关系见 docs/book_coverage.tsv，更详细的算法与 实验记录见 docs/learning_notes.md 和 docs/fast_iterative_solvers.md。

内容概览

主题	主要内容	代表性入口
Poisson	混合/纯 Neumann 边界、奇异解、后验估计、CG、AMG、几何多重网格	poisson_convergence_afepack, poisson_two_grid_afepack
对流扩散	Galerkin、SUPG、人工扩散、边界层/内层、Shishkin 网格、扫掠预条件	convection_diffusion_afepack, convection_diffusion_shishkin_afepack
Stokes/Oseen	Taylor--Hood、稳定化 P1/P1、压力零空间、MINRES、块与 Schur 预条件	stokes_taylor_hood_afepack, oseen_block_pcd_iterative_afepack
Navier--Stokes	Picard/Newton、continuation、Poiseuille、方腔、台阶流、收缩流道、Blasius	navier_stokes_newton_afepack, navier_stokes_step_flow_schur_afepack
快速求解器	Jacobi/GS、Krylov、AMG、几何 V-cycle、PCD、LSC	poisson_solver_comparison_afepack, navier_stokes_pcd_iterative_afepack

目录结构

.
├── CMakeLists.txt          # C++ 算例构建入口
├── docs/                   # Markdown 学习笔记、覆盖表与实验数据
├── examples/
│   ├── afepack/            # AFEPack 算例与求解器实验
│   └── dealii/             # deal.II 基线实现
├── meshes/afepack/         # EasyMesh 输入文件
├── refs/fastit.pdf         # 参考书
├── scripts/                # 验证和批量参数扫描脚本
└── chinese/                # 中译本、课堂课件和独立 AFEPack 教学算例

构建产物默认写入 build/，数值程序通常会在该目录输出 OpenDX 文件或实验表格。

环境要求

• CMake 3.16 或更高版本；支持 C++20 的编译器。
• deal.II 算例默认不构建；显式启用时需要 deal.II 9.4 或兼容版本。
• 构建 AFEPack 算例需要 AFEPack、EasyMesh、OpenBLAS、LAPACKE、 Boost.Serialization 和 pthread；部分功能会在检测到 Eigen3、UMFPACK 时启用。
• 编译中文讲义需要 XeLaTeX、BibTeX、latexmk 和 ctex。

构建

CMake 默认只启用 AFEPack 实现，因此项目的默认重现流程不依赖 deal.II：

cmake -S . -B build \
  -DAFEPACK_ROOT=/path/to/AFEPack
cmake --build build -j2

AFEPack 安装前缀按以下顺序确定：CMake 缓存变量 AFEPACK_ROOT、同名环境 变量、从环境变量 AFEPACK_PATH（通常为 <prefix>/include/AFEPack）推导， 最后回退到 $HOME/local/AFEPack。因此已经配置 AFEPack 环境变量时可直接运行 cmake -S . -B build。如需同时构建可选的 deal.II 基线算例，必须显式传入 -DBUILD_DEALII_EXAMPLES=ON：

# 默认：只构建 AFEPack 算例
cmake -S . -B build \
  -DAFEPACK_ROOT=$HOME/local/AFEPack

# 显式启用 deal.II，并同时构建两套算例
cmake -S . -B build \
  -DBUILD_DEALII_EXAMPLES=ON \
  -DAFEPACK_ROOT=$HOME/local/AFEPack \
  -DDEAL_II_DIR=/path/to/dealii

cmake --build build -j2

若只希望构建 deal.II 基线，可在显式启用 deal.II 的同时传入 -DBUILD_AFEPACK_EXAMPLES=OFF。

AFEPack 构建过程会调用 EasyMesh 生成 .n/.e/.s 网格文件。由于部分 EasyMesh 版本在成功生成网格后仍返回非零状态，项目的 CMake 辅助脚本会以输出文件存在且 节点数、单元数为正作为成功判据。

快速开始

完成 AFEPack 构建后，可以从以下几个算例开始：

# P1 Poisson 制造解及网格收敛阶
./build/poisson_convergence_afepack

# CG、Jacobi-PCG 与 AMG 求解器对比
./build/poisson_solver_comparison_afepack

# Galerkin 与 SUPG 对流扩散对比
./build/convection_diffusion_afepack

# Taylor--Hood Stokes 基线
./build/stokes_taylor_hood_afepack

# Navier--Stokes Newton 迭代
./build/navier_stokes_newton_afepack

多数程序无参数即可运行，并使用 build/meshes/afepack/ 中生成的默认网格； 部分程序支持传入网格基名和输出文件。例如：

./build/poisson_convergence_afepack \
  build/meshes/afepack/unit_square \
  build/poisson_afepack.dx

用于课堂分发的 24 个独立 AFEPack 算例位于 chinese/example/。每个算例都有自己的 Makefile、 源码依赖闭包和 EasyMesh .d 输入，可在对应目录直接运行 make 和 make run，无需使用项目顶层 CMake。

全部可执行目标以 CMakeLists.txt 为准。批量扫描入口位于 scripts/，脚本名称对应具体问题，例如 Reynolds 数、黏性系数、 网格细化和再附着长度扫描。

验证

运行当前构建目录中的全部顶层可执行文件：

bash scripts/verify_examples.sh build

脚本默认给每个程序 180 秒，并将完整输出写入 /tmp/fem_verify_examples.log。可通过环境变量调整超时或检查可执行文件数量：

TIMEOUT_SECONDS=300 EXPECTED_COUNT=116 \
  bash scripts/verify_examples.sh build /tmp/fem_verify_examples.log

EXPECTED_COUNT=116 仅适用于只启用 AFEPack 且所有目标均已构建的配置；两套实现 同时启用时应按实际构建目标数设置。检查原书覆盖表中引用的源文件、目标和脚本：

bash scripts/check_book_coverage.sh build

高分辨率流动算例耗时和内存占用明显高于基础验证，不建议把它们作为日常快速检查。

编译中文讲义

仓库已包含生成的 chinese/fastit.pdf。构建过程会从 refs/fastit.pdf 自动提取原书插图，再运行 XeLaTeX 与 BibTeX：

make -C chinese
make -C chinese audit      # 检查溢出、未定义引用和插图数量
make -C chinese clean      # 清理辅助文件
make -C chinese distclean  # 同时删除生成的 PDF

第 5--8 章的公式编号以原书 PDF 为基准，清单保存在 chinese/references/equations.tsv。新增或调整公式时应使用 equation、align 和 \label{eq:章.序号}，正文统一通过 \eqref 引用；不要直接录入 (5.1) 一类编号。make -C chinese audit 会检查编号全集、重复/缺失标签、编译后的 实际编号以及硬编码引用。

结果与维护约定

• 数值结果、覆盖状态和较长的实验说明放在 docs/，README 只保留稳定入口。
• 新增 C++ 算例时，应同步更新 CMakeLists.txt 和 docs/book_coverage.tsv。
• 新增网格时，将 EasyMesh 输入文件放在 meshes/afepack/，并在 CMake 网格列表中注册。
• 不提交 build/、运行日志和临时数值输出；可复现的汇总数据放在 docs/。

参考资料

Howard C. Elman, David J. Silvester, Andrew J. Wathen, Finite Elements and Fast Iterative Solvers: with Applications in Incompressible Fluid Dynamics, Oxford University Press.