开源CFD框架BASILISK指南：自适应网格与VOF多相流仿真实践

简介：BASILISK 是一款面向蛋白质结构研究与生物信息学领域的开源侧链构象分析工具，其核心思路是用概率模型描述氨基酸侧链在连续χ角空间中的构象，而不是依赖传统旋转异构体库的离散近似，适合需要精细化侧链建模的科研人员与计算化学学习者。该下载包共 27 个文件，以 24 个 Python 脚本为主体，覆盖角度计算、结构评估、隐马尔可夫模型和似然推理等模块，并附带安装说明、许可证与包元数据文件，压缩后整体仅 72KB。代码按功能拆分为多个子模块，结构便于对照学习；已有 305 人学习下载。从源码可看到概率密度函数构建、骨架依赖侧链分布等关键实现，便于理解模型如何从 PDB 实验结构学习参数并用于结构预测或稳定性分析；开源特性也允许按需修改和扩展。 如果你跟我一样，被商业CFD软件高昂的授权费、动不动就得重新画的网格、以及藏在菜单后面的离散格式折磨过，那我建议你认真看看BASILISK这个开源项目。BASILISK是一个完全开源的流体动力学仿真框架，团队这几年在气泡、液滴、多相流、波流相互作用这些方向用得非常狠。它能直接求解不可压缩Navier-Stokes方程，内置VOF界面捕捉和自适应网格细化，还可以拼装出浅水波、弹性体、凝固相变、多孔介质等各种求解器。源码完全公开，官方教程、算例脚本、文档都在线放出来，适合想复现文献、做毕业设计、或者单纯想搞明白CFD底层是怎么跑起来的人。

从2020年开始我陆陆续续用它做了不少算例，从最初在虚拟机里配置环境到后面跑两相流大变形、液滴碰撞，踩过的坑不少，但也确实被它的自适应性震撼到了。这篇文章不打算复制官方文档，只聊我自己理解最深的东西：它是怎么设计的、关键数值原理是什么、怎么快速跑通第一个算例，以及那些文档里不会明说的教训。

1. 认识BASILISK的"开源基因"与设计逻辑

1.1 它从哪来，为什么值得信任

BASILISK的源头可以追溯到Gerris——一个曾经在学术圈很流行的二维/三维流体求解器，作者Stéphane Popinet主导了整个架构。BASILISK可以看作Gerris的彻底重写，保留了四叉树/八叉树网格的思想，但代码更模块化、更易扩展，文档也更系统。项目托管在GitLab上，所有源码和文档一起发布，没有"社区版/专业版"的割裂，这一点在CFD开源圈里其实挺难得。

我选择它还有一个很实际的原因：学术参考案例非常多。你在期刊上看到的气泡上升、液滴撞击壁面、Rayleigh-Taylor不稳定性，很多都在官方examples有对应脚本，直接拿下来改参数就能做参数化研究。对科研人员来说，复现别人的结果是最快的学习路径，BASILISK把这条路径铺得很平。

1.2 树形自适应网格：省掉的不仅仅是一个网格生成器

传统CFD做复杂几何时，贴体网格生成能占掉整个项目一半时间。BASILISK用的办法完全不同：它在物理域上布置一个四叉树（二维）或八叉树（三维）网格，每个网格单元的疏密可以随时调整。界面附近、涡量大的区域自动加密，流动平坦的地方自动粗化，整个过程中不需要人工去"画网格"。

这个思路跟游戏里的LOD（细节层级）很像：你在远处看山时是低模，走到近处才会加载高精度纹理。自适应网格的加密准则由物理量的小波估计来驱动，比如adapt_wavelet({f, u}, ...)，它同时看相分数f和速度u的局部变化，变化剧烈的地方多加密，变化平缓就解粗。这样可以让总网格量维持在相对小的规模，实测下来比固定均匀网格省几倍内存很正常。

1.3 用头文件"组装"一个求解器

BASILISK最特别的一点是：它不是一个装入bin目录的黑盒软件，而是一堆精心设计的C头文件模块。你写代码时用#include "navier-stokes/centered.h"引入不可压缩流求解器，用#include "vof.h"引入界面追踪，用#include "two-phase.h"定义两相物性。qcc这个编译器会把它们和你的主程序编译在一起。

这种"搭积木"方式给了我极大自由度。想加表面张力就加tension.h，想加重力就加gravity.h，想模拟多孔介质就换darcy.h。因为所有模块都是编译期展开，运行时没有额外抽象层开销，性能上也不吃亏。缺点就是初学者会有点懵：原来写CFD程序还能这么"随性"？别急，后面我会用一个完整算例带你走一遍。

2. 核心机制拆解：自适应、界面追踪和稳定性

2.1 小波加密到底在做什么

