Skip to content

sagejupyter

Jump to bottom
Harald Schilly edited this page Mar 28, 2017 · 24 revisions

Jupyter and Sage on CoCalc

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 URL address in your browser) to any relevant project or document, as part of your email.

Two Ways of Using Jupyter Processes:

CoCalc lets you use back-end Jupyter processes, or kernels, such as the languages Python and R, from both Jupyter notebooks and Sage worksheets.

Note: Running Jupyter kernels from a Sage Worksheet is also known as "the Sage worksheet Jupyter bridge."

List of Questions:

Question: I want to use a Jupyter notebook (with Sage support)

Click "+New", then enter a filename and click Jupyter Notebook. This is the official Jupyter notebook, but enhanced with realtime synchronization that supports multiple simultaneous editors and a TimeTravel slider that lets you browse everything you have done in the notebook.

You can also just run a standard Jupyter notebook server (no sync, not integrated into cloud) by clicking the "About" button in any Jupyter notebook in your project, then clicking "open this notebook in a vanilla Jupyter Notebook server without sync"; alternatively, you can finding your project's id in project settings, then visiting

https://cloud.sagemath.com/YourProjectIDMustGoHere/port/jupyter/

but you may have to refresh your browser if this takes too long the first time. Any collaborator on your project can securely use the Jupyter notebook server by visiting this link, but nobody else can.

If you want to make a Jupyter notebook that supports Sage, select the SageMath kernel (in the menu, select Kernel --> Change kernel). This will import the Sage library, enable the preparser, make some graphics work, etc.

Note: As of July 2016, Sage interacts and 3d plots do not work in Jupyter; however, this may change soon.

Question: I want to use my own copy of Jupyter, which is part of my own Python stack

You can install any version of Python you want into your own project -- just download and build it locally, and install Jupyter (and whatever you want) into it. Then, make a directory "bin" in the home directory of your project and put a symlink to your ipython there, e.g.,

cd ~/bin/
ln -s /path/to/your/ipython .

In project settings, restart your project server (just to be sure), then make sure that when you type "ipython" on the command line, you get your Jupyter. Then clicking on existing Jupyter notebooks or creating new ones (through the graphical user interface) should use your copy of Jupyter. It just uses the "Jupyter" that is in the path, since ipython-notebook just sets up some options and runs "ipython notebook." (Look at ~/.smc/ipython-notebook .)

Question: I want to install the cite2c Jupyter extension, so I can use Zotero

Note: Due to some unfriendly users launching attacks from CoCalc, you must pay to enable internet access from within your project in order to access online resources like GitHub.

Do the following in a terminal:

git clone https://github.com/takluyver/cite2c.git && cd cite2c && sage install.py

Now when you open a Jupyter notebook, there will be two new buttons at the end of the button bar, which will let you insert citations.

Question: How do I use Asymptote for vector graphics in a Jupyter notebook?

You can copy the file at this link Examples of drawing scientific diagrams with Asymptote in IPython notebook into your CoCalc project and run it.

Notes:

  1. You may get the message, UserWarning: %install_ext is deprecated on installing the IPython magic extension in the first cell. You can still run the rest of the notebook.
  2. To avoid freeglut (asy): failed to open display '' error when calling show(), add file config.asy to the directory with the notebook, with these two lines:
import settings;
offscreen=true;

Question: How can I install Jupyter's nbextensions configurator?

You can install it in your own project. For that, you need internet access enabled or somehow upload the code into your project. Then, install it like this in a terminal (create a new file terminal.term)

 pip install --user --no-deps jupyter_nbextensions_configurator
 jupyter nbextensions_configurator enable --user

and restart the Jupyter server in CoCalc

smc-jupyter restart

Then, in order to see the configurator, you have to open an ipynb file. Click on the the "About" button in the top right click on the link there to open the version of jupyter without the synchronization. There, either go to the main page or the one dedicated for the nbextensions. The URL looks like this:

https://cloud.sagemath.com/<your_project_id>/port/jupyter/nbextensions

Question: How can I customize the default Jupyter kernel or template?

I just realized we already have a supported mechanism for creating templates for files, which provides a way to make a default Jupyter kernel! In short, just make a file ~/templates/linux/default.ipynb. For example, just do this in a terminal:

cd; mkdir -p templates/linux/; open templates/linux

then create a file default.ipynb. Set the kernel to anything you want, and save the file.
Now any jupyter notebook you create will have that kernel. Of course, you can further customize this file however you want. The same templates work for any file type, by the way.

