CPU 构建选项#
描述#
以下选项主要用于更改以某些 CPU 功能为目标的优化的默认行为:
cpu-baseline:所需 CPU 功能的最小集合.默认值为
min,它提供了可以在处理器系列中的各种平台上安全运行的最小 CPU 功能.备注
在运行时,如果目标 CPU 不支持任何指定的特性,NumPy 模块将无法加载(引发 Python 运行时错误).
cpu-dispatch:调度的其他 CPU 功能集.默认值为
max -xop -fma4,它启用所有 CPU 功能,除了 AMD 遗留功能(在 X86 的情况下).备注
在运行时,NumPy 模块将跳过目标 CPU 中不可用的任何指定功能.
这些选项可以在构建时通过构建前端(例如, pip 或 build )将 setup 参数传递给 meson-python 来访问.它们接受一组 CPU features 或一组特性,这些特性聚集了多个特性或 special options ,这些选项执行一系列过程.
要自定义 CPU/构建选项:
pip install . -Csetup-args=-Dcpu-baseline="avx2 fma3" -Csetup-args=-Dcpu-dispatch="max"
快速入门#
通常,默认设置倾向于不强加某些 CPU 功能,这些功能可能在某些较旧的处理器上不可用.提高基线功能的上限通常会提高性能,并且还可以减小二进制文件的大小.
以下是可能需要更改默认设置的最常见场景:
我正在为本地使用构建 NumPy#
我不打算将构建导出给其他用户,也不打算以与主机不同的 CPU 为目标.
为基线设置 native ,或者在您的平台不支持选项 native 的情况下手动指定 CPU 特性:
python -m build --wheel -Csetup-args=-Dcpu-baseline="native"
在这种情况下,使用额外的 CPU 特性构建 NumPy 不是必需的,因为所有支持的特性都已在基线特性中定义:
python -m build --wheel -Csetup-args=-Dcpu-baseline="native" \
-Csetup-args=-Dcpu-dispatch="none"
备注
如果主机平台不支持 native ,则会引发致命错误.
我不想支持 x86 架构的旧处理器#
由于现在大多数 CPU 至少支持 AVX , F16C 特性,您可以使用:
python -m build --wheel -Csetup-args=-Dcpu-baseline="avx f16c"
备注
cpu-baseline 强制合并所有隐含特性,因此无需添加 SSE 特性.
我遇到了与上述相同的情况,但使用的是 ppc64 架构#
然后将基线特性的上限提高到 Power8:
python -m build --wheel -Csetup-args=-Dcpu-baseline="vsx2"
使用 AVX512 特性时遇到问题?#
您可能对包含 AVX512 或任何其他 CPU 特性有所保留,并且您想要从已调度的特性中排除它们:
python -m build --wheel -Csetup-args=-Dcpu-dispatch="max -avx512f -avx512cd \
-avx512_knl -avx512_knm -avx512_skx -avx512_clx -avx512_cnl -avx512_icl -avx512_spr"
支持的特性#
特性的名称可以表示一个特性或一组特性,如下表所示,支持的特性取决于最低利益:
备注
以下特性可能并非所有编译器都支持,此外,某些编译器在处理 AVX512 , AVX2 和 FMA3 等特性时可能会产生不同的隐含特性集. 有关更多详细信息,请参见 Platform differences .
在 x86 上#
名称 |
暗示 |
收集 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
在 IBM/POWER 大端序上#
名称 |
暗示 |
|---|---|
|
|
|
|
|
|
|
|
在 IBM/POWER 小端序上#
名称 |
暗示 |
|---|---|
|
|
|
|
|
|
|
|
在 ARMv7/A32 上#
名称 |
暗示 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
在 ARMv8/A64 上#
名称 |
暗示 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
在 IBM/ZSYSTEM(S390X) 上#
名称 |
暗示 |
|---|---|
|
|
|
|
|
|
特殊选项#
NONE:不启用任何特性.NATIVE:启用主机 CPU 支持的所有 CPU 特性,此操作基于编译器标志(-march=native,-xHost,/QxHost)MIN:启用可以在各种平台上安全运行的最低 CPU 功能:适用于 Arch
暗示
x86 (32 位模式)
SSESSE2x86_64
SSESSE2SSE3IBM/POWER (大端模式)
NONEIBM/POWER (小端模式)
VSXVSX2ARMHF
NONEARM64 A.K. AARCH64
NEONNEON_FP16NEON_VFPV4ASIMDIBM/ZSYSTEM(S390X)
NONEMAX: Enables all supported CPU features by the compiler and platform.Operators-/+: remove or add features, useful with optionsMAX,MINandNATIVE.
Behaviors#
CPU features and other options are case-insensitive, for example:
python -m build --wheel -Csetup-args=-Dcpu-dispatch="SSE41 avx2 FMA3"
The order of the requested optimizations doesn’t matter:
python -m build --wheel -Csetup-args=-Dcpu-dispatch="SSE41 AVX2 FMA3" # equivalent to python -m build --wheel -Csetup-args=-Dcpu-dispatch="FMA3 AVX2 SSE41"
Either commas or spaces or ‘+’ can be used as a separator, for example:
python -m build --wheel -Csetup-args=-Dcpu-dispatch="avx2 avx512f" # or python -m build --wheel -Csetup-args=-Dcpu-dispatch=avx2,avx512f # or python -m build --wheel -Csetup-args=-Dcpu-dispatch="avx2+avx512f"
all works but arguments should be enclosed in quotes or escaped by backslash if any spaces are used.
cpu-baselinecombines all implied CPU features, for example:python -m build --wheel -Csetup-args=-Dcpu-baseline=sse42 # equivalent to python -m build --wheel -Csetup-args=-Dcpu-baseline="sse sse2 sse3 ssse3 sse41 popcnt sse42"
cpu-baselinewill be treated as “native” if compiler native flag-march=nativeor-xHostor/QxHostis enabled through environment variableCFLAGS:export CFLAGS="-march=native" pip install . # is equivalent to pip install . -Csetup-args=-Dcpu-baseline=native
cpu-baselineescapes any specified features that aren’t supported by the target platform or compiler rather than raising fatal errors.备注
Since
cpu-baselinecombines all implied features, the maximum supported of implied features will be enabled rather than escape all of them. For example:# Requesting `AVX2,FMA3` but the compiler only support **SSE** features python -m build --wheel -Csetup-args=-Dcpu-baseline="avx2 fma3" # is equivalent to python -m build --wheel -Csetup-args=-Dcpu-baseline="sse sse2 sse3 ssse3 sse41 popcnt sse42"
cpu-dispatchdoes not combine any of implied CPU features, so you must add them unless you want to disable one or all of them:# Only dispatches AVX2 and FMA3 python -m build --wheel -Csetup-args=-Dcpu-dispatch=avx2,fma3 # Dispatches AVX and SSE features python -m build --wheel -Csetup-args=-Dcpu-dispatch=ssse3,sse41,sse42,avx,avx2,fma3
cpu-dispatchescapes any specified baseline features and also escapes any features not supported by the target platform or compiler without raising fatal errors.
Eventually, you should always check the final report through the build log to verify the enabled features. See 构建报告 for more details.
Platform differences#
Some exceptional conditions force us to link some features together when it come to certain compilers or architectures, resulting in the impossibility of building them separately.
These conditions can be divided into two parts, as follows:
Architectural compatibility
The need to align certain CPU features that are assured to be supported by successive generations of the same architecture, some cases:
On ppc64le
VSX(ISA 2.06)andVSX2(ISA 2.07)both imply one another since the first generation that supports little-endian mode is Power-8`(ISA 2.07)`On AArch64
NEON NEON_FP16 NEON_VFPV4 ASIMDimplies each other since they are part of the hardware baseline.
For example:
# On ARMv8/A64, specify NEON is going to enable Advanced SIMD
# and all predecessor extensions
python -m build --wheel -Csetup-args=-Dcpu-baseline=neon
# which is equivalent to
python -m build --wheel -Csetup-args=-Dcpu-baseline="neon neon_fp16 neon_vfpv4 asimd"
备注
Please take a deep look at 支持的特性, in order to determine the features that imply one another.
Compilation compatibility
Some compilers don’t provide independent support for all CPU features. For instance
Intel’s compiler doesn’t provide separated flags for AVX2 and FMA3,
it makes sense since all Intel CPUs that comes with AVX2 also support FMA3,
but this approach is incompatible with other x86 CPUs from AMD or VIA.
For example:
# Specify AVX2 will force enables FMA3 on Intel compilers
python -m build --wheel -Csetup-args=-Dcpu-baseline=avx2
# which is equivalent to
python -m build --wheel -Csetup-args=-Dcpu-baseline="avx2 fma3"
The following tables only show the differences imposed by some compilers from the general context that been shown in the 支持的特性 tables:
备注
Features names with strikeout represent the unsupported CPU features.
On x86::Intel Compiler#
名称 |
暗示 |
收集 |
|---|---|---|
FMA3 |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C AVX2 |
|
AVX2 |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 |
|
AVX512F |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512CD |
|
XOP |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX |
|
FMA4 |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX |
|
AVX512_SPR |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F AVX512CD AVX512_SKX AVX512_CLX AVX512_CNL AVX512_ICL |
AVX512FP16 |
On x86::Microsoft Visual C/C++#
名称 |
暗示 |
收集 |
|---|---|---|
FMA3 |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C AVX2 |
|
AVX2 |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 |
|
AVX512F |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512CD AVX512_SKX |
|
AVX512CD |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F AVX512_SKX |
|
AVX512_KNL |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F AVX512CD |
AVX512ER AVX512PF |
AVX512_KNM |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F AVX512CD AVX512_KNL |
AVX5124FMAPS AVX5124VNNIW AVX512VPOPCNTDQ |
AVX512_SPR |
SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F AVX512CD AVX512_SKX AVX512_CLX AVX512_CNL AVX512_ICL |
AVX512FP16 |
构建报告#
在大多数情况下,CPU 构建选项不会产生任何导致构建挂起的致命错误.构建日志中可能出现的大多数错误都是严重的警告,原因是编译器缺少一些预期的 CPU 功能.
因此,我们强烈建议检查最终报告日志,以了解启用了哪些 CPU 功能,以及禁用了哪些.
您可以在构建日志的末尾找到 CPU 优化的最终报告,以下是它在 x86_64/gcc 上的样子:
########### EXT COMPILER OPTIMIZATION ###########
Platform :
Architecture: x64
Compiler : gcc
CPU baseline :
Requested : 'min'
Enabled : SSE SSE2 SSE3
Flags : -msse -msse2 -msse3
Extra checks: none
CPU dispatch :
Requested : 'max -xop -fma4'
Enabled : SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F AVX512CD AVX512_KNL AVX512_KNM AVX512_SKX AVX512_CLX AVX512_CNL AVX512_ICL
Generated :
:
SSE41 : SSE SSE2 SSE3 SSSE3
Flags : -msse -msse2 -msse3 -mssse3 -msse4.1
Extra checks: none
Detect : SSE SSE2 SSE3 SSSE3 SSE41
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_arithmetic.dispatch.c
: numpy/_core/src/umath/_umath_tests.dispatch.c
:
SSE42 : SSE SSE2 SSE3 SSSE3 SSE41 POPCNT
Flags : -msse -msse2 -msse3 -mssse3 -msse4.1 -mpopcnt -msse4.2
Extra checks: none
Detect : SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42
: build/src.linux-x86_64-3.9/numpy/_core/src/_simd/_simd.dispatch.c
:
AVX2 : SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C
Flags : -msse -msse2 -msse3 -mssse3 -msse4.1 -mpopcnt -msse4.2 -mavx -mf16c -mavx2
Extra checks: none
Detect : AVX F16C AVX2
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_arithm_fp.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_arithmetic.dispatch.c
: numpy/_core/src/umath/_umath_tests.dispatch.c
:
(FMA3 AVX2) : SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C
Flags : -msse -msse2 -msse3 -mssse3 -msse4.1 -mpopcnt -msse4.2 -mavx -mf16c -mfma -mavx2
Extra checks: none
Detect : AVX F16C FMA3 AVX2
: build/src.linux-x86_64-3.9/numpy/_core/src/_simd/_simd.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_exponent_log.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_trigonometric.dispatch.c
:
AVX512F : SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2
Flags : -msse -msse2 -msse3 -mssse3 -msse4.1 -mpopcnt -msse4.2 -mavx -mf16c -mfma -mavx2 -mavx512f
Extra checks: AVX512F_REDUCE
Detect : AVX512F
: build/src.linux-x86_64-3.9/numpy/_core/src/_simd/_simd.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_arithm_fp.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_arithmetic.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_exponent_log.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_trigonometric.dispatch.c
:
AVX512_SKX : SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F AVX512CD
Flags : -msse -msse2 -msse3 -mssse3 -msse4.1 -mpopcnt -msse4.2 -mavx -mf16c -mfma -mavx2 -mavx512f -mavx512cd -mavx512vl -mavx512bw -mavx512dq
Extra checks: AVX512BW_MASK AVX512DQ_MASK
Detect : AVX512_SKX
: build/src.linux-x86_64-3.9/numpy/_core/src/_simd/_simd.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_arithmetic.dispatch.c
: build/src.linux-x86_64-3.9/numpy/_core/src/umath/loops_exponent_log.dispatch.c
CCompilerOpt.cache_flush[804] : write cache to path -> /home/seiko/work/repos/numpy/build/temp.linux-x86_64-3.9/ccompiler_opt_cache_ext.py
########### CLIB COMPILER OPTIMIZATION ###########
Platform :
Architecture: x64
Compiler : gcc
CPU baseline :
Requested : 'min'
Enabled : SSE SSE2 SSE3
Flags : -msse -msse2 -msse3
Extra checks: none
CPU dispatch :
Requested : 'max -xop -fma4'
Enabled : SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F AVX512CD AVX512_KNL AVX512_KNM AVX512_SKX AVX512_CLX AVX512_CNL AVX512_ICL
Generated : none
build_ext 和 build_clib 各有一个单独的报告,其中包括几个部分,每个部分都有几个值,代表以下内容:
平台:
Architecture : 目标 CPU 的架构名称.它应该是
x86,x64,ppc64,ppc64le,armhf,aarch64,s390x或unknown之一.Compiler : 编译器名称.它应该是 gcc,clang,msvc,icc,iccw 或 unix-like 之一.
CPU 基线:
Requested :
cpu-baseline的特定功能和选项,按原样.Enabled : 启用的 CPU 功能的最终集合.
Flags : 编译器标志,用于编译所有 NumPy C/C++ 源代码,除了用于生成已调度功能的二进制对象的临时源文件.
Extra checks : 内部检查的列表,用于激活与启用功能相关的某些功能或内在函数,在开发 SIMD 内核时对于调试非常有用.
CPU 调度:
Requested :
cpu-dispatch的特定功能和选项,按原样.Enabled : 启用的 CPU 功能的最终集合.
Generated : 在此属性的下一行开头,以多个部分的形式显示已为其生成优化的功能,这些部分的属性解释如下:
One or multiple dispatched feature : 隐含的 CPU 功能.
Flags : 用于这些功能的编译器标志.
Extra checks : 与基线类似,但适用于这些调度的功能.
Detect : 需要在运行时检测到的 CPU 功能集,以便执行生成的优化.
在上述属性之后出现的行,并以单独一行上的":"结尾,表示定义生成的优化的 c/c++ 源文件的路径.
运行时调度#
导入 NumPy 会触发对来自可调度功能集的可用 CPU 功能的扫描.可以通过将环境变量 NPY_DISABLE_CPU_FEATURES 设置为以逗号,制表符或空格分隔的要禁用的功能列表来进一步限制这一点.如果解析失败或未启用该功能,这将引发错误.例如,在 x86_64 上,这将禁用 AVX2 和 FMA3
NPY_DISABLE_CPU_FEATURES="AVX2,FMA3"
如果该功能不可用,将发出警告.
跟踪调度的函数#
可以通过 Python 函数 numpy.lib.introspect.opt_func_info 来发现为不同的优化函数启用了哪些 CPU 目标.此函数提供了使用两个可选参数应用过滤器的灵活性:一个用于细化函数名称,另一个用于指定签名中的数据类型.
For example:
>> func_info = numpy.lib.introspect.opt_func_info(func_name='add|abs', signature='float64|complex64')
>> print(json.dumps(func_info, indent=2))
{
"absolute": {
"dd": {
"current": "SSE41",
"available": "SSE41 baseline(SSE SSE2 SSE3)"
},
"Ff": {
"current": "FMA3__AVX2",
"available": "AVX512F FMA3__AVX2 baseline(SSE SSE2 SSE3)"
},
"Dd": {
"current": "FMA3__AVX2",
"available": "AVX512F FMA3__AVX2 baseline(SSE SSE2 SSE3)"
}
},
"add": {
"ddd": {
"current": "FMA3__AVX2",
"available": "FMA3__AVX2 baseline(SSE SSE2 SSE3)"
},
"FFF": {
"current": "FMA3__AVX2",
"available": "FMA3__AVX2 baseline(SSE SSE2 SSE3)"
}
}
}