matlab-discover-clusters

# 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 `string`s), not `==`: comparing two `char` arrays with `==` does element-wise character comparison and errors when lengths differ.

```matlab
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:

```matlab
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:

```matlab
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