Opened 17 months ago

Closed 15 months ago

Last modified 15 months ago

#27703 closed enhancement (fixed)

Tutorial about vector calculus

Reported by: egourgoulhon Owned by:
Priority: major Milestone: sage-8.9
Component: documentation Keywords: vector calculus, Euclidean space
Cc: mforets, kcrisman, tscrim Merged in:
Authors: Eric Gourgoulhon Reviewers: Travis Scrimshaw
Report Upstream: N/A Work issues:
Branch: 5c8bb2f (Commits) Commit: 5c8bb2f59bb9cf65d76e74ad649342fbbc160be1
Dependencies: Stopgaps:

Description (last modified by egourgoulhon)

This ticket adds a new tutorial regarding vector calculus in Euclidean spaces, in the Thematic Tutorials section of the documentation.

The tutorial is divived in five parts. The first one regards vector calculus in the 3-dimensional Euclidean space E3 in Cartesian coordinates, focusing on the evaluation of the standard vector operators. The second tutorial deals with the same topic but based on curvilinear (spherical and cylindrical) coordinates. The third tutorial is devoted to changes between the various coordinate systems. The fourth tutorial presents some advanced aspects, namely the treatment of E3 as a Riemannian manifold. Finally, the last tutorial is devoted to 2-dimensional vector calculus, using both Cartesian and polar coordinates in the Euclidean plane E2 ; it combines various features of the other tutorials.

A preview of the tutorial is available here.

Change History (19)

comment:1 Changed 17 months ago by egourgoulhon

  • Branch set to public/manifolds/tutorial_vector_calculus
  • Commit set to 91a721b23824c199602257ad914cf93b53e47fb3

New commits:

6f84452First draft of the vector calcululus tutorial
9c9bc95Add tutorial on vector calculus in cylindrical coordinates
7b47a74Add two more vector calculus tutorials
d298749Add nbviewer and binder links in vector calculus tutorial
b4afeb6Small improvements in the vector calculus tutorial
91a721bA py3 fix in the Euclidean plane tutorial

comment:2 Changed 17 months ago by egourgoulhon

  • Cc mforets kcrisman tscrim added
  • Status changed from new to needs_review

comment:3 Changed 17 months ago by egourgoulhon

  • Description modified (diff)

comment:4 follow-up: Changed 17 months ago by tscrim

So I would say the "What's next" sections are unnecessary considering the table of contents and the next links.

I think it would be good to have some more pictures in part 4, in particular, showing how the two coordinate systems interact.

Do you want to talk at all about integration along curves or determining geodesics?

How difficult would it be to add another tutorial discussing things on a (2D) torus? I think a slightly more non-trivial example than R3 would be beneficial.

Actually, overall I felt that there was no message being conveyed. Just the tutorial outlining what things you can do, rather than, say, trying to answer a particular question. I do think it is useful to have one tutorial about the things you can do on a particular object, but I think given the code samples already in the docstrings, this is not currently saying much more. Perhaps what I am suggesting is to think of this as something you would point a new student/researcher to who did not know the theory as a way to give them a starting point.

comment:5 in reply to: ↑ 4 Changed 17 months ago by egourgoulhon

Replying to tscrim:

So I would say the "What's next" sections are unnecessary considering the table of contents and the next links.

OK, I'll remove them.

I think it would be good to have some more pictures in part 4, in particular, showing how the two coordinate systems interact.

OK.

Do you want to talk at all about integration along curves or determining geodesics?

I think this is out of the scope of this tutorial, which is elementary vector calculus, in the meaning of https://en.wikipedia.org/wiki/Vector_calculus

How difficult would it be to add another tutorial discussing things on a (2D) torus? I think a slightly more non-trivial example than R3 would be beneficial.

This would certainly be interesting but in a separate tutorial. Again, the present one is devoted to elementary vector calculus (probably this should be stressed in the introduction to the tutorial), for which the arena is E3.

