Specify Parallel Computing Toolbox Profile in Java Application

This example shows how to use the MATLAB^® Runtime User Data Interface to specify the profile of a Parallel Computing Toolbox™ cluster in a Java^® application.

For more details, see Using MATLAB Runtime User Data Interface.

Step 1: Write Parallel Computing Toolbox Code

Create sample_pct.m in MATLAB.

This example code uses the cluster defined in the default profile for Parallel Computing Toolbox.

function speedup = sample_pct (n)
warning off all;
tic
if(ischar(n))
    n=str2double(n);
end
for ii = 1:n
   (cov(sin(magic(n)+rand(n,n))));
end
time1 =toc;
parpool;
tic
parfor ii = 1:n
   (cov(sin(magic(n)+rand(n,n))));
end
time2 =toc;
disp(['Normal loop time: ' num2str(time1) ...
    ', parallel loop time: ' num2str(time2) ]);
disp(['parallel speedup: ' num2str(1/(time2/time1)) ...
    ' times faster than normal']);
delete(gcp);
disp('done');
speedup = (time1/time2);

Run the function with the input 400.
```
a = sample_pct(400)
```

The following is an example of the output, assuming the default profile is set to local:

Starting parallel pool (parpool) using the 'local' profile ...
Connected to the parallel pool (number of workers: 6).
Normal loop time: 2.5651, parallel loop time: 1.6371
parallel speedup: 1.5668 times faster than normal
Parallel pool using the 'local' profile is shutting down.
done

ans =

    1.5668

Step 2: Set Parallel Computing Toolbox Profile

To access the MATLAB Runtime User Data interface using a Java package built with MATLAB Compiler SDK™, you must set mcruserdata directly from MATLAB. There is no Java API to access mcruserdata as there is for C and C++ applications built with MATLAB Compiler SDK.

To set the mcruserdata from MATLAB, create an init function. This separate MATLAB function uses setmcruserdata to set the Parallel Computing Toolbox profile once. You then call your other functions to utilize the Parallel Computing Toolbox.

Create the following init_sample_pct function:

function init_sample_pct
% Set the Parallel Computing Toolbox Profile:
if(isdeployed)
    % Let the USER select the cluster profile.
    [profile, profpath] = uigetfile('*.mlsettings'); 
    setmcruserdata('ParallelProfile', fullfile(profpath, profile));
end

To export an existing profile to an .mlsettings file, use the parallel.exportProfile (Parallel Computing Toolbox) function. For example,

parallel.exportProfile('local','mylocalsettings');

Tip

If you need to change your profile in the application, use parallel.importProfile (Parallel Computing Toolbox) and parallel.defaultClusterProfile (Parallel Computing Toolbox). For more information, see Discover Clusters and Use Cluster Profiles (Parallel Computing Toolbox).

Step 3: Compile Your Code into Java Package

Build the Java package with the Library Compiler app or compiler.build.javaPackage.

Use the following information for your project:

Package Name	`parallelComponent`
Class Name	`PctClass`
Files to Compile	`sample_pct.m` and `init_pct_sample.m`

For example, if you are using compiler.build.javaPackage, type:

buildResults = compiler.build.javaPackage( ...
{'sample_pct.m','init_sample_pct.m'}, ...
'PackageName','parallelComponent','ClassName','PctClass');

For more details, see the instructions in Generate Java Package and Build Java Application.

Note

If you are using the GPU feature of Parallel Computing Toolbox, you must manually add the PTX and CU files.

If you are using the Library Compiler app, click Add files/directories on the Build tab.
If you are using a compiler.build function, use the AdditionalFiles option.
If you are using the mcc command, use the -a option.

Step 4: Write Java Application

Write source code for a Java application that accesses the MATLAB functions. Save this code as JavaParallelClass.java in the folder that contains the generated parallelComponent.jar package.

A sample application for this example is provided below.

import com.mathworks.toolbox.javabuilder.*;
import parallelComponent.*;
 
public class JavaParallelClass 
{
	public static void main(String[] args) 
	{
		 MWArray A = null;
		 PctClass C = null;
		 Object[] B = null;
		 try
		 {
			 C = new PctClass();
			 /* Set up the runtime with Parallel Data */
			 C.init_sample_pct();
			 A = new MWNumericArray(400);
			 B = C.sample_pct(1, A);
			 System.out.println("The speed up was: " + B[0]);
		 }
		 catch (Exception e)
		 {
			 System.out.println("The error is " + e.toString());
		 }
		 finally
		 {
			 MWArray.disposeArray(A);
			 C.dispose();
		 }
	}
}

Compile and Run Application

Compile your Java application using an IDE or at the command prompt.

On Windows^®, execute the following command:

javac -classpath "matlabroot\toolbox\javabuilder\jar\javabuilder.jar";.\parallelComponent.jar JavaParallelClass.java

On UNIX^®, execute the following command:

javac -classpath "matlabroot/toolbox/javabuilder/jar/javabuilder.jar":./parallelComponent.jar JavaParallelClass.java

Replace matlabroot with the path to your MATLAB or MATLAB Runtime installation folder. For example, on Windows, the default path is C:\Program Files\MATLAB\R2024b.

Run the JavaParallelClass application.

On Windows, execute the following command:

java -classpath .;"matlabroot\toolbox\javabuilder\jar\javabuilder.jar";.\parallelComponent.jar JavaParallelClass

On UNIX, execute the following command:

java -classpath .:"matlabroot/toolbox/javabuilder/jar/javabuilder.jar":./parallelComponent.jar JavaParallelClass

Note

If you are running the application on the Mac 64-bit platform, you must add the -d64 flag in the java command.

The JavaParallelClass application prompts you to select the cluster profile to use. After you select the .mlsettings file, the application displays output similar to the following:

Starting parallel pool (parpool) using the 'local_mcruserdata' profile ...
Connected to the parallel pool (number of workers: 6).
Normal loop time: 2.428, parallel loop time: 1.6515
parallel speedup: 1.4701 times faster than normal
Parallel pool using the 'local_mcruserdata' profile is shutting down.
done
The speed up was: 1.4701