Параметры сборки процессора

Описание

Следующие параметры в основном используются для изменения стандартного поведения оптимизаций, нацеленных на определённые возможности процессора:

• cpu-baseline: минимальный набор необходимых возможностей процессора.

  Значение по умолчанию — min, которое предоставляет минимальные возможности процессора, которые могут безопасно работать на широком спектре платформ в рамках семейства процессоров.

  Примечание

  Во время выполнения модули NumPy не смогут загрузиться, если какая-либо из указанных возможностей не поддерживается целевым процессором (возникает ошибка времени выполнения Python).

• cpu-dispatch: набор дополнительных возможностей процессора.

  Значение по умолчанию — max -xop -fma4, которое включает все возможности процессора, за исключением устаревших возможностей AMD (в случае x86).

  Примечание

  Во время выполнения модули NumPy пропустят любые указанные возможности, которые недоступны в целевом процессоре.

Эти параметры доступны во время сборки путём передачи аргументов настройки в meson-python через фронтенд сборки (например, pip или build). Они принимают набор возможностей процессора или группы возможностей, которые собирают несколько возможностей или специальные параметры, выполняющие серию процедур.

Чтобы настроить параметры процессора/сборки:

pip install . -Csetup-args=-Dcpu-baseline="avx2 fma3" -Csetup-args=-Dcpu-dispatch="max"

Быстрый старт

В целом, параметры по умолчанию не навязывают определённые возможности процессора, которые могут быть недоступны на некоторых старых процессорах. Поднятие потолка базовых возможностей часто улучшает производительность и может также уменьшить размер двоичного файла.

Ниже приведены наиболее распространённые сценарии, в которых может потребоваться изменение параметров по умолчанию:

python -m build --wheel -Csetup-args=-Dcpu-baseline="native"

python -m build --wheel -Csetup-args=-Dcpu-baseline="native" \
-Csetup-args=-Dcpu-dispatch="none"

python -m build --wheel -Csetup-args=-Dcpu-baseline="avx f16c"

python -m build --wheel -Csetup-args=-Dcpu-baseline="vsx2"

python -m build --wheel -Csetup-args=-Dcpu-dispatch="max -avx512f -avx512cd \
-avx512_knl -avx512_knm -avx512_skx -avx512_clx -avx512_cnl -avx512_icl"

Поддерживаемые функции

Названия функций могут обозначать одну функцию или группу функций, как показано в следующих таблицах. Поддержка зависит от наименьшего интереса:

Специальные параметры

• NONE: отключение всех функций.
• NATIVE: Включает все функции процессора, поддерживаемые процессором хоста. Эта операция основана на флагах компилятора (-march=native, -xHost, /QxHost)

• MIN: Включает минимальный набор функций процессора, которые безопасно работают на широком спектре платформ:

  Для архитектуры	Подразумевает
  x86 (32-битный режим)	SSE SSE2
  x86_64	SSE SSE2 SSE3
  IBM/POWER (большая эндианность)	NONE
  IBM/POWER (маленькая эндианность)	VSX VSX2
  ARMHF	NONE
  ARM64 (AARCH64)	NEON NEON_FP16 NEON_VFPV4 ASIMD
  IBM/ZSYSTEM(S390X)	NONE

• MAX: Включает все поддерживаемые компилятором и платформой функции процессора.
• Operators-/+: удаляет или добавляет функции, полезно с параметрами MAX, MIN и NATIVE.

Поведение

• Функции процессора и другие параметры нечувствительны к регистру, например:

  python -m build --wheel -Csetup-args=-Dcpu-dispatch="SSE41 avx2 FMA3"
  

• Порядок запрошенных оптимизаций не важен:

  python -m build --wheel -Csetup-args=-Dcpu-dispatch="SSE41 AVX2 FMA3"
  # equivalent to
  python -m build --wheel -Csetup-args=-Dcpu-dispatch="FMA3 AVX2 SSE41"
  

• В качестве разделителя можно использовать запятые, пробелы или знак «+», например:

  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"
  

  все работает, но аргументы должны быть заключены в кавычки или экранированы обратной косой чертой, если используются пробелы.

• cpu-baseline объединяет все подразумеваемые функции процессора, например:

  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-baseline будет рассматриваться как «родной», если флаг компилятора -march=native или -xHost или /QxHost включен через переменную среды CFLAGS:

  export CFLAGS="-march=native"
  pip install .
  # is equivalent to
  pip install . -Csetup-args=-Dcpu-baseline=native
  

• cpu-baseline экранирует любые указанные функции, которые не поддерживаются целевой платформой или компилятором, вместо вывода фатальных ошибок.

  Примечание

  Поскольку cpu-baseline объединяет все подразумеваемые функции, будет включен максимальный набор поддерживаемых подразумеваемых функций, а не все они будут экранированы. Например:

  # 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-dispatch не объединяет подразумеваемые функции процессора, поэтому вы должны добавить их, если не хотите отключить одну или все из них:

  # 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-dispatch экранирует любые указанные базовые функции, а также любые функции, которые не поддерживаются целевой платформой или компилятором, без вывода фатальных ошибок.

