Warning

This is as a Lab Notebook which describes how to solve a specific problem at a specific time. Please keep this in mind as you read and use the content. Please pay close attention to the date, version information and other details.

Lab Notebook --- MATLAB offload from localPC to HPCC (2023-07-18)

Cluster Configuration

MATLAB allows its users to run MATLAB on their local machine, such as laptop computer and offload the heavy computation to HPCC cluster, and retrieve the results back from the HPCC cluster to local machine. In this document, we

provide the instructions for setting up the cluster profile for use in the MATLAB parallel computing toolbox running on a local computer.

Following instructions is made from modifying the sample setup from Configure Using the Generic Scheduler Interface - MATLAB & Simulink specifically for SLURM on HPCC. The diagram illustrating the cluster for the sample system in that document is very similar to our HPCC cluster.

Requirements

The setup must meet the following conditions:

The client node and cluster login node must support ssh and sftp.
The cluster login node must be able to call the sbatch command to submit a job to an SLURM scheduler. You can find more about this in the README file in the nonshared subfolder within the installation folder.

Note: HPCC cluster satisfies the requirements.

Configure a Cluster Profile

Follow these steps to configure the cluster profile. You can modify any of these options depending on your setup.

Down load provided plug-in script from GitHub repository at (https://github.com/mathworks/matlab-parallel-slurm-plugin.git) and store it to a location that MATLAB clients (MATLAB on your local machine) can access. This location will be used in the cluster profile setting in step 6(10).

Ex. I saved it on my Mac at the directory: /Users/wangxg/matlab-parallel-slurm-plugin.
1
NOTE: the name of the directory will be used in setting up the profile later in step 6( 10 ).

Start a MATLAB session on the client host.

Ex. I use MATLAB/ R2022b on my Mac.

NOTE: the version of matlab used by client and cluster should be the match.

NOTE: step 3 to 7 are for creating a cluster profile for matlab clients to offload jobs to HPCC. A sample profile is created for users as a reference. Users can import this sample profile ( The name of the sample profile file is “Remote-HPCC-R2022b.mlsettings”) and follow the instructions to create one and/or to customize the sample profile for their own use.

Start the Cluster Profile Manager from the MATLAB desktop. On the Home tab, in the Environment section, select Parallel > Create and Manage Clusters.
Create a new profile in the Cluster Profile Manager by selecting Add Cluster Profile > Generic.
With the new profile selected in the list, in the Manage Profile section, select Rename and change the profile name to InstallTest. Press Enter. (Note, you can name it anything you like)
In the Properties tab, select Edit and provide settings for the following fields:
1. Set the Description field to For testing installation.
2. Set the JobStorageLocation to the location where you want job and task data to be stored on the client machine (not the cluster location), for example, C:\Temp\joblocation. \ You must not share JobStorageLocation among parallel computing products running different versions. Each version on your cluster must have its own JobStorageLocation.
3. Set NumWorkers to the number of workers for which you want to test your installation.
4. Set NumThreads to the number of threads to use on each worker (By default, MATLAB worker runs sequentially, that is using 1 thread).
5. Set ClusterMatlabRoot to the installation location of MATLAB to run on the worker machines, which is the MATLAB PATH on the cluster.
6. If the cluster uses online licensing, set RequiresOnlineLicensing to true. For HPCC cluster, we use license server instead. If you are using MSU campus license and offloading to MSU HPCC cluster, you do not need to set this.
7. If you set RequiresOnlineLicensing to true, enter your LicenseNumber. For MSU campus license users, you do not need to set this.
8. Set OperatingSystem to the operating system of your cluster worker machines. The operating system of HPCC cluster is linux.
9. Set HasSharedFilesystem to false. This setting indicates that the client node (your local machine) and worker nodes (HPCC cluster nodes) cannot share the same data location.
10. Set the PluginScriptsLocation to the location of your plugin scripts ( the location is set at step 1) .
11. To set the connection to a remote cluster, under the AdditionalProperties table, select Add or directly edit the property** ClusterHost . For connect to HPCC cluster, the property with name ClusterHost, value hpcc.msu.edu, and type String.
12. To run jobs on a remote cluster without a shared file system, under the AdditionalProperties table, select Add or directly edit the property RemoteJobStorageLocation to specify a directory on the cluster for jobs to store related files. For HPCC cluster users, specify a new property with name RemoteJobStorageLocation, value as the path in your home or research space, for example, /mnt/home/<yourNetid>/remoteJobStorage/, and type String.
Click Done to save your cluster profile settings and changes.

Test examples

To test if the profile “Remote-HPCC-R2022b” is set correctly for HPCC cluster, users can run the validation from local machine.

Start MATLAB version R2022b on your local machine. Note that the version should match the version you will use on HPCC (define by the installation path).

From HOME -> Parallel computing options -> Create and Manage Clusters. Select the profile “Remote-HPCC-R2022b”, run “validation”. If you can pass the first 4 stages, the profile should work for offloading. You may ignore the last stage of the validation.
To further test the profile setting, users can also run some function or script locally and offload to the cluster, and compare the results. For example, a function get_min is saved in file get_min.m show as

function [s, t] =get_min(niter, n, m)
%function [s,t] = many_parfor_cluster(niter, n, m)
% This function runs myfunc.m may time in a parfor loop
% Workers are created and running on compute nodes
%
% INPUT
% niter: number of times to run.
% n, m: parameters for implicit.m function call.
%
% OUTPUT
% s: maximum value of niter output of myfunc.m
% t: elapsed time of the function.
%
tic;
S = zeros(niter,1);
parfor i =1:niter
    S(i) = max(svd(rand(n, m)));    % each worker will use 1 threads.
end
s = max(S);
t = toc;

The function get_min can be run on a local machine as

>> parpool('local', 4);    % use a local worker pool
Starting parallel pool (parpool) using the 'Local' profile ...
Connected to the parallel pool (number of workers: 4).

>> [s, t] = get_min(100,1000,1000)

s =
     5.010473515126743e+02
t =
     7.260608000000000e+00

The function get_min can also to offload as a job to run on the cluster. User need to create a cluster using the profile “Remote-HPCC-R2022b". Then create a job using “batch” to offload the function “get_min” to the cluster “HPCC” with 4 workers. To obtain the jobs output, user can use function "fetchOutputs" after the job is completed.

>> HPCC = parcluster('Remote-HPCC-R2022b');    % Create cluster HPCC
>> Job = batch(HPCC, @get_min, 2, {100,1000,1000},'pool', 4);  %create a job for cluster HPCC with 4 workers
>> wait(Job);      % wait Job to complete before fetching the results.
>> X = fetchOutputs(Job)
X =

  1×2 cell array

    {[501.0474]}    {[8.2506]}

To monitor the jobs, in the local MATLAB, from HOME -> Parallel computing options -> Monitor Jobs to open the job monitor window. Meanwhile, users can also monitor the jobs from a terminal window of the cluster and use SLURM commands to monitor the jobs.