Manifolds: add orientability

[gh-mjungmath]

It would be good if one can state whether a manifold is orientable as some statements only apply for these kind of manifolds. Of course, at the end it will be, except for very trivial cases, the user's responsibility that the conditions are actually satisfied.

Note: Compactness follows in a later ticket

[gh-mjungmath]

Regarding orientability:

One could add a method set_orientation which takes a list of charts or frames which cover the manifold yielding an orientation. Then it is the user's responsibility to check that this is indeed an orientation. Using this, one can construct things like volume forms etc.

In very easy cases, like if the manifold is covered by only one chart, one can give the orientation right away.

Remark: Notice that the volume form returned by ​sage.manifolds.differentiable.metric.PseudoRiemannianMetric.volume_form does not necessarily yield a volume form at all. One indeed needs an oriented atlas. Otherwise, the gluing process could be messed up. This can all be prevented and covered by my proposal above.

Regarding Compactness:

I think, the best way would be to state compactness right from the beginning. Not stating compactness should, in my opinion, not exclude compactness. Maybe a new manifold class does a suitable job?

[gh-mjungmath]

In the differentiable setting, things are easy and can be managed by using frames. This is quite convenient because there are manifolds which can be covered by one global frame, and therefore admit an orientation, but need at least two charts.

However, I know that there is a notion of orientability in the topological setting, where the use of charts is mandatory. I look for further literature.

I would prefer the chart version because it is applicable to both, topological and differentiable manifolds. Because the former case is easier and more practical, one could also implement orientations only for differentiable manifolds at first. Further opinions on that?

Addendum: If someone has an idea of how both cases, charts and frames, can be managed conveniently, I welcome that pretty much.

[gh-mjungmath]

I have added a first draft (without documentation). I wait for your opinions before I go on.

---

New commits:

​b8fcbe5

Trac #30178: first draft for orientations

[mkoeppe]

Just a quick note that there is already an axiom Compact provided by TopologicalSpaces.

[git]

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

​e1a34b3	Trac #30178: orientibility for vector bundles
​074b43c	Trac #30178: Merge branch 'orientation_alternative' into t/30178/orientability
​39844ba	Trac #30178: unify notation
​329453e	Trac #30178: orientabilty for vector bundles and diff manifolds finished

[git]

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

​8ed6b68

Trac #30178: refinement of concepts

[git]

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

​034cdf7	Trac #30178: volume form adapted to new code
​dec40cd	Trac #30178: documentation improved
​4725246	Trac #30178: orientation finished

[gh-mjungmath]

I forgot the authorship...again.

[git]

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

​afd1577

Trac #30178: doctests fixed

[git]

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

​a904891

Trac #30178: orientation check in metric fixed

[git]

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

​f2c3a3c	Trac #30178: better error message
​76be28c	Trac #30178: documentation improved + error message reverted

[git]

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

​dbd4e5d

Trac #30178: typo in doc

[gh-mjungmath]

Patchbot won't go green, startup issues. Can one force another patchbot check?

[tscrim]

There was a green patchbot run (also that plugin can be a bit more fickle).

[gh-mjungmath]

Ah yes, on beta6. Anyway, this ticket is ready for review. :)

[tscrim]

In response to your questions/comments from comment:2: I think it should just be the user's responsibility as it would be too costly and annoying to include code to check this. Trusting the usuer is done in a number of places in Sage too. As Matthias said, you can use Manifolds(R).Compact() to indicate compactness.

A few stylistic things:

You are saving 1 character here

            from sage.manifolds.differentiable.vector_bundle \
                                                            import TensorBundle

Just go over the 80 char/line limit; it makes it much more readable.

Similar for these changes:

             sage: repr(TM) # indirect doctest
-            'Tangent bundle TM over the 2-dimensional differentiable manifold M'
+            'Tangent bundle TM over the 2-dimensional differentiable
+             manifold M'
             sage: TM._repr_()
