Skip to content

sagews

Jump to bottom
Gregory V. Bard edited this page Jul 19, 2016 · 39 revisions

SageMathCloud Worksheet (and User Interface) Help

This page is for help when using worksheets in SageMathCloud. There is a highly related page for the mathematical syntax, in SageMathCloud and in Sage generally.

Remember: if you don't find what you need, or if you'd like to ask a question, then please email [email protected] at any time. We'd love to hear from you! Please include a link (the address in your browser) to any relevant project or document.

Note: A worksheet is a file ending in .sagews and is subdivided into cells. Each cell has an input region and an output region, which might be 0, 1, 2, or many lines long. The input can be mathematical, in the Sage syntax, or it could be in many other formats, including markdown, html, R, and so forth.

Question: How do I create a Sage worksheet in SageMathCloud?

You can one create by clicking the "+New" icon from any project, and then "Sage worksheet" (or by making a file whose name ends in .sagews).

Question: I think I've made a major mistake! How do I revert/undo changes?

One of the most amazing things about SageMathCloud is that it will keep all versions of all of your files. This means that you can revert back to previous versions easily, and this can be a life-safer in the event of a catastrophic mistake.

From any worksheet, click on Timetravel. There is a sliding bar, but it can be very hard to see. Look under the orange button marked "Revert live version to this", and you'll see the slider.

Using the slider, look at all the versions. Find the revision that you want and then click "Revert live version to this."

Also for tiny changes, control+Z (or command+Z on a mac) will give you an instantaneous undo.

Question: I did xyz and now I have this huge error message! Why?

In almost all cases, when something incorrect is inputted into Sage, an extremely long error message appears. This many-lined report can be extremely intimidating, and even moderately experienced Sage users might not know what to make of it.

This is actually called a "stack trace" and it is very useful to experienced programmers, who can use it to locate a bug very rapidly. However (for new users) it can be very intimidating. The key is to realize that the last line of the error message is usually the most useful.

Whenever you have a huge error message, start with the very last line. That's often all you need. Alternatively, some users find it easier to ignore the error message entirely, read their own code, and figure out what is wrong themselves.

Question: All the input to one of the cells has suddenly vanished! How do I make it visible again?

If you double click on some text in the output region of a cell, then all the input for that cell will become hidden. It is very easy to do this by accident.

The keyboard shortcut for re-displaying the output is control+, for both Macs and non-Macs. That can be hard to remember.

It is more intuitive to click on the icon with a toggle switch and the word "in" but you have to ensure that your cursor is on the line above where your input used to be.

Question: How do I insert a new cell between two existing cells in a Sage worksheet?

Click the boundary between the output of the first cell and the input of the second cell.

Question: Can you tell me how to insert HTML, LaTeX, or simple text between two cells in a Sage worksheet?

To do this, first insert a cell between those two cells. (To do that, click the boundary between the output of the first cell and the input of the second cell.) Then put

%md

at the top of this newly created cell to use markdown formatting (which fully supports LaTeX formulas).

When you press shift-enter, the output is displayed. Double click the output to edit the input.

See http://daringfireball.net/projects/markdown/ about markdown.

You can also use %html in a similar way to the above, which also supports LaTeX.

No graphical editor is available yet to edit %html cells, but I hope to change that soon.

Question: I want to annotate my worksheet with some HTML. How do I make an HTML cell inside of a worksheet?

Just type %html as the first line of input to that cell.

Most of HTML, and even Javascript, should work.

Question: I want to annotate my worksheet with the markdown language. How do I make a markdown cell inside of a worksheet?

Just type %md as the first line of input for your cell.

By the way, markdown comes in several flavors. SageMathCloud uses Github-flavored Markdown.

