Atom Packages Directory

a package directory for a text editor of the 21st Century

Hydrogen by Will Whitney

Install with:
    apm install hydrogen
  

Hydrogen

slack in Greenkeeper badge Build Status

This package lets you run your code directly in Atom using any Jupyter kernels you have installed.

Checkout our Medium blog post to see what you can do with Hydrogen.

hero

Contents

  1. Background
  2. Features
  3. Installation
  4. Troubleshooting
  5. Usage
  6. Plugins for Hydrogen
  7. How it works
  8. Remote kernels via kernel gateways
  9. Custom kernel connection
  10. Why “Hydrogen”?
  11. Development

Background

Hydrogen was inspired by Bret Victor’s ideas about the power of instantaneous feedback and the design of Light Table. Running code inline and in real time is a more natural way to develop. By bringing the interactive style of Light Table to the rock-solid usability of Atom, Hydrogen makes it easy to write code the way you want to.

You also may be interested in our latest project – nteract – a desktop application that wraps up the best of the web based Jupyter notebook.

Features

Installation

For all systems, you’ll need

You can now run apm install hydrogen or search for Hydrogen in the Install pane of the Atom settings.

If you are using Linux 32-bit follow the installation instructions here.

Kernels

Tested and works with:

But it should work with any kernel. If you are using Hydrogen with another kernel please add it to this list or post an issue if anything is broken!

Note that if you install a new kernel, you’ll need to run Hydrogen: Update Kernels for Hydrogen to find it. For performance reasons, Hydrogen only looks for available kernels when it first starts.

Debian 8 and Ubuntu 16.04 LTS

Unfortunately, the versions of IPython provided in Debian’s and Ubuntu’s repositories are rather old and Hydrogen is unable to detect the kernel specs installed in your machine. To workaround this issue, Hydrogen provides the setting KernelSpec, where the user can declare the kernel specs manually. Find the KernelSpec setting in the Atom GUI by going to the Settings pane, click Packages, search for Hydrogen, and click the Hydrogen Settings button.

Below is an example KernelSpec for IPython 2 and 3:

json { "kernelspecs": { "python2": { "spec": { "display_name": "Python 2", "language": "python", "argv": ["python2.7", "-m", "ipykernel", "-f", "{connection_file}"], "env": {} } }, "python3": { "spec": { "display_name": "Python 3", "language": "python", "argv": ["python3.4", "-m", "ipykernel", "-f", "{connection_file}"], "env": {} } } } }

Troubleshooting

We have a troubleshooting guide! It’s pretty sparse at the moment, so please share with us the resolution to any rough spots that you find.

Usage

Hydrogen provides a selection of commands for running code. Press ⌘-⇧-P to open the command palette and type “hydrogen” and they will come up.

“Hydrogen: Run”

There are two ways to tell Hydrogen which code in your file to run.

  1. Selected code: If you have code selected when you hit Run, Hydrogen will run exactly that code.
  2. Current block: With no code selected, Hydrogen will try to find the complete block that’s on or before the current line.

    • If the line you’re on is already a complete expression (like s = "abracadabra"), Hydrogen will run just that line.

    • If the line you’re on is the start of a block like a for loop, Hydrogen will run the whole block.

    • If the line you’re on is blank, Hydrogen will run the first block above that line.

It’s easiest to see these interactions visually:

execute

“Hydrogen: Run And Move Down” will run the the code as described above and move the cursor to the next executable line.

If your code starts getting cluttered up with results, run “Hydrogen: Clear Results” to remove them all at once.

“Hydrogen: Run Cell”

A “code cell” is a block of lines to be executed at once. You can define them using inline comments. Hydrogen supports a multitude of ways to define cells. Pick the one you like best. The following is an example for python but it will work in any language, just replace # with the comment symbol for your desired language:

<img width=280 src=”https://cloud.githubusercontent.com/assets/13285808/17094174/e8ec17b8-524d-11e6-9140-60b43e073619.png”>

When you place the cursor inside a cell and hit “Run Cell”, Hydrogen will execute this cell. The command “Hydrogen: Run Cell And Move Down” will move the cursor to the next cell after execution.

“Hydrogen: Run All” and “Hydrogen: Run All Above”

These commands will run all code inside the editor or all code above the cursor.

Watch Expressions

After you’ve run some code with Hydrogen, you can use the “Hydrogen: Toggle Watches” command from the Command Palette to open the watch expression sidebar. Whatever code you write in watch expressions will be re-run after each time you send that kernel any other code.

watch

IMPORTANT: Be careful what you put in your watch expressions. If you write code that mutates state in a watch expression, that code will get run after every execute command and likely result in some extremely confusing bugs.

You can re-run the watch expressions by using the normal run shortcut (⌘-↩ by default) inside a watch expression’s edit field.

If you have multiple kernels running, you can switch between their watch expressions with the “Hydrogen: Select Watch Kernel” command (or just click on the “Kernel: " text).

Completion

Receive completions from the running kernel.

Code Introspection

You can use the “Hydrogen: Toggle Inspector” command from the Command Palette to get metadata from the kernel about the object under the cursor.

Managing kernels

Sometimes things go wrong. Maybe you’ve written an infinite loop, maybe the kernel has crashed, or maybe you just want to clear the kernel’s namespace. Use the command palette to interrupt (think Ctrl-C in a REPL) or restart the kernel.

You can also access these commands by clicking on the kernel status in the status bar or via the command palette. It looks like this:

<img src=”https://cloud.githubusercontent.com/assets/13285808/16894732/e4e5b4de-4b5f-11e6-8b8e-facf17a7c6c4.png” width=300>

Additionally, if you have two or more kernels for a particular language (grammar), you can select which kernel to use with the “Switch to " option in the Kernel Commands menu.

Multiple kernels inside one rich document

If you are working in a markup file that supports highlighted code blocks, we can handle multiple kernels per file. This way you can write your documentation, readme or paper together with your code while retaining the interactivity of Hydrogen.

<img src=”https://cloud.githubusercontent.com/assets/13285808/24365090/0af6a91c-1315-11e7-92c6-849031bf9f6a.gif” height=350>

We support markdown, gfm, asciidoc, reStructuredText and knitr.

Plugins for Hydrogen

Hydrogen has support for plugins. Feel free to add your own to the list: - Hydrogen Launcher

If you are interested in building a plugin take a look at our plugin API documentation.

How it works

Hydrogen implements the messaging protocol for Jupyter. Jupyter (formerly IPython) uses ZeroMQ to connect a client (like Hydrogen) to a running kernel (like IJulia or iTorch). The client sends code to be executed to the kernel, which runs it and sends back results.

Remote kernels via kernel gateways

In addition to managing local kernels and connecting to them over ZeroMQ, Hydrogen is also able to connect to Jupyter Notebook (or Jupyter Kernel Gateway) servers. This is most useful for running code remotely (e.g. in the cloud).

To connect to a server, you must first add the connection information to the Hydrogen gateways setting. An example settings entry might be:

json [{ "name": "Remote notebook", "options": { "baseUrl": "http://example.com:8888", "token": "my_secret_token" } }]

Each entry in the gateways list needs at minimum a name (for displaying in the UI), and a value for options.baseUrl. The options.token should only be present if your server requires token authentication, in which case it should contain the specific token issued by your server. (Token authentication is enabled by default for Jupyter Notebook 4.3 or later). The options are passed directly to the @jupyterlab/services npm package, which includes documentation for additional fields.

After gateways have been configured, you can use the “Hydrogen: Connect to Remote Kernel” command. You will be prompted to select a gateway, and then given the choice to either create a new session or connect to an existing one.

Unlike with local kernels, Hydrogen does not kill remote kernels when it disconnects from them. This allows sharing remote kernels between Hydrogen and the Notebook UI, as well as using them for long-running processes. To clean up unused kernels, you must explicitly call the “Hydrogen: Shutdown Kernel” command while connected to a kernel.

Example with notebook server

To set up a server on the remote machine, you could

bash pip install jupyter

bash jupyter notebook --generate-config

bash jupyter notebook --port=8888

Example with kernel gateway server

As of December 2016, we recommend that you use a notebook server (version 4.3 or greater) instead of the Jupyter Kernel Gateway. We expect this to change in the future, and will update this README when that occurs.

Docker execution via kernel gateways

You can use the same technique to create a kernel gateway in a Docker container. That would allow you to develop from Atom but with all the dependencies, autocompletion, environment, etc. of a Docker container.

Note: due to the way that the kernel gateway creates sub-processes for each kernel, you have to use it in a special way, you can’t run the jupyter kernelgateway directly in your Dockerfile CMD section. You need to call it with an init manager such as tini or run it from an interactive console.

If all you need is a Docker Python environment to execute your code, you can read the section Example Jupyter Docker Stack kernel gateway (this method uses tini under the hood).

If you want to add a temporal Kernel Gateway (for development) to your current Docker images or need to modify an existing image to add the Kernel Gateway functionality, read the section Example Docker kernel gateway (this method runs the kernel gateway from an interactive console).

Example Jupyter Docker Stack kernel gateway

Follow this if you only need to have a simple environment to run commands inside a Docker container and nothing more.

If you need to customize a Docker image (e.g. for web development) follow the section below: Example Docker kernel gateway.

Dockerfile

```Dockerfile FROM jupyter/minimal-notebook

RUN pip install jupyter_kernel_gateway

EXPOSE 8888 CMD [“jupyter”, “kernelgateway”, “–KernelGatewayApp.ip=0.0.0.0”, “–KernelGatewayApp.port=8888”] ```

Run Docker Container with Docker commands

Note: alternatively, see below for docker-compose instructions.

bash docker build -t hydro-kernel-gateway .

bash docker run -it --rm --name hydro-kernel-gateway -p 8888:8888 hydro-kernel-gateway

Note: you will only be able to run one container using that port mapping. So, if you had another container using that port, you will have to stop that one first. Or alternatively, you can create a mapping to a new port and add that configuration in the Hydrogen settings (see below).

Run Docker Container with Docker Compose

yml version: '2' services: hydro-kernel-gateway: build: . ports: - "8888:8888"

Note: you will only be able to run one container using that port mapping. So, if you had another container using that port, you will have to stop that one first. Or alternatively, you can create a mapping to a new port and add that configuration in the Hydrogen settings (see below).

bash docker-compose up -d

bash docker-compose ps

Connect Atom

Now you need to connect Atom to your setup. Follow the section Connect Atom below.

Example Docker kernel gateway

Follow this if you need to customize a Docker image you already have. For example, for a web project.

If you only need a simple environment in where to run Python commands with Hydrogen inside a Docker container, follow the section above: Example Jupyter Docker Stack kernel gateway.

Dockerfile

```Dockerfile FROM python:2.7

Remove in production

RUN pip install jupyter_kernel_gateway EXPOSE 8888 ```

Run Docker Container with Docker commands

Note: alternatively, see below for docker-compose instructions.

bash docker build -t hydro .

bash docker run -d -p 8888:8888 --name hydro hydro bash -c "while true; do sleep 10; done"

Note: you will only be able to run one container using that port mapping. So, if you had another container using that port, you will have to stop that one first. Or alternatively, you can create a mapping to a new port and add that configuration in the Hydrogen settings (see below).

bash docker exec -it hydro bash

bash jupyter kernelgateway --ip=0.0.0.0 --port=8888

Run Docker Container with Docker Compose

yml version: '2' services: hydro: build: . ports: - "8888:8888" command: bash -c "while true; do sleep 10; done"

Note: you will only be able to run one container using that port mapping. So, if you had another container using that port, you will have to stop that one first. Or alternatively, you can create a mapping to a new port and add that configuration in the Hydrogen settings (see below).

bash docker-compose up -d

bash docker-compose ps

bash docker exec -it myproject_hydro_1 bash

bash jupyter kernelgateway --ip=0.0.0.0 --port=8888

Connect Atom

JSON [{"name": "Docker Toolbox", "options": {"baseUrl": "http://192.168.99.100:8888"}}]

Testing it

You can test that it is actually working by installing a package in your container that you don’t have locally and using it inside your container (from your Atom editor).

```Dockerfile FROM python:2.7

RUN pip install markdown

Remove in production

RUN pip install jupyter_kernel_gateway EXPOSE 8888 ```

Note: If you followed the Example Jupyter Docker Stack kernel gateway section, your Dockerfile will look different. Just make sure you add a line with:

Dockerfile RUN pip install markdown

python import markdown markdown.version

python import markdown [✓] markdown.version ['2.6.6']

Terminate the connection and container

But, if you are using the general instructions (for a custom Docker image), because of the way Jupyter Kernel Gateway creates sub-processes and due to the fact that you are running in a Docker container, the actual kernel process will still be running.

bash ps -fA

root@6d09f8fee132:/# ps -fA UID PID PPID C STIME TTY TIME CMD root 1 0 0 00:21 ? 00:00:00 bash -c while true; do sleep 10; done root 10 0 0 00:22 ? 00:00:00 bash root 23 0 0 00:22 ? 00:00:00 /usr/local/bin/python2 -m ipykernel -f /root/.local/share/jupyter/runtime/kernel-95baef8a-6427-4415-bc95-e02dc74e4ebb.js root 77 1 0 00:28 ? 00:00:00 sleep 10 root 78 10 0 00:28 ? 00:00:00 ps -fA

bash pkill python

bash exit

Custom kernel connection

Hydrogen also supports using a custom kernel connection file for each project. It could be used to connect to “remote” environments as Docker, a remote computer, etc. But the method described above using kernel gateways is less error prone and simpler to apply in more cases.

The recommended way of connecting to remote kernels is now using kernel gateways as described above. But if you still need to use a custom kernel connection file you can read the Custom kernel connection guide here.

Why “Hydrogen”?

Hydrogen atoms make up 90% of Jupiter by volume.

Plus, it was easy to make a logo.

hydrogen logo

Development

#### Quick and dirty setup

apm develop hydrogen

This will clone the hydrogen repository to ~/github unless you set the ATOM_REPOS_HOME environment variable.

I already cloned it!

If you cloned it somewhere else, you’ll want to use apm link --dev within the package directory, followed by apm install to get dependencies.

Workflow

After pulling upstream changes, make sure to run apm update.

To start hacking, make sure to run atom --dev from the package directory. Cut a branch while you’re working then either submit a Pull Request when done or when you want some feedback!

Running specs

You can run specs by triggering the window:run-package-specs command in Atom. To run tests on the command line use apm test within the package directory.

You can learn more about how to write specs here.

⬆ back to top

Keywords: execute, run, jupyter, ipython, julia, python, torch, ijulia, itorch, plot, image Suggest keywords
Fork me on GitHub