Sage: Ticket #27703: Tutorial about vector calculus
https://trac.sagemath.org/ticket/27703
<p>
This ticket adds a new tutorial regarding vector calculus in Euclidean spaces, in the <em>Thematic Tutorials</em> section of the documentation.
</p>
<p>
The tutorial is divived in five parts. The first one regards
vector calculus in the 3dimensional Euclidean space <strong>E</strong><sup>3</sup> 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 <strong>E</strong><sup>3</sup> as a Riemannian manifold. Finally, the last tutorial is devoted to 2dimensional vector calculus, using both Cartesian and polar coordinates in the
Euclidean plane <strong>E</strong><sup>2</sup> ; it combines various features of the other tutorials.
</p>
<p>
A preview of the tutorial is available <a class="extlink" href="https://sagemanifolds.obspm.fr/preview/thematic_tutorials/vector_calculus.html"><span class="icon"></span>here</a>.
</p>
enusSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/27703
Trac 1.1.6egourgoulhonFri, 19 Apr 2019 11:26:05 GMTcommit, branch set
https://trac.sagemath.org/ticket/27703#comment:1
https://trac.sagemath.org/ticket/27703#comment:1
<ul>
<li><strong>commit</strong>
set to <em>91a721b23824c199602257ad914cf93b53e47fb3</em>
</li>
<li><strong>branch</strong>
set to <em>public/manifolds/tutorial_vector_calculus</em>
</li>
</ul>
<p>
New commits:
</p>
<table class="wiki">
<tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit?id=6f844527f1ae62b9166f32cecbcaf32805f6a3c8"><span class="icon"></span>6f84452</a></td><td><code>First draft of the vector calcululus tutorial</code>
</td></tr><tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit?id=9c9bc9580b8089567ca05978c51c78fcb949cd12"><span class="icon"></span>9c9bc95</a></td><td><code>Add tutorial on vector calculus in cylindrical coordinates</code>
</td></tr><tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit?id=7b47a74f8189d007c6f7f394a4e55c3033ac4662"><span class="icon"></span>7b47a74</a></td><td><code>Add two more vector calculus tutorials</code>
</td></tr><tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit?id=d298749eae0830a34639a2ad2d8b88d653364e55"><span class="icon"></span>d298749</a></td><td><code>Add nbviewer and binder links in vector calculus tutorial</code>
</td></tr><tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit?id=b4afeb6c539c1b8f45c6cb41288e6f836087f96e"><span class="icon"></span>b4afeb6</a></td><td><code>Small improvements in the vector calculus tutorial</code>
</td></tr><tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit?id=91a721b23824c199602257ad914cf93b53e47fb3"><span class="icon"></span>91a721b</a></td><td><code>A py3 fix in the Euclidean plane tutorial</code>
</td></tr></table>
TicketegourgoulhonFri, 19 Apr 2019 11:29:18 GMTstatus changed; cc set
https://trac.sagemath.org/ticket/27703#comment:2
https://trac.sagemath.org/ticket/27703#comment:2
<ul>
<li><strong>cc</strong>
<em>mforets</em> <em>kcrisman</em> <em>tscrim</em> added
</li>
<li><strong>status</strong>
changed from <em>new</em> to <em>needs_review</em>
</li>
</ul>
TicketegourgoulhonFri, 19 Apr 2019 11:31:08 GMTdescription changed
https://trac.sagemath.org/ticket/27703#comment:3
https://trac.sagemath.org/ticket/27703#comment:3
<ul>
<li><strong>description</strong>
modified (<a href="/ticket/27703?action=diff&version=3">diff</a>)
</li>
</ul>
TickettscrimSat, 20 Apr 2019 07:55:45 GMT
https://trac.sagemath.org/ticket/27703#comment:4
https://trac.sagemath.org/ticket/27703#comment:4
<p>
So I would say the "What's next" sections are unnecessary considering the table of contents and the next links.
</p>
<p>
I think it would be good to have some more pictures in part 4, in particular, showing how the two coordinate systems interact.
</p>
<p>
Do you want to talk at all about integration along curves or determining geodesics?
</p>
<p>
How difficult would it be to add another tutorial discussing things on a (2D) torus? I think a slightly more nontrivial example than <strong>R</strong><sup>3</sup> would be beneficial.
</p>
<p>
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.
</p>
TicketegourgoulhonSat, 20 Apr 2019 10:34:21 GMT
https://trac.sagemath.org/ticket/27703#comment:5
https://trac.sagemath.org/ticket/27703#comment:5
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/27703#comment:4" title="Comment 4">tscrim</a>:
</p>
<blockquote class="citation">
<p>
So I would say the "What's next" sections are unnecessary considering the table of contents and the next links.
</p>
</blockquote>
<p>
OK, I'll remove them.
</p>
<blockquote class="citation">
<p>
I think it would be good to have some more pictures in part 4, in particular, showing how the two coordinate systems interact.
</p>
</blockquote>
<p>
OK.
</p>
<blockquote class="citation">
<p>
Do you want to talk at all about integration along curves or determining geodesics?
</p>
</blockquote>
<p>
I think this is out of the scope of this tutorial, which is <em>elementary</em> vector calculus, in the meaning of <a class="extlink" href="https://en.wikipedia.org/wiki/Vector_calculus"><span class="icon"></span>https://en.wikipedia.org/wiki/Vector_calculus</a>
</p>
<blockquote class="citation">
<p>
How difficult would it be to add another tutorial discussing things on a (2D) torus? I think a slightly more nontrivial example than <strong>R</strong><sup>3</sup> would be beneficial.
</p>
</blockquote>
<p>
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 <strong>E</strong><sup>3</sup>.
</p>
<blockquote class="citation">
<p>
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.
</p>
</blockquote>
<p>
Agreed. This tutorial presents some tools and is not answering to any precise mathematical question.
</p>
<blockquote class="citation">
<p>
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.
</p>
</blockquote>
<p>
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.
</p>
<blockquote class="citation">
<p>
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.
</p>
</blockquote>
<p>
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.
</p>
TickettscrimSat, 20 Apr 2019 23:52:26 GMT
https://trac.sagemath.org/ticket/27703#comment:6
https://trac.sagemath.org/ticket/27703#comment:6
<p>
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.
</p>
<p>
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 <code>;)</code>).
</p>
TicketegourgoulhonTue, 23 Apr 2019 06:43:17 GMT
https://trac.sagemath.org/ticket/27703#comment:7
https://trac.sagemath.org/ticket/27703#comment:7
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/27703#comment:6" title="Comment 6">tscrim</a>:
</p>
<blockquote class="citation">
<p>
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.
</p>
</blockquote>
<p>
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...
</p>
<blockquote class="citation">
<p>
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 <code>;)</code>).
</p>
</blockquote>
<p>
No problem, your criticism is always constructive.
</p>
TicketegourgoulhonTue, 28 May 2019 15:46:33 GMTstatus changed
https://trac.sagemath.org/ticket/27703#comment:8
https://trac.sagemath.org/ticket/27703#comment:8
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>needs_work</em>
</li>
</ul>
TicketgitTue, 28 May 2019 15:46:48 GMTcommit changed
https://trac.sagemath.org/ticket/27703#comment:9
https://trac.sagemath.org/ticket/27703#comment:9
<ul>
<li><strong>commit</strong>
changed from <em>91a721b23824c199602257ad914cf93b53e47fb3</em> to <em>153ecadc068d40e3ac8555fc37f94468e9d7ed88</em>
</li>
</ul>
<p>
Branch pushed to git repo; I updated commit sha1. New commits:
</p>
<table class="wiki">
<tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit/?id=4af2f7dbfecc3d236ee03fbf83589d1ef722c318"><span class="icon"></span>4af2f7d</a></td><td><code>Merge branch 'public/manifolds/tutorial_vector_calculus' of git://trac.sagemath.org/sage into Sage 8.8.beta6.</code>
</td></tr><tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit/?id=153ecadc068d40e3ac8555fc37f94468e9d7ed88"><span class="icon"></span>153ecad</a></td><td><code>Start rewriting the vector calculus tutorial in question form</code>
</td></tr></table>
TicketgitWed, 29 May 2019 15:26:36 GMTcommit changed
https://trac.sagemath.org/ticket/27703#comment:10
https://trac.sagemath.org/ticket/27703#comment:10
<ul>
<li><strong>commit</strong>
changed from <em>153ecadc068d40e3ac8555fc37f94468e9d7ed88</em> to <em>17a57edfbdd33ae008f889698d5f87bfef6381ee</em>
</li>
</ul>
<p>
Branch pushed to git repo; I updated commit sha1. New commits:
</p>
<table class="wiki">
<tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit/?id=feaeb31e08366adbe0f74678932bb19098b3fe67"><span class="icon"></span>feaeb31</a></td><td><code>Complete tutorial on vector calculus in curvilinear coordinates</code>
</td></tr><tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit/?id=17a57edfbdd33ae008f889698d5f87bfef6381ee"><span class="icon"></span>17a57ed</a></td><td><code>Add plots in the tutorial about coordinate changes</code>
</td></tr></table>
TicketgitWed, 29 May 2019 21:43:15 GMTcommit changed
https://trac.sagemath.org/ticket/27703#comment:11
https://trac.sagemath.org/ticket/27703#comment:11
<ul>
<li><strong>commit</strong>
changed from <em>17a57edfbdd33ae008f889698d5f87bfef6381ee</em> to <em>7ad4de5363621bc11f7bdeb1c1f41bc395594313</em>
</li>
</ul>
<p>
Branch pushed to git repo; I updated commit sha1. New commits:
</p>
<table class="wiki">
<tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit/?id=7ad4de5363621bc11f7bdeb1c1f41bc395594313"><span class="icon"></span>7ad4de5</a></td><td><code>Changes in two vector calculus tutorials (change of coordinates and advanced aspects)</code>
</td></tr></table>
TicketgitThu, 30 May 2019 19:13:10 GMTcommit changed
https://trac.sagemath.org/ticket/27703#comment:12
https://trac.sagemath.org/ticket/27703#comment:12
<ul>
<li><strong>commit</strong>
changed from <em>7ad4de5363621bc11f7bdeb1c1f41bc395594313</em> to <em>ce92e4c1bd975a977c540fa0c985815206898c48</em>
</li>
</ul>
<p>
Branch pushed to git repo; I updated commit sha1. New commits:
</p>
<table class="wiki">
<tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit/?id=ce92e4c1bd975a977c540fa0c985815206898c48"><span class="icon"></span>ce92e4c</a></td><td><code>Minor changes in the vector calculus tutorials</code>
</td></tr></table>
TicketegourgoulhonThu, 30 May 2019 19:52:42 GMTstatus, description changed
https://trac.sagemath.org/ticket/27703#comment:13
https://trac.sagemath.org/ticket/27703#comment:13
<ul>
<li><strong>status</strong>
changed from <em>needs_work</em> to <em>needs_review</em>
</li>
<li><strong>description</strong>
modified (<a href="/ticket/27703?action=diff&version=13">diff</a>)
</li>
</ul>
<p>
I have modified the tutorial according to your recommendations (<a class="ticket" href="https://trac.sagemath.org/ticket/27703#comment:4" title="Comment 4">comment:4</a> and <a class="ticket" href="https://trac.sagemath.org/ticket/27703#comment:6" title="Comment 6">comment:6</a>). 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.
</p>
<p>
The <a class="extlink" href="https://sagemanifolds.obspm.fr/preview/thematic_tutorials/vector_calculus.html"><span class="icon"></span>preview</a> has been updated to the new version.
</p>
TickettscrimFri, 31 May 2019 00:42:25 GMT
https://trac.sagemath.org/ticket/27703#comment:14
https://trac.sagemath.org/ticket/27703#comment:14
<p>
Thank you. I think it is looking much better. There are just a few minor points below to address:
</p>
<p>
A point on linking. Anything that is in the global namespace can be linked, so you can do :func:<code>EuclideanSpace()</code>. For other things you want to have explicitly linked, you can use the <code>:foo:</code>~sage.path.to.object.Bar<code>. However, I would not do this for the methods like </code>display()`.
</p>
<p>
You do not need the <code>:math:</code> here either. (In fact, I am not sure there are any of these left in the library codebase.)
</p>
<p>
You can compactify the source a little, which IMO is easier to read:
</p>
<div class="wikicode"><div class="code"><pre><span class="gd">Let us denote by ``cartesian`` the chart of Cartesian coordinates:

::
</span><span class="gi">+Let us denote by ``cartesian`` the chart of Cartesian coordinates::
</span></pre></div></div><p>
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 <code>?</code>. (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.)
</p>
TicketgitFri, 31 May 2019 15:08:58 GMTcommit changed
https://trac.sagemath.org/ticket/27703#comment:15
https://trac.sagemath.org/ticket/27703#comment:15
<ul>
<li><strong>commit</strong>
changed from <em>ce92e4c1bd975a977c540fa0c985815206898c48</em> to <em>5c8bb2f59bb9cf65d76e74ad649342fbbc160be1</em>
</li>
</ul>
<p>
Branch pushed to git repo; I updated commit sha1. New commits:
</p>
<table class="wiki">
<tr><td><a class="extlink" href="https://git.sagemath.org/sage.git/commit/?id=5c8bb2f59bb9cf65d76e74ad649342fbbc160be1"><span class="icon"></span>5c8bb2f</a></td><td><code>Adding links and polishing the vector calculus tutorial</code>
</td></tr></table>
TicketegourgoulhonFri, 31 May 2019 15:21:46 GMT
https://trac.sagemath.org/ticket/27703#comment:16
https://trac.sagemath.org/ticket/27703#comment:16
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/27703#comment:14" title="Comment 14">tscrim</a>:
</p>
<blockquote class="citation">
<p>
A point on linking. Anything that is in the global namespace can be linked, so you can do :func:<code>EuclideanSpace()</code>. For other things you want to have explicitly linked, you can use the <code>:foo:</code>~sage.path.to.object.Bar<code>. However, I would not do this for the methods like </code>display()`.
</p>
</blockquote>
<p>
Thanks for pointing this. I've added the links.
</p>
<blockquote class="citation">
<p>
You do not need the <code>:math:</code> here either. (In fact, I am not sure there are any of these left in the library codebase.)
</p>
</blockquote>
<p>
Yes I know. Actually, these <code>:math:</code> have been automatically generated by the export to <code>reST</code> of the Jupyter notebooks from which I started. I've suppressed them in the commit above.
</p>
<blockquote class="citation">
<p>
You can compactify the source a little, which IMO is easier to read:
</p>
<div class="wikicode"><div class="code"><pre><span class="gd">Let us denote by ``cartesian`` the chart of Cartesian coordinates:

