matlab-discover-clusters

MATLAB クラスターを検出する

クラスター プロファイルは、MATLAB をコンピューティングリソースに接続するための、プロパティ（名前、種類、ホスト、ワーカー数、スケジューラー引数）の保存済みセットです。このスキルでは、ネットワーク上のクラスターの検出、共有プロファイルのインポート、既定の設定、検証、削除まで、プロファイルのライフサイクル全体を扱います。

使用する場合

• ユーザーが、利用できる並列コンピューティングリソース、クラスター、またはキューについて尋ねている場合。
• ユーザーが、ジョブを送信できるクラスターを探したい場合。
• ユーザーが管理者から .mlsettings プロファイルファイルを受け取り、インポートする必要がある場合。
• ユーザーがクラスター プロファイルの一覧表示、詳細の確認、既定の設定、検証、または削除をしたい場合。
• ユーザーが同僚と共有するためにクラスター プロファイルをエクスポートしたい場合。
• ユーザーが parcluster または parpool を呼び出しており、どのリソースが使われるか、またはどのプロファイル名を渡せばよいかを知りたい場合。

使用しない場合

• ジョブの送信（batch、createJob、submit、parfeval）— このスキルで扱うのは「クラスターを使用する準備が整う」までです。
• プロファイルの選択以降のプールのライフサイクル — parpool の起動／終了、gcp、プールの破棄は別の事項です。parpool に渡すプロファイルの特定は対象範囲です。
• GPU または parfor のワークフロー — それぞれ別のスキルで扱います。

ワークフロー

1. parallel.listProfiles で既存のプロファイルを一覧表示し、すでに設定されているものを確認します。
2. ユーザーが想定しているリソースを見つけられない場合、または追加のクラスターを検索したい場合は、同梱の discoverClusters スクリプト（ネットワークとクラウド）で検出します。
3. 検出したクラスターから作成（saveAsProfile）するか、共有された .mlsettings をインポート（parallel.importProfile）して、クラスターをプロファイルとして追加します。
4. 必要に応じて、parallel.defaultProfile で既定のプロファイルを設定します。
5. 使用する前に、parallel.validateProfile（R2025a 以降）またはクラスター オブジェクトの validate(c) で検証します。NumWorkersToUse（例：2）を渡すか、先にユーザーに確認してください。指定しないと、クラスターの全ワーカー数で検証が実行されます。
6. 古くなったプロファイルは parallel.deleteProfile（R2026a 以降）で削除します。削除は取り消せないため、先にユーザーに確認してください。

各手順の後、次に進む前に検証します。更新されたプロファイル一覧を表示する、種類／ホスト／ワーカー数を確認する、または検証レポートを確認します。

主な関数

関数	用途	利用可能なバージョン
parallel.listProfiles	プロファイル名と既定のプロファイルを一覧表示する	R2022b
parallel.defaultProfile	既定のプロファイルを取得または設定する	R2022b
parallel.importProfile	.mlsettings からプロファイルをインポートする	R2022b
parallel.exportProfile	プロファイルを .mlsettings にエクスポートする	R2022b
parcluster	プロファイルからクラスター オブジェクトを構築する	R2022b
cluster.saveAsProfile	クラスター オブジェクトを新しいプロファイルとして保存する	R2022b
parallel.validateProfile	プロファイルを検証する（単独の関数）	R2025a
validate(cluster)	クラスター オブジェクトを介して検証する	R2026a
parallel.deleteProfile	名前でプロファイルを削除する	R2026a
discoverClusters	このスキルに同梱 — MJS / Generic / HPCServer / MJSComputeCloud を検出する	scripts/discoverClusters.p
cluster.Type	プロパティ：「Local」、「Threads」、「MJS」、「MJSComputeCloud」、「Slurm」、「PBSPro」、「LSF」、「HPCServer」、「Generic」	R2022b

R2022b より新しいバージョンで追加された機能には、パターンに記載された代替手段を使い、リリース時期の違いをユーザーに伝えてください。

パターン

