`random_initialisation` semantics are undocumented and partly undecided

[rogerssam]

The only user-facing description of random_initialisation is one sentence in ?optim_params:

Number of times to randomly shuffle items within swap_within; the design with the best score is used as an initial design (default: 0).

Checked against the behaviour, that sentence is either silent on or wrong about every non-obvious thing the argument does.

Undecided: is the input a candidate?

random_initialise() starts with best_score <- Inf, so the first shuffle always replaces the input and the input never competes. With a 4x4 Latin square input (score 0, optimal) and random_initialisation = 3, the search is handed a design scoring 6.67 and ends at 2.67 — worse than what the user supplied, where with no random initialisation speed() recognises the optimum at iteration 1.

"the design with the best score is used" reads as though the input competes. Either randomisation is the point and the exclusion is deliberate — in which case say so — or it should be best-of-(N+1) and best_score should start at the input's score. This is the same question #89 has to answer before it can auto-trigger anything, and it points the opposite way from #139, where the search privileges the starting design among tied-scoring ones. Worth deciding the rule once for both.

Undocumented

• TRUE means 1. Accepted by .verify_optim_params(), used in ?speed, three vignettes and six tests, documented nowhere.
• The shuffle is not "within swap_within" for hierarchical designs — it is within the intersection of that level's group and every earlier level's. Mentioned only in NEWS 0.0.6, in no .Rd or vignette. (See random_initialise() builds its own grouping for hierarchical levels, unlike the search #142, which proposes removing that behaviour rather than documenting it.)
• It is a design-wide setting read from level 1, though optimise_params is otherwise presented as a per-level override. (See random_initialise() seed handling and parameter resolution #143.)
• Its interaction with swap_all — currently destructive, see random_initialisation destroys nesting in swap_all = TRUE designs #141.

Validation tidy

.verify_optim_params() tests random_initialisation %in% c(TRUE, FALSE). %in% coerces both sides to character, so the strings "TRUE" and "FALSE" match and skip verify_non_negative_whole(), then fail later with NAs introduced by coercion. optim_params(random_initialisation = NULL) gives a bare argument is of length zero rather than the package's own message. Neither input is realistic, but isTRUE(x) || isFALSE(x) is the correct test and costs nothing.

Test coverage

No test calls random_initialise() or shuffle_items() directly, and none combines random_initialisation with swap_all = TRUE. Of the seven tests that set it, only one (test-speed.R:2395) asserts anything about the shuffle itself, and only that the starting score improved. That is why every defect in #141, #142 and #143 went unnoticed.

Worth adding, alongside whichever fixes land: the multiset per group is preserved at each level; units stay intact under swap_all; missing plots do not move; a fresh session with no seed works; a partial optimise_params works.