Tmux guide

jobs/submitting-jobs.md

@@ -176,6 +176,14 @@ Once submitted, you'll be placed in an interactive shell on the allocated node w
 
 To submit an array job, you use the `--array` as a part of your `sbatch`. This option specifies a range of indices that Slurm uses to create multiple tasks from a single job submission. Each task in the array is assigned a unique SLURM_ARRAY_TASK_ID that can be used within your scripts to differentiate between them.
 
+### Multiple terminals in an interactive sessions
+
+It is very common to need more than one terminal for many applications (e.g. running the job in one terminal and monitoring it in another).
+
+A common solution is to use a terminal multiplexer, such as Tmux or GNU Screen.
+Our suggestion is Tmux and have provided a guide to getting started with it [on the Tmux page]({{site.baseurl}}{% link software/tmux.md %}
+
+
 ### Array job example
 
 Suppose you have a dataset split into multiple files and you want to process each file independently. Instead of submitting a separate job for each file, you can submit a single array job where each task processes a different file.

software/tmux.md

+---
+sort: 5
+---
+
+# Tmux
+
+## Introduction
+
+Tmux (Terminal Multiplexer) is a powerful tool that allows you to create multiple terminal sessions within a single window.
+This is particularly useful when working on HPC clusters through interactive sessions on a compute node.
+
+It is very common to need multiple terminal windows, e.g. you have your task running in one terminal, and monitor its activity from another.
+
+### Keywords to know
+
+Before diving in, let's understand some essential Tmux terminology:
+
+- **Session**: A group of windows that can be attached (viewed) or detached (running in background)
+- **Window**: Like tabs in your browser, each containing one or more panes
+- **Pane**: Split sections within a window
+- **Prefix**: The key combination that tells Tmux you're about to enter a command (default: `Ctrl+b`)
+
+## Getting Started
+
+To create a new Tmux session:
+```bash
+tmux new -s my_session
+```
+
+When you create a new session, you'll automatically be attached to it. You'll notice a green status bar appear at the bottom of your terminal. The bottom-left corner shows your session name (in this case, "my_session"), which helps you keep track of where you are.
+
+To list existing sessions:
+```bash
+tmux ls
+```
+
+To attach to an existing session:
+```bash
+tmux attach -t my_session
+```
+
+## Understanding the Interface
+
+![tmux]({{ site.baseurl }}/images/tmux-images/1.png "tmux1")
+
+Looking at the image above, we can see how Tmux organizes your workspace. The window is divided into multiple panes (numbered 0, 1, and 2), and each pane operates as an independent terminal. The green dividing lines help you visually distinguish between panes, while the status bar at the bottom provides important session information.
+
+### Basic Navigation and Control
+
+The prefix key (`Ctrl+b`) is your gateway to controlling Tmux. Here's how to use it:
+1. Press `Ctrl+b`
+2. Release both keys
+3. Press your desired command key
+
+For example, to detach from your current session:
+1. Press `Ctrl+b`
+2. Release both keys
+3. Press `d`
+
+This detaches you from the session while leaving everything running in the background. Once detached, if you want to completely remove a session, you can use:
+
+```bash
+tmux kill-session -t my_session
+```
+
+## Working with Panes
+
+![tmux]({{ site.baseurl }}/images/tmux-images/2.png "tmux2")
+
+As shown in the image, each pane can run its own commands independently. This is incredibly useful when you need to monitor multiple processes or work with different directories simultaneously.
+
+### Creating and Managing Panes
+
+To split your window:
+- Press `Ctrl+b`, release, then press `"` for a horizontal split
+- Press `Ctrl+b`, release, then press `%` for a vertical split
+
+### Navigating Between Panes
+
+Moving between panes is straightforward:
+1. Press `Ctrl+b`, release
+2. Use arrow keys to move in that direction
+
+To quickly identify panes:
+1. Press `Ctrl+b`, release
+2. Press `q`
+This will briefly display large numbers in the middle of each pane, as shown in [Reference to image showing pane numbers].
+
+### Resizing Panes
+
+Resizing panes is done using a continuous key combination:
+1. Press `Ctrl+b`, release
+2. Hold down Ctrl
+3. While holding Ctrl, press arrow keys to resize the current pane:
+   - Up arrow: Expand upward
+   - Down arrow: Expand downward
+   - Left arrow: Expand to the left
+   - Right arrow: Expand to the right
+4. Release Ctrl when done
+
+![tmux]({{ site.baseurl }}/images/tmux-images/3.png "tmux3")
+
+### Command Mode and Advanced Operations
+
+Tmux provides a command mode for more complex operations. To enter it:
+1. Press `Ctrl+b`, release
+2. Press `:`
+
+You'll see a yellow command bar appear at the bottom of your screen, as shown in the image above.
+
+![tmux]({{ site.baseurl }}/images/tmux-images/4.png "tmux4")
+
+The image demonstrates entering a command to swap two panes. This is just one example of what you can do in command mode - from renaming windows to adjusting layouts. The yellow command bar is where you'll type these commands after pressing `Ctrl+b` followed by `:`.
+
+### Scrolling Through Pane History
+
+To view previous output in a pane:
+1. Press `Ctrl+b`, release
+2. Press `[` to enter scroll mode
+3. Use arrow keys or PgUp/PgDn to navigate
+4. Press `q` to exit scroll mode and return to normal operation
+
+## Working with Windows
+
+Windows in Tmux work similar to browser tabs. Here's how to manage them:
+
+- New window: Press `Ctrl+b`, release, then press `c`
+- Switch windows:
+  - Next window: `Ctrl+b`, release, then `n`
+  - Previous window: `Ctrl+b`, release, then `p`
+  - Specific window: `Ctrl+b`, release, then type the window number
+- Rename current window: `Ctrl+b`, release, then press `,`
+
+## Important Notes
+
+1. Commands that start with `:` must be entered in command mode (Prefix then `:`, look for yellow bar)
+2. All Tmux commands start with the prefix (`Ctrl+b`) unless you're in command mode
+3. If you get disconnected, your Tmux session continues running! Just reconnect to your HPC node and reattach to your session
+
+To cleanly exit Tmux, you can either:
+- Exit all shells in all panes
+- Enter command mode and type:
+
+```
+kill-session
+```