Overview

NumPy provides configuration options to optimize performance based on CPU capabilities. These options allow you to specify which CPU features to support, balancing performance, compatibility, and binary size. This document explains how to use these options effectively across various CPU architectures.

Key Configuration Options

NumPy uses several build options to control CPU optimizations:

• cpu-baseline: The minimum set of CPU features required to run the compiled NumPy.

  • Default: min (provides compatibility across a wide range of platforms)
  • If your target CPU doesn’t support all specified baseline features, NumPy will fail to load with a Python runtime error
• cpu-baseline-detect: controls detection of CPU baseline based on compiler flags. Default value is auto that enables detection if -march= or a similar compiler flag is used. The other possible values are enabled and disabled to respective enable or disable it unconditionally.

• cpu-dispatch: Additional CPU features for which optimized code paths will be generated.

  • Default: max (enables all available optimizations)
  • At runtime, NumPy will automatically select the fastest available code path based on your CPU’s capabilities

• disable-optimization: Completely disables all CPU optimizations.

  • Default: false (optimizations are enabled)
  • When set to true, disables all CPU optimized code including dispatch, SIMD, and loop unrolling
  • Useful for debugging, testing, or in environments where optimization causes issues

These options are specified at build time via meson-python arguments:

pip install . -Csetup-args=-Dcpu-baseline="min" -Csetup-args=-Dcpu-dispatch="max"
# or through spin
spin build -- -Dcpu-baseline="min" -Dcpu-dispatch="max"

cpu-baseline and cpu-dispatch can be set to specific CPU groups, features, or special options that perform specific actions. The following sections describe these options in detail.

Common Usage Scenarios

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

# For x86-64: exclude all AVX-512 features
python -m build --wheel -Csetup-args=-Dcpu-dispatch="max -X86_V4"

# For ARM64: exclude SVE
python -m build --wheel -Csetup-args=-Dcpu-dispatch="max -SVE"

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

python -m build --wheel -Csetup-args=-Dcpu-baseline="min+X86_V3"

Supported CPU Features By Architecture

NumPy supports optimized code paths for multiple CPU architectures. Below are the supported feature groups for each architecture. The name of the feature group can be used in the build options cpu-baseline and cpu-dispatch.

Special Options

Beyond specific feature names, you can use these special values:

python -m build --wheel -Csetup-args=-Dcpu-dispatch="max-X86_V4"
python -m build --wheel -Csetup-args=-Dcpu-baseline="min+X86_V4"

Usage And Behaviors

python -m build --wheel -Csetup-args=-Dcpu-dispatch="X86_v4"

python -m build --wheel -Csetup-args=-Dcpu-baseline="X86_V4 VSX4 SVE"

python -m build --wheel -Csetup-args=-Dcpu-dispatch="SVE X86_V4 x86_v3"

# All of these are equivalent
python -m build --wheel -Csetup-args=-Dcpu-dispatch="X86_V2 X86_V4"
python -m build --wheel -Csetup-args=-Dcpu-dispatch=X86_V2,X86_V4

python -m build --wheel -Csetup-args=-Dcpu-baseline=X86_V4