プロファイルの一覧表示と確認

parallel.listProfiles を使ってプロファイル名を取得し、parallel.defaultProfile()（引数なし）を使ってデフォルトのプロファイルを読み取ります。プロファイルを確認するには、parcluster(name) を呼び出して、cluster.Type（文字列）、cluster.NumWorkers、および（該当する場合は）cluster.Host を読み取ります。class(c) を解析しないでください。Type はサポート対象のパブリックプロパティです。

MJS プロファイルに対する parcluster(name) は、スケジューラーから最新のプロパティを取得するためにネットワーク通信を行います。接続できない MJS、またはリリースが一致しない MJS では、「Unable to connect to MATLAB Job Scheduler」というエラーが発生します。これは想定される動作であり、コードのバグではありません。プロファイルを反復処理するときは、必ず parcluster を try/catch で囲み、接続できないプロファイルと存在しないプロファイルを区別して報告してください。

Threads プロファイルは parcluster では返せません。明示的にスキップしてください。

プロファイル名の比較には strcmp（または 2 つの string）を使い、== は使わないでください。2 つの char 配列を == で比較すると、文字ごとの比較が行われ、長さが異なる場合にエラーになります。

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

MJS、Generic、HPCServer、MJSComputeCloud クラスターの検出

discoverClusters は、このスキルの scripts/ フォルダーにあります。初めて使う前に、パスに追加してください。

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

同梱の discoverClusters 関数は、MATLAB Cluster Profile Manager UI が使用するものと同じ内部検出インフラストラクチャーを利用します。検出されたクラスターごとに 1 つのエントリを持つ構造体配列を返します。

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

各エントリには、Type、Name、Host、NumWorkers、MatlabRelease、IsCompatible、CorrespondingProfiles、および Properties（検出されたすべてのプロパティを名前でインデックス化した構造体）の各フィールドがあります。Generic クラスターの場合、Properties には PluginScriptsLocation、JobStorageLocation、AdditionalProperties など、クラスターの構築に必要な情報がすべて含まれます。

調査結果は簡潔に表示し、IsCompatible == false（リリースの不一致）であること、および CorrespondingProfiles がすでに設定されている（すでにインポートされている）クラスターを明示してください。

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

プラットフォーム固有の CLI ツール（nodestatus、mjs status）や、存在しない API（parallel.cluster.find、parallel.cluster.discover、findResource）には、絶対にフォールバックしないでください。discoverClusters を使ってください。これらの代替手段は、存在しないか、サポート対象の検出インフラストラクチャーを迂回します。

discoverClusters が何も返さなくても、ユーザーにクラスターがないという意味ではありません。検出可能な .conf ファイルが設定されていない Generic クラスターもあります。インポートする .mlsettings プロファイルをクラスター管理者に問い合わせるよう、ユーザーに提案してください。

検出した MJS クラスターをプロファイルとして保存する

検出後、parallel.cluster.MJS(Name=, Host=) で MJS クラスターを構築し、saveAsProfile(name) を呼び出します。saveAsProfile は void です。その戻り値を代入しないでください。

parallel.cluster.MJS(Name=,Host=) は MJS ルックアップサービスに接続してクラスターを検証し、最新のプロパティを取得します。単純にオブジェクトを構築するだけの処理ではありません。クラスターに到達できない場合は、"Unable to connect to MATLAB Job Scheduler" というエラーが発生します。

クライアントが接続する際、MJS クラスターでは MATLAB のダイアログで認証情報の入力を求められる場合があります。これは、クラスターの SecurityLevel が 0 以外の場合、またはオンラインライセンスが必要な場合に発生します。ユーザーが応答するまでダイアログが表示されたままとなり、parallel.cluster.MJS(...) は処理を停止します。認証情報を入力せずにダイアログを閉じると、"Operation aborted because no credentials were entered for user ..." というエラーが発生します。MJS クラスターオブジェクトを構築するコードを実行する前に、必ずユーザーに明示的に警告してください："About to connect to MJS cluster <Name> — switch to MATLAB now; a credentials dialog may appear and will block this command until you respond." MJS クラスターが検出されていない場合、または操作対象でない場合は、この警告を表示しないでください。Generic、HPCServer、Local、Threads のプロファイルでは、この方法で認証されません。