(See https://guides.github.com/features/mastering-markdown/ )

You can add mathematical expressions. For example, create a cell with:

%md
$e^{i \pi} = -1$

Question: Can I configure one or more cells to run automatically when I open a worksheet?

Yes, you can! If you type %auto in the top of the cell (as the first line of input to a cell), then it will automatically run whenever the worksheet is first opened.

Question: How do I execute all the code cells in the entire worksheet?

Control+A (or command+A on Mac), then click run or hit "control+enter".

Question: How do I execute code from a set of consecutive cells?

Just highlight those cells, then click run or hit "control+enter".

Question: The output of one of my cells is getting cut off because there is too much output. How do I raise the limit on the number of output messages per cell in a Sage worksheet?

    import sage_server
    sage_server.MAX_OUTPUT_MESSAGES=100000

See this published worksheet for more details.

Also, type sage_server.[tab key] to see information about other limitations.

Question: How do I split a cell into two cells?

Just put your cursor in the input region of the cell, at the spot where you want the split to go. Then press control+; (or command+; on a Mac).

Question: How do I jump to a specific line?

Just press control+L (or command+L on a Mac).

Question: When outputting from a Sage Worksheet using show( ), print, and plot( ), the outputs are coming out of order; how do I fix this?!

Sometimes, if you have a mix of sources for output, e.g. the show() command, the print command, and the plot() command, the outputs can come out of order. This has to do with something called "flushing the output buffer."

Before giving the remedy, here is some sample code the illustrates the problem.

print ("Create a graph")
G = Graph(sparse=True)
G.allow_multiple_edges(True)
G.add_edge(1,2,"blue")
G.add_edge(2,3,"green")
G.add_edge(3,1,"red")
G.add_edge(1,4,"green")
G.add_edge(2,4,"red")
G.add_edge(3,4,"blue")

for i in range(5):
    print ("BEFORE SHOW ", i)
    show(G)
    print ("AFTER SHOW ", i)

    print ("BEFORE PLOT ", i)
    G.plot()
    print ("AFTER PLOT ", i)

Whenever you wish to output something, it goes into an output buffer. That buffer is periodically "flushed." By flushing, we mean that the information in the output buffer is actually outputted, and then removed from the buffer.

This is normal in many programming languages.

The issue is that the show command always immediately flushes the output buffer. So in the above example, the "Before Show" and the "After Show" print outputs might be sitting in the buffer for a while, whereas the show output essentially jumps the queue and gets displayed immediately. Therefore, the outputs appear out of order.

The fix to this complex problem is remarkably easy. Just put sys.stdout.flush() after each print statement to ensure that the output buffer is flushed to the output stream immediately, so you can see it at that instant.

Our previous example can be repaired as follows:

print ("Create a graph")
sys.stdout.flush()

G = Graph(sparse=True)
G.allow_multiple_edges(True)
G.add_edge(1,2,"blue")
G.add_edge(2,3,"green")
G.add_edge(3,1,"red")
G.add_edge(1,4,"green")
G.add_edge(2,4,"red")
G.add_edge(3,4,"blue")

for i in range(5):
    print ("BEFORE SHOW ", i)
    sys.stdout.flush()
    
    show(G)
    
    print ("AFTER SHOW ", i)
    sys.stdout.flush()

    print ("BEFORE PLOT ", i)
    sys.stdout.flush()
    
    G.plot()
    
    print ("AFTER PLOT ", i)
    sys.stdout.flush()

Question: Can I split the editor into two? So that I can look at one region while working on another region?

Sure, just press control+I (or command+I on a Mac).

If you do that, you'll get two editors, one above the editor.

Press that keyboard shortcut again, and you'll get two editors that are side by side.

Press that keyboard shortcut a third time, and you'll return to the normal situation of having one editor for the entire window.

Question: How do I hide a cell's input?

There are two ways to do this.

  1. You can double click on any text in the output region of that cell

  2. You can type control+, both on a mac and on non-macs.

Question: How do I keep HTML or markdown code blocks from being hidden?

For HTML Cells: Instead of using %html as the first line of the cell, simply use %html(hide=False) instead.

For markdown Cells: Instead of using %md as the first line of the cell, simply use %md(hide=False) instead.

Question: How do I delete/hide all output in a worksheet?

Delete: Press control+A (or command+A on a mac), then click the little circular x in the bar at the top.

Hide: Press control+A (or command+A on a mac), then click "out" to toggle the displaying of output. (Likewise you can click "in" to toggle the displaying of input).

Question: How do I delete/hide the output of a selected range of cells?

Delete: Highlight those cells with the mouse, then click the little circular x in the bar at the top.

Hide: Highlight those cells with the mouse, then click "out" to toggle the displaying of output. (Likewise you can click "in" to toggle the displaying of input).

Question: How do I hide the toolbar?

Under account settings, uncheck "Extra button bar."

Question: How do I hide the menu bar?

Click the full-screen toggle arrows in the far upper-right corner. The icon looks like two small diagonal arrows, pointing head to head.

Question: In the standard Sage notebook there is a checkbox to switch on the typesetting of math. How do I turn on typesetting of math output in SageMathCloud?

Turn it on with

typeset_mode(True)

and off with

typeset_mode(False)

Alternatively, you can add %typeset_mode True to the top of your cell, or %typeset_mode False as needed.

Note, that this works across multiple cells, so keep that in mind.

This means that if you execute your cells out of order, you might get different results each time. To avoid confusion, it is useful to make sure that one of these commands (setting typeset either to true or to false) appears at the top of each cell, if you intend to execute your cells out of order.

Question: How do I put the entire worksheet into "typeset" mode?

The previous question dealt with putting individual cells into "typeset" mode. To put all the cells into "typeset" mode, simply put

%auto
typeset_mode(True)

at the top of a worksheet. This will make typsetting automatic.will make this automatic.

Question: I would like nice typeset output from FriCAS mode in my Sage Worksheet. How do I do that?

A mode xxx specified by %xxx in the first line of a cell in SageMathCloud is just a Python function xxx that takes the cell input as a string and does something visible with it.

For example, the following function takes whatever the cell input is, executes the code in FriCAS, performs some simple substitutions on the FriCAS output and then displays it using Markdown:

%sage
def fricas_tex(s):
    import re
    t = fricas.eval(s)
    t=re.compile(r'\r').sub('',t)
    # mathml overbar
    t=re.compile(r'¯').sub('‾',t,count=0)
    # cleanup FriCAS LaTeX
    t=re.compile(r'\\leqno\(.*\)\n').sub('',t)
    t=re.compile(r'\\sb ').sub('_',t,count=0)
    t=re.compile(r'\\sp ').sub('^',t,count=0)
    md(t, hide=False)

FriCAS can generate output that is (almost) compatible with Markdown format.

For example you can use this new mode in a cell with the following contents:

%fricas_tex
)set output algebra off
)set output mathml on
)set output tex on
sqrt(2)/2+1

This will evaluate 'sqrt(2)/2+1' and display the result in both LaTeX format and MathML formats (in a MathML capable browser).

Note: The current version of Sage (6.6 and earlier) requires a patch to correct a bug in the fricas/axiom interface.

Question: I would like nice typeset output from non-Sage modes (other than FriCAS) in my Sage Worksheet. How do I do that?

A mode "xxx" specified by %xxx in the first line of a cell in SageMathCloud is just a Python function xxx that takes the cell input as a string and does something visible with it.

Therefore, you have to use the commands of "xxx" to do what you want, just like any other time you are using language "xxx."

See the answer to the question immediately above this one, which uses FriCAS as an example.

Question: What if my question isn't answered above?

Email [email protected] in case of problems. Do not hesitate to email us at any time. We want to know if anything is broken! Please include a link (the address in your browser) to any relevant project or document.

This Wiki is for CoCalc.com.

A more structured documentation is the CoCalc User Manual.

For further questions, please contact us.

Clone this wiki locally