NumPy 核心数学库#

此库包含大部分与数学相关的 C99 功能，可以在 C99 支持不佳的平台上使用。核心数学函数的 API 与 C99 函数相同，但带有 npy_* 前缀。

可用函数定义在 <numpy/npy_math.h> 中——如有疑问，请参考此头文件。

注意

目前正致力于使 npymath 变得更小（因为随着时间的推移，编译器的 C99 兼容性有所提高），并且更容易进行打包或作为仅头文件依赖项使用。这样可以避免因使用与下游包或最终用户所用编译器不匹配的编译器构建的静态库而引发的问题。详情请参阅 gh-20880。

浮点数分类#

NPY_NAN#: 此宏定义为 NaN（非数字），并保证符号位未设置（“正” NaN）。相应的单精度和扩展精度宏可以通过后缀 F 和 L 获得。

NPY_INFINITY#: 此宏定义为正无穷。相应的单精度和扩展精度宏可以通过后缀 F 和 L 获得。

NPY_PZERO#: 此宏定义为正零。相应的单精度和扩展精度宏可以通过后缀 F 和 L 获得。

NPY_NZERO#: 此宏定义为负零（即符号位已设置）。相应的单精度和扩展精度宏可以通过后缀 F 和 L 获得。

npy_isnan(x)#: 这是 C99 isnan 的别名：适用于单精度、双精度和扩展精度，如果 x 是 NaN，则返回非零值。

npy_isfinite(x)#: 这是 C99 isfinite 的别名：适用于单精度、双精度和扩展精度，如果 x 既不是 NaN 也不是无穷大，则返回非零值。

npy_isinf(x)#: 这是 C99 isinf 的别名：适用于单精度、双精度和扩展精度，如果 x 是无穷大（正数和负数），则返回非零值。

npy_signbit(x)#: 这是 C99 signbit 的别名：适用于单精度、双精度和扩展精度，如果 x 的符号位已设置（即数字为负数），则返回非零值。

npy_copysign(x, y)#: 这是 C99 copysign 的别名：返回 x，其符号与 y 相同。适用于任何值，包括无穷大和 NaN。单精度和扩展精度可以通过后缀 f 和 l 获得。

有用的数学常数#

npy_math.h 中提供了以下数学常数。通过添加 f 和 l 后缀，还可以获得单精度和扩展精度版本。

NPY_E#: 自然对数的底 (\(e\))

NPY_LOG2E#: 欧拉常数的以 2 为底的对数 (\(\frac{\ln(e)}{\ln(2)}\))

NPY_LOG10E#: 欧拉常数的以 10 为底的对数 (\(\frac{\ln(e)}{\ln(10)}\))

NPY_LOGE2#: 2 的自然对数 (\(\ln(2)\))

NPY_LOGE10#: 10 的自然对数 (\(\ln(10)\))

NPY_PI#: 圆周率 (\(\pi\))

NPY_PI_2#: 圆周率除以 2 (\(\frac{\pi}{2}\))

NPY_PI_4#: 圆周率除以 4 (\(\frac{\pi}{4}\))

NPY_1_PI#: 圆周率的倒数 (\(\frac{1}{\pi}\))

NPY_2_PI#: 圆周率倒数的两倍 (\(\frac{2}{\pi}\))

NPY_EULER#

欧拉常数: \(\lim_{n\rightarrow\infty}({\sum_{k=1}^n{\frac{1}{k}}-\ln n})\)

底层浮点数操作#

这些对于精确的浮点数比较可能很有用。

double npy_nextafter(double x, double y)#: 这是 C99 nextafter 的别名：返回从 x 开始，沿 y 方向的下一个可表示的浮点数值。单精度和扩展精度可以通过后缀 f 和 l 获得。

double npy_spacing(double x)#: 这个函数等同于 Fortran 内置函数。返回 x 和下一个可表示的浮点数值之间的距离，例如 spacing(1) == eps。NaN 和 +/- inf 的间距返回 NaN。单精度和扩展精度可以通过后缀 f 和 l 获得。

