Your first job on Aqua.
One step at a time.

What you will do.

Send a tiny calculation to an Aqua compute node, check that it worked, and copy the result back. No GPU, dataset, Python environment or AI tool is needed.

HPC (high-performance computing) is a shared group of powerful computers, and Aqua is QUT’s. You don’t run an experiment straight after logging in. You submit a job—a script plus a resource request—and the scheduler starts it when resources are free.

Every command box is labelled YOUR COMPUTER or ON AQUA (after you connect with SSH). Copy the command, not the example output. This page never connects or submits anything itself.

Start at step 1 →

About 15–30 minutes once you have access. Already running jobs? Jump to the RPID update. Want an agent to run this for you? See the agent skills guide.

Get access and open a terminal.

1. Check your account can use Aqua

   You need a QUT account authorised for HPC and access to the research project you will charge jobs to. If you are new, ask your supervisor or QUT eResearch, and start with QUT’s Aqua guidance. Follow QUT’s current VPN and login instructions for your location.

2. Open a terminal

   • Windows: Windows Terminal or PowerShell.
   • macOS: Terminal.
   • Linux: your usual terminal.

3. Have these ready

   • Your QUT username and login method.
   • Your project’s RPID (next step).

   This tutorial asks for one CPU, 1 GB of memory and two minutes.

Next: find your project RPID →

Find your project’s RPID.

An RPID (research project ID) tells QUT which project a job belongs to. Every submission needs one from 2 November 2026.

1. Look it up

   Sign in to the QUT Data Management Plan system and open your research project. An RPID is six uppercase letters followed by four digits.

2. Can’t find it? Ask

   Your project lead or eResearch can confirm the right ID and your access. Never borrow another project’s ID or use an example ID.

You will type it in at step 4.

Next: connect to Aqua →

Connect, then check where you are.

SSH opens a terminal on Aqua. Once connected, commands act on Aqua’s files, not your computer’s.

1. Connect from your own terminal

   Replace YOUR_QUT_USERNAME with your username. If QUT gave you a different host or SSH alias, use that.

   Your computer · Windows, macOS or Linux Copy

   ssh YOUR_QUT_USERNAME@aqua.qut.edu.au

   Password entry may show no characters; that is normal. On a first connection, check the host-key fingerprint against QUT’s guidance before accepting it.

2. Confirm you are on Aqua

   On Aqua · read-only checks Copy

   hostname
   whoami
   pwd
   command -v qsub

   Expected: an Aqua login-node name, your username, a remote directory, and a path to qsub such as /opt/pbs/bin/qsub. These commands change nothing.

Next: submit your first job →

Create a tiny job and submit it.

The job adds the numbers 1 to 100,000 and checks the answer, using only tools already in the shell.

1. Make a fresh working folder

   On Aqua · create a fresh tutorial folder Copy

   run_dir=$(mktemp -d "$HOME/aqua-first-job.XXXXXX") &&
     cd "$run_dir" && pwd

   Expected: a path ending in aqua-first-job. plus a random suffix. Note it down; you need it in step 5.

2. Write the job file

   Paste the whole block, including the final PBS line. It writes hello.pbs but doesn’t run anything yet.

   On Aqua · write hello.pbs Copy

   cat > hello.pbs <<'PBS'
   #!/bin/bash
   #PBS -N aqua_hello
   #PBS -q cpu_batch
   #PBS -l select=1:ncpus=1:mem=1gb
   #PBS -l walltime=00:02:00
   #PBS -j oe
   # Project accounting will be supplied with qsub -P.
   set -euo pipefail
   cd "${PBS_O_WORKDIR:?}"
   awk 'BEGIN {for(i=1;i<=100000;i++) s+=i; if(s!=5000050000) exit 1; print "CPU arithmetic PASS: 5000050000"}' > result.txt
   printf 'Job: %s\nHost: %s\n' "${PBS_JOBID:?}" "$(hostname)" >> result.txt
   cat result.txt
   PBS

   What each line means

   Line in the script	Meaning
   #PBS -N aqua_hello	A short name that helps you identify this job.
   #PBS -q cpu_batch	Send this CPU-only workload through the CPU batch route.
   select=1:ncpus=1:mem=1gb	Request one resource chunk with one CPU and 1 GB of host memory.
   walltime=00:02:00	Allow up to two minutes after the job starts. Queue waiting is separate.
   #PBS -j oe	Combine normal output and errors into one scheduler log.
   PBS_O_WORKDIR	A variable PBS provides: the directory you submitted from.

3. Enter your RPID and submit once

   This asks for your RPID, checks its format, then submits the job.

   On Aqua · this submits one real job Copy

   read -r -p "Your authorised project RPID: " AQUA_RPID
   if [[ "$AQUA_RPID" =~ ^[A-Z]{6}[0-9]{4}$ && "$AQUA_RPID" != ABCDEF1234 ]]; then
     qsub -P "$AQUA_RPID" -o "$PWD/job.log" hello.pbs
   else
     echo "Enter your real RPID: six uppercase letters followed by four digits."
   fi

   Expected: a job ID such as 12345678.aqua. Save the one you get. If the connection drops, check the queue before resubmitting—the first attempt may have been accepted.

Next: check the result →

Check status, read the result, bring it back.

