NEP 50 — Promotion rules for Python scalars#

Schema of the new proposed promotion rules#

After the change, the promotions in NumPy will follow the schema below. Promotion always occurs along the green lines: from left to right within their kind and to a higher kind only when necessary. The result kind is always the largest kind of the inputs. Note that float32 has a lower precision than int32 or uint32 and is thus sorted slightly to the left in the schematic. This is because float32 cannot represent all int32 values exactly. However, for practical reasons, NumPy allows promoting int64 to float64 effectively considering them to have the same precision.

The Python scalars are inserted at the very left of each “kind” and the Python integer does not distinguish signed and unsigned. NumPy promotion thus uses the following, ordered, kind categories:

• boolean

• integral: signed or unsigned integers

• inexact: floating point numbers and complex floating point numbers

When promoting a Python scalar with a dtype of lower kind category (boolean < integral < inexact) with a higher one, we use the minimum/default precision: that is float64, complex128 or int64 (int32 is used on some systems, e.g. windows).

See the next section for examples which clarify the proposed behavior. Further examples with a comparison to the current behavior can be found in the table below.

Examples of new behaviour#

To make interpretation of above text and figure easier, we provide a few examples of the new behaviour. Below, the Python integer has no influence on the result type:

np.uint8(1) + 1 == np.uint8(2)
np.int16(2) + 2 == np.int16(4)

In the following the Python float and complex are “inexact”, but the NumPy value is integral, so we use at least float64/complex128:

np.uint16(3) + 3.0 == np.float64(6.0)
np.int16(4) + 4j == np.complex128(4+4j)

But this does not happen for float to complex promotions, where float32 and complex64 have the same precision:

np.float32(5) + 5j == np.complex64(5+5j)

Note that the schematic omits bool. It is set below “integral”, so that the following hold:

np.bool_(True) + 1 == np.int64(2)
True + np.uint8(2) == np.uint8(3)

Note that while this NEP uses simple operators as example, the rules described generally apply to all of NumPy operations.

Table comparing new and old behaviour#

The following table lists relevant changes and unchanged behaviours. Please see the Old implementation for a detailed explanation of the rules that lead to the “Old result”, and the following sections for the rules detailing the new. The backwards compatibility section discusses how these changes are likely to impact users.

Note the important distinction between a 0-D array like array(2) and arrays that are not 0-D, such as array([2]).

Impact on can_cast#

can_cast will never inspect the value anymore. So that the following results are expected to change from True to False:

np.can_cast(np.int64(100), np.uint8)
np.can_cast(np.array(100, dtype=np.int64), np.uint8)
np.can_cast(100, np.uint8)

We expect that the impact of this change will be small compared to that of the following changes.

Impact on operators and functions involving NumPy arrays or scalars#

The main impact on operations not involving Python scalars (float, int, complex) will be that operations on 0-D arrays and NumPy scalars will never depend on their values. This removes currently surprising cases. For example:

np.arange(10, dtype=np.uint8) + np.int64(1)
# and:
np.add(np.arange(10, dtype=np.uint8), np.int64(1))

Will return an int64 array in the future because the type of np.int64(1) is strictly honoured. Currently a uint8 array is returned.

Impact on operators involving Python int, float, and complex#

This NEP attempts to preserve the convenience of the old behaviour when working with literal values. The current value-based logic had some nice properties when “untyped”, literal Python scalars are involved:

np.arange(10, dtype=np.int8) + 1  # returns an int8 array
np.array([1., 2.], dtype=np.float32) * 3.5  # returns a float32 array

But led to surprises when it came to “unrepresentable” values:

np.arange(10, dtype=np.int8) + 256  # returns int16
np.array([1., 2.], dtype=np.float32) * 1e200  # returns float64

The proposal is to preserve this behaviour for the most part. This is achieved by considering Python int, float, and complex to be “weakly” typed in operations. However, to avoid surprises, we plan to make conversion to the new type more strict: The results will be unchanged in the first two examples, but in the second one, it will change the following way:

np.arange(10, dtype=np.int8) + 256  # raises a TypeError
np.array([1., 2.], dtype=np.float32) * 1e200  # warning and returns infinity

