Beginner’s Guide to amplitUDE

Welcome to amplitUDE! This guide will help you get started with high-performance computing (HPC), even if you’ve never used a supercomputer before.

What is HPC?

Think of a supercomputer like a massive team instead of a single worker:

Your laptop: 1 worker doing tasks one at a time
amplitUDE: Thousands of workers collaborating on huge projects simultaneously

Why use HPC?

Run calculations that would take weeks on a laptop in hours
Process massive datasets (terabytes of data)
Train AI models on powerful GPUs
Simulate complex physical phenomena

Understanding the amplitUDE System

amplitUDE works like a research facility with different areas:

Compute Nodes (The Lab)

What: The powerful machines that do your actual calculations
Two types:
- CPU nodes: General-purpose computing
- GPU nodes: AI/ML, deep learning, graphics-heavy work
Access: Through the job scheduler (Slurm) only

File Systems (Storage Lockers)

HOME: Your permanent locker (0.5 TB) - keep code and important files
SCRATCH: Temporary workspaces (10 TB total) - large datasets, job outputs
- Important: You must create a workspace before using SCRATCH (see Step 2)

The Setup:

┌─────────────────────────────────────────┐
│  YOUR LAPTOP                            │
│  (where you start)                      │
└────────────┬────────────────────────────┘
             │ SSH connection
             ↓
┌─────────────────────────────────────────┐
│  LOGIN NODES                            │
│  login.hpc.uni-due.de        │
│  • Edit files                           │
│  • Submit jobs                          │
│  • Organize data                        │
└────────────┬────────────────────────────┘
             │ Submit job via Slurm
             ↓
┌─────────────────────────────────────────┐
│  COMPUTE NODES                          │
│  • CPU nodes (many cores)               │
│  • GPU nodes (H200, H100)               │
│  • YOUR JOB RUNS HERE                   │
└─────────────────────────────────────────┘

Step 1: Your First Login

Prerequisites

✅ amplitUDE account (if you don’t have one, see Apply for Access)
✅ SSH client installed
- Linux/Mac: Built-in (use Terminal)
- Windows: Use PuTTY or Windows Terminal

Connect to amplitUDE

On Linux/Mac:

ssh username@login.hpc.uni-due.de ssh amplitude

On Windows (PuTTY):

Open PuTTY
Host Name: login.hpc.uni-due.de
Port: 22
Click “Open”

First Time: You’ll see a message about host key fingerprint. Type yes and press Enter.

Enter your password and 2FA (two-factor authentication code) when prompted (characters won’t show while typing - this is normal!)

Success looks like:

[username@login2 ~]$

🎉 You’re in! This is the login node.

Step 2: Understanding File Systems & Creating a Workspace

Check Your Location

# Where am I?
pwd
# Output: /home/username

# What's in this directory?
ls
# Output: (list of files/folders)

# How much storage space do I have?
quota -s

The Two Main Storage Areas

1. HOME Directory ($HOME or ~)

Location: /home/username
Size: 0.5 TB
Purpose: Code, scripts, small files
Permanent: Yes, kept forever
Backed up: Yes
Best for: Python scripts, job scripts, configurations

2. SCRATCH Workspaces (temporary work areas)

Location: Created via ws_allocate command
Size: 10 TB total available
Purpose: Large datasets, job outputs, temporary files
Permanent: No, workspaces expire (default: 100 days, can be extended)
Backed up: No
Best for: Training datasets, simulation outputs, checkpoints

Create Your First Workspace

Before you can use SCRATCH, you need to create a workspace. Think of it as reserving a temporary locker.

# Create a workspace called "my-project" for 30 days
ws_allocate my-project 30

# You'll see output like:
# Info: creating workspace.
# /lustre/scratch/ws/username-my-project
# remaining extensions  : 4
# remaining time in days: 30

What just happened?

Created a temporary directory on SCRATCH
Valid for 30 days (can be extended up to 100 days)
You can extend it 4 more times before it’s permanently deleted

Find Your Workspace Location

# Get the path to your workspace
ws_find my-project

# Output: /lustre/scratch/ws/username-my-project

List All Your Workspaces

# See all your workspaces
ws_list

# Output shows:
# - Workspace name
# - Location
# - Extensions remaining
# - Expiration date

Navigate to Your Workspace

# Save the workspace path for easy access
MY_WORKSPACE=$(ws_find my-project)

# Go to your workspace
cd $MY_WORKSPACE

# Or go directly (replace username and workspace name)
cd /lustre/scratch/ws/username-my-project

