Getting Started with Jupyter*

Interactive mode provides a containerized Jupyter notebook with access to a CPU or GPUs and the same environment that gets used for ncloud model train. It is a nice way to develop new models or customize neon, getting quick feedback on syntax and algorithm correctness, visualizing with matplotlib or bokeh, and debugging.

The screencast video above walks new users through using interactive mode.

To learn more about how to interact with a Jupyter notebook, start with this overview.

Neon Tutorials in the Notebook

neon tutorials on our nervansystems/neon_course github repo are aimed at demonstrating capabilities of neon, but they are all implemented inside ipython notebooks and make for a great starting point on working with neon in notebooks.

Start with the mnist example for a comprehensive walkthrough, but be sure to check out the others as well.

Launching a New Session

A new session can be launched with ncloud interact start from the command line, or from the Notebooks section in the UI. When launching a session, an ncloud dataset can be attached, as can a previously trained or imported model. See ncloud interact command line documentation for more details. Custom code repos and versions of neon are also supported.

Inside the web browser, python notebooks are provided as an easy way to test snippets of code, getting output in real time. It is also possible to run a terminal within the browser, which allows the user to customize the runtime environment in their container, e.g. by installing apt or pip packages.

Currently, changes made in a notebook are not persisted when the notebook session is stopped, but the session can be run indefinitely. It is possible to download notebook files using the Jupyter UI, or push changes to git repos from within the notebook terminal.


To provide the utmost flexibility as well as security and isolation, the notebook runs as the root user inside of an isolated container. It is possible to modify the environment inside the container by changing packages, configurations, etc. without impacting the underlying server or other interactive sessions.

The same filesystem paths are used inside the interactive environment as the ncloud model train environment, to ensure portability of code from one workflow to the other.

/notebook/code/ neon source code, and custom code repos are placed here
/notebook/data/ if a dataset is attached, it will be mounted here
/notebook/model/ if specified, a resumed model’s model.prm will be here
/notebook/output/ Any output generated during training should be placed here; for ncloud model train, the output will be saved automatically. A future release of interactive mode will also capture state from this directory, as well as providing snapshot capabilities.


A variety of graphical visualization tools for python have built in notebook support. It is easy to display images or plot data.


Users familiar with matplotlib will find using it in a notebook is seamless. Issuing the magic command %matplotlib inline causes all rendering to use the notebook backend.

For additional examples, see this Plotting with Matplotlib overview.

import numpy as np
import matplotlib.pyplot as plt

a = np.random.randn(100,100)

%matplotlib inline


Bokeh is another popular plotting framework built around python and javascript, with built in support for notebooks. Neon visualization tools are integrated with bokeh, as demonstrated in this example.

See this tutorial on Working in the Notebook for more information about bokeh capabilities.

First, train a model to generate some output data to plot.

%run code/neon/examples/ -o test.h5 -w stockdata

The functionality that powers nvis can be leveraged directly by importing from neon.visualizations.

Load the cost data and display a figure using bokeh. Note that the figure is interactive (mousewheel, drag and click).

from neon.visualizations.figure import cost_fig
from import h5_cost_data
from bokeh.plotting import output_notebook, show

cost_data = h5_cost_data('test.h5', epoch_axis=False)
show(cost_fig(cost_data, 300, 900, epoch_axis=epoch_axis))


Setting a Breakpoint

To set a specific breakpoint in code external to the notebook (e.g. another file:line, or function), insert a %debug statement on the same line as a statement that will trigger your breakpoint.

Running this cell will drop you into the debugger. From here, import the function that you want to break at, and set a breakpoint. Then type continue to run the statement following %debug and your breakpoint should be hit.

For example, break at the bprop function of the Convolution layer in neon, and examine the self.W tensor.


Post Mortem (most recent exception)

It is possible to revive the most recent exception in the context of a debugger to examine the stack, simply by executing $debug.



If working inside an ipython notebook isn’t flexible enough, or additional packages are required, a terminal can be used.

New Terminal

Start a terminal with the new -> terminal menu from the Jupyter home screen.



Inside the terminal, make sure to fire up a bash shell (bash) to get tab completion and syntax highlighting. Notice that you’re running as root - but you are inside of a container.

# bash

Package Installation

In order to install additional packages (python or otherwise), simply use the terminal.

Python packages installed system-wide in this manner are available immediately inside of running notebooks.

root@3fb9544639c2:/# apt-get install vim
root@3fb9544639c2:/# pip install matplotlib


The /notebook/ folder is where the notebook environment runs, and where you will find your model file, dataset, and code.

root@3fb9544639c2:/# cd notebook/
root@3fb9544639c2:/notebook# ls
code  data  model  output  stockdata


neon code can be modified and run inside the terminal, for example.

root@3fb9544639c2:/notebook# vim code/neon/neon/layers/
root@3fb9544639c2:/notebook# python code/neon/examples/


nvidia-smi shows GPU usage and memory information, as well as active processes.

root@3fb9544639c2:/notebook# nvidia-smi
Sat Jun 18 04:35:48 2016
| NVIDIA-SMI 346.46     Driver Version: 346.46         |
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|   0  Graphics Device     Off  | 0000:04:00.0     Off |                  N/A |
| 22%   28C    P2    76W / 250W |   1067MiB / 12287MiB |      0%      Default |

| Processes:                                                       GPU Memory |
|  GPU       PID  Type  Process name                               Usage      |