::
</span><span class="gi">+Let us denote by ``cartesian`` the chart of Cartesian coordinates::
</span></pre></div></div></blockquote>
<p>
Again, this placement of <code>::</code> was generated by the <code>reST</code> export of Jupyter. I've replaced it with the standard endoftext version.
</p>
<blockquote class="citation">
<p>
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 <code>?</code>. (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.)
</p>
</blockquote>
<p>
Done in the above commit.
</p>
<p>
I've also made some minor corrections and have updated the <a class="extlink" href="https://sagemanifolds.obspm.fr/preview/thematic_tutorials/vector_calculus.html"><span class="icon"></span>preview</a>.
</p>
TicketegourgoulhonWed, 26 Jun 2019 09:07:01 GMTstatus changed; reviewer set
https://trac.sagemath.org/ticket/27703#comment:17
https://trac.sagemath.org/ticket/27703#comment:17
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>positive_review</em>
</li>
<li><strong>reviewer</strong>
set to <em>Travis Scrimshaw</em>
</li>
</ul>
<p>
Travis checked this with me.
</p>
TicketvbraunThu, 27 Jun 2019 20:13:35 GMTstatus, branch changed; resolution set
https://trac.sagemath.org/ticket/27703#comment:18
https://trac.sagemath.org/ticket/27703#comment:18
<ul>
<li><strong>status</strong>
changed from <em>positive_review</em> to <em>closed</em>
</li>
<li><strong>resolution</strong>
set to <em>fixed</em>
</li>
<li><strong>branch</strong>
changed from <em>public/manifolds/tutorial_vector_calculus</em> to <em>5c8bb2f59bb9cf65d76e74ad649342fbbc160be1</em>
</li>
</ul>
TicketembrayWed, 03 Jul 2019 11:34:48 GMTmilestone changed
https://trac.sagemath.org/ticket/27703#comment:19
https://trac.sagemath.org/ticket/27703#comment:19
<ul>
<li><strong>milestone</strong>
changed from <em>sage8.8</em> to <em>sage8.9</em>
</li>
</ul>
<p>
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 <em>actually</em> included, especially when closing tickets.
</p>
Ticket