Module 00 — Mjolnir Foundations

Each exercise is one of three kinds:

• Read — a page of the Knowledge Base to study, with a question to think about.
• Practise in the simulator — tasks for the practice terminal. They tick themselves off as you do them.
• Explain — a short answer in your own words.

The terminal is on the right on a wide screen, or behind the Simulator button at the bottom of a smaller one. Its prompt looks like Mjolnir's — [sim123@mjolnirgate ~]$ — but the user sim123, the project hb_training and the compute nodes simnode01–simnode04 are all fictional.

An HPC (high-performance computing) cluster is many networked computers sharing storage and a scheduler, pooled so that jobs too large for a laptop — and jobs from many people at once — can run efficiently. Mjolnir is UCPH's cluster for this kind of research. You are never the only person using it, and almost every rule in this module follows from that one fact.

Task: In a few sentences, explain what makes a cluster different from your own laptop, and why sharing it with many researchers changes how you're expected to use it.

Hint

What would happen if every user on a shared machine ran heavy, long-running work wherever and whenever they liked?

Model answer

A cluster gives you far more compute and memory than a laptop, but that capacity is finite and shared. If one person's work takes all the CPU or memory on a shared entry point, everyone else connected at that moment is slowed down — so clusters need etiquette (separate login and compute nodes, a scheduler, resource limits) that a single-user laptop never does.

Knowledge Base: What is Mjolnir? · How Mjolnir works

The Mjolnir Knowledge Base is where current, official information lives: partitions, storage locations, software, troubleshooting and how to get help. Getting into the habit of checking it first will save you — and the support team — a lot of time.

Task: Open the Knowledge Base and find the section you would use for each of these: (a) your job has been pending for a long time, (b) you need software that isn't installed, (c) you aren't sure where your files should go. Note the page titles.

Model answer

(a) Troubleshooting → Why is my job pending? (b) Software → Request software. (c) Storage → Where should my files go?

Knowledge Base: Mjolnir Knowledge Base

On the real cluster you connect over the UCPH VPN with ssh <KU-ID>@mjolnirgate.unicph.domain — First 15 Minutes covers that once your account exists. Whenever you connect, the first habit is to check who and where you are. In this simulation you are already “connected” as sim123.

1. Run whoami to see which user you are.
2. Run hostname to see which machine you're on.

Check yourself: the hostname is mjolnirgate — a login node, not a compute node. Why does that matter for what you do next?

Knowledge Base: VPN and SSH access

The login node mjolnirgate is a shared entry point for everyone connected at that moment, meant for lightweight work: organising files, writing scripts, submitting and checking jobs. Analyses belong on compute nodes, scheduled through Slurm. According to the Knowledge Base, computation isn't allowed on the login node, and repeated misuse can mean losing your access.

1. See what happens when you try real computation on the login node: run module load samtools/1.21, then samtools sort reads.bam.

Then: list three tasks that belong on a login node and three that must go to a compute node.

Hint

The deciding factor isn't “is this a command I type” — it's how much CPU, memory or time it is likely to need.

Model answer

Login node: editing a script, organising folders, checking a small file with head, submitting a job with sbatch. Compute node (through Slurm): aligning reads, an assembly, model training, or any step whose runtime or memory you aren't sure of.

Knowledge Base: Login nodes vs compute nodes

pwd prints where you are, ls lists what's there, and cd moves you somewhere else. Almost everything else you do builds on these three.

1. Move to the project folder /projects/hb_training and list what's inside.
2. Use ls -l (or ls -lh) somewhere to see sizes and permissions.

Check yourself: which folder in the project is for shared datasets, and which is for your own work?

. means “this folder”, .. “the folder above”, and ~ “my home folder”. cd - jumps back to wherever you were before. They appear in many commands, not just cd.

1. Jump straight home with cd ~ (or just cd).
2. Move up one level with cd ...
3. Return to where you were with cd -.

Check yourself: where might . be useful as an argument to a command other than cd — for example as the destination for cp?

An absolute path starts at the root (/) and means the same thing wherever you are. A relative path is read from your current folder — shorter, but it only means what you think if you know where you are. Mixing them up is a common cause of “file not found”, and of scripts that quietly work in the wrong place.

1. Move somewhere using an absolute path (one starting with /).
2. Move into a subfolder using a relative path (no leading /).

