Sage FAQ: Frequently Asked Questions

Contents

  1. Introduction
    1. What is Sage?
    2. Does it run on my computer?
  2. Getting Sage
    1. Can I try out Sage without downloading anything?
    2. How do I get a Sage program I can run immediately?
    3. How do I get the Sage source code?
    4. How do I get a previous release of Sage?
  3. Installing and running Sage
    1. Wouldn't it be way better if Sage did not ship as a gigantic bundle?
    2. How do I compile the source to Sage?
    3. How do I run Sage on a platform other than VirtualBox or Windows?
    4. How do I run Sage with VirtualBox?
    5. How do I create my own Sage virtual machine ?
    6. How do I run Sage in Windows?
    7. I installed Sage on a Unix or Linux server where I have an account, but my personal computer runs Windows. How do I access the Sage notebook?
    8. How do I run a parallel build?
    9. How do I run Sage in a browser that is not the system default
    10. How to get Sage's Python to recognize my system's Tcl/Tk install?
    11. How do I import Sage into a Python script?
    12. I'm seeing an error about 'Permission denied' on a file called sage-flags.txt
    13. I used Debian/Ubuntu to install Sage 3.0.5 and that version is giving lots of errors. What can I do?
    14. Can I see a calculation step-by-step?
  4. Developing in Sage
    1. What tools do I need to develop in Sage?
    2. Where is the source code to Sage?
    3. How can I rebuild the Sage library in parallel?
  5. Working in Sage
    1. What exactly does Sage do when I type 0.6**2?
    2. Why is Sage's command history different than Magma's
    3. How do I work with noncommutative variables
    4. How do I save an object so I don't have to compute it each time I open a worksheet?
    5. I get an error from jsMath or the math symbols don't look right when displaying in the notebook
  6. Getting help
    1. How do I get help?
  7. Other questions

1. Introduction

1.1. What is Sage?

Sage is a comprehensive open-source mathematics software suite that has the mission statement "Creating a viable free open source alternative to Magma, Maple, Mathematica, and Matlab." See http://www.sagemath.org/ for more details.

1.2. Does it run on my computer?

Probably, we are trying to support a wide range of computers. See the supported platforms list for details.

2. Getting Sage

2.1. Can I try out Sage without downloading anything?

Yes! Go to http://www.sagenb.org/ and set up a free account. If you log in, you will be working on a free Sage notebook server that will work identically to the one you get with Sage.

2.2. How do I get a Sage program I can run immediately?

Go to http://www.sagemath.org/download.html and click on the link for the binary for your operating system.

2.3. How do I get the Sage source code?

Go to http://www.sagemath.org/download-source.html to download the tar archive for any release of Sage.

2.4. How do I get a previous release of Sage?

Go to http://www.sagemath.org/src-old to download the tar archive for any release of Sage.

3. Installing and running Sage

3.1. Wouldn't it be way better if Sage did not ship as a gigantic bundle?

This has been discussed over and over again and it plainly doesn't work.

3.2. How do I compile the source to Sage?

Download the source tar archive, extract the archive, change your directory to be inside of it, and read the README.txt file there. Basically, after making sure you have the proper prerequisite tools installed, you type make.

3.3. How do I run Sage on a platform other than VirtualBox or Windows?

Change your directory to the sage directory and run ./sage

To start an online notebook server, start Sage and type notebook() at the sage command prompt.

3.4. How do I run Sage with VirtualBox?

You must install the VirtualBox software available at http://www.virtualbox.org/wiki/Downloads. Then run the downloaded Sage virtual appliance and follow these additional instructions.

3.5. How do I create my own Sage virtual machine ?

See these instructions.

3.6. How do I run Sage in Windows?

Windows is currently supported via the VirtualBox image, so see the instructions for running the Sage virtual appliance. See windows for information on efforts to make a native port of Sage to Windows.

3.7. I installed Sage on a Unix or Linux server where I have an account, but my personal computer runs Windows. How do I access the Sage notebook?

You can use port forwarding with ssh to interact with the notebook via a Windows browser.

Log into the server, and run the Sage notebook. Typically this involves the command

./sage -notebook

from within the Sage directory.

If this is the first time you have used the Sage notebook, the system will prompt you to create an admin password. The system will then give you instructions that look like this:

**************************************************
*                                                *
* Open your web browser to http://localhost:8080 *
*                                                *
**************************************************

Make a note of the number after localhost (in our example, 8080). This is the port that the notebook expects you to use.

Now, close the notebook using Ctrl-C, and log out of the server. You want to open a new ssh connection using port forwarding.

