specifying-plant-models

プラントモデル仕様

閉ループシミュレーション用のプラントモデルの構造化仕様です。物理モデリングの領域に合わせて、specifying-software のテンプレートを適用しています。

使用する場面

• 既存のコントローラーと閉ループを構成するプラントモデルを作成する
• 既存のプラントモデル仕様を更新または拡張する
• プラントモデルの構築前に仕様を定める
• モデルのアーキテクチャ（サブシステムの分割、忠実度レベル）を決定する
• プラントモデルの検証を計画する

使用しない場面

• プラントモデルを構築する → building-simulink-models を使用
• 既存のプラントモデルをテストする → testing-simulink-models を使用
• コントローラーアルゴリズムまたは MBD アルゴリズムの仕様 → specifying-mbd-algorithms を使用
• 従来型ソフトウェア（C、C++、Python、MATLAB スクリプト）の仕様 → specifying-software を使用
• 閉ループシステム全体を仕様化する → アルゴリズム側には specifying-mbd-algorithms、プラント側にはこのスキルを使用

出力規約

プラントモデルごとに仕様を保存します。エディターのタブ、検索結果、フラットな一覧でファイルを識別できるよう、すべてのファイル名の先頭にプラント名を付けてください。

docs/specs/plant-models/<plant-name>/
├── <plant-name>-system.md              # What & why
├── <plant-name>-architecture.md        # Subsystem decomposition
├── <plant-name>-implementation-plan.md # Build sequence
└── <plant-name>-test-plan.md           # Validation plan

motor というプラントの例：

docs/specs/plant-models/motor/
├── motor-system.md
├── motor-architecture.md
├── motor-implementation-plan.md
└── motor-test-plan.md

モードの選択

このプラントの状態数は5未満で、ダイナミクスは単一レートで、強い非線形性はなく、1人の作業者／エージェントが構築しますか？

• はい → 簡易仕様：2つの文書（システムとアーキテクチャを統合、実装とテストを統合）
• いいえ → 完全仕様：4つの個別文書

文書の範囲

仕様	答える内容	含めない内容
システム	何を、なぜ構築するのか？	サブシステムの分割、方程式
アーキテクチャ	どのような構成か？	Simulink ブロックの詳細、パラメーター値
実装計画	どのように構築するのか？	実際の model_edit コマンド
テスト計画	どのように検証するのか？	テストの実行結果

簡易モードでは、システムとアーキテクチャ、および実装とテストをそれぞれ1つの文書に統合します。

ワークフロー

ステップ 1：コントローラーのインターフェースを分析する

model_overview と model_read を使ってコントローラーモデルを読み取ります。各信号を次のように分類します。

• u（コントローラーからの指令入力）、w（外因性外乱）、
• y（センサーの影響を含む、コントローラーへの測定出力）、z（デバッグ用の真値出力）

プラントの境界を定義し、サンプル時間を記録します。

ステップ 2：検証エビデンスを評価する

ドメインの調査を始める前に、利用できるエビデンスを確認します。テストデータ、データシート、標準的なマヌーバー、解析的な予測、参照モデルなどが該当します。

忠実度は利用可能なエビデンスに基づいて決める必要があります。検証できないダイナミクスをモデル化しても意味がありません。用途も重要です。MIL による迅速な反復では低い忠実度でも許容されますが、HIL／コード生成では固定ステップやリアルタイムの制約が適用されます。

ステップ 3：物理ドメインを調査する

標準的なモデリング手法、参照パラメーター、信頼できる情報源の調査に web_search と read_web_page を使用します。必要に応じて、異なるドメインに共通するパターンについて references/plant-model-guidance.md を参照してください。

ステップ 4：システム仕様を作成する

assets/system-spec-template.md を使用します。プラントモデルで重要なセクションは、運転シナリオ、物理モデルの要件、コントローラーインターフェースの契約（サンプル時間、データ型、単位を含む u/w/y/z）、初期化と運転点、レートとタイミングの整合、検証エビデンス、参照情報です。

先に進む前にレビューゲートを設け、以下を確認します。

• インターフェース要件が網羅されている（u と y の信号を網羅）
• 用途と利用可能な検証エビデンスに照らして、忠実度が適切である
• 運転シナリオがコントローラーの動作範囲を網羅している
• 運転点／初期化戦略が指定され、実現可能である
• コントローラーとのレート／サンプル時間の整合が定義されている
• 主要な要件ごとに明確な検証の根拠がある

先に進む前にユーザーのレビューを受けてください。

ステップ 5：アーキテクチャ仕様書を作成する

