docs: add Numba CUDA guide (#2260)

[ianna]

No description provided.

[ianna]

@agoose77 - I'm not sure if I need to link it. Please, have a look. Thanks!

[codecov]

Codecov Report

Merging #2260 (93b5226) into main (ef3e2a9) will decrease coverage by 0.03%.
The diff coverage is 100.00%.

❗ Current head 93b5226 differs from pull request most recent head a06ce43. Consider uploading reports for the commit a06ce43 to get more accurate results

Additional details and impacted files

Impacted Files	Coverage Δ
src/awkward/numba.py	93.87% <100.00%> (ø)
src/awkward/_util.py	74.42% <0.00%> (-0.58%)	⬇️
src/awkward/forms/unionform.py	81.95% <0.00%> (-0.14%)	⬇️
src/awkward/typing.py	83.33% <0.00%> (ø)
src/awkward/__init__.py	97.14% <0.00%> (ø)
src/awkward/operations/__init__.py	100.00% <0.00%> (ø)
src/awkward/operations/ak_almost_equal.py	94.54% <0.00%> (ø)
src/awkward/operations/ak_broadcast_fields.py
src/awkward/contents/recordarray.py	84.77% <0.00%> (+0.07%)	⬆️

[agoose77]

We need to think about how to deploy these docs; we don't have a CUDA-enabled runner currently in-action. My current thinking is that we might be able to deploy only the CUDA docs from e.g. a scheduled CUDA worker. This would push an .ipynb to our repo, so that we can build the rest of docs with our normal CI such that they are always in sync with main.

It's not a perfect solution, and for now we can just do this manually.

[agoose77]

@ianna I changed the result to be a CuPy array instead of Numba. The reason for this is that backend="cuda" uses CuPy under the hood (so it's already a required dependency for zero-copy CUDA use), CuPy arrays can be passed directly into ak.Array, and they also have nice reprs. We might want to make ak.Array et al. understand how to consume __cuda_array_interface__ so that ak.Array can consume Numba's DeviceArray, but that's another PR :)

[ianna]

@ianna I changed the result to be a CuPy array instead of Numba. The reason for this is that backend="cuda" uses CuPy under the hood (so it's already a required dependency for zero-copy CUDA use), CuPy arrays can be passed directly into ak.Array, and they also have nice reprs. We might want to make ak.Array et al. understand how to consume __cuda_array_interface__ so that ak.Array can consume Numba's DeviceArray, but that's another PR :)

I'm actually updating the PR with a better example :-)

[jpivarski]

I'm actually updating the PR with a better example :-)

I didn't notice this before I clicked "Update branch", so be sure to git pull.

(I wanted to see if the "Build Docs" failure is the same everywhere, or if it's only in #2268.)

[jpivarski]

I streamlined the text and code samples to make them easier to learn from. But on the whole, it's a very good tutorial!

I'm assuming that the reason it's a notebook (ipynb file) rather than Jupytest (md file) is because it must not be allowed to run on the CI, due to the dependence on a GPU. If that's the reason, it makes sense to me.

Feel free to merge it when you're ready.

[agoose77]

Yes, the file is an ipynb so that the outputs can be stored in the notebook. There is discussion around extending the scope of text based notebooks in future, but for our purposes this works :)

[ianna]

@jpivarski - thanks, it looks great! I don't know why the tests are not finished - but before they do I cannot merge it.

[agoose77]

Tests don't run for non-code changes! I can merge this, then :)