[HugoFara]

The benchmarks page told users the wrong thing about path_generation(), and I wrote it. Profiling for #29 shows both of its claims are false.

What it said

It searches over n_orientation_samples candidate orientations (36 by default) and runs Burmester synthesis for each, which is why it costs well over a second.

If you need it faster, lowering n_orientation_samples trades solution coverage for time roughly linearly.

What is actually true

Verification dominates, not search. Simulating each surviving candidate through _verify_coupler_path is 67% of the runtime; Burmester synthesis is 21%.

n_orientation_samples is close to inert. It feeds:

per_axis = max(6, int(round(n_samples ** (1.0 / free))))

With 4 precision points free = 3, so n_samples**(1/3) stays under 6 for every value up to 216 — the floor swallows the parameter. Its only other use is a cap of n_samples * n_samples, a quadratic cap on a grid of size 6**free.

n_orientation_samples	README points	benchmark points
6	338 ms, 10 solutions	511 ms, 0 solutions
12	340 ms, 10 solutions	1668 ms, 10 solutions
36 (default)	336 ms, 10 solutions	1676 ms, 10 solutions
72	337 ms, 10 solutions	1679 ms, 10 solutions

Lowering it does not buy time. It eventually just returns nothing.

max_solutions is the real control, since the search stops once it has that many verified solutions:

max_solutions	Time	Solutions
1	124 ms	1
10 (default)	338 ms	10
20	1181 ms	20
None	2316 ms	79

Cost depends on which points you ask for. Two four-point problems, both returning ten solutions: 336 ms for the README's points, 1676 ms for the benchmark's. The headline table reports the slower one, so the page now frames it as an upper bound rather than a typical figure.

Changes

• docs/source/benchmarks.md: replaces the wrong explanation with a breakdown of where the time goes, the max_solutions table, the point-set sensitivity, and a note that n_orientation_samples is not a working control.
• path_generation() docstring: says verification dominates, points users at max_solutions, and warns that n_orientation_samples is a weak control.

This documents current behaviour only. Whether n_orientation_samples should be repaired or removed is a decision for #29 — as is the fact that switching verification to step_fast() would collapse that 67%, which is blocked on #40.