void npy_set_floatstatus_divbyzero()#: 设置除以零浮点异常

void npy_set_floatstatus_overflow()#: 设置溢出浮点异常

void npy_set_floatstatus_underflow()#: 设置下溢浮点异常

void npy_set_floatstatus_invalid()#: 设置无效浮点异常

int npy_get_floatstatus()#

获取浮点状态。返回一个位掩码，包含以下可能标志

NPY_FPE_DIVIDEBYZERO
NPY_FPE_OVERFLOW
NPY_FPE_UNDERFLOW
NPY_FPE_INVALID

请注意，npy_get_floatstatus_barrier 是更推荐的，因为它能防止编译器进行激进的优化，将调用与设置状态的代码重排序，从而可能导致不正确的结果。

int npy_get_floatstatus_barrier(char*)#

获取浮点状态。传入一个指向局部变量的指针，以防止激进的编译器优化将此函数调用与设置状态的代码重排序，从而可能导致不正确的结果。

返回一个位掩码，包含以下可能标志

NPY_FPE_DIVIDEBYZERO
NPY_FPE_OVERFLOW
NPY_FPE_UNDERFLOW
NPY_FPE_INVALID

int npy_clear_floatstatus()#

清除浮点状态。返回之前的状态掩码。

请注意，npy_clear_floatstatus_barrier 是更推荐的，因为它能防止编译器进行激进的优化，将调用与设置状态的代码重排序，从而可能导致不正确的结果。

int npy_clear_floatstatus_barrier(char*)#: 清除浮点状态。传入一个指向局部变量的指针，以防止激进的编译器优化重排序此函数调用。返回之前的状态掩码。

对复数类型的支持#

已添加类似 C99 的复数函数。如果您想实现可移植的 C 扩展，可以使用它们。自 NumPy 2.0 起，我们使用 C99 复数类型作为底层类型。

typedef double _Complex npy_cdouble;
typedef float _Complex npy_cfloat;
typedef long double _Complex npy_clongdouble;

MSVC 不支持 _Complex 类型本身，但通过提供自己的实现，添加了对 C99 complex.h 头文件的支持。因此，在 MSVC 下，将使用等效的 MSVC 类型。

typedef _Dcomplex npy_cdouble;
typedef _Fcomplex npy_cfloat;
typedef _Lcomplex npy_clongdouble;

由于 MSVC 仍然不支持初始化复数的 C99 语法，您需要限制在 C90 兼容语法，例如：

/* a = 1 + 2i \*/
npy_complex a = npy_cpack(1, 2);
npy_complex b;

b = npy_log(a);

在 numpy/npy_math.h 中也添加了一些实用程序，用于检索或设置复数的实部或虚部。

npy_cdouble c;
npy_csetreal(&c, 1.0);
npy_csetimag(&c, 0.0);
printf("%d + %di\n", npy_creal(c), npy_cimag(c));

版本 2.0.0 中已更改：所有 numpy 复数类型的底层 C 类型已更改为使用 C99 复数类型。在此之前，以下内容被用来表示复数类型：

typedef struct { double real, imag; } npy_cdouble;
typedef struct { float real, imag; } npy_cfloat;
typedef struct {npy_longdouble real, imag;} npy_clongdouble;

使用 struct 表示法确保了复数可以在所有平台上使用，即使是那些不支持内置复数类型的平台。这也意味着必须将一个静态库与 NumPy 一起分发，以便为下游包提供 C99 兼容层。然而，近年来，对原生复数类型的支持得到了极大的改进，MSVC 在 2019 年添加了对 complex.h 头文件的内置支持。

为了简化跨版本兼容性，已添加使用新集合 API 的宏。

#define NPY_CSETREAL(z, r) npy_csetreal(z, r)
#define NPY_CSETIMAG(z, i) npy_csetimag(z, i)

numpy/npy_2_complexcompat.h 中也提供了一个兼容层。它检查宏是否存在，并在宏不存在时回退到 1.x 语法。

#include <numpy/npy_math.h>

