Docs tutorial, "How to work with Rotations"

[dehann]

Hi @mateuszbaran , @kellertuer,

Please find a new tutorial and comment as necessary, a new tutorial on SpecialOrthogonal(2). My idea here was to collect the most important functions and type definitions together that I have been having trouble finding usage examples for otherwise. The current docs are a strong function reference, but still pretty weak on helping new users get up to speed with best practices and what the data formats are. My hope is that you would be able to point out any serious errors I made here before I go too far (please!)...

For example, it took me forever to figure out what the relation between get_vector and hat was, similarly for vee (which literature sometimes has as "vectorize") and get_coordinates. Another thing that was very confusing to me was that get_vector and get_coordinates are not full opposites, as get_vector works with the algebra, while get_coordinates might go straight from the group skipping the algebra.

If this tutorial is near enough, then I will work on making a second "Dime Tour, SpecialEuclidean(2)" to showcase some of my very first questions that Mateusz kindly helped point out (https://github.com/JuliaRobotics/ApproxManifoldProducts.jl/issues/41#issuecomment-733636425). I still haven't been able to get to that work as yet, as the struggle with learning the conventions here took quite some time. Feedback on this tutorial will be good confirmation or correction on whether I'm heading in the right direction (long term).

Thanks again for the help!

Best, Dehann

[kellertuer]

Thanks for staring this. I will take a closer look the next days.

Two small remarks:

1. The title. Currently the Section is called “Examples” (in the long run we maybe call it tutorials) and the first tutorial is called “How to implement a manifold” – maybe we can call this one “How to work with Rotations”?

2. the vee/hat|get_coordinates/get_vector confusion: vee and hat are operator names (and here functions) quite close to Lie groups, the get_coordinate/get_vector are the general manifold versions. For people familiar with vee/hat we kept those names, too. And they are full opposites in the following sense. a) Let p be a point on the manifold and X be a tangent vector at p (for example on the sphere p=[1.0,0.0,0.0] and X=[0.0,0.5,0.5], recall that we represent points on the sphere as unit vectors and the tangent space at p is all vectors orthogonal to p). b) Then the disadvantage might be that the representation of X is not nice, i.e. it uses too much space or doing vector-calculations it not so easy (maybe for the fixed rank matrices, we did overload all vector operations, but maybe that is “not enough” for your application in mind and you really want vectors). But: Given a basis B you can look at the coefficients the tangent vector X has with respect to this basis: the so called coordinates (on the sphere the basis would be Y1=[0.0,1.0,0.0] and Y2=[0.0,0.0,1.0]). So you do c = get_coordinates(Sphere(2), p, X, B). c) Now you have a coordinate vector with respect to a basis B of the tangent space at p and want the vector back, then you do X2 = get_vector(M, p, c, B) (and you have X2==X). d) The coordinate vector c might also have the advantage of saving memory. For example SPD matrix tangent vectors take n^2 entries to save, since we store the full matrix, but the coordinate vectors only take n(n+1)/2.

I hope this clarifies the confusion with vectors and coordinates. One more caveat here is that for the Rotation matrices tangent vectors are always stored as elements from the Lie algebra, for sure.

[codecov[bot]]

Codecov Report

Merging #355 (2077014) into master (61c5a5d) will increase coverage by 0.26%. The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #355      +/-   ##
==========================================
+ Coverage   97.65%   97.92%   +0.26%     
==========================================
  Files          76       78       +2     
  Lines        5919     5917       -2     
==========================================
+ Hits         5780     5794      +14     
+ Misses        139      123      -16     

Impacted Files	Coverage Δ
src/manifolds/GeneralizedStiefel.jl	97.67% <0.00%> (-0.16%)	:arrow_down:
src/manifolds/Rotations.jl	95.90% <0.00%> (-0.09%)	:arrow_down:
src/manifolds/Circle.jl	98.60% <0.00%> (-0.06%)	:arrow_down:
src/manifolds/Stiefel.jl	99.19% <0.00%> (-0.02%)	:arrow_down:
src/ode.jl	100.00% <0.00%> (ø)
src/Manifolds.jl	100.00% <0.00%> (ø)
src/groups/group.jl	94.27% <0.00%> (ø)
src/manifolds/Torus.jl	100.00% <0.00%> (ø)
src/manifolds/Sphere.jl	100.00% <0.00%> (ø)
src/manifolds/Oblique.jl	100.00% <0.00%> (ø)
... and 37 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 61c5a5d...2077014. Read the comment docs.

[dehann]

Thanks for feedback, I will fix in the next couple of days as though regular review. I think it is worth having a really strong tutorial like this, so I'm good to go through a few rounds until you are happy. I also want to make another tutorial with SE(2), distance, etc. I'll do the work, if you could just guide this way or that way please (to ensure the rigor and template patterns are not lost).

Looking quickly, I will likely agree with all your comments and change/add accordingly. For the sake of user utility, there are one or two ideas I'd like to keep in some manner to help bridge the terminologies between familiar vector calculus and general differential forms / manifolds. E.g. let me try rephrase "reference frames" and see how you like it -- i.e. I follow that Lie groups are coordinate free and the definitions are all relative.

---

PS, I will also run JuliaFormatter

[mateuszbaran]

Thank you for working on this! :slightly_smiling_face: . It is generally hard for me to tell what kind of thing users may want to see in a tutorial so I really appreciate any help with that. I can definitely help here, so I'll keep reviewing your tutorials :slightly_smiling_face: . Also, feel free to ask me questions even if they seem very basic, such as the relation of vee, hat get_vector and get_coordinates (it's actually not a basic question).

