Editing CommunityData:Hyak Ikt (Deprecreated)

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]].

== 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 [https://sig.washington.edu/itsigs/Logging_In#SSH_Config_File in the Hyak documentation].

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 hyak.washington.edu
    User makohill
    HostName login3.hyak.washington.edu
    ControlPath ~/.ssh/master-%r@%h:%p
    ControlMaster auto
    ControlPersist yes
    ForwardX11 yes
    ForwardX11Trusted 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 <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

It will prompt you for your UWNetID's password and your PRN which is the little number that comes from your token.

== Setting Up Hyak ==

When setting up Hyak, you must first add this to your BASHRC file.  Generally, you can simply edit the following file on Hyak: <code>~/.bashrc</code>

 ##  hyak specific options
 alias rgrep='grep -r'
 alias big_machine='qsub -W group_list=hyak-mako -l walltime=500:00:00,mem=200gb -I'
 alias any_machine='qsub -W group_list=hyak-mako -l walltime=500:00:00,mem=100gb -I'
 PYTHON_PATH="/com/local/lib/python3.5:$PYTHON_PATH"
 LD_LIBRARY_PATH="/com/local/lib:/com/local/lib64/R/lib:${LD_LIBRARY_PATH}"
 PKG_CONFIG_PATH=/com/local/lib/pkgconfig:/usr/share/pkgconfig
 MC_CORES=16
 PATH="/com/local/bin:$PATH"
 module load parallel_sql
 module load contrib/gcc_5.1.0-openmpi_1.10.1
 umask 007

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>.

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.

== 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. Start jupyter:

 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'''.

tmux lets you switch between windows (listed in the green bar at the bottom) here are commands:

* Starts a new tmux: '''tmux''' (at the command line)
* Connect to an existing tmux: '''tmux attach''' (at the command line)
* Create a new window: '''Ctrl-b c''' (from ''within'' tmux)
* Switch to window ''N'': '''Ctrl-b N''' (from ''within'' tmux)
* Disconnect from tmux: '''Ctrl-b d''' (from ''within'' tmux)


Connect to a hyak login node. To keep your jupyter notebook running after you disconnect run screen (or tmux).

We are going to forward the connection from the compute node to the login node to your local machine. 

run jupyter on the compute node. </b>



<b>Now forward the jupyter server to the login node. Open a new screen. </b>


<b>And run this ssh command.</b>

nabcd is the name of the compute node. Replace abcd with the node number.

<code>ssh -N -f -L localhost:$PORT:localhost:$PORT nabcd</code>

<b>Now on you local machine (your laptop), forward the port from hyak to localhost.</b>


<b>open localhost:PORT in your browser</b>

It should work!

== Set up a password for Jupyter Notebook on Hyak ==

Once you have IPython/Jupyter up and running on Hyak and have set up all the port forwarding stuff described above, you might consider adding a password to secure your Jupyter session. Why bother? Anyone with access to Hyak can see that you're forwarding ''something'' via the login node. While unlikely, they may do something to interrupt or otherwise mess with your session. With a password, you can make this much less likely.

Instructions for setting up a password on your Jupyter sessions are available on the [https://sig.washington.edu/itsigs/Hyak_IPython#Set_a_password_on_your_notebook Hyak wiki (UW login required)]. 

Note that you can/should skip the first command that loads the canopy module.

== 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 [https://sig.washington.edu/itsigs/Hyak_Job_Scheduler in the itSigs documentation]. Following are basic instructions for the two most common use cases.

=== Interactive nodes ===

For simple tasks, e.g. running R on a dataset, testing that code is working, etc. it is easiest to run it in an interactive node. This is a compute node that you interact with through the terminal. All of your disk storage is accessible just as though you were on the login node.

=== Parallel SQL ===

For big jobs you will want to use multiple nodes. Hyak has a very cool tool that makes this very easy, called Parallel SQL. Detailed instructions are in [https://sig.washington.edu/itsigs/Hyak_parallel-sql the itsigs parallel-sql documentation]. There is also a full walkthrough example with instructions in the <code>wikiresearch/hyak_example</code> directory.

The basic workflow is:

1. Prepare the code, and test it with a single file (either on your computer, or on an interactive node).
2. Write a job_script file. This tells the node what job to run. There is an example on the Parallel SQL wiki page (linked above), and an example in the wikiresearch/hyak_example directory.
3. Create a task_list file. This is a list of commands that should be run, with one line per file that the command should operate on. An example file might look something like:

 python analysis_script.py -i ./input/wiki_1.tsv -o ./output/wiki_1_analysis.tsv
 python analysis_script.py -i ./input/wiki_2.tsv -o ./output/wiki_2_analysis.tsv
 ...

The README in the hyak_example directory has some example bash commands that you might use to generate this file.

4. Load the task_list into Parallel SQL.

 $ module load parallel_sql
 $ cat task_list | psu --load

5. Run the job_script on as many nodes as you need. When each task is finished, the node will get the next task from Parallel SQL.

 $ for job in $(seq 1 N); do qsub job_script; done 
 # N is the number of nodes

=== Killing jobs on compute nodes ===

Torque documentation suggests that you should do this with <tt>qdel</tt>. That might work, but apparently our system runs moab on top of torque and the recommended (by Hyak admins) way to kill a job is to use the <tt>mjobctl</tt> command.

For example, you might run <tt>nodestate</tt> from a login node to figure out the ID number for your job (let's say it's 12345), then run <tt>mjobctl -c 12345</tt> to send a SIGTERM signal or <tt>mjobctl -F 12345</tt> to send a SIGKILL signal that will bring job 12345 to an end.

Note that only four user accounts at a time can have the bits necessary to kill other people's jobs, so while you can do this on your own jobs, you'll need to bother the IRC channel to find help cancelling other's jobs (we think that Jeremy, Nate, Aaron, and Mako currently have the bits). Also, check out the [http://docs.adaptivecomputing.com/maui/commands/mjobctl.php documentation for mjobctl] for more info.