#ifndef NPY_CSETREALF
#define NPY_CSETREALF(c, r) (c)->real = (r)
#endif
#ifndef NPY_CSETIMAGF
#define NPY_CSETIMAGF(c, i) (c)->imag = (i)
#endif

我们建议所有需要此功能的下游包将兼容层代码复制粘贴到自己的源代码中并使用它，以便它们能够无缝支持 NumPy 1.x 和 2.x。另请注意，complex.h 头文件已包含在 numpy/npy_common.h 中，这使得 complex 成为保留关键字。

在扩展中链接核心数学库#

要在您自己的 Python 扩展中使用 NumPy 提供的核心数学库作为静态库，您需要在您的扩展中添加 npymath 编译和链接选项。具体步骤取决于您使用的构建系统。通用步骤如下：

将 numpy 的 include 目录（= np.get_include() 的值）添加到您的 include 目录中。
npymath 静态库位于 numpy 的 include 目录旁边的 lib 目录中（即 pathlib.Path(np.get_include()) / '..' / 'lib'）。将其添加到您的库搜索目录中。
链接 libnpymath 和 libm。

注意

请记住，在交叉编译时，您必须使用要构建的平台的 numpy，而不是构建机器的原生 numpy。否则，您将链接到为错误架构构建的静态库。

当您使用 numpy.distutils（已弃用）进行构建时，请在您的 setup.py 中使用以下内容：

>>> from numpy.distutils.misc_util import get_info
>>> info = get_info('npymath')
>>> _ = config.add_extension('foo', sources=['foo.c'], extra_info=info)

换句话说，info 的用法与使用 blas_info 等完全相同。

当您使用 Meson 进行构建时，请使用：

# Note that this will get easier in the future, when Meson has
# support for numpy built in; most of this can then be replaced
# by `dependency('numpy')`.
incdir_numpy = run_command(py3,
  [
    '-c',
    'import os; os.chdir(".."); import numpy; print(numpy.get_include())'
  ],
  check: true
).stdout().strip()

inc_np = include_directories(incdir_numpy)

cc = meson.get_compiler('c')
npymath_path = incdir_numpy / '..' / 'lib'
npymath_lib = cc.find_library('npymath', dirs: npymath_path)

