What is Atom?

Atom is a hackable text editor created by GitHub

Why Atom?

A dedicated code editor offers many advantages over pure command-line editors (vim, emacs) or SSH clients (MobaXterm, PuTTY)

• modern editing tools are magic
  • code completion, customizable shortcuts, etc.
  • if you’re really attached to vim/emacs, you can still use those within Atom as well!
• highly customizable, well documented
• ability to easily run/debug code and manage files within your editor

Why specifically Atom, over other alternatives like VS Code or Sublime?

• completely free
• thousands of open-source packages
• convenient Git integration for version control

Even if you prefer one of these options over Atom, it’s a major improvement over slow, rigid tools like MobaXterm and its default text editor.

Installation

Inital setup

• Download and run the installer from https://atom.io/

One of the first things to do after installing Atom would be set up your workspace.

Atom uses projects to manage different workspaces. For example, you might have a project for Bell, another for nanoHUB, and another for local runs.

• After opening Atom, create a new project by clicking Open a Project on the right pane
• Choose (or create) a folder where you want your workspace to be stored
• For this example, we’ll create a new folder called ‘Gilbreth’ we’ll use to connect to the Gilbreth cluster

Creating a git repository

If you’ve never used Git before, it’s a tool used for version control. Instead of only saving the most recent version of each file, Git can track its history.

While this tutorial will focus on individual uses of Git, it’s primary appeal is as a coding collaboration tool. To learn more about why Git is useful, see the explanation provided here. In short, here’s a few relevant terms useful to know

• repository: The location where all of your files and changes are stored. Rather than just a folder, think of it as a history of different states of your folder
• stage: After editing a file, you can stage the changes you made to indicate that you want them tracked. There are some changes which you don’t want to track (passwords, API keys, large files)
• commit: To commit adds all of the staged changes to your repository, saving this state
• push: To tell your repository that this commit/series of commits is the most updated version of your code
• pull: To pull is to take the latest pushed commit and update your files to reflect these changes. While it doesn’t have a huge meaning here, when working on teams it’s essential for sharing code.

Setting up a Git Repository

In the last step, we created a new project called ‘Gilbreth,’ now we’ll initialize a Git repository in this directory. Press CTRL-SHIFT-8 to open the GitHub panel.

• Click ‘Login’ and continue
• Copy the OAuth token to Atom to login
• Click ‘Initialize and publish on GitHub’
• Enter a repository name and set visibility (most likely private)

In addition, we want to set up the Git panel, which we open using CTRL-SHIFT-9.

• Enter your name and email address
• If you intend to use this login for all repositories, click ‘Use for all repositories’

You should now see a panel with three sections: unstaged changes, staged changes, and commit message. This will keep track of the changes you make and allow you to push them to Git.

Create the .gitignore file by selecting the ‘Gilbreth’ folder in the left pane and pressing a, then type ‘.gitignore’ and add whichever files names you don’t want to track

We can now make an initial commit

• In the Git panel, press ‘Stage All’ to stage your changes (creating the .gitignore file)
• Add a Commit message in the text box below, describing the changes this commit contains
• Click ‘Create detached commit’
• Click ‘Publish’ to set up a remote tracking branch

Congrats! You should be able to view your repository on GitHub, and have the system in place to stage, commit, and push your changes from within Atom.

Remote FTP

Atom describes itself as a ‘hackable’ text editor because it has thousands of community-made packages which greatly extend the utility of Atom. We’re now going to install some useful packages

Remote FTP is a package that transfers files between local and remote servers. This is useful when connecting to RCAC clusters or nanoHUB. In this exmaple, we’ll demonstrate how to connect to the Gilbreth cluster.

Press CTRL + , to open the Settings menu. From here, click ‘Install.’ This lets you query and install packages for Atom.

Locate and install the ‘remote-ftp’ package (by icetee). After it’s done installing, you can select ‘Packages → Remote FTP → Toggle’ from the menu bar. This will open a new tab in your left pane.

In this file, there are a few settings we need to change.

• host: ‘gilbreth.rcac.purdue.edu’
• user: ‘[[YOUR USERNAME]]’
• pass: ‘[[YOUR PASSOWRD]]’ (we’ll set up SSH keys later)
• remote: ‘home/[[YOUR USERNAME]]’

With this setup, you’ll still have to use 2FA each time you connect. Following the guide here, you can connect without 2FA

Platformio IDE Terminal

In addition to managing and editing files, it’s often useful to have a command line interface directly connected to the clusters. For this, we’ll use a package called platformio-ide-terminal

