docs: add migration guides and tutorial

[mtsokol]

This PR adds a migration guide (versions for array consumers and producers) and one migration tutorial showing how a simple power-iteration based algorithm from GraphBLAS can be moved to an Array API compatible version.

[ev-br]

This is very nice.

I've a left several comments, mostly very minor. There are two themes:

• for the migration guide, I think it would be helpful to be some more specific and some more opinionated.
• In the tutorial, I love the power iteration example. The only concern is that you talk about JIT, but the example does not jit, not easily at least. So maybe either expand a bit on how to actually jit it, or state that not everything is benefits from jitting and add one more example which does?

[ev-br]

This suggestion reads as aimed at array API producers. Consider expanding to mention that an array API consumer can run their test suite with array-api-strict as a producer.

As a larger edit, consider briefly stressing in these short descriptions that array-api-compat is mainly for consumer's code, array-api-strict is a testing implement, also mostly for a consumer; array-api-tests is for a producer. While you are discussing this in more detail below, I think it'd be helpful to stress it in the very beginning, too.

[mtsokol]

Done - I added a User group clause to each library and mentioned how producers/consumers use it.

[ev-br]

Minor: add a link to https://hypothesis.readthedocs.io/en/latest/ + a couple of sentensies to explicitly state that hypothesis generates this many examples, where each example is a valid combination of inputs; and that the recommendation is to use as many examples as reasonable for the time budget.

[mtsokol]

Done

[ev-br]

Suggested change

	- `--skips-file` for skipping files. At times some failing tests might stall
	- `--skips-file` for skipping tests. At times some failing tests might stall

[mtsokol]

Done

[ev-br]

For consumers, the support is less than ideal, consider mentioning array-api-compat and array_namespace function already?

In [9]: for xp in [np, torch, jnp, cupy, da, array_api_strict]:
   ...:     try:
   ...:         xp.ones(3).__array_namespace__()
   ...:         print(f"{xp.__name__}  check")
   ...:     except:
   ...:         print(f"{xp.__name__}  nope")
   ...: 
numpy  check
torch  nope
jax.numpy  check
cupy  nope
dask.array  nope
array_api_strict  check

[mtsokol]

Done - I mentioned array_api_compat.array_namespace() as well there.

[ev-br]

If this is a first tutorial for a beginner, I think it could be helpful to be a bit more descriptive and a bit more opinionated. Roughly,

• for a function which accepts array arguments, use

def func(array1, scalar1, scalar2):
    xp = array1.__array_namespace__()     # or array_namespace(array1)
    return xp.arange(scalar1, scalar2) @ array1

• for a function that accepts scalars and returns arrays, use

def func(s1, s2, xp):
   return xp.arange(s1, s2)

If you prefer to not clutter the short guide with details, consider adding them to a separate page and linking from the short guide.

[mtsokol]

Done

[ev-br]

But jax jitting this iterative function with data-dependent control flow doesn't work! Simplifying a bit the hits function to accept an array-like, and jitting --- which is what I would do first thing after reading this tutorial--- gives

In [19]: def hits(A, max_iter=100, tol=1.0e-8, normalized=True):
    ...:     A = xp.asarray(A)
    ...:     N = A.shape[0]
    ...:     h = xp.full(N, 1.0 / N)
    ...:     # Power iteration: make up to max_iter iterations
    ...:     for _i in range(max_iter):
    ...:         hprev = h
    ...:         a = hprev @ A
    ...:         h = A @ a
    ...:         h = h / xp.max(h)
    ...:         if is_converged(hprev, h, N, tol):
    ...:             break
    ...:     else:
    ...:         raise Exception("Didn't converge")
    ...:     if normalized:
    ...:         h = h / xp.sum(xp.abs(h))
    ...:         a = a / xp.sum(xp.abs(a))
    ...:     return h, a
    ...: 
    ...: def is_converged(xprev, x, N, tol):
    ...:     err = xp.sum(xp.abs(x - xprev))
    ...:     return err < xp.asarray(N * tol)
    ...: 

In [20]: import jax.numpy as xp

In [21]: jax.jit(hits)(jnp.eye(3))
---------------------------------------------------------------------------
TracerBoolConversionError                 Traceback (most recent call last)
Cell In[21], line 1
----> 1 jax.jit(hits)(jnp.eye(3))

    [... skipping hidden 13 frame]

Cell In[19], line 11, in hits(A, max_iter, tol, normalized)
      9     h = A @ a
     10     h = h / xp.max(h)
---> 11     if is_converged(hprev, h, N, tol):
     12         break
     13 else:

    [... skipping hidden 1 frame]

File ~/.conda/envs/scipy-dev/lib/python3.12/site-packages/jax/_src/core.py:1806, in concretization_function_error.<locals>.error(self, arg)
   1805 def error(self, arg):
-> 1806   raise TracerBoolConversionError(arg)

TracerBoolConversionError: Attempted boolean conversion of traced array with shape bool[].
The error occurred while tracing the function hits at <ipython-input-19-d5a4e616b039>:1 for jit. This concrete value was not available in Python because it depends on the value of the argument A.
See https://docs.jax.dev/en/latest/errors.html#jax.errors.TracerBoolConversionError

[mtsokol]

Sorry for not being clear in the text. It says JIT compile a loop body with JAX's JIT compilation, so to JIT compile what is in the for _i in range(...). That is the hot part that we want to compile into a single kernel.
It's the same premise as in the JAX documentation:

To make it fully digestible by a beginner user I embedded a copy-paste code at the bottom with JAX jit compiled version. Is it sufficiently clear?

[ev-br]

I honestly don't understand this statement. err is an array, you are converting the r.h.s. to a 0D too, so is_converged function returns a 0D array, and if is_converged(...) relies on an automagic bool(0D_array) conversion. Which would also synchronize a device when run on a GPU.

[mtsokol]

Here rhs and lhs are 0D arrays in the current form, and the result is a 0D so that it can be used as if condition.
We're outside of JIT compiled part (as explained in the previous comment) so we don't need to worry about synchronization.