parallel.validateProfile

Validate parallel environment profile

Since R2025a

Syntax

parallel.validateProfile

parallel.validateProfile(profile)

parallel.validateProfile(___,Name=Value)

Description

parallel.validateProfile validates the default parallel environment or cluster profile.

The parallel.validateProfile function prints the validation stages performed and an indication of whether each stage passed, failed, or was skipped.

If a validation stage fails, the function saves a validation report to the temporary folder.

parallel.validateProfile(profile) validates the parallel environment profile specified by profile.

parallel.validateProfile(___,Name=Value) specifies additional profile validation options using one or more name-value arguments.

Examples

Validate Default Profile

Validate the default profile. The parallel.validateProfile function prints the validation stages performed and an indication of whether each stage passed, failed, or was skipped.

parallel.validateProfile

Beginning validation for cluster profile 'Processes'
Cluster connection test (parcluster)
   Stage started at 13:30:11.
   Finished at 13:30:11.
..........................................................................PASSED

Job test (createJob)
   Stage started at 13:30:11.
   Finished at 13:30:59.
..........................................................................PASSED

SPMD job test (createCommunicatingJob)
   Stage started at 13:31:04.
   Job ran with 6 workers.
   Finished at 13:32:26.
..........................................................................PASSED

Pool job test (createCommunicatingJob)
   Stage started at 13:32:33.
   Job ran with 6 workers.
   Finished at 13:33:55.
..........................................................................PASSED

Parallel pool test (parpool)
   Stage started at 13:34:04.
   20-Nov-2024 13:35:08: Job Queued. Waiting for parallel pool job with ID 43 to
   start ...
   Connected to parallel pool with 6 workers.
   Parallel pool using the 'Processes' profile is shutting down.
   Parallel pool ran with 6 workers.
   Finished at 13:35:44.
..........................................................................PASSED

Finished cluster profile validation with status: PASSED

Specify Profile for Validation

Validate the Threads profile. The parallel.validateProfile function only runs the Parallel pool test (parpool) validation stage for thread type profiles.

parallel.validateProfile("Threads")

Beginning validation for cluster profile 'Threads'
Parallel pool test (parpool)
   Stage started at 13:43:30.
   Starting parallel pool (parpool) using the 'Threads' profile ...
   Connected to parallel pool with 6 workers.
   Parallel pool using the 'Threads' profile is shutting down.
   Parallel pool ran with 6 workers.
   Finished at 13:43:30.
..........................................................................PASSED

Finished cluster profile validation with status: PASSED

Specify Stages to Validate

Validate the profile for a remote MATLAB® Job Scheduler cluster, myCluster, using 5 workers. Run only the "parcluster", "pool-job", and "parpool" stages. Save the validation results to a report file with the name "validation.txt". The parallel.validateProfile function prints the validation stages performed and an indication of whether each stage passed or failed.

parallel.validateProfile("myCluster",NumWorkersToUse=5,StagesToRun=["parcluster","pool-job","parpool"],ReportFile="validation.txt");

Beginning validation for cluster profile 'myCluster'
Cluster connection test (parcluster)
   Stage started at 14:00:46.
   Finished at 14:00:47.
..........................................................................PASSED

Pool job test (createCommunicatingJob)
   Stage started at 14:00:47.
   Job ran with 5 workers.
   Finished at 14:01:40.
..........................................................................PASSED

Parallel pool test (parpool)
   Stage started at 14:01:55.
   Connected to parallel pool with 5 workers.
   Parallel pool using the 'myCluster' profile is shutting down.
   Parallel pool ran with 5 workers.
   Finished at 14:03:03.
..........................................................................PASSED

Finished cluster profile validation with status: PASSED
Validation report written to validation.txt

Validate Profile Settings

Validate a newly created profile for a third-party remote cluster.

To ensure that you have successfully integrated MATLAB^® Parallel Server™ into your Spark™ cluster and that your profile is correctly configured, validate the Spark profile named "SparkProfile1". The validation fails because of an incorrectly configured profile and parallel.validateProfile automatically saves a report to the temporary folder.

parallel.validateProfile("SparkProfile1")

Beginning validation for cluster profile 'SparkProfile1'
Cluster connection test (parcluster)
   Stage started at 14:10:26.
   Unable to find Spark. Set the SPARK_HOME environment variable to a valid
   Spark installation folder or use the 'SparkInstallFolder' name-value
   parameter.
..........................................................................FAILED

Spark job test (tall)
   Validation skipped due to previous failure.
.........................................................................SKIPPED

Tall evaluation test (tall gather)
   Validation skipped due to previous failure.
.........................................................................SKIPPED

Finished cluster profile validation with status: FAILED
See validation report for full details:
 C:\Users\user\AppData\Local\Temp\validation_report_SparkProfile1.txt

Validate Profile at Command Line

