A first Lie group!

[kellertuer]

This PR aims to test our interface ideas with a first concrete Group operation and a Lie group

• [x] Introduce AdditionGroupOperation
• [x] Introduce TranslationGroup
• transfer default for the addition group (and test snippets)
  • [x] exp
  • [x] log
  • [x] diff_conjugate
  • [x] div_left_compose, diff_right_compose
  • [x] diff_inv
  • [x] lie_bracket
  • [x] document them thoroughly to help people getting started what the terminology is
• transfer in general
  • [x] is_point and for identity check_vector (a bit nicer than before)
  • [x] is_vector
• start a test suite
  • add tests for the translation group
  • add generic tests with a dummy Lie group and a dummy Lie algebra to test a few fallbacks.
  • [x] tests for also the default given ones like inv_left_compose, adjoint, inv_right_compose
• [x] reorganise the interface to have a bit of a shorter page – maybe a structure with sub pages for
  • general interface functions
  • group operations interface
  • group actions interface
• [x] check for ambiguities once the Identity gets involved
• [x] setup codecov
• [x] setup vale (though not yet run on CI)
• [x] setup/prepare zenodo metadata.

[codecov[bot]]

Welcome to Codecov :tada:

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered :open_umbrella:

[kellertuer]

@mateuszbaran I struggle a bit with the next const-type-thing. This time LieAlgebra as a special type of Fiber.

using LieGroups
G = TranslationGroup(3)
LieAlgebra(G)

yields

TypeError: in Fiber, in G, expected G<:(LieGroup{ℝ, O, M} where {O<:AbstractGroupOperation, M<:ManifoldsBase.AbstractManifold{ℝ}}), got a value of type TranslationGroup{ℝ, ManifoldsBase.TypeParameter{Tuple{3}}}
Stacktrace:
 [1] (ManifoldsBase.Fiber{𝔽, ManifoldsBase.TangentSpaceType, G, I} where {𝔽, G<:(LieGroup{𝔽, O, M} where {O<:AbstractGroupOperation, M<:ManifoldsBase.AbstractManifold{𝔽}}), I<:Identity})(G::TranslationGroup{ℝ, ManifoldsBase.TypeParameter{Tuple{3}}})
   @ LieGroups ~/Repositories/Julia/LieGroups.jl/src/interface.jl:91
 [2] top-level scope
   @ REPL[4]:1

I am super buzzed by “expected Lie Group got TranslationGroup”, because TranslationGroup is a LieGroup (const)

besides that this PR only misses to check which other functions already to take over (from here). and maybe work a bit on the test suite further.

Besides fighting parameters in const (constantly it seems) – the interface seems usable I think, so we could start transferring more LieGroups afterwards.

[mateuszbaran]

It appears you just forgot one typeof :slightly_smiling_face:

[kellertuer]

Oh noes! I was too busy checking the third parameter over and over again, that I did not spot that one – and probably got confused that the variable has a capital letter. Thanks!

[kellertuer]

I am also fond of getting the test suite better from the start here – slowly doing that along with the first group. If that works well I will adopt the same scheme over in Manifolds.jl

[mateuszbaran]

You're welcome.

I'm still curious how this testing approach works out but I guess I'll wait until it's a bit more complete.

[kellertuer]

If you have comments / questions feel free to post them, the general idea is:

With a bit of given data of (up to) 3 points, 3 vectors

• provide modular test functions for every single function of the interface – potentially with interactions to others like in exp/log
• provide properties that list which functions or more general which things can be tested
• provide expectations for whenever we have to be able to know a result

For now both properties and expectations are set manually, but I started already with an idea in the Manifolds.jl branch to have an “auto-discover” mode for them.

This should make testing concrete other groups later a bit faster. I also tried to encapsulate all this in a small test package. so that this can easily be loaded and avoid the need for the “if not yet loaded include now” approach we have in a few packages for generic tools like a DummyLieGroup for example.

The interface/fallbacks in general have to be done as a separate test anyways.

[mateuszbaran]

• provide expectations for whenever we have to be able to know a result

Could you add specific expectations to tested functions in the TranslationGroup test suite? For example that exp performs addition and log does subtraction?

For now both properties and expectations are set manually, but I started already with an idea in the Manifolds.jl branch to have an “auto-discover” mode for them.

I think auto-discovery shouldn't be that important because when you develop some code, you know what should work. So it's not much work to add it manually. Maybe a little bit of semi-automatic discovery, such as "if you declared X and Y as implemented, Z should also work", would be useful though.

[kellertuer]

