From 32f7cc919bab543ce9553adebd311215d173cdfe Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:21:05 +0000 Subject: [PATCH] docs: make Chinese README the default --- README.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..39de650 --- /dev/null +++ b/README.md @@ -0,0 +1,204 @@ + +> [!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 ` + + +文档 +------------- + +请参阅 `numexpr.readthedocs.io `_ 上的官方文档。 +其中包含用户指南、基准测试结果和参考 API。 + + +作者 +------- + +请参阅 `AUTHORS.txt `_。 + + +许可证 +------- + +NumExpr 在 `MIT `_ 许可证下发布。 + + +.. Local Variables: +.. mode: text +.. coding: utf-8 +.. fill-column: 70 +.. End: