Add a trait to tie together compile-time and runtime number of dimensions

[akern40]

This is the next PR to address #1506. In the previous PR (#1568) we established a trait for capturing the "dimensionality" or "rank" of an array at the type level. This PR is focused on providing a bridge from type-level dimensionality to runtime dimensionality, which we do through the new Ranked trait.

First, a note on language: we now have three words / phrases to refer to the same thing: number of dimensions, dimensionality, and rank. That's ok, they're all accurate, but I'm worried it will be confusing as time goes on. Similarly, in #1568, we decided on using Rank as the name of the associated type that tells you the compile-time number of dimensions. However, the function that has traditionally provided the number of dimensions is ndim. So we have a slight vocabulary problem. I would really love some input and feedback about what language we should be using; especially from people for whom English is not their first / primary language.

The Ranked trait is pretty simple: require an associated type (Rank) that carries compile-time dimensionality, and a function fn rank(&self) -> usize that tells the user runtime dimensionality. The src/layout/ranked.rs file contains the definition, implementations, and blanket implementations. There are likely some/many types in the library or outside of it that I forgot to implement Ranked for, but I'm sure we'll find them as time goes on.

I've also removed the Rank associated type on Dimension and made Ranked a supertrait of Dimension. I think this is the best way to do this, but it does mean that I've had to remove the "unstable" feature flag we had introduced. Since this code isn't merging to main yet, I think that's fine.

[nilgoyette]

I would really love some input and feedback about what language we should be using; especially from people for whom English is not their first / primary language.

Moi! I'm one of those :) As a long-time programmer, I like dimension and dimensionality. This being said, I do know what rank means and it's certainly a good word if we're going to work with matrices. The problem that I see it that the complete definition of rank (at least according to google AI) is

The rank of a matrix is the maximum number of linearly independent rows or columns it has, representing the dimension of the vector space spanned by its rows (row space) or columns (column space).

(Emphasis mine) If this definition is right (and I think it is), then I don't think rank is a good name. A mathematician using ndarray might think that rank() returns/calculates the actual mathematical rank. IIUC, a 3x3 matrix of zeros has a rank equal to 1, no?

[akern40]

Yes, rank does have that meaning! I have been considering swapping our use of Rank to be the name of the generic type currently called NDim, and making NDim the name of the associated type of the trait. I'd also change the trait name from Ranked to Dimensioned, and change the function name from rank to ndim. Thoughts?

[nilgoyette]

Yes, imo, it's a good idea.

[legendre6891]

Hi! I consider myself an applied mathematician (working in quantitative finance). I have a preference for using the word rank for denoting the number of axes of a multi-dimensional array; while not universal, this does seem common in numpy, R, MATLAB, and Julia communities.

Some other scattered thoughts:

• while the rank of a matrix has a well-defined meaning in mathematics, in the context of a multi-dimensional array library I think there is less chance of confusion. It might be better to call this concept/function matrix_rank() (as numpy does), as it applies only to 2-dimensional arrays
• dimensionality might be hard to remember. For a given array whose dimensions are (c1, c2, ..., cp), there are multiple notions that reasonably map to the colloquial notion of dimensionality:
  1. p (the number of dimensions)
  2. c1 * ... * cp (the dimension in Euclidean space in which the array may be embedded);
  3. c1 + ... + cp (if each coordinate had names, this would be total number of names captured by the array)
     whereas rank seems to have consensus to mean 32 bit vs. 64 bit indexing #1. Pr

As for the function name to return the "rank", my preference is ndim(). It agrees with numpy/R (ndim) and Julia (ndims).

Anyhow, just my two-cents. Cheers, and thanks for maintaining this library.