Mistake in the documentation of numpy.linalg.svd

[aricci10]

I believe there is a minor mistake in the numpy.linalg.svd documentation, since "Hermitian" should be in the parameters, not in the outputs.

https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.svd.html

[WarrenWeckesser]

What is the mistake that you see? That link now redirects to https://numpy.org/doc/1.18/reference/generated/numpy.linalg.svd.html, and the mistake is not obvious to me.

[eric-wieser]

The bug is in the 1.17 docs:

https://numpy.org/doc/1.17/reference/generated/numpy.linalg.svd.html

We might want to rebuild these from the last 1.17 release, I think right now they're a bit behind. It might make no difference here though.

[aricci10]

Okay, I guess I was just taking a look to an outdated version. I apologise for the trouble.

[rossbar]

No trouble @aricci10 , this is helpful - @eric-wieser is right, the docs on numpy.org/doc for 1.17 are still from 1.17.0. Updating them to the latest (1.17.5) would fix this problem.

@mattip, is there any reason the docs for pre-1.18 versions should not be updated to their latest release in numpy/doc? Unless anyone foresees problems, I am happy to build and upload the docs from the most recent patch numbers.

[aricci10]

Great! I'm glad to help.

By the way, I think it would be very useful if the function allows to return the values u,s,vh (where the input matrix H is factored as H = (u*s)@vh) without re-ordering the columns and rows such that s is returned in descending order. For instance, I'm doing 3D video using two frames with different coordinate systems and I need to estimate the best rotation from one system to another. According to http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.173.2196&rep=rep1&type=pdf, the rotation matrix can be computed using SVD where the rotation matrix R is R=vh.T@U.T. If the columns and rows are re-arranged, the answer won't be the proper rotation. Should I open a new issue with a feature request?

[charris]

@aricci10 I don't recall that reordering causes any problems with fitting rotations, the main thing is that the singular values are non-negative, not their ordering. One problem that you may run into with the SVD method is that it allows reflections, which may, or may not, be a good thing for your application. Note that scipy now has rotation fitting of pure rotations.

[mattip]

@mattip, is there any reason the docs for pre-1.18 versions should not be updated to their latest release in numpy/doc? Unless anyone foresees problems, I am happy to build and upload the docs from the most recent patch numbers.

I think this is relevant for 1.17, 1.16. I wouldn't spend time going further back, you may find problems building the documentation. Even for those, you may need to carefully check which version of sphinx and associated tools works, since the conf.py file changed.

[aricci10]

@aricci10 I don't recall that reordering causes any problems with fitting rotations, the main thing is that the singular values are non-negative, not their ordering. One problem that you may run into with the SVD method is that it allows reflections, which may, or may not, be a good thing for your application. Note that scipy now has rotation fitting of pure rotations.

@charris Thank you for your answer. I do believe the order matter. For instance, let's say I build a matrix H which I apply SVD to, such that H=u@diag(s)@vh. Then, my rotation matrix according to the paper will be R = u.T@vh.T, however, if the rows and columns of u and vh are reordered, the matrix R will have the correct values but in the wrong order representing a rotation on a different axis, I believe.

Could you please point me out which scipy module/function can I use to fit the rotation. Thanks a lot.

[charris]

I do believe the order matter.

The aim is to maximise tr(SC) where S is unitary and C is the cross-correlation of the vectors.

tr(SC) = tr(SUDV^T) = tr((V^TSU)D) => V^TSU = I => S = VU^T

When D contains no zeros. The first implication follows from a linear programming argument. Note that the order of the singular values plays no role.

[rossbar]

The conversation has jumped to multiple different topics here. The original issue with the docs has now been fixed - numpy.org/doc now has the most up-to-date versions of the 1.17 and 1.16 documentation.

I don't want to close this and cut off your conversation @aricci10 and @charris , but suggest either to change the title of the issue to better reflect the current discussion, or to close this issue and reopen a new one.

[aricci10]

I think we can close the issue now. @charris thanks for the explanation.