WIP: What are manifolds?

[mateuszbaran]

A new general descriptions of what manifolds are.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.97%. Comparing base (f43ca1a) to head (8995e7e).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #219   +/-   ##
=======================================
  Coverage   99.97%   99.97%           
=======================================
  Files          31       31           
  Lines        3535     3535           
=======================================
  Hits         3534     3534           
  Misses          1        1           

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

[kellertuer]

I carefully read this. It I a very good idea to introduce this.

1. I would like to rephrase the beginning a bit, since currently it starts what we can not do. However, for now all we need and do implement is the definition used in the next section. So there is no need for the negativity.
2. one could mention a bit, that some links point even to Manifolds.jl since that is not yet part of the interface – all links with icons upfront like at_point
3. Also in topological part we again have a bit of a negative phrasing, but my larger problem is that the points 1-4 are nice to know but might yield the impression we would cover those already. We do not.
4. The same as 3) for the Finsler manifolds. Currently these are not supported neither here in ManifoldsBase nor in Manifolds.jl – so that might be misleading in a tutorial?
5. Finally, since the tutorial does not involve any code (or is that planned) it could also directly be written in markdown within the docs as a normal docs page – would that be reasonable?

I can try the next few days to write an introduction, that is positive, maybe not covering everything, but covering everything that is needed to get started and generalise or specialise it later when necessary. For a starl the topological charts are enough and there is no need to know that other definitions need variants of this.

[kellertuer]

I proposed a second introduction, see the (now directly written) file https://github.com/JuliaManifolds/ManifoldsBase.jl/blob/mbaran/about-manifolds/docs/src/tutorials/what-are-manifolds-tutorial2.md

I also left out sentences like

When reading referenced material remember that advanced mathematical texts are primarily written to help people prove theorems. Most of that knowledge is not required for working with applications.

Because first, that is an opinion. Also one that I disagree with, those books are primality written to summarise and transport knowledge. Based on what one is doing, those are very much required also in applications.
but second, and even more important, the opinion Is not so necessary within a tutorial. If that is your opinion, that is of course fine, but a tutorial should not convey opinions.

edit: A rendered version of that start is https://juliamanifolds.github.io/ManifoldsBase.jl/previews/PR219/tutorials/what-are-manifolds-tutorial2/index.html

If the tone of the intro is fine, I would check the topological part a bit that it follows also that (I think it mostly does) and move ideas “beyond” (that are not yet available in our ecosystem) to a small “Beyond” section? Based on that one could to the same with the following, where I would maybe also link a few more things.

[mateuszbaran]

My idea was actually less of "let's make a tutorial" and more of "let's express my opinion on the direction in which I'd see JuliaManifolds evolve". So that's why I wrote it like that. Maybe it should be published in a different format if you don't think it's a good text for the tutorial section.

Basically all books on manifolds are written by people who prove theorems, so that's what they focus on. That's perfectly fine but when someone has some nontrivial structure of their data, they may quickly find that it doesn't exactly fit one of the more popularized definitions. The standard conclusion is "then manifolds are not for me" and they just use Euclidean tools after some arbitrary transformation. I want to promote the idea that manifolds are more than the standard definitions. But, when someone tries to read about those less popular types of manifolds, they quickly end up with math that takes years to properly understand. This is the part where my opinion has a positive meaning: application people don't have to spent years learning math to use Finsler manifolds, adapt methods to handle corners or deal with stratification. This is often much easier than standard books make it seem. Of course, they won't be able to write a math paper about it, but many people don't need to do that. They want a method that solves their problem. We may not have one available right now but it's much easier to develop one that it might appear.

[kellertuer]

The standard conclusion is "then manifolds are not for me" and they just use Euclidean tools after some arbitrary transformation.

I do agree that that is a danger of a book like the one by Lee, though I hope Absil et al. (with a bit of imprecision even) went a bit more towards applications and Nicolas even more.

My point is not that a tutorial should follow a textbook. My only point on the opinion side is – if we want to avoid that non-math-people (engineers, biologist, who ever) should read this, which I think the level of detail addresses really nicely, then we should also avoid to “do the opposite” of math people (that might say: you have to read the book first) and say “do not read them they are boring”.

So sure, giving an intuitive introduction to Finsler manifolds is totally fine with me – and might be nice for some. But for me the tone is also important.

Concerning whether that should be a tutorial - well, the first parts on tangent space, connections,... definetly, I really like that and would love to help getting that a bit more “in shape” in the sense I just mentioned.

For Finsler, manifolds with boundary,... I am not so sure where to put that, but a tutorial might convey “We can do that already” because a tutorial follows the “this is how you do things” (in JuliaManifolds) road.

So maybe three follow up questions:

1. What do you think about my new introduction? I already tried to adapt the tone – and even for the next section kept all of your parts. If that is fine I could rework the part “what is a manifold you can currently use with us” in that tutorial

2. a technical question on 1) – with or without code? Without code it can stay an .md file which is a bit nicer to write, with code it should be in quarto. I am fine with both, but we should decide at some point

3. For Finsler and such – I did not understand your intentions when I read the text but I understand now from your answer. My initial idea was to always have a small section “actual beyond JuliaManifolds there exists” section, but I dee your intentions were different.
   What do you think about a separate page – not a tutorial, but here in the docs – that solely focusses on Finsler, boundary,... maybe in a “Future Perspectives for JuliaManifolds” sense that maybe has the tone of “hey, if you are interested in any of there we would love to collaborate to bring these into our ecosystem, so they can benefit from what is already there”.
   It could either pick up points from the tutorial and say “actually this we would love to extend to ...” or come from existing manifolds or so. It would be more a “Meta-Issie / Blog post” style and contain all the “Beyond” parts.

What do you think?

[mateuszbaran]

I think your new text is fine. I would propose converting my old text to a post in Manifolds.jl, and then you could take parts of it to continue working on your text here. This seems like the best way forward.

By the way, I definitely don't suggest to anyone that they shouldn't read math books. On the contrary -- they are often interesting and useful. I just don't want people to think they need to spend a lot of time to get anything of value from JuliaManifolds. Absil's book is nice but for example for affine connections I've seen only one chapter in one book that is written with applications in mind, and more or less zero about Finsler, manifolds with corners or stratification.

[mateuszbaran]

I've posted it there: JuliaManifolds/Manifolds.jl#778 .

[kellertuer]

Hm. So we do not add that as a perspektice-or-so page to the docs? What do we do with the rest here? It would be duplicate to continue to work on this now that it is posted over there? Just asking to not waste time on things we do not do any longer then.

Concerning

I definitely don't suggest to anyone that they shouldn't read math books

I am quite sure you did not mean to but the two sentences

When reading referenced material remember that advanced mathematical texts are primarily written to help people prove theorems. Most of that knowledge is not required for working with applications.

Indicate for me the exact opposite. One can read these as “do not read those books unless you want to do proofs”. I do not agree with that. Nor with the second sentence. But I think I mentioned most of my arguments already. You might not have meant to suggest that, but the phrasing you chose does suggest to not read anything from the books when one “only wants to apply it”.

[mateuszbaran]

A discussed on Slack, this won't be worked on for now. The text is available as a discussion.