[DOC] Confusing description of composition in layout_algebra.md

[skailasa]

Report incorrect documentation

Location of incorrect documentation
Provide links and line numbers if applicable.

cutlass/media/docs/cpp/cute/02_layout_algebra.md

Line 138 in 664c4f7

Put into words, `A o B = A o s:d`, for integral `s` and `d` means that we want (1) "remove" the first `d` elements from `A`, and then (2) "keep" the first `s` of those strided elements.

cutlass/media/docs/cpp/cute/02_layout_algebra.md

Line 152 in 664c4f7

2. Keeping the first `s` elements of the strided `A` layout can be computed by "modding out" the first `s` elements from the shape of `A` starting from the left. For example,

Describe the problems or issues found in the documentation
A clear and concise description of what you found to be incorrect.

The description for composition currently reads:

Put into words, `A o B = A o s:d`, for integral `s` and `d` means that we want (1) "remove" the first `d` elements from `A`, and then (2) "keep" the first `s` of those strided elements.

'Remove' is quite confusing here, especially with the quotation marks. Instead what the first step in composition suggests to be doing is selecting every d'th element of A starting from index 0. This aligns with the integer shape/stride example.

'Remove the first...' suggests truncation, which I don't think is what is happening here.

For the second associated issue, the 'modding out' of the required elements from the reduced view of A is also confusing

Keeping the first s elements of the strided A layout can be computed by “modding out” the first s elements from the shape of A starting from the left. For example,

This isn't a standard modulo operation - and though the meaning becomes clear with repeated readings, as it stands it doesn't really make sense as the notation doesn't reflect the actual modulo operation.

Steps taken to verify documentation is incorrect
List any steps you have taken:

Suggested fix for documentation
Detail proposed changes to fix the documentation if you have any.

Both of these docs should have some clarifying examples, or alternatively terminology/notation that reflects the nature of the operations.

I propose changing the description to clarify the meaning of 'remove' and 'keep' with reference to the 1D example. As the '/' operation is really about indexing views based on the 'd' stride, it would be helpful to clarify this if this is indeed what is going on.

---

Report needed documentation

Report needed documentation
A clear and concise description of what documentation you believe it is needed and why.

Describe the documentation you'd like
A clear and concise description of what you want to happen.

Steps taken to search for needed documentation
List any steps you have taken:

I will submit a PR with some clarifying changes.

[danielvegamyhre]

+1, I struggled through reading this documentation and after working through the examples the only conclusion I could reach was the documentation was inaccurate/misleading. Glad to hear I am not the only one who felt this way.

[danielvegamyhre]

One clarification though:

Remove' is quite confusing here, especially with the quotation marks. Instead what the first step in composition suggests to be doing is selecting every d'th element of A starting from index 0. This aligns with the integer shape/stride example.

I'm not sure if the "selects every d-th element" theory is quite right. It works for the simple examples like (6,2) / 3 = (2,2), but not for the larger examples below, such as (3,6,2,8) / 3 => (1,3,2,8). The shape (3,6,2,8) has 288 elements, so if we were removing every 3-rd element, I'd expect 288/3=96 elements, but the output shape (1,3,2,8) has 48 elements.

Let me know if I've misunderstood something. I am still trying to understand this part as well.

[skailasa]

Hi @danielvegamyhre , In this PR I've added to the documentation to make clear what I mean - including worked examples, and extra exposition: #2536. It's a little more complex with multiple modes, as the stride must be respected - I'd appreciate your comments on my update.

[skailasa]

I'm not sure if the "selects every d-th element" theory is quite right. It works for the simple examples like (6,2) / 3 = (2,2), but not for the larger examples below, such as (3,6,2,8) / 3 => (1,3,2,8). The shape (3,6,2,8) has 288 elements, so if we were removing every 3-rd element, I'd expect 288/3=96 elements, but the output shape (1,3,2,8) has 48 elements.

Let me know if I've misunderstood something. I am still trying to understand this part as well.

As far as I can tell this is a typo (3,6,2,8)/3 => (1,6,2,8) - look at the example below it (or above, I cant remember) they mistakenly swapped the 3 and 6 in the second mode of the answer

EDIT: this has been fixed now on main (

cutlass/media/docs/cpp/cute/02_layout_algebra.md

Line 145 in 6dd13d4

* `(3,6,2,8) / 3 => (1,6,2,8)`

)

[danielvegamyhre]

Hi @danielvegamyhre , In this PR I've added to the documentation to make clear what I mean - including worked examples, and extra exposition: #2526. It's a little more complex with multiple modes, as the stride must be respected - I'd appreciate your comments on my update.

Awesome, will take a look, thanks

As far as I can tell this is a typo (3,6,2,8)/3 => (1,6,2,8) - look at the example below it (or above, I cant remember) they mistakenly swapped the 3 and 6 in the second mode of the answer

Yeah I eventually figured out those examples had swapped results last night... very frustrating