assets/architecture-spec-template.mdを使用します。プラントモデルで重要なセクション：物理領域とポートインターフェースを含むコンポーネントカタログ、サブシステムごとの運動方程式、非線形性と制約、数値的な考慮事項（ソルバー、スティフネス、代数ループ）、パラメーター管理、不確かさに関するフック。

最終化前のレビューゲート — 以下を確認します。

• 物理に基づく適切な分解 — 自然な領域境界でのサブシステム境界
• uからダイナミクスを経てyまでの信号フローが完全であること
• 外乱wが適切な箇所に入力されていること
• インターフェースの一貫性：単位、符号規約、座標系が全体を通じて統一されていること
• DAE／代数ループのリスクに対処し、保存則が守られていること
• コントローラーに影響するダイナミクスの見落としがないこと（アクチュエーターの制限、センサーノイズ、輸送遅延）

次に進む前に、ユーザーのレビューを受けてください。

ステップ 6：実装計画とテスト計画を作成する

assets/implementation-plan-template.mdとassets/test-plan-template.mdを使用します。

実装計画の要点：

• フェーズ 0（インターフェース契約とスタブ）が、すべての並行作業の前提条件です — まずポート／単位／符号規約を確定します
• 疎結合のサブシステム（センサー、アクチュエーター、負荷、環境）は、フェーズ 0 の完了後に別々のエージェントで並行して構築できます。密結合の分割（インバーター↔モーター、タイヤ↔シャシー）には調整が必要です
• Model Referencesにより、最も効果的な並行開発が可能になります（別々の.slxファイル）
• パラメーターテーブル：すべてのパラメーターについて、名前、値、単位、出典、ブロックパスを記載します
• 同期ポイントでは、model_readによる検証とmodel_query_paramsによるスポットチェックを行います

テスト計画の要点：

• 3段階の検証：サブシステムの開ループ → 統合モデルの開ループ → 閉ループ
• パラメーターを含む入力信号の定義（ステップ、ランプ、正弦波スイープ）
• model_test形式に対応付けたGherkinシナリオ
• 物理的な根拠を伴う定量的な合格基準

レビューゲート — 実装計画 — 以下を確認します。

• 現実的なボトムアップの構築順序（まずリーフサブシステム）
• フェーズ 0 のインターフェーススタブが並行作業の前提条件となっていること
• 物理現象に適したSimulinkブロックタイプ
• スティフネスと離散要素に適したソルバーの選択
• 出典と単位を含む完全なパラメーターテーブル

レビューゲート — テスト計画 — 以下を確認します。

• 段階的な検証：サブシステムの開ループ → 統合モデルの開ループ → 閉ループ（MIL）
• プラントがHILを対象とする場合、リアルタイム実行の実現可能性が評価されていること
• 各マヌーバーについて、入力、出力、比較方法、合格基準が指定されていること
• パラメーター感度のチェックが含まれていること
• 数値ロバスト性テスト（ソルバーの許容誤差、ステップサイズ）
• model_testで実行可能なGherkinシナリオ

構築を開始する前に、ユーザーの承認を得てください。

ガードレール

必ず行うこと

• すべてのインターフェースで、信号をu/w/y/zに分類します
• すべてのパラメーターについて、出典（値、単位、出典、不確かさ、条件）を明記します
• 忠実度レベルを選択する前に、検証エビデンスを評価します
• 自然な領域境界（アクチュエーター、ダイナミクス、センサー、環境、負荷）でサブシステムに分解します

先に確認すること

• システム仕様の承認後に忠実度レベルを変更する場合
• アーキテクチャ仕様書に含まれていないサブシステムを追加する場合
• コントローラーのサンプル時間との整合性から逸脱する場合

絶対にしないこと

• 仕様書で教科書の導出過程を再現すること — 代わりに信頼できる出典を引用し、分野固有の調査にはweb_searchを使用します
• 利用可能なエビデンスに照らして検証できないダイナミクスをモデル化すること
• 並行構築を計画している場合にフェーズ 0 のインターフェーススタブを省略すること
• 十分に精査されていない情報源からのweb_searchの結果を使用すること — 規格、教科書、MathWorksのドキュメント、査読付き論文を優先します

参考資料

• assets/system-spec-template.md — システム仕様テンプレート（概要と目的）
• assets/architecture-spec-template.md — アーキテクチャテンプレート（サブシステムの分解）
• assets/implementation-plan-template.md — 構築手順テンプレート
• assets/test-plan-template.md — 検証計画テンプレート
• references/plant-model-guidance.md — 任意のドメイン参考資料（分解例、検証操作、ソルバーガイド）。人間向けです。仕様書にそのままコピーしないでください。

---

Copyright 2026 The MathWorks, Inc.

---