The Interactive Shell¶

In most of this tutorial, we assume you start the Sage interpreter using the sage command. This starts a customized version of the IPython shell, and imports many functions and classes, so they are ready to use from the command prompt. Further customization is possible by editing the $SAGE_ROOT/ipythonrc file. Upon starting Sage, you get output similar to the following:

┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 9.7, Release Date: 2022-01-10                     │
│ Using Python 3.10.4. Type "help()" for help.                       │
└────────────────────────────────────────────────────────────────────┘


sage:

To quit Sage either press Ctrl-D or type quit or exit.

Sage

sage: quit
Exiting Sage (CPU time 0m0.00s, Wall time 0m0.89s)

Python

>>> from sage.all import *
>>> quit
Exiting Sage (CPU time 0m0.00s, Wall time 0m0.89s)

The wall time is the time that elapsed on the clock hanging from your wall. This is relevant, since CPU time does not track time used by subprocesses like GAP or Singular.

(Avoid killing a Sage process with kill -9 from a terminal, since Sage might not kill child processes, e.g., Maple processes, or cleanup temporary files from $HOME/.sage/tmp.)

Logging Input and Output¶

Logging your Sage session is not the same as saving it (see Saving and Loading Complete Sessions for that). To log input (and optionally output) use the logstart command. Type logstart? for more details. You can use this command to log all input you type, all output, and even play back that input in a future session (by simply reloading the log file).

was@form:~$ sage
┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 9.7, Release Date: 2022-01-10                     │
│ Using Python 3.10.4. Type "help()" for help.                       │
└────────────────────────────────────────────────────────────────────┘

sage: logstart setup
Activating auto-logging. Current session state plus future input saved.
Filename       : setup
Mode           : backup
Output logging : False
Timestamping   : False
State          : active
sage: E = EllipticCurve([1,2,3,4,5]).minimal_model()
sage: F = QQ^3
sage: x,y = QQ['x,y'].gens()
sage: G = E.gens()
sage:
Exiting Sage (CPU time 0m0.61s, Wall time 0m50.39s).
was@form:~$ sage
┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 9.7, Release Date: 2022-01-10                     │
│ Using Python 3.10.4. Type "help()" for help.                       │
└────────────────────────────────────────────────────────────────────┘

sage: load("setup")
Loading log file <setup> one line at a time...
Finished replaying log file <setup>
sage: E
Elliptic Curve defined by y^2 + x*y  = x^3 - x^2 + 4*x + 3 over Rational
Field
sage: x*y
x*y
sage: G
[(2 : 3 : 1)]

If you use Sage in the Linux KDE terminal konsole then you can save your session as follows: after starting Sage in konsole, select “settings”, then “history…”, then “set unlimited”. When you are ready to save your session, select “edit” then “save history as…” and type in a name to save the text of your session to your computer. After saving this file, you could then load it into an editor, such as xemacs, and print it.

Paste Ignores Prompts¶

Suppose you are reading a session of Sage or Python computations and want to copy them into Sage. But there are annoying >>> or sage: prompts to worry about. In fact, you can copy and paste an example, including the prompts if you want, into Sage. In other words, by default the Sage parser strips any leading >>> or sage: prompt before passing it to Python. For example,

Sage

sage: 2^10
1024
sage: sage: sage: 2^10
1024
sage: >>> 2^10
1024

Python

>>> from sage.all import *
>>> Integer(2)**Integer(10)
1024
>>> sage: sage: Integer(2)**Integer(10)
1024
>>> >>> Integer(2)**Integer(10)
1024

Other IPython tricks¶

As noted above, Sage uses IPython as its front end, and so you can use any of IPython’s commands and features. You can read the full IPython documentation. Meanwhile, here are some fun tricks – these are called “Magic commands” in IPython:

