Skip to content

Add clarification for single to multi index conversion #673

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.

Sign up for GitHub

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

Closed
wants to merge 1 commit into from
Closed

Add clarification for single to multi index conversion #673

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion spec/draft/API_specification/indexing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,7 @@ The behavior outside of these bounds is unspecified.
.. note::
*Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to clip (consistent with Python* ``list`` *slicing semantics), raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations.*


Multi-axis Indexing
-------------------

Expand All @@ -131,7 +132,9 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult
.. note::
In Python, ``A[(exp1, exp2, ..., expN)]`` is equivalent to ``A[exp1, exp2, ..., expN]``; the latter is syntactic sugar for the former.

Accordingly, if ``A`` has rank ``1``, then ``A[(2:10,)]`` must be equivalent to ``A[2:10]``. If ``A`` has rank ``2``, then ``A[(2:10, :)]`` must be equivalent to ``A[2:10, :]``. And so on and so forth.
Accordingly, if ``A`` has rank ``1``, then ``A[(2:10,)]`` must be equivalent to ``A[2:10]``. If ``A`` has rank ``2``, then ``A[(2:10, :)]`` must be equivalent to ``A[2:10, :]``. And so on and so forth.
Copy link
Member

Choose a reason for hiding this comment

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

Isn't this already what the first sentence here says?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Do you mean this sentence?

In Python, A[(exp1, exp2, ..., expN)] is equivalent to A[exp1, exp2, ..., expN]; the latter is syntactic sugar for the former.

If so, I read it as saying something slightly different, more about the python AST parser than any semantics specifics to array indexing? i.e. I read it it as saying that x[y,] is the same as x[(y,)] not that x[y] is not the same as x[y,].

If you meant this one:

Accordingly, if A has rank 1, then A[(2:10,)] must be equivalent to A[2:10]. If A has rank 2, then A[(2:10, :)] must be equivalent to A[2:10, :]. And so on and so forth.

It also reads slightly differently to me, in that it only specifies full indexing of an array, i.e. it doesn't say that A[(2:10,)] is equivalent to A[2:10] for any array, only those with rank 1.

Copy link
Member

Choose a reason for hiding this comment

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

I was referring to that second sentence. Actually it is supposed to say only for rank 1, because we decided to only specify indexing when every axis is explicitly indexed (or an ellipsis is used). So a[2:10] is actually not specified unless a is 1-D (and neither is a[2:10,]). If a is 3-D, for instance, you have to do a[2:10, :, :] or a[2:10, ...]. (FWIW, I personally was not a fan of this decision, but that's what the consortium decided).

I think that this is spelled out in the document but maybe it could be clearer.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Oh wow, I wasn't aware of that.

I'll close this PR then.

Doing a closer reading of the indexing spec I think this bullet point covers your point:

Except in the case of providing a single ellipsis (e.g., A[2:10, ...] or A[1:, ..., 2:5]), the number of provided single-axis indexing expressions (excluding None) should equal N. For example, if A has rank 2, a single-axis indexing expression should be explicitly provided for both axes (e.g., A[2:10, :]). An IndexError exception should be raised if the number of provided single-axis indexing expressions (excluding None) is less than N.


Any single-axis index (e.g. ``A[x]``) is equivalent to multi-indexing with the same term as the only axis (e.g. ``A[x,]``).

- Providing a single nonnegative integer ``i`` as a single-axis index must index the same elements as the slice ``i:i+1``.

Expand Down