• provide expectations for whenever we have to be able to know a result

Could you add specific expectations to tested functions in the TranslationGroup test suite? For example that exp performs addition and log does subtraction?

Uff. No clue, that is maybe a bit too high-level. For now exp and log are mainly checked to produce valid points and vectors, respectively and if both are available, that they are inverses of each others for the given points.

The expectations I have in mind is mainly numbers and strings – main example for now the string repr(G) returns. You idea sounds much more like a whole AI to implement to interprete results. That is not what expectation means – much simpler, just in the sense of expected values (for certain things).

For now both properties and expectations are set manually, but I started already with an idea in the Manifolds.jl branch to have an “auto-discover” mode for them.

I think auto-discovery shouldn't be that important because when you develop some code, you know what should work. So it's not much work to add it manually. Maybe a little bit of semi-automatic discovery, such as "if you declared X and Y as implemented, Z should also work", would be useful though.

Sure auto.discover is something not really urgent and also a bit dangerous, since you would irregularly run it and it would save both properties and expectations in a .jld2 file. The danger is that it might also save erroneous expectatios then (in the sense of wrong values/strings). I would also not consider this too high priority, it was just something the manifolds-test suite branch experimented with a bit. For now we should maybe not follow this here.

[mateuszbaran]

Uff. No clue, that is maybe a bit too high-level. For now exp and log are mainly checked to produce valid points and vectors, respectively and if both are available, that they are inverses of each others for the given points.

The expectations I have in mind is mainly numbers and strings – main example for now the string repr(G) returns. You idea sounds much more like a whole AI to implement to interprete results. That is not what expectation means – much simpler, just in the sense of expected values (for certain things).

That's fine but then this test suite is not sufficiently exhaustive to replace other tests. And I definitely don't mean anything related to AI, only letting the user provide reference results for specific operations such as exp and log. Maybe it's obvious but I wouldn't like to have an expectation that when test_LieGroup(G, properties, expectations) passes, the group is definitely correctly implemented. Similarly test_manifold only checks some general properties and is not exhaustive.

[kellertuer]

The suite is meant to provide a framework for common, usual tests. Sure that might not be exhaustive. I would even be open, that none of our tests are probably exhaustive (in favour of a finite time).

But the point that the suite is to provide tests for most common properties to check is probably a good thing to add to their docs. Though I think we might be able to cover as much as we usually test in Manifolds.jl for most manifolds (and not only with the test_manifold function, but a bit beyond).

[kellertuer]

I think I at least see an end to this with only a few small test suite functions and a few lines of code implementation left.

[olivierverdier]

Speaking about testing, I wrote a package containing sensible tests for Lie groups. You can see an example of usage here: https://github.com/olivierverdier/ManifoldGroupTesting.jl/blob/main/test/test_group.jl There are also tests for group actions.

[kellertuer]

Nice! Here for now I just wrote a few functions like that in an internal sub-package, though here the blocks in each functions are actually already test sets, so they usually test a few more things than just one thing – for now they are a bit more focussed on low-level correctness – that the code works, yours already seem to also check the next level, that more formulae are verified.

[kellertuer]

In theory everything is documented by now.

In practice I fought “duplicate docs” errors for the last hour, that I have never seen before coming from one and the same autodocs block. Well. Maybe this magically disappears tomorrow, or someone else sees how to fix this.

Besides that this is finished.

[kellertuer]

Hmpf. Who ever came up with this clever idea in @autodocs

Note that page matching is done using the end of the provided strings and so a.jl will be matched by any source file that ends in a.jl, i.e. src/a.jl or src/foo/a.jl.

never wrote two interfaces in one project.

[Affie]

Hi, I didn't subscribe to LieGroups.jl notifications after it was transferred and now I'm far behind so sorry I can't help out here. It's very nice to see that you made a lot of progress!

[kellertuer]

No worries, hat was quite a technical hustle we went through, but (yay!) we got the name that way. Feel free to comment anything you notice or open issues about groups you would like to see. We can also already have your group in mind you mentioned, just open an issue for that as well.

[kellertuer]

I started looking a bit into ambiguities, and in general it looks nice, just that for example

+(Manifolds.Identity{O}, LieGroups.Identity{O}) 

is a bit of a temporary and annoying one. I will put that one on Ignore since it will resolve automatically once we make the breaking change in Manifolds.

[kellertuer]

So we now further

• [x] run Aqua.jl tests
• [x] the test suite can now run less tests (skip mutating variants) by setting :Mutating => false in the properties, either to be a bit faster or to work on a manifold with non-mutating points/vectors.