1. Find your job

   On Aqua · replace JOB_ID with your saved ID Copy

   qstat -u "$USER"
   qstat -f 'JOB_ID'

   Check job_state, comment and that the recorded project is yours. Tiny jobs often finish before you see them running.

   What the job states mean

   State	Meaning	Next step
   Q	Queued: waiting for resources.	Wait and check occasionally. Do not submit a duplicate.
   R	Running on a compute node.	Let it finish; the tutorial calculation should be brief.
   H	Held: prevented from running.	Read the comment/hold type; some holds need an operator.
   E	Exiting: still finalising.	Wait for terminal state and output delivery.
   F	Finished, visible in history if retained.	Check exit status and output; “finished” does not mean “passed.”

2. Read the output

   From the step 4 folder, with your real job ID:

   On Aqua · inspect the completed job Copy

   qstat -xf 'JOB_ID'
   cat job.log
   cat result.txt

   It worked if both hold: PBS reports Exit_status = 0, and result.txt contains CPU arithmetic PASS: 5000050000 with the job ID and compute hostname. No such file or directory usually means the job hasn’t finished or you are in the wrong folder.

3. Copy the results to your computer

   In a second terminal on your computer, replace the username and the path with the folder you noted in step 4.

   Your computer · replace username and remote directory Copy

   scp -r YOUR_QUT_USERNAME@aqua.qut.edu.au:/path/to/aqua-first-job.SUFFIX ./aqua-first-job-results

   Expected: a local aqua-first-job-results folder with hello.pbs, job.log and result.txt. For regular use, mount Aqua and open files directly.

4. Log out

   On Aqua · return this terminal to your computer Copy

   exit

   Logging out doesn’t cancel batch jobs. To cancel one on purpose, use qdel 'JOB_ID' with its exact ID.

Next: run your real experiment →

Swap in your own program.

Don’t start with every model, sensor or dataset. Get one representative case working on a compute node first—a smoke test—then scale up.

1. Start from a command that already works

   Note the program, its input data and the output you expect. Use only flags your program supports; check --help.

2. Put code and inputs on Aqua

   Copy a fixed version of your code into a new run folder; files on your laptop aren’t visible to Aqua. Ask QUT about project storage, scratch space and quotas before moving a large dataset.

3. Prepare the software environment

   Use your project’s Pixi, module or container setup. Build it once (heavy builds don’t belong on the login node), then activate the same environment inside the job script.

   Adapt to your project · example flags Copy

   pixi --version
   pixi install --locked
   pixi run --locked experiment --sensor camera --model baseline --seed 0

   The experiment task and its flags are examples; use your project’s own. --locked keeps the environment matching the committed lockfile.

4. Run one case as a job

   Adapt hello.pbs to activate the environment and run your command, keeping the RPID and a fresh output folder. Request a GPU only if the program needs one. Check the output itself, not just the exit code.

5. Scale up with a manifest

   A manifest lists every case, such as each dataset/model/seed combination. A job array runs one job per row. Start with a low limit on how many run at once, and save every job ID.

export AQUA_RPID=YOUR_REAL_RPID
python3 scripts/submit_demo.py --run-dir "$HOME/aqua-demo-preview"

# Explicit submission. Use a different, new run directory.
python3 scripts/submit_demo.py --run-dir "$HOME/aqua-demo-run1" --submit

# Run after completion to validate all eight cells.
python3 "$HOME/aqua-demo-run1/check_results.py" \
  --manifest "$HOME/aqua-demo-run1/matrix.json" \
  --output "$HOME/aqua-demo-run1/results"

QCR or general? Check eligibility first.

A lab allocation is not automatically faster. Choose from the hardware, access, limits and placement your job can actually use.

qstat -Qf qcr-users cpu_batch gpu_batch helps inspect current definitions. Placement can require qlist=qcr-users inside a select chunk. Removing that constraint does not necessarily exclude QCR resources. Queue selection details.

Choosing a GPU model

Aqua’s GPU nodes have different models. The gpu_id resource lets you choose one, or leave it out to accept any. On 28 September 2026 most GPU nodes were A100 or H100; a few had other models.

# Any GPU model: widest choice of nodes
#PBS -l select=1:ncpus=8:mem=32gb:ngpus=1

# Only A100 nodes
#PBS -l select=1:ncpus=8:mem=32gb:ngpus=1:gpu_id=A100

# Only H100 nodes
#PBS -l select=1:ncpus=8:mem=32gb:ngpus=1:gpu_id=H100

Pin a model only when you need to: for example, your code or its compiled libraries only work on one architecture, or you are comparing timings. Pinning narrows the nodes your job can use. See which models exist today with pbsnodes -av | grep gpu_id | sort | uniq -c.

How much walltime should I ask for?

Walltime is the longest your job may run once it starts, not how long it waits in the queue. The walltime calculator turns a quick measurement into a request with headroom.

Where the rules actually live.

QUT’s guidance takes precedence over this community walkthrough. Check it for accounts, access, storage, queues and current requirements:

• About Aqua
• Submitting jobs on Aqua
• About RDSS and RDSS FAQs
• QUT Data Management Plan system (RPIDs)

Dates, observations and verification limits for this page are recorded in the agent guide’s sources section.