Using IPython Notebooks

The IPython notebook is a web-based interactive Python environment which allows users to execute code, display text and mathematical equations, and plot figures in a single page. The Neurokernel source code includes several notebooks that illustrate how to run various neural circuit demos that make use of Neurokernel's API.

Start IPython Notebook Server

Assuming that IPython has been correctly installed, one may start a notebook server from the command line as follows:

$ ipython notebook --pylab inline

The optional argument --pylab inline enables figures generated using Matplotlib to be displayed directly in the notebook. To enable the IPython notebook to continue running in the background even after one closes one's terminal, one can start the server as follows:

$ nohup ipython notebook --pylab inline &

By default, the IPython notebook server is run on port 8888. We can change the port number used to any other available port number XXXX either by starting the server with the --port XXXX option or by creating a custom profile of the IPython notebook that specifies the port number to use. To create a profile for the notebook server, run the following command:

$ ipython profile create nbserver

A file named ipython_notebook_config.py will be created in $HOME/.ipython/profile_nbserver with all fields commented. Open the newly created custom profile, find the line

#c.NotebookApp.port = 8888

and replace 8888 with your preferred number. More details about customizing the IPython notebook are available here.

Accessing the IPython Notebook via SSH Tunnel

Most of the time, people perform computation tasks on remote clusters, and use X window system to render GUI on a local machine. Since IPython notebook is web-based, one can simply resolve the rendering issue by creating an SSH tunnel from one's local machine to a remote cluster that forwards connections from one's local machine to whatever port is being used by the IPython notebook server instance running on a remote cluster. To establish SSH tunnel, run SSH with the -L flag,

$ ssh -L remoteport:localhost:localport the.remote.cluster

For example, suppose we want to forward port 9999 from a local machine to port 8888 on the remote machine xxx.yyy.zzz which runs an IPython notebook server on port 8888, type

$ ssh -L 8888:localhost:9999 xxx.yyy.zzz

Then navigate to localhost:9999 (or 127.0.0.1:9999) to access notebooks on the remote machine.