调试线性代数相关问题

线性代数相关的错误报告是诊断和解决最具挑战性的问题之一。这不仅因为线性代数在数学/算法上可能具有挑战性（SciPy 的许多部分都是如此），还因为 BLAS/LAPACK 库是一个复杂的构建时和运行时依赖项——并且我们支持大量的 BLAS/LAPACK 库。

本文档旨在提供关于如何调试线性代数问题的指导。

如果存在实际错误，它可能位于三个位置之一

• 所使用的 BLAS 库中，

• SciPy 的 BLAS 或 LAPACK 绑定中（由 numpy.f2py 和/或 Cython 生成），

• SciPy 的算法代码中。

关键的第一步是确定错误是在 SciPy 中还是在 BLAS 库中。为此，最有效的方法是设置您的环境，以便您可以在运行时在不同的 BLAS 库之间切换（我们不直接支持，并且 SciPy 从 PyPI 获取的 wheels 也不可能）。

上游 BLAS 库作者强烈倾向于获得清晰的重现器（就像我们一样），这意味着：不涉及 Python。因此，本指南还将介绍如何用 C 或 Fortran 创建重现器。

查找正在使用的 BLAS 库

SciPy 有一个函数 show_config，用于内省已安装包的构建配置。这允许查询 BLAS 和 LAPACK 的详细信息。例如：

>>> blas_dep = scipy.show_config(mode='dicts')['Build Dependencies']['blas']
>>> for key in blas_dep:
...     print(f"{key}:  {blas_dep[key]}")
...
name:  openblas
found:  True
version:  0.3.23
detection method:  pkgconfig
include directory:  /home/user/miniforge/envs/scipy-dev/include
lib directory:  /home/user/miniforge/envs/scipy-dev/lib
openblas configuration:  USE_64BITINT=0 DYNAMIC_ARCH=1 DYNAMIC_OLDER= NO_CBLAS= NO_LAPACK=0 NO_LAPACKE= NO_AFFINITY=1 USE_OPENMP=0 PRESCOTT MAX_THREADS=128
pc file directory:  /home/user/miniforge/envs/scipy-dev/lib/pkgconfig

此方法对于 SciPy wheels 和本地开发版本是正确的。对于其他安装，它可能是正确的，但请记住，conda-forge 和 Debian 等发行版可能基于存根库（通常是 blas.so/lapack.so）构建，然后为用户安装另一个库——在这种情况下，即使环境中安装了 OpenBLAS 或 MKL，也会报告普通的 blas 和 lapack。对于此类安装，threadpoolctl 通常能够报告正在使用的实际 BLAS 库（除了它不报告普通的 Netlib BLAS，参见 threadpoolctl#159）

$ python -m threadpoolctl -i scipy.linalg
[
  {
    "user_api": "blas",
    "internal_api": "openblas",
    "prefix": "libopenblas",
    "filepath": "/home/user/miniforge/envs/dev/lib/libopenblasp-r0.3.21.so",
    "version": "0.3.21",
    "threading_layer": "pthreads",
    "architecture": "SkylakeX",
    "num_threads": 24
  }
]

在本地开发环境中可能有用的其他内省方法包括

1. 检查共享库的依赖项

Linux

$ ldd build/scipy/linalg/_fblas.cpython-*.so
...
libopenblas.so.0 => /home/user/miniforge/envs/scipy-dev/lib/libopenblas.so.0 (0x0000780d6d000000)

macOS

% otool -L build/scipy/linalg/_fblas.cpython-310-darwin.so
build/scipy/linalg/_fblas.*.so:
    /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1336.61.1)
    @rpath/libopenblas.0.dylib (compatibility version 0.0.0, current version 0.0.0)

2. 检查链接库是否包含给定符号。例如，conda-forge 安装的 libblas.so 可能是任何受支持的库

Linux

$ nm -gD ~/miniforge/envs/scipy-dev/lib/libblas.so | rg openblas_set_num_threads
0000000000362990 T openblas_set_num_threads

macOS