python -m build --wheel -Csetup-args=-Dcpu-baseline="X86_V2 X86_V3 X86_V4"

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) and VSX2(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 ASIMD implies 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"

Build report

In most cases, the CPU build options do not produce any fatal errors that lead to hanging the build. Most of the errors that may appear in the build log serve as heavy warnings due to the lack of some expected CPU features by the compiler.

So we strongly recommend checking the final report log, to be aware of what kind of CPU features are enabled and what are not.

You can find the final report of CPU optimizations by tracing meson build log, and here is how it looks on x86_64/gcc:

Test features "X86_V2" : Supported 
Test features "X86_V3" : Supported 
Test features "X86_V4" : Supported 
Test features "AVX512_ICL" : Supported 
Test features "AVX512_SPR" : Supported 
Configuring npy_cpu_dispatch_config.h using configuration
Message: 
CPU Optimization Options
  baseline:
    Requested : min
    Enabled   : X86_V2
  dispatch:
    Requested : max
    Enabled   : X86_V3 X86_V4 AVX512_ICL AVX512_SPR

Generating multi-targets for "_umath_tests.dispatch.h" 
  Enabled targets: X86_V3, baseline
Generating multi-targets for "argfunc.dispatch.h" 
  Enabled targets: X86_V4, X86_V3, baseline
Generating multi-targets for "x86_simd_argsort.dispatch.h" 
  Enabled targets: X86_V4, X86_V3
Generating multi-targets for "x86_simd_qsort.dispatch.h" 
  Enabled targets: X86_V4, X86_V3
Generating multi-targets for "x86_simd_qsort_16bit.dispatch.h" 
  Enabled targets: AVX512_SPR, AVX512_ICL
Generating multi-targets for "highway_qsort.dispatch.h" 
  Enabled targets: 
Generating multi-targets for "highway_qsort_16bit.dispatch.h" 
  Enabled targets: 
Generating multi-targets for "loops_arithm_fp.dispatch.h" 
  Enabled targets: X86_V3, baseline
Generating multi-targets for "loops_arithmetic.dispatch.h" 
  Enabled targets: X86_V4, X86_V3, baseline
Generating multi-targets for "loops_comparison.dispatch.h" 
  Enabled targets: X86_V4, X86_V3, baseline
Generating multi-targets for "loops_exponent_log.dispatch.h" 
  Enabled targets: X86_V4, X86_V3, baseline
Generating multi-targets for "loops_hyperbolic.dispatch.h" 
  Enabled targets: X86_V4, X86_V3, baseline
Generating multi-targets for "loops_logical.dispatch.h" 
  Enabled targets: X86_V4, X86_V3, baseline
Generating multi-targets for "loops_minmax.dispatch.h" 
  Enabled targets: X86_V4, X86_V3, baseline
Generating multi-targets for "loops_modulo.dispatch.h" 
  Enabled targets: baseline
Generating multi-targets for "loops_trigonometric.dispatch.h" 
  Enabled targets: X86_V4, X86_V3, baseline
Generating multi-targets for "loops_umath_fp.dispatch.h" 
  Enabled targets: X86_V4, baseline
Generating multi-targets for "loops_unary.dispatch.h" 
  Enabled targets: X86_V4, baseline
Generating multi-targets for "loops_unary_fp.dispatch.h" 
  Enabled targets: baseline
Generating multi-targets for "loops_unary_fp_le.dispatch.h" 
  Enabled targets: baseline
Generating multi-targets for "loops_unary_complex.dispatch.h" 
  Enabled targets: X86_V3, baseline
Generating multi-targets for "loops_autovec.dispatch.h" 
  Enabled targets: X86_V3, baseline
Generating multi-targets for "loops_half.dispatch.h" 
  Enabled targets: AVX512_SPR, X86_V4, baseline
WARNING: Project targets '>=1.5.2' but uses feature deprecated since '1.3.0': Source file src/umath/svml/linux/avx512/svml_z0_acos_d_la.s in the 'objects' kwarg is not an object..
Generating multi-targets for "_simd.dispatch.h" 
  Enabled targets: X86_V3, X86_V4, baseline

Runtime Dispatch

Importing NumPy triggers a scan of the available CPU features from the set of dispatchable features. You can restrict this scan by setting the environment variable NPY_DISABLE_CPU_FEATURES to a comma-, tab-, or space-separated list of features to disable.

For instance, on x86_64 this will disable X86_V4:

NPY_DISABLE_CPU_FEATURES="X86_V4"

This will raise an error if parsing fails or if the feature was not enabled through the cpu-dispatch build option. If the feature is supported by the build but not available on the current CPU, a warning will be emitted instead.

Tracking Dispatched Functions

You can discover which CPU targets are enabled for different optimized functions using the Python function numpy.lib.introspect.opt_func_info.

This function offers two optional arguments for filtering results:

1. func_name - For refining function names
2. signature - For specifying data types in the signatures

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": "baseline(X86_V2)",
      "available": "baseline(X86_V2)"
    },
    "Ff": {
      "current": "X86_V3",
      "available": "X86_V3 baseline(X86_V2)"
    },
    "Dd": {
      "current": "X86_V3",
      "available": "X86_V3 baseline(X86_V2)"
    }
  },
  "add": {
    "ddd": {
      "current": "X86_V3",
      "available": "X86_V3 baseline(X86_V2)"
    },
    "FFF": {
      "current": "X86_V3",
      "available": "X86_V3 baseline(X86_V2)"
    }
  }
}