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/l2_contract.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. Metric algorithms (overlap / crossing / planarity, with the verified cross-product test): 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