The word “dimension” is unfortunately used in several incompatible ways across programming languages in the context of arrays.

Consider an N-dimensional array `A[i1, i2, ..., iN]`

, where `i1`

runs from 1 to `L1`

, `i2`

runs from 1 to `L2`

, etc., so that the total number of array elements is `L1 * L2 * ... * LN`

. There are at least three inconsistent usages of the word “dimension” in this setup. In the first usage, a “dimension” simply indicates a specific index `ik`

, so that the dimensions of an array are always 1, 2, 3, …, `N`

. In the second usage, a `dimension`

refers to the number `Lk`

of values that the index `ik`

ranges over, so that the dimensions of an array are `L1`

, `L2`

, …, `Lk`

, and the total size of the array is the product of its dimensions. In the third usage, this array only has a single “dimension”, which is the number `N`

.

Julia follows the first usage - e.g. `permutedims`

performs a generalized matrix transpose rather than an array reshape, and the numbers `Lk`

are called the “dimension sizes”. Mathematica uses the second usage: `Dimensions[A]`

returns `{L1, L2, ..., LN}`

.

Given this conflicting terminology, it’s important to use the word “dimension” consistently, but unfortunately the documentation does not do so. It usually uses the word in the first sense, but, for example, it describes `size(A)`

as returning “a tuple containing the dimensions of `A`

”, inconsistently using the second sense of the word “dimension”. In the very next line it switches to using the word in the first sense. Similarly, it describes `reshape(A, dims...)`

as returning “an array containing the same data as `A`

, but with different dimensions”. This should say “dimension sizes”.

I know this might sound like extreme nitpicking, but I recently got extremely confused about why `permutedims`

was performing a transpose rather than a reshape, because of the documentation’s conflation of “dimension” and “dimension size”. (Also, strictly speaking, all the `dims...`

arguments in the documentation should more precisely be `sizes...`

, because under the documentation’s more common use of the word, the “dimensions” are always just 1 through `N`

.)