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