The second one warns because np.float32(1e200) overflows to infinity. It will then continue to do the calculation with inf as usual.

Changes due to the integer “ladder of precision”#

When creating an array from a Python integer, NumPy will try the following types in order, with the result depending on the value:

long (usually int64) → int64 → uint64 -> object

which is subtly different from the promotion described above.

This NEP currently does not include changing this ladder (although it may be suggested in a separate document). However, in mixed operations, this ladder will be ignored, since the value will be ignored. This means, that operations will never silently use the object dtype:

np.array([3]) + 2**100  # Will error

The user will have to write one of:

np.array([3]) + np.array(2**100)
np.array([3]) + np.array(2**100, dtype=object)

As such implicit conversion to object should be rare and the work-around is clear, we expect that the backwards compatibility concerns are fairly small.

Old implementation of “values based” promotion#

This section reviews how the current value-based logic works in practice, please see the following section for examples on how it can be useful.

When NumPy sees a “scalar” value, which can be a Python int, float, complex, a NumPy scalar or an array:

1000  # Python scalar
int32(1000)  # NumPy scalar
np.array(1000, dtype=int64)  # zero dimensional

Or the float/complex equivalents, NumPy will ignore the precision of the dtype and find the smallest possible dtype that can hold the value. That is, it will try the following dtypes:

• Integral: uint8, int8, uint16, int16, uint32, int32, uint64, int64.

• Floating: float16, float32, float64, longdouble.

• Complex: complex64, complex128, clongdouble.

Note that e.g. for the integer value of 10, the smallest dtype can be either uint8 or int8.

NumPy never applied this rule when all arguments are scalar values:

np.int64(1) + np.int32(2) == np.int64(3)

For integers, whether a value fits is decided precisely by whether it can be represented by the dtype. For float and complex, the a dtype is considered sufficient if:

• float16: -65000 < value < 65000 (or NaN/Inf)

• float32: -3.4e38 < value < 3.4e38 (or NaN/Inf)

• float64: -1.7e308 < value < 1.7e308 (or Nan/Inf)

• longdouble: (largest range, so no limit)

for complex these bounds were applied to the real and imaginary component. These values roughly correspond to np.finfo(np.float32).max. (NumPy did never force the use of float64 for a value of float32(3.402e38) though, but it will for a Python value of 3.402e38.)

State of the current “value based” promotion#

Before we can propose alternatives to the current datatype system, it is helpful to review how “value based promotion” is used and can be useful. Value based promotion allows for the following code to work:

# Create uint8 array, as this is sufficient:
uint8_arr = np.array([1, 2, 3], dtype=np.uint8)
result = uint8_arr + 4
result.dtype == np.uint8

result = uint8_arr * (-1)
result.dtype == np.int16  # upcast as little as possible.

Where especially the first part can be useful: The user knows that the input is an integer array with a specific precision. Considering that plain + 4 retaining the previous datatype is intuitive. Replacing this example with np.float32 is maybe even more clear, as float will rarely have overflows. Without this behaviour, the above example would require writing np.uint8(4) and lack of the behaviour would make the following surprising:

result = np.array([1, 2, 3], dtype=np.float32) * 2.
result.dtype == np.float32

where lack of a special case would cause float64 to be returned.

It is important to note that the behaviour also applies to universal functions and zero dimensional arrays:

# This logic is also used for ufuncs:
np.add(uint8_arr, 4).dtype == np.uint8
# And even if the other array is explicitly typed:
np.add(uint8_arr, np.array(4, dtype=np.int64)).dtype == np.uint8

To review, if we replace 4 with [4] to make it one dimensional, the result will be different:

# This logic is also used for ufuncs:
np.add(uint8_arr, [4]).dtype == np.int64  # platform dependent
# And even if the other array is explicitly typed:
np.add(uint8_arr, np.array([4], dtype=np.int64)).dtype == np.int64

Proposed weak promotion#

This proposal uses a “weak scalar” logic. This means that Python int, float, and complex are not assigned one of the typical dtypes, such as float64 or int64. Rather, they are assigned a special abstract DType, similar to the “scalar” hierarchy names: Integral, Floating, ComplexFloating.