必ずこのパターンを適用する前に、検出されたクラスターを Type=="MJS" でフィルターしてください。検出では Generic／HPCServer／MJSComputeCloud のエントリーも返されます。また、Slurm のヘッドノードに対して parallel.cluster.MJS を実行すると、分かりにくい接続エラーが発生します。

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);

saveAsProfile(name) を呼び出す前に parallel.listProfiles を確認してください。name がすでに使われている場合は、上書きしたり重複を作成したりせず、別の名前（ホスト名を含めるなど）をユーザーに尋ねてください。

検出した Generic（Slurm/PBS/LSF）クラスターをプロファイルとして保存する

Generic クラスターは、ファイルシステムベースの検出によって見つかります。管理者がスケジューラーを記述した .conf ファイルを配置すると、検出処理が matlabroot/toolbox/parallel/user/clusterprofiles、$MATLAB_CLUSTER_PROFILES_LOCATION、$HOME、または $HOME/Downloads からそのファイルを検出します。検出されたエントリーの Properties 構造体には、parallel.cluster.Generic オブジェクトに必要なすべての情報が含まれています。

parallel.cluster.Generic に Name プロパティはありません。プロファイル名は 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));

同じパターンは、.conf によって検出されたサードパーティー製スケジューラー（Slurm、PBS Pro、LSF、Grid Engine、HTCondor）でも使用できます。Type は Generic のままです。スケジューラーは PluginScriptsLocation の内容によって識別されます。

共有プロファイルをインポートし、デフォルトに設定して検証する

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

parallel.importProfile は、インポートしたプロファイルの名前を返します。引数を 1 つ指定した parallel.defaultProfile はデフォルトを設定しますが、有用な値は返しません。現在の設定を読み取るには、引数なしで parallel.defaultProfile() を呼び出してください。

クラスターを検証する（ステージ指定あり）

parallel.validateProfile（R2025a 以降）を使用します。StagesToRun、StagesToSkip、NumWorkersToUse、ReportFile の名前と値の引数を受け取ります。出力引数はありません。検証レポートが表示され、指定した場合は ReportFile に書き込まれます。

新たに検出したクラスターや共有クラスターでは、必ず NumWorkersToUse を指定してください。指定しない場合、検証は全ワーカー数で実行されますが、これはユーザーが望む設定とは限りません。また、共有クラスター（MJSComputeCloud やサイトの MJS など）では、ほかのユーザーが利用を待っているリソースを消費します。クラスター全体で検証する前に、必ずユーザーに確認してください。

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

有効なステージ（ほとんどのクラスタータイプの場合）は "parcluster"、"job"、"spmd-job"、"pool-job"、"parpool" です。正確なステージの一覧はクラスターの Type によって異なります。Threads のみのプロファイルでは、検証するステージが少なくなります。

R2026a 以降では、同じオプションを validate(cluster) を使ってクラスターオブジェクトからも指定できます。

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

R2025a より前のリリースには、スクリプトから実行できる検証 API はありません。Cluster Profile Manager の UI（Home > Parallel > Create and Manage Clusters）を使うようユーザーに案内し、使用中のリリースではこの機能が利用できないことを伝えてください。

プロファイルを削除する

削除する前に、必ずユーザーに確認してください。parallel.deleteProfile は取り消せません。最初にプロファイルを一覧表示し、削除対象を読み上げて確認してください。

parallel.deleteProfile("oldCluster");

R2026a より前のリリースでは、これを行うパブリック関数はありません。ユーザーに Cluster Profile Manager UI（Home > Parallel > Create and Manage Clusters または parallel.gui.ProfileManager.start）を案内してください。

規約

