#27703 closed enhancement (fixed)
Tutorial about vector calculus
Reported by:  egourgoulhon  Owned by:  

Priority:  major  Milestone:  sage8.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, GitHub, GitLab)  Commit:  5c8bb2f59bb9cf65d76e74ad649342fbbc160be1 
Dependencies:  Stopgaps: 
Description (last modified by )
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 3dimensional Euclidean space E^{3} 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 E^{3} as a Riemannian manifold. Finally, the last tutorial is devoted to 2dimensional vector calculus, using both Cartesian and polar coordinates in the Euclidean plane E^{2} ; it combines various features of the other tutorials.
A preview of the tutorial is available here.
Change History (19)
comment:1 Changed 2 years ago by
 Branch set to public/manifolds/tutorial_vector_calculus
 Commit set to 91a721b23824c199602257ad914cf93b53e47fb3
comment:2 Changed 2 years ago by
 Cc mforets kcrisman tscrim added
 Status changed from new to needs_review
comment:3 Changed 2 years ago by
 Description modified (diff)
comment:4 followup: ↓ 5 Changed 2 years ago by
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 nontrivial example than R^{3} 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 2 years ago by
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 nontrivial example than R^{3} 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 E^{3}.
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.
comment:6 followup: ↓ 7 Changed 2 years ago by
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 2 years ago by
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 2 years ago by
 Status changed from needs_review to needs_work
comment:9 Changed 2 years ago by
 Commit changed from 91a721b23824c199602257ad914cf93b53e47fb3 to 153ecadc068d40e3ac8555fc37f94468e9d7ed88
comment:10 Changed 2 years ago by
 Commit changed from 153ecadc068d40e3ac8555fc37f94468e9d7ed88 to 17a57edfbdd33ae008f889698d5f87bfef6381ee
comment:11 Changed 2 years ago by
 Commit changed from 17a57edfbdd33ae008f889698d5f87bfef6381ee to 7ad4de5363621bc11f7bdeb1c1f41bc395594313
Branch pushed to git repo; I updated commit sha1. New commits:
7ad4de5  Changes in two vector calculus tutorials (change of coordinates and advanced aspects)

comment:12 Changed 2 years ago by
 Commit changed from 7ad4de5363621bc11f7bdeb1c1f41bc395594313 to ce92e4c1bd975a977c540fa0c985815206898c48
Branch pushed to git repo; I updated commit sha1. New commits:
ce92e4c  Minor changes in the vector calculus tutorials

comment:13 Changed 2 years ago by
 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 2dimensional case.
The preview has been updated to the new version.
comment:14 followup: ↓ 16 Changed 2 years ago by
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 2 years ago by
 Commit changed from ce92e4c1bd975a977c540fa0c985815206898c48 to 5c8bb2f59bb9cf65d76e74ad649342fbbc160be1
Branch pushed to git repo; I updated commit sha1. New commits:
5c8bb2f  Adding links and polishing the vector calculus tutorial

comment:16 in reply to: ↑ 14 Changed 2 years ago by
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 endoftext 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 2 years ago by
 Reviewers set to Travis Scrimshaw
 Status changed from needs_review to positive_review
Travis checked this with me.
comment:18 Changed 2 years ago by
 Branch changed from public/manifolds/tutorial_vector_calculus to 5c8bb2f59bb9cf65d76e74ad649342fbbc160be1
 Resolution set to fixed
 Status changed from positive_review to closed
comment:19 Changed 2 years ago by
 Milestone changed from sage8.8 to sage8.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.
New commits:
First draft of the vector calcululus tutorial
Add tutorial on vector calculus in cylindrical coordinates
Add two more vector calculus tutorials
Add nbviewer and binder links in vector calculus tutorial
Small improvements in the vector calculus tutorial
A py3 fix in the Euclidean plane tutorial