py3.extension_module('module_name',
  ...
  include_directories: inc_np,
  dependencies: [npymath_lib],

半精度函数#

头文件 <numpy/halffloat.h> 提供了用于处理 IEEE 754-2008 16 位浮点值的函数。虽然此格式通常不用于数值计算，但它对于存储需要浮点但不需要太多精度的值很有用。它还可以作为一种教育工具，用于理解浮点舍入误差的性质。

与其他类型一样，NumPy 为 16 位浮点数包含一个 typedef npy_half。与大多数其他类型不同，您不能将其用作 C 中的普通类型，因为它是一个 typedef，指向 npy_uint16。例如，1.0 在 C 中看起来像 0x3c00，如果您在不同的符号零之间进行相等比较，您将得到 -0.0 != 0.0 (0x8000 != 0x0000)，这是不正确的。

出于这些原因，NumPy 提供了一个 API 来处理 npy_half 值，可以通过包含 <numpy/halffloat.h> 并链接到 npymath 来访问。对于未直接提供的函数，如算术运算，首选方法是转换为 float 或 double 再转换回来，如下例所示：

npy_half sum(int n, npy_half *array) {
    float ret = 0;
    while(n--) {
        ret += npy_half_to_float(*array++);
    }
    return npy_float_to_half(ret);
}

外部链接

NPY_HALF_ZERO#: 此宏定义为正零。

NPY_HALF_PZERO#: 此宏定义为正零。

NPY_HALF_NZERO#: 此宏定义为负零。

NPY_HALF_ONE#: 此宏定义为 1.0。

NPY_HALF_NEGONE#: 此宏定义为 -1.0。

NPY_HALF_PINF#: 此宏定义为 +inf。

NPY_HALF_NINF#: 此宏定义为 -inf。

NPY_HALF_NAN#: 此宏定义为 NaN 值，并保证其符号位未设置。

float npy_half_to_float(npy_half h)#: 将半精度浮点数转换为单精度浮点数。

double npy_half_to_double(npy_half h)#: 将半精度浮点数转换为双精度浮点数。

npy_half npy_float_to_half(float f)#: 将单精度浮点数转换为半精度浮点数。该值会舍入到最接近的可表示的半精度值，平局则舍入到最近的偶数。如果值过小或过大，系统将设置浮点下溢或溢出标志。

npy_half npy_double_to_half(double d)#: 将双精度浮点数转换为半精度浮点数。该值会舍入到最接近的可表示的半精度值，平局则舍入到最近的偶数。如果值过小或过大，系统将设置浮点下溢或溢出标志。

int npy_half_eq(npy_half h1, npy_half h2)#: 比较两个半精度浮点数（h1 == h2）。

int npy_half_ne(npy_half h1, npy_half h2)#: 比较两个半精度浮点数（h1 != h2）。

int npy_half_le(npy_half h1, npy_half h2)#: 比较两个半精度浮点数（h1 <= h2）。

int npy_half_lt(npy_half h1, npy_half h2)#: 比较两个半精度浮点数（h1 < h2）。

int npy_half_ge(npy_half h1, npy_half h2)#: 比较两个半精度浮点数（h1 >= h2）。

int npy_half_gt(npy_half h1, npy_half h2)#: 比较两个半精度浮点数（h1 > h2）。

int npy_half_eq_nonan(npy_half h1, npy_half h2)#: 比较两个已知不为 NaN 的半精度浮点数（h1 == h2）。如果值为 NaN，则结果未定义。

int npy_half_lt_nonan(npy_half h1, npy_half h2)#: 比较两个已知不为 NaN 的半精度浮点数（h1 < h2）。如果值为 NaN，则结果未定义。

int npy_half_le_nonan(npy_half h1, npy_half h2)#: 比较两个已知不为 NaN 的半精度浮点数（h1 <= h2）。如果值为 NaN，则结果未定义。

int npy_half_iszero(npy_half h)#: 测试半精度浮点数的值是否等于零。这可能比调用 npy_half_eq(h, NPY_ZERO) 更快。

int npy_half_isnan(npy_half h)#: 测试半精度浮点数是否为 NaN。

int npy_half_isinf(npy_half h)#: 测试半精度浮点数是否为正负无穷。

int npy_half_isfinite(npy_half h)#: 测试半精度浮点数是否为有限值（不是 NaN 或 Inf）。

int npy_half_signbit(npy_half h)#: 如果 h 为负数，则返回 1，否则返回 0。

npy_half npy_half_copysign(npy_half x, npy_half y)#: 返回 x 的值，但符号位从 y 复制。适用于任何值，包括无穷大 (Inf) 和非数字 (NaN)。

npy_half npy_half_spacing(npy_half h)#: 对于半精度浮点数，这与低级浮点数部分中描述的 npy_spacing 和 npy_spacingf 相同。

npy_half npy_half_nextafter(npy_half x, npy_half y)#: 对于半精度浮点数，这与低级浮点数部分中描述的 npy_nextafter 和 npy_nextafterf 相同。

npy_uint16 npy_floatbits_to_halfbits(npy_uint32 f)#: 低级函数，将存储为 uint32 的 32 位单精度浮点数转换为 16 位半精度浮点数。

npy_uint16 npy_doublebits_to_halfbits(npy_uint64 d)#: 低级函数，将存储为 uint64 的 64 位双精度浮点数转换为 16 位半精度浮点数。

npy_uint32 npy_halfbits_to_floatbits(npy_uint16 h)#: 低级函数，将 16 位半精度浮点数转换为存储为 uint32 的 32 位单精度浮点数。

npy_uint64 npy_halfbits_to_doublebits(npy_uint16 h)#: 低级函数，将 16 位半精度浮点数转换为存储为 uint64 的 64 位双精度浮点数。