Geometry of pseudo-Riemannian submanifolds

[gh-FlorentinJ]

This ticket is the logical continuation of #25164

It implements various calculus methods on pseudo-riemannian submanifolds (for example: normal vector, first/second fundamental form, gauss/principal/mean curvature...).

Some methods are also used exclusively in the case a foliation is provided (shift, lapse, ...).

Using these functions, one can for example easily perform n+1 decomposition of any tensorfield.

This is part of the ​​SageManifolds project; see the metaticket #18528 for an overview.

[git]

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

​4932d56	Added mixed_projection
​2bf6d93	Added doctests
​3c72fca	Merge branch 'develop' into calculus
​c9a7082	Merge branch 'public/manifolds/submanifolds' of git://trac.sagemath.org/sage into Sage 8.3.beta2
​eb2b4c8	Reviewer tweaks for submanifolds
​a3a1cce	Merge ticket 25164 into calculus
​4834f1c	Fix error in mixed projection

[git]

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

​65ae3ff

Update to 8.3.beta3

[egourgoulhon]

Have you noticed the errors reported by the patchbot (2 doctests + various plugins)?

To understand what the plugins check presicely, see the docstrings in the source file ​plugins.py. For instance, you will see that \overrightarrow, which is a valid LaTeX instruction, triggers the plugin foreign_latex...

[git]

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

​9d42338	Removed an inaccessible piece of code, added exception
​2d6fd8e	Minor improvements

[egourgoulhon]

This is a nice enhancement regarding differential geometry!

The code is carefully written and documented. The main issue is the long time of some doctests, for instance:

File "src/sage/manifolds/differentiable/pseudo_riemannian_submanifold.py", 
line 156, in sage.manifolds.differentiable.pseudo_riemannian_submanifold
Warning, slow doctest:
    N.extrinsic_curvature()[:] # long time
Test ran for 462.97 s

This is far too long for a single doctest. On my computer, there are 7 doctests with a time above 50 s. This increases too much the total time for doctesting all Sage library. Probably the solution would be to decrease the dimensionality of your examples, i.e. consider hypersurfaces embedded in a 3-dimensional manifold instead of a 4-dimensional one.

Another remark: the documentation generated for the method ambient_extrinsic_curvature appears to be that of the decorator @cached_method, because of the alias

ambient_extrinsic_curvature = cached_method(ambient_second_fundamental_form)

in line 974 of pseudo_riemannian_submanifold.py. Same issue for extrinsic_curvature, induced_metric, ambient_induced_metric.

[git]

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

​e5a290d

Shorten some doctests, fix documentation of alias of cached_methods

[gh-FlorentinJ]

I went from 4D Minkowsky to 3D Minkowsky in the first example, which resulted in a total test time of about 4 minutes on my laptop:

----------------------------------------------------------------------
All tests passed!
----------------------------------------------------------------------
Total time for all tests: 247.5 seconds
    cpu time: 269.6 seconds
    cumulative wall time: 247.4 seconds

Further reducing this time would mean further reducing the dimension, but 1D foliation of 2D manifold are not very interesting.

[git]

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

​0690144

Reviewer tweaks regarding geometry of pseudo-Riemannian submanifolds

[egourgoulhon]

In the above "reviewer tweaks", I've mostly amended the documentation. The main change is the removal of the @cached_method decorator on methods like first_fundamental_form and the removal of the duplicated code in methods like induced_metric. I understand that this was introduced to address the documentation issue related to @cached_method mentioned in comment:8. In the new setting, the caching is performed "manually", by checking whether the attribute self._first_fundamental_form is None or not, and the alias is properly defined as

extrinsic_curvature = second_fundamental_form

This avoids the duplication of doctests. As a result, the doctest time for the file pseudo_riemannian_submanifold.py decreases from 315 s to 248 s (on my computer). However this is still too much! A solution would be to replace most (all?) the sphere examples by simpler ones, like those for a cylinder, or even by those for a plane, in cases where they are not trivial (e.g. for the normal).

Another thing to do is to distinguish which methods are valid for a generic submanifold, like first_fundamental_form or projector, and those that are valid only for hypersurfaces, like second_fundamental_form or normal.

I am leaving the ticket status to "needs review" to catch the attention of the patchbot...

[egourgoulhon]

Now that one patchbot has done its job... (it's reporting only a failure of the commit_messages plugin, which looks a false report to me, since all commits involved in this ticket do have a commit message...)

[git]

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

​72abf0b	Small fix to help careless user
​ca13dd5	Merge with branch 'public/manifolds/submanifolds_calc' of git://trac.sagemath.org/sage
​b2fabf7	Reduce doctest time to about 100s

[git]

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

​9477287

Raise exception when an hypersurface is needed, normal can now return a multivector

[egourgoulhon]

Thanks for the changes. LGTM. Thanks for this nice piece of work!