% nm ~/miniforge/envs/scipy-dev/lib/libblas.3.dylib | rg openblas_set_num_threads
000000000015b6b0 T _openblas_set_num_threads

设置您的环境以切换 BLAS 库

我们将介绍几种在不同 BLAS 库之间切换的方法，因为最简单的方法可能取决于您的操作系统/发行版以及您想要 SciPy 的发布版本还是开发版本。

Conda-forge

也许最简单的方法是使用发行版提供的运行时切换功能。例如，创建一个安装了最新 SciPy 版本的 conda 环境，然后在 OpenBLAS、Netlib BLAS/LAPACK 和 MKL 之间切换就像这样简单：

$ mamba create -n blas-switch scipy threadpoolctl
$ mamba activate blas-switch
$ python -m threadpoolctl -i scipy.linalg
...
    "user_api": "blas",
    "internal_api": "openblas",

$ mamba install "libblas=*=*netlib"
...
  libblas                         3.9.0-21_linux64_openblas --> 3.9.0-5_h92ddd45_netlib
  libcblas                        3.9.0-21_linux64_openblas --> 3.9.0-5_h92ddd45_netlib
  liblapack                       3.9.0-21_linux64_openblas --> 3.9.0-5_h92ddd45_netlib

$ mamba install "libblas=*=*mkl"
...
  libblas                           3.9.0-5_h92ddd45_netlib --> 3.9.0-21_linux64_mkl
  libcblas                          3.9.0-5_h92ddd45_netlib --> 3.9.0-21_linux64_mkl
  liblapack                         3.9.0-5_h92ddd45_netlib --> 3.9.0-21_linux64_mkl

$ python -m threadpoolctl -i scipy.linalg
...
  "user_api": "blas",
  "internal_api": "mkl",

这也可以用于开发版本，当通过 spin 构建时，与 SciPy 的 conda-forge 构建配方 完全相同（输出为简洁起见已省略，它们与上面的类似）

$ mamba env create -f environment.yml
$ mamba activate scipy-dev
$ mamba install "libblas=*=*netlib"  # necessary, we need to build against blas/lapack
$ spin build -S-Dblas=blas -S-Dlapack=lapack -S-Duse-g77-abi=true
$ spin test -s linalg  # run tests to verify
$ mamba install "libblas=*=*mkl"
$ spin test -s linalg
$ mamba install "libblas=*=*openblas"

Linux 发行版包管理器

许多 Linux 发行版使用 update-alternatives 机制，允许通过系统包管理器在不同的 BLAS 库之间切换。请注意，这是一种管理“同一库或工具的多个实现”情况的通用机制，而不是 BLAS/LAPACK 特有的。它类似于上面的 conda-forge 方法，因为它适用于发行版提供的 scipy 包以及针对参考 libblas/liblapack 接口的开发构建。

接口看起来像

$ update-alternatives --config libblas.so.3
$ update-alternatives --config liblapack.so.3

这将在终端中打开一个菜单，其中包含所有可用的库供选择。由于接口和可用选项可能因发行版而异，我们在此处链接到 Debian 关于 BLAS/LAPACK 切换的文档，并避免更详细地记录这在其他发行版上如何工作。

请注意，Fedora 是一个例外；它是唯一一个提供 FlexiBLAS（更多内容见下一节）并允许并行安装多个 BLAS 库的发行版，因此无需调用系统包管理器即可实现真正的运行时切换。有关详细信息，请参阅 Fedora 关于系统级和用户级选择的文档。

FlexiBLAS

FlexiBLAS 为所有它能检测到的已安装 BLAS 库提供运行时切换支持（以及其他功能）。截至撰写本文时（2024 年 3 月），存在一些限制，主要是：不支持 Windows，不支持 macOS Accelerate（更新版本，带有 NEWLAPACK 符号）。如果这些限制对您不重要，FlexiBLAS 可以成为一个非常有用的高效调试工具，包括您必须从源代码构建的 OpenBLAS 和其他 BLAS 库版本。

一旦您设置好所有内容，开发体验是

