matlab-discover-clusters

name: matlab-discover-clusters description: > Discover MATLAB Parallel Computing Toolbox clusters on the network and in the cloud, and manage their profiles — list, inspect, import, export, set default, validate, and delete. Use whenever the user asks what parallel computing resources, clusters, or cluster profiles they have or can use — e.g. "what parallel resources do I have", "show my cluster profiles", "list clusters", "what clusters can I run on", "where can I submit jobs" — and for any work with parcluster, parallel.listProfiles, parallel.defaultProfile, MJS / Generic / HPC Server / MJSComputeCloud clusters, .mlsettings files, or profile validation. Does NOT cover job submission, parpool, or parfor. license: MathWorks BSD-3-Clause metadata: author: MathWorks version: "1.3"

Discover MATLAB Clusters

A cluster profile is a saved set of properties (name, type, host, number of workers, scheduler arguments) that lets MATLAB connect to a compute resource. This skill covers the full profile lifecycle: discovering clusters on the network, importing shared profiles, setting a default, validating, and deleting.

When to Use

• The user asks what parallel computing resources, clusters, or queues are available to them.
• The user wants to find clusters they can submit jobs to.
• The user has an .mlsettings profile file from an admin and needs to import it.
• The user wants to list, inspect, set the default for, validate, or delete a cluster profile.
• The user wants to export a cluster profile to share with colleagues.
• The user is calling parcluster or parpool and wants to know which resource it will use or which profile name to pass.

When NOT to Use

• Submitting jobs (batch, createJob, submit, parfeval) — this skill stops at "the cluster is ready to use."
• Pool lifecycle beyond profile selection — parpool startup/shutdown, gcp, and pool destruction are separate concerns. Identifying which profile to pass to parpool is in scope.
• GPU or parfor workflows — covered by separate skills.

Workflow

1. List existing profiles with parallel.listProfiles to see what is already configured.
2. If the user is missing an expected resource or wants to search for additional clusters, discover them with the bundled discoverClusters script (network and cloud).
3. Add the cluster as a profile — either by creating it from a discovered cluster (saveAsProfile) or importing a shared .mlsettings (parallel.importProfile).
4. Set the default profile with parallel.defaultProfile if appropriate.
5. Validate with parallel.validateProfile (R2025a+) or validate(c) on the cluster object before relying on it. Pass NumWorkersToUse (e.g. 2) or confirm with the user first — leaving it unset runs validation on the cluster's full worker count.
6. Delete obsolete profiles with parallel.deleteProfile (R2026a+) — confirm with the user first; deletion is irreversible.

After every step, verify before moving on — show the updated profile list, confirm the type/host/worker count, or check the validation report.

Key Functions

For features above the R2022b floor, use the fallback noted in the patterns and announce the release gap to the user.

Patterns

Listing and inspecting profiles

Use parallel.listProfiles to get profile names and parallel.defaultProfile() (no args) to read the default. To inspect a profile, call parcluster(name) and read cluster.Type (string), cluster.NumWorkers, and (where applicable) cluster.Host. Do not parse class(c) — Type is the supported public property.

parcluster(name) makes a network round-trip for MJS profiles to fetch live properties from the scheduler. An unreachable or release-mismatched MJS will throw "Unable to connect to MATLAB Job Scheduler" — that is expected behavior, not a code bug. Always wrap parcluster in try/catch when iterating profiles, and report unreachable profiles distinctly from missing ones.

The Threads profile cannot be returned by parcluster at all — skip it explicitly.

Compare profile names with strcmp (or two strings), not ==: comparing two char arrays with == does element-wise character comparison and errors when lengths differ.

profiles = parallel.listProfiles;
defaultName = parallel.defaultProfile();

fprintf("\n%-25s %-10s %-10s  %s\n", "Profile", "Type", "Workers", "Default");
fprintf("%s\n", repmat('-', 1, 70));
for k = 1:numel(profiles)
    name = profiles{k};
    marker = "";
    if strcmp(name, defaultName); marker = "(default)"; end
    if strcmp(name, "Threads")
        fprintf("%-25s %-10s %-10s  %s\n", name, "Threads", "n/a", marker);
        continue
    end
    try
        c = parcluster(name);
        fprintf("%-25s %-10s %-10d  %s\n", name, string(c.Type), c.NumWorkers, marker);
    catch
        fprintf("%-25s %-10s %-10s  %s\n", name, "?", "?", marker + " unreachable");
    end
end

Discover MJS, Generic, HPCServer, and MJSComputeCloud clusters

discoverClusters lives in this skill's scripts/ folder. Add it to the path before first use:

addpath(fullfile(skillRoot, "scripts"));   % skillRoot = directory containing this SKILL.md