Similarly to Remote FTP, search for this package in settings and install

To automatically connect to a cluster by default, open Settings (CTRL + ,), then select ‘Packages → platformio-ide-terminal → Settings’. Within these settings, set ‘Auto Run Command’ to your ssh connection line. For example,

ssh [[YOUR USERNAME]]@gilbreth.rcac.purdue.edu

If you want to files in the cluster directly from the Atom editor, change your SSH command to use port-forwarding, as below

ssh -L[[1234]]:localhost:[[1234]] [[YOUR USERNAME]]@gilbreth.rcac.purdue.edu

Where [[1234]] is some arbitrary 4-digit number you’ll use as a port

Hydrogen

Hydrogen is an Atom package which lets you run Jupyter-like Python files within your Atom editor. This gives you the benefits of instantaneous code feedback, without being restricted by clunky Jupyter Notebooks.

Installation is similar to the previous steps - search for ‘Hydrogen’ (by nteract) and install.

Running local Python files

To run Hydrogen kernels locally, you’ll need to install Python. After installing Python, install the ipykernel package locally

pip install ipykernel
python -m ipykernel install

Let’s start by testing out Hydrogen using a simple python file. In your Gilbreth directory, create a new file called hydrogen.py

Hydrogen uses Python (.py) files to simulate Jupyter Notebooks. Similarly, it has markdown and code cells, which can be separated in the following way

# %% markdown

This is the content of the Markdown cell. $$H|\psi\rangle = E|\psi\rangle$$

# %% codecell

fish = 2+2
print("Wow Kat, thank you for writing this tutorial!")

Try copying the above cells into your hydrogen.py file, and typing ALT-SHIFT-ENTER. This should run the cell your cursor is in, then move down to the next cell

This system takes a little getting used to, but it’s essentially equivalent to cells in Jupyter notebooks

Running remote Python files

Running files locally is cool, but it’s often desired to run Python files directly in the cluster.

1. Connect to a cluster using ssh port forwarding (this should be done from the previous step)

ssh -L[[1234]]:localhost:[[1234]] [[YOUR USERNAME]]@gilbreth.rcac.purdue.edu

2. Setup config file in the cluster (you can do this using the platformio-ide-terminal)

pip install jupyter
jupyter notebook --generate-config

3. In config file (~/.jupyter/jupyter_notebook_config.py), uncomment

    #c.NotebookApp.token = ''

and set the string to some arbitrary phrase (i.e. ‘katnyp’)

4. Run a Jupyter server using

jupyter notebook --port=[[1234]] --no-browser

You should now see a Jupyter Notebook server running in the terminal!

5. If you just want to use your local Jupyter in-browser in the cluster environment, copy the output of the previous command into a browser

# it should look something like this
http://127.0.0.1:[[1234]]/?token=...

This is Jupyter notebook server connected to the RCAC clusters. Cool! But we want more, we want it within Atom

6. From Hydrogen package settings, set ‘Kernel Gateways’ to the following

[{
  "name": "Gilbreth",
  "options": {
    "baseUrl": "http://localhost:[[1234]]",
    "token": "[[your chosen token]]"
  }
}]

7. To connect, we there’s a few steps we need to take.

To connect to a remote kernel, open the command palette using CTRL-SHIFT-P

• type ’re k’ to select ‘Hydrogen: Connect to Remote Kernel’
• select Gilbreth
• choose ‘Authenticate with a token’
• type in your chosen token
• choose [new session] (or connect to an existing one)
• choose your desired Python kernel

Congrats, you’re now connected to the clusters! As a check, try adding the following code cell to your Python file

# %% codecell
import os
os.getcwd()

You should see that you’re in the cluster!

Other useful packages

That’s the gist of the tutorial, I hope you found it useful! Feel free to reach out if you have any questions, email or slack works best.

Atom has tons of open-source packages. This is great, but it also means that you need to be careful with installing random packages. I tend to only install packages with large user bases and active communities to check for vulnerabilities.

Cool packages that didn’t warrant their own pages:

• atom-beautify: adjusts your code to fit proper code formatting standards
• highlight-selected: highlights the current word selected (everywhere it appears) when double clicked
• jumpy: navigate around your code with dynamic hotkeys
• minimap: preview your full code in your scroll bar
• pp-markdown: live preview Markdown files (useful for writing this tutorial!)
• split-diff: compare differences between two files
• todo-show: finds all TODOs, FIXMEs, etc. in your project and compiles them into a list
• zentabs: sets a maximum on the number of opened tabs