Pseudo-Riemannian manifods

[egourgoulhon]

This ticket implements pseudo-Riemannian manifolds, i.e. real differentiable manifolds equipped with a metric tensor. Important subcases are of course Riemannian manifolds and Lorentzian manifolds. Taking into account that pseudo-Riemannian metric tensors are already implemented in Sage (see ​here), this ticket introduces

• the parent class PseudoRiemannianManifold, as a subclass of the existing class DifferentiableManifold, with the specific methods metric and volume_form
• new methods gradient, laplacian and dalembertian for scalar fields
• new methods divergence, laplacian and dalembertian for tensor fields
• new methods curl, dot_product, cross_product and norm for vector fields

For a greater generality, all these methods have an optional argument metric; if it is omitted, the metric of the underlying pseudo-Riemannian manifold is assumed.

To match with the standard functional notation, functions grad, div, curl, laplacian and dalembertian have been implemented in src/sage/manifolds/differentiable/operators.py. Their role is simply to call the corresponding methods on their arguments. In order not to clutter the global namespace in a standard Sage session, these functions are imported only if some pseudo-Riemannian manifold is constructed, via the call to sage.repl.user_globals.set_global in PseudoRiemannianManifold.__init__.

Some vector calculus functionalities introduced by this ticket are demonstrated in this ​Jupyter worksheet.

The follow-up ticket #24623 implements Euclidean spaces.

This work is part of the ​SageManifolds project, see #18528 for an overview.

[egourgoulhon]

This is work in progress...

---

New commits:

​8e1148c	First version of pseudo-Riemannian manifold class
​8e56cf3	Pseudo-Riemannian manifolds constructed by the generic function Manifold
​ce3a617	Divergence of a tensor field + new section on pseudo-Riemannian manifolds in the reference manual
​06f8fd3	Add doctests for pseudo-Riemannian manifolds

[git]

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

​55f356c

Improve documentation of pseudo-Riemannian manifolds

[git]

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

​0fc661a

Remove method set_metric and improve doc of pseudo-Riemannian manifolds

[git]

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

​b4dddf7

Add operators Laplacian, d'Alembertian and curl on pseudo-Riemannian manifolds

[git]

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

​040b01c

Add dot product and cross product of vector fields

[git]

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

​46b8f66

Add norm of vector fields.

[git]

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

​135af97

Add method volume_form() to class PseudoRiemannianManifold

[git]

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

​38e8fd3

Add global functions grad, div, curl, etc. for vector/tensor operators on pseudo-Riemannian manifolds

[git]

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

​8309fdd

Improve documentation for operators on pseudo-Riemannian manifolds

[tscrim]

The biggest issue I have with this ticket is the addition of functions to the global namespace. curl, laplacian, and dalembertian I think are okay. grad over gradient I am not sure about. div looks too much like it is coming from "divide" or "division". I think you should ask on sage-devel to see if anyone has any objections with adding these to the global namespace and about them being a simple re-direct. (Ralf may want to have them interact with the symbolics in some way.)

In the same vein, this is bad to me:

        # Import differential operators in the user global namespace:
        if 'grad' not in get_globals():
            from sage.manifolds.differentiable.operators import (grad, div,
                                                 curl, laplacian, dalembertian)
            set_global('grad', grad)
            set_global('div', div)
            set_global('curl', curl)
            set_global('rot', curl)
            set_global('laplacian', laplacian)
            set_global('dalembertian', dalembertian)

I think a much better way is just to either have them all in the global namespace at start or having some function inject_functions(), but with some better name than I can come up with in 5 seconds.

---

Other small comments:

This is under-indetented:

src/sage/manifolds/differentiable/tensorfield.py

@@ -3087 +3087 @@
 
         .. MATH::
 
-            (T^\sharp)^{a_1\ldots a_{k+1}}_{\qquad\ \ b_1 \ldots b_{l-1}}
-            = g^{a_{k+1} i} \,
-            T^{a_1\ldots a_k}_{\qquad\   b_1 \ldots b_{p-k} \, i \, b_{p-k+1}\ldots b_{l-1}},
+          (T^\sharp)^{a_1\ldots a_{k+1}}_{\phantom{a_1\ldots a_{k+1}}\, b_1 \ldots b_{l-1}}
+          = g^{a_{k+1} i} \,
+          T^{a_1\ldots a_k}_{\phantom{a_1\ldots a_k}\, b_1 \ldots b_{p-k} \, i \, b_{p-k+1}\ldots b_{l-1}},
 
         `g^{ab}` being the components of the inverse metric.
 
@@ -3235 +3235 @@
 
         .. MATH::
 
