Sage: Ticket #8825: Improve documentation for function norm
https://trac.sagemath.org/ticket/8825
<p>
The documentation for the function norm currently does not mention that different kinds of norms are used for complex numbers and vectors of complex numbers.
</p>
<p>
I was very surprised that for a complex number z,
norm(z) == norm(vector([z]))<sup>2</sup>, and no hint of this is available from the documentation available through executing "sage: norm?".
</p>
<p>
See this <a class="ext-link" href="http://groups.google.com/group/sage-devel/browse_thread/thread/9f941378a95c0191"><span class="icon"></span>sage-devel</a> thread for some background information.
</p>
<p>
Apply patches in this order:
</p>
<ol><li><a class="closed ticket" href="https://trac.sagemath.org/ticket/8819" title="defect: warnings in building documentation of Sage 4.4.2.alpha0 (closed: fixed)">#8819</a>
</li><li><a class="closed ticket" href="https://trac.sagemath.org/ticket/8831" title="defect: fail to build PDF version of reference manual in Sage 4.4.1.alpha2 (closed: fixed)">#8831</a>
</li><li><a class="ext-link" href="http://trac.sagemath.org/sage_trac/attachment/ticket/8825/trac_8825_norm_docstring.patch"><span class="icon"></span>trac_8825_norm_docstring.patch</a>
</li><li><a class="ext-link" href="http://trac.sagemath.org/sage_trac/attachment/ticket/8825/trac_8825-more-norm-doc.patch"><span class="icon"></span>trac_8825-more-norm-doc.patch</a>
</li></ol>en-usSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/8825
Trac 1.1.6johanThu, 29 Apr 2010 19:58:30 GMTattachment set
https://trac.sagemath.org/ticket/8825
https://trac.sagemath.org/ticket/8825
<ul>
<li><strong>attachment</strong>
set to <em>trac_8825_norm_docstring.patch</em>
</li>
</ul>
<p>
Patch
</p>
TicketmvnguThu, 29 Apr 2010 20:05:21 GMTstatus, component, description changed; milestone, author set
https://trac.sagemath.org/ticket/8825#comment:1
https://trac.sagemath.org/ticket/8825#comment:1
<ul>
<li><strong>status</strong>
changed from <em>new</em> to <em>needs_review</em>
</li>
<li><strong>milestone</strong>
set to <em>sage-4.4.1</em>
</li>
<li><strong>component</strong>
changed from <em>misc</em> to <em>documentation</em>
</li>
<li><strong>description</strong>
modified (<a href="/ticket/8825?action=diff&version=1">diff</a>)
</li>
<li><strong>author</strong>
set to <em>Johan Grönqvist</em>
</li>
</ul>
TicketmvnguFri, 30 Apr 2010 20:47:41 GMTdescription, author changed; reviewer set
https://trac.sagemath.org/ticket/8825#comment:2
https://trac.sagemath.org/ticket/8825#comment:2
<ul>
<li><strong>reviewer</strong>
set to <em>Minh Van Nguyen</em>
</li>
<li><strong>description</strong>
modified (<a href="/ticket/8825?action=diff&version=2">diff</a>)
</li>
<li><strong>author</strong>
changed from <em>Johan Grönqvist</em> to <em>Johan Grönqvist, Minh Van Nguyen</em>
</li>
</ul>
<p>
I'm happy with the patch <a class="ext-link" href="http://trac.sagemath.org/sage_trac/attachment/ticket/8825/trac_8825_norm_docstring.patch"><span class="icon"></span>trac_8825_norm_docstring.patch</a>. To prevent further confusion regarding how the norm function is defined for various objects, I have added more documentation for various norm functions. The new documentation also cross references between norm functions. So only my patch <a class="ext-link" href="http://trac.sagemath.org/sage_trac/attachment/ticket/8825/trac_8825-more-norm-doc.patch"><span class="icon"></span>trac_8825-more-norm-doc.patch</a> needs review by anyone but me. If it gets a positive review, the whole ticket is good to go.
</p>
TicketpangWed, 12 May 2010 08:36:33 GMTattachment set
https://trac.sagemath.org/ticket/8825
https://trac.sagemath.org/ticket/8825
<ul>
<li><strong>attachment</strong>
set to <em>weirddoc.png</em>
</li>
</ul>
TicketpangWed, 12 May 2010 08:45:54 GMT
https://trac.sagemath.org/ticket/8825#comment:3
https://trac.sagemath.org/ticket/8825#comment:3
<p>
I've attached a screen capture: the norm reads |*v*| in the notebook (norm?). However, if I read:
</p>
<p>
$SAGE_ROOT/devel/sage/doc/output/html/en/reference/sage/misc/functional.html
</p>
<p>
it looks fine.
</p>
TicketpangWed, 12 May 2010 08:54:52 GMT
https://trac.sagemath.org/ticket/8825#comment:4
https://trac.sagemath.org/ticket/8825#comment:4
<p>
Another comment: when read in the notebook, it says:
</p>
<pre class="wiki">See also
* norm – the p -norm of a matrix.
* norm – the p -norm of a vector.
* norm – the norm of a double precision complex number.
* norm – the norm of an arbitrary precision complex number.
* norm – the complex norm of a symbolic expression.
</pre><p>
which is confusing. Maybe instead of norm it could say sage.matrix.matrix2.Matrix.norm, etcetera. A cool possibility would be to put hyperlinks, but this would probably interfere with the automatic generation of doc, wouldn't it?
</p>
TicketmhansenSun, 06 Jun 2010 20:20:44 GMT
https://trac.sagemath.org/ticket/8825#comment:5
https://trac.sagemath.org/ticket/8825#comment:5
<p>
Nope, you can put in autogenerated hyperlinks. For example, the markup
</p>
<pre class="wiki">:meth:`sage.matrix.matrix2.Matrix.norm`
</pre><p>
would change to a link to that method.
</p>
TicketmvnguTue, 15 Jun 2010 04:22:25 GMTattachment set
https://trac.sagemath.org/ticket/8825
https://trac.sagemath.org/ticket/8825
<ul>
<li><strong>attachment</strong>
set to <em>trac_8825-more-norm-doc.patch</em>
</li>
</ul>
TicketmvnguTue, 15 Jun 2010 04:24:29 GMT
https://trac.sagemath.org/ticket/8825#comment:6
https://trac.sagemath.org/ticket/8825#comment:6
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/8825#comment:4" title="Comment 4">pang</a>:
</p>
<blockquote class="citation">
<p>
Maybe instead of norm it could say sage.matrix.matrix2.Matrix.norm, etcetera.
</p>
</blockquote>
<p>
My updated patch takes care of this. As for the weirdness in the notebook, I don't know how to fix that.
</p>
TicketdrkirkbyTue, 21 Sep 2010 09:26:55 GMT
https://trac.sagemath.org/ticket/8825#comment:7
https://trac.sagemath.org/ticket/8825#comment:7
<p>
See my suggestion on <a class="ext-link" href="http://groups.google.com/group/sage-devel/browse_thread/thread/2e10a6e35237c87e?hl=en"><span class="icon"></span>sage-devel</a>. I personally think it would useful to also add
</p>
<p>
1) External links to Mathworld and Wikipedia
</p>
<ul><li><a class="ext-link" href="http://en.wikipedia.org/wiki/Matrix_norm"><span class="icon"></span>http://en.wikipedia.org/wiki/Matrix_norm</a>
</li><li><a class="ext-link" href="http://mathworld.wolfram.com/Norm.html"><span class="icon"></span>http://mathworld.wolfram.com/Norm.html</a>
</li><li><a class="ext-link" href="http://mathworld.wolfram.com/MatrixNorm.html"><span class="icon"></span>http://mathworld.wolfram.com/MatrixNorm.html</a>
</li><li><a class="ext-link" href="http://mathworld.wolfram.com/VectorNorm.html"><span class="icon"></span>http://mathworld.wolfram.com/VectorNorm.html</a>
</li></ul><p>
These would certainly help people like me, who are not mathmaticians and might want to find out a bit more about a topic.
</p>
<p>
2) Document the nearest Mathematica, Maple, MATLAB and Macsyma commands when possible.
</p>
<p>
For Mathematica, it is Norm[] See:
</p>
<p>
<a class="ext-link" href="http://reference.wolfram.com/mathematica/ref/Norm.html"><span class="icon"></span>http://reference.wolfram.com/mathematica/ref/Norm.html</a>
</p>
<p>
For MATLAB it is norm()
</p>
<p>
<a class="ext-link" href="http://www.mathworks.com/help/techdoc/ref/norm.html"><span class="icon"></span>http://www.mathworks.com/help/techdoc/ref/norm.html</a>
</p>
<p>
I'm not sure about Maple - but Norm() might be the right one.
</p>
<p>
<a class="ext-link" href="http://www.maplesoft.com/support/help/Maple/view.aspx?path=VectorCalculus%2fNorm"><span class="icon"></span>http://www.maplesoft.com/support/help/Maple/view.aspx?path=VectorCalculus%2fNorm</a>
</p>
<p>
(Please check <strong>all<em> these - I'm not a mathematician).
</em></strong></p>
<p>
Having a list of the nearest equivalent commands in the commercial packages would be useful if we ever provide any documentation helping people migrate from those packages to Sage.
</p>
<p>
I'm not saying there's anything wrong with this ticket, and my comments should certainly <strong>not</strong> be interpreted as need_work. But I think the documentation could be made more useful by having links and names of the commands in the external packages.
</p>
<p>
Dave
</p>
TicketdrkirkbyTue, 21 Sep 2010 09:38:54 GMT
https://trac.sagemath.org/ticket/8825#comment:8
https://trac.sagemath.org/ticket/8825#comment:8
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/8825#comment:7" title="Comment 7">drkirkby</a>:
</p>
<blockquote class="citation">
<p>
But I think the documentation could be made more useful by having links and names of the commands in the external packages.
</p>
<p>
Dave
</p>
</blockquote>
<p>
Oops. I mean the documentation could be made more useful by having the name of the nearest command in the commercial packages. Not necessarily links to them, though that might be worth considering too. Some are non-obvious. For example factor() in Sage can factor an integer:
</p>
<pre class="wiki">sage: factor(12)
2^2 * 3
</pre><p>
but in Mathematica one would use <code>FactorInteger</code>
</p>
<pre class="wiki">In[1]:= FactorInteger[12]
Out[1]= {{2, 2}, {3, 1}}
</pre>
TicketmhamptonTue, 21 Sep 2010 13:18:00 GMTstatus changed
https://trac.sagemath.org/ticket/8825#comment:9
https://trac.sagemath.org/ticket/8825#comment:9
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>positive_review</em>
</li>
</ul>
<p>
Positive review - these are nice improvements.
</p>
TicketleifTue, 21 Sep 2010 13:50:25 GMT
https://trac.sagemath.org/ticket/8825#comment:10
https://trac.sagemath.org/ticket/8825#comment:10
<p>
Note that one has to perhaps change the locale (e.g. <code>LC_ALL</code>) to some UTF-8 one before importing the first patch:
</p>
<pre class="wiki">applying ../../../patches/trac_8825_norm_docstring.patch
transaction abort!
rollback completed
abort: decoding near 'Johan Grönqvist <': 'ascii' codec can't decode byte 0xc3 in position 8: ordinal not in range(128)!
</pre>
TicketjohanWed, 22 Sep 2010 11:30:34 GMT
https://trac.sagemath.org/ticket/8825#comment:11
https://trac.sagemath.org/ticket/8825#comment:11
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/8825#comment:10" title="Comment 10">leif</a>:
</p>
<blockquote class="citation">
<p>
Note that one has to perhaps change the locale (e.g. <code>LC_ALL</code>) to some UTF-8 one before importing the first patch: abort: decoding near 'Johan Grönqvist <': 'ascii' codec can't decode byte 0xc3 in position 8: ordinal not in range(128)!
</p>
</blockquote>
<p>
I do not know what is easiest, but changing my name to Johan Gronqvist (if that is the only problem) is another solution, that may work better. (Those dots are not important to me.)
</p>
<p>
/ Johan
</p>
TicketleifWed, 22 Sep 2010 12:42:57 GMT
https://trac.sagemath.org/ticket/8825#comment:12
https://trac.sagemath.org/ticket/8825#comment:12
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/8825#comment:11" title="Comment 11">johan</a>:
</p>
<blockquote class="citation">
<p>
I do not know what is easiest, but changing my name to Johan Gronqvist (if that is the only problem) is another solution, that may work better. (Those dots are not important to me.)
</p>
</blockquote>
<p>
No, that was my (or Mercurial's) mistake. It just happened that I'd changed the locale in the terminal I was trying to apply the patch in; the note was meant to keep others from running into the same.
</p>
<p>
-Leif
</p>
TicketmpatelTue, 28 Sep 2010 09:08:37 GMTstatus changed; resolution, merged set
https://trac.sagemath.org/ticket/8825#comment:13
https://trac.sagemath.org/ticket/8825#comment:13
<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>merged</strong>
set to <em>sage-4.6.alpha2</em>
</li>
</ul>
Ticket