$ spin build -S-Dblas=flexiblas -S-Dlapack=flexiblas
$ FLEXIBLAS=NETLIB spin test -s linalg
$ FLEXIBLAS=OpenBLAS spin test -s linalg
# Or export the environment variable to make the selection stick:
$ export FLEXIBLAS=OpenBLAS

您还可以提供构建好的 BLAS 库的路径（例如，FLEXIBLAS="libbhlas_atlas.so"）——有关详细信息，请参阅其 README 中的使用文档。

除非您使用 Fedora，否则您可能需要从源代码构建 FlexiBLAS，这需要一些工作。好消息是，无论您是在 Linux 还是 macOS 上，并通过 virtualenvs、conda 环境或以其他方式使用 Python，这都应该可行。我们将介绍如何从源代码构建 OpenBLAS 和 FlexiBLAS，以允许调试最新 OpenBLAS 版本中是否存在与 Netlib BLAS/LAPACK（或 MKL）不同的问题。

下面的内容应该适用于任何可以构建 SciPy 本身的环境；我们唯一需要的额外工具是 CMake（例如，通过 pip install cmake 安装）。

克隆每个仓库

$ cd ..  # starting from the root of the local `scipy` repo
$ mkdir flexiblas-setup && cd flexiblas-setup
$ git clone https://github.com/OpenMathLib/OpenBLAS.git openblas
$ git clone https://github.com/mpimd-csc/flexiblas.git
$ mkdir built-libs  # our local prefix to install everything to

构建 OpenBLAS

$ cd openblas
$ mkdir build && cd build
$ cmake .. -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$PWD/../../built-libs
$ cmake --build . -j
$ cmake --install . --prefix $PWD/../../built-libs
$ cd ../..

构建 FlexiBLAS

$ cd flexiblas
$ mkdir build && cd build
$ # Note: this will also pick up the libraries in your system/env libdir
$ cmake .. -DEXTRA="OpenBLAS" -DLAPACK_API_VERSION=3.9.0 \
    -DOpenBLAS_LIBRARY=$PWD/../../built-libs/lib/libopenblas.so \
    -DCMAKE_INSTALL_PREFIX=$PWD/../../built-libs
$ cmake --build . -j
$ cmake --install . --prefix $PWD/../../built-libs
$ cd ../..

我们现在准备好针对 FlexiBLAS 构建 SciPy

$ export PKG_CONFIG_PATH=$PWD/flexiblas-setup/built-libs/lib/pkgconfig/
$ cd scipy
$ spin build -S-Dblas=flexiblas -S-Dlapack=flexiblas
...
Run-time dependency flexiblas found: YES 3.4.2

现在我们可以运行测试了。请注意，NETLIB 选项是无需指定即可构建的；它是 FlexiBLAS 中的默认选项，并且源代码包含在其仓库中

$ FLEXIBLAS=OpenBLAS spin test -s linalg
$ FLEXIBLAS=NETLIB spin test -s linalg
$ spin test -s linalg  # uses the default (NETLIB)

这种后端切换也可以在 Python 解释器内部使用 threadpoolctl 完成（有关详细信息，请参阅 其 README）。

系统上可用的其他库可以通过以下方式检查

$ ./flexiblas-setup/built-libs/bin/flexiblas list

注意

使用参考 BLAS/LAPACK 或 BLIS 的本地构建更加困难，因为 FlexiBLAS 需要一个包含所有所需符号的单个共享库。作为“系统库”，使用单独的 libblas 和 liblapack 可能是可行的，但这已被证明更脆弱且更难以构建（因此这取决于您的经验）。如果您确实想尝试

构建参考 BLAS 和 LAPACK

$ git clone Reference-LAPACK/lapack.git $ cd lapack $ mkdir build && cd build $ cmake -DCBLAS=ON -DBUILD_SHARED_LIBS=OFF .. $ cmake –build . -j $ cmake –install . –prefix $PWD/../../built-libs

然后将以下两行添加到 FlexiBLAS 的 cmake .. 配置命令中

-DSYS_BLAS_LIBRARY=$PWD/../../built-libs/lib/libblas.a \
-DSYS_LAPACK_LIBRARY=$PWD/../../built-libs/lib/liblapack.a \

