Support complex dtypes in `extra.array_api`

[honno]

The Array API has had it's first spec release 2021.12 a while now. The next release will add complex numbers, which would be nice to support in extra.array_api.

We could give make_strategies_namespace() say a new kwarg called api_version, to parallel how x.__array_namespace__() works in returning an Array API namespace of a particular version... I think any solution like this is something we'd like to avoid 😅

Good thing is I think it's okay to just ignore versioning until we need to ^{(which I don't think we ever will, as the parts of the Array API we do use seems pretty stable)}. I propose we still can only return one namespace, where we

• Generates complex dtype objects in xps.numeric_dtypes(), as per how "numeric" is treated in the draft spec. This would still work if xp doesn't have complex dtype objects, but would warn and thus is probably considered a breaking change.
• Introduce xps.real_dtypes() to generate integer and floating-point dtype objects, as per how "real" is treated in the draft spec. This essentially would take over the previous role of xps.numeric_dtypes().
• Introduce xps.complex_dtypes() to generate complex dtypes.
• Support generating complex values in xps.from_dtype(). This won't be a breaking change. Allow subnormal in complex_numbers #3409 should mean the hard part is already over with 🚀

First note: There was some explicit deliberation in Array API's semantic model of "numeric" and "real" (data-apis/array-api#418 (comment)). I think it should be safe to follow, and generally makes sense.

Second note: I think it's ultimately okay to make the somewhat breaking change to xps.numeric_dtypes(), given we note in the extra.array_api docs that

The Array API standard is not yet finalised, so this module will make breaking changes if necessary to support newer versions of the standard.

Although the Array API now has a finalised first release, we hadn't removed this note, and generally we hadn't settled that extra.array_api was now "stable". I think we don't have many users beyond array-api-tests anywho heh.

I do see that the v1 spec doesn't define complex dtypes as "numeric" (they're not listed anyway), or have any "real-valued" category. Still, I think it'll be fine to just clarify in the xps.numeric_dtypes() docstring what "sub-categories" (ints, uints, floats and complex) are included. I also think after complex support is added in v2 that these categories should be "stable".

Of course I'll be happy to make a PR once we settle on a general direction~

[Zac-HD]

I think we probably should support the api_version argument - alas! It's a bit annoying, but otherwise we'll have problems when Hypothesis supports a newer version of the array API standard than is implemented by the module we're wrapping.

• It would be really nice if there was some way to introspect an array API module to determine which versions it supports! Currently we could try calling __array_namespace__(api_version=...) with each known version, which I guess does cover all versions that Hypothesis knows how to support.
• If we're passed api_version=None I think that should be an error to disambiguate; but I'd like the default value to instead be ... (ellipsis literal), meaning "try known versions in sequence, newest-first, and return the first that works". That way if e.g. libX supports an older version of the standard we're compatible-by-default, which still allowing for an exact version to be specified for e.g. interop testing.

All your other notes sound great to me.

And thanks again for leading so much of the work around array-API testing! It's been really helpful for Hypothesis, and is a fantastic service to the broader ecosystem 😍

[honno]

Ok, I see now the user is saved if a future release makes a breaking change to the API surface we use. Humour me as I get my head around things—

Say an author of an array-consuming library is using extra.array_api to test their code like so

xps = make_strategies_namespace(np.array_api, api_version="2023.03")  # example future version

If there's a hypothetical breaking change in say spec release "2024.04", this won't affect the existing user's testing. If the user instead used

xps = make_strategies_namespace(np.array_api)

we'd be screwed, as yeah there's no way in the spec to get an array library namespace (e.g. np.array_api) version.

My proposed changes basically wouldn't break using np.array_api as it is right now (i.e. a v1 implementation). But to future-proof against possible breaking changes in the future, we should add in versioned strategy namespaces before we make extra.array_api "stable".

---

It would be really nice if there was some way to introspect an array API module to determine which versions it supports! Currently we could try calling __array_namespace__(api_version=...) with each known version, which I guess does cover all versions that Hypothesis knows how to support.

Ayup. I'm assuming you're alluding to the x.__array_namespace__() spec saying

If the given version is invalid or not implemented for the given module, an error should be raised.

where we'd be try... except Exception-ing a throwaway array when we call make_strategies_namespace(), which should work but yeah feels a bit iffy.

If we're passed api_version=None I think that should be an error to disambiguate; but I'd like the default value to instead be ... (ellipsis literal), meaning "try known versions in sequence, newest-first, and return the first that works". That way if e.g. libX supports an older version of the standard we're compatible-by-default, which still allowing for an exact version to be specified for e.g. interop testing.

I think this is an excellent solution! I got a headache thinking how a parallel api_version kwarg should work when I wrote this issue 😅 I can get to writing a PR that does this, where particularly we can explore/deliberate on the logic for trying known versions.

So would we want say a "draft" argument which lets us access a namespace with no guarantees, document as such and possibly even raise a warning still. The expectation is that the namespace would follows the draft spec, where Hypothesis-we (and end users? probably just array-api-tests) can implement/test things before releases, with an appreciation that we might chuck things away.

---

Also thanks heh, you've been a mighty help too!

btw, the NumPy folks are looking to adopt the Array API on it's top-level 🎉 Such a transition should be deliberated upon in an upcoming NEP, but I guess it probably won't matter to Hypothesis for a fair bit.