GPU Optimization Education (GOE)
A VS Code extension that shows students where their CUDA code repeats memory work it doesn't need to. It runs the RedSan redundancy sanitizer from AccelProf and maps every flagged instruction back to the line of source that produced it. The method follows the RedSan paper (Zhao et al., SC '25): three rules (dead store, dead load, load after store), each within one thread.
Made by the GPU-Ed-Vis project for teaching. Cluster runs are set up for NCSU CSC's ARC cluster; importing results you made yourself works anywhere.
Install
Search for GPU Optimization Education in VS Code's Extensions view and click Install. The GOE! icon appears in the activity bar.
To install a .vsix file instead: Extensions view → ··· menu → Install from VSIX….
Needs VS Code 1.125 or newer.
Two ways to get results
Run on the cluster (recommended). Right-click a .cu file in the Explorer, or on its editor tab, and pick GOE: Analyze on the cluster. You can also use Manage analyses → Analyze a .cu file on ARC…. GOE compiles and profiles the file on ARC and brings the results back as a report. You're always asked before anything is submitted. This needs the one-time setup below.
Import results you already have. Use Manage analyses → Import existing results… and pick the .cu, its SASS listing (nvdisasm -gi, compiled with -lineinfo) and the RedSan output folder.
One-time ARC setup
ARC is the NCSU CSC research cluster. Its user guide is at https://arcm.csc.ncsu.edu/~mueller/cluster/arc/. GOE uses your own ARC account and your own ssh key. It never asks for or stores a password.
These steps assume you already have an ARC account. If you're using GOE for a class, your instructor arranges it. If you don't have one, see Getting an ARC account below.
1. Have your ssh key ready
Use the key whose public half (the .pub file) you gave ARC for your account; ls ~/.ssh lists your keys. If you don't have one, make one. ARC asks for a 4096-bit RSA key. In a terminal (PowerShell on Windows, Terminal on macOS or Linux):
ssh-keygen -t rsa -b 4096
Accept the default location and set a passphrase. The default is C:\Users\<you>\.ssh\id_rsa on Windows and ~/.ssh/id_rsa on macOS and Linux. Upload the .pub file (id_rsa.pub) with the upload link from your ARC approval email, or ask your instructor. Never share the file without .pub.
2. Tell ssh about ARC
Your ssh config is a plain text file called config, with no extension, in the .ssh folder of your home folder. These commands create it if it's missing and open it:
Paste this at the end of the file, put in your Unity ID, and save:
Host arc
HostName arc.csc.ncsu.edu
User <your Unity ID>
IdentityFile ~/.ssh/id_rsa
AddKeysToAgent yes
The IdentityFile must be the key whose .pub you gave ARC. It's usually id_rsa; ls ~/.ssh lists your keys. If you used a different one, such as id_ed25519, put that name here and in step 3.
arc is the name GOE uses by default (setting goe.cluster.host). If you already have an entry with a different name, either use that name in the setting or add this one.
3. Let ssh log in without asking
GOE runs ssh in the background and can't type a passphrase, so the key has to be loaded in your ssh agent.
Windows. Once, in an administrator PowerShell:
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
Then, once, in a normal PowerShell. Windows remembers the key after this, across restarts:
ssh-add ~/.ssh/id_rsa
macOS. The agent is already running. Do these two things once:
In Terminal, add the key, and type its passphrase when asked. macOS saves the passphrase in your Keychain:
ssh-add --apple-use-keychain ~/.ssh/id_rsa
Open your ssh config with open -e ~/.ssh/config, which opens it in TextEdit. Add the line UseKeychain yes to the Host arc entry from step 2, indented like the other lines. This makes the Mac load the key again after a restart. The entry should end up like this:
Host arc
HostName arc.csc.ncsu.edu
User <your Unity ID>
IdentityFile ~/.ssh/id_rsa
AddKeysToAgent yes
UseKeychain yes
If your key has no passphrase, you can skip both.
Linux. Most desktops run an agent for you. Run ssh-add ~/.ssh/id_rsa once per login, or rely on AddKeysToAgent yes (step 2): the first ssh arc you type in a terminal then loads the key. Start VS Code from that same desktop session, so it can see the agent.
4. Check it in a terminal
Be on the NCSU network or the NCSU VPN, then run:
ssh arc echo ok
The first time, ssh asks you to confirm ARC's host key; answer yes. After that it must print ok with no prompt at all. If it still asks for anything, go back to step 3.
5. Turn it on in GOE
- GOE's Settings (the gear icon on any GOE screen) → Cluster → ARC (ssh).
- Manage analyses → Test connection. You should see "Connected to arc" plus whether AccelProf is installed yet.
- Optional, in VS Code's settings under
goe.cluster:
- partition: which GPUs to run on. The default,
rtx4060ti16g, is ARC's largest GPU pool. Others are listed in the ARC guide under "Hardware".
- timeLimit: how long one run may take. The default is 5 minutes; a student program usually takes seconds.
- accelProfHome: only set this if you already have an AccelProf build on ARC.
6. Your first run
Right-click a .cu file → GOE: Analyze on the cluster → confirm. On a new account, GOE first submits a job that builds AccelProf in ~/goe/accelprof. That takes about 15 minutes, but happens only once, and your run starts automatically when it finishes. Runs then usually take a few minutes, plus however long the queue is. You can close VS Code meanwhile: GOE picks the run up again next time.
What GOE does on ARC
- All real work runs in Slurm batch jobs on compute nodes. ARC's rule is "do not execute any other commands on the login node". So on the login node GOE only unpacks a few small files, submits the job, reads the status files, and deletes a finished run's folder, each as a single ssh command.
- Status checks are spaced out: after about 1, 3 and 8 minutes, then every 10 minutes, and only while VS Code has focus. Check now on a run checks immediately.
- Limits: one run waiting per analysis, and two in total. The two are counted on ARC too, so runs started from another computer count.
- Time: each run has 5 minutes (
goe.cluster.timeLimit), and a step still running a minute before that is stopped, so a stuck program gives the GPU back early. The one-time AccelProf build job is stopped after 45 minutes.
- Nothing is left behind: a cancel that can't reach ARC is retried, a submit whose reply is lost is checked by job name, deleting an analysis cancels its run first, and a run waiting on a failed AccelProf build is dropped by Slurm itself.
- Disk:
- Runs are staged in
~/goe/runs/<run-id>/, and successful runs are removed after their results come back. Only your three newest failed runs are kept, for inspection.
- Your ARC home has a 40 GB quota, so check it with
quota -vs if a run fails strangely.
Getting an ARC account
If you're using GOE for a class, you should already have one. Otherwise, follow "Account Access" in the ARC guide. In short:
- Make your ssh key first (step 1), so it's ready to upload.
- Email your instructor asking for ARC access, and include your Unity ID. They forward the request.
- If it's approved, the approval email has a link for uploading your public key. Upload the
.pub file, then carry on from step 2.
If something goes wrong
| GOE says |
What to do |
| "Could not start ssh…" |
Install an OpenSSH client: on Windows, Settings → Optional features → OpenSSH Client; on Linux, the openssh-client package. macOS has it built in. |
| "Can't reach the cluster…" |
You're off the NCSU network: connect the VPN. Also check HostName arc.csc.ncsu.edu in your ssh config. |
| "ARC refused the login key…" |
The key isn't loaded in your agent (step 3), or isn't the one you registered with ARC. ssh arc echo ok must work with no prompt. |
| "The cluster's host key is not known or has changed" |
Run ssh arc once in a terminal and answer yes. If it warns that the key changed, ask before accepting. |
| "…an older build made for one CPU type…" |
Your AccelProf build only works on some ARC nodes. See Rebuilding AccelProf below. |
| A run fails with "illegal instruction" |
Same cause: rebuild AccelProf. |
| "compile error" on a run |
That's nvcc's own output for your code: open build.log from the run. |
| "ran out of time" |
A step was still running near the 5-minute limit. Check the program doesn't loop forever; if it really needs longer, raise goe.cluster.timeLimit. |
| "stopped by the queue" |
Slurm ended the job (memory, or the time limit). slurm.out from the run says which. |
| "You already have 2 GOE runs on the cluster" |
Counted on ARC, including runs from other computers. Wait for one to finish, or cancel one (squeue -u $USER lists them). |
| The AccelProf build stops with "No usable Python…" |
AccelProf needs Python 3.8+ with headers. ARC has them (python3.8–python3.11); if none qualify, export GOE_PYTHON=/path/to/python3 in ~/.bashrc. |
Rebuilding AccelProf
Builds made by GOE 0.2.0 or later run on every ARC node. An older build, made by an earlier GOE or by hand with -march=native, only works on nodes with the same CPU generation as the node it was built on. ARC mixes CPU generations even within one partition. GOE warns you about such a build when you test the connection or start a run.
To rebuild, run the following on a compute node, never the login node:
ssh arc
salloc -p rtx4060ti16g -t 00:10:00
rm -rf ~/goe/accelprof
exit
exit
Your next run rebuilds AccelProf automatically, which takes about 15 minutes, once.
If you set goe.cluster.accelProfHome to your own build, instead re-run GOE's 00_build_accelprof.sh from this version against it. The script ships in the extension's media/cluster folder. It recompiles only the CPU parts.
Don't use VS Code's Remote-SSH to work on the ARC login node. The ARC guide asks people not to, and GOE doesn't need it: your code stays on your computer.
Good to know
- GOE keeps its data in a
.goe/ folder inside your project. Add .goe/ to your .gitignore unless you mean to share it.
- "No redundancy detected" means none was found, not that none exists. RedSan tracks memory in 4-byte chunks.
- A finding is a candidate to look at, not necessarily a bug to fix.