Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: ufunc API documentation needs clarification for order kwargs description #26226

Open
y-koj opened this issue Apr 8, 2024 · 0 comments
Open

Comments

@y-koj
Copy link

y-koj commented Apr 8, 2024

Issue with current documentation:

order kwargs documentation in the ufunc API reference is confusing, especially around "if the inputs are F-contiguous and not also not C-contiguous, C-contiguous otherwise".

Current order kwargs description is:

Specifies the calculation iteration order/memory layout of the output array. Defaults to 'K'. 'C' means the output should be C-contiguous, 'F' means F-contiguous, 'A' means F-contiguous if the inputs are F-contiguous and not also not C-contiguous, C-contiguous otherwise, and 'K' means to match the element ordering of the inputs as closely as possible.

Related links

https://github.com/numpy/numpy/blob/main/doc/source/reference/ufuncs.rst
https://numpy.org/doc/stable/reference/ufuncs.html
PR #3221

Idea or request for content:

The description will be clear by rewriting like below. It replaces "F-contiguous and not also not C-contiguous" with "F-contiguous and not C-contiguous" and divides the long sentence into short.

Specifies the calculation iteration order/memory layout of the output array. Defaults to 'K'. 'C' means the output should be C-contiguous. 'F' means F-contiguous. 'A' means F-contiguous if the inputs are F-contiguous and not C-contiguous, C-contiguous otherwise. 'K' means to match the element ordering of the inputs as closely as possible.

My concerns about this documentation change idea are:

  1. Whether "F-contiguous and not C-contiguous" reflects the actual API semantics or not
  2. A clearer rephrase of "if the inputs are F-contiguous and not C-contiguous, C-contiguous otherwise". The last "C-contiguous, C-contiguous otherwise" looks a bit weird.

The concern (1) is important because it relates to the API semantics. I need a comment from those who understand how ufunc-compliant functions are implemented or know where/how the ufunc order kwargs behavior is decided.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant