---

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: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.2"

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

| Function | Purpose | Available From | |---|---|---| | parallel.listProfiles | List profile names and the default | R2022b | | parallel.defaultProfile | Get or set the default profile | R2022b | | parallel.importProfile | Import a profile from .mlsettings | R2022b | | parallel.exportProfile | Export a profile to .mlsettings | R2022b | | parcluster | Construct a cluster object from a profile | R2022b | | cluster.saveAsProfile | Save a cluster object as a new profile | R2022b | | parallel.validateProfile | Validate a profile (standalone function) | R2025a | | validate(cluster) | Validate via the cluster object | R2026a | | parallel.deleteProfile | Delete a profile by name | R2026a | | discoverClusters | Bundled with this skill — discover MJS / Generic / HPCServer / MJSComputeCloud | scripts/discoverClusters.p | | cluster.Type | Property: "Local", "Threads", "MJS", "MJSComputeCloud", "Slurm", "PBSPro", "LSF", "HPCServer", "Generic" | R2022b |

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.saveAsProf