When promotion occurs (as it does for ufuncs if no exact loop matches), the other DType is able to decide how to regard the Python scalar. E.g. a UInt16 promoting with an Integral will give UInt16.

At no time is the value used to decide the result of this promotion. The value is only considered when it is converted to the new dtype; this may raise an error.

Use strongly-typed scalars or a mix of both#

The simplest solution to the value-based promotion/casting issue would be to use strongly typed Python scalars, i.e. Python floats are considered double precision and Python integers are always considered the same as the default integer dtype.

This would be the simplest solution, however, it would lead to many upcasts when working with arrays of float32 or int16, etc. The solution for these cases would be to rely on in-place operations. We currently believe that while less dangerous, this change would affect many users and would be surprising more often than not (although expectations differ widely).

In principle, the weak vs. strong behaviour need not be uniform. It would also be possible to make Python floats use the weak behaviour, but Python integers use the strong one, since integer overflows are far more surprising.

Do not use weak scalar logic in functions#

One alternative to this NEPs proposal is to narrow the use of weak types to Python operators.

This has advantages and disadvantages:

• The main advantage is that limiting it to Python operators means that these “weak” types/dtypes are clearly ephemeral to short Python statements.

• A disadvantage is that np.multiply and * are less interchangeable.

• Using “weak” promotion only for operators means that libraries do not have to worry about whether they want to “remember” that an input was a Python scalar initially. On the other hand, it would add a the need for slightly different (or additional) logic for Python operators. (Technically, probably as a flag to the ufunc dispatching mechanism to toggle the weak logic.)

• __array_ufunc__ is often used on its own to provide Python operator support for array-likes implementing it. If operators are special, these array-likes may need a mechanism to match NumPy (e.g. a kwarg to ufuncs to enable weak promotion.)

NumPy scalars could be special#

Many users expect that NumPy scalars should be different from NumPy arrays, in that np.uint8(3) + 3 should return an int64 (or Python integer), when uint8_arr + 3 preserves the uint8 dtype.

This alternative would be very close to the current behaviour for NumPy scalars but it would cement a distinction between arrays and scalars (NumPy arrays are “stronger” than Python scalars, but NumPy scalars are not).

Such a distinction is very much possible, however, at this time NumPy will often (and silently) convert 0-D arrays to scalars. It may thus make sense, to only consider this alternative if we also change this silent conversion (sometimes referred to as “decay”) behaviour.

Handling conversion of scalars when unsafe#

Cases such as:

np.arange(10, dtype=np.uint8) + 1000

should raise an error as per this NEP. This could be relaxed to give a warning or even ignore the “unsafe” conversion which (on all relevant hardware) would lead to np.uint8(1000) == np.uint8(232) being used.

Allowing weakly typed arrays#

One problem with having weakly typed Python scalars, but not weakly typed arrays is that in many cases np.asarray() is called indiscriminately on inputs. To solve this issue JAX will consider the result of np.asarray(1) also to be weakly typed. There are, however, two difficulties with this:

1. JAX noticed that it can be confusing that:

   np.broadcast_to(np.asarray(1), (100, 100))
   

   is a non 0-D array that “inherits” the weak typing. [2]

2. Unlike JAX tensors, NumPy arrays are mutable, so assignment may need to cause it to be strongly typed?

A flag will likely be useful as an implementation detail (e.g. in ufuncs), however, as of now we do not expect to have this as user API. The main reason is that such a flag may be surprising for users if it is passed out as a result from a function, rather than used only very localized.

Keep using value-based logic for Python scalars#

Some of the main issues with the current logic arise, because we apply it to NumPy scalars and 0-D arrays, rather than the application to Python scalars. We could thus consider to keep inspecting the value for Python scalars.

We reject this idea on the grounds that it will not remove the surprises given earlier:

np.uint8(100) + 1000 == np.uint16(1100)
np.uint8(100) + 200 == np.uint8(44)

And adapting the precision based on the result value rather than the input value might be possible for scalar operations, but is not feasible for array operations. This is because array operations need to allocate the result array before performing the calculation.