Simulink Layout Tidy

simulink-layout-tidy

Make an already-built Simulink model compact, readable, and overlap-free — and report line crossings honestly, never promising a zero that the graph's topology forbids.

Safety invariants (read first)

In Simulink a block's Position and a line's Points are purely cosmetic and orthogonal to the port connections. That fact is the whole basis for this skill being safe.

• L1 contract (default, zero-risk). This skill MUST only modify block Position and line Points. It MUST NOT add or remove blocks and MUST NOT change any port connection. Why: the compiled model is then byte-for-byte identical, so simulation results cannot change and no functional re-test is needed.
• L2 contract (opt-in, explicit only). L2 additionally allows (a) replacing long-range / multi-consumer wires with Goto/From and (b) wrapping a functional cluster into a Subsystem. These are logically equivalent but change the block set, so after enabling L2 you MUST run one smoke simulation and confirm no NaN/Inf and unchanged behavior. See [references/l2contract.md](references/l2contract.md).
• NEVER hard-gate "zero line crossings." A non-planar graph (one containing a K3,3 or K5 minor) cannot be drawn crossing-free on a plane (Kuratowski). Forcing zero would reject mathematically-valid models. Use the tiered gates below instead.

Quick start (L1)

addpath('scripts');
load_system('my_model');
rpt = tidy_layout('my_model');          % diagnose -> arrange -> de-overlap -> re-measure -> screenshot
% rpt.before / rpt.after hold the metric structs; rpt.screenshot is the PNG path.

Diagnose planarity (decides whether zero crossings is even reachable):

extract_graph('my_model', 'graph.json');           % blocks=nodes, lines=edges
% then, from a venv/env with networkx:
% python3 scripts/planarity_check.py graph.json     (exit 2 == proven non-planar)

Workflow

| Step | Action | Where | |---|---|---| | 1 | Measure BEFORE: overlaps, line-block hits, crossings, extent | layout_metrics.m | | 2 | Diagnose planarity → is zero-crossing reachable at all? | extract_graph.m + planarity_check.py | | 3 | Build two candidates: minimal-move (de-overlap only) and arrange | tidy_layout.m | | 4 | Keep whichever has fewer crossings; NEVER accept an arrange regression | tidy_layout.m | | 5 | Measure AFTER + assert hard gates + export PNG for human sign-off | tidy_layout.m |

arrangeSystem optimizes placement and orthogonal routing but not crossing number — on a non-planar graph it can increase crossings (the fixture goes 9→15). So tidy_layout measures the arrange cost on a throwaway copy and falls back to the minimal-move layout (original routing + just-enough de-overlap) whenever arrange is strictly worse on crossings. The reported after never regresses crossings vs before; crossings remain a soft reported metric, never a hard gate.

Acceptance gates (tiered by reachability)

| Criterion | Gate type | |---|---| | block-block overlaps == 0 | hard assert (always achievable) | | line-through-block hits == 0 (or tiny threshold) | hard assert | | line-line crossings | soft report + soft gate: planar graph → expect ~0; non-planar → only require ≤ L1 floor, or resolved via L2 | | screenshot "not ugly" | human-in-the-loop — user eyeballs the PNG |

Full rationale and thresholds: [references/gates.md](references/gates.md). Metric algorithms (overlap / crossing / planarity, with the verified cross-product test): [references/algorithms.md](references/algorithms.md).

Self-contained fixture

make_dirty_fixture.m programmatically builds an ugly model (overlapping blocks, long crossing lines, a non-planar K3,3 fan-in). selftest.m runs the full L1 flow + planarity check against it — no external model needed:

addpath('scripts'); selftest        % builds fixture, tidies, asserts gates, prints planarity verdict

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: calebzu
• Source: calebzu/pmsm-control-claude-skills-for-matlab
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.