# Create a folder for your project
mkdir my-first-project
cd my-first-project

Workspace Tips

💡 Add to your .bashrc for convenience:

# Add this to ~/.bashrc so you can easily access your workspace
echo "export MY_WORKSPACE=\$(ws_find my-project 2>/dev/null)" >> ~/.bashrc
source ~/.bashrc

# Now you can use:
cd $MY_WORKSPACE

💡 Get email reminders:

# Create workspace with email reminder 7 days before expiration
ws_allocate -r 7 -m your.email@uni-due.de my-project 30

💡 Extend workspace lifetime:

# Extend workspace by 30 more days
ws_extend my-project 30

What Happens When Workspace Expires?

Day 100: Workspace expires
Days 101-130: Data kept for 30 days (grace period)
Day 131: Data permanently deleted

⚠️ Important: Copy important results to HOME before expiration!

# Copy results from workspace to HOME before it expires
cp -r $MY_WORKSPACE/important-results ~/my-results

Navigate Around (Updated)

# Go to HOME (for code)
cd ~

# Go to your workspace (for data)
cd $MY_WORKSPACE

# Create a project folder in HOME
mkdir ~/my-first-project
cd ~/my-first-project

For more details about workspaces, see the Workspaces Guide.

Step 3: Create Your First Script

Let’s create a simple Python script that says “Hello from amplitUDE!”

Create the Script

# Make sure you're in a good location
cd ~/my-first-project

# Create a Python script
cat > hello.py << 'EOF'
import platform
import socket

print("=" * 50)
print("Hello from amplitUDE!")
print("=" * 50)
print(f"Hostname: {socket.gethostname()}")
print(f"Python version: {platform.python_version()}")
print(f"System: {platform.system()}")
print("=" * 50)
EOF

# Check it was created
ls -l hello.py

Step 4: Your First Job Submission

Now let’s run this script on a compute node using Slurm (the job scheduler).

Create a Job Script

# Create a Slurm job script
cat > run_hello.sh << 'EOF'
#!/bin/bash
#SBATCH --job-name=my-first-job
#SBATCH --partition=STD-l-12h
#SBATCH --time=00:05:00
#SBATCH --mem=1G
#SBATCH --cpus-per-task=1
#SBATCH --output=hello_%j.out
#SBATCH --error=hello_%j.err

# Print start time
echo "Job started at: $(date)"
echo "Running on node: $(hostname)"
echo ""

# Run the Python script
python3 hello.py

# Print end time
echo ""
echo "Job finished at: $(date)"
EOF

# Make it executable
chmod +x run_hello.sh

# Check it was created
ls -l run_hello.sh

Understanding the Job Script

Let’s break down what each #SBATCH line means:

#SBATCH --job-name=my-first-job     # Name for your job (shows in queue)
#SBATCH --partition=STD-l-12h         # Which nodes to use
#SBATCH --time=00:05:00             # Max runtime (HH:MM:SS) - 5 minutes
#SBATCH --mem=1G                    # Memory needed (1 gigabyte)
#SBATCH --cpus-per-task=1           # Number of CPU cores
#SBATCH --output=hello_%j.out       # Where to save output (%j = job ID)
#SBATCH --error=hello_%j.err        # Where to save errors

Submit Your Job

sbatch run_hello.sh

You’ll see:

Submitted batch job 12345

🎉 Your job is now in the queue! The number (12345) is your job ID.

Step 5: Monitor Your Job

Check Job Status

# See your jobs
squeue -u $USER

While running:

JOBID    PARTITION  NAME          USER      ST  TIME  NODES
12345    STD-l-12h    my-first-job  username  R   0:01  1

Status codes:

R = Running
PD = Pending (waiting for resources)
CG = Completing
Job disappears = Finished!

Watch It In Real-Time

# Update every 2 seconds
watch -n 2 squeue -u $USER

# Press Ctrl+C to stop watching

Step 6: View Your Results

Once the job finishes (usually takes <1 minute for this simple example):

# List output files
ls -l hello_*

# You should see:
# hello_12345.out  (the output)
# hello_12345.err  (any errors - should be empty)

Read the Output

# View the output file (replace 12345 with your actual job ID)
cat hello_12345.out

You should see:

Job started at: Thu May 07 10:30:45 CEST 2026
Running on node: ndstd001

==================================================
Hello from amplitUDE!
==================================================
Hostname: ndstd001
Python version: 3.9.21
System: Linux
==================================================

Job finished at: Thu May 07 10:30:46 CEST 2026

Notice:

