minor doc fixes from a long-ago email #1678
Description
Somebody wrote those
comments to me about Sage. I envision the tutorial mainly having a
gotchas section that would address all of these confusions and issues below.
Metacomment: Using SAGE Version 2.5.3, Release Date: 2007-05-22.
I did
*not* use the python documentation (I didn't have access to it, due to
some uninteresting technical problems that have now been fixed).
(9) This might be an unreasonable request, but: it might be nice to be
able to get sage documentation w/out the python doc -- for example,
my python documentation might be from somewhere on the Internet, and
my Internet connection might be down (perhaps I'm flying on a
plane) -- the specific case I ran across was trying to get the `if'
syntax: it might be nice if somehow ?if, too, worked in sage.
(10) The Abstract on the Front Matter page of the tutorial says "[...]
from the SAGE notebook click Documentation [...]" but doesn't
tell you how to get to the sage notebook; perhaps a pointer (say
to Section 3.10) at that point would help.
(11) I couldn't easily find the right way to get an integer/float (not
symbolic) square root. Should ?sqrt tell me how to do that?
(12) In general, it would be nice to know, for example, what types of
sqrt are available, what types of arguments they take, etc.
(Perhaps somewhat similar to what, e.g., Emacs-calc allows if you
type M-x apropos, then sqrt to the prompt, then you can click on
a sqrt of interest.)
(13) More generally, perhaps a way to see the names of all "available"
functions would be nice. (It may exist, but I couldn't see in
two minutes how to get it.) For example, I guessed `nextprime',
but that didn't exist; it was only much later that I stumbled
across the next_prime function, with an underscore.
(14) Back to sqrt?; it gave me --
Type: Function_sqrt
Base Class: <class 'sage.calculus.calculus.Function_sqrt'>
String Form: sqrt
Namespace: Interactive
Docstring:
The square root function. This is a symbolic square root.
EXAMPLES:
sage: sqrt(-1)
I
sage: sqrt(2)
sqrt(2)
sage: sqrt(x^2)
abs(x)
-- but from this I couldn't figure out what type the argument had
to be. For example, I was surprised that
sage: M = 3099044504245996706400
sage: float(sqrt(M))
55669062361.836098
worked but then doing
sage: M = int(M)
sage: float(sqrt(M))
gave an error. Part of my surprise was that the next_prime
function that I came across *did* work with both integer types
(sage and python).
(15) Eventually someone showed me the timeit function, which I found
really useful (with it, I easily found out that the X.is_square()
form ran much faster than the is_square(X) form). Perhaps some
quick mention of timeit should be in the 3.4 Timing Commands
section of the tutorial.
(16) I was a bit surprised when
print "N = %d" %N
didn't work if N got too large (more than about 63 bits); I guess
I expected sage?python? to do the coercion. (I wound up using
print "N = %d" %(int(N))
and that worked for smallish large N but I wasn't sure it would
work for arbitrarily large N; I now know to use %s for this.)
(17) I was surprised that this code failed --
for p in range(1,50) :
if (p.is_prime()) :
print p
-- apparently because p somehow has become a python int, not a
sage Integer. Here was the error message:
<type 'exceptions.AttributeError'>: 'int' object has no attribute 'is_prime'
----------------------------------------------------------------------
----------------------------------------------------------------------
(18) I unexpectedly got this error:
<type 'exceptions.OverflowError'> Traceback (most recent call last)
[ . . . ]
---> 22 for N in xrange(BASE, MAXBOUND, BASE) :
[ . . . ]
<type 'exceptions.OverflowError'>: long int too large to convert to int
Also, it would have been nice if the error had told me which variable
caused the overflow. (I forget how I figured this out, but I wound up
using xsrange instead.)
(19) I was surprised that with s defined as
s = RealField(5000)(X).sqrt()
that (where X is a very large nonsquare integer)
print "%.4f [...]" %(s, [...])
"stops" working if s gets too large. Presumably this is a coercion
problem.
(20) I was a little surprised that something of length 725760
(apparently) would cause a problem:
sage: len(quadratic_residues(232792560))
/usr/local/sage-2.8.2/local/bin/sage-sage: line 182: 25097 Killed
sage-ipython -c "$SAGE_STARTUP_COMMAND;" "$@"
----------------------------------------------------------------------
Component: documentation
Author: Karl-Dieter Crisman
Branch/Commit: bb1447d
Reviewer: Nathann Cohen
Issue created by migration from https://trac.sagemath.org/ticket/1678