Sharedlectures / 2018-01-10 / 2018-01-10.ipynbOpen in CoCalc

Math 157: Intro to Mathematical Software

UC San Diego, winter 2018

January 10, 2018: Jupyter notebooks

As I explained last time, you should start each lecture by performing the following steps. (Do them now.)

  • Open your device, sign into CoCalc, and open your individual project.
  • If necessary, get to the Files view by clicking the folder icon: Folder icon
  • If necessary, navigate to the top of your directory structure by clicking the home icon: Home icon
  • Click on the folder "lectures", then the subfolder "2018-01-10".
  • Open the file "2018-01-10.ipynb" with that day's date. You should see this file!

This file is an example of a Jupyter notebook. In this lecture, we explain what Jupyter notebooks are, what you can do with them, and how they will be used in this course.

Optional: chat room

You may also want to open a second tab or window, open the shared project in CoCalc, and enter the master chat room. Of course you are welcome to ask questions during the lecture, but you also have the possibility of using the chat room to ask a question of the rest of the class. I encourage you to take advantage of the knowledge of your classmates in this way! (Your social media can wait for an hour...)

Also to be found in the shared project: a folder called first_steps. This is a little tutorial put together by the CoCalc team to walk you through some basic tasks. If you want to mess around with it, please make a copy of the folder first (demonstrate that here). You can also copy it into your course project, but you won't be able to add collaborators there.

Project Jupyter

According to its home page http://jupyter.org/:

Project Jupyter exists to develop open-source software, open-standards, and services for interactive computing across dozens of programming languages.

To put that in context, the idea is to provide a uniform environment for both doing scientific computations, using a variety of software tools, and communicating the results, in a way that others can then reproduce the results. In this course, we'll use Jupyter to replace two older technologies: paper and the chalkboard.

Notebooks and their structure

The Jupyter notebook is Jupyter's analogue of a piece of paper (or an Excel spreadsheet, or a Word document, or ...). At the moment it looks like a pretty static object, but let's look more closely.

Click on this piece of text. You should see a blue outline appear around it. This outline delineates a cell; the notebook is composed of a sequence of such cells, of three kinds.

  • Markdown cells, like this one, display text with some formatting. For help with the formatting, go to the Help menu and select Markdown.
  • Code cells contain code to be executed by a particular piece of software (the kernel). We'll start working with code cells when we start with Python in the next lecture (or today if time permits).
  • Raw cells are in between: they look like code, but are static like markdown cells. These are useful if you want to display a piece of code but not actually execute it; but this probably won't come up very often for us.
17*235 # Example of a code cell, executes something
3995
2+3 # Example of a raw cell, does not execute

Now double-click on this cell (or any other). It should be replaced by a text editing box containing the contents of the cell. You should be able to edit this text as in a word processor. Go ahead and try editing some text now (don't worry about clobbering the original; we'll see in a moment how to undo changes). To close the editor, hit Shift-Enter. (The editor will not automatically close if you switch to another cell. If you have multiple open cells, the colored outline will indicate which one you are editing.)

You can also try editing the code and raw cells above. They behave slightly differently; for instance, Shift-Enter in a code cell causes it to execute.

Notebooks in this course

I can now explain how we will verify your in-class participation for the purposes of your course grade. During each lecture, I will be demonstrating a particular notebook; by following the instructions I gave you at the beginning, you will have access to your own private copy of the same notebook. In order to get credit for in-class participation on a particular day, you need to make a "reasonable" number of edits to that day's file during that day's lecture (which we will verify using file logs). So don't just sit there watching me; experiment on your own! I will sometimes pause to give you a chance to try something specific, but you should be trying things out even when I'm not specifically directing you to do so.

For example, if you click immediately below this cell, a new cell will be inserted in between this cell and the next one. (If you are using a mouse, a colored bar should appear as you hover, indicating where you should click.) Try inserting a cell and fiddling with Markdown formatting (again using the Help menu).

  • Can you make some text appear in boldface? Strikethrough? Bold and italic at once?
  • Can you produce a numbered list? A list of lists? A checklist?
  • Can you make a piece of text (which is not itself a URL) appear as a link to a URL?
  • What emoji can you produce?

Homework assignments will also be in the form of notebooks. To find the homework assignment due on a given date, we perform a similar process to the one we did to get started with this lecture. Let's try this with the "assignment" due this Friday (January 12).

  • Open your device, sign into CoCalc, and open your individual project.
  • If necessary, get to the Files view by clicking the folder icon: Folder icon
  • If necessary, navigate to the top of your directory structure by clicking the home icon: Home icon
  • Click on the folder "assignments", then the subfolder "2018-01-12".
  • Open the file "2018-01-12.ipynb".

In fact there is no assignment due this Friday; what you have is a "practice assignment" designed to let you get accustomed to working with CoCalc, and to show you some additional features. It will be collected, evaluated, and returned to you as if it were a homework assignment, but no grades will be assigned.

I remind you that there is no mechanism for submitting your homework assignment. When the homework is due, we will simply copy the contents of the folder (the notebook plus any additional files) to another directory. When grading is complete, you will receive additional files in the same folder.

Can I make text appear in boldface?
did this work?

TimeTravel

Jupyter notebooks are a widely used format, and are most commonly manipulated using the standard Jupyter server. CoCalc instead implements a custom version of the Jupyter server which has some very useful features, notably TimeTravel.

Try clicking on the TimeTravel button near the top of the window. This takes you to a "flat" view of your notebook, in which nothing is editable. However, there is now a slider at the top of your window which you can use to scroll through historical versions of your document. CoCalc takes snapshots about once per second when there is activity on the file.

Note that the TimeTravel view is a separate tab from the original file. To get back without changing anything, just close the TimeTravel tab. If instead you want to roll back some changes, find the version you want in TimeTravel and then click on Revert live version to this.

There are additional options in TimeTravel, such as highlight changes between two versions, and "Load all history" in case you want to go back to a much older version of the file.

When you copy a file, the history does not come along with it. So for example, if you want to revert this notebook back to its original state and save your changes, use the file view to copy the changed version to a new file (which now has no history), then do TimeTravel on the original file.

Kernels and cell execution

So far we have only seen text in Jupyter notebooks, but of course the whole point is to integrate explanatory text with code that actually does something. So let's talk a bit about how that is going to work. We'll get into this in more detail once we start discussing Python specifically (next time).

CoCalc supports the use of many different "kernels". A kernel is basically a programming language; different kernels have different syntaxes for input (what you type into the kernel) and output (what comes back from the kernel), and often are useful for very different purposes. At any given time, a notebook is set to use a particular kernel, which is named at the top right of the window (right now you should see "Python 3 (Ubuntu Linux)".) One can change the running kernel using the "Kernel" menu, but you won't normally do this in the middle of a session (and I'll try to make sure the kernel is set correctly for each lecture).

Communication between the user and the kernel is broken down into cells. When editing a code cell, hit Shift-Enter to execute the contents of the cell; the response from the kernel will be printed underneath.

2+2
4

Note the difference between Shift-Enter and Enter: you can have multiple lines of code within a single cell.

x=2
x+3
5

Although the interaction is broken down into cells, in a single session all of the cell executions form a single "dialogue", with persistence of state between cells. For example, in the previous cell the line 'x=2' was an assignment: it declared a new variable 'x' and set it to have the value '2'. That value will persist if we perform another execution. (The "Restart" command under the "Kernel" menu can be used to end the current dialogue and start afresh.)

3*x+1
7

One potential source of confusion: when you look at a notebook, you see a series of code cells in some order. However, in any given session, you can choose to execute the cells in any order; this includes repeatedly executing a single cell, or skipping one entirely. (Notice the "In" and "Out" tags in the left margin telling you about the execution order; this might look familiar if you have used Mathematica.) Try some experiments with this using the following example.

x=x+1 # Try executing this repeatedly, then one of the others

That said, if you are preparing a notebook for someone else to read (e.g., when you are submitting homework!), you probably want to assume that the user plans to execute the cells in the order they are given. In fact, there is an easy way to do exactly that: the "Run all" command in the "Cell" menu. (Note: this picks up from the current state of the kernel; if you want a fresh start, instead use the "Restart and run all..." command under the "Kernel" menu.)

On rare occasions, you may want to include a cell that looks like code (i.e., monospaced text without formatting) but shouldn't actually execute. This can be achieved by setting the cell type to "Raw".

this=looks like code
but=does nothing