Check yourself: if you moved somewhere else first, would ../data still point to the same place? Why does an absolute path not have that problem?

Your home folder, /home/<KU-ID>, is personal but limited to 100 GB, and is for configuration files and small scripts — the Knowledge Base is clear that datasets and job output don't belong there. Research work belongs in the project: /projects/<project>/people/<KU-ID>/ for your own work, data/ for shared datasets, apps/ for shared software, and scratch/ for temporary files (not backed up — keep only what you can recreate). If your people folder is missing on the real cluster, don't create it: ask through Getting help.

1. List your home folder (ls ~) and read welcome.txt.
2. List your own working folder, /projects/hb_training/people/sim123.

Check yourself: which of the two should hold your working files for a project, and why?

Knowledge Base: Where should my files go? · Storage limits and responsibilities

Give each piece of work its own folder inside your people folder, with a name you'll still understand later. mkdir creates a folder; mkdir -p creates any missing parents too.

1. Create a folder called m00-practice inside /projects/hb_training/people/sim123.

Check yourself: try creating a folder in data/. Why does the simulation stop you?

Project storage is shared, finite and paid for, and the Knowledge Base stresses that having no enforced quota doesn't mean you can store without limit. The Knowledge Base recommends du -sh --apparent-size for reporting how much a folder holds, and du -h --apparent-size --max-depth=1 <folder> | sort -h to find which subfolder is biggest. Big scans belong in a job, not on the login node.

1. Measure your people folder: du -sh --apparent-size /projects/hb_training/people/sim123.

Knowledge Base: How much storage am I using? · Storage limits and responsibilities

cp copies, mv moves or renames, and rm deletes — immediately, without asking and without a recycle bin. Check the path before every rm, and read shared datasets from data/ rather than making your own copies.

1. Copy /projects/hb_training/data/README.txt into your m00-practice folder.
2. Rename the copy to notes.txt.
3. Create an empty file with touch m00-practice/delete-me.txt, then remove it with rm.

Check yourself: what does rm -r do, and why is it worth pausing before you press Enter?

Sequencing files are large and often compressed. file tells you what a file is; head and tail show its first or last lines; less pages through it. Check what a file is before you assume its format.

1. Run file on /projects/hb_training/data/sample_R1.fastq.gz.
2. Show the first four lines of /projects/hb_training/data/sample_preview.fastq with head -n 4.

Check yourself: what would cat on a compressed file print, and why is that unhelpful?

Mjolnir provides shared research software through Environment Modules (version 4.5.2 — not Lmod). Instead of everyone installing their own copy of every tool, pre-installed software is loaded into your session or job with one command. Much of it is built from Conda environments under the hood, but module load is the supported way to use it.

Task: Why would a shared cluster prefer this over letting every user install and manage their own software?

Hint

Think about disk space (home is capped at 100 GB), reproducibility, and fifty people each installing a slightly different version of the same tool.

Model answer

Shared, versioned installs save duplicated disk space and effort, and when you report which module and version you used, someone else can reproduce your environment exactly.

Knowledge Base: Find and load software

module avail lists what's installed, module load <name>/<version> loads it (pin the version for repeatable work), module list shows what's loaded, and which confirms a tool is on your PATH. Some commands from other clusters, like module spider, aren't available on Mjolnir. The module names and versions in the simulation are examples — run module avail on Mjolnir for the real list.

1. Search for samtools: module avail samtools.
2. Try module spider samtools and read why it doesn't work here.
3. Load a pinned version: module load samtools/1.21.
4. Check what's loaded with module list.
5. Confirm the tool is available with which samtools.

Check yourself: why might installing your own Conda environment in your home folder be a bad idea on Mjolnir?

Knowledge Base: Find and load software · Request software

Slurm is the scheduler that decides which job runs on which compute node, and when. Every job declares the CPUs, memory and maximum time it needs, the partition (a pool of nodes) and the QoS (a set of limits). On Mjolnir --qos is mandatory: Slurm refuses any job that doesn't name a QoS. cpuqueue is the default partition and normal the everyday QoS. Fairshare matters too: according to the Knowledge Base, your usage is counted by what you request, rather than by what your job actually uses.

Task: Why does a shared cluster need everyone to declare their needs upfront, rather than letting jobs run and seeing what happens?

Hint

