matlab-create-experiment

Experiment Manager 用の実験を作成

ユーザーのコードまたは問題の説明を分析し、実験の種類を判断して、適切な実験関数、ハイパーパラメーターのテーブル、および実験オブジェクトを生成することで、MATLAB Experiment Manager で実験を計画、作成します。

使用する場合

• ユーザーが MATLAB のスクリプト／関数を持っており、パラメーターまたはハイパーパラメーターをスイープしたい場合
• ユーザーが実験の作成や構成の比較を求めている場合
• ユーザーが問題を説明し、パラメーター空間を探索したい場合
• ユーザーが異なるパラメーターの組み合わせで出力を追跡したい場合

使用しない場合

• ユーザーが既存の実験やトレーニングの失敗をデバッグしている場合
• ユーザーが既存の実験の実行、再開、または結果の表示を求めている場合
• ユーザーがすでに動作する Experiment Manager の実験を設定している場合
• ユーザーが実験の設定（ハイパーパラメーター、戦略、説明）の編集を求めている場合 — Experiment Manager アプリで変更するよう案内してください。ただし、実験関数のコード（.m ファイル）の編集は許可されています。
• ユーザーがベイズ最適化またはランダムサンプリング戦略を求めている場合 — Experiment Manager アプリで設定するよう案内してください

---

自律性モデル

このスキルでは、ガイダンスと自律性を組み合わせたパターンに従います。判断が必要な箇所にはタグが付いています。

タグ	意味
[user]	必ず一時停止して質問します。これは必須です。
[auto]	エージェントが内部で判断します。失敗した場合は確認を求めます。
[depends]	シグナルの明確さに応じて判断します。明確なら自動で進め、不明確なら質問します。

分析後、どのように作業を進める予定かを、簡潔な一文でユーザーに伝えてください。 必ず次の文を追加してください。「制御を強めたい場合や緩めたい場合はお知らせください。」

---

フェーズ 1：分析

ユーザーのコードまたは問題の説明を読み、実験の種類を分類します。

種類の分類

API レベルのシグナルと意味的なシグナルを使い、次の 3 種類のいずれかに分類します。

重要： 明示的な DL API 呼び出しがなくても、意味的なシグナルがトレーニングを示している場合は、汎用ではなくトレーニングに分類します。

種類	シグナル	テンプレートクラス
汎用	DL 関数もトレーニングを示す要素もありません。最適化、シミュレーション、データ分析などです。	'experiments.internal.experimentTemplates.MATLABFunction'
組み込みトレーニング	trainnet／trainNetwork／trainingOptions、標準レイヤー、データストアを使用します。または、ファイル名に "train" が含まれるか、ユーザーが "classification"／"transfer learning" に言及しています。	'experiments.internal.experimentTemplates.BlankTrainnetTraining'
カスタムトレーニング（カスタムループ）	dlnetwork／dlfeval／dlgradient／dlarray、手動の勾配計算、GAN を使用します。または、損失計算を含むトレーニングループがあるか、ユーザーが "fine-tune"／"detector" に言及しています。	'experiments.internal.experimentTemplates.CustomTraining'

分類の優先順位

1. トレーニングループの構造（エポックの反復、損失の追跡）→ カスタムトレーニング
2. ループなしでデータ／レイヤー／オプションを設定 → 組み込みトレーニング
3. 意味的なシグナルも API シグナルもトレーニングを示さない → 汎用

調査する変数

変数	タグ	備考
実験の種類	[depends]	シグナルが明確なら自動で判断し、不明確なら質問します
スイープするパラメーター	[depends]	ハードコードされた値から自動推定し、不明確なら質問します
パラメーターの値	[auto]	ハードコードされた値を基に、2～3 個の代替値を提案します
初期化関数が必要か	[auto]	パラメーターと無関係な高コスト処理が検出された場合は「はい」です
関数シグネチャ	[auto]	種類に応じて決定します（REFERENCES.md を参照）

終了条件：種類が分類され、パラメーターが特定され、出力が把握されています。

---

Phase 2: 設計

実験関数を生成し、ユーザーが確認できるよう設計全体を準備します。

1. 説明 — 以下を含む2～4行の説明を作成します。実験の内容、スイープするパラメーター、各試行で取得する出力、評価基準。

2. パラメーター — パラメーター表（Name | Values | Description）を作成します。

   • ハードコードされた値 → その値の前後にある候補を2～3個提案します
   • カテゴリ値 → 妥当な候補を列挙します
   • [auto] 試行の合計が50を超える場合は警告します（値を減らすよう提案します）

