wehub-resource-sync
32f7cc919b
Build / Build and test on ubuntu-24.04-arm for aarch64 (push) Waiting to run
Build / Build and test on windows-11-arm for aarch64 (push) Waiting to run
Build / Build and test on ubuntu-latest for x86_64 (push) Waiting to run
Build / Build and test on ubuntu-latest (numpy 1.26) for x86_64 (push) Waiting to run
Build / Build and test on macos-latest for x86_64 (push) Waiting to run
Build / Build and test on windows-latest for x86_64 (push) Waiting to run
205 lines
7.5 KiB
Markdown
205 lines
7.5 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/pydata/numexpr) · [上游 README](https://github.com/pydata/numexpr/blob/HEAD/README.rst)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
======================================================
|
||
NumExpr：面向 NumPy 的快速数值表达式求值器
|
||
======================================================
|
||
|
||
:Author: David M. Cooke、Francesc Alted 等。
|
||
:Maintainer: Francesc Alted
|
||
:Contact: faltet@gmail.com
|
||
:URL: https://github.com/pydata/numexpr
|
||
:Documentation: http://numexpr.readthedocs.io/en/latest/
|
||
:GitHub Actions: |actions|
|
||
:PyPi: |version|
|
||
:DOI: |doi|
|
||
:readthedocs: |docs|
|
||
|
||
.. |actions| image:: https://github.com/pydata/numexpr/workflows/Build/badge.svg
|
||
:target: https://github.com/pydata/numexpr/actions
|
||
.. |travis| image:: https://travis-ci.org/pydata/numexpr.png?branch=master
|
||
:target: https://travis-ci.org/pydata/numexpr
|
||
.. |docs| image:: https://readthedocs.org/projects/numexpr/badge/?version=latest
|
||
:target: http://numexpr.readthedocs.io/en/latest
|
||
.. |doi| image:: https://zenodo.org/badge/doi/10.5281/zenodo.2483274.svg
|
||
:target: https://doi.org/10.5281/zenodo.2483274
|
||
.. |version| image:: https://img.shields.io/pypi/v/numexpr
|
||
:target: https://pypi.python.org/pypi/numexpr
|
||
|
||
|
||
什么是 NumExpr？
|
||
----------------
|
||
|
||
NumExpr 是面向 NumPy 的快速数值表达式求值器。借助它，
|
||
作用于数组的表达式（例如 :code:`'3*a+4*b'`）会获得加速，
|
||
并且比用 Python 做相同计算占用更少内存。
|
||
|
||
此外，其多线程能力可以利用你的所有
|
||
CPU 核心——与 NumPy 相比，通常能带来显著的性能扩展。
|
||
|
||
最后同样重要的是，numexpr 可以利用 Intel 的 VML（Vector Math
|
||
Library，向量数学库，通常集成在其 Math Kernel Library（MKL）中）。
|
||
这可以进一步加速超越函数（transcendental）表达式的计算。
|
||
|
||
|
||
NumExpr 如何实现高性能
|
||
-------------------------------------
|
||
|
||
NumExpr 比 NumPy 性能更好的主要原因
|
||
是它避免为中间结果分配内存。这
|
||
会带来更好的缓存利用率，并总体上减少内存访问。
|
||
正因如此，NumExpr 最适合处理大型数组。
|
||
|
||
NumExpr 将表达式解析为自身的操作码（op-codes），然后由
|
||
集成的计算虚拟机使用。数组操作数被拆分为
|
||
易于放入 CPU 缓存的小块（chunk），并传递给
|
||
虚拟机。虚拟机随后对每个块
|
||
应用相应运算。值得注意的是，表达式中的所有临时变量和
|
||
常量也会被分块。这些块会分配到
|
||
CPU 的可用核心上，从而实现高度并行的代码
|
||
执行。
|
||
|
||
其结果是，NumExpr 可以在按数组进行的计算中充分发挥机器的
|
||
计算能力。相对于 NumPy，常见的加速比通常介于 0.95 倍（对于非常简单的表达式，如
|
||
:code:`'a + 1'`）和 4 倍（对于相对复杂的表达式，如 :code:`'a*b-4.1*a > 2.5*b'`）之间，
|
||
尽管对于某些函数和复杂
|
||
数学运算，可以实现更高的加速（某些情况下可达 15 倍）。
|
||
|
||
NumExpr 在矩阵过大、无法放入 L1 CPU 缓存时表现最佳。
|
||
若要更好地了解在你的平台上可以实现的不同加速效果，
|
||
请运行提供的基准测试。
|
||
|
||
安装
|
||
------------
|
||
|
||
通过 wheel 安装
|
||
^^^^^^^^^^^
|
||
|
||
NumExpr 可通过 `pip` 在多种平台和
|
||
Python 版本上安装（可在以下地址浏览：https://pypi.org/project/numexpr/#files).
|
||
安装命令如下::
|
||
|
||
pip install numexpr
|
||
|
||
如果你使用的是 Anaconda 或 Miniconda 发行版的 Python，你可能更愿意
|
||
在这种情况下使用 `conda` 包管理器::
|
||
|
||
conda install numexpr
|
||
|
||
从源码安装
|
||
^^^^^^^^^^^
|
||
|
||
在大多数 \*nix 系统上，编译器通常已经就绪。不过，如果你
|
||
使用的是虚拟环境，且其中的 Python 版本明显新于
|
||
系统 Python，系统可能会提示你安装新版本的 `gcc` 或 `clang`。
|
||
|
||
在 Windows 上，你需要先安装 Microsoft Visual C++ Build Tools
|
||
（该工具免费）。具体版本取决于你安装的 Python 版本：
|
||
|
||
https://wiki.python.org/moin/WindowsCompilers
|
||
|
||
对于 Python 3.6+，通常只需安装最新版本的 MSVC build tools 即可。
|
||
请注意，通过 pip 获取的 wheel 不包含 MKL 支持。通过 `conda` 提供的 wheel
|
||
在 NumPy 使用 MKL 后端时会包含 MKL。
|
||
|
||
有关所需的 NumPy 版本，请参阅 `requirements.txt`。
|
||
|
||
NumExpr 按标准 Python 方式构建::
|
||
|
||
pip install [-e] .
|
||
|
||
你可以这样测试 `numexpr`::
|
||
|
||
python -c "import numexpr; numexpr.test()"
|
||
|
||
不要在源码目录中测试 NumExpr，否则会产生导入错误。
|
||
|
||
启用 Intel® MKL 支持
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
NumExpr 包含对 Intel MKL 库的支持。在 Intel 架构上，这可能带来更好的
|
||
性能，尤其是在求值超越函数（三角函数、指数函数等）时。
|
||
|
||
如果你已安装 Intel MKL，请将发行版附带的 `site.cfg.example` 复制到
|
||
`site.cfg`，并编辑后者文件，以提供系统中
|
||
MKL 库的正确路径。完成上述步骤后，即可按照
|
||
上文列出的常规构建说明继续操作。
|
||
|
||
请注意构建过程中的提示信息，以确认
|
||
是否已检测到 MKL。最后，你可以通过运行 `bench/vml_timing.py` 脚本检查本机上的加速效果（你可以在
|
||
脚本中调整 `set_vml_accuracy_mode()` 和 `set_vml_num_threads()`
|
||
函数的参数，以观察其对性能的影响）。
|
||
|
||
用法
|
||
-----
|
||
|
||
::
|
||
|
||
>>> import numpy as np
|
||
>>> import numexpr as ne
|
||
|
||
>>> a = np.arange(1e6) # Choose large arrays for better speedups
|
||
>>> b = np.arange(1e6)
|
||
|
||
>>> ne.evaluate("a + 1") # a simple expression
|
||
array([ 1.00000000e+00, 2.00000000e+00, 3.00000000e+00, ...,
|
||
9.99998000e+05, 9.99999000e+05, 1.00000000e+06])
|
||
|
||
>>> ne.evaluate("a * b - 4.1 * a > 2.5 * b") # a more complex one
|
||
array([False, False, False, ..., True, True, True], dtype=bool)
|
||
|
||
>>> ne.evaluate("sin(a) + arcsinh(a/b)") # you can also use functions
|
||
array([ NaN, 1.72284457, 1.79067101, ..., 1.09567006,
|
||
0.17523598, -0.09597844])
|
||
|
||
>>> s = np.array([b'abba', b'abbb', b'abbcdef'])
|
||
>>> ne.evaluate("b'abba' == s") # string arrays are supported too
|
||
array([ True, False, False], dtype=bool)
|
||
|
||
|
||
自由线程（free-threading）支持
|
||
----------------------
|
||
从 CPython 3.13 起，出现了新的发行版，可完全禁用
|
||
全局解释器锁（Global Interpreter Lock，GIL），从而在单个解释器下的多线程场景中提升性能收益，
|
||
而无需转而使用
|
||
多进程（multiprocessing）。
|
||
|
||
尽管已证明 numexpr 可在自由线程
|
||
CPython 下运行，但在使用 numexpr 原生并行
|
||
实现与直接使用 Python 线程之间需要权衡，以避免过度订阅（oversubscription）。
|
||
我们建议要么使用主 CPython 解释器线程，通过并行 numexpr API 启动多个 C 线程，
|
||
要么启动多个不使用
|
||
并行 API 的 CPython 线程。
|
||
|
||
有关自由线程 CPython 的更多信息，我们建议访问以下
|
||
`community Wiki <https://py-free-threading.github.io/>`
|
||
|
||
|
||
文档
|
||
-------------
|
||
|
||
请参阅 `numexpr.readthedocs.io <https://numexpr.readthedocs.io>`_ 上的官方文档。
|
||
其中包含用户指南、基准测试结果和参考 API。
|
||
|
||
|
||
作者
|
||
-------
|
||
|
||
请参阅 `AUTHORS.txt <https://github.com/pydata/numexpr/blob/master/AUTHORS.txt>`_。
|
||
|
||
|
||
许可证
|
||
-------
|
||
|
||
NumExpr 在 `MIT <http://www.opensource.org/licenses/mit-license.php>`_ 许可证下发布。
|
||
|
||
|
||
.. Local Variables:
|
||
.. mode: text
|
||
.. coding: utf-8
|
||
.. fill-column: 70
|
||
.. End:
|