README.md

EvCxR Jupyter Kernel

A Jupyter Kernel for the Rust programming language.

Installation

If you don't already have Rust installed, follow these instructions.

Linux (Debian/Ubuntu)

rustup component add rust-src
sudo apt install jupyter-notebook cmake
cargo install evcxr_jupyter
evcxr_jupyter --install

Alternative instructions if you want to use libzmq from your system:

sudo apt install libzmq3-dev jupyter-notebook
cargo install evcxr_jupyter --no-default-features
evcxr_jupyter --install

Once installed, you should be able to start Juypter notebook with:

jupyter-notebook

Once it starts, it should open a new tab in your browser, or at least print a link for you to open. From this tab you can select File -> New Notebook -> Rust.

Mac OS X

• Install jupyter or jupyterlab (eg. via anaconda)
• Install cmake. These instructions might help.

cargo install evcxr_jupyter
evcxr_jupyter --install

Alternative instructions if you want to use libzmq from your system. Note, if following these instructions, then you shouldn't need to install cmake.

brew install zeromq pkg-config
cargo install evcxr_jupyter --no-default-features
evcxr_jupyter --install

Windows

Note that Evcxr on Windows appears to be substantially slower than on other platforms. We're not yet sure why.

• Install jupyter or jupyterlab (eg. via anaconda)
• Install CMake

cargo install evcxr_jupyter
evcxr_jupyter --install

If you'd like to install ZMQ yourself, rather than having cargo install build it for you, then These instructions might help.

Usage information

Evcxr is both a REPL and a Jupyter kernel. See Evcxr common usage for information that is common to both.

Custom output

The last expression in a cell gets printed. By default, we'll use the debug formatter to emit plain text. If you'd like, you can provide a function to show your type (or someone else's type) as HTML (or an image). To do this, the type needs to implement a method called evcxr_display which should then print one or more mime-typed blocks to stdout. Each block starts with a line containing BEGIN_EVCXR_OUTPUT followed by the mime type, then a newline, the content then ends with a line containing EVCXR_END_CONTENT.

For example, the following shows how you might provide a custom display function for a type Matrix. You can copy this code into a Jupyter notebook cell to try it out.

use std::fmt::Debug;
pub struct Matrix<T> {pub values: Vec<T>, pub row_size: usize}
impl<T: Debug> Matrix<T> {
    pub fn evcxr_display(&self) {
        let mut html = String::new();
        html.push_str("<table>");
        for r in 0..(self.values.len() / self.row_size) {
            html.push_str("<tr>");
            for c in 0..self.row_size {
                html.push_str("<td>");
                html.push_str(&format!("{:?}", self.values[r * self.row_size + c]));
                html.push_str("</td>");
            }
            html.push_str("</tr>");
        }
        html.push_str("</table>");
        println!("EVCXR_BEGIN_CONTENT text/html\n{}\nEVCXR_END_CONTENT", html);
    }
}
let m = Matrix {values: vec![1,2,3,4,5,6,7,8,9], row_size: 3};
m

It's probably a good idea to either print the whole block at once, or to lock stdout then print the block. This should ensure that nothing else prints to stdout at the same time (at least no other Rust code).

If the content is binary (e.g. mime type "image/png") then it should be base64 encoded.

Prompting for input

:dep evcxr_input
let name = evcxr_input::get_string("Name?");
let password = evcxr_input::get_password("Password?");

Installing from git head

If there's a bugfix in git that you'd like to try out, you can install directly from git with the command:

cargo install --force --git https://github.com/google/evcxr.git evcxr_jupyter

3rd party integrations

There are several Rust crates that provide Evcxr integration:

• Petgraph
  • Graphs (the kind with nodes and edges)
• Plotly
  • Lots of different kinds of charts
• Plotters
  • Charts
• Showata
  • Displays images, vectors, matrices (nalgebra and ndarray)

3rd party resources

• Dr. Shahin Rostami has written a book Data Analysis with Rust Notebooks. He's also put up a great getting started video.

Limitations

• Don't ask Jupyter to "interrupt kernel", it won't work. Rust threads can't be interrupted.

Uninstall

evcxr_jupyter --uninstall
cargo uninstall evcxr_jupyter