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

本文档包含在 scikit-learn 中开发 Cython 代码的提示。

在 scikit-learn 中使用 Cython 进行开发的提示#

简化开发的提示#

花时间阅读 Cython 文档并非浪费时间。
如果您打算使用 OpenMP：在 MacOS 上，系统分发的 clang 未实现 OpenMP。您可以安装 conda-forge 上提供的 compilers 包，该包附带 OpenMP 实现。
激活检查可能会有所帮助。例如，要激活 boundscheck，请使用
```
export SKLEARN_ENABLE_DEBUG_CYTHON_DIRECTIVES=1
```
从头开始在 Notebook 中学习如何使用 Cython 并快速获取工作反馈。如果您计划在 Jupyter Notebook 中使用 OpenMP 实现，请在 Cython magic 中添加额外的编译器和链接器参数。
```
# 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-string，例如
```
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 提供了很好的概述、上下文以及移除 GIL 的途径。
确保您已禁用检查。
尽可能优先使用 memoryviews 而不是 cnp.ndarray：memoryviews 是轻量级的。
避免 memoryview 切片：memoryview 切片在某些情况下可能代价高昂或产生误导，我们最好不要使用它，即使在某些上下文中处理更少的维度会更可取。
使用 @final 装饰最终类或方法（这允许在需要时移除虚表）
在有意义时内联方法和函数
如有疑问，请尽可能阅读生成的 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 if 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 例程，必须从该模块而不是直接从 OpenMP 库 cimport 它们

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 sklearn.utils._typedefs cimport float32, float64

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

在 scikit-learn 中使用 Cython 进行开发的提示#

简化开发的提示#

性能提示#

使用 OpenMP#

类型#

此页面