-            'Tangent bundle TM over the 2-dimensional differentiable manifold M'
+            'Tangent bundle TM over the 2-dimensional differentiable
+             manifold M'

Further indent the last line on this change and all other similar changes:

             {(Chart (M, (x, y)),
-              Chart (M, (u, v))): Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v))}
+              Chart (M, (u, v))): Change of coordinates from Chart (M, (x, y))
+              to Chart (M, (u, v))}

to make it (more) clear that it is associated to that item.

[gh-mjungmath]

Replying to tscrim:

In response to your questions/comments from comment:2: I think it should just be the user's responsibility as it would be too costly and annoying to include code to check this. Trusting the usuer is done in a number of places in Sage too. As Matthias said, you can use Manifolds(R).Compact() to indicate compactness.

Right. There are many tickets going on simultaneously. I have to catch them up first.

A few stylistic things:

You are saving 1 character here

            from sage.manifolds.differentiable.vector_bundle \
                                                            import TensorBundle

Just go over the 80 char/line limit; it makes it much more readable.

Similar for these changes:

             sage: repr(TM) # indirect doctest
-            'Tangent bundle TM over the 2-dimensional differentiable manifold M'
+            'Tangent bundle TM over the 2-dimensional differentiable
+             manifold M'
             sage: TM._repr_()
-            'Tangent bundle TM over the 2-dimensional differentiable manifold M'
+            'Tangent bundle TM over the 2-dimensional differentiable
+             manifold M'

Further indent the last line on this change and all other similar changes:

             {(Chart (M, (x, y)),
-              Chart (M, (u, v))): Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v))}
+              Chart (M, (u, v))): Change of coordinates from Chart (M, (x, y))
+              to Chart (M, (u, v))}

to make it (more) clear that it is associated to that item.

Mh, okay. Well, I followed the PEP8 guidelines which indicates 79 characters per line: ​https://www.python.org/dev/peps/pep-0008/#maximum-line-length

[gh-mjungmath]

Apparently, the guidelines have changed a couple of years ago. The PEP8 guidelines are linked in the ​Sage reference but their recommendations have not been updated.

[tscrim]

PEP8 sets guidelines, but code readability is the most important thing. Each of those changes makes it harder to read the code.

[gh-mjungmath]

Replying to tscrim:

PEP8 sets guidelines, but code readability is the most important thing. Each of those changes makes it harder to read the code.

Fair enough, I'll change it back. Thanks.

[git]

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

​f56f56e

Trac #30178: improve readability

[git]

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

​54267bc

Trac #30178: indent

[gh-mjungmath]

Like this?

[tscrim]

Yes, except I think you are better off leaving this alone:

from sage.manifolds.differentiable.vector_bundle import TensorBundle

(i.e., on one line).

[git]

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

​3eaaaab

Trac #30178: one line

[gh-mjungmath]

Satisfied? :)

[gh-mjungmath]

Patchbot is green.

[tscrim]

Yes, thank you. However, I do have a few other comments from another read-over. However, these should be the last of them.

The keys() call here

for frame in base_space._get_min_covering(connection._coefficients.keys()):

seem like it is not needed.

         INPUT:
 
-        - an orientation; either a chart / list of charts, or a vector frame /
+        - ``orientation`` -- either a chart / list of charts, or a vector frame /
           list of vector frames, covering ``self``

and similar.

This

        .. NOTE::

            This assumes that the manifold admits an orientation, see
            :meth:`~sage.manifolds.manifold.DifferentiableManifold.orientation`
            for details.

in volume_form() (in differentiable/metric.py) is wrong. An error is raised if the manifold does not admit an orientation. Subsequently in hodge_star as well.

In set_orientation is it the default orientation or simply the orientation? I don't think you allow multiple orientations on a manifold. Is that a planned future feature?

# set a priori no orientation -> # default is no orientation (or # set no orientation a priori)

-        if self.orientation():
-            return True
-        return False
+        return bool(self.orientation())