You can use %edit (or %ed or ed) to open an editor, if you want to type in some complex code. Before you start Sage, make sure that the EDITOR environment variable is set to your favorite editor (by putting export EDITOR=/usr/bin/emacs or export EDITOR=/usr/bin/vim or something similar in the appropriate place, like a .profile file). From the Sage prompt, executing %edit will open up the named editor. Then within the editor you can define a function:
```
def some_function(n):
    return n**2 + 3*n + 2
```
Save and quit from the editor. For the rest of your Sage session, you can then use some_function. If you want to modify it, type %edit some_function from the Sage prompt.
If you have a computation and you want to modify its output for another use, perform the computation and type %rep: this will place the output from the previous command at the Sage prompt, ready for you to edit it.
Sage
sage: f(x) = cos(x) sage: f(x).derivative(x) -sin(x)
Python
>>> from sage.all import * >>> __tmp__=var("x"); f = symbolic_expression(cos(x)).function(x) >>> f(x).derivative(x) -sin(x)
At this point, if you type %rep at the Sage prompt, you will get a new Sage prompt, followed by -sin(x), with the cursor at the end of the line.

For more, type %quickref to get a quick reference guide to IPython. As of this writing (April 2011), Sage uses version 0.9.1 of IPython, and the documentation for its magic commands is available online. Various slightly advanced aspects of magic command system are documented here in IPython.

Errors and Exceptions¶

When something goes wrong, you will usually see a Python “exception”. Python even tries to suggest what raised the exception. Often you see the name of the exception, e.g., NameError or ValueError (see the Python Library Reference [PyLR] for a complete list of exceptions). For example,

Sage

sage: 3_2
------------------------------------------------------------
   File "<console>", line 1
     ZZ(3)_2
           ^
SyntaxError: invalid ...

sage: EllipticCurve([0,infinity])
------------------------------------------------------------
Traceback (most recent call last):
...
TypeError: Unable to coerce Infinity (<class 'sage...Infinity'>) to Rational

Python

>>> from sage.all import *
>>> Integer(3_2)
------------------------------------------------------------
   File "<console>", line 1
     ZZ(3)_2
           ^
SyntaxError: invalid ...

>>> EllipticCurve([Integer(0),infinity])
------------------------------------------------------------
Traceback (most recent call last):
...
TypeError: Unable to coerce Infinity (<class 'sage...Infinity'>) to Rational

The interactive debugger is sometimes useful for understanding what went wrong. You can toggle it on or off using %pdb (the default is off). The prompt ipdb> appears if an exception is raised and the debugger is on. From within the debugger, you can print the state of any local variable, and move up and down the execution stack. For example,

Sage

sage: %pdb
Automatic pdb calling has been turned ON
sage: EllipticCurve([1,infinity])
---------------------------------------------------------------------------
<class 'exceptions.TypeError'>             Traceback (most recent call last)
...

ipdb>

Python

>>> from sage.all import *
>>> %pdb
Automatic pdb calling has been turned ON
>>> EllipticCurve([Integer(1),infinity])
---------------------------------------------------------------------------
<class 'exceptions.TypeError'>             Traceback (most recent call last)
...

ipdb>

For a list of commands in the debugger, type ? at the ipdb> prompt:

ipdb> ?

Documented commands (type help <topic>):
========================================
EOF    break  commands   debug    h       l     pdef   quit    tbreak
a      bt     condition  disable  help    list  pdoc   r       u
alias  c      cont       down     ignore  n     pinfo  return  unalias
args   cl     continue   enable   j       next  pp     s       up
b      clear  d          exit     jump    p     q      step    w
whatis where

Miscellaneous help topics:
==========================
exec  pdb

Undocumented commands:
======================
retval  rv

Type Ctrl-D or quit to return to Sage.

Reverse Search and Tab Completion¶

Reverse search: Type the beginning of a command, then Ctrl-p (or just hit the up arrow key) to go back to each line you have entered that begins in that way. This works even if you completely exit Sage and restart later. You can also do a reverse search through the history using Ctrl-r. All these features use the readline package, which is available on most flavors of Linux.

To illustrate tab completion, first create the three dimensional vector space $V=\QQ^3$ as follows:

Sage

sage: V = VectorSpace(QQ,3)
sage: V
Vector space of dimension 3 over Rational Field

Python

>>> from sage.all import *
>>> V = VectorSpace(QQ,Integer(3))
>>> V
Vector space of dimension 3 over Rational Field

You can also use the following more concise notation:

Sage

sage: V = QQ^3

Python

>>> from sage.all import *
>>> V = QQ**Integer(3)