用 C 或 Fortran 创建重现器

我们的经验告诉我们，绝大多数错误都存在于 SciPy 中，而不是 OpenBLAS 或其他 BLAS 库中。然而，如果使用不同 BLAS 库的测试告诉我们问题特定于单个 BLAS 库（甚至可能是该库的某个版本存在回归），那么下一步是用 C 或 Fortran 生成一个重现器；这样做对于向上游报告错误是必要的，并且使得 BLAS 库开发人员更容易解决问题。

要从使用 NumPy 数组作为输入的 scipy 函数的 Python 重现器转换为 C/Fortran 重现器，需要找到 SciPy 中采用的代码路径并确定调用了哪个精确的 BLAS 或 LAPACK 函数，以及使用了什么输入（注意：答案可能包含在 .pyf.src f2py 签名文件中；查看构建目录中生成的 _flapackmodule.c 也可能有用）。然后可以通过定义一些整数/浮点变量和数组（通常是带有硬编码数字的小数组就足够了）在 C/Fortran 中重现这一点。

BLAS 和 LAPACK 函数的参数列表可以在 Netlib LAPACK 文档 或 Reference-LAPACK/lapack 仓库 中查找。

下面显示了一个参考 LAPACK 中问题的重现器，该问题在 scipy#11577 中作为 SciPy 问题报告。我们将文件命名为 ggev_repro_gh_11577.c|f90

C

#include <stdio.h>
#include "lapacke.h"

#define n 4

int main()
{
    int lda=n, ldb=n, ldvr=n, ldvl=n, info;
    char jobvl='V', jobvr='V';
    double alphar[n], alphai[n], beta[n];

    double vl[n*n], vr[n*n];
    // int lwork = 156;
    // double work[156];    /* cheat: 156 is the optimal lwork from the actual lapack call*/

    double a[n*n] = {12.0, 28.0, 76.0, 220.0,
                     16.0, 32.0, 80.0, 224.0,
                     24.0, 40.0, 88.0, 232.0,
                     40.0, 56.0, 104.0, 248.0};

    double b[n*n] = {2.0, 4.0, 10.0, 28.0,
                     3.0, 5.0, 11.0, 29.0,
                     5.0, 7.0, 13.0, 31.0,
                     9.0, 11.0, 17.0, 35.0};

    info = LAPACKE_dggev(LAPACK_ROW_MAJOR, jobvl, jobvr, n, a, lda, b,
                         ldb, alphar, alphai, beta, vl, ldvl, vr, ldvr); //, work, lwork, info);

    printf("info = %d\n", info);

    printf("Re(eigv) = ");
    for(int i=0; i < n; i++){
        printf("%f , ", alphar[i] / beta[i] );
    }
    printf("\nIm(eigv = ");
    for(int i=0; i < n; i++){
        printf("%f , ", alphai[i] / beta[i] );
    }
    printf("\n");
}

Fortran

!A = numpy.array([[12.0, 28.0, 76.0, 220.0], [16.0, 32.0, 80.0, 224.0], [24.0, 40.0, 88.0, 232.0], [40.0, 56.0, 104.0, 248.0]], dtype='float64')
! B = numpy.array([[2.0, 4.0, 10.0, 28.0], [3.0, 5.0, 11.0, 29.0], [5.0, 7.0, 13.0, 31.0], [9.0, 11.0, 17.0, 35.0]], dtype='float64')
! D, V = scipy.linalg.eig(A, B); D 
implicit none
integer, parameter :: n = 4

integer :: lda, ldb, ldvr, ldvl, lwork, info
character*1 :: jobvl, jobvr
real*8 :: alphar(n)
real*8 :: alphai(n)
real*8 :: beta(n)
real*8 :: vl(n, n)
real*8 :: vr(n, n)
real*8, allocatable :: work(:)


real*8 :: a(n, n)
real*8 :: b(n, n)

a(1, :) = (/12.0, 28.0, 76.0, 220.0/)
a(2, :) = (/16.0, 32.0, 80.0, 224.0/)
a(3, :) = (/24.0, 40.0, 88.0, 232.0/)
a(4, :) = (/40.0, 56.0, 104.0, 248.0/)