• 必ず変更を加える前にプロファイルの一覧を読み取ってください。parallel.listProfiles で存在するプロファイルを確認し、次に parallel.defaultProfile()（引数なし）でデフォルトを確認します。
• 必ず検出したクラスターをプロファイルとして保存する前に、IsCompatible を確認してください。リリースが一致しない場合、プロファイル作成時ではなくジョブの送信時に失敗します。
• 必ずクラスターの種類の識別には cluster.Type を使ってください。class(c) は使わないでください。
• 必ずプロファイルを反復処理するときは parcluster(name) を try/catch で囲んでください。MJS プロファイルではネットワークへの往復が発生し、到達できないサーバーやリリースが一致しないサーバーでは失敗します。
• 必ずプロファイル名の比較には strcmp（または 2 つの string）を使い、== は使わないでください。parallel.listProfiles は char のセル配列を返し、長さの異なる 2 つの char 配列を == で比較するとエラーになります。
• 必ず新たに検出したクラスターや共有クラスターを検証する場合は、NumWorkersToUse に上限（2 などの小さな数で構いません）を設定するか、先にユーザーにワーカー数を確認してください。設定しないと、クラスターの全ワーカー数で検証が実行されます。
• 必ずプロファイルを削除する前にユーザーに確認してください。parallel.deleteProfile は取り消せません。
• 必ずsaveAsProfile(name) を呼び出す前に parallel.listProfiles を確認してください。name がすでに使用されている場合は、上書きや重複を避け、別の名前をユーザーに尋ねてください。
• 非推奨の parallel.clusterProfiles よりも、parallel.listProfiles を優先してください。
• 非推奨の parallel.defaultClusterProfile よりも、parallel.defaultProfile を優先してください。
• parallel.validateProfile（R2025a 以降）を優先してください。クラスターオブジェクトを先に作成する必要がありません。validate(cluster) でも同じオプションを使えますが、利用できるようになったのは R2026a 以降です。R2025a ではスタンドアロン関数または GUI を使用します。

よくある間違い

間違い	誤りである理由	正しい方法
parallel.clusterProfiles	R2022b 以降、非推奨です（引き続き動作しますが、推奨されません）。	parallel.listProfiles
parallel.defaultClusterProfile(name)	R2022b 以降、非推奨です。	parallel.defaultProfile(name)
クラスターの種類の識別に class(c) を使う	MATLAB のクラス名（'parallel.cluster.Local'）が返され、プロファイルの種類は返されません。	c.Type（"Local"、"MJS" などが返されます）
parallel.cluster.find、parallel.cluster.discover、findResource	いずれも存在しません。	discoverClusters（このスキルに含まれています）
system() 経由での nodestatus	CLI ツールであり、プラットフォーム固有で、API としてはサポートされていません。	discoverClusters
parallel.cluster.removeProfile、parallel.removeProfile	存在しない名前です。どちらも存在しません。	parallel.deleteProfile（R2026a 以降）
[ok, msg] = validate(c)	validate に出力引数はありません。	validate(c)（または parallel.validateProfile）を呼び出し、表示されたレポートまたは ReportFile を確認します。
name = c.saveAsProfile(name)	saveAsProfile は戻り値を返しません。	戻り値を代入せずに c.saveAsProfile(name) を呼び出します。
parallel.cluster.Generic で c.Name を設定する	Generic に Name プロパティはありません。Name はプロファイルの保存時に設定されます。	プロパティを設定してから、c.saveAsProfile("<name>") を呼び出します。
Threads プロファイルに対して parcluster を呼び出す	Threads プロファイルは parcluster で取得できません。	プロファイルを反復処理するときは Threads をスキップします。

スクリプト

• scripts/discoverClusters.p — Cluster Profile Manager UI と同じインフラを使用してクラスターを検出します。Type、Name、Host、NumWorkers、MatlabRelease、IsCompatible、CorrespondingProfiles を含む構造体配列を返します。名前と値のオプション：Scope（"all"／"network"／"cloud"、既定値は "all"）、TimeoutSeconds（既定値は 30）。

---

Copyright 2026 The MathWorks, Inc.

---