3. 関数シグネチャ — 種類に応じて選択します。

   Type	Signature
   General purpose	[out1, out2, ...] = func(params)
   Built-in (Form A, targets in datastore)	[trainingData, net, lossFcn, options] = func(params)
   Built-in (Form B, targets separate)	[trainingData, targets, net, lossFcn, options] = func(params)
   Custom training	output = func(params, monitor)

   組み込み関数では、最後の3つの出力は常に net、lossFcn、options にする必要があります。 Form A と Form B の選択ガイドおよびサポートされている損失関数については、references/REFERENCES.md を参照してください。

4. 実験関数の生成 — ユーザーのコードを実験関数に適合させます。

   提示時の見出し規則：

   • 汎用 → "Generated Experiment Function"
   • 組み込みトレーニング → "Generated Setup Function"
   • カスタムトレーニングループ → "Generated Training Function"

   主なルール：

   • 調整可能な値にはすべて params.<field> を使用します（スイープする値をハードコードしないでください）
   • 各 params.<field> は単一のスカラー値（数値、文字列、または論理値）です。Experiment Manager は各試行に1つの値を割り当てます。関数内でパラメーター値をループ処理しないでください。スイープは外部で処理されます。
   • trainingOptions では 'Plots', 'none' を使用します
   • H1 ヘルプコメントブロックを含めます
   • すべてのファイル／データ参照には絶対パスを使用します。REFERENCES.md の § "Absolute Path Rules" を参照してください
   • カスタムトレーニングのモニターパターンについては、REFERENCES.md の § "Custom Training Monitor Pattern" を参照してください

   Type	Body contains	Returns
   General purpose	Figure／プロットのコードを含む、ユーザーの計算ロジック	名前付き出力（シリアル化可能な任意の型）
   Built-in training	データの読み込み、ネットワークの定義、trainingOptions	[data..., net, lossFcn, options]
   Custom training	モニターとの連携およびFigure／プロットのコードを含むトレーニングループ	output（シリアル化可能な任意の型）

5. [auto] 初期化関数 — ハイパーパラメーターに依存しない、コストの高い一度限りの処理（データのダウンロード、大きなファイルの読み込み、params に依存しないデータストアなど）が検出された場合は、初期化関数に切り出します。 コードテンプレートについては、references/REFERENCES.md の § "Initialization Function Template" を参照してください。

---

Phase 3: 確認

Gate: [user] — 実行前に設計を提示して確認を受けます。

必須： ファイルの作成や MATLAB コードの実行を行う前に、必ず設計を提示し、ユーザーから明示的な確認を受けてください。ユーザーが以前に同様の実験を確認していても、このゲートを省略してはいけません。例外は、ユーザーが確認を省略するよう明示的に指示した場合（例：「確認せずに作成してください」）のみです。

提示する順序が重要です：

1. 生成した実験関数のコード
2. 生成した初期化関数のコード（該当する場合）
3. 概要表
4. 確認を求める

概要表を関数コードより先に表示しないでください。

概要表：

Topic	Details
Experiment type	<選択した種類とその理由>
Parameters/Hyperparameters	<コンマ区切りのリスト>
Total trials	<数値>
Function name	<functionName>
Initialization function	<生成した場合は initFunctionName>、生成しない場合はその理由
Key metric	<メトリック名>（<最小化／最大化>）
Logged live metrics	<コンマ区切りのリスト>

ユーザーの確認後にのみ Phase 4 に進みます。

---

Phase 4: 作成と検証

MATLAB で実験のセットアップを実行します。

4a: プロジェクトのセットアップ [auto]

1. currentProject を確認します — 開いていればそれを使用し、そうでなければ新しいプロジェクトを作成します
2. 開いているプロジェクトを閉じたり置き換えたりしないでください。 currentProject が成功した場合は、常にそのプロジェクトを使用します — 実験関数と .mat ファイルをそのルートフォルダに書き込みます。matlab.project.createProject を呼び出すのは、プロジェクトが開いていない場合だけです。
3. matlab.project.createProject は pwd を変更します — 直後に pwd をそのまま使用し、フォルダを前に付けないでください
4. プロジェクトが存在した後に、writelines を使って関数ファイルをプロジェクトルートに書き込みます
5. 新しいプロジェクトを作成するときは、一意のフォルダ名を生成します（_2、_3 を付け加えます）

完全なコードについては references/REFERENCES.md の「Step 6 Code Template」を参照してください。

4b: 実験オブジェクトの作成 [auto]

createExperiment ヘルパー（scripts/ 内）を使用します。これが処理する内容は次のとおりです:

