NumPy 中的数据类型提升#

当混合两种不同的数据类型时，NumPy 必须为操作结果确定合适的 dtype。此步骤称为提升或查找通用 dtype。

在典型情况下，用户无需担心提升的细节，因为提升步骤通常会确保结果与输入精度匹配或超出输入精度。

例如，当输入具有相同的 dtype 时，结果的 dtype 与输入的 dtype 匹配

>>> np.int8(1) + np.int8(1)
np.int8(2)

混合两种不同的 dtype 通常会产生一个精度更高的输入 dtype 的结果

>>> np.int8(4) + np.int64(8)  # 64 > 8
np.int64(12)
>>> np.float32(3) + np.float16(3)  # 32 > 16
np.float32(6.0)

在典型情况下，这不会导致意外。但是，如果您使用非默认 dtype，例如无符号整数和低精度浮点数，或者混合 NumPy 整数、NumPy 浮点数和 Python 标量，则 NumPy 提升规则的一些细节可能会变得相关。请注意，这些详细规则并不总是与其他语言的规则匹配 [1]。

数值 dtype 有四种“类型”，它们具有自然的层次结构。

  1. 无符号整数 (uint)

  2. 有符号整数 (int)

  3. 浮点数 (float)

  4. 复数 (complex)

除了类型，NumPy 数值 dtype 还具有关联的精度，以比特为单位指定。类型和精度共同指定 dtype。例如，uint8 是使用 8 位存储的无符号整数。

操作的结果将始终是任何输入类型中相等或更高类型的。此外，结果的精度将始终大于或等于输入的精度。这已经可能导致一些意想不到的例子

  1. 当混合浮点数和整数时，整数的精度可能会迫使结果变为更高精度的浮点数。例如，涉及 int64 和 float16 的操作结果是 float64。

  2. 当混合相同精度的无符号整数和有符号整数时，结果的精度将高于任一输入。此外，如果其中一个已经具有 64 位精度，则没有更高精度的整数可用，例如涉及 int64 和 uint64 的操作会得到 float64。

有关两者的详细信息，请参阅下面的数值提升部分和图片。

Python 标量的详细行为#

自 NumPy 2.0 [2] 以来，我们提升规则中的一个重要点是，尽管涉及两个 NumPy dtype 的操作从不丢失精度，但涉及 NumPy dtype 和 Python 标量（int、float 或 complex）的操作可能会丢失精度。例如，Python 整数与 NumPy 整数之间操作的结果应该是 NumPy 整数，这可能是直观的。然而，Python 整数具有任意精度，而所有 NumPy dtype 都具有固定精度，因此无法保留 Python 整数的任意精度。

更普遍地，NumPy 在确定结果 dtype 时会考虑 Python 标量的“类型”，但会忽略其精度。这通常很方便。例如，在使用低精度 dtype 的数组时，通常希望与 Python 标量进行的简单操作能保留其 dtype。

>>> arr_float32 = np.array([1, 2.5, 2.1], dtype="float32")
>>> arr_float32 + 10.0  # undesirable to promote to float64
array([11. , 12.5, 12.1], dtype=float32)
>>> arr_int16 = np.array([3, 5, 7], dtype="int16")
>>> arr_int16 + 10  # undesirable to promote to int64
array([13, 15, 17], dtype=int16)

在这两种情况下，结果精度都由 NumPy dtype 决定。因此，arr_float32 + 3.0 的行为与 arr_float32 + np.float32(3.0) 相同，而 arr_int16 + 10 的行为与 arr_int16 + np.int16(10.) 相同。

另一个例子是，当 NumPy 整数与 Python float 或 complex 混合时，结果总是具有 float64 或 complex128 类型

>> np.int16(1) + 1.0 np.float64(2.0)

然而，当使用低精度 dtype 时，这些规则也可能导致意想不到的行为。

首先，由于 Python 值在执行操作之前会被转换为 NumPy 值，当结果看似明显时，操作可能会因错误而失败。例如，np.int8(1) + 1000 无法继续，因为 1000 超过了 int8 的最大值。当 Python 标量无法强制转换为 NumPy dtype 时，会引发错误

>>> np.int8(1) + 1000
Traceback (most recent call last):
  ...
OverflowError: Python integer 1000 out of bounds for int8
>>> np.int64(1) * 10**100
Traceback (most recent call last):
...
OverflowError: Python int too large to convert to C long
>>> np.float32(1) + 1e300
np.float32(inf)
... RuntimeWarning: overflow encountered in cast

其次，由于 Python 浮点数或整数精度总是被忽略，低精度 NumPy 标量将继续使用其较低精度，除非明确转换为更高精度的 NumPy dtype 或 Python 标量（例如通过 int()、float() 或 scalar.item()）。这种较低精度可能对某些计算不利或导致不正确的结果，尤其是在整数溢出的情况下

>>> np.int8(100) + 100  # the result exceeds the capacity of int8
np.int8(-56)
... RuntimeWarning: overflow encountered in scalar add