The hostname is different (a compute node, not login2!)
Your script ran on a dedicated CPU node
It took about 1 second to run

🎉 Congratulations! You’ve successfully run your first HPC job!

Step 7: Common Commands Cheat Sheet

File Management

# List files
ls                    # List files in current directory
ls -l                 # Detailed list
ls -lh                # Human-readable file sizes

# Navigate
pwd                   # Print current directory
cd folder_name        # Enter a folder
cd ..                 # Go up one level
cd ~                  # Go to home directory
cd $SCRATCH           # Go to scratch

# Create/Delete
mkdir folder_name     # Create directory
rm file_name          # Delete file (careful!)
rm -r folder_name     # Delete directory (very careful!)

# Copy/Move
cp file1 file2        # Copy file
mv file1 file2        # Move/rename file

# View files
cat file.txt          # Print entire file
less file.txt         # View file (press q to quit)
head file.txt         # First 10 lines
tail file.txt         # Last 10 lines

Job Management

# Submit job
sbatch job_script.sh

# Check your jobs
squeue -u $USER

# Cancel a job
scancel JOB_ID

# Job history (completed jobs)
sacct -u $USER

# Detailed job info
scontrol show job JOB_ID

Useful Shortcuts

# Tab completion
cd my[TAB]           # Auto-completes to 'my-first-project'

# Command history
history              # Show recent commands
!123                 # Re-run command #123
!!                   # Re-run last command

# Clear screen
clear                # Or press Ctrl+L

Step 8: Working with Large Data (Using Workspaces)

Now let’s work with larger data that should go in your workspace, not HOME.

Create Data in Your Workspace

# Go to your workspace
cd $MY_WORKSPACE/my-first-project

# Create a larger data file (simulating a dataset)
cat > large_data.txt << 'EOF'
10
20
30
40
50
60
70
80
90
100
EOF

Create Processing Script

cat > process_data.py << 'EOF'
import sys
import os

# Print where we're running from
print(f"Working directory: {os.getcwd()}")

# Read data
with open('large_data.txt', 'r') as f:
    numbers = [int(line.strip()) for line in f]

print(f"Read {len(numbers)} numbers")
print(f"Numbers: {numbers}")
print(f"Sum: {sum(numbers)}")
print(f"Average: {sum(numbers) / len(numbers)}")
print(f"Maximum: {max(numbers)}")
print(f"Minimum: {min(numbers)}")

# Save results
with open('results.txt', 'w') as f:
    f.write(f"Sum: {sum(numbers)}\n")
    f.write(f"Average: {sum(numbers) / len(numbers)}\n")
    f.write(f"Max: {max(numbers)}\n")
    f.write(f"Min: {min(numbers)}\n")

print("Results saved to results.txt")
EOF

Create Job Script (Running from Workspace)

cat > process_job.sh << 'EOF'
#!/bin/bash
#SBATCH --job-name=process-data
#SBATCH --partition=STD-l-12h
#SBATCH --time=00:05:00
#SBATCH --mem=1G
#SBATCH --cpus-per-task=1
#SBATCH --output=process_%j.out

echo "Job started at $(date)"
echo "Running on node: $(hostname)"

# Navigate to workspace
WORKSPACE=$(ws_find my-project)
cd $WORKSPACE/my-first-project

echo "Working directory: $(pwd)"

# Process data
python3 process_data.py

echo "Job finished at $(date)"
EOF

chmod +x process_job.sh

Submit and Check

# Submit from your workspace
sbatch process_job.sh

# Wait a moment, then check output
ls -l process_*.out

# View results (replace XXXXX with your job ID)
cat process_XXXXX.out

# Check the results file
cat results.txt

Best Practice: HOME vs Workspace

# ✅ CORRECT: Code in HOME, data in workspace
~/my-first-project/         # Scripts here (HOME)
  ├── process_data.py
  ├── process_job.sh
  
$MY_WORKSPACE/my-first-project/  # Data here (workspace)
  ├── large_data.txt
  ├── results.txt

# ❌ WRONG: Everything in HOME
~/                          # Don't put big data here!
  ├── scripts/
  ├── huge_dataset.tar.gz   # This fills up your HOME quota!

Step 9: Working with Modules

amplitUDE provides pre-installed software via modules.

See Available Software

# List all available modules
module avail

# Search for specific software
module avail python
module avail anaconda

Load and Use Modules

# Load Anaconda (Python 3.11 + scientific packages)
module load anaconda3/2023

# Check Python version
python3 --version
# Output: Python 3.11.7

# See what's loaded
module list

