CommunityData:Hyak

 Note: This page is intended to replace the main CommunityData:Hyak page in the near future. This is a part of our transition to the new Slurm-based job scheduler. Some of the sections may be incomplete, and the instructions may not work. Feel free to edit and fix the content that is incorrect/out-of-date.

To use Hyak, you must first have a UW NetID, access to Hyak, and a two factor authentication token. Details on getting set up with all three are available at CommunityData:Hyak setup.

There are a number of other sources of documentation:

• Slides from the UW HPC Club
• Hyak User Documentation

Setting up SSH

When you connect to SSH, it will ask you for a key from your token. Typing this in every time you start a connection be a pain. One approach is to create an .ssh config file that will create a "tunnel" the first time you connect and send all subsequent connections to Hyak over that tunnel. Some details in the Hyak documentation.

I've added the following config to the file ~/.ssh/config on my laptop (you will want to change the username):

 Host hyak-mox mox2.hyak.uw.edu
     User sdg1
     HostName mox2.hyak.uw.edu
     ControlPath ~/.ssh/master-%r@%h:%p
     ControlMaster auto
     ControlPersist yes
     Compression yes

ONE WARNING: If your SSH connection becomes stale or disconnected (e.g., if you change networks) it may take some time for the connection to time out. Until that happens, any connections you make to hyak will silently hang. If your connections to ssh hyak are silently hanging but your Internet connection seems good, look for ssh processes running on your local machine with:

ps ax|grep hyak

If you find any, kill them with kill <PROCESSID>. Once that is done, you should have no problem connecting to Hyak.

Connecting to Hyak

To connect to Hyak, you now only need to do:

ssh hyak-mox

It will prompt you for your UWNetID's password. Once you type in your password, you will have to respond a [2-factor authentication request].

Setting Up Hyak

When setting up Hyak, you must first add this stanza to the very bottom of your ~/.bashrc file. Generally, you can simply edit the following file on Hyak: ~/.bashrc

## START hyak-cdsc specific options -- BOTTOM OF FILE
 
source /etc/profile.d/modules.sh
 
alias big_machine='srun -p mako -A mako --mem=248G --time=500:00:00 --pty bash -l'
alias any_machine='srun -p mako -A mako --mem=124G --time=500:00:00 --pty bash -l'
alias build_machine='srun -p build --mem=100G --time=2:00:00 --pty bash -l'
alias queue_state='squeue -p mako'
 
MODULEPATH=/gscratch/mako/modules/modulefiles:$MODULEPATH
module load pandoc/2.2.1
module load R/3.5.0
 
umask 007
 
## END hyak-cdsc specific options -- BOTTOM OF FILE

The final line is particularly important. If you do not do this, the files you create on Hyak will be able to be read or written by others in the group!

Once you do this, you will need to restart bash. This can be done simply by logging out and then logging back in or by restarting bash with the command exec bash.

I also add these two lines to my Hyak .ssh/config:

ForwardX11 yes
ForwardX11Trusted yes

These lines will mean that if I have "checked out" an interactive machine, I can ssh from my computer to Hyak and then directly through an addition hop to the machine (like ssh n0652). Those ForwardX11 lines means if I graph things on this window, they will open on my local display.

Custom software in Hyak

Software on Hyak can be outdated, or in some cases, not available at all. In some of these situations, it may be possible to use environment modules to install and run software without necessitating administrative (root) privileges. For example, it is possible to have and run the newest version of R that is installed in a central, shared directory, and it is even possible to have multiple versions of R available in parallel. The following subsection shows how to do this. Ordinarily, this should be necessary on a day-to-day basis.

Installing and making available a custom module

 Note: If you are using screen to run and manage your builds, keep in mind that screen drops a few environment variables such as LD_LIBRARY_PATH, which may mess up your builds. You should check that all the relevant environment variables are set before starting your build.

The first step toward installing and making available a custom module (in this case, R 3.5.0) is to spin up the build node, download R, compile it with a specific prefix, and install it.

$ build_machine
$ module load contrib/texlive/2017  # loads the texlive module that is helpful for generating R documentation
$ module load contrib/openblas/0.2.20  # loads the openblas library, which speeds up some R operations significantly
$ wget https://cran.r-project.org/src/base/R-3/R-3.5.0.tar.gz
$ tar xzvf R-3.5.0.tar.gz
$ cd R-3.5.0
$ ./configure --prefix=/gscratch/mako/modules/sw/R/3.5.0  --with-x --enable-R-shlib --with-lapack --with-blas="-L/sw/contrib/openblas/0.2.20/lib -lopenblas"
$ make
$ make install

The --prefix option to ./configure tells the build scripts that R is going to be installed in /gscratch/mako/modules/sw/R/3.5.0. This follows a convention that we picked—software in modules should go into /gscratch/mako/modules/sw/{SOFTWARE_NAME}/{SOFTWARE_VERSION}. The --prefix option is the most important flag for ./configure—any other flag or option will be specific to the software being installed.

The second step is to write a modulefile. This contains the metadata about our module. Edit the file /gscratch/mako/modules/modulefiles/R/3.5.0 to contain the following

#%Module1.0####################################################################
##
proc ModulesHelp { } {
        puts stderr "\tModule providing R 3.5.0."
}

module-whatis "Module providing R 3.5.0."

module load contrib/openblas/0.2.20
prepend-path    PATH            /gscratch/mako/modules/sw/R/3.5.0/bin
prepend-path    MANPATH         /gscratch/mako/modules/sw/R/3.5.0/share/man

# The following line prevents everyone from installing libraries in the global namespace
file mkdir ~/R/x86_64-pc-linux-gnu-library/3.5

Note that the filename follows a similar convention as --prefix earlier (/gscratch/mako/modules/modulefiles/{SOFTWARE_NAME}/{SOFTWARE_VERSION}). This file sets up the PATH and MANPATH environment variables appropriately so that the specified version of R can be accessed and run as needed. There are many more directives that can go into the modulefile—see man modulefile for details on those directives.

Once this file is written out, the module avail command should list R/3.5.0 as an available module. This is because the module system is set up to look inside /gscratch/mako/modules/modulefiles for module files, thanks to the MODULEPATH variable that is set through .bashrc. The command module load R/3.5.0 should make R available and ready for use. To avoid running module load R/3.5.0 whenever you log in, you can add the command at the end of your .bashrc file (after the section that sets MODULEPATH).

Parallel R

The nodes on Hyak have 28 CPU cores. These may help in speeding up your analysis significantly. If you are using R functions such as lapply, there are parallelized equivalents (e.g. mclappy) which can take advantage of all the cores and give you a 2800% boost! However, something to be aware of here is memory requirements—if you are running 28 processes in parallel, your memory needs can also go up to 28x, which may be more than the ~240GB that the big_machine node will have. In such cases, you may want to dial down the number of CPU cores being used—a way to do that globally in your code is to run the following snippet of code before calling any of the parallelized functions.

library(parallel)
options(mc.cores=20)  ## tell the mc* functions to use 20 cores unless otherwise specified

More information on parallelizing your R code can be found in the parallel package documentation.

Jupyter Notebook on Hyak

1. Choose a number you are going to use as a port. We should each use a different port and the number should be between 1000 and 65000. It doesn't matter what it is but it needs to be unique. Pick something unique. In the following instructions, replace $PORT with your number below.

2. Connect to Hyak and forward the the port from you local machine to the new one:

ssh -L localhost:$PORT:localhost:$PORT username@hyak.washington.edu

You can also add the following line to the Hyak section on your local .ssh/config file on your laptop:

    LocalForward $PORT localhost:$PORT

3. We're going to need to connect to one of the compute servers twice. As a result, we'll use a program called tmux. Tmux is very similar (but a little easier to learn) than a program called screen. If you know screen, just use that. Otherwise, run tmux like:

tmux

You can tell you're in tmux because of the green line at the bottom of the screen.

4. "Check out" a compute node

any_machine

5.

Keep track of which machine you are on. It should be something like n0650 and it should be displayed on the prompt. We'll refer to it as $HOST below.

6. Start jupyter on the compute node:

jupyter-notebook --no-browser --port=$PORT

You'll see that jupyter just keeps running in the background. This can be useful because when there are errors, they will sometimes be displayed in this terminal. Generally, you can just ignore this though.

6. Create a new window in tmux/screen

At this point, you have jupyter running on the compute node on $PORT. You also will have forwarded the port from your laptop to the login node. We're really only missing one thing which is the tunnel from the login node to the compute node within hyak. To do this, we'll create a new window inside tmux with the keystroke Ctrl-b c.

If you're not familiar with it, you'll want to read the CommunityData:tmux which includes a quick cheatsheet. To switch back to the original window running jupyter, you should type: Ctrl-b 0. If you switch though, be sure to switch back to the new window with Ctrl-b 1.

Because you originally ran tmux on the login node, the new window/terminal will be opened within tmux on the login node.

7. Open a tunnel from the login node to the compute node.

 ssh -L localhost:$PORT:localhost:$PORT $HOST

8. In your local browser, localhost:$PORT

Running Jobs on Hyak

Killing jobs on compute nodes

The Slurm scheduler provides a command called scancel to terminate jobs. For example, you might run queue_state from a login node to figure out the ID number for your job (let's say it's 12345), then run scancel --signal=TERM 12345 to send a SIGTERM signal or scancel --signal=KILL 12345 to send a SIGKILL signal that will bring job 12345 to an end.

Working on Hyak from a local emacs client

Some of us (like Nate) rely heavily on the Emacs text editor. Emacs speaks statistics is a powerful emacs mode for programming in R and doing data analysis. There are a few options for using Emacs on hyak. If you open emacs on an interactive node with X-forwarding enabled then you will get a nice graphical emacs window and plots you make will be displayed on your screen. But if you disconnect from Hyak you will lose your R session. This makes running emacs the normal way on an interactive node unsuitable for fitting models. Another disadvantage is that your will be working with an x-forwarded emacs and so will not look as nice or be as responsive as your local emacs.

Alternatively, you might run emacs in console mode in tmux. Then Hyak will keep running your R process even when you log out. The downsides here is that you can't view plots on your display (you could save them as a pdf, and then open the pdf on your local machine) and that some emacs key chords will collide with tmux key bindings and configuring tmux to fix this is a pain.

A better way is to run emacs server on a compute node on hyak and then open a local emacs client that connects to that server.

Instructions For ESS

Unfortunately, this requires running emacsserver on a login node and viewing plots does not work. These problems should go away if hyak let us forward X from a compute node and tunnel it through a login node. This doesn't seem to work as ssh -X n0649 doesn't seem to forward X.

1. Open tmux on a login node and start emacsserver.

 $ tmux
 $ emacs --daemon

2. Still in tmux, start an interactive session

 $ any_machine

3. In a new terminal (not tmux) ssh into the login node and start an emacs client (-c means in a new window).

 $ emacsclient -c

4. In this emacsclient open a shell, ssh to the compute node, and start an R process.

 M-x shell
 $ ssh n0649

5. With focus on the R process buffer in emacs, connect ESS to the R process.

  M-x ess-remote