You can validate a profile noninteractively at the command line using the -batch MATLAB startup option. To learn more about MATLAB startup options, see Commonly Used Startup Options.

In a command-line prompt, validate the profile for a remote cluster, mySlurmCluster, using 4 workers. Skip the "parpool" stage. Save the validation results to a report file with the name 'validation.txt'. The parallel.validateProfile function prints the validation stages performed and an indication of whether each stage passed or failed.

matlab -batch "parallel.validateProfile('mySlurmCluster',NumWorkersToUse=4,StagesToSkip='parpool',ReportFile='validation.txt')"

Beginning validation for cluster profile 'mySlurmCluster'
Cluster connection test (parcluster)
   Stage started at 14:53:30.
   Finished at 14:53:31.
..........................................................................PASSED

Job test (createJob)
   Stage started at 14:53:31.
   Finished at 14:53:54.
..........................................................................PASSED

SPMD job test (createCommunicatingJob)
   Stage started at 14:54:04.
   Job ran with 4 workers.
   Finished at 14:54:44.
..........................................................................PASSED

Pool job test (createCommunicatingJob)
   Stage started at 14:54:59.
   Job ran with 4 workers.
   Finished at 14:55:45.
..........................................................................PASSED

Finished cluster profile validation with status: PASSED
Validation report written to 'validation.txt'

Input Arguments

profile — Parallel environment or cluster profile

character vector | string

Parallel environment or cluster profile, specified as a character vector or string. If you do not specify a profile, parallel.validateProfile validates the default profile.

Example: "Processes"

Example: "Threads"

Example: "myMJSCluster"

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: NumWorkersToUse=4

NumWorkersToUse — Number of workers to use

nonnegative integer

Number of workers to use in validation, specified as a nonnegative integer. Use this argument to validate the profile with fewer workers than those specified in the profile's PreferredPoolNumWorkers or NumWorkers property.

Example: NumWorkersToUse=4

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

StagesToRun — Validation stages to run

string array | cell array of character vectors

Validation stages to run, specified as a string array or cell array of character vectors with one or more of these stage values:

• "parcluster" — Cluster connection test (parcluster) stage.

• "job" — Job test (createJob) stage.

• "spmd-job" — SPMD job test (createCommunicatingJob) stage.

• "pool-job" — Pool job test (createCommunicatingJob) stage.

• "parpool" — Parallel pool test (parpool) stage.

• "spark" — Spark job test (tall) stage.

• "tall" — Tall evaluation test (tall gather) stage.

Some stages are only available for certain parallel environment or cluster types. You cannot specify this argument if you specify the StagesToSkip argument. To learn more about each stage, see List of Validation Stages.

Example: StagesToRun=["parcluster","parpool"]

Data Types: char | string | cell

StagesToSkip — Validation stages to skip

string array | cell array of character vectors

Validation stages to skip, specified as a string array or cell array of character vectors with one or more of these stage values:

• "parcluster" — Cluster connection test (parcluster) stage.

• "job" — Job test (createJob) stage.

• "spmd-job" — SPMD job test (createCommunicatingJob) stage.

• "pool-job" — Pool job test (createCommunicatingJob) stage.

• "parpool" — Parallel pool test (parpool) stage.

• "spark" — Spark job test (tall) stage.

• "tall" — Tall evaluation test (tall gather) stage.

Some stages are only available for certain parallel environment or cluster types. You cannot specify this argument if you specify the StagesToRun argument. To learn more about each stage, see List of Validation Stages.

Example: StagesToSkip=["parcluster","spmd-job"]

Data Types: char | string | cell

ReportFile — File to save validation report

character vector | string

Filename to save validation report, specified as a character vector or string.

If you do not set the ReportFile argument and validation is successful, parallel.validateProfile does not create a report. If you do not set the ReportFile argument and validation fails, parallel.validateProfile automatically creates a validation report and saves it in the temporary folder.

Example: ReportFile="validation.txt"

Data Types: char | string

Limitations

• When you validate a profile for the Threads parallel environment, parallel.validateProfile runs only the Parallel pool test (parpool) stage.

Algorithms

List of Validation Stages

The parallel.validateProfile function performs these validation stages.

Validation Stage	Description
Cluster connection test (parcluster)	Tests cluster connections using the parcluster function.
Job test (createJob)	Tests independent job creation using the createJob function.
SPMD job test (createCommunicatingJob)	Tests creation of a batch job with an SPMD enabled parallel pool using the createCommunicatingJob function.
Pool job test (createCommunicatingJob)	Tests creation of a batch job with a parallel pool using the createCommunicatingJob function.
Parallel pool test (parpool)	Tests creation of an interactive parallel pool using the parpool function.
Spark job test (tall)	Tests creation of a job on a Spark cluster.
Tall evaluation test (tall gather)	Tests evaluation of a tall array on a Spark cluster using the tall and gather functions.

Version History

Introduced in R2025a