有些朋友以为自适应就是"梯度大就加密"，其实没那么简单。BASILISK里的adapt_wavelet用的是Haar小波变换思想：对每个待加密场在每个方向做两次差分，估计场在更高分辨率下的插值误差，误差超过阈值就细分，低于阈值就粗化。如果多个场同时传给adapt_wavelet，耦合的加密要求会合并，所以你在C代码里常看到这样的写法：

event adapt (i++) adapt_wavelet ({f, u}, (double[]){0.001, 0.01, 0.01}, maxlevel = 9, minlevel = 5);

这里的{0.001, 0.01, 0.01}分别对应f、ux、uy的误差阈值，单位是"物理量在当前网格上的许用波动幅度"。阈值越小越精细，计算量也越大。maxlevel限制最细层数，minlevel保证最粗也不能低于某一级，否则空旷区域网格太大，时间步长会被拖得很长，得不偿失。

2.2 VOF界面捕捉：为什么它比Level Set更"守恒"

BASILISK处理界面流动时默认使用VOF方法。核心变量是一个在0到1之间的相分数f：f=1表示全液体，0表示全气体，界面就在0到1过渡的地方。每个单元内部用一条平面段（二维）或平面片（三维）近似重构界面，再通过几何运算法精确计算对流通量，这就是PLIC几何重构。

与Level Set这类基于符号距离函数的界面方法相比，VOF的最大优势是质量守恒性非常好——液滴分裂、合并、飞溅这类大变形过程跑很久，总质量和初始质量差别通常很小。缺点是界面的曲率计算精度依赖网格分辨率，所以通常会把界面区域的网格加密到较高层级。这也是为什么BASILISK在默认算例里几乎都叠加了f场上的自适应加密。

2.3 时间步长不是越大越好

用BASILISK跑两相流时，计算自动推进会遵守各种CFL约束，比如dt <= CFL * dx / |u|max、表面张力约束dt <= sqrt(rho * dx^3 / (2 * pi * sigma))、粘性约束dt <= dx^2 / (2*nu)。默认CFL是0.8，但表面张力占主导的算例，我一般手动调小。

另外，如果你自己写了源项或强外力，BASILISK不会自动感知这些新物理过程的稳定性限制，需要手动限制时间步，否则很容易在初始阶段直接产出NaN。写自定义事件时一定要记得用dtnext()而不是直接给dt赋值，这才是安全的推进方式。

3. 实操全流程：从空环境到跑出第一张图

3.1 准备环境：Ubuntu上的一次性配置

以Ubuntu为例，安装依赖包后克隆源码、设置环境变量，就能开始写代码了。

sudo apt update sudo apt install -y gcc make python3 gsl-bin libgsl-dev \ libglu1-mesa-dev freeglut3-dev libosmesa6-dev ffmpeg \ imagemagick gnuplot git clone https://gitlab.com/basilisk-fr/basilisk.git $HOME/basilisk export BASILISK=$HOME/basilisk export PATH=$PATH:$BASILISK

简单说明几个点：libgsl是BASILISK数值运算依赖的GNU科学计算库；freeglut和libglu是为了visualization模块，不做三维可视化可以省略；python3用于部分文档生成工具和qcc本身可能调用的脚本。环境变量写进~/.bashrc后重开终端即可。

3.2 第一个算例：二维液滴松弛

这是一个非常适合上手的经典例子：一个圆形液滴放置在静止流体中，由于表面张力作用会慢慢松弛变形，最终保持几乎圆形。代码不到四十行：

#include "navier-stokes/centered.h" #include "vof.h" #include "two-phase.h" #include "tension.h" #include "view.h" double R0 = 0.1; int main() { size (1.0); origin (-0.5, -0.5); init_grid (256); rho1 = 1000.; rho2 = 1.; mu1 = 0.1; mu2 = 0.001; f.sigma = 0.07; run(); } event init (t = 0) { fraction (f, sq(x) + sq(y) - sq(R0)); } event adapt (i++) { adapt_wavelet ({f, u}, (double[]){0.001, 0.005, 0.005}, maxlevel = 9, minlevel = 5); } event pictures (t += 0.01; t <= 1.0) { output_ppm (f, file = "drop.ppm", min = 0, max = 1, linear = true); }

这里面值得注意的几点：fraction函数用解析几何公式初始化相分数；rho1/mu1表示液体相密度和动力粘度，rho2/mu2为气相参数；f.sigma是表面张力系数；output_ppm在计算过程中每0.01个时间单位输出一帧界面图。linear = true表示双线性插值采样，出图更平滑。

3.3 编译、运行和结果检查

在drop.c所在目录执行：

qcc -O2 -Wall -o drop drop.c -lm ./drop > log 2>&1

在终端里你会看到类似这样的推进信息：

