17. Interface issues

17.1 Background jobs

Yes, a SAGE job can be run in the background on a UNIX system. The canonical thing to do is type

nohup sage < command_file  > output_file &

The advantage of nohup is that SAGE will continue running after you log out.

Currently SAGE will appears as ``ipython" or ``python" in the output of the (unix) ``top" command, but in future versions of SAGE it will appears as ``sage".

17.2 Referencing SAGE

To reference SAGE, please add the following to your bibliography:

\bibitem[S]{S} William Stein, {\it SAGE: Software for Algebra and 
Geometry Experimentation}, 
http://modular.math.washington.edu/sage/, http://sage.scipy.org/

Here is the bibtex entry:

@manual{S,
    AUTHOR = {William Stein},
     TITLE = {SAGE: Software for Algebra and Geometry Experimentation},
       URL = {http://modular.math.washington.edu/sage/, http://sage.scipy.org/},

If you prefer a published entry:

\bibitem[SJ]{SJ} William Stein, David Joyner, 
{\it SAGE: System for Algebra and Geometry Experimentation}, 
Comm. Computer Algebra 39(2005)61-64.
http://modular.math.washington.edu/sage/, http://sage.scipy.org/

Here is the bibtex entry:

@article{SJ05,
    AUTHOR = {William Stein and David Joyner},
     TITLE = {SAGE: System for Algebra and Geometry Experimentation},
   JOURNAL = {Comm. Computer Algebra},
    VOLUME = {39},
      YEAR = {2005},
    NUMBER = {2},
     PAGES = {61--64},
       URL = {http://modular.math.washington.edu/sage/, http://sage.scipy.org/},
}

If you happen to use the SAGE interface to PARI, GAP or Singular, you should definitely reference them as well. Likewise, if you use code that is implemented using PARI, GAP, or Singular, reference the corresponding system (you can often tell from the SAGE documentation if PARI, GAP, or Singular is used in the implementation of a function).

For PARI, you may use

@manual{PARI2,
      organization = "{The PARI~Group}",
      title        = "{PARI/GP, version {\tt 2.1.5}}",
      year         = 2004,
      address      = "Bordeaux",
      note         = "available from \url{http://pari.math.u-bordeaux.fr/}"
    }

\bibitem{PARI2} PARI/GP, version {\tt 2.1.5}, Bordeaux, 2004, 
\url{http://pari.math.u-bordeaux.fr/}.

(replace the version number by the one you used).

For GAP, you may use

[GAP04] The GAP Group, GAP -- Groups, Algorithms, and Programming, 
Version 4.4; 2005. (http://www.gap-system.org)

@manual{GAP4,
    key          = "GAP",
    organization = "The GAP~Group",
    title        = "{GAP -- Groups, Algorithms, and Programming,
                    Version 4.4}",
    year         = 2005,
    note         = "{\tt http://www.gap-system.org}",
    keywords     = "groups; *; gap; manual"}

\bibitem[GAP]{GAP4}
  The GAP~Group, \emph{GAP -- Groups, Algorithms, and Programming, Version 4.4}; 2005,
  {\tt http://www.gap-system.org}.

For Singular, you may use

[GPS05] G.-M. Greuel, G. Pfister, and H. Sch\"onemann.
{\sc Singular} 3.0. A Computer Algebra System for Polynomial
Computations. Centre for Computer Algebra, University of
Kaiserslautern (2005). {\tt http://www.singular.uni-kl.de}.

@TechReport{GPS05,
  author =       {G.-M. Greuel and G. Pfister and H. Sch\"onemann},
  title =        {{\sc Singular} 3.0},
  type =         {{A Computer Algebra System for Polynomial Computations}},
  institution =  {Centre for Computer Algebra},
  address =      {University of Kaiserslautern},
  year =         {2005},
  note =         {{\tt http://www.singular.uni-kl.de}},
}

\bibitem[GPS05]{GPS05}
G.-M.~Greuel, G.~Pfister, and H.~Sch\"onemann.
\newblock {{\sc Singular} 3.0}. A Computer Algebra System for Polynomial Computations.
\newblock Centre for Computer Algebra, University of Kaiserslautern (2005).
\newblock {\tt http://www.singular.uni-kl.de}.

17.3 Logging your SAGE session

Yes you can log your sessions.

(a) Modify line 186 of the .ipythonrc file (or open .ipythonrc into an editor and search for ``logfile''). This will only log your input lines, not the output.

(b) You can also write the output to a file, by running SAGE in the background (§17.1).

(c) Start sage in a KDE konsole (this only work in linux). Go to settings $\rightarrow$ History ... and select unlimited. Start your sage session. When ready, go to edit $\rightarrow$ save history as ....

Some interfaces (such as the interface to Singular or that to GAP) allow you to create a log file. For Singular, there is a logfile option (in singular.py). In GAP, use the command LogTo.

17.4 LaTeX conversion

Yes, you can output some of your results into latex.

sage: M = MatrixSpace(RealField(),3,3)
sage: A = M([1,2,3, 4,5,6, 7,8,9])
sage: print latex(A)
\left(\begin{array}{rrr}
1.0000000000000000&2.0000000000000000&3.0000000000000000\\
4.0000000000000000&5.0000000000000000&6.0000000000000000\\
7.0000000000000000&8.0000000000000000&9.0000000000000000
\end{array}\right)

sage: view(A)

At this point a dvi preview should automatically be called to display in a separate window the latex output produced.

Latex previewing for multivariate polynomials and rational functions is also available:

sage: x = MPolynomialRing(QQ,3).gens()
sage: f = x[0] + x[1] - 2*x[1]*x[2]
sage: h = f /(x[1] + x[2])
sage: print latex(h)
      \frac{x_{1} - 2 x_{1}x_{2} + x_{0}}{x_{2} + x_{1}}

17.5 SAGE and other computer algebra systems

If foo is a Pari, GAP (without ending semicolon), Singular, Maxima command, resp., enter gp("foo") for Pari, gap.eval("foo"), singular.eval("foo"), maxima("foo"), resp.. These programs merely send the command string to the external program, execute it, and read the result back into SAGE. Therefore, these will not work if the external program is not installed and in your PATH. (At the present, you will need a unix system for these to work.)

17.6 Command-line SAGE help

If you know only part of the name of a SAGE command and want to know where it occurs in SAGE, a new option for SAGE 0.10.11 has been added to make it easier to hunt it down. Just type sage -grep <string> to find all occurences of <string> in the SAGE source code. For example,

was@form:~/s/local/bin$ sage -grep berlekamp_massey
matrix/all.py:from berlekamp_massey import berlekamp_massey
matrix/berlekamp_massey.py:def berlekamp_massey(a):
matrix/matrix.py:import berlekamp_massey
matrix/matrix.py:            g =
berlekamp_massey.berlekamp_massey(cols[i].list())

Type help(foo) or foo?? for help and foo.[tab] for searching of SAGE commands. Type help("") for Python commands.

For example

help(Matrix)

returns

Help on function Matrix in module sage.matrix.constructor:

Matrix(R, nrows, ncols, entries = 0, sparse = False)
    Create a matrix.

    INPUT:
        R -- ring
        nrows -- int; number of rows
        ncols -- int; number of columns
        entries -- list; entries of the matrix
        sparse -- bool (default: False); whether or not to store matrices as sparse
    OUTPUT:
        a matrix

    EXAMPLES:
        sage: Matrix(RationalField(), 2, 2, [1,2,3,4])
        [1 2]
        [3 4]

        sage: Matrix(FiniteField(5), 2, 3, range(6))
        [0 1 2]
        [3 4 0]

        sage: Matrix(IntegerRing(), 10, 10, range(100)).parent()
        Full MatrixSpace of 10 by 10 dense matrices over Integer Ring

        sage: Matrix(IntegerRing(), 10, 10, range(100), sparse = True).parent()
        Full MatrixSpace of 10 by 10 sparse matrices over Integer Ring

in a new screen. Type q to return to the SAGE screen.

17.7 Reading and importing files into SAGE

A file ``import"ed into SAGE must end in a ``.py", e.g., foo.py and contain legal Python syntax. For a simple example see §4.1 with the rubik's cube group example above.

Another way to read a file in is to use the load or attach command. Create a file called example.sage (located in the home directory of SAGE) with the following content:

print "Hello World"
print 2^3

Read in and execute example.sage file using the load command.

sage: load "example.sage"
Hello World
8

You can also attach a SAGE file to a running session:

sage: attach "example.sage"
Hello World
8

Now if you change example.sage and enter one blank line into SAGE, then the contents of example.sage will be automatically reloaded into SAGE:

sage: !emacs example.sage&     #change 2^3 to 2^4
sage:                          #hit return
***************************************************
                Reloading 'example.sage'
***************************************************
Hello World
16

17.8 Installation for the impatient

We shall explain the basic steps for installing the most recent version of SAGE (which is the ``source'' version, not the ``binary'').

Download sage-*.tar (where * denotes the version number) from the website and save into a directory, say SAGEHOME. Type tar zxvf sage-*.tar in HOME.
cd sage-* (we call this SAGEHOME) and type make. Now be patient because this process make take 30 minutes or so.
Optional: When the compilation is finished, type on the command line in the SAGE home directory:
```
./sage -i database_jones_numfield-2005.11.03
./sage -i database_gap-4.4.7
./sage -i database_cremona_ellcurve-2005.11.03
./sage -i gap_gpl_packages-4.4.6_2
```
This last package loads the GAP GPL'd packages DESIGN, FactInt, GAPDoc, GRAPE, GUAVA 2.5, LAGUNA, SONATA 2.3, and TORIC . It also compiles (automatically) the C programs in GUAVA and GRAPE.
Other optional packages to install are at http://modular.math.washington.edu/sage/packages/optional/.
Another way: download packages from http://sage.scipy.org/sage/packages/optional/ and save to the directory SAGEHOME. Type
```
/sage -i sage-package.spkg
```
for each sage-package you download. This might be useful if you have a CD of these packages but no (or a very slow) internet connection.
Start SAGE by typing ./sage on the command line. You must create a GAP workspace. For example, if you want to create a workspace of 750M and with GRAPE, SONATA, GUAVA and LAGUNA preloaded, type at the SAGE prompt:
```
sage: gap.eval('LoadPackage("grape")')
      'true'
sage: gap.eval('LoadPackage("sonata")')
      'true'
sage: gap.eval('LoadPackage("braid")')
      'true'
sage: gap.eval('LoadPackage("laguna")')
      'true'
sage: gap_reset_workspace(750)
```
For the default, just use gap_reset_workspace(). Now exit SAGE by typing ctl-D. On restarting, once a GAP command is interfaced with, the above GAP packages are automatically loaded. The command gap_reset_workspace() is only needed once (unless you install a new version of SAGE).
If you want to build the documentation, cd devel/doc and type ./rebuild. This requires having latex and latex2html installed.

17.9 Python language program code for SAGE commands

Let's say you want to know what the Python program is for the SAGE command to compute the center of a permutation group. Use SAGE's help interface to find the file name:

sage: ?PermutationGroup.center
Type:           instancemethod
Base Class:     <type 'instancemethod'>
String Form:    <unbound method PermutationGroup.center>
Namespace:      Interactive
File:           /home/wdj/sage/local/lib/python2.4/site-packages/sage/groups/permgroup.py
Definition:     PermutationGroup.center(self)

Now you know that the command is located in the permgroup.py file and you know the directory to look for that Python module. You can use an editor to read the code itself.

17.10 ``Special functions'' in SAGE

SAGE has several special functions:

Bessel functions and Airy functions
spherical harmonic functions
spherical Bessel functions (of the 1st and 2nd kind)
spherical Hankel functions (of the 1st and 2nd kind)
Jacobi elliptic functions
complete/incomplete elliptic integrals
hyperbolic trig functions (for completeness, since they are special cases of elliptic functions)

and orthogonal polynomials

chebyshev_T (n, x), chebyshev_U (n, x) - the Chebyshev polynomial of the first, second kind for integers n > -1.
laguerre (n, x), gen_laguerre (n, a, x) - the (generalized) Laguerre poly. for n > -1.
legendre_P (n, x), legendre_Q (n, x), gen_legendre_P (n, x), gen_legendre_Q (n, x) - the (generalized) Legendre function of the first, second kind for integers n > -1.
hermite (n,x) - the Hermite poly. for integers n > -1.
jacobi_P (n, a, b, x) - the Jacobi polynomial for integers n > -1 and a and b symbolic or a > -1 and b > -1.
ultraspherical (n,a,x) - the ultraspherical polynomials for integers n > -1. The ultraspherical polynomials are also known as Gegenbauer polynomials.

In SAGE these are restricted to numerical evaluation and plotting but via maxima, some symbolic manipulationis allowed:

sage: maxima.eval("f:bessel_y (v, w)")
 'bessel_y(v,w)'
sage: maxima.eval("diff(f,w)")
 'bessel_y(v - 1,w) - v*bessel_y(v,w)/w'
sage: maxima.eval("diff (jacobi_sn (u, m), u)")
 'jacobi_cn(u,m)*jacobi_dn(u,m)'
sage: jsn = lambda x: jacobi("sn",x,1)
sage: P = plot(jsn,0,1); Q = plot(lambda x:bessel_Y( 1, x), 1/2,1)

Now type show(P), show(Q).

In addition to maxima, pari and octave also have special functions (in fact, some of pari's special functions are wrapped in SAGE).

Here's an example using SAGE's interface (located in sage/interfaces/octave.py) with octave (http://www.octave.org/doc/index.html).

sage: octave("atanh(1.1)")   ## requires optional octave
(1.52226,-1.5708)

Here's an example using SAGE's interface to pari's special functions.

sage: pari('2+I').besselk(3)
0.04559077184075505871203211094 + 0.02891929465820812820828883526*I     # 32-bit
0.045590771840755058712032110938791854704 + 0.028919294658208128208288835257608789842*I   # 64-bit
sage: pari('2').besselk(3)  # random
 0.061510458471742038

The last command can also be executed using the SAGE command

sage: bessel_K(3,2)
 0.061510458471742038
sage: bessel_K(3,2,100)
 0.061510458471742037656820071452903

17.11 What is SAGE?

SAGE is a framework for number theory, algebra, and geometry computation that is initially being designed for computing with elliptic curves and modular forms. The long-term goal is to make it much more generally useful for algebra, geometry, and number theory. It is open source and freely available under the terms of the GPL. The section titles in the reference manual gives a rough idea of the topics covered in SAGE.

17.11.1 History of SAGE

SAGE was started by William Stein while at Harvard University in the Fall of 2004, with version 0.1 released in January of 2005. That version included Pari, but not GAP or Singular. Version 0.2 was released in March, version 0.3 in April, version 0.4 in July. During this time, support for Cremona's database, multivariate polynomials and large finite fields was added. Also, more documentation was written. Version 0.5 beta was released in August, version 0.6 beta in September, and version 0.7 later that month. During this time, more support for vector spaces, rings, modular symbols, and windows users was added. As of 0.8, released in October 2005, SAGE contained the full distribution of GAP, though some of the GAP databases have to be added separately, and Singular. Adding Singular was not easy, due to the difficulty of combiling Singular from source. Version 0.9 was released in November. This version when through 34 releases! As of version 0.9.34 (definitely by version 0.10.0), Maxima and clisp were included with SAGE. Version 0.10.0 was released January 12, 2006. The release of SAGE 1.0 was made early February, 2006. As of September, 2006, the latest release is 1.3.7.3.

During all this time, most of the work was done by William Stein but many people have contributed significant code and other expertise (such as assistance in compiling on various OS's). Generally code authors are acknowledged in the AUTHOR section of the Python docstring of their file. As of late Sepember 2006, here is an alphabetical list of those helping:

Martin Albrecht, Jennifer Balakrishnan, Tom Boothby, Robert Bradshaw, Iftikhar Burhanuddin, David Harvey, Wilson Cheung, Craig Citro, Alex Clemesha, John Cremona, Doug Cutrell, Didier Deshommes, Jon Hanke, Naqi Jaffery, David Joyner, Josh Kantor, Kiran Kedlaya, David Kirkby, Emily Kirkman, David Kohel, Kate Minola, Bobby Moretti, Gregg Musiker, Yi Qiang, David Roe, Kyle Schalm, Steven Sivek, Jaap Spies, William Stein (Project leader), Gonzalo Tornaria, Justin Walker, Mark Watkins, Joe Wetherell, Gary Zablackis.

This does not even count those many people (such as Steve Linton and Karim Belebas for example) who helped integrate SAGE with one of the software components.

See About this document... for information on suggesting changes.