To navigate this multi-page article:

Use the drop-down lists and arrow icons located at the top and bottom of each page.

 

The first thing to understand about Sage is that it has two identities — one is as a Web server, the other is as a modest command-line application. The Web server identity is very sophisticated, can serve multiple users and has a nice interface, but requires more system resources than the command-line interface.

• Sage as Network Server
  • Sage runs as a Web server, either locally or remotely.
  • Significant but not unreasonable system requirements.
  • The user accesses Sage by way of a Web browser (more detail later).
  • Sophisticated Web 2.0 "Notebook" interface.
  • Inline equation rendering, e.g. instead of this:
    

    x = -1/2*(b + sqrt(-4*a*c + b^2))/a

    , one sees this:

    

  • Graphics and animations embedded in the worksheet.
  • The ability to load, save and publish worksheets.
  • Browser-based help resources.

  Here is an example notebook session (my notes are in italics):

  User entries look like this (and can be copied into a Sage worksheet)

  Sage replies look like this

  Variables to be used as unknowns must be declared in advance:

  var('a b c d')

  (a, b, c, d)

  Solve a quadratic equation:

  q = solve(a*x^2+b*x+c==0,x);q

  [x == -1/2*(b + sqrt(-4*a*c + b^2))/a, x == -1/2*(b - sqrt(-4*a*c + b^2))/a]

  The two solutions are stored in q[0] and q[1]:

  show(q[0])

  

  Let's solve a cubic equation:

  q = solve(a*x^3+b*x^2+c*x+d==0,x);q

  (huge table result rendered as text)

  The three solutions are stored in q[0], q[1] and q[2]:

  show(q[0].simplify_full())

  Use the scroll bar below to see the full result:

  

  Here's a plotting example:

  plot(e^-x^2,x,-2,2,fill=True,fillcolor='yellow')

  

  To save a plot in Sage, right-click the image and choose "Save As ..."

  Readers may want to copy the above example Sage entries and paste them into Sage itself. There are many more examples later in this article.

• Sage as Command-line Application
  • Sage runs as an ordinary application in a command shell.
  • Modest system requirements.
  • Text-based, terminal interaction.
  • Prior entries preserved (use up and down arrow keys).
  • Equations and graphics rendered if possible in separate windows.
  • Text-based help resources.

  Here is an example command-line session:

  sage: var('a b c d')
     (a, b, c, d)
     
  sage: q = solve(a*x^2+b*x+c==0,x);q
     [x == -1/2*(b + sqrt(-4*a*c + b^2))/a, x == -1/2*(b - sqrt(-4*a*c + b^2))/a]
  
  sage: show(q)
     If possible, Sage will launch a window showing the two solutions properly rendered.
  
  sage: q = solve(a*x^3+b*x^2+c*x+d==0,x);q
     (a huge table containing the three solutions)
  
  sage: show(q)
     If possible, Sage will launch a window showing the three solutions
      properly rendered, but truncated at the right (Sage version 4.1.2).
  
  sage: plot(e^-x^2,x,-2,2,fill=True,fillcolor='yellow')
     If possible, Sage will launch a window showing the requested plot.
  
  sage: p = plot(e^-x^2,x,-2,2,fill=True,fillcolor='yellow')
     Instead of being rendered, the requested plot is assigned to variable 'p'.
  
  sage: p.save("my_plot.png")
     The plot is saved as "my_plot.png" in the user's home directory.
                

Okay, if you didn't know whether you wanted Sage before, most likely you want it now. It's time for some direct experience.

Linux

The Linux download takes the form of a TAR archive. The download mirrors offer several versions of the archive for different Linux distributions. If readers experience difficulties with a particular download, I recommend they try the Debian download instead — it's more robust in the face of missing system resources.

The first step below will open a new browser window/tab — move back and forth between the displays to follow these instructions.