The bundled discoverClusters function wraps the same internal discovery infrastructure used by the MATLAB Cluster Profile Manager UI. It returns a struct array with one entry per discovered cluster:

clusters = discoverClusters();                                  % all scopes, 30s timeout
% Other forms:
%   discoverClusters(Scope="network", TimeoutSeconds=15)
%   discoverClusters(Scope="cloud")

Each entry has fields: Type, Name, Host, NumWorkers, MatlabRelease, IsCompatible, CorrespondingProfiles, and Properties (a struct holding every discovered property, indexed by name). For Generic clusters, Properties contains PluginScriptsLocation, JobStorageLocation, AdditionalProperties, etc. — everything needed to construct the cluster.

Display findings concisely and call out IsCompatible == false (release mismatch) and any cluster that already has CorrespondingProfiles set (already imported).

clusters = discoverClusters();

if isempty(clusters)
    disp("No clusters discovered.");
    return
end

fprintf("Discovered %d clusters:\n", numel(clusters));
for k = 1:numel(clusters)
    profileNote = "no profile";
    if ~isempty(clusters(k).CorrespondingProfiles)
        profileNote = "profile: " + strjoin(string(clusters(k).CorrespondingProfiles), ", ");
    end
    compatNote = "compatible";
    if ~clusters(k).IsCompatible
        compatNote = "INCOMPATIBLE (" + clusters(k).MatlabRelease + ")";
    end
    fprintf("  [%d] %s '%s' on %s — %s, %s\n", ...
        k, clusters(k).Type, clusters(k).Name, clusters(k).Host, ...
        compatNote, profileNote);
end

Do not fall back to platform-specific CLI tools (nodestatus, mjs status) or hallucinated APIs (parallel.cluster.find, parallel.cluster.discover, findResource). Use discoverClusters — these alternatives either do not exist or bypass the supported discovery infrastructure.

If discoverClusters returns nothing, that does not mean the user has no cluster — not every Generic cluster is configured with a discoverable .conf file. Suggest the user contact their cluster administrator for a .mlsettings profile to import.

Save a discovered MJS cluster as a profile

After discovery, construct an MJS cluster with parallel.cluster.MJS(Name=, Host=) and call saveAsProfile(name). saveAsProfile is void — do not assign its return value.

parallel.cluster.MJS(Name=,Host=) connects to the MJS lookup service to validate the cluster and fetch live properties — it is not a cheap object construction step. If the cluster is unreachable it throws "Unable to connect to MATLAB Job Scheduler".

MJS clusters can prompt for credentials in a MATLAB dialog when the client connects, in two situations: the cluster has a non-zero SecurityLevel, or the cluster requires online licensing. The dialog blocks parallel.cluster.MJS(...) until the user responds; if it is dismissed without entering credentials, the call errors with "Operation aborted because no credentials were entered for user ...". Before running any code that constructs an MJS cluster object, warn the user explicitly: "About to connect to MJS cluster <Name> — switch to MATLAB now; a credentials dialog may appear and will block this command until you respond." Do not issue this warning when no MJS clusters were discovered or are being acted on — Generic, HPCServer, Local, and Threads profiles do not authenticate this way.

Always filter discovered clusters by Type=="MJS" before this pattern — discovery returns Generic / HPCServer / MJSComputeCloud entries too, and parallel.cluster.MJS against a Slurm headnode produces a confusing connection error.

clusters = discoverClusters(Scope="network");

% Pick the first compatible MJS without an existing profile.
isMJS = string({clusters.Type}) == "MJS";
target = clusters(find(isMJS & [clusters.IsCompatible] & ...
    cellfun(@isempty, {clusters.CorrespondingProfiles}), 1));

c = parallel.cluster.MJS(Name=target.Name, Host=target.Host);
c.saveAsProfile(target.Name);
fprintf("Saved profile '%s'\n", target.Name);

Before calling saveAsProfile(name), check parallel.listProfiles — if name is already taken, ask the user for an alternative (e.g. include the host) rather than silently overwriting or producing a duplicate.

Save a discovered Generic (Slurm/PBS/LSF) cluster as a profile

Generic clusters surface through filesystem-based discovery — admins ship a .conf file describing the scheduler, and discovery picks it up from matlabroot/toolbox/parallel/user/clusterprofiles, $MATLAB_CLUSTER_PROFILES_LOCATION, $HOME, or $HOME/Downloads. The Properties struct on the discovered entry holds everything the parallel.cluster.Generic object needs.

parallel.cluster.Generic has no Name property — the profile name is passed to saveAsProfile.

clusters = discoverClusters();
target = clusters(find(string({clusters.Type}) == "Generic" & ...
    [clusters.IsCompatible], 1));
p = target.Properties;