# Unload a module
module unload anaconda3/2023

Use Modules in Jobs

cat > module_job.sh << 'EOF'
#!/bin/bash
#SBATCH --job-name=module-test
#SBATCH --partition=CPU-big
#SBATCH --time=00:05:00
#SBATCH --output=module_%j.out

# Load module
module load anaconda3/2023

# Now you have access to Python 3.11 and scientific packages
python3 --version
python3 -c "import numpy; print(f'NumPy version: {numpy.__version__}')"
EOF

sbatch module_job.sh

Step 10: Managing Your Workspace

As you work on amplitUDE, you’ll need to manage your workspace lifecycle.

Check Workspace Status

# List all workspaces with details
ws_list

# Output shows:
# id: my-project
# workspace directory: /lustre/scratch/ws/username-my-project
# remaining extensions: 4
# creation time: Wed May 07 10:00:00 2026
# expiration date: Sat Jun 06 10:00:00 2026
# remaining time: 29 days 23 hours

Extend Workspace Before It Expires

# Extend by another 30 days (from today)
ws_extend my-project 30

# Verify extension
ws_list

Remember: You can extend up to 4 times, max 100 days total.

Set Up Email Reminders

# Add to ~/.ws_user.conf for automatic reminders
cat >> ~/.ws_user.conf << 'EOF'
mail: your.email@uni-due.de
reminder: 7
EOF

# Now all future workspaces will email you 7 days before expiration

Save Important Results Before Expiration

# Copy results from workspace to HOME
cp -r $MY_WORKSPACE/important-results ~/results-backup/

# Verify copy
ls -lh ~/results-backup/

Clean Up Old Workspaces

# Delete workspace when done
ws_release my-project

# Data is kept for 30 days in case you need to restore

Restore Accidentally Deleted Workspace

# List deleted workspaces (still in grace period)
ws_restore --list

# Restore workspace
ws_restore my-project my-project-restored

Step 11: Next Steps

Ready for More?

Now that you’ve mastered the basics, explore:

Python Environments
- Create custom Python environments
- Install packages with conda/pip
- Set up for AI/ML work
AI/ML on amplitUDE
- Use GPUs for deep learning
- Train neural networks
- Run PyTorch/TensorFlow
Slurm Job Scheduler
- Advanced job options
- Array jobs (run many similar jobs)
- Job dependencies
Data Storage
- Understand quotas
- Best practices for large files
- Data transfer
Software Modules
- Find pre-installed software
- Load multiple modules
- Create your own modules

Common Beginner Mistakes (and How to Avoid Them)

❌ Forgetting to Request Enough Time

Wrong:

#SBATCH --time=00:05:00  # Job needs 10 minutes, only requested 5

Right:

#SBATCH --time=00:15:00  # Request a bit more than needed

What happens: Job gets killed when time runs out!

❌ Using HOME for Large Files

Wrong:

# Saving 50 GB dataset to HOME (only 0.5 TB quota!)
cp huge_dataset.tar.gz ~/

Right:

# Create workspace and use it for large files
ws_allocate my-data 30
WORKSPACE=$(ws_find my-data)
cp huge_dataset.tar.gz $WORKSPACE/

Why: HOME is for code and small files. Use workspaces for big data.

❌ Forgetting to Extend Workspace

Wrong:

# Create 30-day workspace, forget about it
ws_allocate my-project 30
# ... 35 days later: all data is gone!

Right:

# Create workspace with email reminder
ws_allocate -r 7 -m your.email@uni-due.de my-project 30

# Extend before it expires
ws_extend my-project 30

# Copy important results to HOME
cp -r $MY_WORKSPACE/results ~/backup/

Why: Workspaces expire! Set reminders and back up important data.

❌ Not Checking Job Output

Wrong:

sbatch job.sh
# Walk away, never check if it worked

Right:

sbatch job.sh
# Check status
squeue -u $USER
# Later, check output
cat output_12345.out

Quick Reference Card

Print this section or bookmark it!

Essential Commands

What	Command	Example
Submit job	`sbatch script.sh`	`sbatch my_job.sh`
Check jobs	`squeue -u $USER`	See your running jobs
Cancel job	`scancel JOB_ID`	`scancel 12345`
Check quota	`quota -s`	See storage usage
Create workspace	`ws_allocate <name> <days>`	`ws_allocate my-project 30`
Find workspace	`ws_find <name>`	`ws_find my-project`
List workspaces	`ws_list`	See all workspaces
Extend workspace	`ws_extend <name> <days>`	`ws_extend my-project 30`
Go to HOME	`cd ~`	Go to home directory
Go to workspace	`cd $(ws_find <name>)`	`cd $(ws_find my-project)`
Load module	`module load name`	`module load anaconda3/2023`
List files	`ls -lh`	Human-readable file list

