Euclidean spaces and vector calculus

[egourgoulhon]

This ticket implements Euclidean spaces as Riemannian manifolds diffeomorphic to Rⁿ and equipped with a flat metric, which defines the Euclidean dot product. Using the operators introduced in #24622, this provides the standard operators of vector calculus: dot product, norm, cross product, gradient, divergence, curl and Laplacian, along with the standard coordinate systems (Cartesian, spherical, cylindrical, etc.).

See this ask.sagemath question for a motivation, as well as this one.

The implementation is performed via the parent class EuclideanSpace, which inherits from PseudoRiemannianManifold (introduced in #24622). Two subclasses are devoted to specific cases:

• EuclideanPlane for n=2
• Euclidean3dimSpace for n=3
  The user interface for constructing an Euclidean space relies on the EuclideanSpace.__classcall_private__ to direct to the appropriate subclass.

The implementation through the manifold framework allows for an easy use of various coordinate systems, along with the related transformations. However, the user interface does not assume any knowledge of Riemannian geometry. In particular, no direct manipulation of the metric tensor is required.

A minimal example is

sage: E.<x,y,z> = EuclideanSpace(3)
sage: v = E.vector_field(-y, x, 0)
sage: v.display()
-y e_x + x e_y
sage: v[:]
[-y, x, 0]
sage: w = v.curl()
sage: w.display()
2 e_z
sage: w[:]
[0, 0, 2]

The transformation to spherical coordinates:

sage: spherical.<r,th,ph> = E.spherical_coordinates()
sage: spherical_frame = E.spherical_frame()  # orthonormal frame (e_r, e_th, e_ph)
sage: v.display(spherical_frame)
sqrt(x^2 + y^2) e_ph
sage: v.display(spherical_frame, spherical)
r*sin(th) e_ph
sage: v[spherical_frame, :, spherical]
[0, 0, r*sin(th)]
sage: w.display(spherical_frame, spherical)
2*cos(th) e_r - 2*sin(th) e_th
sage: w[spherical_frame, :, spherical]
[2*cos(th), -2*sin(th), 0]

More detailed examples are in the following Jupyter notebooks:

• vector calculus in Cartesian coordinates
• vector calculus in spherical coordinates
• vector calculus in cylindrical coordinates
• changing coordinates in the Euclidean 3-space
• Advanced aspects: Euclidean spaces as Riemannian manifolds
• the Euclidean plane

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

Depends on #24622
Depends on #24792

CC: @sagetrac-tmonteil

Component: geometry

Keywords: Euclidean space, vector calculus, gradient, divergence, curl, Laplacian

Author: Eric Gourgoulhon

Branch: 220726c

Reviewer: Travis Scrimshaw

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

[egourgoulhon]

comment:4

This is a first sketch (not ready yet).

---

Last 10 new commits:

55f356c	Improve documentation of pseudo-Riemannian manifolds
0fc661a	Remove method set_metric and improve doc of pseudo-Riemannian manifolds
b4dddf7	Add operators Laplacian, d'Alembertian and curl on pseudo-Riemannian manifolds
040b01c	Add dot product and cross product of vector fields
46b8f66	Add norm of vector fields.
135af97	Add method volume_form() to class PseudoRiemannianManifold
38e8fd3	Add global functions grad, div, curl, etc. for vector/tensor operators on pseudo-Riemannian manifolds
8309fdd	Improve documentation for operators on pseudo-Riemannian manifolds
29fc5c8	Merge branch 'public/manifolds/pseudoRiemannian' of git://trac.sagemath.org/sage into Sage 8.2.beta5
4bf8020	First draft of Euclidean spaces as Riemannian manifolds

[egourgoulhon]

Commit: 4bf8020

[egourgoulhon]

Branch: public/manifolds/Euclidean_spaces

[egourgoulhon]

Changed dependencies from #24622 to #24622, #24792

[egourgoulhon]

comment:5

#24792 introduces more flexibility in naming the elements of vector frames, for instance using (e_x, e_y, e_z) for a coordinate frame instead of (d/dx, d/dy, d/dz). The current ticket will therefore be build on it for a better user interface.

[sagetrac-git]

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

a527e8e	First draft adding more flexibility in symbols of free module bases and vector frames
2d43a23	More refactoring in vector frames
0840d54	More work on vector frames
01681b8	Add documentation for new options of vector frames
f24a5f9	Merge branch 'public/manifolds/Euclidean_spaces' of git://trac.sagemath.org/sage into public/manifolds/more_basis_flexibility (branch of #24792)

[sagetrac-git]

Changed commit from 4bf8020 to f24a5f9

[sagetrac-git]

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

d9302b6

Add documentation and doctests for Euclidean spaces

[sagetrac-git]

Changed commit from f24a5f9 to d9302b6

[kcrisman]

comment:8

I wonder whether some of this (in terms of the div/grad/curl) could be exposed in the symbolic calculus places, at least with some well-placed and well-formed examples that would be understandable to someone teaching Calc III to engineers (in the US framework) who may not be a differential geometer.

[egourgoulhon]

comment:9

Replying to @kcrisman:

I wonder whether some of this (in terms of the div/grad/curl) could be exposed in the symbolic calculus places, at least with some well-placed and well-formed examples that would be understandable to someone teaching Calc III to engineers (in the US framework) who may not be a differential geometer.

Indeed, the aim here is to provide some interface which does not require any knowledge of differential geometry on manifolds. The class EuclideanSpaceGeneric does inherit from PseudoRiemannianManifold, but the end user has not to know it if he is not interested by this aspect and prefers to focus on vector calculus. Regarding examples, I plan to prepare some Jupyter notebooks and will expose them here, when the ticket is ready for review. Already, you can have a glimpse of the div/grad/curl capabilities introduced in the dependency #24622 in this notebook.

[kcrisman]

comment:10

That's great! The reason I brought it up is because folders like sage/calculus and sage/symbolic might benefit from some good examples that are easy to find.

Is there a way to use something like (say) vector([x<sup>2+y,y</sup>2+z,z^2+x]) as "vector field" immediately, without much (or any) of the formalism necessary in that notebook? I think that is how most end users I've talked to about this issue would want it. See e.g. https://ask.sagemath.org/question/10104/gradient-divergence-curl-and-vector-products/ and ticket:3021 for one version already in Sage - maybe these should be combined somehow, if possible.

[egourgoulhon]

comment:11

Replying to @kcrisman:

Is there a way to use something like (say) vector([x<sup>2+y,y</sup>2+z,z^2+x]) as "vector field" immediately, without much (or any) of the formalism necessary in that notebook?

Yes, this is precisely the aim of the current ticket. The above notebook is still at the level of semi-Riemannian manifolds (i.e. it illustrates only ticket #24622), while the user interface of the current ticket will be much simpler. It should also provide an easy way to change from Cartesian coordinates to e.g. polar or cylindrical ones.

See e.g. https://ask.sagemath.org/question/10104/gradient-divergence-curl-and-vector-products/ and ticket:3021 for one version already in Sage - maybe these should be combined somehow, if possible.

Thanks for pointing this version; I was not aware of it.

[sagetrac-git]

Changed commit from d9302b6 to 56a1a4a

[sagetrac-git]

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

9ddc467	Add method set_name to classes VectorFrame and CoFrame
82c37b4	Cut long lines in src/sage/manifolds/differentiable/vectorframe.py
95b2736	Merge branch 'public/manifolds/more_basis_flexibility' of git://trac.sagemath.org/sage into Euclidean (to get latest version of the dependency #24792)
56a1a4a	Add method vector_field to Euclidean spaces + internal changes regarding charts and frames

[sagetrac-git]

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

799066b	List entries of VectorFrame processed by __classcall_private__
da06d12	Small improvement in treatment of symbol attributes of free module bases
244c1f4	Merge branch 'public/manifolds/more_basis_flexibility' into 'public/manifolds/Euclidean_spaces' to get the latest version of dependency #24792 in #24623.
70a2a74	Vector fields on Euclidean spaces can be initialized from a vector of symbolic expressions

[sagetrac-git]

Changed commit from 56a1a4a to 70a2a74

[egourgoulhon]

comment:15

Here is some status update: functionalities regarding the 2-dimensional case are almost complete, as you can see in this demo worksheet (any feedback is of course appreciated). The 3-dimensional case is under preparation. The generic n-dimensional case, with n=1 or n>=4 is ready, since only Cartesian coordinates will be introduced (by default) in this case.

Regarding a question raised in comment:10, it is now possible to construct a vector field on an Euclidean space from a vector of symbolic expressions like this:

v = E.vector_field(vector([-y,x]))

where E is the underlying Euclidean space.

[sagetrac-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__
8367232	Merge branch 'public/manifolds/pseudoRiemannian' of git://trac.sagemath.org/sage into 'public/manifolds/Euclidean_spaces' to get the latest version of the dependency #24622 in #24623.
6e9fce6	First draft of Euclidean 3-spaces, with the Cartesian, spherical and cylindrical coordinate systems

[sagetrac-git]

Changed commit from 70a2a74 to 6e9fce6

[sagetrac-git]

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

825ba78

Add doctests to Euclidean spaces

[sagetrac-git]

Changed commit from 6e9fce6 to 825ba78

[sagetrac-git]

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

185e438	Improve documentation of pseudo-Riemannian manifolds
52b10ee	Merge branch 'public/manifolds/pseudoRiemannian' of git://trac.sagemath.org/sage into 'public/manifolds/Euclidean_spaces' to get the final version of the dependency #24622 in #24623.
88f12ed	Improve documentation of Euclidean spaces

[egourgoulhon]

comment:26

Replying to @kcrisman:

I wonder whether some of this (in terms of the div/grad/curl) could be exposed in the symbolic calculus places, at least with some well-placed and well-formed examples that would be understandable to someone teaching Calc III to engineers (in the US framework) who may not be a differential geometer.

I have added an entry "Vector Calculus" to src/doc/en/reference/calculus/index.rst. I have also added some SEEALSO sections in the definitions of curl and div in src/sage/modules/free_module_element.pyx, as well as in the definition of gradient in src/sage/symbolic/expression.pyx.

[sagetrac-git]

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

b821dac	Merge branch 'public/manifolds/Euclidean_spaces' of git://trac.sagemath.org/sage into public/manifolds/Euclidean_spaces
3578e5f	Fusing EuclideanSpace function with EuclideanSpaceGeneric plus other misc reviewer changes.

[sagetrac-git]

Changed commit from de74bb7 to 3578e5f

[sagetrac-git]

Changed commit from 3578e5f to ab249df

[sagetrac-git]

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

ab249df

Fusing EuclideanSpace function with EuclideanSpaceGeneric plus other misc reviewer changes.

[tscrim]

comment:31

Okay, I have made my way through the code. Overall, it looks good.

I remove the function EuclideanSpace and just used the __classcall_private__ mechanism (provided by UniqueRepresentation) to make the class EuclideanSpace (formerly EuclideanSpaceGeneric) the main entry point.

There is something very subtle happening as some of the doctest output for display names of arctan2(y, x) needed to be arctan(y/x). I do not understand why nor could I see what was causing this. It is not a blocker issue, but it is an indication that something might not be working properly.

The rest of my changes were mostly cosmetic.

[tscrim]

Reviewer: Travis Scrimshaw

[egourgoulhon]

comment:32

Replying to @tscrim:

Okay, I have made my way through the code. Overall, it looks good.

Thanks a lot for looking into this.

I remove the function EuclideanSpace and just used the __classcall_private__ mechanism (provided by UniqueRepresentation) to make the class EuclideanSpace (formerly EuclideanSpaceGeneric) the main entry point.

This is a nice improvement, thanks!

There is something very subtle happening as some of the doctest output for display names of arctan2(y, x) needed to be arctan(y/x). I do not understand why nor could I see what was causing this. It is not a blocker issue, but it is an indication that something might not be working properly.

Indeed; I will look into this...

The rest of my changes were mostly cosmetic.

Thanks for all of them.

[tscrim]

comment:33

I should also say that if you approve of my changes, then you can set a positive review.

(Unfortunately, a number of the doctests are just slow because of feeding calls off to Maxima and the simplifications. Although I don't think there is anything we can do about that.)

[sagetrac-git]

Changed commit from ab249df to 220726c

[sagetrac-git]

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

654b0aa	Merge branch 'public/manifolds/Euclidean_spaces' of git://trac.sagemath.org/sage into Sage 8.2.rc4
220726c	A few minor changes in doctests of Euclidean spaces

[egourgoulhon]

comment:35

The above commit fixes the arctan issue mentioned in comment:31: it was due to the declaration

sage: E3.<x,t,p> = EuclideanSpace(coordinates='spherical')

in line 591 of euclidean.py, which had the side effect of adding x>0 to Sage's assumptions. Then subsequent doctests involving arctan2(y, x) automatically replaced it by arctan(y/x). I changed the variable x to r in the declaration of E3 (which btw fits better with standard notation for spherical coordinates) and everything was OK, i.e. all arctan2(y, x) could be restored.

Moreover, since it is now possible to skip the dimension as first argument of EuclideanSpace in constructions of the type E.<x,y> = EuclideanSpace() (thank you for this improvement!), I systematically removed the dimension argument and added a sentence in the documentation about this.

I also took the opportunity of this commit to add a single-line fix of a (small) bug in src/sage/manifolds/differentiable/vectorfield_module.py revealed after the dependency ticket #24792 was merged. I hope you do not mind.

[tscrim]

comment:36

Yep, LGTM. Thank you for tracking that down.

[egourgoulhon]

comment:37

Replying to @tscrim:

Yep, LGTM. Thank you for tracking that down.

Thank you very much for the review, and the associated improvements in the code!

[vbraun]

Changed branch from public/manifolds/Euclidean_spaces to 220726c

[slel]

Changed commit from 220726c to none

[slel]

comment:39

Merged in Sage 8.3.beta0.