Quickstart: MATLAB & AFNI Interactive GUI Session

This guide walks you through connecting to the MIND cluster (mind.cs.cmu.edu) from Windows or macOS, reserving resources on a CPU compute node via Slurm, and launching MATLAB with full X11 graphics and AFNI integration enabled.

Note: Do not run heavy processing scripts or graphical GUIs directly on the SSH login node. Always request an interactive compute node using srun first.

Step 1: Set Up Your Local X11 Client

Graphical applications like MATLAB and AFNI require an X11 display server running on your local machine to display GUI windows forwarded from the cluster.

Option A: Windows Users (MobaXterm)

1. Download the Home Edition (Portable) from the official MobaXterm Download Page.

2. Extract the downloaded .zip file into a directory on your computer (e.g., Desktop or Documents).

3. Double-click MobaXterm_Personal_X.X.exe to launch the application. (No administrator rights required. X11 forwarding is enabled automatically).

Option B: macOS Users (XQuartz)

1. Download and install XQuartz from xquartz.org.

2. Log out of your Mac and log back in (or restart your Mac). This is a required one-time setup step so macOS registers XQuartz as your default X11 display server.

3. Open your Mac’s native Terminal app (press Cmd + Space, type Terminal, and press Enter).

Step 2: SSH into mind.cs.cmu.edu

Windows (via MobaXterm)

1. Click the Session button in the top-left corner $\rightarrow$ select SSH.

2. Configure parameters:

   • Remote host: mind.cs.cmu.edu

   • Specify username: Check the box and enter your cluster username.

   • Port: 22

3. Click OK, then enter your password and complete 2FA when prompted.

macOS (via Native Terminal)

In your Mac Terminal window, run the following command (note the -Y flag, which enables trusted X11 graphics forwarding):

ssh -Y username@mind.cs.cmu.edu

(Replace username with your cluster ID, then enter your password and complete 2FA).

Step 3: Request a CPU Compute Node with Slurm

Once connected to the login node, request an interactive compute node session on the cpu partition with X11 graphics enabled:

srun --pty --x11 -p cpu --cpus-per-task=4 --mem=16G --time=02:00:00 bash

Tip: You can adjust --cpus-per-task=4, --mem=16G, or --time=02:00:00 depending on the resource requirements of your specific workload.

Wait until your terminal prompt updates to show a compute node hostname (e.g., username@mind-0-15).

Step 4: Configure Linux Path and Start MATLAB

1. Export the AFNI binary path into your Linux environment:

   export PATH=/lab_data/hawk/afni-25-0-09:$PATH
   

2. Confirm Linux can locate the AFNI binaries:

   which 3dinfo
   

   Expected output: /lab_data/hawk/afni-25-0-09/3dinfo

3. Load the MATLAB module (if required) and launch the MATLAB GUI in the background:

   module load matlab
   matlab &
   

Step 5: Configure AFNI inside MATLAB & Verify Setup

In the MATLAB command prompt (>>), add the AFNI MATLAB helper folder and run the quick diagnostic script below to verify environment compatibility:

% 1. Add AFNI MATLAB helper functions (Note the /matlab subfolder)
addpath('/lab_data/hawk/afni_matlab/matlab');

% 2. Verify MATLAB sees functions and system tools
which BrikInfo
which BrikLoad
system('which 3dinfo')

% 3. Run Self-Test Verification
system('echo "1 1 1 1" | 3dUndump -dimen 10 10 10 -prefix /tmp/test_afni -overwrite -');
[err, Info] = BrikInfo('/tmp/test_afni+orig.HEAD');

if err == 0 && isfield(Info, 'IJK_TO_DICOM_REAL')
    disp('----------------------------------------------------')
    disp('SUCCESS: AFNI MATLAB setup is working correctly!')
    disp('Loaded IJK_TO_DICOM_REAL matrix:')
    disp(Info.IJK_TO_DICOM_REAL)
    disp('----------------------------------------------------')
else
    disp('ERROR: AFNI MATLAB setup failed. Please contact support.')
end

Troubleshooting & Common Issues

Warning:

• Mac Users — GUI window doesn’t open / “Display error”: Ensure you restarted your Mac after installing XQuartz, and make sure you included the -Y flag in your SSH command (ssh -Y ...).

• Unrecognized function ‘BrikInfo’: Ensure you added /lab_data/hawk/afni_matlab/matlab to addpath(). Missing the /matlab subfolder will prevent MATLAB from indexing the .m files.

• Windows — X11 Display Errors: If the MATLAB GUI fails to open on Windows, verify that MobaXterm’s X server icon (in the system tray) is active and that you included the --x11 flag in your srun command.