Actually, overall I felt that there was no message being conveyed. Just the tutorial outlining what things you can do, rather than, say, trying to answer a particular question.

Agreed. This tutorial presents some tools and is not answering to any precise mathematical question.

I do think it is useful to have one tutorial about the things you can do on a particular object, but I think given the code samples already in the docstrings, this is not currently saying much more.

Agreed. All the information in the tutorial is already in the reference manual, but scattered over various places. For instance, many methods are described in the manifold section or in the tensor field one, not in the vector field section. I have the feeling that a newcomer to Sage will first jump on tutorials rather than explore the reference manual.

Perhaps what I am suggesting is to think of this as something you would point a new student/researcher to who did not know the theory as a way to give them a starting point.

Indeed, this tutorial assumes the reader knows already about Euclidean spaces and elementary vector calculus. It is not an introduction to the subject, but to the vector calculus tools available in Sage.

Last edited 17 months ago by egourgoulhon (previous) (diff)

comment:6 follow-up: Changed 17 months ago by tscrim

I think it would be nice to at least frame parts of the tutorial as answering a question (i.e., how can this be used). For instance, I like the divergence, curl, and Laplacian because they show that you can verify (important) identities. In some ways, having just one tutorial that does these things for one, maybe two, coordinate systems seems sufficient, as well as part 4 to change between the coordinates.

I know a lot of this is bikeshedding, and I think these tutorials are a good addition (I probably should add a few for my research stuff). I might be too bias/subborn about what I think a good tutorial will have. (I can cc you on any tutorials I do so you can tell me how hypocritical I am ;)).

comment:7 in reply to: ↑ 6 Changed 17 months ago by egourgoulhon

Replying to tscrim:

I think it would be nice to at least frame parts of the tutorial as answering a question (i.e., how can this be used). For instance, I like the divergence, curl, and Laplacian because they show that you can verify (important) identities. In some ways, having just one tutorial that does these things for one, maybe two, coordinate systems seems sufficient, as well as part 4 to change between the coordinates.

OK I see your point. I'll try to reformulate things as questions as much as possible. I don't have time to it now, though...

I know a lot of this is bikeshedding, and I think these tutorials are a good addition (I probably should add a few for my research stuff). I might be too bias/subborn about what I think a good tutorial will have. (I can cc you on any tutorials I do so you can tell me how hypocritical I am ;)).

No problem, your criticism is always constructive.

comment:8 Changed 16 months ago by egourgoulhon

  • Status changed from needs_review to needs_work

comment:9 Changed 16 months ago by git

  • Commit changed from 91a721b23824c199602257ad914cf93b53e47fb3 to 153ecadc068d40e3ac8555fc37f94468e9d7ed88

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

4af2f7dMerge branch 'public/manifolds/tutorial_vector_calculus' of git://trac.sagemath.org/sage into Sage 8.8.beta6.
153ecadStart rewriting the vector calculus tutorial in question form

comment:10 Changed 16 months ago by git

  • Commit changed from 153ecadc068d40e3ac8555fc37f94468e9d7ed88 to 17a57edfbdd33ae008f889698d5f87bfef6381ee

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

feaeb31Complete tutorial on vector calculus in curvilinear coordinates
17a57edAdd plots in the tutorial about coordinate changes

comment:11 Changed 16 months ago by git

  • Commit changed from 17a57edfbdd33ae008f889698d5f87bfef6381ee to 7ad4de5363621bc11f7bdeb1c1f41bc395594313

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

7ad4de5Changes in two vector calculus tutorials (change of coordinates and advanced aspects)

comment:12 Changed 16 months ago by git

  • Commit changed from 7ad4de5363621bc11f7bdeb1c1f41bc395594313 to ce92e4c1bd975a977c540fa0c985815206898c48

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

ce92e4cMinor changes in the vector calculus tutorials

comment:13 Changed 16 months ago by egourgoulhon

  • Description modified (diff)
  • Status changed from needs_work to needs_review

