Add a benchmark harness for iterating on layout behaviour

[matt-edmondson]

Why

Judging a layout change by running a graph once and looking at the number does not work. The simulation is chaotic — which local minimum one starting arrangement falls into says nothing about the change that was made, and a single-start assertion flips between passing and failing across parameter values that are all perfectly reasonable.

Repulsion_IsWhatSpreadsAGraphOut did exactly that while #375 was being tuned: it passed at repulsion 1,200,000 and 600,000, failed at 800,000, and passed again at 400,000. That is chaos, not a threshold. And every measured claim in this library's comments ("measured over forty starting arrangements…") was established with a harness someone hand-rolled and threw away.

What

tests/ForceDirectedLayout.Tests/Bench/:

• GraphCorpus — four graphs that break a layout differently. Counter is the real twenty-node document with sizes from a 60-wide literal to a 118x180 function; Chain is the shape that most wants to be a horizontal row; FanIn is eight sources arriving at eight pins on one target, which is where crossings come from; MixedSizes alternates 400-wide slabs with 50-wide literals. Node sizes and pin rows are load-bearing — repulsion measures clear space between boxes and every angle force measures between pins, so a graph of equal-sized points exercises none of it.
• LayoutMetrics — settled area, mean edge angle, links drawn across a body they are no end of, tightest and mean clear gap, worst overlap, crossed link pairs, settled. Meant to be read as a row: a collapse into a crushed ribbon flatters both the area and the angle while being the worst outcome available.
• LayoutBench.Run / .Sweep / .Compare / .Table — settles a configuration over several starts, walked from nodes piled on top of each other to nodes flung a thousand units apart, and renders the rows as a fixed-width table. Deterministic, so the difference between two rows is the setting and nothing else.
• LayoutSvg — writes a settled graph to SVG: links first, as the cubic the renderer actually draws, nodes over them, overlapping bodies outlined in red. A link hidden in the picture is a link hidden in the editor. No window, no GPU, no ImGui context.

Iterating is now: add a scratch [TestMethod] that prints a sweep, run the suite, read the column that should have moved.

Console.WriteLine(LayoutBench.Table(LayoutBench.Sweep(
    GraphCorpus.Counter, LayoutSettings.Defaults, "repulsion",
    [300_000, 600_000, 1_200_000],
    (s, v) => s with { RepulsionStrength = v })));

Existing tests moved onto it

ASmallGraph_IsReadableWithinTenSeconds and Repulsion_IsWhatSpreadsAGraphOut were single-start and are now measured over six and eight. Untwisting_ReducesCrossingsWithoutLeavingBodiesOverlapping was already multi-start by hand and gets simpler. Their private helpers — the Counter graph, Shape, LinksOverBodies, WorstOverlap — are deleted in favour of the corpus and the metrics, leaving ForceLayoutTests 156 lines shorter with more starts behind every claim.

It immediately found a real defect

Corpus_SettlesIntoAReadableShape_UnderTheDefaults is the new quality gate. It came up red on first run, and the cause is genuine: centre gravity coils a long chain.

A plain twelve-node chain — the shape that most obviously wants to be a horizontal row — settles at ~53° mean edge angle with only two starts in six reading left to right. It is not settling time; 4000, 12000 and 30000 frames all land on 52.6. Sweeping GravityStrength over the same six starts:

gravity	mean angle	readable
0	0.6°	5/6
10	1.9°	5/6
50 (default)	52.9°	2/6
200	58.4°	0/6

Raising DirectionalBias makes it worse (62.7° at bias 2), because ordering pairs left-to-right says nothing about the shape of the whole. MixedSizes is a chain too and coils the same way.

I have not fixed this — it is a change to gravity, not to this harness, and it wants its own PR and its own judgement call about whether compactness or left-to-right readability wins. The gate's per-graph thresholds are current behaviour with headroom, and the two loose ones carry the evidence above in a comment so nobody mistakes them for targets. Happy to follow up on the gravity side if you want it.

Notes for whoever uses this next

Two things that bite, both documented in CLAUDE.md:

• Console output only renders for tests the runner shows a block for, which by default is failing ones. Pass --show-stdout All --show-test-results all to see a sweep printed by a passing test.
• The analyzers apply to scratch tests too — IDE0005, IDE2001 and IDE0055 are errors here, so a quick { s.X = v; return s; } lambda will not build. Use a with expression.

CLAUDE.md also gains a ForceDirectedLayout library entry, which was missing entirely.

Verification

ForceDirectedLayout.Tests 61/61 (was 43 — the harness adds 12 of its own tests and the ports consolidate the rest), ImGui.NodeEditor.Tests 71/71, NodeGraph.Tests 106/106. Full solution builds clean in Release with no warnings. The whole layout suite still runs in about 2 seconds.

🤖 Generated with Claude Code

https://claude.ai/code/session_018b2bn5CKSzpjRV4nxv3c3y

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud