Add Spheres smoothly embedded in Euclidean Space to Manifold Catalog

[mjungmath]

See #30189.

The current catalog only provides spheres of dimension two. A comprehensive and faster version will be added here.

Features:

• spherical and stereographic coordinates
• orientation
• radius and barycenter can be stated
• link to minimal triangulation in homology module
• initialized embedding such that extrinsic quantities can be derived

Follow-Ups:

• make S^1, S^3 and S^7 parallelizable
• Hopf coordinates on S^3
• link to Lie group structure on S^1 and S^3

CC: @egourgoulhon @tscrim @tobiasdiez

Component: manifolds

Author: Michael Jung

Branch: caa9d5f

Reviewer: Eric Gourgoulhon, Travis Scrimshaw

Issue created by migration from https://trac.sagemath.org/ticket/30804

[mjungmath]

Description changed:

--- 
+++ 
@@ -1 +1 @@
-
+The current catalog only provides spheres of dimension two. A comprehensive and faster version will be added here.

[mjungmath]

comment:2

Establishing the stereographic projection in more than 3 dimensions is very demanding, even if you know the inverse. I know that you can speed these things up a little by turning off checking and choosing a suitable simplification. But do you know more workarounds?

I also suspect that the Jacobian takes a long time.

[tscrim]

comment:3

Even if it takes a long time, IMO it still is good to have a general version (with a warning to the user about the time).

[mjungmath]

comment:4

I agree. It is good to have these examples.

I thought about computing the desired quantities only on demand. Unfortunately it turned out difficult since most quantities are integral components and invoked by attributes not by methods. That's why I usually prefer methods rather than attributes.

[mjungmath]

Description changed:

--- 
+++ 
@@ -1 +1,3 @@
+See #30189.
+
 The current catalog only provides spheres of dimension two. A comprehensive and faster version will be added here.

[mjungmath]

Branch: u/gh-mjungmath/add_standard_sphere_to_manifold_catalog

[mjungmath]

comment:6

Please take a peek at this first approach. I'd appreciate if someone can take a closer look at the details, i.e. transition maps, choice of subsets etc.

I tried to cover spherical coordinates in arbitrary dimensions as well. But it turned out that the transition map to the stereographic coordinates is a bit complicated in the general setup. I welcome any kind of reference that might help. Furthermore, I wanted to ensure that the spherical coordinates have the correct orientation right from the start. That explains the reordering of coordinates compared to Wikipedia, and it makes the transition map to figure out even more tricky.

---

New commits:

bf4440a

Trac #30804: first n-sphere approach

[mjungmath]

Commit: bf4440a

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from bf4440a to 3ea0f27

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

3ea0f27

Trac #30804: transition spher <-> stereo added

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

245d563

Trac #30804: transition maps corrected

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 3ea0f27 to 245d563

[mjungmath]

comment:10

This should be the correct transition map, now. Checks all pass, too. I hope I didn't mess up the domains. Please check. Examples follow.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 245d563 to 6215d79

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

6215d79

Trac #30804: transition spher <-> stereo added

[egourgoulhon]

comment:12

Replying to @mjungmath:

I tried to cover spherical coordinates in arbitrary dimensions as well. But it turned out that the transition map to the stereographic coordinates is a bit complicated in the general setup. I welcome any kind of reference that might help.

A very good reference for the sphere in any dimension is Chapter 18 The sphere for its own sake in Marcel Berger: Geometry, vol. II, Universitext. Springer-Verlag, Berlin, 1987.

Furthermore, I wanted to ensure that the spherical coordinates have the correct orientation right from the start. That explains the reordering of coordinates compared to Wikipedia, and it makes the transition map to figure out even more tricky.

On general grounds, I don't think we should depart from Wikipedia conventions without a good reason. Moreover, I think it is standard convention to have the periodic coordinate on Sⁿ to be the last one (as in (theta, phi) for S²), not the first one.

[mjungmath]

comment:13

Replying to @egourgoulhon:

Replying to @mjungmath:

I tried to cover spherical coordinates in arbitrary dimensions as well. But it turned out that the transition map to the stereographic coordinates is a bit complicated in the general setup. I welcome any kind of reference that might help.

A very good reference for the sphere in any dimension is Chapter 18 The sphere for its own sake in Marcel Berger: Geometry, vol. II, Universitext. Springer-Verlag, Berlin, 1987.

Thanks. I'll take a look.

Furthermore, I wanted to ensure that the spherical coordinates have the correct orientation right from the start. That explains the reordering of coordinates compared to Wikipedia, and it makes the transition map to figure out even more tricky.

On general grounds, I don't think we should depart from Wikipedia conventions without a good reason. Moreover, I think it is standard convention to have the periodic coordinate on Sⁿ to be the last one (as in (theta, phi) for S²), not the first one.

We have to deviate from the Wikipedia convention anyway.

This is simply because the slit we take out for spherical coordinates should meet the poles. Currently, the north/south pole is encoded in the last coordinate. We can shift it to the first, and then we can recover the conventions in Wikipedia for spherical coordinates. But that would be another convention we break, namely for the stereographic projection.

[egourgoulhon]

comment:14

Replying to @mjungmath:

We have to deviate from the Wikipedia convention anyway.

This is simply because the slit we take out for spherical coordinates should meet the poles. Currently, the north/south pole is encoded in the last coordinate. We can shift it to the first, and then we can recover the conventions in Wikipedia for spherical coordinates. But that would be another convention we break, namely for the stereographic projection.

Sorry I don't understand what you mean. It seems to me that we can keep Wikipedia conventions, both for spherical coordinates and stereographic ones, as we do already for S² in this example. Then the spherical frame and the stereographic frame from the South pole are right-handed and the stereographic frame from the North pole is left-handed.

[mjungmath]

comment:15

Replying to @egourgoulhon:

Replying to @mjungmath:

We have to deviate from the Wikipedia convention anyway.

This is simply because the slit we take out for spherical coordinates should meet the poles. Currently, the north/south pole is encoded in the last coordinate. We can shift it to the first, and then we can recover the conventions in Wikipedia for spherical coordinates. But that would be another convention we break, namely for the stereographic projection.

Sorry I don't understand what you mean. It seems to me that we can keep Wikipedia conventions, both for spherical coordinates and stereographic ones, as we do already for S² in this example. Then the spherical frame and the stereographic frame from the South pole are right-handed and the stereographic frame from the North pole is left-handed.

That's right. But notice that the convention in the general case is slightly different than in the 2-sphere case, compare [https://en.wikipedia.org/wiki/N-sphere#Spherical_coordinates [1]] with [https://en.wikipedia.org/wiki/Spherical_coordinate_system#Cartesian_coordinates [2]]. If you consider the embedding in spherical coordinates in the general case, and follow the convention [1], it appears to happen that the poles do not belong to the removed meridian.

So what I did was reversing the order of the x_i and phi_i simultanously (compare [1]) in hope to find a consistent formula. Turns out that everything behaves nicely in this setup: the implementation is easy and the inverse looks comparably nice. One even gets an oriented coordinate frame on top.

Whatever convention we choose, I will provide a thorough documentation of the conventions used in the implementation anyway.

[mjungmath]

comment:16

Attachment: spherical.png

I have added the choice of coordinates and their inverse in an attachment. I think the formulas look very nice this way (provided I haven't miscalculated).

[mjungmath]

comment:19

I see these options:

1. Keep it the way I suggested.
2. Break the convention for the stereographic projection, and put the poles to the first coordinate, then use the convention [https://en.wikipedia.org/wiki/N-sphere#Spherical_coordinates [1]].
3. Use suggestion 1 or 2 and separate the 2-sphere to obtain convention [https://en.wikipedia.org/wiki/Spherical_coordinate_system#Cartesian_coordinates [2]].
4. Keep the stereographic convention, alter the convention [https://en.wikipedia.org/wiki/N-sphere#Spherical_coordinates [1]] in such a way that we obtain convention [https://en.wikipedia.org/wiki/Spherical_coordinate_system#Cartesian_coordinates [2]] for the 2-sphere case.

I personally vote for 1 as long as the documentation is thorough enough.

[mjungmath]

comment:21

I gave it a little thought. I think option 4 is best. Option 4 is in a way canonical: we obtain the convention for S^1 and for S^2. It is only plausible then that the convention should be kept for higher dimensions as well (I don't know why it isn't so).

In addition, we don't need an extra class with facade pattern for 1D and 2D.

Agreed?

[tobiasdiez]

comment:22

This sounds like a good plan.

I'm not sure if that works, but is it possible to add all these different conventions as additional charts? Then the user can decide which convention he wants to follow. This would also be the most flexible approach (e.g. to verify formulas in different conventions etc).

[mjungmath]

comment:23

Replying to @tobiasdiez:

I'm not sure if that works, but is it possible to add all these different conventions as additional charts? Then the user can decide which convention he wants to follow. This would also be the most flexible approach (e.g. to verify formulas in different conventions etc).

I agree that this would be the best option. But I suspect that it is not worth the effort. Furthermore, these details can be added by time. I think, a non-primitive working sphere example in any dimension is enough for now.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 6215d79 to 888b360

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

47600c6	Trac #30804: simplicial complex added
8d2f44d	Trac #30799: collect manifolds examples in 'examples' + lazy_import for catalog
0265e0a	Trac #30804: Merge branch 't/30799/add_folder_for_manifold_models' into t/30804/add_standard_sphere_to_manifold_catalog
d81a522	Trac #30804: "<...>" syntax support for coordinates
60b2724	Merge branch 'develop' into t/30804/add_standard_sphere_to_manifold_catalog
888b360	Trac #30804: coordinate convention in 1D and 2D

[mjungmath]

comment:25

I have added some more features and adapted the coordinates. If you agree on these conventions, I would start with the documentation.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 888b360 to e9c11dd

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

e9c11dd

Trac #30804: tuple syntax error

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

a31fcbb	Trac #30804: intermediate commit for docstring
9815ea5	Trac #30804: intermediate step
ae86b2a	Trac #30804: programming content done

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from e9c11dd to ae86b2a

[mjungmath]

comment:28

Okay, this is it, the code should be complete now. I will finish the documentation soon. Until then, you are free to comment on the code.

If everything is done, I will stash the commits to smooth the final merge.

[mjungmath]

comment:29

If you have any ideas for examples that should come up in the documentation, please let me know.

[egourgoulhon]

comment:30

This looks very nice. Thanks!

Some first few remarks:

• the reference to Berger should be Geometry II, not Geometry I
• the LaTeX formula in the docstring of spherical_coordinates is not correct; in particular, one should have x_n = cos phi_1, not x_n = cos phi_n
• could one have an option for the periodic coordinate phi_n to range in [0, 2pi] instead of [-pi, pi]? Both conventions exist in the literature. What should be the default? (I would vote for [0, 2pi])
• for S³, could we have customized spher. coordinate names (chi, theta, phi) (I think this is pretty standard for S³), instead of (phi_1, phi_2, phi_3)?
• for S³, we should probably have Hopf coordinates as well

[mjungmath]

comment:31

Replying to @egourgoulhon:

This looks very nice. Thanks!

Some first few remarks:

• the reference to Berger should be Geometry II, not Geometry I
• the LaTeX formula in the docstring of spherical_coordinates is not correct; in particular, one should have x_n = cos phi_1, not x_n = cos phi_n

Corrected. The finished docstring will be pushed soon. Almost done here.

• could one have an option for the periodic coordinate phi_n to range in [0, 2pi] instead of [-pi, pi]? Both conventions exist in the literature. What should be the default? (I would vote for [0, 2pi])

This belongs more or less to what Tobias suggested. In principle it is good to allow various conventions. However, the case [-pi, pi] is easier to handle with the atan2 function (its range is exactly [-pi, pi]).

• for S³, could we have customized spher. coordinate names (chi, theta, phi) (I think this is pretty standard for S³), instead of (phi_1, phi_2, phi_3)?

I will add them.

• for S³, we should probably have Hopf coordinates as well

I agree. However, I would prefer that the special cases S^1, S^3, S^7 are dedicated to a follow up ticket. This ticket already covers all necessary functionalities of general spheres.

[mjungmath]

comment:32

Moreover, I think it is a splendid idea to connect S^1 and S^3 to its corresponding Lie groups, i.e. U(1) and SU(2), and possible spin groups.

[egourgoulhon]

comment:33

Replying to @mjungmath:

Replying to @egourgoulhon:

• could one have an option for the periodic coordinate phi_n to range in [0, 2pi] instead of [-pi, pi]? Both conventions exist in the literature. What should be the default? (I would vote for [0, 2pi])

This belongs more or less to what Tobias suggested. In principle it is good to allow various conventions. However, the case [-pi, pi] is easier to handle with the atan2 function (its range is exactly [-pi, pi]).

Indeed. Could we have at least a keyword argument periodic_range in Sphere? Or do you think this deserves another ticket?

• for S³, we should probably have Hopf coordinates as well

I agree. However, I would prefer that the special cases S^1, S^3, S^7 are dedicated to a follow up ticket. This ticket already covers all necessary functionalities of general spheres.

Agreed.

[egourgoulhon]

comment:34

Replying to @mjungmath:

Moreover, I think it is a splendid idea to connect S^1 and S^3 to its corresponding Lie groups, i.e. U(1) and SU(2), and possible spin groups.

+1

[mjungmath]

comment:35

Replying to @egourgoulhon:

Indeed. Could we have at least a keyword argument periodic_range in Sphere? Or do you think this deserves another ticket?

Hm, I personally would vote for another ticket. Adding new features would clutter my current progress. I would like to finish the examples and conclude that ticket as soon as possible. Then we can discuss further improvements. My proposal is already more comprehensive than the previous and worth a merge, I'd say.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from ae86b2a to 2bb397e

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

4497e15	Trac #30804: doctests passed so far
2bb397e	Trac #30804: next docstring step

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 2bb397e to f3b4d86

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

2a64378	Trac #30804: docstring probably finished
f3b4d86	Trac #30804: docstring probably finished II

[mjungmath]

comment:38

docstring should be finished now. Last opportunity to declare wishes for examples.

I will finish everything up tomorrow and set the ticket to needs_review.

[mjungmath]

comment:39

By the way, I noticed that there is no section in the documentation dedicated to general examples (except for EuclideanSpace). This should be expanded when more examples of this kind are added.

[tscrim]

comment:40

You can just set it to needs review now; if there are more comments then people can provide it then.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from f3b4d86 to 95982e8

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

1152908	Trac #30804: first n-sphere approach
6edafec	Trac #30799: collect manifolds examples in 'examples' + lazy_import for catalog
95982e8	Trac #30804: code and docstring finished

[mjungmath]

comment:42

Squashed commits. Ready for review.

[mjungmath]

Author: Michael Jung