E.g. let me try rephrase "reference frames" and see how you like it -- i.e. I follow that Lie groups are coordinate free and the definitions are all relative.

Sure, I'm not against referencing "reference frames" but I think it should be done more clearly. Reference frames exist in differential geometry, and actually our bases are ordered so they can act as such, so we need to be careful and indicate where we mean an ordinary vector calculus reference frame, and (here) what is meant by moving between two reference frames. I wouldn't interpret our apply as moving between two reference frames.

The other thing is that calling Lie groups "coordinate free" may be incorrectly understood. You can definitely have coordinates on Lie groups (through charts and atlases) and we'll have that soon (PR #325 ). Most Lie groups, though, are not vector spaces so you have to be careful which coordinates you mean. There may for example be coordinates of a point or tangent vector in an embedding, coordinates in a chart or coordinates of a tangent vector in a basis. The thing is that in such cases there is no canonical way to define coordinates.

[Affie]

@dehann, Thanks for writing this up. I come from not knowing any of the general manifold math and definitions and only a user of the rigid transform groups and algebras, so this tutorial is a good place to start. I still had to read up quite a bit to completely understand and have a few suggestions that could help:

• A simple visualization perhaps showing the example points and vectors on the group and algebra to help follow the code would have helped me a lot, at least for SO(2). With the equations written out in a similar fashion to the documentation.
• Should the various project and retract functions be included?
• vee/hat|get_coordinates/get_vector took me some time to understand

[dehann]

just a breadcrum to remember to add, (as Ronny said before), that hat assumes a default basis for the more general get_vector

[dehann]

UPDATE: Haven't forgotten, finishing this PR is high on my priority list!

xref: https://github.com/JuliaNLSolvers/Optim.jl/issues/920#issuecomment-841832307

[dehann]

I'm having a little trouble parsing how to fix this Formatter issue?

[kellertuer]

Each entry in the array has to have a comma in the end, you are missing that.

[dehann]

Thanks!

Also note, I'm busy writing up another tutorial for SpecialEuclidean(2) to follow this one. Will open a PR soon (today if I can get far enough).

[kellertuer]

Oh, don‘t worry if it takes a while, we are happy about any contribution. I will check this PR the next days somewhen. And I look forward to also seeing the next PR :)

[kellertuer]

Another small remark: could you also rename the markdown file, maybe to rotations.md or groups.md?

[dehann]

No problem, I changed it to howtorotations.md

[dehann]

Hi, just an update (sorry for the delay on this). Over at JuliaRobotics, we are finally finishing the major upgrade to Manifolds.jl. I have a much better idea of how to describe these tutorials and aim to update this and #366 as soon as possible. The tutorials as they are currently written in the PRs does not do enough to show the connections between groups, identity elements, tangent vectors, and manifold points. Although the delay has not been great, I think the eventual product will be better. Best, Dehann

[kellertuer]

Oh never mind the delay! Great to hear that you are transitioning/upgrading! :) For the tutorial, as said, never mind the delay, if we have a nice tutorial that helps explaining all these terms, I think that would be great so I am looking forward to an update here :)

[dehann]

Hi Folks, I added this Manifolds 101 page in the Caesar.jl Docs: https://juliarobotics.org/Caesar.jl/latest/concepts/using_manifolds/

Which points to this and sibling tutorial. Thought I'd link it here so long...

[kellertuer]

Nice!

I have two short comments after a short first look: In the intro you introduce Lie groups – at the end you link to JuliaManifolds/Manifolds.jl, but you could actually link to the documentation about GroupManifolds? https://juliamanifolds.github.io/Manifolds.jl/latest/manifolds/group.html

Second, more e technical remark: We redesigned ManifoldsBase to have a neat trait system, so AbstractGroupManifold will vanish in the next (breaking) release of Manifolds.jl (based on the already released ManifoldsBase.jl 0.13.0 with its own documentation now) and there will just be a IsGroupManifold trait.

Oh I just saw two further things down the road:

• You write $T_M(p)$ for the tangent space, we actually write $T_p\mathcal M$ (manifolds are calligraphic). This is just a remark, if you have a different notation that is fine of course, if you just use this notation in this one place, maybe it might be helpful to the reader to use only one notation.
• you write $vee$. and $Euclidean$ and such in Math mode. To me that reads as variables multiplied (so it would acutally be $e^2v$), since they are in italics, the function would be $\mathrm{vee}$ (but that's also just me, a math and notation nerd).

[mateuszbaran]

Cool! I'll read it and make notes if something could be improved :+1: .

By the way, we are currently working on automatic differentiation support for Manifolds.jl, so soon you will be able to quite easily compute gradients of functions involving distance, exp, log, etc. -- basically I expect section III of micro Lie theory ( https://arxiv.org/pdf/1812.01537.pdf ) will be automatic via ForwardDiff.jl or Zygote.jl.

[kellertuer]

Hej, long time no hear – since I am starting with Pluto based tutorials (see #534) so I could also adapt the tutorial from here. I am just not sure how much is missing / how far this is?

[kellertuer]

Is has become silent a bit on these two PR – are there still plans to finish these or should we close them for now and you start anew once there is a need?

[kellertuer]

This got quite silent and is a bit outdated by now, is it ok if we close this for now and restart when you find time again, @dehan? We could restart this also directly as a Quarto notebook by then.