What does the scheduler need to know to fit many people's jobs onto a limited number of machines without conflicts?

Model answer

Without declared requests, Slurm couldn't tell which jobs can safely share a node without running out of memory or starving each other of CPU. The requests are also what fairshare charges against, so over-requesting lowers your own future priority — and realistic, short requests are easier for the scheduler to fit into gaps.

Knowledge Base: Partitions, QoS, and fairshare

A batch script is a shell script whose #SBATCH lines tell Slurm what the job needs. The project has a template at data/templates/first-job.sh — but it has a mistake that older scripts often have.

1. Copy the template into your people folder: cp /projects/hb_training/data/templates/first-job.sh /projects/hb_training/people/sim123/.
2. Go there and read it with cat first-job.sh.
3. Submit it with sbatch first-job.sh and read why it's rejected.
4. Fix it: open it with nano first-job.sh, add the line #SBATCH --qos=normal under the partition line, and save.

Check yourself: which line sets where the output goes, and what does %j become?

Knowledge Base: Submitting jobs

When Slurm accepts a job it replies “Submitted batch job <jobid>”. That job ID is how you refer to the job from now on.

1. Submit your corrected first-job.sh and note the job ID.

squeue -u $USER shows your queued and running jobs. The ST column reads PD (pending), R (running) or CG (completing); an empty list means your jobs have finished. Pending is usually normal queuing on a shared cluster. Time runs faster in the simulation.

1. Run squeue -u $USER while your job is pending or running.

Hint

To see why a job is waiting, try squeue -u $USER -o "%.10i %.8T %R".

Knowledge Base: Monitoring jobs · Why is my job pending?

The job writes to the file named by --output (here first-job-<jobid>.out); errors go there too unless you set --error. The hostname in the output should be a compute node — proof the work didn't run on the login node.

1. When the job has finished, read its output file, for example cat first-job-*.out.

Check yourself: which line of the output proves where the job actually ran?

seff <jobid> summarises CPU and memory use as a share of what you requested; sacct -j <jobid> gives more detail. Because fairshare is charged on what you request, right-sizing protects your own priority — and memory you reserve but leave idle stays blocked for everyone else until your job ends.

1. Run seff on your finished job.
2. Run sacct -j <jobid> on the same job.

Check yourself: your job mostly slept. If it had requested 8 CPUs “to be safe”, what would that have cost you, and everyone else?

Knowledge Base: Check job efficiency

If you spot a mistake after submitting, cancel the job with scancel <jobid> rather than letting it use resources for nothing.

1. Submit first-job.sh again, then cancel it with scancel while it's still pending or running.

Knowledge Base: Cancelling jobs

Sometimes you want to type commands yourself on a compute node — to test a step before writing the batch script. An interactive session gives you that, but it holds its resources until you exit, even while idle, so request only what you need and leave when you're done.

1. Start one: srun --partition=cpuqueue --qos=normal --nodes=1 --cpus-per-task=2 --mem-per-cpu=2G --time=01:00:00 --pty bash.
2. Run hostname to confirm you're on a compute node.
3. Release the resources with exit.

Knowledge Base: Interactive jobs

Questions and problems go to the Mjolnir Support Center. A request that includes the job ID, the exact command, the exact error text (copied, not described), the relevant path and what you expected is usually resolved in one exchange. New accounts don't go through the Support Center, and VPN problems go to KU-IT.

Task: Your job failed. Write the support request you would send, using a made-up job ID and error.

Model answer

“Job 4200123 failed after two minutes. I ran sbatch align.sh from /projects/<project>/people/<KU-ID>/run1. The .err file says: samtools: command not found. I expected it to run because I load samtools/1.21 in the script.” — plus the output of sacct -j 4200123 --format=JobID,State,Elapsed,ReqMem,MaxRSS,ExitCode.

Knowledge Base: Getting help · Why did my job fail?

Put it together without step-by-step instructions.

1. Create a folder final in your people folder and work inside it.
2. Write a job script there (use nano) that loads samtools/1.21, prints samtools --version, and requests cpuqueue with --qos=normal. Submit it.
3. Let it finish successfully, then read its output.
4. Check its efficiency with seff.

Hint

Start from first-job.sh: copy it, keep the #SBATCH lines, and replace the commands with module load samtools/1.21 and samtools --version.