See https://github.com/sagemathinc/smc/issues/424

Question: How do I start a Jupyter kernel?

For a quick reminder, sample code is available for opening an Anaconda3 session. In the Sage worksheet toolbar, select Modes > Jupyter bridge.

Use the jupyter command to launch any installed Jupyter kernel from a Sage worksheet

py3 = jupyter("python3")

After that, any cell that begins with %py3 will send statements to the Python3 kernel that you just started. If you want to draw graphics, there is no need to call %matplotlib inline.

%py3
print(42)

import numpy as np; import pylab as plt
x = np.linspace(0, 3*np.pi, 500)
plt.plot(x, np.sin(x**2))
plt.show()

You can set the default mode to be your Jupyter kernel for all cells in the worksheet: after putting the following in a cell, click the "restart" button, and you have an anaconda worksheet.

%auto
anaconda3 = jupyter('anaconda3')
%default_mode anaconda3

Each call to jupyter() launches its own Jupyter kernel, so you can have more than one instance of the same kernel type in the same worksheet session.

p1 = jupyter('python3')
p2 = jupyter('python3')
p1('a = 5')
p2('a = 10')
p1('print(a)')   # prints 5
p2('print(a)')   # prints 10

Question: What features are supported?

The features listed below are demonstrated in sample worksheets at https://github.com/sagemath/cloud-examples/tree/master/sagews-jupyter.

  1. Help, with list of available kernels: jupyter?.
  2. Execution count: [n]: 'XYZ'.
  3. pwd
  4. ls with color-coded output
  5. Plot to png.
  6. Plot to image/svg+xml.
  7. Display image from local file or URL.
  8. Ignore python prompt markers.
  9. Error output with ansi colors.
  10. Non-blocking output.
  11. Function docstring with ansi colors.
  12. Long docstring and magic output to scrolling div.
  13. Markdown, including inline and display MathJAX.
  14. Embed Youtube video.
  15. Embed web page from external site.
  16. LaTeX output from Math() and Latex() objects.
  17. Play audio from local file.
  18. Play audio from generated data.
  19. Autocompletion, if supported by jupyter kernel - tested with Python, R, and bash.

Question: How Can I get help on running a Jupyter kernel from a Sage worksheet?

You can get a version of this help message from within a Sage worksheet, regardless of default mode, with

%sage
jupyter?

Question: Are there any known issues with running a Jupyter kernel from a Sage worksheet?

  1. Raw input hangs the worksheet: a = raw_input("type here: ").
  2. If default_mode is enabled for the jupyter mode and a cell starts with a jupyter magic command, the cell needs to start with a comment or mode decorator, or the jupyter magic will be interpreted as a sagews mode.
  3. Long docstring and magic create scrollable div, but there is no close button.
  4. If the jupyter kernel crashes, it must be restarted manually.
  5. %load somefile - hangs the .sagews
  6. Embedded youtube widget is rendered multiple times.
  7. ipywidgets are not supported.
  8. jupyter? calls _get_doc() three times

Question: Which Jupyter kernels are pre-installed?

From any Sage worksheet cell, just type the following to get a full and up-to-date listing.

%sage
print(jupyter.available_kernels())

Question: How can I add my own Jupyter kernel?

Jupyter Kernels are small JSON files, telling the Jupyter notebook what program to start, in order to communicate with the actual kernel that holds your working session and executes your code. To install your own, they need to go into the directory:

$HOME/.local/share/jupyter/kernels/[name_of_your_kernel]/kernel.json

For example, this is the content of kernel.json file is running Anaconda Python 3:

{
 "display_name": "My Anaconda (Python 3)",
 "argv": [
  "/projects/anaconda3/bin/python3",
  "-E",
  "-m",
  "ipykernel",
  "--matplotlib=inline",
  "-f",
  "{connection_file}"
 ],
 "language": "python",
 "env":{
    "LD_LIBRARY_PATH" : "/projects/anaconda3/lib",
    "PYTHONPATH" : "/projects/anaconda3/lib/python3.5:/projects/anaconda3/lib/python3.5/site-packages",
    "PYTHONHOME" : "/projects/anaconda3/lib/python3.5"
 }
}

Once that file is there, click the reload button (top right of the Jupyter notebook) to let it search for kernels and find your configuration. For more information, read Jupyter Kernel Specs

Question: I want to XXX, but I don't see XXX above.

Do not hesitate to email THE LINK TO YOUR PROJECT to [email protected] or https://groups.google.com/forum/?fromgroups#!forum/sage-cloud

Analytics

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