Differences

This shows you the differences between two versions of the page.

--- cluster-linux [2024/05/07 11:26] – created gabriele
+++ cluster-linux [2024/05/26 11:17] (current) – gabriele
@@ Line 7: / Line 7: @@
   - Common Commands
   - Text editing in command line
+  - Displaying images in command line
+  - Displaying images from command line (using X11 forwarding)
+  - Displaying NIFTI images in command line
+  - X11 Forwarding
@@ Line 12: / Line 16: @@
 ===== 1. New on Linux systems? =====
-Psychp01
+This page contains some tips on how to get started using the psychp01 cluster if you are not too familiar with Linux/Unix. The information is intended for both users that are new to psychp01 and for users that are new to Linux/UNIX-like operating systems. Please consult the rest of the user guide for information that is not covered in this chapter.
+Please also visit [[https://missing.csail.mit.edu/|this MIT course]] on basics shell commands and command line environment.
+==== SSH ====
+On a terminal, you can use ssh to login to psychp01. Check the [[cluster-access|Access to psychp01 through Command Line]] in this documentation to learn more about ''ssh''.
+==== File Transfer Clients ====
+To transfer any file or data you wish to use to the cluster, you can use file transfer clients, such as ''scp'' or ''sftp''. For more info, see [[cluster-file_transfer|Transferring files to/from psychp01]].
+==== Running jobs on the cluster ====
+You must execute your jobs by submitting them to the batch system using bash files. There is a dedicated [[cluster-batch|section]] on bash files and batch system in our user guide that explains how to use the batch system. The pages explain how to write job scripts, and how to submit, manage, and monitor jobs. It is not allowed to run long or large memory jobs interactively (i.e., directly from the command line).
 ===== 2. Common Commands =====
-Psychp01
+Provide the full path name of the directory you are currently in:
+  pwd
+Change the current working directory:
+  cd
+List the files and directories which are located in the directory you are currently in:
+  ls
+Searches through one or more directory trees of a file system, locates files based on some user-specified criteria and applies a user-specified action on each matched file:
+  find
+Find specific files, you can use the -name and -type arguments:
+  find . -name 'my*' -type f
+The above command searches in the current directory (.) and below it, for files and directories with names starting with my. “-type f” limits the results of the above search to only regular files, therefore excluding directories, special files, pipes, symbolic links, etc. my* is enclosed in single quotes (apostrophes) as otherwise the shell would replace it with the list of files in the current directory starting with “my”.
+Find a certain expression in one or more files:
+  grep
+For example, to find the string apple in the fruitlist.txt text file, type:
+  grep apple fruitlist.txt
+Create new directory:
+  mkdir
+Remove a file. Use with caution:
+  rm
+Remove a directory. Use with caution:
+  rmdir
+Move or rename a file or directory:
+  mv
+Edit text files in command line (for more details, see below Text editing in command line):
+  vi
+or
+  vim
+View (but do not change) the contents of a text file one screen at a time, or, when combined with other commands (see below Text editing in command line) view the result of the command one screen at a time. Useful if a command prints several screens of information on your screen so quickly, that you don’t manage to read the first lines before they are gone.
+  less
+and
+  more
+Use the “pipe” or “vertical bar” to group two or more commands together:
+  |
+For example, list files in the current directory (ls), retain only the lines of ls output containing the string "key" (grep), and view the result in a scrolling page (less), type:
+  ls -l | grep key | less
+A complete listing of the defined variables and their meanings can be obtained by typing:
+  printenv
+You can define (and redefine) your own variables by typing:
+  export VARIABLE=VALUE
+If you know the UNIX-command that you would like to use but not the exact syntax, consult the manual pages on the system to get a brief overview. Use ''man'' + //command// for this. For example, to get the right options to display the contents of a directory, use:
+  man ls
+To choose the desired options for showing the current status of processes, use
+  man ps
 ===== 3. Text editing in command line =====
-Psychp01
+A popular tool for editing files (e.g., your code) on Linux/UNIX-based systems is ''vi''. Unfortunately, the commands within both ''vi'' editor are quite cryptic for beginners. It is probably wise to spend some time understanding the basic editing commands before starting to program the machine.
+For quick help, use:
+  man vi
+or
+  man vim
+Suppose you want to check the progress of your analyses. Suppose that you defined in your [[cluster-batch|bash file]] that SLURM is supposed to output the status of your analyses in a text file (see [[cluster-jobs|here]]) named ''job_out.txt'' stored in your ''analyses'' folder in your home directory ''/home/gbellucci''. To quickly check the status of your analyses, you would first establish an ssh connection with the cluster, then ''cd'' to your analyses folder and type ''vim job_out.txt'', like that:
+  ssh gbellucci@psychp01.rhul.ac.uk
+  gbellucci@psychp01.rhul.ac.uk's password:
+  gbellucci@psychp01:~$ cd /home/gbellucci/analyses
+  gbellucci@psychp01:~$ vim job_out.txt
+This would open the file in your command window. You can scroll and check the status of your analyses. To exit just type:
+  :q
+Every file opened with vim will be in a non-writable state. To write in your opened file, press
+  i
+On the bottom left of your command line, you will see the word ''INSERT'' appear, like that:
+  --INSERT--
+Modify your file as you wish. When done, press ''ESC'' on your keyboard. This will make the word ''INSERT'' disappear. You are again back to a non-writable state. To save and exit, type:
+  :wq
+Where w stands for “write” and q for “quit”. If you change your mind and decide to exit without saving your changes, just type
+  :q!
+This will not write your changes and force an exit (that's why the ''!'') from ''vim''.
+===== 4. Displaying images in command line =====
+The easiest way to display images is to use ''niicat'' (see [[https://github.com/MIC-DKFZ/niicat?tab=readme-ov-file|here]]). For that, you would not need an X11 forwarding connection (see X11 forwarding below), as it prints the image in your terminal using [[https://github.com/saitoha/libsixel|libsixel]]. ''niicat'' can display niftii, png, jpg, or similar images. Importantly, though, to display images with ''niicat'', you need to work on a terminal that supports sixel (see [[https://github.com/saitoha/libsixel#terminal-requirements|here]]).
+For macOS, you could use [[https://iterm2.com/index.html|iTerm2]]. Once installed, open iTerm2 and establish an ssh connection to the remote desktop (see [[cluster-access|Cluster access]]). For example:
+  ssh gbellucci@psychp01.rhul.ac.uk
+Now, suppose that you have a NIFTI image named ''anatomical_brain.nii'' in the folder ''fmri_results'' in your home ''/home/gbellucci''. You can open the image like that:
+  niicat -lb /home/gbellucci/fmri_results/anatomical_brain.nii
+The ''-lb'' option tells ''niicat'' to use libsixel-bin to display the image in your terminal.
+===== 5. Displaying images from command line (using X11 forwarding) =====
+Another option to open an image saved on a remote server is to establish an X11 forwarding connection to the server and use an image viewer. For that, you need to:
+  - Ensure you have X11 installed on your local machine (XQuartz on macOS, typically installed X server on Linux).
+  - Enable X11 forwarding when connecting via SSH.
+For example, first make sure XQuartz is currently running on your machine. Before connecting to the remote server, you can start XQuartz on your local machine by typing the following in a terminal window:
+  open -a XQuartz
+You then would need to establish a X11 forwarding connection like that (see [[cluster-access|Cluster access]] for more information):
+  ssh -X username@remote_server
+For example, suppose your username is ''gbellucci'' and the remote server is ''psychp01.rhul.ac.uk'', you would need to type:
+  ssh -X gbellucci@psychp01.rhul.ac.uk
+You will be prompted to enter a password. Afterwards, suppose that you have a beautiful image named ''my_beautiful_result_image.jpg'' in the folder results in your home ''/home/gbellucci''. You can open your image by using ''fim'' like that:
+  fim /home/gbellucci/results/my_beautiful_result_image.jpg
+You can also open your image by using ''Eye of GNOME'', which tends to display images with higher resolution:
+  eog /home/gbellucci/results/my_beautiful_result_image.jpg
+===== 6. Displaying NIFTI images in command line =====
+To quickly preview neuroimaging images in NIFTI format on the terminal, you can use ''niicat'' (see [[https://github.com/MIC-DKFZ/niicat?tab=readme-ov-file|here]]). For that, you would not need an X11 forwarding connection, as it prints the image in your terminal using [[https://github.com/saitoha/libsixel|libsixel]]. ''niicat'' can display niftii, png, jpg, or similar images. Importantly, though, to display images with ''niicat'', you need to work on a terminal that supports sixel (see [[https://github.com/saitoha/libsixel#terminal-requirements|here]]).
+For macOS, you could use [[https://iterm2.com/index.html|iTerm2]]. Once installed, open iTerm2 and establish an ssh connection to the remote desktop (see [[cluster-access|Cluster access]]). For example:
+  ssh gbellucci@psychp01.rhul.ac.uk
+Now, suppose that you have a NIFTI image named ''anatomical_brain.nii'' in the folder ''fmri_results'' in your home ''/home/gbellucci''. You can open the image like that:
+  niicat -lb /home/gbellucci/fmri_results/anatomical_brain.nii
+The ''-lb'' option tells ''niicat'' to use libsixel-bin to display the image in your terminal.
+===== 7. X11 Forwarding =====
+X11 forwarding is a feature that allows you to run graphical applications installed on a remote server and display them on your local machine as if they were running locally. The “X11” part refers to the X Window System (version 11), which is a protocol and system for managing graphical displays on UNIX and UNIX-like operating systems.
+This is how it works:
+  - //Local X Server//: Your local machine runs an X server. This is a software component responsible for managing the display and input devices (like keyboard and mouse) for graphical applications.
+  - //Remote Application//: The remote machine runs the graphical application. Instead of displaying the graphical output on the remote machine’s screen, it sends this output to your local X server.
+  - //SSH Tunnel//: The graphical output is sent securely over the network using SSH (Secure Shell, see [[cluster-access|Cluster access]]). SSH creates a tunnel between your local machine and the remote server, carrying the X11 protocol data.
+X11 forwarding is primarily designed for UNIX-like operating systems, such as Linux and BSD. However, it can also be used on macOS and Windows with some additional setup.
+==== Setting up X11 Forwarding in macOS/Linux ====
+=== Installation ===
+Linux distributions typically have X11 forwarding support built-in.
+macOS uses XQuartz, an implementation of the X server for macOS. You need to install and run XQuartz to use X11 forwarding. You can easily install XQuartz via the Terminal using [[https://brew.sh/|Homebrew]]. In a Terminal window, just type:
+  brew install --cask xquartz
+=== Setup ===
+The setup of X11 Forwarding is pretty easy in macOS/Linux.
+  - Ensure your local machine has an X server running (like XQuartz on macOS).
+  - Connect to the remote server with the -X or -Y option:
+First make sure an X server is currently running on your machine. For instance, if you are working on macOS and use XQuartz, before connecting to the remote server, you can start XQuartz on your local machine by typing the following in a terminal window:
+  open -a XQuartz
+You then would need to establish a X11 forwarding connection like that (see [[cluster-access|Cluster access]] for more information):
+  ssh -X username@remote_server
+For example, suppose your username is ''gbellucci'' and the remote server is ''psychp01.rhul.ac.uk'', you would need to type:
+  ssh -X gbellucci@psychp01.rhul.ac.uk
+For trusted X11 forwarding, you can use the -Y option like that:
+  ssh -Y gbellucci@psychp01.rhul.ac.uk
+Both -X and -Y options allow you to run graphical applications from a remote server and display them on your local machine, but there are important differences in terms of security and functionality. The -X option or untrusted X11 Forwarding is the more secure option because it restricts the level of access that the remote application has to your local X server. Specifically, it limits the remote application’s ability to interact with other X11 clients and monitor or modify your local desktop environment. Even if more secure, with the -X option you might experience restrictions on some functionalities of the remote graphical applications. You can employ the -X option for general use, especially when you are unsure about the security of the remote applications you are running. It helps to prevent potential security risks from untrusted remote applications.
+On the contrary, the -Y option enables trusted X11 forwarding, allowing the remote application to have full access to your local X server. It can interact with other X11 clients and modify your local desktop environment, just like a local application. This implies that the -Y option will give you full functionality for remote graphical applications, but it also removes the restrictions imposed by the -X option, which means that applications that need more direct access to the X server will work correctly. You can use the -Y option if you need full functionality from the remote graphical applications and you trust the remote server and the applications you are running. Since it allows more access, it should only be used in secure, trusted environments.
+==== Setting up X11 Forwarding in Windows ====
+Windows does not natively support X11 forwarding because it does not use the X Window System. However, you can use third-party software like Xming, VcXsrv, or MobaXterm to run an X server on Windows. Combine these with an SSH client like PuTTY or use the built-in SSH in Windows 10 (using the Windows Subsystem for Linux, WSL). See [[https://kb.iu.edu/d/bdnt|here]] for more information.
+[[{:backward_arrow.png?40|width: 12em}cluster-prerequisites|Getting Started with HPC on psychp01]][[{:forward_arrow.png?40|width: 12em}cluster-access|Cluster access]]\\
+[[{:toc.png?40|width: 12em}cluster-toc|Return to Table of Contents]][[{:main_page.png?40|width: 12em}cluster-guide|Return to main page]]