-            (T^\flat)^{a_1\ldots a_{k-1}}_{\qquad\ \  b_1 \ldots b_{l+1}}
-            = g_{b_1 i} \,
-            T^{a_1\ldots a_{p} \, i \, a_{p+1}\ldots a_{k-1}}_{\qquad\qquad\quad\; b_2 \ldots b_{l+1}},
+          (T^\flat)^{a_1\ldots a_{k-1}}_{\phantom{a_1\ldots a_{k-1}}\, b_1 \ldots b_{l+1}}
+          = g_{b_1 i} \,
+          T^{a_1\ldots a_{p} \, i \, a_{p+1}\ldots a_{k-1}}_{\phantom{a_1\ldots a_{p} \, i \, a_{p+1}\ldots a_{k-1}}\, b_2 \ldots b_{l+1}},
 
         `g_{ab}` being the components of the metric tensor.
 

(It's okay that not everything in a .. MATH:: block, but I do prefer the >= 4 spaces indentation visually.)

Everything else LGTM.

[egourgoulhon]

Replying to tscrim:

Thanks for looking to this ticket and for your comments.

The biggest issue I have with this ticket is the addition of functions to the global namespace. curl, laplacian, and dalembertian I think are okay. grad over gradient I am not sure about. div looks too much like it is coming from "divide" or "division".

I agree that div may evoke "division", however grad and div are pretty much standard notations in both elementary vector calculus and differential geometry, see e.g.

• ​https://en.wikipedia.org/wiki/Vector_calculus#Differential_operators
• ​https://en.wikipedia.org/wiki/Vector_calculus_identities#Operator_notations
• ​https://en.wikipedia.org/wiki/Divergence

As a side note, neither grad nor div is already used as a global function in Sage, so the slot is free.

I think you should ask on sage-devel to see if anyone has any objections with adding these to the global namespace and about them being a simple re-direct.

OK I will.

In the same vein, this is bad to me:

        # Import differential operators in the user global namespace:
        if 'grad' not in get_globals():
            from sage.manifolds.differentiable.operators import (grad, div,
                                                 curl, laplacian, dalembertian)
            set_global('grad', grad)
            set_global('div', div)
            set_global('curl', curl)
            set_global('rot', curl)
            set_global('laplacian', laplacian)
            set_global('dalembertian', dalembertian)

I think a much better way is just to either have them all in the global namespace at start or having some function inject_functions(), but with some better name than I can come up with in 5 seconds.

Why is it bad? Is it because it prevents the user from discovering the grad function with the TAB key and/or grad? before having set up any pseudo-Riemannian manifold? This would indeed be a good reason to have the operators in the global namespace at start.

This is under-indetented: (It's okay that not everything in a .. MATH:: block, but I do prefer the >= 4 spaces indentation visually.)

OK, I will correct this.

[tscrim]

Replying to egourgoulhon:

Replying to tscrim:

Thanks for looking to this ticket and for your comments.

The biggest issue I have with this ticket is the addition of functions to the global namespace. curl, laplacian, and dalembertian I think are okay. grad over gradient I am not sure about. div looks too much like it is coming from "divide" or "division".

I agree that div may evoke "division", however grad and div are pretty much standard notations in both elementary vector calculus and differential geometry, see e.g.

• ​https://en.wikipedia.org/wiki/Vector_calculus#Differential_operators
• ​https://en.wikipedia.org/wiki/Vector_calculus_identities#Operator_notations
• ​https://en.wikipedia.org/wiki/Divergence

As a side note, neither grad nor div is already used as a global function in Sage, so the slot is free.

The difference is that in those links, you know you are doing vector calculus, whereas in Python you have operator.div.

In the same vein, this is bad to me:

        # Import differential operators in the user global namespace:
        if 'grad' not in get_globals():
            from sage.manifolds.differentiable.operators import (grad, div,
                                                 curl, laplacian, dalembertian)
            set_global('grad', grad)
            set_global('div', div)
            set_global('curl', curl)
            set_global('rot', curl)
            set_global('laplacian', laplacian)
            set_global('dalembertian', dalembertian)

I think a much better way is just to either have them all in the global namespace at start or having some function inject_functions(), but with some better name than I can come up with in 5 seconds.

Why is it bad? Is it because it prevents the user from discovering the grad function with the TAB key and/or grad? before having set up any pseudo-Riemannian manifold? This would indeed be a good reason to have the operators in the global namespace at start.

You should not inject them without the user knowing. In particular, what if you have rot = some expensive computation, then you create your manifold (with not having created a grad) and all of a sudden, your rot computation is gone. On the other side, what if we add a different grad to the global namespace, something I think could happen, then you will not get these injections.

I agree that they should be in the global namespace from the start and would making this issue moot. Some other thoughts that come to my mind is a function like setup_manifolds_environment and/or getting people who use SageManifolds to have a specific section to their .sage/init.sage file.

[egourgoulhon]

Replying to tscrim:

The difference is that in those links, you know you are doing vector calculus, whereas in Python you have operator.div.

Yes I agree, this depends on the context.

You should not inject them without the user knowing. In particular, what if you have rot = some expensive computation, then you create your manifold (with not having created a grad) and all of a sudden, your rot computation is gone. On the other side, what if we add a different grad to the global namespace, something I think could happen, then you will not get these injections.

Thanks for these explanations. I totally overlooked this point... I am now 100% convinced that injecting silently names in the global namespace is a very bad thing.

I agree that they should be in the global namespace from the start and would making this issue moot. Some other thoughts that come to my mind is a function like setup_manifolds_environment and/or getting people who use SageManifolds to have a specific section to their .sage/init.sage file.

I'll think about this, given that the discussion on sage-devel leans toward not adding new stuff in the global namespace.

[git]

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

​18b63a6

Differential operators are no longer imported in the global namespace by PseudoRiemannianManifold.__init__

[egourgoulhon]

Following the conclusions of the ​sage-devel thread, the above commit allows only explicit imports of the type:

sage: from sage.manifolds.operators import *

to inject the differential operators in the global namespace. Besides, this commit corrects the indentation of .. MATH blocks mentioned in comment:15.

[tscrim]

One little trivial thing: the functions are no longer global (at least, I am interpreting that as being in the global namespace):

-        The function :func:`~sage.manifolds.operators.laplacian` can be
+        The global function :func:`~sage.manifolds.operators.laplacian` can be
+        used instead of the method ``laplacian()``::

and similar for div and curl, etc. Also, do you want to link laplacition() to a (the?) corresponding method via :meth:?

[jhpalmieri]

A few typos with proposed corrections:

src/sage/manifolds/differentiable/pseudo_riemannian.py

@@ -4 +4 @@
 A *pseudo-Riemannian manifold* is a pair `(M,g)` where `M` is a real
 differentiable manifold `M` (see
 :class:`~sage.manifolds.differentiable.manifold.DifferentiableManifold`)
-and `g` is a field non-degenerate symmetric bilinear forms on `M`, which is
+and `g` is a field of non-degenerate symmetric bilinear forms on `M`, which is
 called the *metric tensor*, or simply the *metric* (see
 :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetric`).
 
@@ -58 +58 @@
     sage: g
     Riemannian metric g on the 2-dimensional Riemannian manifold S^2
 
-At this stage, the metric `g` is defined a Python object but there remains to
+At this stage, the metric `g` is defined as a Python object but there remains to
 initialize it by setting its components with respect to the vector frames
 associated with the stereographic coordinates. Let us begin with the frame
 of chart ``stereoN``::
@@ -145 +145 @@
     sage: gU.display()
     g = 4/(x^2 + y^2 + 1)^2 dx*dx + 4/(x^2 + y^2 + 1)^2 dy*dy
 
-On course, ``gU`` is nothing but the restriction of `g` to `U`::
+Of course, ``gU`` is nothing but the restriction of `g` to `U`::
 
     sage: gU is g.restrict(U)
     True
@@ -153 +153 @@
 .. RUBRIC:: Example 2: Minkowski spacetime as a Lorentzian manifold of
   dimension 4
 
-We start by declaring 4-dimensional Lorentzian manifold::
+We start by declaring a 4-dimensional Lorentzian manifold::
 
     sage: M = Manifold(4, 'M', structure='Lorentzian')
     sage: M
@@ -223 +223 @@
     A *pseudo-Riemannian manifold* is a pair `(M,g)` where `M` is a real
     differentiable manifold `M` (see
     :class:`~sage.manifolds.differentiable.manifold.DifferentiableManifold`)
-    and `g` is a field non-degenerate symmetric bilinear forms on `M`, which is
+    and `g` is a field of non-degenerate symmetric bilinear forms on `M`, which is
     called the *metric tensor*, or simply the *metric* (see
     :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetric`).
 
@@ -405 +405 @@
                dest_map=None):
         r"""
         Return the metric giving the pseudo-Riemannian structure to the
-        manifold, or defines a new metric tensor on the manifold.
+        manifold, or define a new metric tensor on the manifold.
 
         INPUT:
 

[git]

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

​185e438

Improve documentation of pseudo-Riemannian manifolds

[egourgoulhon]

Replying to tscrim:

One little trivial thing: the functions are no longer global (at least, I am interpreting that as being in the global namespace):

and similar for div and curl, etc. Also, do you want to link laplacition() to a (the?) corresponding method via :meth:?

Thanks for pointing this. This is corrected in the above commit. I have also added some simple vector fields in the Minkowski spacetime example (example 2 at the top of pseudo_riemannian.py).

[egourgoulhon]

Replying to jhpalmieri:

A few typos with proposed corrections:

Thank you very much for these corrections. They are effective in the above commit.

[tscrim]

LGTM. Thank you.

[egourgoulhon]

Thank you very much for the review!