Adopt the `numpy.array_api` module as `cupy.array_api` #5698

This is based on the function stubs from the array API test suite, and is currently based on the assumption that NumPy already follows the array API standard. Now it needs to be modified to fix it in the places where NumPy deviates (for example, different function names for inverse trigonometric functions).

…ult numpy namespace

…space

…dual files The specific submodule organization is an implementation detail and should not be used. Only the top-level numpy._array_api namespace should be used.

This avoids importing everything inside the individual functions, but still is preferred over importing the functions used explicitly, as most of them clash with the wrapper function names.

The docstrings just point back to the functions they wrap for now. More thought may need to be put into this for the future. Most functions can actually perhaps inherit the docstring of the function they wrap directly, but there are some functions that have differences (e.g., different names, different keyword arguments, fewer keyword arguments, etc.). There's also the question of how to handle cross-references/see alsos that point to functions not in the API spec and behavior shown in docstring examples that isn't required in the spec.

This is mostly aimed at any potential reviewers of the module for now.

Some stubs still need to be modified to properly pass mypy type checking. Also, 'device' is just left as a TypeVar() for now.

(see data-apis/array-api#116)

…eturn a scalar This is needed to pass mypy type checks for the given type annotations.

…bmodule That way they only work on actual ndarray inputs, not array-like, which is more inline with the spec.

So far, it just is a wrapper with all the methods defined in the spec, which all pass through. The next step is to make it so that the methods that behave differently actually work as the spec describes. We also still need to modify all the array_api functions to return this wrapper object instead of np.ndarray.

…ndarray class These methods aren't required by the spec, but without them, the array object is harder to use interactively.

…nctions The array API namespace is designed to be only those parts of specification that are required. So many things that work in NumPy but are not required by the array API specification will not work in the array_api namespace functions. For example, transcendental functions will only work with floating-point dtypes, because those are the only dtypes required to work by the array API specification.

The array API namespace is not going to do type checking against arbitrary objects. An object that takes an array as input should assume that it will get an array API namespace array object. Passing a NumPy array or other type of object to any of the functions is undefined behavior, unless the type signature allows for it.

…ike()

The spec does not actually specify whether these should be dimension 0 arrays or Python floats (which they are in NumPy). However, making them dimension 0 arrays is cleaner, and ensures they also have all the methods and attributes that are implemented on the ndarray object.

…rays

…bject

As discussed at https://mail.python.org/pipermail/numpy-discussion/2021-February/081541.html, _implementation is not as useful for the array API module as previously thought.

…espace The private function _validate_indices describes the cases that are disallowed. This functionality should be tested (it isn't yet), as the array API test suite will only test the cases that are allowed, not that non-required cases are rejected.

… the first argument

…s integers Without this the error message would be a confusing message about object arrays not being supported.

The array API does not require any methods or behaviors on dtype objects, other than that they be literals that can be compared for equality and passed to dtype keywords in functions. Since dtype objects are already used by the dtype attribute of ndarray, this makes it consistent, so that func(dtype=<dtype>).dtype will give exactly <dtype> back, which will be the same thing as numpy._array_api.<dtype>. This also fixes an issue in the array API test suite due to the fact that dtype classes and objects are not equal as dictionary keys.

…s and operators NumPy's type promotion behavior deviates from the spec, which says that type promotion should work independently of shapes or values, in cases where one array is 0-d and the other is not. A helper function is added that works around this issue by adding a dimension to the 0-d array before passing it to the NumPy function. This function is used in elementwise functions and operators. It may still need to be applied to other functions in the namespace. Additionally, this fixes: - The shift operators (<< and >>) should always return the same dtype as the first argument. - NumPy's __pow__ does not type promote the two arguments, so we use the array API pow() in ndarray.__pow__, which does. - The internal _promote_scalar helper function was changed to return an array API ndarray object, as this is simpler with the inclusion of the new _normalize_two_args helper in the operators.

… the array API namespace

…of the spec

For now, only the functions in from the main spec namespace are implemented. The remaining linear algebra functions are part of an extension in the spec, and will be implemented in a future pull request. This is because the linear algebra functions are relatively complicated, so they will be easier to review separately. This also updates those functions that do remain for now to be more compliant with the spec.

That way they aren't ambiguous with the attributes with the same names.

The actual class name doesn't matter because it isn't part of the namespace API (arrays should be constructed with the array creation functions like asarray()). However, it is better to use a name that is different from the existing NumPy array object to avoid ambiguity.

This includes returning custom dataclasses for finfo and iinfo that only contain the properties required by the array API specification.

…iv__ See data-apis/array-api#221.

They should not accept int. PEP 484 actually makes int a subtype of float, so this won't actually affect type checkers the way we would want.

These are easier for type checkers to handle.

The spec previously said it should return the type of the left argument, but this was changed to do type promotion to be consistent with all the other elementwise functions/operators.

…pace

…spec

The array API requires that elementwise functions always give a value, like nan. However, it doesn't specify that the functions need not give warnings. It is possible here to still break things by manually changing warnings into errors with np.seterr(), but this is considered unsupported behavior.

…constructor

The tests for the module will mostly focus on those things that aren't already tested by the official array API test suite (https://github.com/data-apis/array-api-tests). Currently, indexing tests are added, which test that the Array object correctly rejects otherwise valid indices that are not required by the array API spec.

np.result_type() has too many behaviors that we want to avoid in the array API namespace, like value-based casting and unwanted type promotions. Instead, we implement the exact type promotion table from the spec.

Only those type promotions that are required by the spec are allowed. In particular, promotions across kinds, like integer + floating-point, are not allowed, except for the case of Python scalars. Tests are added for this. This commit additionally makes the operators return NotImplemented on unexpected input types rather than directly giving a TypeError. This is not strictly required by the array API spec, but it is generally considered a best practice for operator methods in Python. This same thing will be implemented for the various functions in the array API namespace in a later commit.

This is consistent with @ and with NumPy.

It is similar to floor() and ceil() but I missed it previously.

See numpy/numpy#18585 (comment).

Other spellings like dtype=int or dtype='i' are not part of the spec.

As with the other array API tests, the tests primarily focus on things that should error. Working behavior is tested by the official array API test suite.

Instead of the leading underscore, the experimentalness of the module will be indicated by omitting a warning on import. That we, we do not have to change the API from underscore to no underscore when the module is no longer experimental.

asarray() is already called in Array._new.

They are not an official part of the spec but are useful for various parts of the implementation.

Some of the imports in the array API module have to be inside functions to avoid circular imports, but these ones did not.

…l-only See data-apis/array-api#100.

I've omitted a few changes from black that messed up the readability of some complicated if statements that were organized logically line-by-line, and some changes that use unnecessary operator spacing.

This was blocked on #18536, which has been merged.

NumPy has dropped Python 3.7, so these are no longer necessary (and they didn't completely work anyway).

- replace numpy/np by cupy/cp - make the tests runnable in CuPy's tester - comment out two failing tests (which I believe is OK)

Commits on Sep 7, 2021

build a skeleton for docs

leofang committed Sep 7, 2021

Configuration menu

View commit details

Copy full SHA for b81eb39

Browse repository at this point

Copy the full SHA

b81eb39 View commit details

Browse the repository at this point in the history

Commits on Sep 8, 2021

expand docs

leofang committed Sep 8, 2021

Configuration menu

View commit details

Copy full SHA for d3a6f0d

Browse repository at this point

Copy the full SHA

d3a6f0d View commit details

Browse the repository at this point in the history

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adopt the `numpy.array_api` module as `cupy.array_api` #5698

Adopt the `numpy.array_api` module as `cupy.array_api` #5698

Commits on Sep 5, 2021

Commits on Sep 6, 2021

Commits on Sep 7, 2021

Commits on Sep 8, 2021

Commits on Sep 24, 2021

Adopt the numpy.array_api module as cupy.array_api #5698

Adopt the numpy.array_api module as cupy.array_api #5698

Commits on Sep 5, 2021

Commits on Sep 6, 2021

Commits on Sep 7, 2021

Commits on Sep 8, 2021

Commits on Sep 24, 2021

Adopt the `numpy.array_api` module as `cupy.array_api` #5698

Adopt the `numpy.array_api` module as `cupy.array_api` #5698