Ticket #3905: prog.2.patch

File prog.2.patch, 53.8 KB (added by malb, 11 years ago)

my comments from trac as a patch

  • prog/prog.tex

    # HG changeset patch
    # User Martin Albrecht <malb@informatik.uni-bremen.de>
    # Date 1219531586 -3600
    # Node ID 4bf9056066e8e0b85be0f485dbea99b11fa6ec87
    # Parent  9e8605f19c12ab9371c60f976207d3b76a503e42
    my comments on Trac -> a patch
    
    diff -r 9e8605f19c12 -r 4bf9056066e8 prog/prog.tex
    a b  
    66
    77\documentclass{manual}
    88\usepackage{textcomp}
    9 
    109\include{macros-new}
    1110% a hack to get around another hack.
    1211\ifpdf
     
    1716%\newcommand{\todo}[1]{\footnote{1}}
    1817\newcommand{\todo}[1]{}
    1918
    20 \newcommand{\swlist}{GAP, GSL, Matplotlib, Maxima, MWRANK, NetworkX,
    21   NTL, Numpy, PARI and Singular\xspace}
     19\newcommand{\swlist}{Flint, FpLLL, GAP, GSL, IML, LinBox, M4RI, Matplotlib,
     20Maxima, MWRank, ECLib, NetworkX, NTL, Numpy, PARI/GP, PolyBoRi, R
     21Scipy, Singular, Sympy\xspace}
    2222
    2323\usepackage{color}
    2424\definecolor{hue}{rgb}{.202, .602, .58}
     
    2828\definecolor{orange}{rgb}{.902, .502, .08}
    2929\definecolor{black}{rgb}{0,0, 1}
    3030
    31 
    32 
    3331\input{boilerplate}
    3432
    3533\makeindex
     
    3937
    4038\title{\SAGE Developer's Guide}
    4139
    42 \author{William Stein and David Joyner}
     40\author{The Sage Group}
    4341
    4442\maketitle
    4543
     
    5351
    5452\noindent
    5553\SAGE is a free mathematics software system. It is implemented using
    56 Python, Cython, and C++, and uses \swlist.  It is free and open
    57 source, and is available under the terms of the GNU Public License.
     54Python, Cython, and C++, uses \swlist and many specialized smaller systems
     55and libraries. It is free and open source, and is available under the terms of
     56the GNU Public License. Some parts are available under compatible licenses.
    5857
    5958Everybody who uses \SAGE should contribute something
    6059back to \SAGE at some point.  Implement a new function, add examples
     
    8483\item Implement it in C/C++ and make the result accessible
    8584      to \SAGE using Cython,
    8685\item Implement it using Cython,
    87 \item Implement it using one or more of the following: \swlist.
     86\item Implement it using one or more of the following: \swlist or any of the
     87other libraries included with \SAGE~\footnote{See
     88\url{http://www.sagemath.org/links-components.html} for a full list of packages
     89shipped with every copy of \SAGE}
    8890\item or {\em any combination} of the above.
    8991\end{enumerate}
    9092
     
    99101contains sophisticated, optimized number theory algorithms.  Notably
    100102absent from this triad is a good system for exact linear algebra
    101103(something MAGMA does extremely well), but this gap is being filled by
    102 code written for \SAGE.
     104code written for \SAGE or covered by specialized C/C++ libraries like LinBox,
     105IML and M4RI.
    103106\todo{Say something about GSL, Matplotlib, Maxima, MWRANK, NetworkX,
    104107NTL, Numpy}
    105108
     
    110113semantics of objects, the definitions, etc., are informed by how the
    111114corresponding objects are used in everyday mathematics.
    112115
    113 This document was authored by William Stein, David Joyner and others
    114 with the editorial help of Iftikhar Burhanuddin.
    115 
    116 
     116This document was authored by William Stein, David Joyner, John Palmieri
     117and others with the editorial help of Iftikhar Burhanuddin and Martin Albrecht.
    117118
    118119\chapter{Conventions for Coding in \SAGE}\label{ch:conventions}
    119120
     
    147148    objects, e.g., \code{PolynomialRing}.
    148149\end{itemize}
    149150
     151Note however that some functions do have uppercase letters where it makes sense.
     152For instance, the function for lattice reduction by the LLL algorithm is called
     153\code{Matrix_integer_dense.LLL}.
    150154
    151155\section{File and Directory Names}
    152156
     
    156160file \code{polynomial\_ring.py} might still contain definitions of
    157161several different types of polynomial rings.
    158162
     163%malb: I'm not sure about the encouragement of TXT files. It seems to be hardly
     164%      used and gets old quickly.
    159165\note{You are encouraged
    160166to include miscellaneous notes, emails, design
    161167discussions, etc., in your package.  Make these
     
    196202\end{verbatim}
    197203
    198204The following is the top of the file
    199 \code{SAGE_ROOT/devel/sage/sage/modular/ssmmod/ssmod.py}, which
    200 contains the Supersingular Module code.
     205\code{SAGE_ROOT/devel/sage/sage/rings/integer.pyx}, which
     206contains the implementation for $\Z$.
    201207
    202208{\small
    203209
    204210\begin{verbatim}
    205 """
    206 Module of Supersingular Points
     211r"""
     212Elements of the ring $\Z$ of integers
    207213
    208214AUTHORS:
    209     -- William Stein
    210     -- David Kohel
    211     -- Iftikhar Burhanuddin
     215    -- William Stein (2005): initial version
     216    -- Gonzalo Tornaria (2006-03-02): vastly improved python/GMP
     217                                   conversion; hashing
     218    -- Didier Deshommes <dfdeshom@gmail.com> (2006-03-06): numerous
     219                                   examples and docstrings
     220    -- William Stein (2006-03-31): changes to reflect GMP bug fixes
     221    -- William Stein (2006-04-14): added GMP factorial method (since it's
     222                                   now very fast).
     223    -- David Harvey (2006-09-15): added nth_root, exact_log
     224    -- David Harvey (2006-09-16): attempt to optimise Integer constructor
     225    -- Rishikesh (2007-02-25): changed quo_rem so that the rem is positive
     226    -- David Harvey, Martin Albrecht, Robert Bradshaw (2007-03-01):
     227                                   optimized Integer constructor and
     228                                   pool
     229    -- Pablo De Napoli (2007-04-01): multiplicative_order should
     230                                   return +infinity for non zero
     231                                   numbers
     232    -- Robert Bradshaw (2007-04-12): is_perfect_power, Jacobi symbol
     233                                   (with Kronecker extension). Convert
     234                                   some methods to use GMP directly
     235                                   rather than pari, Integer() ->
     236                                   PY_NEW(Integer)
     237    -- David Roe (2007-03-21): sped up valuation and is_square, added
     238                                   val_unit, is_power, is_power_of and
     239                                   divide_knowing_divisible_by
     240    -- Robert Bradshaw (2008-03-26): gamma function, multifactorials
    212241
    213242EXAMPLES:
    214     sage: x = SupersingularModule(389)
    215     sage: m = x.T(2).matrix()
    216     sage: a = m.change_ring(GF(97))
    217     sage: D = a.decomposition()
    218     sage: D[:3]
    219     [
    220     (Vector space of degree 33 and dimension 1 over Finite Field of size 97
    221     Basis matrix:
    222     [ 0  0  0  1 96 96  1 96 96  0  2 96 96  0  1  0  1  2 95  0  1  1  0  1  0 95  0 96 95  1 96  0  2], True),
    223     (Vector space of degree 33 and dimension 1 over Finite Field of size 97
    224     Basis matrix:
    225     [ 0  1 96 75 16 81 22 17 17  0  0 80 80  1 16 40 74  0  0 96 81 23 57 74  0  0  0 24  0 23 73  0  0], True),
    226     (Vector space of degree 33 and dimension 1 over Finite Field of size 97
    227     Basis matrix:
    228     [ 0  1 96 90 90  7  7  6 91  0  0 91  6 13  7  0 91  0  0 84 90  6  0  6  0  0  0 90  0 91  7  0  0], True)
    229     ]
    230     sage: len(D)
    231     9
     243   Add 2 integers:
     244       sage: a = Integer(3) ; b = Integer(4)
     245       sage: a + b == 7
     246       True
    232247
    233 We compute a Hecker operator on a space of huge dimension!
    234     sage: X = SupersingularModule(next_prime(100000))
    235     sage: t = X.T(2).matrix()            # long time (but still less than a minute!)
    236     sage: t.nrows()                      # long time
    237     8334
     248   Add an integer and a real number:
     249       sage: a + 4.0
     250       7.00000000000000
    238251
    239 TESTS:
    240     sage: X = SupersingularModule(389)
    241     sage: T = X.T(2).matrix().change_ring(QQ)
    242     sage: d = T.decomposition()
    243     sage: len(d)
    244     6
    245     sage: [a[0].dimension() for a in d]
    246     [1, 1, 2, 3, 6, 20]
    247     sage: loads(dumps(X)) == X
     252   Add an integer and a rational number:
     253       sage: a + Rational(2)/5
     254       17/5
     255
     256   Add an integer and a complex number:
     257       sage: b = ComplexField().0 + 1.5
     258       sage: loads((a+b).dumps()) == a+b
     259       True
     260
     261   sage: z = 32
     262   sage: -z
     263   -32
     264   sage: z = 0; -z
     265   0
     266   sage: z = -0; -z
     267   0
     268   sage: z = -1; -z
     269   1
     270
     271Multiplication:
     272    sage: a = Integer(3) ; b = Integer(4)
     273    sage: a * b == 12
    248274    True
    249     sage: loads(dumps(d)) == d
     275    sage: loads((a * 4.0).dumps()) == a*b
    250276    True
     277    sage: a * Rational(2)/5
     278    6/5
     279
     280    sage: list([2,3]) * 4
     281    [2, 3, 2, 3, 2, 3, 2, 3]
     282
     283    sage: 'sage'*Integer(3)
     284    'sagesagesage'
     285
     286COERCIONS:
     287    Returns version of this integer in the multi-precision floating
     288    real field R.
     289
     290    sage: n = 9390823
     291    sage: RR = RealField(200)
     292    sage: RR(n)
     293    9.3908230000000000000000000000000000000000000000000000000000e6
     294
    251295"""
    252 
    253296#*****************************************************************************
    254297#       Copyright (C) 2004,2006 William Stein <wstein@gmail.com>
    255 #       Copyright (C) 2006 David Kohel <kohel@maths.usyd.edu.au>
    256 #       Copyright (C) 2006 Iftikhar Burhanuddin <burhanud@usc.edu>
     298#       Copyright (C) 2006 Gonzalo Tornaria <tornaria@math.utexas.edu>
     299#       Copyright (C) 2006 Didier Deshommes <dfdeshom@gmail.com>
     300#       Copyright (C) 2007 David Harvey <dmharvey@math.harvard.edu>
     301#       Copyright (C) 2007 Martin Albrecht <malb@informatik.uni-bremen.de>
     302#       Copyright (C) 2007,2008 Robert Bradshaw <robertwb@math.washington.edu>
     303#       Copyright (C) 2007 David Roe <roed314@gmail.com>
     304#
    257305#  Distributed under the terms of the GNU General Public License (GPL)
    258 ...
     306#                  http://www.gnu.org/licenses/
     307#*****************************************************************************
    259308\end{verbatim}
    260309
    261310}%small
    262311
    263 All code included with \sage must be licensed under the GPL or a less
    264 restrictive license (e.g., the BSD license). 
    265 It is {\em very
    266   important} that you include your name in the AUTHOR log, since
    267 everybody who submits code to \sage to receive proper credit. (If
     312All code included with \sage must be licensed under the GPLv2+ or a
     313less restrictive license (e.g., the BSD license). 
     314It is {\em very important} that you include your name in the AUTHOR log, since
     315everybody who submits code to \sage to receive proper credit\footnote{See
     316\url{http://www.sagemath.org/development-map.html}}. (If
    268317ever you feel you are not receiving proper credit for anything you
    269318submit to \sage, please let the development team know!)
    270319
     
    279328  have to represent the exact \SAGE/Python types.  For example, use
    280329  ``integer'' for anything that behaves like an integer; you do not
    281330  have to put a precise type name such as \code{int}.
    282 \item An EXAMPLES block for examples. This is {\em not} optional.
     331\item An EXAMPLES block for examples. This is {\em not} optional. These
     332examples are used for automatic testing before each release and new functions
     333without these doctests will not be accepted for inclusion with \SAGE.
     334\item An ALGORITHM block (optional) which indicates what software and/or what
     335algorithm is used. For example \code{ALGORITHM: Uses Pari}.
    283336\item A NOTES block for special notes (optional). Include information
    284   such as algorithm used, references, etc.
     337  such as references, purpose etc.
    285338\item An AUTHORS block (optional, but encouraged for important
    286339functions, so users can see from the docstring who wrote it and
    287340therefore whom to contact if they have questions).
     
    295348    This function returns the point $(x^5,y)$.
    296349
    297350    INPUT:
    298         self -- anything special about self
    299351        x -- integer (default: 1) the ...
    300352        y -- integer (default: 2) the ...
    301353
     
    336388You are {\em strongly encouraged} to:
    337389\begin{itemize}
    338390
    339 \item Use nice \Latex formating everywhere but in the
    340   \code{INPUT/OUTPUT} blocks.  If you use backslashes, either use
     391\item Use nice \Latex formating everywhere.  If you use backslashes, either use
    341392  double backslashes or place an {\tt r} right before the first triple
    342393  opening quote. For example,
    343394%skip
     
    371422  regular basis, and are crucial for the quality and adaptability of
    372423  \sage.  Without such examples, small changes to one part of \sage
    373424  that break something else might not go seen until much later when
    374   someone uses the system, which is unacceptable.
     425  someone uses the system, which is unacceptable. Note that no new functions
     426  without will be accepted for inclusion in \SAGE.
    375427\end{itemize}
    376428 
    377429The code in the examples should pass automatic testing.  This means
     
    423475    sage: c._hash #random
    424476    1335416675971793195
    425477\end{verbatim}
     478  However, most functions generating pseudo-random output do not need this tag
     479  since the doctesting framework guarantees the state of the
     480pseudo random number generators (PRNGs) used in \SAGE for a given doctest. See
     481\ref{ch:random} for details on this framework.
    426482
    427483\item If a line contains the text \code{long time} then that line is
    428484  not tested unless the {\code -long} option is given, e.g.,
     
    459515class \code{EllipticCurve_finite_field} from the
    460516\code{SAGE_ROOT/devel/sage/sage/schemes/elliptic_curves/ell_finite_field.py}
    461517contains
     518{\small
    462519\begin{verbatim}
    463     sage: EllipticCurve(GF(41),[2,5])._magma_init_() # optional -- requires Magma
     520    sage: E = EllipticCurve(GF(41),[2,5])
     521    sage: E._magma_init_() # optional -- requires Magma
    464522    'EllipticCurve([_sage_[1]|GF(41)!0,GF(41)!0,GF(41)!0,GF(41)!2,GF(41)!5])'
    465 \end{verbatim}
     523\end{verbatim}}
    466524
    467525\item If the entire documentation string contains all three words
    468526\code{optional}, \code{package}, and \code{installed}, then
     
    478536 implemented}, one can use the results of such a search to direct
    479537further development on \sage.
    480538
     539\section{Random Numbers}\label{ch:random}
     540
     541(This section was originally written by Carl Witty)
     542
     543The \code{sage.misc.randstate} module manages all the available pseudo-random
     544number generators
     545in \Sage.  (For the rest of the documentation, we will drop the ``pseudo''.)
     546
     547The goal is to allow algorithms using random numbers to be reproducible from one
     548run of \sage to the next, and (to the extent possible) from one machine to the
     549next (even across different operating systems and architectures).
     550
     551There are two parts to the API.  First we will describe the
     552command-line-oriented API, for setting random number generator seeds.
     553Then we will describe the library API, for people writing \sage library code
     554that uses random numbers.
     555
     556We'll start with the simplest usage: setting fixed random number seeds
     557and showing that these lead to reproducible results.
     558
     559\begin{verbatim}
     560sage: K.<x> = QQ[]
     561sage: G = PermutationGroup([[(1,2,3),(4,5)], [(1,2)]])
     562sage: rgp = Gp()
     563sage: def gap_randstring(n):
     564...       current_randstate().set_seed_gap()
     565...       return gap(n).SCRRandomString()
     566sage: def rtest():
     567...       current_randstate().set_seed_gp(rgp)
     568...       return (ZZ.random_element(1000), RR.random_element(),
     569...               K.random_element(), G.random_element(),
     570...               gap_randstring(5),
     571...               rgp.random(), ntl.ZZ_random(99999),
     572...               random())
     573\end{verbatim}
     574
     575The above test shows the results of six different random number generators, in
     576three different processes.  The random elements from \code{ZZ}, \code{RR}, and
     577\code{K} all derive from a single GMP-based random number generator.  The random
     578element from \code{G} comes from a GAP subprocess. The random ``string''
     579(5-element binary list) is also from a GAP subprocess, using the ``classical''
     580GAP random generator. The random number from \code{rgp} is from a Pari/gp
     581subprocess. NTL's \code{ZZ_random} uses a separate NTL random number generator
     582in the main \sage process.  And \code{random()} is from a Python
     583\class{random.Random} object.
     584
     585Here we see that setting the random number seed really does make the
     586results of these random number generators reproducible.
     587
     588\begin{verbatim}
     589sage: set_random_seed(0)
     590sage: rtest()
     591(303, -0.187141682737491, 1/2*x^2 - 1/95*x - 1/2, (1,2), [ 0, 0, 0, 0, 1 ],
     5921698070399, 8045, 0.96619117347084138)
     593sage: set_random_seed(1)
     594sage: rtest()
     595(978, 0.184109262667515, -3*x^2 - 1/12, (2,3), [ 0, 1, 1, 0, 0 ], 1046254370,
     59660359, 0.83350776541997362)
     597sage: set_random_seed(2)
     598sage: rtest()
     599(207, 0.505364206568040, 4*x^2 + 1/2, (1,2)(4,5), [ 0, 0, 1, 0, 1 ], 2137873234,
     60027695, 0.19982565117278328)
     601sage: set_random_seed(0)
     602sage: rtest()
     603(303, -0.187141682737491, 1/2*x^2 - 1/95*x - 1/2, (1,2), [ 0, 0, 0, 0, 1 ],
     6041698070399, 8045, 0.96619117347084138)
     605sage: set_random_seed(1)
     606sage: rtest()
     607(978, 0.184109262667515, -3*x^2 - 1/12, (2,3), [ 0, 1, 1, 0, 0 ], 1046254370,
     60860359, 0.83350776541997362)
     609sage: set_random_seed(2)
     610sage: rtest()
     611(207, 0.505364206568040, 4*x^2 + 1/2, (1,2)(4,5), [ 0, 0, 1, 0, 1 ], 2137873234,
     61227695, 0.19982565117278328)
     613\end{verbatim}
     614
     615Once we've set the random number seed, we can check what seed was used.
     616(This is not the current random number state; it does not change when
     617random numbers are generated.)
     618
     619\begin{verbatim}
     620sage: set_random_seed(12345)
     621sage: initial_seed()
     62212345L
     623sage: rtest()
     624(720, 0.0216737401150802, x^2 - x, (), [ 1, 0, 0, 0, 0 ], 1506569166, 14005,
     6250.92053315995181839)
     626sage: initial_seed()
     62712345L
     628\end{verbatim}
     629
     630If \code{set_random_seed()} is called with no argument, then a new
     631seed is automatically selected.  On operating systems that support it,
     632the new seed comes from \function{os.urandom}; this is intended to be
     633a truly random (not pseudo-random), cryptographically secure number.
     634(Whether it is actually cryptographically secure depends on operating
     635system details that are outside the control of \sage.)
     636
     637If \function{os.urandom} is not supported, then the new seed comes
     638from the current time, which is definitely not cryptographically
     639secure.
     640
     641\begin{verbatim}
     642sage: set_random_seed()
     643sage: r = rtest()
     644sage: r         # random
     645(909, -0.407373370020575, 6/7*x^2 + 1, (1,2,3)(4,5), 985329107, 21461,
     6460.30047071049504859)
     647\end{verbatim}
     648
     649After setting a new random number seed with \code{set_random_seed()},
     650we can use \function{initial_seed} to see what seed was automatically
     651selected, and call \function{set_random_seed} to restart the same
     652random number sequence.
     653
     654\begin{verbatim}
     655sage: s = initial_seed()
     656sage: s         # random
     657336237747258024892084418842839280045662L
     658sage: set_random_seed(s)
     659sage: r2 = rtest()
     660sage: r == r2
     661True
     662\end{verbatim}
     663
     664Whenever \sage starts, \code{set_random_seed()} is called just before
     665command line interaction starts; so every \sage run starts with a
     666different random number seed.  This seed can be recovered with
     667\code{initial_seed()} (as long as the user has not set a different
     668seed with \function{set_random_seed}), so that the results of this run
     669can be reproduced in another run; or this automatically selected seed
     670can be overridden with, for instance, \code{set_random_seed(0)}.
     671
     672We can demonstrate this startup behavior by running a new instance of
     673\sage as a subprocess.
     674
     675\begin{verbatim}
     676sage: subsage = Sage()
     677sage: s = ZZ(subsage('initial_seed()'))
     678sage: r = ZZ(subsage('ZZ.random_element(2^200)'))
     679sage: s         # random
     680161165040149656168853863459174502758403
     681sage: r         # random
     6821273828861620427462924151488498075119241254209468761367941442
     683sage: set_random_seed(s)
     684sage: r == ZZ.random_element(2^200)
     685True
     686\end{verbatim}
     687
     688Note that wrappers of all the random number generation methods from
     689Python's \module{random} module are available at the \sage command
     690line, and these wrappers are properly affected by set_random_seed().
     691
     692\begin{verbatim}
     693sage: set_random_seed(0)
     694sage: random(), getrandbits(20), uniform(5.0, 10.0), normalvariate(0, 1)
     695(0.111439293741037, 539332L, 8.26785106378383, 1.3893337539828183)
     696sage: set_random_seed(1)
     697sage: random(), getrandbits(20), uniform(5.0, 10.0), normalvariate(0, 1)
     698(0.82940228518742587, 624859L, 5.77894484361117, -0.42013668263087578)
     699sage: set_random_seed(0)
     700sage: random(), getrandbits(20), uniform(5.0, 10.0), normalvariate(0, 1)
     701(0.111439293741037, 539332L, 8.26785106378383, 1.3893337539828183)
     702\end{verbatim}
     703
     704That pretty much covers what you need to know for command-line use of
     705this module.  Now let's move to what authors of \sage library code
     706need to know about the module.
     707
     708First, we'll cover doctesting.  Every docstring now has an implicit
     709\code{set_random_seed(0)} prepended.  Any uses of \code{# random} that
     710are based on random numbers under the control of this module should be
     711removed, and the reproducible answers inserted instead.
     712
     713This practice has two potential drawbacks.  First, it increases the work
     714of maintaining doctests; for instance, in a long docstring that has
     715many doctests that depend on random numbers, a change near the beginning
     716(for instance, adding a new doctest) may invalidate all later doctests
     717in the docstring.  To reduce this downside, you may add calls to
     718\code{set_random_seed(0)} throughout the docstring (in the extreme case,
     719before every doctest).
     720
     721Second, the \code{# random} in the doctest served as a signal to the
     722reader of the docstring that the result was unpredictable and that it
     723would not be surprising to get a different result when trying out the
     724examples in the doctest.  If a doctest specifically refers to
     725\code{ZZ.random_element()} (for instance), this is presumably enough
     726of a signal to render this function of \code{# random} unnecessary.
     727However, some doctests are not obviously (from the name) random, but
     728do depend on random numbers internally, such as the
     729\method{composition_series} method of a \class{PermutationGroup}.  In
     730these cases, the convention is to insert the following text at the
     731beginning of the EXAMPLES section.
     732
     733\begin{verbatim}
     734        These computations use pseudo-random numbers, so we set the
     735        seed for reproducible testing.
     736            sage: set_random_seed(0)
     737\end{verbatim}
     738
     739Note that this call to \code{set_random_seed(0)} is redundant, since
     740\code{set_random_seed(0)} is automatically inserted at the beginning
     741of every docstring; but it makes the example reproducible for somebody
     742who just types the lines from the doctest and doesn't know about the
     743automatic \code{set_random_seed(0)}.
     744
     745Next, let's cover setting the random seed from library code.  The
     746first rule is that library code should never call
     747\function{set_random_seed}; this function is only for command-line
     748use.  Instead, if the library code wants to use a different random
     749seed, it should use \code{with seed(s):}; this will use the new seed
     750within the scope of the \code{with}, but will revert to the previous seed
     751once the \code{with} is completed.  (Or the library can use
     752\code{with seed():} to get a seed automatically selected using
     753\code{os.urandom()} or the current time, in the same way as described for
     754\code{set_random_seed()} above.)
     755
     756Ideally, using \code{with seed(s):} should not affect the outer random
     757number sequence at all; we will call this property ``isolation.''  We
     758achieve isolation for most, but not all, of the random number generators
     759in \sage (we fail for generators, such as NTL, that do not provide an API
     760to retrieve the current random number state).
     761
     762We'll demonstrate isolation.  First, we show the sequence of random numbers
     763that you get without intervening \code{with seed}.
     764
     765\begin{verbatim}
     766sage: set_random_seed(0)
     767sage: r1 = rtest(); r1
     768(303, -0.187141682737491, 1/2*x^2 - 1/95*x - 1/2, (1,2), [ 0, 0, 0, 0, 1 ],
     7691698070399, 8045, 0.96619117347084138)
     770sage: r2 = rtest(); r2
     771(105, -0.581229341007821, -x^2 - x - 6, (1,3,2)(4,5), [ 1, 0, 0, 1, 1 ],
     772697338742, 1271, 0.001767155077382232)
     773\end{verbatim}
     774
     775We get slightly different results with an intervening \code{with seed}.
     776
     777\begin{verbatim}
     778sage: set_random_seed(0)
     779sage: r1 == rtest()
     780True
     781sage: with seed(1): rtest()
     782(978, 0.184109262667515, -3*x^2 - 1/12, (2,3), [ 0, 1, 1, 0, 0 ], 1046254370,
     78360359, 0.83350776541997362)
     784sage: r2m = rtest(); r2m
     785(105, -0.581229341007821, -x^2 - x - 6, (1,3,2)(4,5), [ 1, 0, 0, 1, 1 ],
     786697338742, 19769, 0.001767155077382232)
     787sage: r2m == r2
     788False
     789\end{verbatim}
     790
     791We can see that \var{r2} and \var{r2m} are the same except for the
     792call to \function{ntl.ZZ_random}, which produces different results
     793with and without the \code{with seed}.
     794
     795However, we do still get a partial form of isolation, even in this
     796case, as we see in this example:
     797
     798\begin{verbatim}
     799sage: set_random_seed(0)
     800sage: r1 == rtest()
     801True
     802sage: with seed(1): (rtest(), rtest())
     803((978, 0.184109262667515, -3*x^2 - 1/12, (2,3), [ 0, 1, 1, 0, 0 ], 1046254370,
     80460359, 0.83350776541997362), (138, -0.247578366457583, 2*x - 24, (), [ 1, 1, 1,
     8050, 1 ], 1077419109, 10234, 0.0033332230808060803))
     806sage: r2m == rtest()
     807True
     808\end{verbatim}
     809
     810The NTL results after the \code{with seed} don't depend on how many
     811NTL random numbers were generated inside the \code{with seed}.
     812
     813Unfortunately, Cython does not yet support the \code{with} statement.
     814Instead, you must use the equivalent \code{try}/\code{finally} statement:
     815
     816\begin{verbatim}
     817sage: set_random_seed(0)
     818sage: r1 == rtest()
     819True
     820sage: ctx = seed(1)
     821sage: try:
     822...       ctx.__enter__()
     823...       rtest()
     824... finally:
     825...       ctx.__exit__(None, None, None)
     826<sage.misc.randstate.randstate object at 0x...>
     827(978, 0.184109262667515, -3*x^2 - 1/12, (2,3), [ 0, 1, 1, 0, 0 ], 1046254370,
     82860359, 0.83350776541997362)
     829False
     830sage: r2m == rtest()
     831True
     832\end{verbatim}
     833
     834(In general, the above code is not exactly equivalent to the \code{with}
     835statement, because if an exception happens in the body, the real
     836\code{with} statement will pass the exception information as parameters to
     837the \method{__exit__} method.  However, our \method{__exit__} method
     838ignores the exception information anyway, so the above is equivalent in
     839our case.)
     840
     841Now we come to the last part of the documentation: actually generating
     842random numbers in library code.  First, the easy case: if you generate
     843random numbers only by calling other \sage library code (such as
     844\method{random_element} methods on parents), you don't need to do
     845anything special; the other code presumably already interacts with
     846this module correctly.
     847
     848Otherwise, it depends on what random number generator you want to use.
     849
     850\begin{description}
     851\item[gmp_randstate_t] If you want to use some random number generator
     852that takes a \code{gmp_randstate_t} (like \code{mpz_urandomm} or
     853\code{mpfr_urandomb}), then use code like the following:
     854\begin{verbatim}
     855from sage.misc.randstate cimport randstate, current_randstate
     856...
     857
     858    cdef randstate rstate = current_randstate()
     859\end{verbatim}
     860then a \code{gmp_randstate_t} is available as \code{rstate.gmp_state}.
     861
     862Fetch the current \class{randstate} with \code{current_randstate()} in
     863every function that wants to use it; don't cache it globally or
     864in a class.  (Such caching would break \method{set_random_seed}).
     865
     866\item[Python] If you want to use the random number generators from the
     867\module{random} module, you have two choices.  The slightly easier choice
     868is to import functions from \module{sage.misc.prandom}; for instance,
     869you can simply replace \code{from random import randrange} with
     870\code{from sage.misc.prandom import randrange}.  However, this is
     871slighly less efficient, because the wrappers in \module{sage.misc.prandom}
     872look up the current \class{randstate} on each call.  If you're generating
     873many random numbers in a row, it's faster to instead do
     874\begin{verbatim}
     875from sage.misc.randstate import current_randstate
     876...
     877
     878    randrange = current_randstate().python_random().randrange
     879\end{verbatim}
     880
     881Fetch the current \class{randstate} with \code{current_randstate()} in
     882every function that wants to use it; don't cache the
     883\class{randstate}, the \class{Random} object returned by
     884\method{python_random}, or the bound methods on that \class{Random}
     885object globally or in a class.  (Such caching would break
     886\method{set_random_seed}).
     887
     888\item[GAP] If you are calling code in GAP that uses random numbers,
     889call \method{set_seed_gap} at the beginning of your function, like this:
     890\begin{verbatim}
     891from sage.misc.randstate import current_randstate
     892...
     893
     894    current_randstate().set_seed_gap()
     895\end{verbatim}
     896
     897Fetch the current \class{randstate} with \code{current_randstate()} in
     898every function that wants to use it; don't cache it globally or
     899in a class.  (Such caching would break \method{set_random_seed}).
     900
     901\item[Pari] If you are calling code in the Pari library that uses
     902random numbers, call \method{set_seed_pari} at the beginning of your
     903function, like this:
     904\begin{verbatim}
     905from sage.misc.randstate import current_randstate
     906...
     907
     908    current_randstate().set_seed_pari()
     909\end{verbatim}
     910
     911Fetch the current \class{randstate} with \code{current_randstate()} in
     912every function that wants to use it; don't cache it globally or
     913in a class.  (Such caching would break \method{set_random_seed}).
     914
     915\item[Pari/gp] If you are calling code in a Pari/gp subprocess that
     916uses random numbers, call \method{set_seed_gp} at the beginning of
     917your function, like this:
     918\begin{verbatim}
     919from sage.misc.randstate import current_randstate
     920...
     921
     922    current_randstate().set_seed_gp()
     923\end{verbatim}
     924This will set the seed in the gp process in sage.interfaces.gp.gp.
     925If you have a different gp process, say in the variable \var{my_gp}, then
     926call \code{set_seed_gp(my_gp)} instead.
     927
     928Fetch the current \class{randstate} with \code{current_randstate()} in
     929every function that wants to use it; don't cache it globally or
     930in a class.  (Such caching would break \method{set_random_seed}).
     931
     932\item[NTL] If you are calling code in the NTL library that uses
     933random numbers, call \method{set_seed_ntl} at the beginning of your
     934function, like this:
     935\begin{verbatim}
     936from sage.misc.randstate import current_randstate
     937...
     938
     939    current_randstate().set_seed_ntl(False)
     940\end{verbatim}
     941
     942Fetch the current \class{randstate} with \code{current_randstate()} in
     943every function that wants to use it; don't cache it globally or
     944in a class.  (Such caching would break \method{set_random_seed}).
     945
     946\item[libc] If you are writing code that calls the libc function
     947\code{random()}: don't!  The \code{random()} function does not give
     948reproducible results across different operating systems, so we can't
     949make portable doctests for the results.  Instead, do:
     950\begin{verbatim}
     951from sage.misc.randstate cimport random
     952\end{verbatim}
     953The \function{random} function in \module{sage.misc.randstate} gives a
     95431-bit random number (the same range as the \function{random} in libc,
     955on all systems I'm familiar with), but it uses the \code{gmp_randstate_t}
     956in the current \class{randstate}, so it is portable.
     957
     958However, you may still need to set the libc random number state; for
     959instance, if you are wrapping a library that uses \code{random()}
     960internally and you don't want to change the library.  In that case,
     961call \method{set_seed_libc} at the beginning of your function, like this:
     962\begin{verbatim}
     963from sage.misc.randstate import current_randstate
     964...
     965
     966    current_randstate().set_seed_libc(False)
     967\end{verbatim}
     968
     969Fetch the current \class{randstate} with \code{current_randstate()} in
     970every function that wants to use it; don't cache it globally or
     971in a class.  (Such caching would break \method{set_random_seed}).
     972
     973\end{description}
    481974
    482975\section{Automated Testing}\label{ch:testing}
    483976
     
    5211014on \code{.doctest_foo.py}. 
    5221015\end{enumerate}
    5231016
    524 \note{{\em Note that line numbers in the errors 
    525 you might see apply to the file \code{.doctest_foo.py}, not
    526 to the original file \code{foo.py}!}  If you get errors,
    527 feel free to inspect \code{.doctest_foo.py}; it is never
    528 automatically deleted by \sage.}
     1017% malb: I think these numbers are correct.
     1018% \note{{\em Note that line numbers in the errors 
     1019% you might see apply to the file \code{.doctest_foo.py}, not
     1020% to the original file \code{foo.py}!}  If you get errors,
     1021% feel free to inspect \code{.doctest_foo.py}; it is never
     1022% automatically deleted by \sage.}
    5291023
    5301024Your file passes these tests if the code in it will run when entered
    5311025at the \code{sage:} prompt with no special imports.  Thus users are
     
    5751069
    5761070\section{Randomized Testing}
    5771071\label{ch:randomtesting}
     1072%malb: do we run randomized tests regulary?
    5781073
    5791074In addition to all the examples in your docstrings, which serve as
    5801075both demonstrations and tests of your code, you should consider creating a
     
    6541149
    6551150\item Define a method \code{_latex_(self)} that returns a
    6561151  \Latex representation of your object.  It should be something that
    657   can be typeset correctly within math mode.
     1152  can be typeset correctly within math mode. Do not include opening and closing
     1153  \$'s.
    6581154
    6591155\item Often objects are built up out of other \sage objects, and these
    6601156  components should be typeset using the \code{latex} function.
     
    6801176class X:
    6811177   ...
    6821178   def _latex_(self):
    683        """
     1179       r"""
    6841180       Return \Latex representation of X.
    6851181 
    6861182       EXAMPLES:
     
    7011197The standard Python printing method is \code{__repr__(self)}.  In
    7021198\sage, that is for objects that derive from \code{SageObject} (which
    7031199is everything in \sage), instead define \code{_repr_(self)}.
    704 % This is preferable because if you only define \code{_repr_(self)} and
    705 % not \code{__repr__(self)}, then users can rename your object to print
    706 % however they like.
     1200This is preferable because if you only define \code{_repr_(self)} and
     1201not \code{__repr__(self)}, then users can rename your object to print
     1202however they like. Also, some objects should print differently depending on the
     1203context.
    7071204
    7081205Here is an example of the \code{_latex_} and \code{_repr_} functions
    7091206for the Pi class. It is from the file
     
    7481245
    7491246    def adjacency_matrix(self, sparse=None, boundary_first=False):
    7501247        ...
    751 
    752     am = adjacency_matrix # shorter call makes life easier
    7531248\end{verbatim}
    7541249
    7551250Similarly,
     
    8231318\end{verbatim}
    8241319
    8251320\item Raw literals can be very useful in certain cases. For instance,
    826   Python integers are typically much more efficient than \SAGE integers
     1321  Python integers can be more efficient than \SAGE integers
    8271322  when they are very small; large \SAGE integers are much more
    8281323  efficient than Python integers, since they are implemented using the
    829   GMP C library.  For example, the first of these commands may be somewhat
    830   slower than the second:
    831 \begin{verbatim}
    832     sage: v = [ 2*i for i in range(10000)]
    833     sage: v = [ 2r*i for i in range(10000r)]
    834 \end{verbatim}
    835 because the first uses \sage integers, while the second uses raw
    836 Python integers.
     1324  GMP C library.
     1325% For example, the first of these commands may be somewhat
     1326%   slower than the second:
     1327% \begin{verbatim}
     1328%     sage: v = [ 2*i for i in range(10000)]
     1329%     sage: v = [ 2r*i for i in range(10000r)]
     1330% \end{verbatim}
     1331% because the first uses \sage integers, while the second uses raw
     1332% Python integers.
    8371333
    8381334\end{itemize}
    8391335
     
    10921588
    10931589If you don't have any exceptions explicitly listed (as a tuple), your
    10941590code will catch absolutely anything, including \code{ctrl-C} and alarms,
    1095 and this will lead to confusion.
     1591and this will lead to confusion. Also, this might catch real errors which
     1592should be propagated to the user.
    10961593
    10971594
    10981595\section{Importing}
     
    11201617With this set-up, running \sage will produce an error:
    11211618%skip
    11221619\begin{verbatim}
    1123 Exception exceptions.ImportError: 'cannot import name SteenrodAlgebra' in 'sage.rings.polynomial.polynomial_element.Polynomial_generic_dense.__normalize' ignored
    1124 ---------------------------------------------------------------------------
    1125 ImportError                               Traceback (most recent call last)
     1620Exception exceptions.ImportError: 'cannot import name SteenrodAlgebra' \
     1621in 'sage.rings.polynomial.polynomial_element.\
     1622Polynomial_generic_dense.__normalize' ignored
     1623-------------------------------------------------------------------
     1624ImportError                       Traceback (most recent call last)
    11261625
    11271626...
    11281627ImportError: cannot import name SteenrodAlgebra
     
    11471646as possible, since this is what dominates the \SAGE startup time, and
    11481647controlling the top-level imports helps to do this.
    11491648
     1649% malb: Describe late_import trick here-ish.
    11501650
    11511651\section{Using Optional Packages}
    11521652
     
    11541654perhaps using a \code{try} and \code{except} block --- when the optional
    11551655package is not available, and should give a hint about how to install
    11561656it.  For example, typing \code{sage -optional} gives a list of all
    1157 optional packages, so it might suggest to the user that they type that.
     1657optional packages, so it might suggest to the user that they type that. The
     1658command \code{optional_packages()} from within \SAGE also returns this list.
    11581659
    11591660
    11601661
     
    11631664When writing code for \sage, use Python for the basic structure and
    11641665interface.  For speed, efficiency, or convenience, you can implement
    11651666parts of the code using any of the following languages:
    1166 Cython, C/C++, Fortran 95, GAP, Singular, and GP/PARI.  You can also
    1167 use the mwrank, GSL, NTL, and PARI C/C++ libraries. (And if you are
     1667Cython, C/C++, Fortran 95, GAP, Common Lisp, Singular, and GP/PARI. You can
     1668also use all C/C++ libraries included with \SAGE~\footnote{See \url{
     1669http://www.sagemath.org/links-components.html} for a list}. (And if you are
    11681670okay with your code depending on optional \sage packages, you can use
    11691671Octave, or even Magma, Mathematica, or Maple.)
    11701672
     
    11731675written in Cython.  Later sections discuss the interfaces between
    11741676\sage and PARI, GAP, and Singular.
    11751677
    1176 
    1177 
    11781678\section{Cython}
    11791679
    11801680Cython is a compiled version of Python; it is based on Pyrex
    11811681(\url{http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/}).  To
    11821682a large degree, Cython has changed based on what \sage's developers
    1183 needed: Cython has been developed in concert with \sage.
     1683needed: Cython has been developed in concert with \sage. However, it is an
     1684independent project now which is used beyond the scope of \SAGE.
    11841685
    11851686As such, it is a young, but developing, language, with young, but
    11861687developing, documentation.  See its web page,
     
    12251726              ['sage/graphs/chrompoly.pyx']
    12261727              ), \
    12271728\end{verbatim}
    1228 in \code{setup.py}.  Then type \code{sage -ba} to build \sage with the
    1229 new code.
     1729in \code{setup.py}. Also, the module -- in this example \code{sage.graphs.ch
     1730rompoly} -- needs to be added to the \code{packages} list in \code{setup.py}
     1731. Then type \code{sage -b} to build \sage with the new code.
    12301732\end{enumerate}
     1733
     1734\subsection{Special Pragmas}
     1735%malb: needs flashing out, example
     1736If Cython code is either attached or loaded as a \verb|.spyx| file or loaded
     1737from the notebook as a \code{\%cython} block, the follow pragmas are available:
     1738
     1739\begin{description}
     1740\item[clang] may be either c or c++ indicating whether a C or
     1741             C++ compiler should be used
     1742\item[clib] additional libraries to be linked in, the space
     1743            separated list is split and passed to distutils.
     1744\item[cinclude] additional directories to search for header
     1745                files. The space separated list is split and
     1746                passed to distutils.
     1747\end{description}
     1748
     1749For example:
     1750\begin{verbatim}
     1751#clang C++
     1752#clib givaro
     1753#cinclude /usr/local/include/
     1754\end{verbatim}
    12311755
    12321756\subsection{Attaching or Loading {\tt .spyx} Files}
    12331757
     
    12641788\begin{verbatim}
    12651789sage: attach "power2.spyx"
    12661790\end{verbatim}
    1267 Cython is used for its speed.  Here is a timed test on a 2.4 GHz iMac:
     1791Cython is used for its speed.  Here is a timed test on a 2.6 GHz Opteron:
    12681792%skip
    12691793\begin{verbatim}
    12701794sage: time [n for n in range(10^5) if is2pow(n)]
    1271 [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536]
    1272 CPU time: 0.06 s,  Wall time: 0.06 s
     1795[1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768,
     179665536]
     1797CPU times: user 0.60 s, sys: 0.00 s, total: 0.60 s
     1798Wall time: 0.60 s
    12731799\end{verbatim}
    12741800Now, the code in the file \code{power2.spyx} is valid Python, and if
    12751801we copy this to a file \code{powerslow.py} and load that, we get the
     
    12791805sage: load "powerslow.py"
    12801806sage: time [n for n in range(10^5) if is2pow(n)]
    12811807[1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536]
    1282 CPU time: 1.80 s,  Wall time: 1.84 s
     1808CPU times: user 1.01 s, sys: 0.04 s, total: 1.05 s
     1809Wall time: 1.05 s
    12831810\end{verbatim}
    1284 By the way, we could gain even a little more speed -- cutting it down
    1285 to 0.03 s -- with the Cython version with a type declaration, by
    1286 changing \code{def is2pow(n):} to \code{def is2pow(unsigned int n):}.
     1811By the way, we could gain even a little more speed  with the Cython version with
     1812a type declaration, by changing \code{def is2pow(n):} to \code{def
     1813is2pow(unsigned int n):}.
    12871814
    12881815
    12891816
     
    13011828
    13021829(This chapter was written by Martin Albrecht.)
    13031830
     1831%malb: explain why we didn't add matfrobenius to some decl.pxi
     1832
    13041833Here is the step-by-step guide to adding a new PARI functions to \SAGE.
    13051834We use the Frobenius form of a matrix as an example.
    13061835
    1307 The heavy lifting for matrices over integers is implemented using the
     1836Some heavy lifting for matrices over integers is implemented using the
    13081837PARI library. To compute the Frobenius form in PARI the
    13091838\code{matfrobenius} function is used.
    13101839
     
    13251854\code{SAGE_ROOT/devel/sage/sage/libs/pari/gen.pyx}, and this is where we add
    13261855the method \code{matfrobenius}:
    13271856
     1857%malb: that docstring isn't up to Sage's standards, change it in the code and
     1858%      then update it here.
    13281859\begin{verbatim}
    1329 
    13301860    def matfrobenius(self, flag=0):
    13311861        """
    13321862        matfrobenius(M,{flag}): Return the Frobenius form of the
     
    13401870\end{verbatim}
    13411871
    13421872The \code{_sig_on} statement is some magic to prevent SIGSEGVs from the PARI C
    1343 library to crash the \SAGE interpreter by catching these signals. The
    1344 \code{self.new_gen()} call constructs a new SAGE-python-gen object from a given
     1873library to crash the \SAGE interpreter by catching these signals. Note that
     1874\code{self.new_gen()} calls a closing \code{_sig_off} macro. These two
     1875\emph{must always} come in pairs, i.e. every \code{_sig_on} must be matched by
     1876a closing \code{_sig_off}. The \code{self.new_gen()} call constructs a new
     1877SAGE-python-gen object from a given
    13451878pari-C-gen where the pari-C-gen is stored as the SAGE-python-gen.g attribute.
    13461879The \code{matfrobenius} call is just a call to the PARI C library function
    13471880\code{matfrobenius} with the appropriate parameters.
     
    13641897so we can do
    13651898\code{matfrobenius(<some.pari.gen>)} as well as
    13661899\code{<some.pari.gen>.matfrobenius()}:
     1900
     1901%malb: no docstring!
    13671902\begin{verbatim}
    13681903def matfrobenius(self): return pari(self).matfrobenius()
    13691904\end{verbatim}
     
    13721907\code{matrix_integer} class where we call the \code{matfrobenius()}
    13731908method on the PARI object associated to the matrix after doing some
    13741909sanity checking. Then we convert output from PARI to \SAGE objects:
     1910
     1911%malb: this docstring isn't up to Sage's standards.
    13751912\begin{verbatim}
    13761913    def frobenius(self,flag=0):
    13771914        """
     
    14041941           [     0  -2/15   1/15])
    14051942        """
    14061943        if self.nrows()!=self.ncols():
    1407             raise ArithmeticError, "frobenius matrix of non-square matrix not defined."
     1944            raise ArithmeticError, \
     1945            "frobenius matrix of non-square matrix not defined."
    14081946        v = self._pari_().matfrobenius(flag)
    14091947        if flag==0:
    14101948            return self.matrix_space()(v.python())
     
    15402078A ``hard'' example is left as an exercise!  Here are a few ideas.
    15412079
    15422080\begin{itemize}
    1543 
     2081%malb: are these examples still valid.
    15442082\item Write a wrapper for GAP's \code{FreeLieAlgebra} function (or,
    15452083  more generally, all the finitely presented Lie algebra fuunctions in
    15462084  GAP).  This would require creating new Python objects.
     
    15562094\end{itemize}
    15572095
    15582096\section{Singular}
     2097
     2098%malb: this section needs heavy updating, it is outdated, needs libSingular,
     2099%suggests ugly-ish hacks
    15592100
    15602101(The first version of this chapter was written by David Joyner.)
    15612102
     
    17802321% }
    17812322
    17822323
    1783 From looking at the output, notice that our wrapper program will need to
     2324From looking at the output, notice that our wrapper function will need to
    17842325parse the string represented by $L$ above, so
    1785 let us write a separate program to do just that. This requires figuring out how
     2326let us write a separate function to do just that. This requires figuring out how
    17862327to determine where the coordinates of the points are placed in the string L.
    17872328Python has some very useful string manipulation commands to do just that.
    17882329
     
    17902331\begin{verbatim}
    17912332def points_parser(string_points,F):
    17922333    """
    1793     This program will parse a string of points
     2334    This function will parse a string of points
    17942335    of X over a finite field F returned by Singular's NSplaces
    17952336    command into a Python list of points with entries from F.
    17962337    EXAMPLE
     
    21162657\begin{itemize}
    21172658\item The \sage tutorial:
    21182659\code{SAGE_ROOT/devel/doc/tut/tut.tex}
    2119 \item The \sage programming guide:
     2660\item The \sage developer's guide:
    21202661\code{SAGE_ROOT/devel/doc/prog/prog.tex}
    21212662\item Constructions in \sage:
    21222663\code{SAGE_ROOT/devel/doc/const/const.tex}
     
    21452686
    21462687\begin{itemize}
    21472688\item the Google group \code{sage-support}, at
    2148 \url{http://groups.google.com/group/sage-support}.  According to the
    2149 group's official description, ``This group gives help and support to
    2150 those who have problems with \sage (installation, syntax, etc).''
     2689\url{http://groups.google.com/group/sage-support}. This group gives help and
     2690support to those who have problems with \sage (installation, syntax, etc).
     2691The IRC channel \#sage-support on freenode serves the same purpose.
    21512692\item the Google group \code{sage-devel}, at
    2152 \url{http://groups.google.com/group/sage-devel}.  According to the
    2153 group's description, ``This list is for \sage development and is about
    2154 programming, design and technical issues.''  This is a great place to
    2155 post questions about whether certain behavior is a bug, or whether a
    2156 certain feature ought to be implemented (or how it ought to be
    2157 implemented), or similar issues.
     2693\url{http://groups.google.com/group/sage-devel}. This list is for \sage
     2694development and is about programming, design and technical issues. This is a
     2695great place to post questions about whether certain behavior is a bug, or
     2696whether a certain feature ought to be implemented (or how it ought to be
     2697implemented), or similar issues. Also implementation issues are discussed here
     2698and the general direction of the project. The matching IRC channel is
     2699\#sage-devel on freenode.
    21582700\item Mercurial: this is the source control system that is included
    21592701with \SAGE.  Use this to produce patches for \sage.  See
    21602702Chapter~\ref{ch:mercurial} for a full discussion of Mercurial.
     
    21662708
    21672709
    21682710
    2169 \section{Inclusion Procedure for New \sage Code}
     2711\section{Inclusion Procedure for New Packages}
    21702712
    2171 For code to become part of \sage's core, it must meet the
     2713For a package to become part of \sage's standard distribution, it must meet the
    21722714following requirements:
    21732715
    21742716\begin{itemize}
     
    22292771for doing development is available in your copy of \SAGE.
    22302772
    22312773Before using Mercurial,
    2232 make sure to define your username and password so the
     2774make sure to define your username so the
    22332775patches you make are identified as yours.  Make a
    22342776file \verb+~/.hgrc+ in your home directory like this one:
    22352777%skip
     
    23072849
    23082850Note that you can also start a very nice web server that allows you to
    23092851navigate your repository with a web browser, or pull patches from it
    2310 remotely, by typing \code{hg_sage.serve()}.
     2852remotely, by typing \code{hg_sage.serve()}. Then open your webbrowser and point
     2853it to \url{http://localhost:8000} which is the default listening address for
     2854Mecurial.
    23112855
    23122856Finally, if you want to apply a patch file (perhaps you've downloaded
    23132857a patch from the trac server for review), use the command
     
    23832927Put your files in that directory.
    23842928
    23852929\item[(c)]
    2386 Create an executable shell script \code{mypackage-0.1/spkg-install}.
     2930Create an executable shell script \code{mypackage-0.1/spkg-install} following
     2931the skeleton given below.
     2932\begin{verbatim}
     2933 #!/usr/bin/env bash
     2934
     2935if [ "$SAGE_LOCAL" = "" ]; then
     2936   echo "SAGE_LOCAL undefined ... exiting";
     2937   echo "Maybe run 'sage -sh'?"
     2938   exit 1
     2939fi
     2940
     2941cd src
     2942
     2943./configure --prefix="$SAGE_LOCAL"
     2944if [ $? -ne 0 ]; then
     2945   echo "Error configuring PACKAGE_NAME."
     2946   exit 1
     2947fi
     2948
     2949make
     2950if [ $? -ne 0 ]; then
     2951   echo "Error building PACKAGE_NAME."
     2952   exit 1
     2953fi
     2954
     2955make install
     2956if [ $? -ne 0 ]; then
     2957   echo "Error installing PACKAGE_NAME."
     2958   exit 1
     2959fi
     2960\end{verbatim}
     2961
    23872962
    23882963\item[(d)]
    23892964The script \code{spkg-install} is run during installation
     
    24242999automatically install it by typing \code{sage -i mypackage-version.spkg}.
    24253000\end{itemize}
    24263001
    2427 If your package depends on another package, say GAP, then you should
    2428 check that this other package has been installed.  In the case of GAP,
    2429 it is installed into the directory \code{SAGE_ROOT/local/lib/gap-4.4.10/}
    2430 and your \code{spkg-install} script should check that this exists,
    2431 with the code like the following:
     3002If your package depends on another package, say boehm_gc, then you should
     3003check that this other package has been installed. Your \code{spkg-install}
     3004script should check that it exists, with the code like the following:
    24323005%skip
    24333006\begin{verbatim}
    2434 if [ ! -d $SAGE_ROOT/local/lib/gap-4.4.10 ]; then
    2435     echo "This package requires that GAP 4.4.10 is installed."
     3007BOEHM_GC=`cd $SAGE_ROOT/spkg/standard/; ./newest_version boehm_gc`
     3008if [ $? -ne 0 ]; then
     3009    echo "Failed to find boehm_gc.  Please install the boehm_gc spkg"
    24363010    exit 1
    24373011fi
    24383012\end{verbatim}
    24393013
    24403014\emph{Caveat}: Do {\em not} just
    2441 copy to \code{SAGE_ROOT/local/lib/gap*/} since that will copy
     3015copy to e.g. \code{SAGE_ROOT/local/lib/gap*/} since that will copy
    24423016your package to the lib directory of the {\em old} version of GAP if
    24433017GAP is upgraded.
    24443018
     
    24483022that's where you'd put it.  You'd also want to have relevant Python code
    24493023to make the Magma code easily usable.
    24503024
    2451 \textbf{Example}:
    2452 These instructions provide directions for creating a particular
    2453 \sage package.
    2454 
    2455 \begin{itemize}
    2456 \item
    2457 Download \code{guava3.6.tar.gz} (the tarball for GUAVA, the
    2458 GAP error-correcting codes package) from
    2459 \url{http://www.gap-system.org/Packages/guava.html}.
    2460 
    2461 \item
    2462 Suppose you have a directory \code{sagefiles}.
    2463 Within that, create a subdirectory \code{guava-3.6}.
    2464 Extract the tarball into the directory \code{guava-3.6}.
    2465 
    2466 \item
    2467 Create a file \code{guava-3.6/spkg-install} with the following
    2468 contents:
    2469 %skip
    2470 \begin{verbatim}
    2471 #!/bin/sh
    2472 
    2473 if [ ! -d $SAGE_ROOT/local/lib/gap-4.4.10 ]; then
    2474     echo "This package requires that GAP 4.4.10 is installed."
    2475     exit 1
    2476 fi
    2477 
    2478 cp -pr guava-3.6 $SAGE_ROOT/local/lib/gap-4.4.10/pkg/
    2479 
    2480 cd $SAGE_ROOT/local/lib/gap-4.4.10/pkg/guava-3.6
    2481 ./configure ../..
    2482 make
    2483 \end{verbatim}
    2484 
    2485 Make it executable with \code{chmod +x spkg-install}.
    2486 
    2487 \item
    2488 In the directory \code{sagefiles},
    2489 issue the command
    2490 
    2491 %skip
    2492 \begin{verbatim}
    2493     sage -pkg guava-3.6
    2494 \end{verbatim}
    2495 This will do some checks, run tar/bz2, and create the spkg file,
    2496 \code{guava-3.6.spkg}, in the
    2497 directory \code{sagefiles},
    2498 \end{itemize}
    2499 
    2500 To test this, within the \code{sagefiles} directory, type
    2501 %skip
    2502 \begin{verbatim}
    2503     sage -i guava-3.6.spkg
    2504 \end{verbatim}
    2505 It should install and compile the guava program in sage.
    2506 To test its functionality, one could do the following:
    2507 
    2508 \begin{verbatim}
    2509 sage: gap(`LoadPackage("guava")')          # requires optional package
    2510 true
    2511 sage: gap(`HammingCode(3,3)')              # requires optional package
    2512 a linear [13,10,3]1 Hamming (3,3) code over GF(3)
    2513 \end{verbatim}
    2514 
    2515 To  build it again if you've already installed the package, use
    2516 %skip
    2517 \begin{verbatim}
    2518     sage -f guava-3.6.spkg
    2519 \end{verbatim}
    2520 
    2521 
     3025% \textbf{Example}:
     3026% These instructions provide directions for creating a particular
     3027% \sage package.
     3028%
     3029% \begin{itemize}
     3030% \item
     3031% Download \code{guava3.6.tar.gz} (the tarball for GUAVA, the
     3032% GAP error-correcting codes package) from
     3033% \url{http://www.gap-system.org/Packages/guava.html}.
     3034%
     3035% \item
     3036% Suppose you have a directory \code{sagefiles}.
     3037% Within that, create a subdirectory \code{guava-3.6}.
     3038% Extract the tarball into the directory \code{guava-3.6}.
     3039%
     3040% \item
     3041% Create a file \code{guava-3.6/spkg-install} with the following
     3042% contents:
     3043% %skip
     3044% \begin{verbatim}
     3045% #!/bin/sh
     3046%
     3047% if [ ! -d $SAGE_ROOT/local/lib/gap-4.4.10 ]; then
     3048%     echo "This package requires that GAP 4.4.10 is installed."
     3049%     exit 1
     3050% fi
     3051%
     3052% cp -pr guava-3.6 $SAGE_ROOT/local/lib/gap-4.4.10/pkg/
     3053%
     3054% cd $SAGE_ROOT/local/lib/gap-4.4.10/pkg/guava-3.6
     3055% ./configure ../..
     3056% make
     3057% \end{verbatim}
     3058%
     3059% Make it executable with \code{chmod +x spkg-install}.
     3060%
     3061% \item
     3062% In the directory \code{sagefiles},
     3063% issue the command
     3064%
     3065% %skip
     3066% \begin{verbatim}
     3067%     sage -pkg guava-3.6
     3068% \end{verbatim}
     3069% This will do some checks, run tar/bz2, and create the spkg file,
     3070% \code{guava-3.6.spkg}, in the
     3071% directory \code{sagefiles},
     3072% \end{itemize}
     3073%
     3074% To test this, within the \code{sagefiles} directory, type
     3075% %skip
     3076% \begin{verbatim}
     3077%     sage -i guava-3.6.spkg
     3078% \end{verbatim}
     3079% It should install and compile the guava program in sage.
     3080% To test its functionality, one could do the following:
     3081%
     3082% \begin{verbatim}
     3083% sage: gap(`LoadPackage("guava")')          # requires optional package
     3084% true
     3085% sage: gap(`HammingCode(3,3)')              # requires optional package
     3086% a linear [13,10,3]1 Hamming (3,3) code over GF(3)
     3087% \end{verbatim}
     3088%
     3089% To  build it again if you've already installed the package, use
     3090% %skip
     3091% \begin{verbatim}
     3092%     sage -f guava-3.6.spkg
     3093% \end{verbatim}
     3094%
     3095%
    25223096
    25233097
    25243098\chapter{The \sage Trac Server: Submitting Patches and Packages}
     
    26463220Download it (from the window displaying the patch, see the
    26473221``Download'' option at the bottom of the page).  Apply it (using
    26483222\code{hg_sage.patch('filename')}, for example) to your copy of \sage,
    2649 and build \sage with the new code by typing \code{sage -b} (for
    2650 patches to .py files) or \code{sage -ba} (for patches to .pyx files).
     3223and build \sage with the new code by typing \code{sage -b}.
    26513224
    26523225Now ask yourself questions like these:
    26533226\begin{itemize}
     
    26873260
    26883261\section{Closing Tickets}
    26893262
    2690 Don't close tickets.  That is the job of the \sage administrators.  If
     3263Don't close tickets.  That is the job of the acting \sage release manager.  If
    26913264you feel strongly that a ticket should be closed or deleted, send
    26923265email to the current release manager explaining the situation.
    26933266