Skip to content

ndarray: import python standard library complex arrays#1323

Merged
wjakob merged 1 commit intowjakob:masterfrom
hpkfft:complex-array
Apr 10, 2026
Merged

ndarray: import python standard library complex arrays#1323
wjakob merged 1 commit intowjakob:masterfrom
hpkfft:complex-array

Conversation

@hpkfft
Copy link
Copy Markdown
Contributor

@hpkfft hpkfft commented Apr 1, 2026

Python 3.15 adds support for complex arrays to the standard library's array module. It uses a single capital letter as the format code. This PR adds support to nanobind's ndarray to import these arrays using the buffer protocol.

I tested this locally. The array support will be in Python 3.15 alpha 8. When testing nanobind on older releases, the new test is skipped.

PEP 3118 proposed additions to the struct string syntax which were not added. One of these was that Z followed by another character describes a complex number. For example, 'Zf' describes a complex single-precision number. For example, this PR allows nanobind to import complex single precision arrays via the buffer protocol that use either 'Zf' or 'F' as the format code. (Also, 'ZF' is accepted, but that's unintentional.)

Comment thread src/nb_ndarray.cpp
Comment on lines 185 to 186
case 64: format = "Zf"; break;
case 128: format = "Zd"; break;
Copy link
Copy Markdown
Contributor Author

@hpkfft hpkfft Apr 1, 2026

Choose a reason for hiding this comment

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

Note that we export arrays using the buffer protocol using the format proposed by PEP 3118 because that's what NumPy requires for import. NumPy cannot import buffers using 'F' or 'D'. (NumPy has half-precision reals, but not complex, so complex32 is currently irrelevant to them.)
Consequently, nanobind cannot export complex ndarrays as Python standard library arrays.
(Neither can NumPy. NumPy cannot import them either, but we can at least do that.)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@ngoldbaum, if you have time, I'd appreciate having your thoughts on a related Python question. Above, format is set to a string literal. I would guess doing this is common. The compiler/linker puts these constant strings in read-only memory. In the Python header file pybuffer.h, this is char *format;. Would it be better for Python to specify pointer-to-const, i.e., const char *format;?

@wjakob wjakob merged commit 3630e53 into wjakob:master Apr 10, 2026
28 checks passed
@wjakob
Copy link
Copy Markdown
Owner

wjakob commented Apr 10, 2026

Thanks!

@hpkfft hpkfft deleted the complex-array branch April 10, 2026 18:59
@hpkfft
Copy link
Copy Markdown
Contributor Author

hpkfft commented Apr 17, 2026

For those interested, the Python Steering Council may offer their opinion: python/steering-council#345

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.

2 participants