File Locations

Directory	Path	Size	Use For	Expiration
HOME	`/home/username` or `~`	0.5 TB	Code, scripts, configs	Never
Workspace	`$(ws_find <name>)`	Up to 10 TB	Large data, outputs	30-100 days

Job Script Template

#!/bin/bash
#SBATCH --job-name=my-job
#SBATCH --partition=STD-l-12h          # or GPU-H200 for GPU
#SBATCH --time=01:00:00              # HH:MM:SS
#SBATCH --mem=16G                    # Memory needed
#SBATCH --cpus-per-task=4            # Number of cores
#SBATCH --output=job_%j.out
#SBATCH --error=job_%j.err

# For GPU jobs, add:
# #SBATCH --gres=gpu:1

# Your commands here
echo "Starting at $(date)"
python3 my_script.py
echo "Finished at $(date)"

Congratulations! 🎉

You now know how to:

✅ Log in to amplitUDE
✅ Navigate the file system
✅ Create and manage workspaces on SCRATCH
✅ Create and edit files
✅ Submit jobs to the scheduler
✅ Monitor and check your results
✅ Use modules for software
✅ Manage workspace lifecycle (create, extend, share)
✅ Avoid common mistakes

You’re ready to start real research computing on amplitUDE!

What’s Next?

Choose your path based on your research needs:

For AI/ML Researchers: → Start with AI/ML on amplitUDE

For Python Users: → Set up Python Environments

For Domain Scientists: → Check Available Software for your field

For Advanced Users: → Dive into Software Development

Getting Help

Office Hours

When: Wednesdays, 11:00 AM (even weeks only)
Where: Zoom - https://uni-due.zoom.us/j/62455456799?pwd=bkNUbU4rSm1PVVBLVFl2Zzl0SXNtZz09
What: Drop in with questions, get live help

Email Support

Email: hpc-support@uni-due.de
Response time: Usually within 1 business day

Community

Ask colleagues in your research group
Share tips with other amplitUDE users
Attend training workshops (subscribe for announcements https://www.uni-due.de/zim/forschung/hpc_schulungen.php)

Feedback

Found this guide helpful? Have suggestions for improvement?
Email us at hpc-support@uni-due.de

We’re always improving our documentation based on user feedback!

Last updated: May 2026

Beginner’s Guide to amplitUDE

What is HPC?

Understanding the amplitUDE System

Login Nodes (The Reception Desk)

Compute Nodes (The Lab)

File Systems (Storage Lockers)

Step 1: Your First Login

Prerequisites

Connect to amplitUDE

Step 2: Understanding File Systems & Creating a Workspace

Check Your Location

The Two Main Storage Areas

Create Your First Workspace

Find Your Workspace Location

List All Your Workspaces

Navigate to Your Workspace

Workspace Tips

What Happens When Workspace Expires?

Navigate Around (Updated)

Step 3: Create Your First Script

Create the Script

Test It (on login node)

Step 4: Your First Job Submission

Create a Job Script

Understanding the Job Script

Submit Your Job

Step 5: Monitor Your Job

Check Job Status

Watch It In Real-Time

Step 6: View Your Results

Read the Output

Step 7: Common Commands Cheat Sheet

File Management

Job Management

Useful Shortcuts

Step 8: Working with Large Data (Using Workspaces)

Create Data in Your Workspace

Create Processing Script

Create Job Script (Running from Workspace)

Submit and Check

Best Practice: HOME vs Workspace

Step 9: Working with Modules

See Available Software

Load and Use Modules

Use Modules in Jobs

Step 10: Managing Your Workspace

Check Workspace Status

Extend Workspace Before It Expires

Set Up Email Reminders

Save Important Results Before Expiration

Share Workspace with Collaborators

Clean Up Old Workspaces

Restore Accidentally Deleted Workspace

Step 11: Next Steps

Ready for More?

Common Beginner Mistakes (and How to Avoid Them)

❌ Running Heavy Jobs on Login Nodes

❌ Forgetting to Request Enough Time

❌ Using HOME for Large Files

❌ Forgetting to Extend Workspace

❌ Not Checking Job Output

Quick Reference Card

Essential Commands

File Locations

Job Script Template

Congratulations! 🎉

What’s Next?

Getting Help

Office Hours

Email Support

Community

Feedback