b(1, :) = (/2.0, 4.0, 10.0, 28.0/)
b(2, :) = (/3.0, 5.0, 11.0, 29.0/)
b(3, :) = (/5.0, 7.0, 13.0, 31.0/)
b(4, :) = (/9.0, 11.0, 17.0, 35.0/)

lda = n
ldb = n
ldvr = n
ldvl = n
jobvr = 'V'
jobvl = 'V'

! workspace query

allocate(work(1:8*n)) ! min value
lwork = -1

print*, 'workspace query: lwork = ', lwork

call dggev(jobvl, jobvr, n, a, lda, b, ldb, alphar, alphai, beta, vl, ldvl, vr, ldvr, work, lwork, info)

print*, 'info = ', info
lwork = int(work(1))
print*, 'opt lwork =', lwork

! do the work

deallocate(work)
allocate(work(1:lwork))

call dggev(jobvl, jobvr, n, a, lda, b, ldb, alphar, alphai, beta, vl, ldvl, vr, ldvr, work, lwork, info)

print*
print*, 'info = ', info
print*, 'alphar = ', alphar
print*, 'alphai = ', alphai
print*, 'beta = ', beta
print*
print*, 'Re(eigv) = ', alphar / beta
print*, 'Im(eigv) = ', alphai / beta

deallocate(work)
end

现在我们需要在本地编译并运行这个重现器。如果我们直接调用编译器，我们需要手动添加所需的编译和链接标志。包含路径将取决于您的本地安装，链接标志将取决于您正在测试的库。例如，要针对 OpenBLAS 的本地构建进行测试

C

$ gcc ggev_repro_gh_11577.c \
  -I$PWD/../flexiblas-setup/built-libs/include/ \
  -L$PWD/../flexiblas-setup/built-libs/lib -lopenblas
$ ./a.out  # to run the reproducer

Fortran

$ gfortran ggev_repro_gh_11577.f90 \
  -I/$PWD/../flexiblas-setup/built-libs/include/ \
  -L$PWD/../flexiblas-setup/built-libs/lib -lopenblas
$ ./a.out  # to run the reproducer

对于参考 BLAS/LAPACK，-lopenblas 应该替换为 -lblas -llapack。

请注意，显式路径仅适用于非标准位置的库（如本指南中我们构建的库）。对于针对包管理器安装的库进行构建，如果共享库和头文件位于正常的编译器搜索路径上（例如，在 /usr/lib 和 /usr/include 中，或者在使用来自同一 env 的编译器时位于 conda env 内部），它们可以省略。

C

$ gcc ggev_repro_gh_11577.c -lopenblas
$ ./a.out  # to run the reproducer

Fortran

$ gfortran ggev_repro_gh_11577.f90 -lopenblas
$ ./a.out  # to run the reproducer

或者（可能是一种更健壮的方法），使用一个小的 meson.build 文件来自动化此过程并避免手动路径

C

project('repro_gh_11577', 'c')

openblas_dep = dependency('openblas')

executable('repro_c',
    'ggev_repro_gh_11577.c',
    dependencies: openblas_dep
)

然后构建并运行测试

$ export PKG_CONFIG_PATH=~/code/tmp/flexiblas-setup/built-libs/lib/pkgconfig/
$ meson setup build
$ ninja -C build
$ ./build/repro_c  # output may vary

