Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs tutorial, "How to work with Rotations" #355

Closed
wants to merge 12 commits into from

Conversation

dehann
Copy link
Contributor

@dehann dehann commented May 4, 2021

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 kellertuer added the preview docs Add this label if you want to see a PR-preview of the documentation label May 4, 2021
@kellertuer
Copy link
Member

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
Copy link

codecov bot commented May 4, 2021

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.

docs/src/examples/dimetourrotations.md Outdated Show resolved Hide resolved
docs/src/examples/dimetourrotations.md Outdated Show resolved Hide resolved
@dehann
Copy link
Contributor Author

dehann commented May 4, 2021

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
Copy link
Member

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
Copy link
Contributor

Affie commented May 13, 2021

@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
Copy link
Contributor Author

dehann commented May 13, 2021

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

@dehann
Copy link
Contributor Author

dehann commented May 19, 2021

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

xref: JuliaNLSolvers/Optim.jl#920 (comment)

@dehann dehann changed the title Docs tutorial, "Dime Tour, Rotations" Docs tutorial, "How to work with Rotations" May 22, 2021
@dehann
Copy link
Contributor Author

dehann commented May 22, 2021

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

Screenshot from 2021-05-22 06-33-50

@kellertuer
Copy link
Member

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

@dehann
Copy link
Contributor Author

dehann commented May 22, 2021

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
Copy link
Member

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

@dehann dehann mentioned this pull request May 22, 2021
docs/src/examples/dimetourrotations.md Outdated Show resolved Hide resolved

With the basics in hand on how to move between the coordinate, algebra, and group representations, let's briefly look at composition and application of points on the manifold. For example, a `Rotation(n)` manifold is the mathematical representation, but the points have an application purpose in retaining information regarding a specific rotation.

Points from a Lie group may have an associated action (i.e. a rotation) which we [`apply`](@ref). Consider rotating through `θ = π/6` three vectors `V` from their native domain `Euclidean(2)`, from the reference point `a` to a new point `b`. Engineering disciplines sometimes refer to the action of a manifold point `a` or `b` as reference frames. More generally, by taking the tangent space at point `p`, we are defining a local coordinate frame with basis `B`, and should not be confused with "reference frame" `a` or `b`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

bθa = π/6
bXa = get_vector(base_manifold(G), xR0, bθa, B)

bRa = exp(G, R0, bXa)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is R0 defined? Did you mean xR0?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 🙂 .

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

docs/src/examples/dimetourrotations.md Outdated Show resolved Hide resolved
@kellertuer
Copy link
Member

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

@dehann
Copy link
Contributor Author

dehann commented May 24, 2021

No problem, I changed it to howtorotations.md

@dehann
Copy link
Contributor Author

dehann commented Oct 8, 2021

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
Copy link
Member

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
Copy link
Contributor Author

dehann commented Apr 5, 2022

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
Copy link
Member

kellertuer commented Apr 5, 2022

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
Copy link
Member

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
Copy link
Member

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
Copy link
Member

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
Copy link
Member

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 mateuszbaran mentioned this pull request Aug 15, 2024
8 tasks
@mateuszbaran
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
preview docs Add this label if you want to see a PR-preview of the documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants