Editing CommunityData:Hyak
From CommunityData
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
{{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 [https://slurm.schedmd.com/ 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: | |||
* [http://students.washington.edu/hpcc/using-hyak/information-for-beginner-users/slides-from-training-sessions/ Slides from the UW HPC Club] | |||
* [http://wiki.hyak.uw.edu Hyak User Documentation] | |||
== Setting up SSH == | == Setting up SSH == | ||
Line 24: | Line 16: | ||
I've added the following config to the file <code>~/.ssh/config</code> on my laptop (you will want to change the username): | I've added the following config to the file <code>~/.ssh/config</code> on my laptop (you will want to change the username): | ||
Host hyak mox2.hyak.uw.edu | Host hyak-mox mox2.hyak.uw.edu | ||
User | User sdg1 | ||
HostName mox2.hyak.uw.edu | HostName mox2.hyak.uw.edu | ||
ControlPath ~/.ssh/master-%r@%h:%p | ControlPath ~/.ssh/master-%r@%h:%p | ||
Line 36: | Line 28: | ||
ps ax|grep hyak | ps ax|grep hyak | ||
If you find any, kill them with <code>kill | If you find any, kill them with <code>kill <PROCESSID></code>. 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 to a [https://itconnect.uw.edu/security/uw-netids/2fa/ 2-factor authentication request]. | |||
== Setting Up Hyak == | |||
When setting up Hyak, you must first add this stanza to the ''very bottom'' of your <code>.bashrc</code> file. Generally, you can simply edit the following file on Hyak: <code>~/.bashrc</code> | |||
<source lang="bash"> | |||
## START hyak-cdsc specific options -- BOTTOM OF FILE | |||
source /etc/profile.d/modules.sh | |||
alias big_machine='srun -p mako -A mako --mem=200G --time=500:00:00 --pty bash -l' | |||
alias any_machine='srun -p mako -A mako --mem=100G --time=500:00:00 --pty bash -l' | |||
alias build_machine='srun -p build --mem=16G --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 | |||
module load contrib/python/3.6.3 | |||
umask 007 | |||
## END hyak-cdsc specific options -- BOTTOM OF FILE | |||
</source> | |||
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 <code>exec bash</code>. | |||
=== X11 forwarding === | === X11 forwarding === | ||
You may also want to add these two lines to your Hyak .ssh/config: | |||
You may also want to add these two lines to your Hyak | |||
ForwardX11 yes | ForwardX11 yes | ||
ForwardX11Trusted yes | ForwardX11Trusted yes | ||
These lines will mean that if you have "checked out" an interactive machine, you can ssh from your computer to Hyak and then directly through an addition hop to the machine (like ssh | These lines will mean that if you have "checked out" an interactive machine, you can ssh from your computer to Hyak and then directly through an addition hop to the machine (like ssh n0652). Those ForwardX11 lines means if you graph things on this session, they will open on your local display. | ||
=== Moving files from ikt to mox === | |||
You can copy files at high speed without a password between the Hyak systems using commands like the ones below (instructions from the [http://wiki.cac.washington.edu/display/hyakusers/Hyak+mox+Overview Hyak documentation]). | |||
'''From ikt to mox''' | |||
ikt1$ hyakbbcp myfile mox1.hyak.uw.edu:/gscratch/mako/users/YOUR_DIR | |||
ikt1$ hyakbbcp -r mydirectory mox1.hyak.uw.edu:/gscratch/mako/users/YOUR_DIR | |||
'''From mox to ikt''' | |||
mox1$ hyakbbcp myfile ikt1.hyak.uw.edu:/com/users/YOUR_DIR | |||
mox1$ hyakbbcp -r mydirectory ikt1.hyak.uw.edu:/com/users/YOUR_DIR | |||
== Running Jobs on Hyak == | |||
When you first log in to Hyak, you will be on a "login node". These are nodes that have access to the Internet, and can be used to update code, move files around, etc. They should not be used for computationally intensive tasks. To actually run jobs, there are a few different options, described in detail [http://wiki.cac.washington.edu/display/hyakusers/Mox_scheduler in the Hyak User documentation]. Following are basic instructions for some common use cases. | |||
=== Interactive nodes === | |||
Interactive nodes are systems where you get a <code>bash</code> shell from which you can run your code. This mode of operation is conceptually similar to running your code on your own computer, the difference being that you have access to much more CPU and memory. To check out an interactive node, run the <code>big_machine</code> or <code>any_machine</code> command from your login shell. Before running these commands, you will want to be in a [[CommunityData:Tmux|<code>tmux</code>]] or <code>screen</code> session so that you can start your job, and log off without having to worry about your job getting terminated. | |||
{{note}} At a given point of time, unless you are using the <code>ckpt</code> (formerly the <code>bf</code>) queue, you can have one instance of <code>big_machine</code> and three instances of <code>any_machine</code> running at the same time. You may need to coordinate over IRC if you need to use a specific node for any reason. | |||
=== Killing jobs on compute nodes === | |||
The Slurm scheduler provides a command called [https://slurm.schedmd.com/scancel.html scancel] to terminate jobs. For example, you might run <tt>queue_state</tt> from a login node to figure out the ID number for your job (let's say it's 12345), then run <tt>scancel --signal=TERM 12345</tt> to send a SIGTERM signal or <tt>scancel --signal=KILL 12345</tt> to send a SIGKILL signal that will bring job 12345 to an end. | |||
=== 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 <code>lapply</code>, there are parallelized equivalents (e.g. <code>mclappy</code>) which can take advantage of all the cores and give you a 2800% boost! However, something to be aware of here is your code's memory requirement—if you are running 28 processes in parallel, your memory needs can also go up to 28x, which may be more than the ~200GB that the <code>big_machine</code> 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. | |||
== | <source lang="r"> | ||
library(parallel) | |||
options(mc.cores=20) ## tell the mc* functions to use 20 cores unless otherwise specified | |||
mcaffinity(1:20) | |||
</source> | |||
More information on parallelizing your R code can be found in the [https://stat.ethz.ch/R-manual/R-devel/library/parallel/doc/parallel.pdf <code>parallel</code> package documentation]. | |||
<!-- The hyak machines have 16 cpu cores. The Mox machines will have 28! Running your program on all the cores can speed things up a lot! We make heavy use of R for building datasets and for fitting models. Like most programming languages, R uses only one cpu by default. However, for typical computation-heavy data science tasks it is pretty easy to make R use all the cores. | |||
For fitting models, the R installed in Gentoo should use all cores automatically. This is thanks to OpenBlas, which is a numerical library that implements and parallelizes linear algebra routines like matrix factorization, matrix inversion, and other operations that bottleneck model fitting. | |||
However, for building datasets, you need to do a little extra work. One common strategy is to break up the data into independent chunks (for example, when building wikia datasets there is one input file for each wiki) and then use <code>mcapply</code> from <code>library(parallel)</code> to build variables from each chunk. Here is an example: | |||
library(parallel) | |||
options(mc.cores=detectCores()) ## tell R to use all the cores | |||
mcaffinity(1:detectCores()) ## required and explained below | |||
library(data.table) ## for rbindlist, which concatenates a list of data.tables into a single data.table | |||
## imagine defining a list of wikis to analyze | |||
## and a function to build variables for each wiki | |||
source("wikilist_and_buildvars") | |||
dataset <- rbindlist(mclapply(wikilist,buildvars)) | |||
mcaffinity(rep(1,detectCores())) ## return processor affinities to the status preferred by OpenBlas | |||
A working example can be found in the [[Message Walls]] git repository. | |||
<code>mcaffinity(1:detectCores())</code> is required for the gentoo R <code>library(parallel)</code> to use multiple cores. The reason is technical and has to do with OpenBlas. Essentially, OpenBlas changes settings that govern how R assigns processes to cores. OpenBlas wants all processes assigned to the same core, so that the other cores do not interfere with it's fancy multicore linear algebra. However, when building datasets, the linear algebra is not typically the bottleneck. The bottleneck is instead operations like sorting and merging that OpenBlas does not parallelize. | |||
The important thing to know is that if you want to use mclapply, you need to do <code>mcaffinity(1:detectCores())</code>. If you want to then fit models you should do <code>mcaffinity(rep(1,detectCores())</code> so that OpenBlas can do its magic. --> | |||
=== 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 <code>tmux</code>. Tmux is very similar (but a little easier to learn) than a program called <code>screen</code>. 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''' | |||
--> | |||
==== Set up a password for Jupyter Notebook on Hyak ==== | |||
=== Working on Hyak from a local emacs client === | |||
<!-- Some of us (like Nate) rely heavily on the Emacs text editor. [http://ess.r-project.org/| 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 | |||
--> | |||
== | == Custom software in Hyak == | ||
=== R packages === | |||
To install a R package that's not available globally, you can check out a build node, and install the package locally. Here's how to do it: | |||
<source lang="bash"> | |||
$ build_machine | |||
$ R | |||
</source> | |||
This will start R, where you can install a package in the usual way. The build node has access to the Internet, so it will be able to download the required source packages, etc. | |||
<source lang="r"> | <source lang="r"> | ||
> install.packages('lme4') | |||
</source> | |||
=== Python Packages === | |||
The recommended python to use on hyak is the intel-python. This is a customized anaconda distribution with a magical optimization of python that really increases the performance of numpy. | |||
Using an anaconda python distribution has important implications for how you install packages. While in normal python, you would install python packages using `pip`, when you use an anaconda distribution you should use `conda` to install packages. Conda also has some fancy features like virtual environments for using different versions of python or different versions of packages in different projects. The problem with using conda is that it does not include all the packages you might want to use. If you want to install a python package that is missing from conda, you can use pip. | |||
Importantly, when using intel-python, you should prefer to install software using conda over pip. | |||
The first time you use intel-python you need to create a custom environment for installing software: | |||
conda create -n my_root | |||
Then add the following to your .bashrc to use this environment. | |||
if [ -z $(conda info --env | grep my_root | grep \*) ]; then | |||
source activate my_root | |||
fi | |||
Conda doesn't like it when you try to activate an environment that is already active. T | |||
Conda modifies your prompt in a possibly annoying way. To disable this behavior run the command: | |||
$ conda config --set changeps1 False | |||
<!-- If you need python libraries that are not installed in the shared environment: | |||
$ pip3 install --user YOURLIBHERE | |||
...replacing YOURLIBHERE with the name of the library you need, e.g. 'pandas'. The --user option will install it for just you. | |||
If you have a lot of dependencies for a specific project, consider using [[#Python Virtual Environments |Python Virtual Environments]] --> | |||
=== Custom modules === | |||
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 [http://modules.sourceforge.net/ 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 not be necessary on a day-to-day basis. | |||
== | ==== Installing and making available a custom module ==== | ||
{{note}} If you are using <code>screen</code> to run and manage your builds, keep in mind that <code>screen</code> [https://superuser.com/a/235773 drops a few environment variables] such as <code>LD_LIBRARY_PATH</code>, which may mess up your build process. You should check that all the relevant environment variables are set before starting your build. | |||
The | 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. | ||
<source lang='bash'> | |||
$ 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 | |||
</source> | |||
<code> | The <code>--prefix</code> option to <code>./configure</code> tells the build scripts that R is going to be installed in <code>/gscratch/mako/modules/sw/R/3.5.0</code>. This follows a convention that we picked—software in modules should go into <code>/gscratch/mako/modules/sw/{SOFTWARE_NAME}/{SOFTWARE_VERSION}</code>. The <code>--prefix</code> option is the most important flag for <code>./configure</code>—any other flag or option will be specific to the software being installed. | ||
The second step is to write a <code>modulefile</code>. This contains the metadata about our module. Edit the file <code>/gscratch/mako/modules/modulefiles/R/3.5.0</code> to contain the following | |||
<source lang='tcl'> | |||
#%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 | |||
</source> | |||
Note that the filename follows a similar convention as <code>--prefix</code> earlier (<code>/gscratch/mako/modules/modulefiles/{SOFTWARE_NAME}/{SOFTWARE_VERSION}</code>). This file sets up the <code>PATH</code> and <code>MANPATH</code> 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 <code>modulefile</code>—see <code>man modulefile</code> for details on those directives. | |||
Once this file is written out, the <code>module avail</code> command should list <code>R/3.5.0</code> as an available module. This is because the module system is set up to look inside <code>/gscratch/mako/modules/modulefiles</code> for module files, thanks to the <code>MODULEPATH</code> variable that is set through <code>.bashrc</code>. The command <code>module load R/3.5.0</code> should make R available and ready for use. To avoid running <code>module load R/3.5.0</code> whenever you log in, you can add the command at the end of your <code>.bashrc</code> file (after the section that sets <code>MODULEPATH</code>). | |||
== Spack == | |||
To use spack to manage software on hyak, add the following to your .bashrc. | |||
<source> | |||
## we need to load these modules to use proprietary hyak compilers to get faster code. | |||
module load icc_18-impi_2018 | |||
module load icc_18 | |||
/gscratch/mako/spack/share/spack/setup-env.sh | |||
export PATH=/gscratch/mako/spack/bin:$PATH | |||
</source> | |||
For directions on working with spack, see the [https://spack.readthedocs.io/en/latest/tutorial_basics.html spack documentation]. |