В конечном итоге, всегда следует проверять окончательный отчет в журнале сборки, чтобы убедиться в включенных функциях. Подробнее см. Отчет о сборке.

Отличия платформ

В некоторых исключительных случаях, для определенных компиляторов или архитектур, нам приходится связывать некоторые функции вместе, что делает невозможным их отдельное компилирование.

Эти условия можно разделить на две части следующим образом:

Архитектурная совместимость

Необходимость выравнивания определенных функций процессора, которые гарантированно поддерживаются последовательными поколениями той же архитектуры, некоторые примеры:

• На ppc64le VSX(ISA 2.06) и VSX2(ISA 2.07) предполагают друг друга, так как первое поколение, поддерживающее режим little-endian, это Power-8`(ISA 2.07)`
• На AArch64 NEON NEON_FP16 NEON_VFPV4 ASIMD предполагают друг друга, так как они являются частью базового аппаратного обеспечения.

Например:

# 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"

Совместимость компиляции

Некоторые компиляторы не предоставляют независимую поддержку всех функций процессора. Например, компилятор Intel не предоставляет отдельные флаги для AVX2 и FMA3, что имеет смысл, так как все процессоры Intel, поставляемые с AVX2, также поддерживают FMA3, но этот подход несовместим с другими процессорами x86 от AMD или VIA.

Например:

# 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"

В следующих таблицах показаны только различия, накладываемые некоторыми компиляторами, исходя из общего контекста, представленного в таблицах Поддерживаемые функции:

Отчет о сборке

В большинстве случаев опции сборки процессора не приводят к фатальным ошибкам, которые вызывают зависание сборки. Большинство ошибок, которые могут появиться в журнале сборки, являются серьезными предупреждениями из-за отсутствия некоторых ожидаемых функций процессора у компилятора.

Поэтому мы настоятельно рекомендуем проверить окончательный отчет о сборке, чтобы быть осведомленными о том, какие функции процессора включены, а какие нет.

Вы можете найти окончательный отчет об оптимизациях процессора в конце журнала сборки, и вот как он выглядит на 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, который включает несколько разделов, и каждый раздел содержит несколько значений, представляющих следующее:

Платформа:

• Архитектура: Имя архитектуры целевого процессора. Должно быть одним из x86, x64, ppc64, ppc64le, armhf, aarch64, s390x или unknown.
• Компилятор: Название компилятора. Должно быть одним из gcc, clang, msvc, icc, iccw или unix-like.

База процессора:

• Запрошено: Конкретные функции и параметры для cpu-baseline как есть.
• Включено: Окончательный набор включенных функций процессора.
• Флаги: Флаги компилятора, которые использовались для всех источников NumPy C/C++ во время компиляции, за исключением временных источников, которые использовались для генерации двоичных объектов разнесенных функций.
• Дополнительные проверки: список внутренних проверок, которые активируют определенные функции или внутренние функции, связанные с включенными функциями, полезны для отладки при разработке SIMD-ядер.

Разнесение процессора:

• Запрошено: Конкретные функции и параметры для cpu-dispatch как есть.
• Включено: Окончательный набор включенных функций процессора.

• Сгенерировано: В начале следующей строки этого свойства показаны функции, для которых были сгенерированы оптимизации, в виде нескольких разделов с аналогичными свойствами, объясненными следующим образом:

  • Одна или несколько функций разнесения: Предполагаемые функции процессора.
  • Флаги: Флаги компилятора, используемые для этих функций.
  • Дополнительные проверки: Аналогично базовой проверке, но для этих разнесенных функций.
  • Обнаружение: Набор функций процессора, которые должны быть обнаружены во время выполнения, чтобы выполнить сгенерированные оптимизации.
  • Строки, следующие за вышеуказанным свойством и заканчивающиеся двоеточием в отдельной строке, представляют пути к исходным кодам c/c++, которые определяют сгенерированные оптимизации.

Динамическое распределение ресурсов

Импорт NumPy запускает сканирование доступных функций процессора из набора отправляемых функций. Это можно дополнительно ограничить, установив переменную среды NPY_DISABLE_CPU_FEATURES в список функций, разделяемых запятыми, табуляцией или пробелами, для отключения. Это вызовет ошибку, если произойдет сбой разбора или функция не была включена. Например, на x86_64 это отключит AVX2 и FMA3.

NPY_DISABLE_CPU_FEATURES="AVX2,FMA3"

Если функция недоступна, будет выведено предупреждение.

Отслеживание отправленных функций

Определение того, какие целевые процессоры включены для различных оптимизированных функций, достижимо с помощью Python-функции numpy.lib.introspect.opt_func_info. Эта функция предоставляет гибкость применения фильтров с использованием двух необязательных аргументов: один для уточнения имен функций и другой для указания типов данных в подписях.

Например:

 >> 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)"
     }
  }
}