• params 構造体からハイパーパラメータテーブルを構築する
• 一意の .mat ファイル名を生成する（決して上書きしません）
• ファイル名から実験名を設定する
• プロジェクトに追加する

4c: 検証 [auto]

検証を実行する前に、何をチェックするのかをユーザーに簡単に伝えます: 「関数がパス上に存在し、静的解析に合格し、正しいシグネチャを持ち、そのパラメータ参照がハイパーパラメータテーブルと一致することを検証しています。」

パスの移植性チェック: 検証の前に、生成された関数内の相対ファイルパスをスキャンします。見つかった場合は、絶対パスに解決して書き換えます。

段階的な検証を実行します（REFERENCES.md の「Validation」を参照）:

1. Tier 0 — 存在確認: which() で関数がパス上にあることを確認します
2. Tier 1 — 静的解析: checkcode() を実行します。重大度 > 1（エラー）の場合はブロックします。重大度 ≤ 1 の場合は警告します。
3. Tier 2a — シグネチャ: nargin と nargout が実験タイプと一致することを確認します:
   • general: nargin=1, nargout≥1
   • builtin_A: nargin=1, nargout=4
   • builtin_B: nargin=1, nargout=5
   • custom: nargin=2, nargout=1
4. Tier 2b — パラメータカバレッジ: 関数のソースを解析して params.<field> 参照を調べます。 関数がハイパーパラメータテーブルにない params を参照している場合は失敗します。テーブルのエントリが未使用の場合は警告します。

ゲート: [auto] — 検証結果

• すべての Tier に合格 → Experiment Manager を開きます（REFERENCES.md の「Open Experiment Manager」を参照）
• ブロッキング障害 → 修正し、.m と .mat を書き換え、再検証します（最大 2 回）
• 2 回試行しても失敗 → [user] にエラーの詳細を添えてエスカレーションします

---

フェーズ 5: ハンドオフ

実験が作成され、Experiment Manager が開いたら:

あなたの実験は Experiment Manager で準備完了です！ 実行前にできることをいくつか紹介します:

推奨される作成アクション:

• ハイパーパラメータテーブルでハイパーパラメータの値を編集するか、新しいパラメータを追加します
• 実験の説明を変更します
• Experiment Manager アプリから関数を開いて調整します:
  • 汎用 → 「experiment function」
  • 組み込みトレーニング → 「setup function」
  • カスタムトレーニングループ → 「training function」
• アプリの UI から初期化関数を追加または設定します

準備ができたら、Experiment Manager ツールバーの Run をクリックして試行を開始してください。

---

主なルール

1. 常に新しいファイルを作成します — 既存のファイルを上書きせず、数値のサフィックスを追加します。
2. MATLAB 内に関数ファイルを書き込みます — writelines を使ってプロジェクトフォルダーに直接書き込みます。
3. ユーザーのロジックを保持します — コードを実験関数に適合させ、アルゴリズムを書き換えないでください。
4. 学習の進行状況を示すプロットは表示しません — trainingOptions では 'Plots', 'none' を使用します（組み込みの学習のみ）。汎用学習およびカスタム学習では、ユーザーの Figure／プロットのコードを保持します。
5. params 構造体を使用します — 調整可能な値はすべて params から取得し、ハードコードしないでください。
6. プロジェクトベースにします — 実験は MATLAB プロジェクト内に配置する必要があります。
7. 一意の名前を使用します — 関数と実験ファイルには、内容がわかる一意の名前を付けます。プロジェクト名にはサフィックス Project、実験名にはサフィックス Experiment を使用します（例：AntennaProject、AntennaExperiment）。
8. 内部 API を公開しないでください — テンプレートクラス名をユーザーに表示しないでください。
9. 絶対パスを使用します — すべてのファイル参照では、絶対パスの構成要素を指定して fullfile() を使用してください。

テンプレートクラス、シグネチャの対応付け、一般的なハイパーパラメーターについては、references/REFERENCES.md を参照してください。

---

エラーからの回復

エラー	対処方法
検証に失敗する	関数を修正し、.mat を書き換えて、再検証します（最大 2 回まで）
相対パスが見つかった	ソーススクリプトのディレクトリを基準に絶対パスへ解決し、書き換えます
プロジェクトが開かれておらず、作成もできない	ユーザーにプロジェクトの保存場所を尋ねます
試行回数が 50 を超える	警告し、値を減らすよう提案します
実験タイプが曖昧	ユーザーに確認を求めます
ファイルがすでに存在する	数値のサフィックス（_2、_3、...）を追加します
パスを解決できない	ユーザーにフルパスを尋ねます

---

Copyright 2026 The MathWorks, Inc.