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 (JuliaRobotics/ApproxManifoldProducts.jl#41 (comment)). 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]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.92%. Comparing base (61c5a5d) to head (2077014).
Report is 224 commits behind head on master.

Additional details and impacted files

@@            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     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[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! 🙂 . 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 🙂 . 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: JuliaNLSolvers/Optim.jl#920 (comment)

[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 :)

[mateuszbaran]

In the language of Manifolds.jl, what the code below does is rotating three points aV1, aV2 and aV3 from Euclidean(2) around the origin (point [0, 0]). These points can, of course, be identified with vectors (specifically, free vectors that have two coordinates. You can also keep separately their origins if they are meant to represent bound vectors. FYI, I'm not particularly attached to this bound/free vector terminology so feel free to use different names, I just added these links to make the point more clear.

Manifolds.jl also offers a more differential-geometric way for representing bound vectors. Vectors aV1, aV2 and aV3 that are bound at a can be thought of as belonging to the tangent space at a, that is TangentSpaceAtPoint(Euclidean(2), a). If you then wanted to rotate aV1, aV2 and aV3 through a rotation that sends a to b, you'd actually apply differential of the group action on them, more or less like that:

using Manifolds, StaticArrays

a = [2, 3]
aV1 = [1;0]
aV2 = [0;1]
aV3 = [10;10]
G = SpecialOrthogonal(2)
A_left = RotationAction(Euclidean(2), G)
bθa = π/6

p0 = @SMatrix [1.0 0; 0 1]
xR0 = identity(G, p0)

B = DefaultOrthogonalBasis()
bXa = get_vector(base_manifold(G), xR0, bθa, B)
bRa = exp(G, xR0, bXa)

b = apply(A_left, bRa, a)
bV1 = apply_diff(A_left, bRa, a, aV1)

Of course, this is an extremely convoluted way of rotating a vector but that's what actually can be extended to arbitrary manifolds and actions. I don't know how useful would that perspective be, so don't take it as a recommendation for this tutorial, just a point that might be worth keeping in mind.

[dehann]

offers a more differential-geometric way for representing bound vectors

I agree with that, let me try work this in. Will take a bit before I can though, busy week coming up this side.

I don't know how useful would that perspective be, so don't take it as a recommendation for this tutorial, just a point that might be worth keeping in mind.

I think it is important to get the language right, otherwise this will always be something that comes up with more people wanting to add contributions. Better to get it right now :-) thanks!

[mateuszbaran]

Where is R0 defined? Did you mean xR0?

[dehann]

Oops, yes I think so. I also want to review all these variables again, especially in the context of the next docs in PR #366 which needs a lot of variable name updates.

What I'd like to get right here is that the language from rigid transforms (aka coordinate transformations) through to the differential geometry (and also differential forms) is as consistent as possible. The most important thing to get right now, in my view, is how folks understand all the conventions with a clear path to the future. I think manifold and differential form/geometry language is the right way to go. Getting consistency across terminology and convention is hard, but should eventually be the stronger outcome.

[mateuszbaran]

Yes, naming is hard, especially when we need to accommodate for people with different backgrounds. We have a long (and growing) table with notation used in Manifolds.jl: https://juliamanifolds.github.io/Manifolds.jl/stable/misc/notation.html but it still assumes basic knowledge of differential geometry. An introduction aimed at people who work with rigid transforms would definitely be valuable.

On the topic of differential forms, so far I haven't found any use for them outside of integration on manifolds so they are not available in Manifolds.jl yet but it's definitely something I'd like to see here 🙂 .

[dehann]

Sounds good, my hope is that these two tutorial examples "how to rotations" and the next "how to rigid transforms" give enough of runway to learn the terminology and pick up the JuliaManifolds packages.

Aside, over at IncrementalInference.jl we are working to adopt the differential forms / manifolds language as default (at least internally), while most of our audience is familiar with vector calculus and linear algebra lingo. All the issue comments and documentation you guys have added the past couple of weeks have been a great help, thanks!

[kellertuer]

And the other way around: Thanks for the questions and hence improving the documentation.

[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 👍 .

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.

[mateuszbaran]

I've extracted and updated key parts of your tutorial and put them in #732 , so this can be closed now I think.