step: 12 t: 0.021 dt: 0.0017 grid: 3488 cells step: 25 t: 0.043 dt: 0.0012 grid: 4120 cells

网格单元数会随自适应不断变化，这正是四叉树网格的直观表现。跑完后目录下有一堆drop.ppm文件，用ImageMagick批量转成png：

for f in drop*.ppm; do convert $f ${f%.ppm}.png; done

我一般还会顺手统计一下界面面积的变化来验证守恒性，这个可以用output_facets把界面导出成gnuplot格式，再用awk统计总长度。官方教程里也有类似的脚本模板，照着改就行。看到液滴形状保持稳定、不剧烈畸变，就说明第一步走通了。

4. 调试与避坑：我踩过的编译和数值问题

4.1 编译与配置问题速查表

这部分问题大多不是BASILISK本身复杂，而是新环境少装了东西。建议初学者运行官方examples里最基础的cavity.c，能编译通过就说明基础环境OK。

4.2 数值发散时我的三个排查顺序

第一，先把时间步压下来。在表面张力、两相密度比超过100的场景，CFL建议直接调到0.2以下：

event stability (i++) dt = dtnext (0.2 * 0.001);

第二，看自适应阈值是否过小。当你把adapt_wavelet的误差阈值设到1e-4以下时，界面附近网格会疯狂细化，单元数指数增长，单步时间被网格尺寸拖得极小，计算直接卡死，读日志时看到grid数字指数增加基本就是这个原因。

第三，检查初场是否满足连续性。用解析公式初始化速度场时，必须保证通量守恒（divergence-free）。有一回我模拟一个旋转流场，初始速度给的是单纯半径函数，结果前几步速度场就被压力和投影算子修正得面目全非。这类问题不是BASILISK的bug，而是初始条件物理不自洽。

4.3 并行和跨环境经验

BASILISK支持MPI，编译时加-D_MPI=1，运行用mpirun -np 4 ./drop。实测下来，在自适应网格场景下MPI并行效率还比较稳定，因为它自带动态负载平衡，不必像非结构网格求解器那样手动分区。但要注意：输出IO如果每个进程都写一个大文件，会严重拖慢计算。我建议用process相关的输出函数，或把结果统一汇总后再写盘。

另外，我个人强烈建议在Docker或WSL2里跑BASILISK。它的代码没有GUI依赖，纯命令行在Linux下最省心。如果以后要用basilisk-view看三维结果，再找个有图形界面的环境也不迟。

5. 开源生态：从复现案例到改造代码

5.1 官方文档是最好的"抄作业"来源

BASILISK官网的Tutorial和Examples质量非常高，每篇文章都带可运行的源代码、解释和结果图。遇到不懂的模块，用站内搜索功能直接翻源码，比看二手博客靠谱得多。社区邮件列表也保留了大量历史讨论，很多疑难杂症在里面都能搜到答案。

开源项目的另一个隐形福利是版本可控。git pull可以随时更新，想回到稳定版本切tag即可。我自己一般会固定一个版本跑完整个课题，避免更新引发的行为变化。

5.2 自己定义一个标量输运模块

如果算例需要加一个温度场或浓度场，BASILISK的处理方式很直接：声明一个scalar T[]，再用advection和diffusion模块推进它的对流和扩散。核心代码可以抽象成这样：

#include "advection.h" #include "diffusion.h" scalar T[]; event tracer_advance (i++) { advection ({T}, u, dt); diffusion (T, dt, D = 0.001); }

这样写的好处是物理方程和网格操作完全解耦，你不需要关心底层四叉树是怎么遍历的。BASILISK已经帮你把树形网格上的梯度、通量、约束都封装好了，你只需要像描述物理过程一样写代码。想改方程，改的就是这几行，而不是解剖一个大型框架。

6. 一点个人的总结

我用了两三年BASILISK之后最深的感受是：开源CFD工具的价值不只是省了授权费，而是让你有机会真正理解数值方法在具体网格上是怎么落地的。你调adapt_wavelet的时候，会逐渐意识到网格自适应并不神秘；你改stability事件时，会重新想起CFL和表面张力约束这些课本知识。这些都很难在商业黑箱软件里体会到。

最后再分享一个小技巧：跑正式算例前，先做一个低分辨率、短时长的"冒烟测试"，用最小的网格、最少的时间步看代码逻辑能不能跑通。确认没有语法错误、边界条件设置合理、图像输出正常之后，再调高分辨率去跑长期模拟。这样既能省出大量试错成本，也能帮你更早发现物理模型选错的问题。BASILISK本身的学习曲线不算陡，真正陡的是你对流动问题本身的理解。希望这篇分享能让你少走点弯路，早点跑出自己满意的算例。

本文还有配套的精品资源，点击获取