NumPy 核心数学库#

numpy 核心数学库 ( npymath ) 是朝着这个方向迈出的第一步.这个库包含大多数与数学相关的 C99 功能,可以在 C99 支持不佳的平台上使用.核心数学函数具有与 C99 函数相同的 API,除了 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,则返回非 0 值.

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

npy_isinf(x)#: 这是 C99 isinf 的别名:适用于单精度,双精度和扩展精度,如果 x 是无穷大(正和负),则返回非 0 值.

npy_signbit(x)#: 这是 C99 signbit 的别名:适用于单精度,双精度和扩展精度,如果 x 设置了符号位(即数字为负数),则返回非 0 值.

npy_copysign(x, y)#: 这是 C99 copysign 的别名:返回 x,其符号与 y 相同.适用于任何值,包括 inf 和 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 ( \(\pi\) )

NPY_PI_2#: Pi 除以 2 ( \(\frac{\pi}{2}\) )

NPY_PI_4#: Pi 除以 4 ( \(\frac{\pi}{4}\) )

NPY_1_PI#: Pi 的倒数 ( \(\frac{1}{\pi}\) )

NPY_2_PI#: 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 与 x 的下一个可表示的浮点数值之间的距离,例如 spacing(1) == eps.nan 和 +/- inf 的 spacing 返回 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 包含目录(= np.get_include() 的值)添加到您的包含目录中,
npymath 静态库位于紧挨着 numpy 的包含目录的 lib 目录中(即 pathlib.Path(np.get_include()) / '..' / 'lib' ). 将其添加到您的库搜索目录中,
与 libnpymath 和 libm 链接.

备注

请记住,当您进行交叉编译时,您必须使用为您正在构建的平台构建的 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 包含一个 typedef npy_half 用于 16 位浮点数. 与大多数其他类型不同,您不能将其用作 C 中的普通类型,因为它是一个 npy_uint16 的 typedef. 例如,1.0 看起来像 C 的 0x3c00,如果您在不同的带符号零之间进行相等比较,您将得到 -0.0 != 0.0 (0x8000 != 0x0000),这是不正确的.

由于这些原因,NumPy 提供了一个 API 来处理可以通过包含 <numpy/halffloat.h> 并链接到 npymath 访问的 npy_half 值. 对于未直接提供的函数(例如算术运算),首选方法是转换为 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 位双精度浮点数.

如何运行和测试 NumPy 的代码？

在探索 NumPy 库的核心概念、常见问题和实用代码示例时，所有代码都可在 PythonRun 上直接运行测试。

请给出一个简单的 NumPy 代码示例

下面是一个简单的 NumPy 用法示例：

import numpy as np
a = np.array([1, 2, 3])
a = a * 2
print(a)

你可以在 PythonRun 上执行它，看看结果。