Let netsim_scenarios() cycle a vector of restart paths across batches

[smjenness]

netsim_scenarios() and step_tmpl_netsim_scenarios() take a single path_to_x, so every replicate of every scenario reinitializes from the same saved state. That state's deviation is common to all replicates, so it is inherited as bias rather than averaged away, and adding replicates does not touch it.

Measured in EpiModel/LA-PrEP-2026 over 45 restart draws: at 250 replicates, restart-driven error in gonorrhea incidence is 8.23% against 0.57% from replication. Spreading the same replicate budget over several restarts is the largest error reduction available and it costs nothing: 8.23% at one restart, 4.12% at four, 2.06% at sixteen.

Today that needs either J separate workflow steps writing into J output directories, or a step_tmpl_map() fan-out. Both work and both are awkward to read back.

Proposed change: let path_to_x take a character vector and cycle it deterministically by batch, so batch b uses path_to_x[(b - 1) %% J + 1].

The determinism is the part that matters. Projects that pair arms under common random numbers need batch b of every scenario to share a restart as well as a seed, or the pairing breaks and every contrast gets noisier. A fixed cycle on the batch index gives that. Anything sampled per scenario does not.

Evidence: plan/calibration-restart-recommendations.md in EpiModel/LA-PrEP-2026.

The diagnostic that would have caught this before the calibration is EpiModel/EpiModelHIV-Template#62.

[smjenness]

Follow-up. EpiModel/EMH-Calib-Tests experiment A (burnladder) is generating the restart pools this would cycle over, and will quantify how much cycling buys at each burn-in age rather than only at the current one.

Worth adding to the design here: the gain from cycling depends on how wide the pool is, and the pool's width is a function of the burn-in that produced it. If a longer burn-in narrows it substantially, the value of this feature changes, and it is better to know that before building it. The measurement lands with that campaign.

The determinism requirement in the issue body is unchanged and is the part not to compromise on.

[smjenness]

Follow-up, and it answers the open design question from the previous comment.

The concern raised there was that the value of cycling depends on how wide the restart pool is, that the width is a function of the burn-in that produced it, and that a longer burn-in might narrow the pool enough to change whether this feature is worth building. EpiModel/EMH-Calib-Tests experiment A measured it directly with matched pools of 128 restarts at 70, 120 and 200 years.

A longer burn-in does not narrow the pool. Sixteen of seventeen targets show no meaningful reduction in production between-restart CV going from a 70-year to a 200-year burn-in, and several get slightly wider: cc.vsupp.H worsens by 16%, cc.vsupp.W by 11%. Counting targets above a 2% between-restart CV gives six at 70 years and seven at 200. The pool's width is a property of the model at equilibrium rather than an artifact of an unfinished burn-in, so the value of this feature is not sensitive to the burn-in age a project happens to use. That removes the reason to wait.

How many paths to cycle. Decomposing production spread into the part attributable to the restart and the part generated during the run, then averaging over targets, gives an expected proposal-run error of 2.05% at one restart, 1.55% at four, 1.41% at eight and 1.15% at the full 128. Eight captures about two-thirds of the available reduction and there is little past sixteen, so a path_to_x vector of length 8 is a sensible default to document alongside the feature. The original gonorrhea-specific figures in the issue body are corroborated: this campaign puts ir100.gono at 6.81% restart-driven against the 8.23% measured on the LA-PrEP-2026 ensemble.

One thing to note in the implementation. There is a floor at about 1.06%, which is the pool center's own distance from target and is not reducible by cycling. Worth saying in the documentation so the feature is not oversold: it removes the draw-to-draw component, not the systematic one.

The deterministic-cycle requirement in the proposal above is unchanged and still the part that matters for paired designs.

Evidence: data/output/burnladder/ in EpiModel/EMH-Calib-Tests.