I have modified the tutorial according to your recommendations (comment:4 and comment:6). The various topics are now introduced as questions that the reader may ask (in the first three tutorials). I have merged the previous tutorials 2 (spherical coord.) and 3 (cylindrical coord.) into a single document (curvilinear coord.). I have added some plots illustrating the link between spherical and Cartesian coordinates in the third document (previously no. 4). I kept the tutorial about advanced topics in the same shape, performing only minor changes, because I did not feel putting it in the "How to" flavor. Same thing for the last document, which recaps all the previous ones, but in the 2-dimensional case.

The preview has been updated to the new version.

Last edited 16 months ago by egourgoulhon (previous) (diff)

comment:14 follow-up: Changed 16 months ago by tscrim

Thank you. I think it is looking much better. There are just a few minor points below to address:

A point on linking. Anything that is in the global namespace can be linked, so you can do :func:EuclideanSpace(). For other things you want to have explicitly linked, you can use the :foo:~sage.path.to.object.Bar. However, I would not do this for the methods like display()`.

You do not need the :math: here either. (In fact, I am not sure there are any of these left in the library codebase.)

You can compactify the source a little, which IMO is easier to read:

-Let us denote by ``cartesian`` the chart of Cartesian coordinates:
-
-::
+Let us denote by ``cartesian`` the chart of Cartesian coordinates::

A minor grammatical point: The topic names are good, but they are not strictly questions. It is more of they are answering a question, and subsequently should not have a question mark ?. (I know that it is correct to ask questions in this way, but it comes across as very awkward to me as a native (American) English speaker.)

comment:15 Changed 16 months ago by git

  • Commit changed from ce92e4c1bd975a977c540fa0c985815206898c48 to 5c8bb2f59bb9cf65d76e74ad649342fbbc160be1

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

5c8bb2fAdding links and polishing the vector calculus tutorial

comment:16 in reply to: ↑ 14 Changed 16 months ago by egourgoulhon

Replying to tscrim:

A point on linking. Anything that is in the global namespace can be linked, so you can do :func:EuclideanSpace(). For other things you want to have explicitly linked, you can use the :foo:~sage.path.to.object.Bar. However, I would not do this for the methods like display()`.

Thanks for pointing this. I've added the links.

You do not need the :math: here either. (In fact, I am not sure there are any of these left in the library codebase.)

Yes I know. Actually, these :math: have been automatically generated by the export to reST of the Jupyter notebooks from which I started. I've suppressed them in the commit above.

You can compactify the source a little, which IMO is easier to read:

-Let us denote by ``cartesian`` the chart of Cartesian coordinates:
-
-::
+Let us denote by ``cartesian`` the chart of Cartesian coordinates::

Again, this placement of :: was generated by the reST export of Jupyter. I've replaced it with the standard end-of-text version.

A minor grammatical point: The topic names are good, but they are not strictly questions. It is more of they are answering a question, and subsequently should not have a question mark ?. (I know that it is correct to ask questions in this way, but it comes across as very awkward to me as a native (American) English speaker.)

Done in the above commit.

I've also made some minor corrections and have updated the preview.

comment:17 Changed 15 months ago by egourgoulhon

  • Reviewers set to Travis Scrimshaw
  • Status changed from needs_review to positive_review

Travis checked this with me.

comment:18 Changed 15 months ago by vbraun

  • Branch changed from public/manifolds/tutorial_vector_calculus to 5c8bb2f59bb9cf65d76e74ad649342fbbc160be1
  • Resolution set to fixed
  • Status changed from positive_review to closed

comment:19 Changed 15 months ago by embray

  • Milestone changed from sage-8.8 to sage-8.9

Not in Sage 8.8. Let's please to try keep tickets' milestones related to the release in which we actually intend to include them, and in particular the release in which they were actually included, especially when closing tickets.

Note: See TracTickets for help on using tickets.