{"id":743,"date":"2026-07-29T15:20:01","date_gmt":"2026-07-29T15:20:01","guid":{"rendered":"https:\/\/ni.cmu.edu\/computing\/?post_type=ht_kb&p=743"},"modified":"2026-07-29T15:29:18","modified_gmt":"2026-07-29T15:29:18","slug":"quickstart-matlab-afni-interactive-gui-session","status":"publish","type":"ht_kb","link":"https:\/\/ni.cmu.edu\/computing\/knowledge-base\/quickstart-matlab-afni-interactive-gui-session\/","title":{"rendered":"Quickstart: MATLAB & AFNI Interactive GUI Session"},"content":{"rendered":"

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

\n

Note: <\/b>Do not run heavy processing scripts or graphical GUIs directly on the SSH login node. Always request an interactive compute node using srun<\/code> first.<\/p>\n<\/blockquote>\n

Step 1: Set Up Your Local X11 Client<\/h2>\n

Graphical applications like MATLAB and AFNI require an X11 display server<\/b> running on your local machine to display GUI windows forwarded from the cluster.<\/p>\n

Option A: Windows Users (MobaXterm)<\/h3>\n
    \n
  1. \n

    Download the Home Edition (Portable)<\/b> from the official MobaXterm Download Page<\/a>.<\/p>\n<\/li>\n

  2. \n

    Extract the downloaded .zip<\/code> file into a directory on your computer (e.g., Desktop or Documents).<\/p>\n<\/li>\n

  3. \n

    Double-click MobaXterm_Personal_X.X.exe<\/code> to launch the application. (No administrator rights required. X11 forwarding is enabled automatically).<\/i><\/p>\n<\/li>\n<\/ol>\n

    Option B: macOS Users (XQuartz)<\/h3>\n
      \n
    1. \n

      Download and install XQuartz<\/b> from xquartz.org<\/a>.<\/p>\n<\/li>\n

    2. \n

      Log out of your Mac and log back in<\/b> (or restart your Mac). This is a required one-time setup step so macOS registers XQuartz as your default X11 display server.<\/p>\n<\/li>\n

    3. \n

      Open your Mac’s native Terminal<\/b> app (press Cmd + Space<\/code>, type Terminal<\/code>, and press Enter<\/code>).<\/p>\n<\/li>\n<\/ol>\n

      Step 2: SSH into mind.cs.cmu.edu<\/code><\/h2>\n

      Windows (via MobaXterm)<\/h3>\n
        \n
      1. \n

        Click the Session<\/b> button in the top-left corner $\\rightarrow$<\/span> select SSH<\/b>.<\/p>\n<\/li>\n

      2. \n

        Configure parameters:<\/p>\n

          \n
        • \n

          Remote host:<\/b> mind.cs.cmu.edu<\/code><\/p>\n<\/li>\n

        • \n

          Specify username:<\/b> Check the box and enter your cluster username.<\/p>\n<\/li>\n

        • \n

          Port:<\/b> 22<\/code><\/p>\n<\/li>\n<\/ul>\n<\/li>\n

        • \n

          Click OK<\/b>, then enter your password and complete 2FA when prompted.<\/p>\n<\/li>\n<\/ol>\n

          macOS (via Native Terminal)<\/h3>\n

          In your Mac Terminal window, run the following command (note the -Y<\/code> flag, which enables trusted X11 graphics forwarding):<\/p>\n

          \n
          \n
          \n
          \n

          Bash<\/span><\/p>\n

          <\/div>\n<\/div>\n
          ssh -Y username@mind.cs.cmu.edu\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
          (Replace username<\/code> with your cluster ID, then enter your password and complete 2FA).<\/i><\/p>\n
          Step 3: Request a CPU Compute Node with Slurm<\/h2>\n
          Once connected to the login node, request an interactive compute node session on the cpu<\/code> partition with X11 graphics enabled:<\/p>\n
          \n
          \n
          \n
          srun --pty --x11 -p cpu --cpus-per-task=4 --mem=16G --time=02:00:00 bash\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
          \n
          Tip: <\/b>You can adjust --cpus-per-task=4<\/code>, --mem=16G<\/code>, or --time=02:00:00<\/code> depending on the resource requirements of your specific workload.<\/p>\n<\/blockquote>\n
          Wait until your terminal prompt updates to show a compute node hostname (e.g., username@mind-0-15<\/code>).<\/p>\n
          Step 4: Configure Linux Path and Start MATLAB<\/h2>\n
            \n
          1. \n
            Export the AFNI binary path into your Linux environment:<\/p>\n
            \n
            \n
            \n
            export<\/span> PATH=\/lab_data\/hawk\/afni-25-0-09:$PATH<\/span>\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n<\/li>\n
          2. \n
            Confirm Linux can locate the AFNI binaries:<\/p>\n
            \n
            \n
            \n
            which<\/span> 3dinfo\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
            Expected output:<\/i> \/lab_data\/hawk\/afni-25-0-09\/3dinfo<\/code><\/p>\n<\/li>\n
          3. \n
            Load the MATLAB module (if required) and launch the MATLAB GUI in the background:<\/p>\n
            \n
            \n
            \n
            module load matlab\r\nmatlab &\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n<\/li>\n<\/ol>\n
            Step 5: Configure AFNI inside MATLAB & Verify Setup<\/h2>\n
            In the MATLAB command prompt (>><\/code>), add the AFNI MATLAB helper folder and run the quick diagnostic script below to verify environment compatibility:<\/p>\n
            \n
            \n
            \n
            % 1. Add AFNI MATLAB helper functions (Note the \/matlab subfolder)<\/span>\r\naddpath('\/lab_data\/hawk\/afni_matlab\/matlab'<\/span>);\r\n\r\n% 2. Verify MATLAB sees functions and system tools<\/span>\r\nwhich BrikInfo\r\nwhich BrikLoad\r\nsystem('which 3dinfo'<\/span>)\r\n\r\n% 3. Run Self-Test Verification<\/span>\r\nsystem('echo \"1 1 1 1\" | 3dUndump -dimen 10 10 10 -prefix \/tmp\/test_afni -overwrite -'<\/span>);\r\n[err, Info] = BrikInfo('\/tmp\/test_afni+orig.HEAD'<\/span>);\r\n\r\nif<\/span> err == 0<\/span> && isfield(Info, 'IJK_TO_DICOM_REAL'<\/span>)\r\n    disp<\/span>('----------------------------------------------------'<\/span>)\r\n    disp<\/span>('SUCCESS: AFNI MATLAB setup is working correctly!'<\/span>)\r\n    disp<\/span>('Loaded IJK_TO_DICOM_REAL matrix:'<\/span>)\r\n    disp<\/span>(Info.IJK_TO_DICOM_REAL)\r\n    disp<\/span>('----------------------------------------------------'<\/span>)\r\nelse<\/span>\r\n    disp<\/span>('ERROR: AFNI MATLAB setup failed. Please contact support.'<\/span>)\r\nend<\/span>\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
            Troubleshooting & Common Issues<\/h2>\n
            \n
            Warning:<\/b><\/p>\n
              \n
            • \n
              Mac Users \u2014 GUI window doesn’t open \/ “Display error”:<\/b> Ensure you restarted your Mac after installing XQuartz, and make sure you included the -Y<\/code> flag in your SSH command (ssh -Y ...<\/code>).<\/p>\n<\/li>\n
            • \n
              Unrecognized function ‘BrikInfo’:<\/b> Ensure you added \/lab_data\/hawk\/afni_matlab\/matlab<\/code> to addpath()<\/code>. Missing the \/matlab<\/code> subfolder will prevent MATLAB from indexing the .m<\/code> files.<\/p>\n<\/li>\n
            • \n
              Windows \u2014 X11 Display Errors:<\/b> 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<\/code> flag in your srun<\/code> command.<\/p>\n<\/li>\n<\/ul>\n<\/blockquote>\n","protected":false},"excerpt":{"rendered":"
              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…<\/p>\n","protected":false},"author":1,"comment_status":"closed","ping_status":"closed","template":"","format":"standard","meta":{"footnotes":""},"ht-kb-category":[11],"ht-kb-tag":[],"class_list":["post-743","ht_kb","type-ht_kb","status-publish","format-standard","hentry","ht_kb_category-software"],"jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/ht-kb\/743","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/ht-kb"}],"about":[{"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/types\/ht_kb"}],"author":[{"embeddable":true,"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/comments?post=743"}],"version-history":[{"count":8,"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/ht-kb\/743\/revisions"}],"predecessor-version":[{"id":751,"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/ht-kb\/743\/revisions\/751"}],"wp:attachment":[{"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/media?parent=743"}],"wp:term":[{"taxonomy":"ht_kb_category","embeddable":true,"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/ht-kb-category?post=743"},{"taxonomy":"ht_kb_tag","embeddable":true,"href":"https:\/\/ni.cmu.edu\/computing\/wp-json\/wp\/v2\/ht-kb-tag?post=743"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}