c = parallel.cluster.Generic;
c.NumWorkers = double(p.NumWorkers);
c.JobStorageLocation = char(p.JobStorageLocation);
c.PluginScriptsLocation = char(p.PluginScriptsLocation);
c.ClusterMatlabRoot = char(p.ClusterMatlabRoot);
c.OperatingSystem = char(p.OperatingSystem);
c.HasSharedFilesystem = logical(p.HasSharedFilesystem);
c.RequiresOnlineLicensing = logical(p.RequiresOnlineLicensing);

if isfield(p, 'AdditionalProperties')
    apFields = fieldnames(p.AdditionalProperties);
    for k = 1:numel(apFields)
        c.AdditionalProperties.(apFields{k}) = p.AdditionalProperties.(apFields{k});
    end
end

c.saveAsProfile(char(p.Name));

The same pattern works for any third-party scheduler discovered via .conf (Slurm, PBS Pro, LSF, Grid Engine, HTCondor) — the Type stays Generic; the scheduler is identified by the contents of PluginScriptsLocation.

Import a shared profile, set as default, validate

profileName = parallel.importProfile("team_cluster.mlsettings");
parallel.defaultProfile(profileName);
parallel.validateProfile(profileName);

parallel.importProfile returns the imported profile's name. parallel.defaultProfile with one argument sets the default and returns nothing useful — call parallel.defaultProfile() with no arguments to read it back.

Validate a cluster (with stages)

Use parallel.validateProfile (R2025a+). It accepts StagesToRun, StagesToSkip, NumWorkersToUse, and ReportFile name-value arguments. There are no output arguments — validation prints a report and writes to ReportFile if requested.

Always pass NumWorkersToUse for newly discovered or shared clusters — without it, validation runs on the full worker count, which is rarely what the user wants and on a shared cluster (e.g. an MJSComputeCloud or a site MJS) consumes resources other people may be waiting for. Confirm with the user before validating on the full cluster.

parallel.validateProfile("myProfile", ...
    StagesToRun=["parcluster", "job", "parpool"], ...
    NumWorkersToUse=4, ...
    ReportFile="validation-report.txt");

Valid stages (for most cluster types): "parcluster", "job", "spmd-job", "pool-job", "parpool". The exact set varies by cluster Type — Threads-only profiles validate fewer stages.

On R2026a+, the same options are also exposed on the cluster object via validate(cluster):

c = parcluster("myProfile");
validate(c, StagesToRun=["parcluster", "job", "parpool"]);

For releases below R2025a, there is no scriptable validation API — direct the user to the Cluster Profile Manager UI (Home > Parallel > Create and Manage Clusters) and announce the release gap.

Delete a profile

Always confirm with the user before deleting — parallel.deleteProfile is irreversible. List profiles first and read back the deletion target.

parallel.deleteProfile("oldCluster");

For releases below R2026a, there is no public function for this. Direct the user to the Cluster Profile Manager UI (Home > Parallel > Create and Manage Clusters or parallel.gui.ProfileManager.start).

Conventions

• Always read the profile list before mutating: parallel.listProfiles to see what exists, then parallel.defaultProfile() (no args) to see the default.
• Always verify IsCompatible before saving a discovered cluster as a profile — release mismatches will fail at job submit, not at profile creation.
• Always use cluster.Type to identify cluster kind — never class(c).
• Always wrap parcluster(name) in try/catch when iterating profiles — for MJS profiles it makes a network round-trip that fails on unreachable or release-mismatched servers.
• Always compare profile names with strcmp (or two strings), not ==. parallel.listProfiles returns a cell array of char, and == between two char arrays of different lengths errors.
• Always cap NumWorkersToUse (a small number like 2 is fine) when validating a freshly discovered or shared cluster, or confirm the worker count with the user first — leaving it unset runs validation on the cluster's full worker count.
• Always confirm with the user before deleting a profile — parallel.deleteProfile is irreversible.
• Always check parallel.listProfiles before calling saveAsProfile(name). If name is already taken, ask the user for an alternative rather than overwriting or producing a duplicate.
• Prefer parallel.listProfiles over the deprecated parallel.clusterProfiles.
• Prefer parallel.defaultProfile over the deprecated parallel.defaultClusterProfile.
• Prefer parallel.validateProfile (R2025a+) — it does not require constructing the cluster object first. validate(cluster) exposes the same options but only landed in R2026a; on R2025a it is the standalone function or the GUI.

Common Mistakes

Scripts

• scripts/discoverClusters.p — discover clusters using the same infrastructure as the Cluster Profile Manager UI. Returns a struct array with Type, Name, Host, NumWorkers, MatlabRelease, IsCompatible, CorrespondingProfiles. Name-value options: Scope ("all"/"network"/"cloud", default "all"), TimeoutSeconds (default 30).

Copyright 2026 The MathWorks, Inc.