Beginner’s Guide to working with the VSC

The Vlaams Supercomputer Center (VSC) is a powerful, shared cluster for research.
Before you can run jobs or create a project directory, you need to understand:

How to access the cluster
How file storage and quotas work
How credits and accounting function
The basics of navigating with the Linux terminal
How to check and manage software modules
Why jobs must be submitted (not run directly)
Where to find help and documentation

1. Getting Access

Before you can use the VSC (Vlaams Supercomputer Center), you must have an account.
This section explains who can get access, what you need, and what happens after you apply.

Who can use the VSC?

Students and researchers at universities or research institutes in Flanders, such as: KU Leuven (@kuleuven.be), UHasselt (@uhasselt.be), UGent (@ugent.be), VUB (@vub.be) and UAntwerpen (@uantwerpen.be)
You must use your institutional email address (for example, john.doe@kuleuven.be).
Personal emails like @gmail.com or @hotmail.com are not accepted.
You must apply through your university, supervisor, or research group.
Private individuals cannot apply directly.

Why apply through your institution?

The VSC is a shared resource for academic research.
When you apply through your institution: - Your eligibility is checked. - Your use of the cluster is tracked under your research project or group. - You can access shared credits and storage with your team.

How do you apply for a VSC account?

Ask your supervisor or your university’s IT support for the correct application procedure.
Complete the online application form (usually provided by your institution).
- Fill in your institutional email, name, and department.
- Include your research group or project name. (Your supervisor may need to approve your application.)
Wait for your confirmation email.
- This email will include your VSC user ID and instructions for logging in.
```
Example confirmation email:
"Welcome to the VSC! Your user ID is vsc12345. 
You can log in using this username and your institutional password."
```
What do you get after your account is approved?

A VSC user ID (e.g., vsc12345). This is your username for logging in.
A default shell (usually Bash, which is the command-line environment).
The login address of your VSC cluster, for example:
```
ssh vsc12345@login.hpc.kuleuven.be
```
- This command connects you to the VSC.
- If you see a prompt like vsc12345@login.hpc:~$, you are successfully logged in and ready to start.
What does this mean?
You are now connected to the VSC login node, where you can set up your environment and submit jobs.

Important points to remember

Never share your password or user ID with anyone.
Your access is always linked to a research project or group. This is how resources like credits and storage are managed.
If you need help or have problems with your account, contact your local IT support or the VSC Helpdesk.

2. Connecting and Navigating

Once you have your account, you can connect to the VSC using SSH.

How to connect

Open a terminal on your computer
Connect using this command:
```
ssh <vsc_user>@login.hpc.kuleuven.be
```
- Replace <vsc_user> with your own user ID (e.g., vsc12345).
- After entering your password, you’ll see the command prompt, e.g. vsc12345@login.hpc:~$
What does this mean?
You are now on the login node. Use this for setup and managing jobs, not for running programs directly.

Basic navigation commands

Here are some basic Linux commands you’ll use often:

pwd          # Show your current directory
ls           # List files in your current directory
cd <dir>     # Change to another directory
mkdir <dir>  # Make a new directory

3. VSC File System & Architecture

The VSC has a specialized file system. Understanding where your files go is essential to avoid errors and lost work.

Where does your data live?

$HOME:
- For your code, scripts, software configs, and small data files.
- This area is backed up and has a storage limit.
- Example path: /user/<vsc_user>
$VSC_DATA:
- For large datasets and important results that need to persist.
- Not backed up by default! Always keep your own backups of essential data.
- Example path: /data/<project>/<vsc_user>
$VSC_SCRATCH:
- For temporary files and fast, intermediate computation results.
- This space is cleaned up regularly, do not store anything important here.
- Example path: /scratch/<vsc_user>
See more at VSC Data Storage

Where does your code live?

Typically, you should store scripts and notebooks in your $HOME or $VSC_DATA/scripts/ directory.

Where does your terminal/session live?

When you connect with SSH you are on the login node.
```
ssh <vsc_user>@login.hpc.kuleuven.be
```
Only use the login node for:
- Setting up code and environment
- File transfers (using scp, rsync)
- Submitting and managing jobs
Never run heavy computation on the login node!
All compute tasks must be submitted as jobs.

4. Credits & Accounting

Before you do anything on the Vlaams Supercomputer Center (VSC), it’s vital to understand how credits work:

The VSC uses a credit-based system for managing who can use its resources. Every computational job you run consumes credits based on:
- The number of CPUs/GPUs you request
- The amount of memory (RAM) you need
- The wall time (maximum job duration) you specify
Why do credits matter?
- Credits ensure fair sharing of limited HPC resources among all users and research groups.
- When your group or project runs out of credits, you will not be able to submit more jobs until more are allocated.
- Be efficient: Always request only the resources and wall time you truly need.
How to check your credit balance:
- In your SSH terminal:
```
$ sam-balance
```
- Or check instructions at VSC Slurm Accounting
How to request more credits:
- Credits are typically requested at the project level by your research supervisor or group lead, not individual level. It can also depend on per case basis.
- To apply for a new project or more credits, follow the Job Credits.

5. SLURM Jobs: How Computing Happens on VSC

All heavy computation on VSC happens through a job scheduling system called SLURM.
You do not run heavy programs directly, instead, you write a script and submit it as a job..
Here’s what you need to know:

Why use SLURM?
- Ensures fair scheduling and distribution of compute resources
- Protects the login node from being overloaded
- Makes jobs reproducible and trackable
The SLURM job workflow:
1. Prepare a SLURM batch script (.sh file) describing the resources you need and the commands to run.
2. Submit the job to the queue with:
```
sbatch my_job.sh
```
3. SLURM waits until resources are available, then runs your job on a compute node.
4. Job output and error logs are stored as specified in your script.
Managing jobs:
- Submit a job:
```
sbatch run_job.sh
```
- Monitor status of your job:
```
squeue -u $USER
```
- Cancel a job:
```
scancel <job_id>
```
- More info: VSC Running Jobs in Slurm

6. Linux Command-Line Essentials

You’ll do almost everything with commands in the terminal. Here are some that are commonly used:

Command	Purpose
`ls`	List files
`cd <dir>`	Change directory
`mkdir <dir>`	Make new directory
`cp`	Copy files
`mv`	Move/rename files
`rm`	Remove (delete) files
`nano`	Simple text editor
`chmod`	Change permissions

Tip: Organize your files into folders for code, data, logs, and results.

7. Software Modules

On the VSC, you load software using a module system. You can do this using the commands below:

module avail           # See available modules
module load Python/3.10.4-GCCcore-11.3.0
module list            # Show loaded modules
module purge           # Unload all modules

For some projects like in our case we can also use Conda or Python virtual environments.