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

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

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

简化开发的技巧#

花时间阅读 Cython 的文档绝不会浪费时间。
如果你打算使用 OpenMP：在 MacOS 上，系统分发的 clang 不支持 OpenMP。你可以安装 conda-forge 上的 compilers 包，它自带 OpenMP 的实现。
激活检查可能会有所帮助。例如，要激活边界检查，请使用：
```
export SKLEARN_ENABLE_DEBUG_CYTHON_DIRECTIVES=1
```
从零开始在笔记本中了解如何使用 Cython 并快速获得反馈。如果你计划在 Jupyter Notebook 中使用 OpenMP 实现，请在 Cython 魔法中添加额外的编译器和链接器参数。
```
# 对于 GCC 和 clang
%%cython --compile-args=-fopenmp --link-args=-fopenmp
# 对于微软的编译器
%%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 扩展很方便：

# 您可能希望将这个别名添加到您的 shell 脚本配置中。
alias cythonX="cython -X language_level=3 -X boundscheck=False -X wraparound=False -X initializedcheck=False -X nonecheck=False -X cdivision=True"

# 这将生成 `source.c` ，就像您重新编译了整个 scikit-learn 一样。
cythonX --annotate source.pyx

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

性能优化提示#

了解 CPython 中的 GIL（它解决的问题，它的局限性）并深入理解 Cython 何时会映射到没有与 CPython 交互的 C 代码，何时不会，以及何时不能（例如，存在与 Python 对象的交互，包括函数）。在这方面， PEP073 提供了很好的概述和上下文以及移除的路径。
确保已停用检查 .
尽可能优先使用 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:

    # 一些与 CPython 交互的逻辑，例如通过 NumPy 分配数组。

    with nogil:
        # 这里的代码如同直接用 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 例程，必须从该模块中 cimport ，而不是直接从 OpenMP 库中导入：

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