[Numpy-discussion] numpy.linalg.svd documentation

[Jason Grout]

The SVD documentation seems a bit misleading.  It says:

Factors the matrix a as u * np.diag(s) * v, where u and v are unitary 
and s is a 1-d array of a‘s singular values.

However, that only is true (i.e., you just have to do np.diag(s) to get 
S) in general if full_matrices is False, which is not the default. 
Otherwise, you have to something like in the first example in the docstring.

I'm not sure what the right fix is here.  Changing the default for 
full_matrices seems too drastic.  But then having u*np.diag(s)*v in the 
first line doesn't work if you have a rectangular matrix.  Perhaps the 
first line could be changed to:

Factors the matrix a as u * S * v, where u and v are unitary and S is a 
matrix with shape (a.shape[0], a.shape[1]) with np.diag(S)=s, where s is 
a 1-d array of a‘s singular values.

It sounds more confusing that way, but at least it's correct.

Maybe even better would be to add a shape option to np.diag, and then 
just make the first line of the svd docstring say 
u*np.diag(s,shape=(a.shape[0],a.shape[1]))*v


Jason