1. Click here (opens a new window/tab in your browser) and choose a suitable Sage download mirror site.
2. Choose a processor type. Most readers will want the 32-bit option.
3. Choose a distribution. At the time of writing there are six listed — Debian, Fedora, Ubnuntu, openSUSE, Mandriva, and CentOS. If the user has difficulties with one of these downloads, I recommend they try the Debian download instead.
4. After the download is complete, move the archive to the directory you want Sage to run from and unpack it. Let's say you have decided to locate Sage under your home directory. Here are the steps one would take from the command line:

   $ cd ~
   $ mkdir Sage
   $ cd Sage
   (Move the downloaded archive into the new directory, then)
   $ tar -xvzf (download name).tar.gz
   (The above will create a new directory with the download's name)
   $ cd (download name)
   (the next instruction runs Sage as a command-line application)
   $ ./sage
   (the next instruction runs Sage as a Web server on your local network)
   $ ./sage -notebook
                     

   In this scenario, the Sage executable is located at:

   /home/(user name)/Sage/(download name)/sage
   

5. If you decided to run the Sage notebook server, run your favorite browser and enter "http://localhost:8000" in its address bar. You will be presented with the Sage logon page.
6. See below on this page for Sage Notebook Testing.
7. Create an optional Desktop Shortcut.
   • This Sage desktop shortcut will allow you to start the Sage Web server by clicking a desktop icon.
   • First, open a text editor and copy the text below into an empty file:

                             [Desktop Entry]
                             Encoding=UTF-8
                             Name=Sage
                             Exec=(full path to Sage directory)/sage -notebook
                             Terminal=false
                             Type=Application
                             Icon=math_int
                           

   • When the text is copied into your text editor, enter the full path to the Sage executable you installed above:

     /home/(user name)/Sage/(download name)/sage

   • Save the text file as "sage_launcher.desktop," give it executable permissions:

                               $ chmod +x sage_launcher.desktop
                             

     , and save it in /home/(user name)/Desktop (this will make it appear on your desktop). Now test it — clicking it should start the Sage server and launch the system default browser with the Sage login page on display.

Windows

The Windows installation is a bit more complicated — Sage is run from within a free virtual machine (VM) host called "VirtualBox". Readers must download a free copy of VirtualBox, as well as a special Sage version meant to be run within VirtualBox. Sage is then installed within the VirtualBox host.

The first step below will open a new browser window/tab — move back and forth between the displays to follow these instructions.

1. Click Here (opens a new window/tab in your browser) to download VirtualBox — choose an appropriate VirtualBox version and download it.
2. Install VirtualBox by running the download.
3. Now Click here and navigate to a suitable Sage download mirror site.
4. Click "sage-virtualbox-(version).zip" to download the VirtualBox-compatible version of Sage.
5. Create a directory named "Sage" under your "Program Files" directory (normaly located at "C:\Program Files").
6. Move the Sage ZIP download to the directory you have just created.
7. Using a file explorer, navigate to the Sage directory.
8. Right-click the Sage ZIP file and choose "Extract All."
9. The extraction may take several minutes (don't get impatient) and will create a new directory under the "Sage" directory named "sage_vbox-(version)".
10. Choose menu item "File ... Import Appliance".
11. Navigate to the directory you created above: "\Program Files\Sage\sage-vbox-(version)". Inside this directory, click the file named "sage.ovf".
12. VirtualBox will install Sage and Sage will appear in the VirtualBox menu with the title "Sage VirtualBox Appliance".
13. Select the Sage VirtualBox Appliance and click "Start".
14. Ssge will run and you will be presented with a message box incuding an Internet address that will look like this: "http://192.168.nnn.nnn". Make a note of this address.
15. Run your favorite browser and type in the address you were presented with above. By the way, is your favorite browser Firefox? I ask because all the examples in these pages were created using Firefox and they may not work as well on other browsers. To be specific, the Windows default browser "Explorer" performs rather poorly when used with Sage — Firefox does much better. Click here to get Firefox for Windows (it's free).
16. See below on this page for Sage Notebook Testing.
17. When you are done playing with Sage in your browser, return to the Sage window and click the icon marked "Turn Sage Off".
18. If you have difficulties, either click the file named "README.txt" in the Sage directory you created — or Click here — for additional assistance with the Windows installation.

TeX Fonts

If provided with the right resources, Sage can render equations beautifully. The most important resource not bundled with Sage are a set of fonts important for equation rendering. Here is how to find out if your system has these important fonts:

• Run Sage as explained above and log on using your browser.
• Create a new worksheet, or enter an existing one, suitable for exercises and experiments.

• Make this entry into your Sage worksheet (copy the entry from this page):

  var('a b c d');show(sqrt(a+sqrt(b+sqrt(c+sqrt(d)))))

  If Sage's response looks like this, you need to download TeX fonts:

  
  If Sage's response looks like this, the required fonts are already present:
  

• If Sage rendered the above test expression poorly, this means your system needs additional fonts (they're free). Here is how to get the required fonts:

  • Linux:
    • Download this archive, unpack it, and place the contents in a directory named ".fonts" under your home directory. If the directory doesn't exist, create it:

                                $ mkdir ~/.fonts
                              

    • Press "Refresh" in Firefox. The rendering should improve immediately.

  • Windows:
    • This procedure is much more difficult than it should be. I apologize for the designers of Windows.
    • Open a file browser and navigate to the "C:\" directory.
    • Create a new directory by right-clicking the right-hand pane and choosing item "New ... Folder." Type the name "temp".
    • Read the instructions on this page and choose a font package after reading them. Most Windows users will want the download named "Tex-fonts-25.zip".
    • When a font download is selected, Windows will respond with a dialog asking if you want to "Open" or "Save" the archive. Choose "Open."
    • A dialog will open showing a folder with the name of the font set. Click this folder.
    Copy the fonts in this folder into the directory you created above: "C:\temp".
    • Open the Font Manager applet located in the Windows Control Panel.
    • Select menu item "File ... Install New Font."
    • Navigate to the new folder created above: "C:\temp". The downloaded fonts should appear in the upper window.
    • Click "Select All". Make sure the "Copy Fonts to Fonts Folder" selector is checked.
    • Click "OK".
    • Press "Refresh" in Firefox. The rendering should improve immediately.
    • To Windows fans who might say, "Why don't you just copy the fonts directly from the download dialog to \Windows\Fonts?", my reply is "try it."

Java

• Some of the nicer features on Sage (like a 3D viewer) require the latest Java, and it must be gotten from http://java.com, no substitutes. Copy the example text line below into your Sage worksheet and see if it runs correctly:

  var('u v');plot3d(sin(u^2) - cos(v^2), (u,-2,2),(v,-2,2))

  You should see this:

  

• If you don't see this rendering in your copy of Sage, or if it doesn't look like this copy, or if you can't rotate it by dragging your mouse on it, then you need to get the current Java version and install it. Go to http://java.com and download the current Java version.
• In the event of difficulty, type "about:plugins" into the Firefox address bar, scroll down to the Java entries and verify that you have an appropriate Java plugin installed. Such a plugin will have "Java(TM)" as part of its name. If a Java plugin named "IcedTea" is present, disable it — it is a very ambitious open-source project that unfortunately isn't ready for prime time.

At this point the reader should have a local working copy of Sage and optionally has installed the Firefox Web browser (the preferred browser for Sage, primarily because of its very fast JavaScript engine). Other desirable options include the TeX fonts described above to optimize equation rendering, and an up-to-date Java runtime engine from http://java.com rather than the open-source IcedTea version (an admirable project that is unfortunately still broken).

It is the goal of this installation and testing procedure that differences between platforms will be minimized or eliminated, so it won't be necessary to say "if you're running Windows, do this ...", at least very often. This is one reason to run Sage as a Web server and access it from a browser — it tends to minimize platform differences, especially if the same browser is used.

In the following pages, readers will learn how Sage can help them do interesting, worthwhile mathematics.

Remember: to navigate these pages, use the drop-down lists or arrow icons at the top and bottom of each page.

  "Exploring Mathematics with Sage" by Paul Lutus is licensed under a
Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License.