Documentation suggestions?

[cleong110]

I recently learned about einops, and decided to try and learn more. After reading all the way through I was still confused: "what do the letters mean? What is 'b'? What is 'h'?"

I iterally ended up Googling "einsum what do the letters mean", and found this thread, where someone explained that the letters can be anything. You don't have to use "b" or "h", you can use whichever labels you wish.

But if this is explained in the documentation, I could not find it. It just shows a number of examples, but I didn't see an example where the same thing is done but using different labels. An explanation or example up front would probably help, maybe something like this?

rearrange(ims[0], "foo bar baz -> bar foo baz")

[cleong110]

Other possibly very noob questions I ran into that I didn't find in the documentation include

• is there a list of valid symbols for rearrange anywhere? I see -> and (), are there others?
• what is invalid? Can I use an asterisk (*) within rearrange?
• I see you can do things like "mean" and "max", is there a list of those somewhere? Edit: found a list in in the API, though that doesn't seem to include every item from _reductions?

[arogozhnikov]

Hi @cleong110

"b c h w" vs "b h w c" was important in DL 5 years ago, anyone knew that. Generation gap, I guess.

Some comments can improve that.

rearrange(ims[0], "foo bar baz -> bar foo baz")

ehm, no, I won't teach users to use meaningless axes

is there a list of valid symbols for rearrange anywhere? I see -> and (), are there others?

only ellipsis.

what is invalid? Can I use an asterisk (*) within rearrange?

If you used asterisk, what would this mean? Don't ask 'what I can put in there'; ask 'can I do X'? Documentation covers a lot of cases, if you can understand 50% of them - that's already p95 of users.

... though that doesn't seem to include every item from _reductions?

Good catch, docstring needs to be updated

[cleong110]

ehm, no, I won't teach users to use meaningless axes

Right, I suppose not... perhaps a better way might be to give two different meaningful labels, huh. Like:

# verbose
rearrange(ims[0], "batch colors height width -> batch height width colors"

#concise 
rearrange(ims[0], "b c h w -> b h w c"

This would get across to new users that they can assign the axes any name that is meaningful to them.