请注意，NumPy 在标量发生溢出时会发出警告，但数组不会；例如，np.array(100, dtype="uint8") + 100 不会发出警告。

数值提升#

下图显示了数值提升规则，其中类型在垂直轴上，精度在水平轴上。

../_images/nep-0050-promotion-no-fonts.svg

具有更高类型的输入 dtype 决定了结果 dtype 的类型。结果 dtype 的精度尽可能低，但不会在图中出现在任何一个输入 dtype 的左侧。

请注意以下具体规则和观察结果

  1. 当 Python float 或 complex 与 NumPy 整数交互时，结果将是 float64 或 complex128（黄色边框）。NumPy 布尔值也将转换为默认整数 [3]。当另外涉及 NumPy 浮点值时，这不相关。

  2. 精度绘制为 float16 < int16 < uint16，因为大的 uint16 不适合 int16，而大的 int16 存储在 float16 中时会丢失精度。然而，这个模式被打破了，因为 NumPy 总是将 float64 和 complex128 视为任何整数值的可接受提升结果。

  3. 一个特殊情况是 NumPy 会将有符号和无符号整数的许多组合提升为 float64。这里使用了更高类型，因为没有有符号整数 dtype 能够足够精确地容纳 uint64。

一般提升规则的例外情况#

在 NumPy 中，提升指的是特定函数对结果所做的处理，在某些情况下，这意味着 NumPy 可能会偏离 np.result_type 的结果。

sum 和 prod 的行为#

np.sum 和 np.prod 在对整数值（或布尔值）求和时，总是返回默认的整数类型。这通常是 int64。这样做的原因是，否则整数求和很可能溢出并给出令人困惑的结果。此规则也适用于底层函数 np.add.reduce 和 np.multiply.reduce。

NumPy 或 Python 整数标量的显著行为#

NumPy 提升指的是结果 dtype 和操作精度，但操作有时会决定结果。除法总是返回浮点值，而比较总是返回布尔值。

这导致了可能看似规则“例外”的情况

  • NumPy 与 Python 整数或混合精度整数的比较总是返回正确的结果。输入绝不会以损失精度的方式进行类型转换。

  • 无法提升的类型之间的相等比较将被视为全部 False（相等）或全部 True（不相等）。

  • 像 np.sin 这样总是返回浮点值的一元数学函数，通过将其转换为 float64 来接受任何 Python 整数输入。

  • 除法总是返回浮点值，因此也允许任何 NumPy 整数与任何 Python 整数值之间的除法，通过将两者都转换为 float64。

原则上，其中一些例外可能对其他函数也适用。如果您认为情况确实如此，请提出一个问题。

Python 内置类型类的显著行为#

当组合 Python 的内置标量类型（即 float、int 或 complex，而非标量值）时，提升规则可能看起来令人惊讶

>>> np.result_type(7, np.array([1], np.float32))
dtype('float32')  # The scalar value '7' does not impact type promotion
>>> np.result_type(type(7), np.array([1], np.float32))
dtype('float64')  # The *type* of the scalar value '7' does impact promotion
# Similar situations happen with Python's float and complex types

这种行为的原因是 NumPy 将 int 转换为其默认整数类型，并使用该类型进行提升

>>> np.result_type(int)
dtype('int64')

更多详情请参阅 Python 内置类型。

非数值数据类型的提升#

NumPy 将提升扩展到非数值类型，尽管在许多情况下，提升没有明确定义，并简单地被拒绝。

适用以下规则

  • NumPy 字节字符串 (np.bytes_) 可以提升为 Unicode 字符串 (np.str_)。但是，将字节转换为 Unicode 对于非 ASCII 字符将失败。

  • 出于某些目的，NumPy 几乎会将任何其他数据类型提升为字符串。这适用于数组创建或拼接。

  • 当没有可行的提升时，像 np.array() 这样的数组构造函数将使用 object dtype。

  • 结构化 dtype 在其字段名称和顺序匹配时可以提升。在这种情况下，所有字段都将单独提升。

  • NumPy timedelta 在某些情况下可以与整数一起提升。

注意

其中一些规则有些令人惊讶，未来正在考虑进行更改。然而，任何向后不兼容的更改都必须权衡其可能破坏现有代码的风险。如果您对提升应如何工作有特别的想法，请提出一个问题。

已提升 dtype 实例的详细信息#

以上讨论主要涉及混合不同 DType 类时的行为。附加到数组的 dtype 实例可以携带额外信息，例如字节顺序、元数据、字符串长度或精确的结构化 dtype 布局。

虽然结构化 dtype 的字符串长度或字段名称很重要，但 NumPy 将字节顺序、元数据和结构化 dtype 的精确布局视为存储细节。

在提升期间，NumPy 不考虑这些存储细节

  • 字节顺序被转换为本机字节顺序。

  • 附加到 dtype 的元数据可能保留也可能不保留。

  • 结果结构化 dtype 将被打包（如果输入是对齐的，则也会对齐）。

这种行为对于大多数程序来说是最佳行为，因为存储细节与最终结果无关，并且使用不正确的字节顺序可能会极大地减慢评估速度。