deali.II 入门教程：从网格生成到自适应细化，带你跑通 step-1

1. 学 deal.II 之前，先想清楚它到底解决什么问题

很多人一听到“有限元”三个字，第一反应是 ANSYS、Abaqus 这类商业软件，或者是用 MATLAB 手写一个桁架程序。我跟 deal.II 打了一段时间交道之后，最大的感受是：它跟商业软件完全不是一个赛道，跟你用 MATLAB 自己玩也不是一回事。deal.II 是给“需要自己掌握有限元底层逻辑、又想站在一个成熟框架上做研究”的人准备的。它本质上是一个用 C++ 写成的开源有限元库，不是一个点开界面就能划网格、加边界条件的软件。

step-1 是 deal.II 官方教程里的第一个算例，名字起得很朴素，内容也确实是“热身”——它不会让你求解任何偏微分方程，只做两件事：生成网格，以及展示网格细化的效果。但你千万别小看这个热身，我见过太多人直接跳过 step-1 去啃 step-3、step-4，结果连Triangulation和active_cell_iterator这种最基础的对象都没搞明白，越往后越痛苦。step-1 就是用来把“网格”这个有限元的地基打实的。

适合读这篇内容的人有三类：第一类是刚接触有限元编程、想找一个比 MATLAB 手写更专业路径的学生或工程师；第二类是已经会用 COMSOL、Abaqus 这类工具，但想知道底层网格结构到底是怎么回事的人；第三类是纯粹被 C++ 模板和一堆抽象类吓住，想找一个低门槛入口的初学者。这篇文章我会从“为什么值得学”讲起，一直讲到我实际跑通 step-1 的每一步细节，包括编译、运行、可视化、改参数，以及那些官方文档里没写清楚、我踩过坑之后才明白的事情。

2. 环境搭不起来，后面全是空谈

2.1 三种安装方式怎么选

跑 deal.II 的 step-1，第一步不是理解代码，而是把环境弄出来。我试过几种安装方式，经验如下：

第一种是直接用系统包管理器安装，比如 Ubuntu 上执行sudo apt install libdeal.ii-dev。这种方式最省事，几分钟就能装完，但问题也很明显：仓库里的版本通常偏老，而且不会帮你配置好 examples。如果你只是想先跑通一个 demo 感受一下，可以这么干。但如果你后面要系统学完整个 tutorial 系列，我建议你别走这条路，因为新版 deal.II 的 API 变化不小，教程代码经常依赖新特性。

第二种是用官方提供的 Docker 镜像，命令很简单：docker pull dealii/dealii，然后直接进容器跑。这个方案的好处是你不用折腾一大堆依赖，坏处是你要熟悉 Docker 的基本操作，而且图形化界面、文件挂载这些事情多少要花点时间。我自己第一次接触时，就靠这个镜像跑通了环境，强烈推荐给赶时间的人。

第三种是源码编译。这也是我最终选择的路线，因为后续要调试、要看源码、要改库内部行为，源码编译是绕不开的。deal.II 的编译依赖包括 CMake、GCC 或 Clang、TBB 或 MPI 等，不要被这堆依赖吓到，实际装起来比我预想的顺利。先装好依赖，再下载 release 源码包，进目录执行mkdir build && cd build && cmake .. && make -j4，编译时间大概在二三十分钟左右，取决于你的机器性能。

2.2 源码编译的全流程与关键参数

我第一次编译 deal.II 的时候，卡在一个细节上：编译出来的库默认只启用 Debug 模式，跑 step-1 没问题，但后面算真实问题会发现性能完全不能看。这里要补充说明，deal.II 支持 Debug 和 Release 两种编译模式，主要区别在于断言检查是否开启。Debug 模式下，每次网格操作都会带大量检查，适合学习调试；Release 模式关掉了大部分检查，代码执行快得多。建议学习阶段用 Debug，等到了真正计算时再编一个 Release 版本。

具体编译命令，我把最常用的参数放在这里：