Then it is easy to list all member functions for $V$ using tab completion. Just type V., then type the Tab key on your keyboard:

Sage

sage: V.[tab key]
V._VectorSpace_generic__base_field
...
V.ambient_space
V.base_field
V.base_ring
V.basis
V.coordinates
...
V.zero_vector

Python

>>> from sage.all import *
>>> V.[tab key]
V._VectorSpace_generic__base_field
...
V.ambient_space
V.base_field
V.base_ring
V.basis
V.coordinates
...
V.zero_vector

If you type the first few letters of a function, then the Tab key, you get only functions that begin as indicated.

Sage

sage: V.i[tab key]
V.is_ambient  V.is_dense    V.is_full     V.is_sparse

Python

>>> from sage.all import *
>>> V.i[tab key]
V.is_ambient  V.is_dense    V.is_full     V.is_sparse

If you wonder what a particular function does, e.g., the coordinates function, type V.coordinates? for help or V.coordinates?? for the source code, as explained in the next section.

Saving and Loading Complete Sessions¶

Sage has very flexible support for saving and loading complete sessions.

The command save_session(sessionname) saves all the variables you’ve defined in the current session as a dictionary in the given sessionname. (In the rare case when a variable does not support saving, it is simply not saved to the dictionary.) The resulting file is an .sobj file and can be loaded just like any other object that was saved. When you load the objects saved in a session, you get a dictionary whose keys are the variables names and whose values are the objects.

You can use the load_session(sessionname) command to load the variables defined in sessionname into the current session. Note that this does not wipe out variables you’ve already defined in your current session; instead, the two sessions are merged.

First we start Sage and define some variables.

Sage

sage: E = EllipticCurve('11a')
sage: M = ModularSymbols(37)
sage: a = 389
sage: t = M.T(2003).matrix(); t.charpoly().factor()
 _4 = (x - 2004) * (x - 12)^2 * (x + 54)^2

Python

>>> from sage.all import *
>>> E = EllipticCurve('11a')
>>> M = ModularSymbols(Integer(37))
>>> a = Integer(389)
>>> t = M.T(Integer(2003)).matrix(); t.charpoly().factor()
 _4 = (x - 2004) * (x - 12)^2 * (x + 54)^2

Next we save our session, which saves each of the above variables into a file. Then we view the file, which is about 3K in size.

Sage

sage: save_session('misc')
Saving a
Saving M
Saving t
Saving E
sage: quit
was@form:~/tmp$ ls -l misc.sobj
-rw-r--r--  1 was was 2979 2006-01-28 19:47 misc.sobj

Python

>>> from sage.all import *
>>> save_session('misc')
Saving a
Saving M
Saving t
Saving E
>>> quit
was@form:~/tmp$ ls -l misc.sobj
-rw-r--r--  1 was was 2979 2006-01-28 19:47 misc.sobj

Finally we restart Sage, define an extra variable, and load our saved session.

Sage

sage: b = 19
sage: load_session('misc')
Loading a
Loading M
Loading E
Loading t

Python

>>> from sage.all import *
>>> b = Integer(19)
>>> load_session('misc')
Loading a
Loading M
Loading E
Loading t

Each saved variable is again available. Moreover, the variable b was not overwritten.

Sage

sage: M
Full Modular Symbols space for Gamma_0(37) of weight 2 with sign 0
and dimension 5 over Rational Field
sage: E
Elliptic Curve defined by y^2 + y = x^3 - x^2 - 10*x - 20 over Rational
Field
sage: b
19
sage: a
389

Python

>>> from sage.all import *
>>> M
Full Modular Symbols space for Gamma_0(37) of weight 2 with sign 0
and dimension 5 over Rational Field
>>> E
Elliptic Curve defined by y^2 + y = x^3 - x^2 - 10*x - 20 over Rational
Field
>>> b
19
>>> a
389

The Interactive Shell¶

Your Sage Session¶

Logging Input and Output¶

Paste Ignores Prompts¶

Timing Commands¶

Other IPython tricks¶

Errors and Exceptions¶

Reverse Search and Tab Completion¶

Integrated Help System¶

Saving and Loading Individual Objects¶

Saving as Text¶

Saving and Loading Complete Sessions¶