---
tags: User
---

<a href="https://hackmd.io/@teoroo-cluster" alt="Teoroo Cluster">
<img src="https://img.shields.io/badge/Teoroo--CMC-All%20Public%20Notes-black?style=flat-square" /></a>

# Teoroo cluster: user guide

Welcome to the Teoroo group. Here you can find information about
the Teoroo cluster. This particular note contains information
for you to get started and access the machines and software.

More information and recommendations can be found in the [resources and guides section below](#Resources-and-guides). You are also more than welcome to [contribute](#Contributing) to the notes.

## Accessing the cluster

### Get an account

First of all, ask the admin to create an account for you.

### Accessing through SSH

All compute nodes in the Teoroo cluster is behind the firewall and have to be accessed through `brosnan`. `brosnan` also serves as a compute node (with 6 GPU accelerators). Assuming you have `ssh` installed on your computer:

ssh [e-mail] # this brings you to brosnan

:::info
If you have an account on the old teoroo cluster, your old home folder is now under `/home/{username}_old` (you need to type the directory by hand the first time you access it on a node).
:::

> see also: [more ssh advices](https://hackmd.io/SvTVam5bTvuz-20AdxJoZQ#ssh-agent).

#### Example `$HOME/.ssh/config` for Linux/Mac/WSL users
::: spoiler **Click to expand**

# SSH config template, by Yunqi Shao @ STIBS of TEOROO on 23.Oct.5th

# TD;DR: The file `$HOME/.ssh/config` controls you ssh connection, and it can
# make your life working with HPC clusters much easier.

# This file contains some common setups useful when working with the teoroo2
# clusters and other HPCs. You can use the file by copying the content of this
# file to you `.ssh/config` and read the comments below to find out what it
# does.

# PS: If you use other software than the Unix openssh, such as PuTTY, similar
# setup might be possible, but you'll need to find the correct options, e.g.:
# https://the.earth.li/~sgtatham/putty/0.79/htmldoc/Chapter3.html#using-port-forwarding
# https://docs.rc.fas.harvard.edu/kb/using-ssh-controlmaster-for-single-sign-on/#WindowsPuTTY

# 1. You can give names to know ssh hosts so that you can do `ssh BROSNAN`,
#    `rsync BROSNAN:xxx yyy`, `scp BROSAN:xxx yyy` instead of typing the full
#    hostname.

# 2. You can use a ssh-agent to serve you ssh key for authentication, you can
#    also forward the agent to ssh servers so that you can use the same ssh key
#    on the server. This way you can use the same public key when jumping across
#    servers. You can read more about ssh keys here:
#    https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Public_Key_Authentication#Key-based_Authentication_Using_an_Agent


Host BROSNAN
  HostName teoroo2.kemi.uu.se
  ForwardAgent yes

# 3. Your local username is used by default, you can specify the username for
#    the server as well.

Host TETRALITH
  HostName tetralith1.nsc.liu.se
  ForwardAgent yes
  User x_yunsh


# 4. If you alway need to jump across ssh servers, you can automate this with
#    the `ProxyCommand` or `ProxyJump` option. This way, you can directly land
#    in Jackie with `ssh JACKIE`.

# 5. You can also automatically forward the ports, for instance if you run a
#    Jupyter notebook server, you can make sure that the port is always
#    forwarded when you connect (instead of using the `ssh -L` syntax).

Host JACKIE
  HostName 10.1.10.4
  ProxyCommand ssh BROSNAN nc %h %p
  ForwardAgent yes
  LocalForward 19999 localhost:19999
  LocalForward 10003 localhost:10003
  LocalForward 10005 localhost:10005


# 6. If you need a specific authentication method for a server, you can set it
#    in the file as well, this might be useful if the server lags during login
#    when it tries several authentication methods.

Host ALVIS
  HostName alvis1.c3se.chalmers.se
  PreferredAuthentications publickey,password
  ForwardAgent yes

# 7. You can use wildcards to apply rules to multiple servers, the rules are
     applied in the order they appear in this file.

# 8. The control master keeps a ssh connection alive and reuse the same
#    connection when you run `ssh`, `rsync`, `scp`, etc. This is usually more
#    efficient if you need to go through 2-factor authentications, or if you
#    copy files often. See more details here:
#    https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing

Host *
  ControlMaster auto
  ControlPath ~/.ssh/sockets/%r@%h-%p
  ControlPersist 10m
  ServerAliveInterval 10
  ServerAliveCountMax 2

:::

### Accessing through VNC
Sometimes you need to use some software on the cluster with GUI, one way of doing this is to use the VNC server.

1. First you need to get a working VNC client first (recommanding [tigerVNC](https://tigervnc.org/)). We already setup tigerVNC on brosnan. The only necessary step is copying the xstartup file to your .vnc folder. To do that, run the following command:

   (on the cluster)$ cp /sw/vnc/xstartup ~/.vnc/xstartup

3. Then, start a VNC server for yourself:

   (on the cluster)$ vncserver
   # You'll see something like
   # New 'brosnan:1 (yunqi)' desktop is brosnan:1

3. The VNC server will be running on a port `590+N`, in this case 5901, to access it, you have to forward the port through ssh:

   (on your machine)$ ssh -L 5901:localhost:5901 teoroo2.kemi.uu.se
   # -L XXXX:hostname:YYYY forwards the YYYY port on the machine "host" on 
   # the cluster to the XXXX port on your local machine, 
   # e.g. 8888:jackie:5903 forwards the 5903 port on jackie

After that, you can reach the VNC with the address `localhost:5901` on your local machine's VNC client (i.e: tigerVNC). The VNC server will be running in the background on the remote host: you need to run `vncserver -kill :<number>` to kill the VNC server, if you want to stop it. <number> can be found inside your .vnc folder.

### Keeping terminal sessions alive through tmux
You might want to keep your terminal session in the remote server (such as on the cluster) active after closing it on your local machine.
One way to work around this uses the `tmux` command.
This creates its own session within the remote server that runs independently of your `ssh` session.
In other words, if you lose your `ssh` connection for whatever reason, the `tmux` session would *still* be running.
You just need to connect/disconnect your `ssh` and `tmux` sessions.
In `tmux` terminology, connecting to an existing session is known as *attaching* to that session.
Likewise, disconnecting from an existing session is known as *detaching* from it.

To use tmux, you first have to ssh into the desired server before running it:

$ ssh [e-mail]
$ tmux

This activates a `tmux` session and attaches to it automatically.
A `tmux` session functions like a regular Linux terminal, so you can run any calculation or process you'd like in it as usual.
To use specific `tmux` commands you must first precede them with the `Ctrl+b` key combination, which is also known as the tmux *prefix*.
For example, to **d**etach from the current `tmux` session you must press the `Ctrl+b` keys, followed by the `d` key on your keyboard.
After detaching from the current `tmux` session, you can reattach to it from your ssh session with:

$ tmux attach

You can create multiple `tmux` sessions by running `tmux` alone without any other flags; it appends a new session to the list of current ones.
To get a list of active sessions, run:

$ tmux list-sessions

And to attach to a particular **t**arget session in a given list of sessions, you run:

$ tmux attach-session -t session-name

For more commands and info on `tmux`, feel free to read the manual:

$ man tmux

or check this online [cheatsheet](https://gist.github.com/MohamedAlaa/2961058).

### Compute nodes

You can run some light computations or GPU jobs on `Brosnan`,
but you are recommended to run heavy calculations on the
GPU node `jackie`, or the CPU nodes from the old cluster

ssh jackie # this brings you to the GPU node
ssh w1 # this brings you to the CPU nodes (w1-w7)

In Teoroo we do not have a scheduling system on the local cluster.
Please check that you're not interfering with others (e.g. check `htop`
before running something intensive), and communicate
with the group members if there's a problem.
More information about the machines can be found [here](/1jvgV8w6R2OMgWgexorVGw).

### Transfering files

You can use `scp` or `rsync` to transfer files from/to supercompters or your own
computers. Usually, you can directly do the transfer on `Brosnan`, but if you
need to tranfer a large amount of files, you are recommended to do the transfer
on the file server `Clooney`, and preferably limit the speed of your transfer.
If you use rsync, you can use the `--bwlimit` option. There is also a way to
limit the speed of any process using [pipe
viewer](http://www.ivarch.com/programs/pv.shtml), an example of usage is given
[here](https://borgbackup.readthedocs.io/en/stable/faq.html#is-there-a-way-to-limit-bandwidth-with-borg).

## Software

Below you can find instructions for the software and development tools
available.

### Quantum Chemistry Software
- [Gaussian](/SvTVam5bTvuz-20AdxJoZQ#Gaussian)
- [ORCA](/SvTVam5bTvuz-20AdxJoZQ#ORCA)
- [VASP](/SvTVam5bTvuz-20AdxJoZQ#VASP)

### Visualization
- [Blender](/SvTVam5bTvuz-20AdxJoZQ#Blender)
- [VESTA](/SvTVam5bTvuz-20AdxJoZQ#VESTA)
- [GaussView](/SvTVam5bTvuz-20AdxJoZQ#GaussView)
- [VMD](/SvTVam5bTvuz-20AdxJoZQ#VMD)

### Development environments
- [Python](/SvTVam5bTvuz-20AdxJoZQ#Python) (image with Jupyter, ASE, etc.)

### Compilers and libraries
- [Nvidia Tookit](/SvTVam5bTvuz-20AdxJoZQ#Nvidia-toolkit)

## Resources and guides
The following are a list of other notes that can be useful for Teoroo members.

- **[Software](/SvTVam5bTvuz-20AdxJoZQ)**: information about the software.
- **[Hardware](/1jvgV8w6R2OMgWgexorVGw)**: information about the machines.
- **[Inventory](/xF7Rvb_sRsKSD02lRycoBQ)**: need a spare hard disk or screen?
- **[Data management](/_ifXJepyTZ6GmitGug3Jxw)**: how do I backup my data?
- **[Colours in python](https://github.com/viktorsvahn/python_colour_guide/blob/main/colour_schemes.ipynb)**: How to change the colour palette in python.

## Contributing

The notes are written in the MarkDown format. If you are new to MarkDown,
please checkout [this guide](https://www.markdownguide.org/basic-syntax). A more detailed reference about the
syntax on HackMD can be found [here](https://hackmd.io/c/codimd-documentation/%2F%40codimd%2Fmarkdown-syntax).

All notes here are editable for logged in users of HackMD.

- If you find a typo, just go ahead and fix it.
- Minor addition can proceed without notice, but consider mentioning it on our meetings.
- If you'd like to do some substantial change or add more pages, please contact the admin.