git clone https://github.com/dealii/dealii.git cd dealii mkdir build && cd build cmake -DCMAKE_BUILD_TYPE=Debug \ -DDEAL_II_COMPONENT_EXAMPLES=ON \ -DDEAL_II_COMPONENT_DOCUMENTATION=OFF \ .. make -j4

DEAL_II_COMPONENT_EXAMPLES=ON这个参数很关键，它会帮你把官方 examples 目录配置好，教程的源文件和 CMakeLists.txt 都会生成，省得你手动去下载。我当时没开这个选项，导致后面还要单独去 GitHub 上把 examples 拉下来，多绕了一圈。

如果你用的是 macOS 或者 Windows + WSL，依赖安装方式会有差异，但核心的 CMake 流程基本一致。Windows 原生编译 deal.II 是比较折腾的，我劝你别轻易尝试，老老实实装个 WSL 或者虚拟机，省下来的时间足够你跑完 step-1 到 step-5。

2.3 跑通 step-1 的三种姿势

环境装完之后，你手头其实有三种方式可以运行 step-1：

第一种是直接进入 deal.II 源码目录下的examples/step-1，执行：

mkdir build && cd build cmake -DDEAL_II_DIR=/path/to/dealii/build .. make ./step-1

这里要特别注意DEAL_II_DIR指向哪里。我一开始以为要指向源码根目录，结果 CMake 一直报找不到 deal.II 配置，后来才发现应该指向你编译时创建的build目录，因为deal.IIConfig.cmake这类文件是在 build 目录下自动生成的。

第二种是用 Docker：

docker run -it --rm -v $(pwd):/workspace dealii/dealii:latest cd /workspace

然后把examples/step-1复制到当前目录，进去执行编译命令。挂载目录的方式很方便，你在宿主机上编辑代码，容器里编译运行，两边文件是同步的。

第三种比较冷门，但很适合快速看效果：deal.II 官方提供了一个在线文档，里面 step-1 的每个代码块都可以直接运行查看输出，不用在本地装任何东西。这个适合在地铁上、手机上随手翻一翻，建立直观印象。真正动手还是建议本地跑一遍。

3. step-1 的代码到底在干什么

3.1 全局细化与网格输出

step-1 的代码量不大，但信息密度很高。第一部分用GridGenerator::hyper_cube生成一个最简单的二维正方形网格，然后调用triangulation.refine_global(4)做四次全局加密，最后用GridOut写成了 VTK 文件。

这段代码看着简单，但背后有很值得琢磨的东西。你创建出来的Triangulation<2>对象，内部其实不只保存了最细的网格，还按照“层”的概念保存了每一级加密前的网格。在 deal.II 里，这个数据结构叫做“自适应八叉树结构”，它把网格的层次关系全部记住了。这跟你用 MATLAB 里的简单网格工具不一样，那是每次重画一张新的网格表，而 deal.II 里细化一次网格，父单元和子单元是有关联的，这在后面做多重网格、误差估计时都是基础。

我强烈建议你在跑完 step-1 之后，顺手做一个实验：把refine_global(4)改成refine_global(2)和refine_global(6)，分别生成输出文件，对比一下文件大小和网格数量。这样你就能直观理解“指数增长”的含义，对计算量有一个身体记忆。

3.2 自适应细化的核心思路

step-1 的第二部分是精华所在，它演示了“局部细化”而不是全局细化。所谓局部细化，就是只在网格的某个局部区域把单元切得更细，其他地方保持粗网格。代码的做法分两步，第一步遍历所有活动单元（active cell），判断它是否满足某个条件，满足就调用cell->set_refine_flag()；第二步调用triangulation.execute_coarsening_and_refinement()，真正执行细化。

这个模式我后来发现几乎是所有 deal.II 程序的通用骨架：标记（flag）和操作（execute）。不只是网格细化，后面做自适应加密也遵循一样的思路。你用set_refine_flag做标记，用execute_coarsening_and_refinement执行，中间不会立刻生效。这种延迟执行的设计有很多好处，比如可以避免一个单元刚细化又被另一个条件给杀掉这种冲突。

