Cython 最佳实践、约定和知识#

本文档介绍了在 scikit-learn 中开发 Cython 代码的技巧。

在 scikit-learn 中使用 Cython 开发的技巧#

简化开发的技巧#

花时间阅读 Cython 文档并非浪费时间。
如果您打算使用 OpenMP：在 MacOS 上，系统的 clang 分发版未实现 OpenMP。您可以安装 conda-forge 上提供的 compilers 包，其中包含 OpenMP 的实现。
激活检查可能会有所帮助。例如，要激活 boundscheck，请使用
```
export SKLEARN_ENABLE_DEBUG_CYTHON_DIRECTIVES=1
```
从笔记本中从头开始以了解如何使用 Cython 以及如何快速获得工作反馈。如果您计划在 Jupyter Notebook 中的实现中使用 OpenMP，请在 Cython 魔法中添加额外的编译器和链接器参数。
```
# For GCC and for clang
%%cython --compile-args=-fopenmp --link-args=-fopenmp
# For Microsoft's compilers
%%cython --compile-args=/openmp --link-args=/openmp
```
要调试 C 代码（例如段错误），请使用 gdb，方法是
```
gdb --ex r --args python ./entrypoint_to_bug_reproducer.py
```
要在 cdef (nogil) 上下文中访问某个值以进行调试，请使用
```
with gil:
    print(state_to_print)
```
请注意，Cython 无法解析带有 {var=} 表达式的 f-字符串，例如
```
print(f"{test_val=}")
```
scikit-learn 代码库包含许多非统一（融合）类型（重新）定义。目前正在进行简化和统一整个代码库的工作。现在，请确保您了解最终使用的具体类型。

您可能会发现此别名可用于编译单个 Cython 扩展名

# You might want to add this alias to your shell script config.
alias cythonX="cython -X language_level=3 -X boundscheck=False -X wraparound=False -X initializedcheck=False -X nonecheck=False -X cdivision=True"

# This generates `source.c` as if you had recompiled scikit-learn entirely.
cythonX --annotate source.pyx

使用此标志的 --annotate 选项可以生成代码注释的 HTML 报告。此报告指示与 CPython 解释器的逐行交互。在算法的计算密集型部分，应尽可能避免与 CPython 解释器的交互。有关更多信息，请参阅 Cython 教程的此部分
```
# This generates a HTML report (`source.html`) for `source.c`.
cythonX --annotate source.pyx
```

性能技巧#

了解 CPython 上下文中的 GIL（它解决了哪些问题，它的局限性是什么），并清楚地了解 Cython 何时将映射到没有与 CPython 交互的 C 代码，何时不会映射，以及何时无法映射（例如，存在与 Python 对象的交互，包括函数）。在这方面，PEP073 提供了良好的概述、上下文和删除路径。
确保您已停用检查。
始终优先使用内存视图而不是 cnp.ndarray（如果可能）：内存视图很轻量级。
避免内存视图切片：内存视图切片在某些情况下可能很昂贵或具有误导性，我们最好不要使用它，即使在某些情况下处理较少的维度会更可取。
使用 @final 装饰最终类或方法（这允许在需要时删除虚拟表）
在有意义的情况下内联方法和函数
确保您的 Cython 编译单元使用 NumPy 最新的 C API。
如有疑问，请阅读生成的 C 或 C++ 代码（如果可以）：“对于一行 Cython 代码，C 指令越少，间接引用越少越好”是一个很好的经验法则。
nogil 声明只是提示：当将 cdef 函数声明为 nogil 时，这意味着它们可以在不持有 GIL 的情况下被调用，但这不会在进入它们时释放 GIL。您必须自己执行此操作，方法是显式地将 nogil=True 传递给 cython.parallel.prange，或者使用显式上下文管理器
```
cdef inline void my_func(self) nogil:

    # Some logic interacting with CPython, e.g. allocating arrays via NumPy.

    with nogil:
        # The code here is run as is it were written in C.

    return 0
```
此项基于 Stéfan Benhel 的此评论
可以通过 sklearn.utils._cython_blas 中定义的接口直接调用 BLAS 例程。

使用 OpenMP#

由于 scikit-learn 可以不使用 OpenMP 构建，因此有必要保护对 OpenMP 的每次直接调用。

_openmp_helpers 模块（位于 sklearn/utils/_openmp_helpers.pyx 中）提供了 OpenMP 例程的受保护版本。要使用 OpenMP 例程，必须从该模块中 cimported 它们，而不是直接从 OpenMP 库中 cimported 它们

from sklearn.utils._openmp_helpers cimport omp_get_max_threads
max_threads = omp_get_max_threads()

并行循环 prange 已由 cython 保护，可以直接从 cython.parallel 中使用。

类型#

Cython 代码需要使用显式类型。这是您获得性能提升的原因之一。为了避免代码重复，我们在 sklearn/utils/_typedefs.pyd 中为最常用的类型提供了一个集中位置。理想情况下，您应该先查看那里，然后 cimport 您需要的类型，例如

from sklear.utils._typedefs cimport float32, float64