matlab/simulink-agentic-toolkit/specifying-plant-models

Plant Model Specs

Structured specification of plant models for closed-loop simulation. Adapts the specifying-software templates for the physics-modeling domain.

When to Use

• Creating a plant model to close the loop with an existing controller
• Updating or extending an existing plant model spec
• Specifying a plant model before building it
• Deciding on model architecture (subsystem decomposition, fidelity level)
• Planning validation of a plant model

When NOT to Use

• Building the plant model → use building-simulink-models
• Testing an existing plant model → use testing-simulink-models
• Specs for controller algorithms or MBD algorithms → use specifying-mbd-algorithms
• Specs for traditional software (C, C++, Python, MATLAB scripts) → use specifying-software
• Specifying a full closed-loop system → use specifying-mbd-algorithms for the algorithm side, this skill for the plant side

Output Conventions

Store specs per plant model. Prefix every filename with the plant name so files are self-identifying in editor tabs, search results, and flat listings:

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

Example for a plant called motor:

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

Mode Selection

Does this plant have <5 states, single-rate dynamics, no strong nonlinearities, and will be built by one person/agent?

- Yes → Quick spec: 2 documents (system+architecture combined, implementation+test combined)

- No → Full spec: 4 separate documents

Document Boundaries

In quick mode, combine system+architecture and implementation+test into two documents.

Workflow

Step 1: Analyze Controller Interface

Read the controller model with model_overview and model_read. Classify every signal as:

• u (commanded inputs from controller), w (exogenous disturbances),
• y (measured outputs to controller, with sensor effects), z (truth outputs for debugging)

Define the plant boundary and document sample times.

Step 2: Assess Validation Evidence

Before researching the domain, establish what evidence exists: test data, datasheets, standard maneuvers, analytic expectations, reference models.

Fidelity must be justified by available evidence — no point modeling dynamics you can't validate. Intended use matters: MIL rapid iteration → lower fidelity acceptable; HIL/code generation → fixed-step, real-time constraints.

Step 3: Research the Physics Domain

Use web_search and read_web_page for standard modeling approaches, reference parameters, and authoritative sources. Consult references/plant-model-guidance.md for cross-domain patterns if needed.

Step 4: Write System Spec

Use assets/system-spec-template.md. Key plant-model sections: operating scenarios, physical model requirements, controller interface contract (u/w/y/z with sample times, data types, units), initialization & operating points, rate & timing alignment, validation evidence, reference sources.

Review gate before proceeding — verify:

• Completeness of interface requirements (u, y signals covered)
• Appropriate fidelity given intended use AND available validation evidence
• Coverage of controller's operating envelope in operating scenarios
• Operating points / initialization strategy specified and feasible
• Rate/sample time alignment with controller defined
• Clear validation reference for each major requirement

Get user review before proceeding.

Step 5: Write Architecture Spec

Use assets/architecture-spec-template.md. Key plant-model sections: component catalog with physics domain and port interfaces, equations of motion per subsystem, nonlinearities & constraints, numerical considerations (solver, stiffness, algebraic loops), parameter management, uncertainty hooks.

Review gate before finalizing — verify:

• Correct physics decomposition — subsystem boundaries at natural domain boundaries
• Complete signal flow from u through dynamics to y
• Disturbances w entering at the right points
• Consistent interfaces: units, sign conventions, coordinate frames end-to-end
• DAE / algebraic loop risks addressed; conservation laws respected
• Missing dynamics that affect the controller (actuator limits, sensor noise, transport delays)

Get user review before proceeding.

Step 6: Write Implementation Plan + Test Plan

Use assets/implementation-plan-template.md and assets/test-plan-template.md.

Implementation plan essentials:

• Phase 0 (interface contract & stubs) gates all parallel work — freeze ports/units/sign conventions first
• Loosely coupled subsystems (sensors, actuators, load, environment) can be built by separate agents concurrently after Phase 0; tightly coupled splits (inverter↔motor, tire↔chassis) need coordination
• Model References enable the strongest parallel development (separate .slx files)
• Parameter table: every parameter with name, value, unit, source, block path
• Sync points use model_read verification and model_query_params spot-checks

Test plan essentials:

• Three-stage validation: subsystem open-loop → integrated open-loop → closed-loop
• Input signal definitions with parameters (step, ramp, sine sweep)
• Gherkin scenarios mapped to model_test format
• Quantitative acceptance criteria with physical justification

Review gate — Implementation Plan — verify:

• Realistic bottom-up build order (leaf subsystems first)
• Phase 0 interface stubs gate parallel work
• Correct Simulink block types for the physics
• Solver choice matches stiffness + discrete elements
• Complete parameter table with sources and units

Review gate — Test Plan — verify:

• Validation staging: subsystem open-loop → integrated open-loop → closed-loop (MIL)
• Real-time execution feasibility assessed if plant is HIL-targeted
• Each maneuver specifies: input, outputs, comparison method, acceptance criteria
• Parameter sensitivity checks included
• Numerical robustness test (solver tolerance, step size)
• Gherkin scenarios executable via model_test

Get user approval before building begins.

Guardrails

Always

• Classify signals as u/w/y/z at every interface
• Cite sources for every parameter (value, unit, source, uncertainty, conditions)
• Assess validation evidence before choosing fidelity level
• Decompose into subsystems at natural domain boundaries (actuator, dynamics, sensor, environment, load)

Ask First

• Fidelity level changes after system spec is approved
• Adding subsystems not in the architecture spec
• Deviating from the controller's sample time alignment

Never

• Reproduce textbook derivations in specs — cite authoritative sources instead; use web_search for domain-specific research
• Model dynamics you cannot validate against available evidence
• Skip Phase 0 interface stubs when parallel building is planned
• Use web_search results from unvetted sources — prefer standards, textbooks, MathWorks docs, and peer-reviewed papers

References

• assets/system-spec-template.md — System spec template (what & why)
• assets/architecture-spec-template.md — Architecture template (subsystem decomposition)
• assets/implementation-plan-template.md — Build sequence template
• assets/test-plan-template.md — Validation plan template
• references/plant-model-guidance.md — Optional domain reference (decomposition examples, validation maneuvers, solver guide). Human-facing; do not copy verbatim into specs.

Copyright 2026 The MathWorks, Inc.