Opened 11 years ago

Closed 10 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 mvngu)

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:

  1. #8819
  2. #8831
  3. trac_8825_norm_docstring.patch
  4. trac_8825-more-norm-doc.patch

Attachments (3)

trac_8825_norm_docstring.patch (885 bytes) - added by johan 11 years ago.
Patch
weirddoc.png (6.9 KB) - added by pang 11 years ago.
trac_8825-more-norm-doc.patch (8.9 KB) - added by mvngu 10 years ago.

Download all attachments as: .zip

Change History (16)

Changed 11 years ago by johan

Patch

comment:1 Changed 11 years ago by mvngu

  • Authors set to Johan Grönqvist
  • 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 mvngu

  • Authors changed from Johan Grönqvist to Johan Grönqvist, Minh Van Nguyen
  • 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 pang

comment:3 Changed 11 years ago by pang

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: Changed 11 years ago by pang

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 10 years ago by mhansen

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 10 years ago by mvngu

comment:6 in reply to: ↑ 4 Changed 10 years ago by mvngu

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: Changed 10 years ago by drkirkby

See my suggestion on sage-devel. I personally think it would useful to also add

1) External links to Mathworld and Wikipedia

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 10 years ago by drkirkby

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 10 years ago by mhampton

  • Status changed from needs_review to positive_review

Positive review - these are nice improvements.

comment:10 follow-up: Changed 10 years ago by leif

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: Changed 10 years ago by johan

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 10 years ago by leif

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 10 years ago by mpatel

  • Merged in set to sage-4.6.alpha2
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.