Opened 11 years ago
Closed 11 years ago
#8825 closed enhancement (fixed)
Improve documentation for function norm
Reported by: | johan | Owned by: | jason |
---|---|---|---|
Priority: | trivial | Milestone: | sage-4.6 |
Component: | documentation | Keywords: | |
Cc: | nguyenminh2@… | Merged in: | sage-4.6.alpha2 |
Authors: | Johan Grönqvist, Minh Van Nguyen | Reviewers: | Minh Van Nguyen |
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
Description (last modified by )
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.
I was very surprised that for a complex number z, norm(z) == norm(vector([z]))^{2}, and no hint of this is available from the documentation available through executing "sage: norm?".
See this sage-devel thread for some background information.
Apply patches in this order:
Attachments (3)
Change History (16)
Changed 11 years ago by
comment:1 Changed 11 years ago by
- Component changed from misc to documentation
- Description modified (diff)
- Milestone set to sage-4.4.1
- Status changed from new to needs_review
comment:2 Changed 11 years ago by
- Description modified (diff)
- Reviewers set to Minh Van Nguyen
I'm happy with the patch trac_8825_norm_docstring.patch. 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 trac_8825-more-norm-doc.patch needs review by anyone but me. If it gets a positive review, the whole ticket is good to go.
Changed 11 years ago by
comment:3 Changed 11 years ago by
I've attached a screen capture: the norm reads |*v*| in the notebook (norm?). However, if I read:
$SAGE_ROOT/devel/sage/doc/output/html/en/reference/sage/misc/functional.html
it looks fine.
comment:4 follow-up: ↓ 6 Changed 11 years ago by
Another comment: when read in the notebook, it says:
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.
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?
comment:5 Changed 11 years ago by
Nope, you can put in autogenerated hyperlinks. For example, the markup
:meth:`sage.matrix.matrix2.Matrix.norm`
would change to a link to that method.
Changed 11 years ago by
comment:6 in reply to: ↑ 4 Changed 11 years ago by
Replying to pang:
Maybe instead of norm it could say sage.matrix.matrix2.Matrix.norm, etcetera.
My updated patch takes care of this. As for the weirdness in the notebook, I don't know how to fix that.
comment:7 follow-up: ↓ 8 Changed 11 years ago by
See my suggestion on sage-devel. I personally think it would useful to also add
1) External links to Mathworld and Wikipedia
- http://en.wikipedia.org/wiki/Matrix_norm
- http://mathworld.wolfram.com/Norm.html
- http://mathworld.wolfram.com/MatrixNorm.html
- http://mathworld.wolfram.com/VectorNorm.html
These would certainly help people like me, who are not mathmaticians and might want to find out a bit more about a topic.
2) Document the nearest Mathematica, Maple, MATLAB and Macsyma commands when possible.
For Mathematica, it is Norm[] See:
http://reference.wolfram.com/mathematica/ref/Norm.html
For MATLAB it is norm()
http://www.mathworks.com/help/techdoc/ref/norm.html
I'm not sure about Maple - but Norm() might be the right one.
http://www.maplesoft.com/support/help/Maple/view.aspx?path=VectorCalculus%2fNorm
(Please check all these - I'm not a mathematician).
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.
I'm not saying there's anything wrong with this ticket, and my comments should certainly not 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.
Dave
comment:8 in reply to: ↑ 7 Changed 11 years ago by
Replying to drkirkby:
But I think the documentation could be made more useful by having links and names of the commands in the external packages.
Dave
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:
sage: factor(12) 2^2 * 3
but in Mathematica one would use FactorInteger
In[1]:= FactorInteger[12] Out[1]= {{2, 2}, {3, 1}}
comment:9 Changed 11 years ago by
- Status changed from needs_review to positive_review
Positive review - these are nice improvements.
comment:10 follow-up: ↓ 11 Changed 11 years ago by
Note that one has to perhaps change the locale (e.g. LC_ALL
) to some UTF-8 one before importing the first patch:
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)!
comment:11 in reply to: ↑ 10 ; follow-up: ↓ 12 Changed 11 years ago by
Replying to leif:
Note that one has to perhaps change the locale (e.g.
LC_ALL
) 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)!
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.)
/ Johan
comment:12 in reply to: ↑ 11 Changed 11 years ago by
Replying to johan:
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.)
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.
-Leif
comment:13 Changed 11 years ago by
- Merged in set to sage-4.6.alpha2
- Resolution set to fixed
- Status changed from positive_review to closed
Patch