step-1 里选择细化区域的条件是“离某个参考点越近越细化”，但实际工程中这个条件通常是误差估计器，比如 KellyErrorEstimator。你先算出误差大的区域，把那些单元标出来，再加密。这就是自适应有限元最朴素的理解。

3.3 输出文件：VTK 到底是个什么东西

step-1 运行之后会生成.vtk文件，很多人看到这个后缀就懵了。有没有一种可能是，你把文件名字改成.csv然后用 Excel 打开？别笑，我还真见过这么干的。

VTK 是 Visualization Toolkit 的缩写，是科学计算可视化领域非常通用的文件格式。deal.II 把网格几何信息和节点数据写在 VTK 文件里，然后用 ParaView 打开就能看到彩色网格。这一步背后的知识你不需要完全搞懂，但建议你用文本编辑器打开一个.vtk文件看一眼，会发现里面其实是一堆坐标点、单元连接关系，还有可能有一堆标量数据。这能帮你建立“文件格式只是数据存储方式”的直觉。

我自己的习惯是用 ParaView 查看，因为它免费、跨平台、能处理大规模网格，而且可交互地切剖面。如果你暂时不想装 ParaView，也可以把输出格式改成 GNUPLOT 格式，step-1 里有一行代码就是做这个的，直接用 gnuplot 或者 matplotlib 画。

4. 实操验证：修改参数、观察现象、验证逻辑

4.1 从 2D 到 3D 该怎么改

step-1 默认生成的是二维网格。我第一次跑完，脑子里冒出的问题就是：三维网格怎么生成？答案出乎意料地简单，把Triangulation<2>改成Triangulation<3>，再在GridGenerator::hyper_cube后面加上一个参数指定它是三维的立方体，剩下的流程几乎一模一样。这就是 C++ 模板给你带来的便利：一套代码，多维复用。

但这种改动只看表面是体会不到精髓的。你最好动手试一下：写一个三维的版本，调refine_global(3)，然后看看输出文件的体积。二维加密 4 次单元数是 256 个，三维加密 3 次单元数是 512 个，但三维网格的几何信息量是二维的好几倍，文件大小肉眼可见地增长。这就给你一个重要的直观印象：高维问题的计算量是指数爆炸的，这也从另一个角度解释了为什么需要自适应加密。

以下是三维版本中最核心的一小段代码，其他部分几乎不用动：

Triangulation<3> triangulation; GridGenerator::hyper_cube(triangulation, -1, 1); triangulation.refine_global(3);

4.2 在 ParaView 里看懂网格

使用 ParaView 打开 step-1 生成的 VTK 文件后，选一下Wireframe显示模式，你就能看到网格的边；切到Surface模式，看到的则是单元面。建议把每次细化级别的网格打开，用不同的颜色区分，你会发现加密后网格更密的地方跟你的细化标准是对应的。

这一步看起来很“观赏”，但价值在于验证你的直觉。比如你让网格在右上角局部加密，打开 ParaView 后确认加密区域真的在右上角，间谍了？其实不需要间谍，这是你自己的程序，必须亲眼看到结果才能确认逻辑没有写错。对于学习有限元编程来说，可视化不只是为了演示，更是调试的重要手段。

4.3 观察细化次数与单元数目的对应关系

为了帮助掌握网格加密的规律，我把不同维度下全局细化次数与单元数的对应关系整理成了下面这张表，你可以对照自己的运行结果检查：

表格里 3D 的单元数增长很明显，看到 4096 这个数字时你可能会意识到，如果无脑细化到 6 层，就是 26 万个单元，这个规模在普通笔记本上已经开始有点吃力了。这就是为什么 half 理论里讲“自适应加密可以节省大量计算资源”，第一步的实验就能让你完全理解这句话。

5. 常见问题与排查技巧实录

5.1 编译报错不知道从哪里查

step-1 的编译错误常见的有两类。第一类发生在 CMake 阶段，最常见的报错是“Could not find deal.II”。这个问题的头号原因就是DEAL_II_DIR设置不对，或者根本没有设置。解决办法是在 CMake 命令行里显式指定：

cmake -DDEAL_II_DIR=/path/to/dealii/build ..

