DOC: numpy.result_type promotion "algorithm" is outdated

[MustafaYounes1]

Describe the issue:

According to the API Reference, the algorithm of numpy.result_type determines the output type following these steps:

1. Categories are determined by first checking which of boolean, integer (int/uint), or floating point (float/complex) the maximum kind of all the arrays and the scalars are.

2. If there are only scalars or the maximum category of the scalars is higher than the maximum category of the arrays, the data types are combined with promote_types to produce the return value.

3. Otherwise, min_scalar_type is called on each scalar, and the resulting data types are all combined with promote_types to produce the return value.

However, when it's provided with a Python scalar and an ndarray of the same category (e.g., int), it seems it completely ignores the scalar and outputs whatever datatype the ndarray has (and that contradicts the third point above; according to the doc, it should apply min_scalar_type on the scalar, and follow that with a call to promote_types).

However, when the provided scalar is a NumPy scalar, the behavior is different: what it seemingly does is only a call to promote_types

So, I'm wondering why the behavior is inconsistent on NumPy/Python scalars, and what exactly the role of min_scalar_type is in this context?

Please take a look at the provided code that shows this unexpected behaviour with a couple of examples.

Reproduce the code example:

import numpy as np

#############
# Example 1 #
#############

# Both the ndarray and the scalar are of the same category (int)

s = -129
a = np.empty(1, dtype='i1')

# Python Scalar & ndarray

# The following outputs 'int8' (completely ignoring the scalar)
print(np.result_type(s, a))

# according to the doc; it should have called:
print(np.promote_types(np.min_scalar_type(s), a.dtype))  # gives int16

# NumPy Scalar & ndarray

# gives 'int16' (seemingly only calls np.promote_types)
print(np.result_type(np.int16(s), a))  
 
#############
# Example 2 #
#############

# The ndarray has a higher category (float vs int)

s = np.iinfo(np.int64).max
a = np.empty(1, np.float32)

# Python Scalar & ndarray

# The following outputs 'float32' (completely ignoring the scalar)
print(np.result_type(s, a))

# according to the doc; it should have called:
print(np.promote_types(np.min_scalar_type(s), a.dtype))  # gives float64

# NumPy Scalar & ndarray

# gives 'float64' (seemingly only calls np.promote_types)
print(np.result_type(np.int64(1), a))

# Pay attention to the following: (np.min_scalar_type is not used at all)
print(np.min_scalar_type(np.int64(1)))  # gives uint8
print(np.promote_types(np.min_scalar_type(np.int64(1)), a.dtype)) # gives float32

Python and NumPy Versions:

Python: 3.11.5
NumPy: 2.3.1

[jakevdp]

However, when it's provided with a Python scalar and an ndarray of the same category (e.g., int), it seems it completely ignores the scalar and outputs whatever datatype the ndarray has

I believe what you describe is the expected behavior in NumPy 2.0. See NumPy 2.0 migration guide: Changes to NumPy data type promotion for details on this.

It may be that the docs you are looking at predate NumPy 2.0 and need to be updated.

[MustafaYounes1]

@jakevdp Thanks for the info!

I took a glance at the relevant NEP. It has a lot of information about old behavior vs new behavior, issues, reasoning, related work, etc. (An excellent reference for backwards compatibility)

However, I do agree with you and believe that it's crucial for the API reference to have a sort of brief explanation of the current state of NumPy 2.0's new promotion rules.

I presume this issue shouldn't be closed for now.

[seberg]

Agreed thanks for noticing. The documentation needs updating it is completely incorrect now. We have a new overview page for promotion (outside of the NEP), unless I am very mistaken. The best thing might be to just link to there.

If there is something to link, then this is a good small issue to just attack (otherwise it's OK, but formulating this stuff right tends to be tricky).