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

Spec	Answers	Does NOT Contain
System	What are we building and why?	Subsystem decomposition, equations
Architecture	How is it structured?	Simulink block details, parameter values
Implementation Plan	How do we build it?	Actual model_edit commands
Test Plan	How do we validate it?	Test execution results

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.

---