第二类发生在 make 阶段，通常是编译器语法错误。如果你用的是旧版 GCC，或者 C++ 标准设置不对，会出现模板实例化失败这类报错。deal.II 7.3 之后要求 C++17，所以确认编译器版本至少 GCC 9 以上。遇到模板报错不要慌，往前翻几行看第一个 error，那里往往指向真正的问题。

5.2 运行期常见问题：断言与内存

运行 step-1 本身很轻量，但如果你改了参数，比如把refine_global的次数调到很大，可能会遇到内存不足。这里补充一个排查技巧：deal.II 在编译时打开 Debug 模式的前提下，运行期如果违反某些操作规则会在屏幕上打印一串带DealIIAssert字样的错误信息。很多初学者看到这种红字就慌了，其实有经验的人都知道，这些信息恰恰是在帮你定位错误。你应该把注意力放在最后一行，它通常会写清楚“哪个文件第几行，哪个断言失败了”。

比如你试着在 refine 之前去访问一个已经不存在的 cell，这个断言就会触发。别问我怎么知道的，这种错误我在写新手练习时踩过很多次。

5.3 后续递进：从 step-1 你能自然连接到什么

既然认真学完了 step-1，下一个问题自然是“接下来学哪个”。我的建议是 step-2 和 step-3，不是因为它们简单，而是因为它们承接得非常顺。step-2 会带你学会怎么查看 deal.II 的文档，这直接解决“这个类怎么用”的困惑；step-3 开始真正求解拉普拉斯方程，会用到你在 step-1 里亲手生成的网格。

学习 step-1 的过程让我回头反思传统有限元教学：很多人先学 Galerkin 变分、先学形函数插值，最后才动手编程，导致一开始脑子里只有公式没有图像。而 deal.II 的路线正好反过来，先用 step-1 建立网格的直觉，再慢慢填充数学细节。我个人的体会是，这种“先看见、再算清”的方式，反而比纯推导省力得多。

6. 给新手的两个额外建议

6.1 动手写一个“最小变体”

读完这篇文章、跑完官方 step-1 之后，我不建议你立刻去啃下一个教程。更有效的做法是，把 step-1 的代码改成你自己想要的样子。举个例子：把hyper_cube改成GridGenerator::hyper_ball，或者把输出格式改成.eps，或者改成一个不规则的 L 形区域。改出一个小变体并跑通，你就会绕过“照着敲一遍”的虚假成就感，真正开始理解每一步代码的含义。

我自己当时改了一个案例，把二维正方形区域改成一个中间挖了圆孔的板，试着做局部加密。这个改动在理论上一句话就能描述，但实际操作中却牵扯出很多细节，比如怎么设定一个子区域、怎么判断一个 cell 是否在圆内、怎么指定圆心条件和半径。这个过程比官方教程本身更能教会你东西。

6.2 至少读一遍代码注释

deal.II 官方 examples 的代码注释写得极其详尽，step-1 的源文件里几乎每一行重要代码都有对应解释。很多人拿到代码后直接拷贝编译，看都不看注释，我觉得浪费了最宝贵的教育资源。建议你一行一行读一遍，把不懂的英文术语记下来，把不理解的类名去文档里查一遍。这个过程花不了半小时，但看完之后你对Triangulation、GridGenerator、GridOut这几个核心类会有真正的理解，而不仅仅是“见过名字”。

我曾经硬着头皮读了半小时 step-1 的注释，读完之后去看 step-3 的代码，突然觉得顺眼了很多。很多概念是相通的，step-1 里没有的，step-3 就会在注释里再解释一遍，到那时你会发现“原来这个类还能这样用”，这种顿悟正是源码注释的价值所在。

从 step-1 出发，你会发现 deal.II 的世界其实没有想象中那么高不可攀。它只是一套把有限元数学翻译成 C++ 对象的工具，你需要做的不是记住每一个类名，而是理解它为什么要这样设计。等你开始接触自适应误差估计、多重网格方法时，再回头看 step-1 里那些网格细化操作，你会意识到，原来当时已经种下了未来进阶的种子。