If you are using the free ssh program PuTTy, you should first enter the name of your server. Then find the port forwarding options: you can locate these by going to Connections, then SSH, then Tunneling in the "Category" menus on the left. Enter the port number (e.g., 8080) in the Source Port box, and then enter localhost: followed by the port number (e.g., localhost:8080) in the Destination box. Make sure the Local radio button is selected, and click Add. Then hit Open to log into your server.

Return to your sage directory, and run

./sage -notebook

again.

This time, when the notebook prompts you to open your web browser to a particular address, you should do so (in our example, that means opening a new browser window and going to http://localhost:8080 ). Log in using the username admin and the password you created. Once you have done so, you can create new users by following the Settings link and then choosing the Manage Users option.

3.8. How do I run a parallel build?

The command

export MAKE="make -j8"

will enable 8 threads for parts of the build that support parallelism. Change the number 8 as appropriate to suit the number of cores on your system.

The command

export SAGE_PARALLEL_SPKG_BUILD="yes"

will enable building the spkgs in parallel.

3.9. How do I run Sage in a browser that is not the system default

Issue this command "env SAGE_BROWSER=opera /usr/bin/sage -notebook" either from the command prompt or as a menu command for Sage. Assumes a Linux operating system, Opera as the browser, and I happen to use KDE as my desktop.

3.10. How to get Sage's Python to recognize my system's Tcl/Tk install?

It may be that you have Tcl/Tk installed and that your system's Python recognizes it but Sage's Python does not. To fix that, install the tcl/tk development library. On Ubuntu, this is the command

sudo apt-get install tk8.5-dev

Next, reinstall Sage's Python:

sage -f python-2.5.2.p8

This will pick up the tcl/tk library automatically. If

sage: import _tkinter
sage: import Tkinter

does not raise an ImportError then it worked.

3.11. How do I import Sage into a Python script?

Yes you can import Sage as a library in a Python script. One caveat is that you need to run that Python script using the version of Python that is bundled with Sage (e.g. Sage 5.8 has Python 2.7.3). To import Sage, put the following in your Python script:

from sage.all import *

Then when you want to run your script, you need to invoke Sage with the option "-python" which would run your script using the Python that comes with Sage. For example, if Sage is in your PATH variable then you can do this:

sage -python /path/to/my/script.py

Another way is to write a Sage script and run that script using Sage itself. A Sage script has the file extension ".sage" and is more or less a Python script but uses Sage-specific functions and commands. You can then run that Sage script like so:

sage /path/to/my/script.sage

This will take care of loading the necessary environment variables and default imports for you.

3.12. I'm seeing an error about 'Permission denied' on a file called sage-flags.txt

When sage is built from source, it keeps track of what special instructions your CPU supports (such as SSE2), and records these (so that if you try running the code on a different machine, which doesn't support these extra instructions, you get a sensible error message instead of a segfault or illegal instruction). Since this should be stored with sage itself (as opposed to a user's .sage directory), it has to be created by someone with the appropriate permissions.

So if you're seeing something like this:

Traceback (most recent call last):
  File "/usr/local/sage-4.0.2/local/bin/sage-location", line 174, in <module>
    t, R = install_moved()
  File "/usr/local/sage-4.0.2/local/bin/sage-location", line 18, in install_moved
    write_flags_file()
  File "/usr/local/sage-4.0.2/local/bin/sage-location", line 82, in write_flags_file
    open(flags_file,'w').write(get_flags_info())
IOError: [Errno 13] Permission denied: '/usr/local/sage-4.0.2/local/lib/sage-flags.txt'

it probably means that you compiled/installed sage as one user, but haven't run it to let it generate the sage-flags.txt file. Just run sage one time as whatever user installed it, and this problem should go away. This would also be easy to fix by having sage run once as part of the install process; see trac #6375 for this fix.

3.13. I used Debian/Ubuntu to install Sage 3.0.5 and that version is giving lots of errors. What can I do?

The version of Sage, i.e. Sage version 3.0.5, that's available through apt-get in Debian and Ubuntu is very old. No-one has yet found time to update the Debian/Ubuntu version of Sage. Help wanted! You should download the latest version of Sage from the download page. If you would like to help with updating the Debian/Ubuntu version of Sage, please email the sage-devel mailing list.

3.14. Can I see a calculation step-by-step?

Unfortunately no. You can run the python debugger to execute it step-by-step, but that is entirely different from how a human would do a calculation.

4. Developing in Sage

4.1. What tools do I need to develop in Sage?

You need the prerequisite tools listed in the README.txt file in the root directory of Sage.

4.2. Where is the source code to Sage?

You can browse the complete source code to everything in Sage at https://github.com/sagemath/sage. This is a web interface to the Git repository.

4.3. How can I rebuild the Sage library in parallel?

When you run sage -b, the Sage library gets rebuilt. If you've changed a large number of files (for example, by using Mercurial to jump over many revisions), rebuilding the library will take a long time. If you are using a multicore machine, you can speed this up very easily: set the MAKE environment variable. If you run, say, env MAKE='make -j5' ./sage -b then the Sage library will get rebuilt using five threads. The other library-rebuilding commands also work: -br, -ba, and -ba-force all respect MAKE. In the bash shell, you can also simply do export MAKE='make -j5' and thereafter any rebuilds you do will automatically use five threads.

Note that there is an apparent bug in GNU make, so that you cannot leave a space between the -j and the number of threads (jobs, as Make calls them). So make -j 5 and so on will not work.

5. Working in Sage

5.1. What exactly does Sage do when I type 0.6**2?

sage: preparse('0.6**2')
"RealNumber('0.6')**Integer(2)"

So what is *actually* run is:

RealNumber('0.6')**Integer(2)

The Sage developers (in fact, Carl Witty) decided that Sage floating point numbers should by default print only the known correct decimal digits, when possible, thus skirting the problem that Python has. This decision has its pros and cons. Note that RealNumber and Integer are Sage specific, so you wouldn't be able to just type the above into python and expect it to work without first doing from sage.all import RealNumber, Integer, preparse.

5.2. Why is Sage's command history different than Magma's

5.3. How do I work with noncommutative variables

sage: R.<a,b> = FreeAlgebra(QQ, 2)
sage: a*b + b*a
a*b + b*a
sage: s = matrix(R)
sage: s = matrix(R, [[a,b],[b,a]]); s
[a b]
[b a]
sage: s*s
[a^2 + b^2 a*b + b*a]
[a*b + b*a a^2 + b^2]
sage: b*s*s
[  b*a^2 + b^3 b*a*b + b^2*a]
[b*a*b + b^2*a   b*a^2 + b^3]

For matrices in particular, see http://groups.google.com/group/sage-devel/browse_thread/thread/cafb486c79a2eb3c/d0bb78d09a4fb52a

5.4. How do I save an object so I don't have to compute it each time I open a worksheet?

The save and load commands will save and load an object, respectively. In the notebook, the DATA variable is the location of the data storage area of the worksheet. To save the object my_stuff in a worksheet, you could do save(my_stuff, DATA+"my_stuff") and to reload it, you would just do my_stuff = load(DATA+"my_stuff")

5.5. I get an error from jsMath or the math symbols don't look right when displaying in the notebook

If you see the error "It looks like jsMath failed to set up properly (error code -7). I will try to keep going, but it could get ugly.", you haven't installed the TeX fonts which help jsMath render beautiful mathematics. To get the nice TeX display with jsMath, please download a set of fonts from here:

http://www.math.union.edu/~dpvc/jsMath/download/jsMath-fonts.html

If you are on Linux/Unix, ignore the instructions on the page and just unzip the fonts into your ~/.fonts directory. You can also install the "jsmath-fonts" package.

6. Getting help

6.1. How do I get help?

Sage has two very active email lists: http://groups.google.com/group/sage-devel and http://groups.google.com/group/sage-support. There are also two very active IRC channels: #sage-devel and #sage-support on freenode. Many developers also actively blog and also post other Sage-related tutorials and talks. See http://www.sagemath.org/help.html for a listing of these resources.

7. Other questions



















# * QUESTION: How do I make the VMware appliance for Windows automatically login as "sage"? # * ANSWER: Follow http://ubuntu-utah.ubuntuforums.org/showthread.php?t=303319. Short version: put in the file /usr/bin/autologin the text #

#/bin/login -f sage
#

# and make this file executable; then edit /etc/event.d/tty1, comment out #

#respawn /sbin/getty 38400 tty1
#

# and add #

#respawn /sbin/getty -n -1 /usr/bin/autologin 38400 tty1
#

# Now every time the appliance reboots, it will automatically load directly to the sage: prompt. Warning: This will make it nearly impossible to get a terminal prompt! So only do this if you don't plan on any further management. # #If you do need to escape to a shell, you can run the following from inside sage (untested): #

#import os
#os.execp('sh')
#

#then use "sudo -s" to get a root shell. #


# * QUESTION: When running Sage under VMware, if you log in under manage you are not given the permissions to create a file! # * ANSWER: Type "sudo su" before creating files. #





ToDo