info = 0
Re(eigv) = 4.000000 , 8.000000 , inf , -inf ,
Im(eigv = 0.000000 , 0.000000 , -nan , -nan ,

Fortran

project('repro_gh_11577', 'fortran')

openblas_dep = dependency('openblas')

executable('repro_f90',
    'ggev_repro_gh_11577.f90',
    dependencies: openblas_dep
)

然后构建并运行测试

$ export PKG_CONFIG_PATH=~/code/tmp/flexiblas-setup/built-libs/lib/pkgconfig/
$ meson setup build
$ ninja -C build
$ ./build/repro_f90  # output may vary

workspace query: lwork =           -1
info =            0
opt lwork =         156

info =            0
alphar =    1.0204501477442456        11.707793036240817        3.7423579363517347E-014  -1.1492523608519701E-014
alphai =    0.0000000000000000        0.0000000000000000        0.0000000000000000        0.0000000000000000
beta =   0.25511253693606051        1.4634741295300704        0.0000000000000000        0.0000000000000000

Re(eigv) =    4.0000000000000142        8.0000000000001741                       Infinity                 -Infinity
Im(eigv) =    0.0000000000000000        0.0000000000000000                            NaN                       NaN

警告

当您的机器上存在同一 BLAS 库的多个版本/构建时，在构建过程中很容易意外地选择错误的库（请记住：-lopenblas 只表示“链接到某个 libopenblas.so”）。如果您不确定，请对您构建的测试可执行文件使用 ldd 来检查它链接到哪个共享库。

使用 gdb 调试线性代数问题

在调试线性代数问题时，有时通过 Python 和 C 代码进行单步调试很有用。前者可以使用 pdb，后者可以使用 gdb。

首先，准备一个小的 python 重现器，并设置一个断点。例如

$ cat chol.py
import numpy as np
from scipy import linalg
n = 40
rng = np.random.default_rng(1234)
x = rng.uniform(size=n)
a = x[:, None] @ x[None, :] + np.identity(n)

breakpoint()      # note a breakpoint
linalg.cholesky(a)

然后，您需要将其在 gdb 下运行，并在 LAPACK 函数处添加一个 C 级别断点。这样，您的执行将停止两次：首先在 Python 断点处，然后在 C 断点处，您将能够单步执行并检查 Python 和 C 变量的值。

要找出 LAPACK 名称，请阅读 SciPy 函数的 python 源代码，并对 .so 库使用 nm 来找出确切名称。对于上面的 Cholesky 分解，LAPACK 函数是 ?potrf，在 Ubuntu linux 上 C 名称是 dpotrf_（它可能带或不带尾随下划线，大写或小写，具体取决于系统）。

以下是一个 gdb 会话示例

$ gdb --args python chol.py
...
(gdb) b dpotrf_     # this adds a C breakpoint (type "y" below)
Function "dpotrf_" not defined.
Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (dpotrf_) pending.
(gdb) run    # run the python script
...
> /home/br/temp/chol/chol.py(12)<module>()
-> linalg.cholesky(a)   # execution stopped at the python breakpoint
(Pdb) p a.shape  # ... inspect the python state here
(40, 40)
(Pdb) c     # continue execution until the C breakpoint

Thread 1 "python" hit Breakpoint 1, 0x00007ffff4c48820 in dpotrf_ ()
   from /home/br/miniforge/envs/scipy-dev/lib/python3.10/site-packages/numpy/core/../../../../libcblas.so.3
(gdb) s     # step through the C function
Single stepping until exit from function dpotrf_,
which has no line number information.
f2py_rout__flapack_dpotrf (capi_self=<optimized out>, capi_args=<optimized out>,
    capi_keywds=<optimized out>, f2py_func=0x7ffff4c48820 <dpotrf_>)
    at scipy/linalg/_flapackmodule.c:63281
....
(gdb) p lda    # inspect values of C variables
$1 = 40

# print out the C backtrace
(gdb) bt
#0  0x00007ffff3056b1e in f2py_rout.flapack_dpotrf ()
   from /path/to/site-packages/scipy/linalg/_flapack.cpython-311-x86_64-linux-gnu.so
#1  0x0000555555734323 in _PyObject_MakeTpCall (tstate=0x555555ad0558 <_PyRuntime+166328>,
    callable=<fortran at remote 0x7ffff40ffc00>, args=<optimized out>, nargs=1,
    keywords=('lower', 'overwrite_a', 'clean'))
    at /usr/local/src/conda/python-3.11.8/Objects/call.c:214
...

根据您的系统，您可能需要使用调试构建类型构建 SciPy，并取消设置 CFLAGS/CXXFLAGS 环境变量。有关详细信息，请参阅 NumPy 调试指南。