[gh-mjungmath]

Replying to tscrim:

Yes, thank you. However, I do have a few other comments from another read-over. However, these should be the last of them.

The keys() call here

for frame in base_space._get_min_covering(connection._coefficients.keys()):

seem like it is not needed.

Ah yes. Thank you.

         INPUT:
 
-        - an orientation; either a chart / list of charts, or a vector frame /
+        - ``orientation`` -- either a chart / list of charts, or a vector frame /
           list of vector frames, covering ``self``

and similar.

Good. Thanks.

This

        .. NOTE::

            This assumes that the manifold admits an orientation, see
            :meth:`~sage.manifolds.manifold.DifferentiableManifold.orientation`
            for details.

in volume_form() (in differentiable/metric.py) is wrong. An error is raised if the manifold does not admit an orientation. Subsequently in hodge_star as well.

You mean wrong in the sense that we should note that having no orientation means this feature is not available?

In set_orientation is it the default orientation or simply the orientation? I don't think you allow multiple orientations on a manifold. Is that a planned future feature?

I cannot think of a case where a manifold has the orientation. Allowing multiple orientations means also allowing multiple volume forms. But which one then to choose for hodge_star? I think it is reasonable to fix just one orientation.

# set a priori no orientation -> # default is no orientation (or # set no orientation a priori)

-        if self.orientation():
-            return True
-        return False
+        return bool(self.orientation())

Good. Already done.

[tscrim]

Replying to gh-mjungmath:

Replying to tscrim:

This

        .. NOTE::

            This assumes that the manifold admits an orientation, see
            :meth:`~sage.manifolds.manifold.DifferentiableManifold.orientation`
            for details.

in volume_form() (in differentiable/metric.py) is wrong. An error is raised if the manifold does not admit an orientation. Subsequently in hodge_star as well.

You mean wrong in the sense that we should note that having no orientation means this feature is not available?

No, as in there is not an assumption being made. If it has not been defined, an error is raised rather than assuming that the manifold admits an orientation (and using that implicit orientation).

In set_orientation is it the default orientation or simply the orientation? I don't think you allow multiple orientations on a manifold. Is that a planned future feature?

I cannot think of a case where a manifold has the orientation. Allowing multiple orientations means also allowing multiple volume forms. But which one then to choose for hodge_star? I think it is reasonable to fix just one orientation.

I know there are multiple orientations possible for a manifold, but there is a set orientation for the manifold. There is not a default one where a user can arbitrarily choose another as an input. Contrast this with charts. I would think of this like a manifold with a distinguished orientation (which can be changed later on, but the manifold has still indicated the one orientation to rule them all).

[gh-mjungmath]

Okay, I will call it "preferred" orientation instead. It would be good if, in the trivial case, the default chart/frame is used. While applying this, I discovered a bug (see #30320).

[git]

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

​70fae37	Trac #30178: cosmetic improvements
​071efcf	Trac #30178: prefer default chart/frame being orientation

[gh-mjungmath]

See my new push. This approach is independent of #30320.

[tscrim]

Just to be clear, as long as you raise an error when there is no orientation, you need to remove that .. NOTE:: because it is wrong. No assumption is made as an explicit check is performed.

[gh-mjungmath]

Replying to tscrim:

Just to be clear, as long as you raise an error when there is no orientation, you need to remove that .. NOTE:: because it is wrong. No assumption is made as an explicit check is performed.

Ah, it's just about the note block. I'll remove it.

[git]

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

​9b5f74b

Trac #30178: .. NOTE: block removed

[gh-mjungmath]

Is this better? If not, could you please suggest an improvement, because then I don't know what you mean.

[tscrim]

That is perfect, thank you.

[gh-mjungmath]

Okay good. Thank you for the review and your patience. :)

[vbraun]

Merge conflict

[git]

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

​a198d1f

Merge branch 'develop' into t/30178/orientability

[egourgoulhon]

See #30519 for a follow up.