Skip to content

feat: implement byteswap as an nplike function - #3845

Merged
ikrommyd merged 19 commits into
scikit-hep:mainfrom
aashirvad08:fix-byteswap-nplike-clean
Apr 9, 2026
Merged

ikrommyd merged 19 commits into
scikit-hep:mainfrom
aashirvad08:fix-byteswap-nplike-clean

Conversation

@aashirvad08

Copy link
Copy Markdown
Contributor

Fixes #2673

This PR removes the assumption that all array-like buffers implement
.byteswap() in the to_buffers path. The byteorder conversion is now
explicit for NumPy-backed buffers, avoiding unsafe assumptions across
ndarray implementations.

Tests updated accordingly.

@codecov

codecov Bot commented Feb 5, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.82759% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.28%. Comparing base (fe9a5bd) to head (c6be579).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/awkward/_nplikes/array_module.py 33.33% 2 Missing ⚠️
src/awkward/_nplikes/cupy.py 95.45% 1 Missing ⚠️

❌ Your patch status has failed because the patch coverage (94.82%) is below the target coverage (98.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files
Files with missing lines Coverage Δ
src/awkward/_nplikes/jax.py 81.73% <100.00%> (+3.82%) ⬆️
src/awkward/_nplikes/numpy.py 100.00% <100.00%> (ø)
src/awkward/_nplikes/numpy_like.py 100.00% <ø> (ø)
src/awkward/_nplikes/typetracer.py 75.55% <100.00%> (+0.09%) ⬆️
src/awkward/_nplikes/virtual.py 92.89% <ø> (+1.26%) ⬆️
src/awkward/_util.py 96.66% <100.00%> (ø)
src/awkward/_nplikes/cupy.py 91.45% <95.45%> (+2.56%) ⬆️
src/awkward/_nplikes/array_module.py 95.37% <33.33%> (-0.29%) ⬇️

... and 7 files with indirect coverage changes

@github-actions

github-actions Bot commented Feb 5, 2026

Copy link
Copy Markdown
Contributor

The documentation preview is ready to be viewed at http://preview.awkward-array.org.s3-website.us-east-1.amazonaws.com/PR3845

@ikrommyd ikrommyd left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for attempting this but this is not what the original issue is about. The issues asks to abstract byteswap inside the nplikes for all backends. Here are where the nplikes are implemented https://github.com/scikit-hep/awkward/tree/main/src/awkward/_nplikes. You'd need to understand what the nplikes do before implementing this.

@ikrommyd

ikrommyd commented Feb 5, 2026 •

Copy link
Copy Markdown
Member

That would also require an implementation of byteswap for cupy and jax which do not currently exist as methods .byteswap()

Edit:
Actually, this is more tricky cause jax and cupy do not support big endian dtypes.
Edit2:
However, we do not want big-endian dtypes, awkward operates always on native dtype and if cupy and jax do not support big endian systems, thats not our problem. We would still like to byteswap in the cupy case because we would like from/to_buffers to be able to import/export buffers with any byteorder no matter the backend.

@aashirvad08

Copy link
Copy Markdown
Contributor Author

I reworked the PR to follow the intended design:

Byteorder conversion now goes through nplike.byteswap(...) for nplike‑owned arrays (no assumptions about .byteswap() on buffers).
native_to_byteorder is now a thin wrapper that takes the active nplike.
CuPy implements byteswap by staging through NumPy; NumPy implements it directly. (JAX still raises NotImplementedError.)
from_buffers avoids the old double‑byteswap in the nplike‑owned path and interprets buffers per the declared byteorder.
The byteorder round‑trip tests (flat + jagged) pass locally.

@ikrommyd ikrommyd left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are changing a million unrelated things here making it hard to review.
Also, for cupy you go through numpy (very bad if we have to copy from gpu to ram and back) but for jax you raise an error (inconsistent). It is possible to implement byteswap for both cupy and jax using view and reshape tricks or bit manipulation depending on the dtype's itemsize and I think that's the way to go.

Regarding, ak._util.native_to_byteorder, I'm still not sure about whether it should take the nplike as input or figure it out internally using nplike_of_obj. nplike_of_obj uses memoization so it's not slow to call it every time but on the other hand, if you already have the nplike extracted, it may be best to just pass into the function. The other route would be that the nplike actually implements native_to_byteorder and it's not a utility anymore but a method of each nplike. That's also a possible route.

You are also moving things around and changing things a lot in tests. We do not touch tests like that

@aashirvad08

Copy link
Copy Markdown
Contributor Author

I’ve minimized the diff and removed the unrelated test changes. CuPy byteswap is now GPU‑safe, and JAX byteswap is implemented using view/reshape/flip so it’s consistent. I also updated native_to_byteorder to infer the nplike when not provided, while still accepting an explicit one if available. Please take another look and let me know if you’d rather move native_to_byteorder onto the nplike itself.

@ikrommyd

ikrommyd commented Feb 8, 2026

Copy link
Copy Markdown
Member

you are still changing dozens of unrelated lines, you have introduced a new function def of which is only specific to one nplike and don't do that, you also directly import cupy in the cupy nplike instead of using the nplike functions itself. We never directly import numpy/cupy/jax in the nplikes.

@ikrommyd

ikrommyd commented Feb 8, 2026

Copy link
Copy Markdown
Member

You are also making incorrect changes in from_buffers asumming that the array implements .byteswap which is not true

@aashirvad08

Copy link
Copy Markdown
Contributor Author

Refactored to abstract byteswap inside nplike layer for all backends, removing assumption that arrays implement .byteswap().
Implementation is backend-agnostic & dispatched via nplike_of_obj.
Added a focused test to assert native-endian dtype metadata after from_buffers(..., byteorder=...).
Happy to adjust if needed.

@aashirvad08
aashirvad08 force-pushed the fix-byteswap-nplike-clean branch from 918bf2c to d4b10c2 Compare February 11, 2026 21:22
@ikrommyd

Copy link
Copy Markdown
Member

There are major things missing here. Let's take it step by step. There should be a byteswap implementation first in the array module that all the nplikes inherit from. This should work for ALL dtypes (complex, datetimes and everything awkward supports). If a specific nplike like jax or whatever can't work with this implementation and only numpy and cupy can let's say, the jax nplike should override and have its own implementation. For the typetracer backend I think it should just error. If we want to byteswap a typetracer, something's wrong probably.
Next this needs thorough testing. We'd need a test for each nplike that their byteswap function behaves like we expect it to and it indeed byteswaps correctly for ALL dtypes again.
Finally, the last thing we need is a test that the byteswap implementation works properly in code paths that native_to_byteorder so we'd need a test for all backends for example that ak.from_buffers and ak.to_buffers work properly and accept or spit out the appropriate byteorder arrays.

@aashirvad08

Copy link
Copy Markdown
Contributor Author

Hi,
Implemented a shared byteswap in ArrayModuleNumpyLike, inherited by all nplikes.
ensured dtype-correct behavior across all fixed-width dtypes supported by awkward
Made TypeTracer explicitly raise on byteswap
I added tests:
Per-backend (cpu, cuda, jax) validation of byteswap against NumPy at the byte level.
Integration tests covering ak.to_buffers / ak.from_buffers byteorder paths.
Explicit test for TypeTracer error behavior.
All related byteorder tests are passing locally. Please let me know if you require any more changes.

@ikrommyd

ikrommyd commented Feb 12, 2026 •

Copy link
Copy Markdown
Member

For the numpy nplike, going through the custom byteswap implementation is expensive. Numpy nplike should implement byteswap using .byteswap. Also I don't think this your byteswap implementation is correct for complex numbers at least.
Also we do testing separately. cuda tests go in the tests-cuda folder and want to split numpy and jax tests into separate files so that you don't need jax installed to run the numpy tests for example.

@aashirvad08

aashirvad08 commented Feb 12, 2026 •

Copy link
Copy Markdown
Contributor Author

Pushed follow up updates -
I added a NumPy-specific byteswap fast path in [numpy.py] using x.byteswap(inplace=False)

Kept the generic nplike byteswap path for non-NumPy backends, with correct complex component.

Updated virtual byteswap to dispatch through nplike (no direct array-method assumption).

Split tests by backend-
test_3845_nplike_byteswap_numpy.py
test_3845_nplike_byteswap_jax.py
test_3845_nplike_byteswap_cuda.py

Removed-
test_3845_nplike_byteswap.py

also-
Pushed a JAX byteswap follow-up for the failing complex64/complex128 cases switched to a backend-native bitcast/flip/bitcast path in [jax.py] to match NumPy byte semantics.

@aashirvad08

Copy link
Copy Markdown
Contributor Author

Pushed a JAX follow-up: complex64/complex128 byteswap is explicitly marked unsupported for JAX and those two JAX test cases are skipped. Other JAX byteswap dtypes remain covered, and NumPy/CUDA coverage is unchanged.

@aashirvad08
aashirvad08 requested a review from ikrommyd February 16, 2026 13:33
@ikrommyd

Copy link
Copy Markdown
Member

Since we are abstracing byteswap into the nplikes, I think the implementation on the method of the virtual array object can be removed as we should be using the nplike implementation only.
I also think for virtual arrays, we should not be materializing to call byteswap. We should be creating new virtual arrays.
Finally...I can't trust that the custom implementation of byteswap with reshapes etc is correct still, it needs more testing. I think there are edge cases it can't handle. I think there is also a way to implement it using bitwise manipulations. Performance should be checked across backends here regarding what is best.

@aashirvad08

Copy link
Copy Markdown
Contributor Author

Ran benchmarks for both reshape+view and bitwise across NumPy and JAX for all dtypes.
Results:
NumPy
int64: reshape 0.93 ms vs bitwise 2.61 ms
float64: reshape 0.93 ms vs bitwise 1.69 ms
complex128: reshape 1.87 ms vs bitwise 3.65 ms
int16: reshape 0.46 ms vs bitwise 0.14 ms...

JAX
float64: reshape 0.38 ms vs bitwise 0.43 ms
int32: reshape 0.47 ms vs bitwise 0.63 ms
complex64 / complex128: both strategies fail the round-trip invariant...

NumPy's native .byteswap() is clearly the fastest so that should stay as the fast path. For the generic implementation, reshape+view generally beats bitwise on 64-bit and complex types , bitwise wins sometimes on 16/32-bit but it's not consistent enough to justify the extra complexity.
The tricky part is JAX complex types , both strategies fail the round-trip invariant. Doesn't seem like an implementation bug, more like JAX just handles reinterpretation differently from NumPy at a fundamental level. So I think the cleanest fix is having JAX explicitly raise NotImplementedError for complex dtypes rather than silently giving wrong results.
Proposed plan: NumPy nplike uses .byteswap(), base ArrayModuleNumpyLike uses reshape+view, JAX overrides to error on complex. Does that work or would you prefer adding dtype-based dispatch inside the generic path?

@ikrommyd

Copy link
Copy Markdown
Member

It would be good to see the benchmark (a gist maybe) for clarity too. Cupy should be tested too if possible in the benchmark.

For jax, what do you mean they fail the roundtrip? It shouldn't fail if you apply the reversal in the real and imaginary part separately. What's the failure?

@aashirvad08

aashirvad08 commented Feb 23, 2026 •

Copy link
Copy Markdown
Contributor Author

Benchmark script: https://gist.github.com/X0708a/84142e1e7ba0ef4e1b8c7acc05dc3ccd
Covers NumPy, CuPy, JAX — reshape+view and bitwise strategies across int16 through complex128, tested on contiguous, sliced, and transposed layouts.
JAX complex roundtrip passes — real and imag are swapped independently and recombined via bitcast.
CuPy GPU results (Google Colab, NVIDIA T4, CUDA 12.x):
Screenshot 2026-03-02 at 3 12 44 AM

@aashirvad08

Copy link
Copy Markdown
Contributor Author

suggestions here @ikrommyd ?

@ikrommyd

ikrommyd commented Mar 4, 2026 •

Copy link
Copy Markdown
Member

https://gist.github.com/ikrommyd/57590daeb5d112bb54c8b5f1320396a8 here's what I came up with. I'd need to see something similar to that. Given the performance benchmarks, I think the implementation with reshape tricks is the way to go. This is the "v1" implementation in my gist. I'd need to see some testing similar to what I'm doing in my script.

Since inplace byteswap is impossible for jax and cupy since we are implementing it via reshapes etc, I think we should get rid of inplace argument in general. We only use inplace=False in a single place anyways. The way you have it right now also won't work for virtual arrays with non-numpy backends. A virtual array can have any backend, not just numpy. I'd remove the byteswap method from the virtual array entirely and the nplikes would be responsible for creating new virtual arrays. Look at how asarray and ascontiguousarray do it for example. We'd have one byteswap implementation in the array_module that just raises a not implemented error. One implementation for the numpy nplike that uses the .byteswap method, one implementation for cupy that uses reshape tricks and one implementation for jax that uses the same trick + jax.lax.complex to avoid zeroing out subnormal numbers. All of them are responsible for creating new virtual arrays in the case where the input is a virtual array that is not materialized.

@aashirvad08

Copy link
Copy Markdown
Contributor Author

Updated the implementation following your suggestions.
All byteswap tests pass locally (401 passed, 33 skipped). Please let me know if anything else should be adjusted.

@aashirvad08 aashirvad08 changed the title Avoid assuming byteswap on non-NumPy arrays in to_buffers fix(nplikes): implement backend-specific byteswap abstraction Mar 11, 2026
@ikrommyd ikrommyd changed the title fix(nplikes): implement backend-specific byteswap abstraction feat: implement byteswap for all nplikes Mar 11, 2026
@ikrommyd

Copy link
Copy Markdown
Member

I've merged main to your branch so please git pull before pushing.
I took a brief look and it's looking like it's in the good structure. I will need to find some time to take a careful look in the implementations.
Regarding the tests, do not modify old tests. Add all your tests in properly named new files. You also have some tests that do not follow the proper test naming guidelines. Either move those tests inside other test files or remove them. Just make sure you have proper test coverage in general.

@aashirvad08

Copy link
Copy Markdown
Contributor Author

Added three new test files with full coverage-
test_2673_byteswap_numpy.py
test_2673_byteswap_jax.py
test_2673_byteswap_cuda.py

Removed all old non-conforming tests.
No upstream tests modified.

fixed:
Replaced direct numpy import in cupy.py with:
NumpyMetadata.instance() for dtypes
Numpy.instance().frombuffer() for buffer handling

Aligned with existing nplike patterns.

@aashirvad08

Copy link
Copy Markdown
Contributor Author

any updates ?

@ikrommyd ikrommyd changed the title feat: implement byteswap for all nplikes feat: implement byteswap as an nplike function Mar 31, 2026
@ikrommyd

ikrommyd commented Apr 7, 2026 •

Copy link
Copy Markdown
Member

I have pushed a few fixes and done some refactoring and I think the source code is now what we want. However, the tests quality is not there yet. There are many things that are not being tested and many extra redundant testing. I will edit them. Probably today.

@aashirvad08

Copy link
Copy Markdown
Contributor Author

Sounds good.
Let me know if I can help with anything on the tests

@ikrommyd
ikrommyd requested a review from pfackeldey April 8, 2026 13:19
@ikrommyd

ikrommyd commented Apr 8, 2026

Copy link
Copy Markdown
Member

I rewrote the tests and we now have 100% coverage of all the relevant parts of the source code changes and the tests actually test all dtypes awkward supports and multiple shapes and shape edge cases.

Comment thread src/awkward/_nplikes/cupy.py Resolved

@ikrommyd ikrommyd left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good from my side now.

@pfackeldey pfackeldey left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Nicely covers all our backends 👍

@ikrommyd
ikrommyd merged commit a245cce into scikit-hep:main Apr 9, 2026
60 of 63 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make byteswap an nplike function

4 participants