chanlier都说PETSc难调，其实很多痛苦都源于没把它的调试选项用明白。PETSc作为科学计算领域最常用的并行数值求解库之一，功能强大是事实，但报错信息晦涩、日志输出庞杂、一不留神就在并行环境下出个段错误也同样是事实。这篇文章就把我在实际项目中反复使用、验证过的PETSc调试选项系统梳理一遍，讲清楚每个选项背后的作用逻辑和适用场景，希望能帮你少走些弯路。
1. 搞清楚PETSc调试选项的基本逻辑
1.1 为什么PETSc程序调试起来特别费劲
先说点背景。PETSc的代码是高度抽象和分层的，从顶层的SNES非线性求解器，到下面的KSP线性求解器，再到PC预处理和底层的Mat、Vec数据结构，每一层都会对输入参数做校验，也会在内部分发大量状态信息。这种设计的好处是功能模块化，坏处就是——一旦某个环节出问题，错误往往不会第一时间暴露在真正出错的代码行，而是被层层传递到某个看起来毫不相关的地方才爆出来。
举一个我实际遇到过的例子。有一次我在一个三维不可压缩流场的求解程序里，发现KSP迭代残差始终不下降，一开始怀疑是预处理选型问题，后来逐步排查才发现是边界条件的Vec赋值在某个MPI进程上根本没有执行对。PETSc不会告诉你是赋值出了问题，它只会告诉你“求解器在第42步发散”。类似这种问题，如果没有系统化的调试手段，基本就是在大海捞针。
PETSc的调试选项正是为这类场景设计的。它们不只是一个简单的“打开日志开关”，而是一整套从错误捕获、内存检查、性能剖析到运行时行为追踪的工具链。理解这些选项的一个关键前提是先弄懂PETSc的选项系统。
1.2 选项系统的三个入口
PETSc的选项系统通过三个途径接收参数：
- 命令行方式：
./app -ksp_type gmres -pc_type bjacobi - 配置文件方式：
./app -options_file myopts.txt - 代码内嵌方式：
PetscOptionsSetValue(NULL, "-ksp_type", "gmres")
三种方式优先级从高到低略有区别，但通常来说命令行覆盖配置文件，代码内嵌在运行时设置。调试过程中最常用的还是命令行方式，改动不用重新编译，效率高很多。
有个小技巧值得一提：在程序里调用PetscOptionsSetValue时，如果该选项已经在命令行中被设置过，代码内嵌的方式会直接覆盖命令行值。但这个行为在PETSc 3.14之后的版本中有所调整，具体要看PetscOptionsSetValue的第四个参数opt的取值（PETSC_OPTIONS_FIRST还是PETSC_OPTIONS_LAST），建议有版本强迫症的朋友去查一下对应版本的man page确认行为，避免踩坑。
无论用哪种方式设置调试选项，都建议先在程序初始化阶段调用PetscOptionsView把最终生效的选项打印出来看一眼。这一招在排查“为什么我设置了选项但程序没反应”的时候特别有效，因为很多时候不是选项没生效，而是你在程序代码里手动设置求解器类型时把命令行选项覆盖掉了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 追踪选项消费情况：-options_left与-options_table
2.1 -options_left：找出没被消费的选项
刚开始用PETSc的时候，我经常遇到一个诡异的情况：明明在命令行写了-ksp_max_it 5000，程序跑起来求解器迭代次数上限却还是默认的10000。排查了半天，最后用-options_left一看才发现，选项名拼错了——我写成了-ksp_maxits。
-options_left会在程序结束时打印出所有未被PETSc内部代码消费的选项清单。这个选项太有用了。PETSc通过PetscOptionsGetInt这类接口获取选项时，会从全局选项数据库中“取走”对应的键值。如果程序结束时有选项留在数据库里没被取走，说明这些选项要么拼写错了，要么对应的功能根本没有被调用。
实际操作时，在命令行加一个-options_left就可以了：
bash复制mpiexec -n 8 ./solver -options_left
程序跑完后会输出类似这样的信息：
code复制[0] PETSc Options left:
[0] -ksp_maxits (value 5000)
[0] -pc_factor_levels (value 2)
看到这些输出基本就能判定：我的拼写有问题，或者对应的代码分支没执行。这里有一个经验心得：当你怀疑自己设置了某个选项但没生效时，第一件事不是去查文档确认拼写，而是先跑一遍-options_left。这个动作几乎能解决一半的“选项不生效”问题。
2.2 -options_table：查看最终生效的参数组合
-options_left看的是“没被用的”，-options_table则是把最终生效的参数组合完整列出来。它跟PetscOptionsView的作用类似，但更彻底——它会遍历所有PETSc组件（每个KSP、PC、SNES、TS对象都会有一个自己的选项表），把每个对象的实际参数都打印出来。
这个选项在排查“为什么两个进程行为不一致”时非常有用。并行程序里如果每个MPI进程读到的配置文件不同，或者某段代码只在一个分支里设置参数，运行结果就会千奇百怪。用-options_table，每个进程都会打印一遍自己看到的参数组合，对比一下就能快速锁定是哪个进程的配置出了问题。
一个常见使用姿势：
bash复制mpiexec -n 4 ./solver -options_table -options_file runtime.opts
输出会按进程打印，例如：
code复制[0] KSP Object: 1 MPI processes
[0] type: gmres
[0] maximum iterations=10000
[0] tolerances: relative=1e-05, absolute=1e-50, divergence=10000.
[0] left preconditioning
[0] using nonzero initial guess
这里要提醒一点：-options_table会把每个MPI进程的内容全部打印出来，进程数多的时候输出量非常大。我一般习惯先用-options_table配合-options_left一起跑一个小规模case，确认配置无误后再上大规模计算，这样既不会浪费算力，也避免被刷屏的日志淹没。
3. 日志与轨迹：-info和-log_view的正确打开方式
3.1 -info不是“查看帮助”而是“打开运行时追踪”
很多新手会误以为-info是查看帮助信息的选项。实际上，PETSc的帮助信息是用-help或-h看的，而-info是把PETSc内部的分层日志信息实时打印到终端上。它的本质是开启PETSc内部所有PetscInfo调用点的输出，包括对象创建、矩阵装配、通信握手等过程。
这个选项在调试“程序卡在某个阶段不动了”这类问题时特别有用。比如并行程序启动后长时间没有输出，你无法判断是卡在MatAssemblyBegin等通信上，还是陷入某个循环里。加上-info之后，每个关键节点都会有输出，能直接判断程序执行到了哪一步。
举一个实际场景。我调试一个自适应网格加密的代码时，程序在第三步时间推进后就再无输出。加-info后看到：
code复制[0] PetscCommDuplicate: duplicating MPI_Comm 0x84000004
[0] PetscCommDuplicate: returning same communicator 0x84000004
[0] MatAssemblyBegin_MPIAIJ: Stash has 0 entries, local size is 1024
[0] MatAssemblyEnd_MPIAIJ: Stash has 0 entries, local size is 1024
[0] VecScatterBegin: VecScatter from 128 to 128, mode = SCATTER_FORWARD
最后一行停在VecScatterBegin，说明程序卡在通信上。再结合拓扑信息排查，很快锁定了网格迁移后进程邻居关系没更新的问题。
但要注意，-info的输出量极其惊人。在大规模并行下直接加到命令行，日志文件会以GB级别增长，严重拖慢计算速度。我通常的做法是在怀疑程序异常时先用少量进程加-info跑一遍，确认问题后立即去掉。如果在生产环境必须保留信息，可以用-info_log把信息写入文件而不是屏幕。
3.2 -log_view：性能剖析的核心工具
如果说-info是程序轨迹追踪器，那-log_view就是PETSc内置的轻量级性能剖析器。它会统计每个PETSc事件（Event）的调用次数、总耗时、平均耗时和通信开销，最终汇总成一张性能分析表。
这个选项在排查性能瓶颈时是救命稻草。我曾经排查过一个矩阵装配异常缓慢的问题，直觉以为是稀疏矩阵插入模式导致的，但加上-log_view后发现MatAssemblyBegin耗时占比高达40%，再仔细看是矩阵的非零结构预分配（预分配）没做好，导致装配过程中频繁触发动态内存重分配和通信。如果没有-log_view做数据支撑，这种问题靠猜根本猜不准。
典型用法：
bash复制mpiexec -n 16 ./solver -log_view -log_view_final
输出会按Stage组织。PETSc把计算过程分成了几个Stage，比如main、solve等，每个Stage下面列出了所有事件的时间统计。-log_view输出的核心字段包括：
Count：事件被调用的次数MaxTime：单次最长耗时MaxOverhead：单次开销（时间戳管理的额外花费）MaxTime列与MaxOverhead列的差异如果很大，说明事件嵌套层级过深或者计时器管理引入了过多开销
3.3 用-log_view_garbage和-log_view_memory排查内存问题
-log_view还附带两个加强版选项：-log_view_garbage会统计PETSc内部动态申请/释放内存的次数和大小，-log_view_memory会列出每个事件触发时PETSc已知的内存消耗。这两个选项叠加使用，可以比较准确地定位到某个事件是否是内存泄漏的源头。
需要说明的是，PETSc自身的内存统计并不覆盖你用malloc申请的内存，只统计PETSc内部通过PetscMalloc系列函数分配的内存。如果想同时追踪应用层的内存，建议结合valgrind或者AddressSanitizer一起使用。PETSc为此专门提供了--with-debugging=1编译选项，编译出的库会包含完整的内存检查支持，性能虽然会有一定下降，但调试阶段这是值得的。
4. 让错误“炸”得又快又准：错误处理相关的调试选项
4.1 -start_in_debugger：程序起点就挂上调试器
PETSc的调试选项里，最直接也最容易被忽视的就是-start_in_debugger。前面的-info和-log_view都是事后追踪，而这个选项是让你在程序启动的第一时间就进入调试器，方便你在初始状态还没被破坏前设置断点。
具体用法是在命令行指定调试器和调试器参数：
bash复制./solver -start_in_debugger gdb:port=1234
这个场景主要用于并行环境下某个指定进程需要单独调试的情况。你可以指定让哪个进程进入调试器，比如./solver -start_in_debugger gdb:port=1234:rank=2，这样只有rank 2的进程会自动挂上gdb等待连接，其他进程照常运行。配合gdb的set follow-fork-mode等设置，能比较精细地控制并行调试过程。
我自己平时用这个选项的场景，是在排查那种“只在特定进程数下才出现”的诡异问题。通过让目标进程挂起而其他进程继续执行，可以在不打断整体计算节奏的情况下对目标进程做单独诊断，比所有进程都停在断点要省心得多。
4.2 -on_error_attach_debugger：错误发生时再进调试器
如果不想在程序启动时就挂调试器，而是希望程序出错后再进入调试，可以用-on_error_attach_debugger。这个选项会让PETSc在检测到第一个错误时自动启动调试器并attach到当前进程。
这个选项对那种“运行很久之后才出错”的场景特别有价值。试想一个需要先迭代几百步才会触发浮点异常的求解程序，你用-start_in_debugger从头跟的话会累死，而-on_error_attach_debugger让你只在错误点获得调试环境。
用法示例：
bash复制./solver -on_error_attach_debugger gdb
当PETSc捕获到错误后，会跳转进入gdb交互环境，你可以在那里查看当前调用栈、变量值甚至内存内容。这里有一个关键技巧：要在gdb里持续追踪到错误源头，需要在进入调试器后先执行frame命令查看当前栈帧，然后逐层调用up往上回溯。PETSc的错误处理机制（SETERRQ宏）会把错误标记在出错的函数里，调用栈里能找到对应位置。
如果担心多个进程同时出错时调试器难以操作，可以结合MPI进程数控制，比如只在第0号进程上attach调试器，其他进程直接终止。这样至少能先把单进程的错误链摸清楚。
4.3 -on_error_throw_exception：把PETSc错误转成C++异常
如果你的代码是用C++写的，并且已经有一套成熟的异常处理机制，那-on_error_throw_exception会是你的好帮手。这个选项让PETSc在出错时不再直接调用MPI_Abort终止所有进程，而是抛出一个PetscException，你可以在自己的try-catch块中捕获它，做自定义的错误处理。
一个典型场景是参数扫描。假设你要在一个循环里用不同的物理参数反复调用PETSc求解器，某个参数组合可能导致数值发散、甚至矩阵奇异。如果没有这个选项，PETSc一发现奇异矩阵就直接MPI_Abort，整个扫描任务直接挂掉。有了-on_error_throw_exception，你可以在catch块中记录这个参数组合并跳过，继续执行下一组参数。
代码模式下需要配合PetscPopErrorHandler使用，示例如下：
cpp复制try {
set_stage_solve_and_post_step();
VecDestroy(&x);
KSPDestroy(&ksp);
}
catch (PetscException &e) {
// 记录异常参数，继续下一组计算
PetscPrintf(PETSC_COMM_WORLD, "Solver error: %s
", e.what());
}
不过这个选项有一些使用前提：你的PETSc必须启用了C++异常支持，即在configure时加入--with-cxx-dialect=C++11等参数，并且通常需要--with-debugging=1。如果没有正确配置，这个选项可能会在运行时直接报错。
4.4 错误码的解读和KSPGetConvergedReason
除了启动调试器的选项，PETSc还提供了一整套错误状态查询接口，最常用的就是KSPGetConvergedReason。这个方法返回一个枚举值，告诉你线性求解器是因为收敛（如KSP_CONVERGED_RTOL）还是发散（如KSP_DIVERGED_ITS）而终止。
实际调试中，不要只满足于“有没有收敛”，而是要仔细看收敛原因是哪个。比如KSP_DIVERGED_INDEFINITE_PC表示预处理矩阵不定，这通常意味着预处理器的构造有问题；KSP_DIVERGED_DTOL则说明残差增长过快，往往是问题本身条件数太差或者初始猜测有问题。
PETSc 3.14以后的版本的KSP迭代路径有了更多细节可选（比如KSPGetIterationNumber），但调试思路不变：先把每个阶段返回的状态码打印出来，再做对比分析。比如我常这么做：
c复制KSPConvergedReason reason;
KSPGetConvergedReason(ksp, &reason);
if (reason < 0) {
PetscPrintf(PETSC_COMM_WORLD, "KSP diverged, reason: %d (%s)
",
reason, KSPConvergedReasons[reason]);
}
这种打印对定位问题区间非常有帮助。如果求解器在早期迭代就发散，问题大概率在预处理或矩阵装配；如果坚持了很久才发散，要重点检查边界条件和时间步长。
5. 内存问题的定向追查：-malloc_debug与相关选项
5.1 -malloc_debug：PETSc自带的内存分配追踪
PETSc可以通过PetscMalloc系列函数管理内存分配，一旦启用内存调试，它会记录每次分配的调用位置、大小、是否释放等信息。命令行对应的开关就是-malloc_debug。
这个选项会显著增加内存和CPU开销，因为它需要在每次Malloc/Free时记录调用栈和元数据。但如果你在纠结“到底是哪一行代码导致了内存泄漏”这个问题，这就是最直接的答案了。程序退出时如果已经开启了-malloc_debug，PETSc会报告未释放的内存块及对应的分配位置，类似这样：
code复制[0]PETSC ERROR: Memory allocated at:
[0]PETSC ERROR: VecCreateSeq() line 234 in /path/to/petsc/src/vec/vec/interface/vector.c
[0]PETSC ERROR: main() line 78 in /path/to/myapp.c
这个输出会帮你精确定位到申请内存但未释放的代码行。顺带一提，PETSc在--with-debugging=1时默认开启内存调试，在--with-debugging=0时需要显式指定，这一点在生产环境优化编译时容易被忽略。
5.2 -check_pointer：检测野指针访问
除了内存泄漏，更让人头疼的是野指针。PETSc的-check_pointer选项会在每次通过PetscMemcpy、PetscMemmove等函数访问内存时检查指针是否在合法范围内。如果发现越界，会立即报错并打印调用栈。
我自己用这个选项最多的时候，是在做非结构网格并行重划分时。网格迁移过程中经常出现元素列表跨越了当前进程的局部范围，如果用了-check_pointer，在访问越界的那一刻就会直接报错并指出错误的指针地址和对应的分配上下文，比等程序在某个远端函数中崩溃后去回溯调用栈快多了。
注意，-check_pointer并不检查所有的内存访问，它只在PETSc自己的内存操作函数入口做检查。如果你的代码里直接用了裸指针运算并且越界，这个选项是抓不到的。这种场景就要靠valgrind或者AddressSanitizer了。
5.3 编译期内存检查的配合：--with-debugging与第三方工具
PETSc的configure阶段有一个贯穿始终的重要参数：--with-debugging=1/0。默认是1。这个选项不仅决定了PETSc库是否包含调试符号，还决定了一系列内置错误检查行为——比如数组索引越界、零除数、非法参数等。
如果是调试阶段，建议始终用--with-debugging=1编译的PETSc，并且搭配-malloc_debug。但要注意，即便有这些内部检查，PETSc也覆盖不了你应用层代码的所有动态内存问题。所以在遇到难以定位的内存错误时，我通常的做法是三层递进排查：
- 先用PETSc自带的内存调试选项（
-malloc_debug、-check_pointer）排除PETSc对象相关的问题。 - 再用
valgrind的内存错误检测（--tool=memcheck）跑小规模算例，确认是否有非法读写。 - 最后用
AddressSanitizer（-fsanitize=address）重新编译应用代码，缩小到具体代码行。
这三层叠加起来，绝大多数内存问题都能在半小时内揪出来。如果还不行，就要考虑是不是MPI通信缓冲区的问题了，那需要用到-start_in_debugger加调试器逐进程分析。
6. 浮点异常与数值不稳定的专项选项
6.1 -fp_trap：让NaN和Inf无处遁形
数值计算里最常见的“幽灵问题”就是NaN和Inf的传播。程序可能在一个时间步里某个量变成了NaN，但PETSc本身并不会直接报错——它会继续算，直到某次矩阵分解或求解过程中无法继续，才以一个莫名其妙的错误退出。
-fp_trap这个选项可以让PETSc在检测到浮点异常时立即中断，并定位到出现异常的代码位置。这个选项实际上是利用了底层硬件的浮点异常机制，相当于在关键操作时开启了FPU的异常陷阱。
用法：
bash复制./solver -fp_trap
开启后，一旦出现除零、溢出或无效操作，程序就会在异常点触发一个SIGFPE信号。需要提醒的是，这个信号有时候不是在你的代码行触发，而是在PETSc库函数内部触发，这时候要配合-on_error_attach_debugger才能在调试器中看到完整的调用链。
我在实际操作中遇到过一种情况：某个物理量在时间推进第500步出现NaN，但第499步看起来一切正常。这种问题靠-fp_trap能定位到具体哪一步、哪个函数，但往往需要再结合输出中间量才能理解为什么会产生NaN。一个高效的小技巧是配合PETSc的VecView或MatView在关键时间步吐出中间结果，或者在代码里临时加针对性的PetscPrintf，把可疑的物理量打印出来。
6.2 调试NaN时的辅助输出：-ksp_monitor与-ksp_monitor_true_residual
定位NaN的来源时，光知道“第500步出现NaN”还不够，最好能知道是在线性求解器的哪一次迭代开始出现异常。-ksp_monitor会实时打印每次KSP迭代的残差范数，-ksp_monitor_true_residual则打印真实残差（而非预条件残差）。
这两个选项输出的曲线能直观地反映问题：如果残差在某一迭代突然变成nan或者inf，那问题就锁定在这次迭代对应的矩阵-向量乘或预处理操作中。拿到这个迭代号后，再去对应代码段打点检查就精准多了。
举一个实际案例。我在调试一个可压缩流的隐式时间推进时，残差在迭代第20次左右开始振荡，再后来直接发散。用-ksp_monitor_true_residual后发现真实残差下降率在第18次迭代后开始恶化，进一步检查发现是对流项通量的Jacobian矩阵某一行赋值错了，导致矩阵不对称性异常。如果不用残差监控直接查代码，要排查的面会大很多。
6.3 用-ksp_view和-snes_view检查求解器配置
有时候数值问题不是代码bug，而是求解器配置不对。-ksp_view会打印线性求解器的完整配置信息，包括迭代方法、预条件器类型、容差设置、最大迭代次数等。-snes_view同理，是给非线性求解器用的。
这两个选项在调试“程序能跑但不收敛”的场景下几乎是必备的。我见过不少同行在代码里调了一堆参数但没生效，原因就是求解器配置被更高层的代码覆盖了。用-ksp_view一看，实际生效的配置跟预期完全不一样——这种情况下再怎么调参数都是白费力气。
用法：
bash复制./solver -ksp_view -snes_view
输出内容里重点看几个字段：
type：实际使用的迭代方法（gmres、cg、bcgs等）preconditioner：实际使用的预条件器tolerances：三个容差（相对残差、绝对残差、发散阈值）maximum iterations：最大迭代步数
这几个字段如果跟你预期不一致，优先检查是不是代码里手动调用KSPSetType之类的方法把命令行配置覆盖了。
7. 实战：一个典型的并行求解器调试流程
说了这么多选项，怎么组合使用才是关键。我总结一套自己常用的调试流程，刚好可以当作速查手册。
假设我们的程序在某个规模下运行崩溃，或者结果不对，我的排查顺序是这样的：
第一步：确认基础配置与选项消费
bash复制mpiexec -n 4 ./solver -options_left -options_table 2>&1 | tee debug_init.log
检查输出中是否有未消费的选项，以及实际生效的求解器配置是否符合预期。这一步能排除大部分“选项没生效”和“配置被覆盖”的问题。
第二步：缩小问题范围，观察运行时轨迹
将进程数降到最小可复现规模，加上-info观察程序运行到哪个阶段出错或卡住。如果是性能问题，改用-log_view定位瓶颈事件。
bash复制mpiexec -n 4 ./solver -info 2>&1 | tee debug_trace.log
第三步：定位数值异常
如果错误与数值有关（发散、NaN），加上-fp_trap和-on_error_attach_debugger，在异常点进入调试器查看调用栈。
bash复制mpiexec -n 4 ./solver -fp_trap -on_error_attach_debugger gdb 2>&1 | tee debug_nan.log
第四步：内存专项检查
如果错误是段错误或疑似内存非法访问，启用-malloc_debug和-check_pointer，必要时用valgrind兜底。
bash复制mpiexec -n 4 ./solver -malloc_debug -check_pointer 2>&1 | tee debug_mem.log
第五步：确认修复
修复后，用-log_view重新跑一遍，对比修复前后的性能数据，确认没有引入新的性能回退。
这套流程看着简单，但每一步都有明确的输出文件和排查目标，能避免在大型代码里到处加print的混乱。实测下来，大部分问题都能在一个小时内定位到代码级别。
8. 几个其他值得关注的调试选项
PETSc的调试选项远不止上面这些。有些可能不常用，但在特定场景下能救命。
-mat_view ::ascii_info：打印矩阵的维度、非零元数量等结构化信息，排查矩阵装配是否正确时很有用。-vec_view ::ascii_info_detail：查看向量的详细布局信息，尤其是并行分布的情况。-ksp_converged_reason：只在求解结束时打印一条收敛/发散原因，简洁明了，适合批量测试。-snes_monitor、-ts_monitor：非线性求解器和时间推进器的收敛过程监控，用法与-ksp_monitor类似。-malloc_dump：在程序指定位置（调用PetscMallocDump）导出当前未释放内存的分配信息。-malloc_view：运行结束时打印PETSc内存分配的汇总统计。
还有一个容易被忽略的编译期选项--with-cxx-dialect如果你用C++写PETSc代码，建议保持开启C++11以上，否则某些调试选项在编译时会默认禁用。
9. 关于调试选项使用的一点个人经验
说实话，用PETSc做大型数值模拟这些年，我踩过的坑大半都跟“不重视调试选项”有关。很多时候程序出了诡异问题，第一反应是怀疑算法本身有问题，结果折腾半天发现就是一个矩阵的非零结构预分配没做好，或者一个命令行的选项名拼错。PETSc的调试选项体系其实就是为这种“看起来像玄学”的问题准备的系统化排查工具。
另外想强调的是，调试选项不要只在程序出错的时候才想起来用。养成在正式跑大规模计算之前，先小规模加上-options_table和-log_view看一眼配置和性能特征的习惯，往往能提前暴露很多隐患。比如矩阵的预分配是否合理、通信热点在哪里、求解器配置是否跟预期一致，这些信息在计算规模放大十倍之前发现并修正，成本是最低的。
如果你正在被PETSc的某个诡异行为折磨，先花半小时把这些选项过一遍，大概率能帮你省下好几天的时间。