building-simulink-models

Building Models

Use model_edit for all structural changes — Simulink, System Composer, Simscape, and Stateflow chart internals

When to Use

• Adding, connecting, deleting, or replacing blocks in a model
• Configuring block parameters, signal properties, or model settings
• Creating or editing Stateflow chart internals (states, transitions, junctions, data, events, messages, functions)
• Building System Composer architecture models
• Wiring Simscape physical connections

When NOT to Use

• Querying parameter values → use model_query_params
• Resolving variable references to numeric values → use model_resolve_params

Workflow

1. Read first: Use model_read on the target scope to get block IDs and understand existing topology.
2. Plan the data flow: For complex edits, sketch inputs → operations → outputs, then map to blocks.
3. Edit: Use model_edit with operations scoped to one subsystem level at a time.
4. Verify: Use model_read on the scope to confirm the structure matches your intent.
5. Check connectivity: After all edits in a scope are complete, run model_check to catch unconnected ports or dangling lines. Fix any error-severity issues.

If model_edit returns status: partial: Run both model_read and model_check immediately — don't wait until all edits are complete.

Operation Chaining with ref

Use ref to name a block and #ref to reference it in later operations within the same call:

[{"op": "add_block", "type": "Gain", "name": "MyGain", "ref": "g1"},
 {"op": "connect", "target": "blk_5.y1 -> #g1.u1"}]

In SF scope, #ref references are portless — no .y1/.u1 suffixes (see reference/stateflow.md).

The response created map shows ref → blk_id (or ref → sf_X in SF scope). In subsequent calls, use the returned ID — #ref only works within a single call.

Guardrails

• Never manually construct block path strings from names shown in model_overview or model_read. Block names can contain invisible newlines and trailing whitespace that cause hilite_system, open_system, and get_param to fail. Instead, resolve paths from blk_X IDs:

  % blk_42 → use the number after "blk_" as the SID
  blockPath = Simulink.ID.getFullName('<ModelName>:42');
  hilite_system(blockPath)
  open_system(blockPath)
  get_param(blockPath, 'BlockType')
  

• Do not call Simulink.BlockDiagram.arrangeSystem or use set_param for block positioning unless the user explicitly requests it. model_edit has a built-in autolayout engine that runs automatically after each call.
• Always pass layout_mode to model_edit. Use "full" when populating an empty scope (new model root, or a newly-created subsystem) for optimal block arrangement. Use "incremental" when adding blocks to a scope that already has existing blocks (preserves existing positions).
• Each model_edit call operates in exactly one domain (Simulink, System Composer, or Stateflow) determined by the scope. To add a Chart block and then populate it, use two calls: SL scope for the Chart block, then SF scope for internals. Use model_read between calls to discover the chart's sf_X scope ID.
• Use meaningfully named variables (e.g., Kp_SpeedController) instead of hardcoded numeric values. Define variables in model workspace or a .m init script.
• Don't use evaluate_matlab_code with set_param/add_block to bypass model_edit — it skips autolayout, undo tracking, and error recovery
• Use open_system rather than load_system to open models that are not already open, or when creating new models, unless the user explicitly asks otherwise or the model is a library. This ensures the user can see live edits as they happen.

Naming Conventions

Prefer code-generation-safe names for blocks, signals, and variables:

• Use only: a-z, A-Z, 0-9, underscore (_)
• Don't start with a number
• Don't use leading/trailing or consecutive underscores
• Prefer names under 32 characters (required for some code generation targets)

Block Types

Use the block's display name in the type field. Do not construct or guess library paths.

• Built-in Simulink blocks: Use the BlockType directly: Gain, Sum, Constant, Integrator, SubSystem, Scope
• Library blocks (Simscape, Aerospace, DSP, Communications, etc.): Use the display name as it appears in the Simulink Library Browser: Voltage Source, Resistor, DC Motor, Solver Configuration, 6DOF (Euler Angles)
• If model_edit returns INVALID_TYPE: Fall back to the full library path from MATLAB documentation (e.g., ee_lib/Sources/Voltage Source)

[{"op": "add_block", "type": "Voltage Source", "name": "V1", "ref": "v1"},
 {"op": "add_block", "type": "Resistor", "name": "R1", "ref": "r1"},
 {"op": "add_block", "type": "Electrical Reference", "name": "Gnd", "ref": "gnd"},
 {"op": "add_block", "type": "Solver Configuration", "name": "Solver", "ref": "sc"}]

Review Gate

After completing all edits for a scope, verify:

• No error-severity issues from model_check (unconnected ports, dangling lines)
• All ref names resolved to blk_id in the created map — no dangling #ref references in subsequent calls
• Stateflow charts pass lint (model_check with checks='["stateflow_lint"]') before layout is applied
• If model_edit returned status: partial at any point, confirm the scope is now structurally complete via model_read

Domain-Specific Rules

When working with these domains, read the corresponding reference file before editing:

• Stateflow charts -> reference/stateflow.md — model_edit edits chart internals natively. Scope to a chart (sf_X or chart blk_X) and use the same operations: add_block for SF elements, portless connect for transitions, configure for properties. The reference covers SF-specific syntax, scoping, LabelString patterns, and the two-call SL+SF workflow.
• System Composer architecture models -> reference/system-composer.md — Create models with systemcomposer.createModel, then use model_edit. Components use type: "SubSystem", ports use Bus Element blocks. The reference covers component creation, port wiring, and behavior model generation.
• Simscape physical models -> reference/simscape.md — Physical connections use bidirectional <-> syntax. The reference covers connection semantics, port patterns, and initial target variables.

---

Copyright 2026 The MathWorks, Inc.

---