Run a parameter sweep

ledgr_sweep() evaluates a ledgr_param_grid against a ledgr_experiment without writing candidate runs to the experiment store. Sweep is an exploratory surface: it returns candidate summaries, does not rank candidates automatically, and does not create committed run artifacts.

Usage

ledgr_sweep(
  exp,
  param_grid,
  precomputed_features = NULL,
  retain = ledgr_sweep_retention(),
  seed = NULL,
  stop_on_error = FALSE,
  workers = 1L,
  worker_packages = NULL,
  compiled_accounting_model = NULL
)

Arguments

exp

A ledgr_experiment.

param_grid

A ledgr_param_grid.

precomputed_features

Optional ledgr_precomputed_features object.

retain

A ledgr_sweep_retention object. The default keeps the current scalar-only sweep output. Retention metadata is not execution identity.

seed

Optional integer-like master seed. When supplied, each candidate receives a deterministic derived execution seed.

stop_on_error

Logical. When FALSE, candidate-level execution errors are captured as failed rows; when TRUE, they are rethrown.

workers

Whole-number worker count. The default 1 uses the sequential reference path. Values greater than 1 dispatch candidates through the optional mirai backend.

worker_packages

Optional character vector of packages to attach on parallel workers for unqualified package calls in strategy code.

compiled_accounting_model

Optional accounting accelerator selector. NULL uses the canonical R accounting path. "spot_fifo" opts into the scoped spot-asset FIFO accelerator for memory-backed sweep candidates.

Value

A ledgr_sweep_results tibble.

Details

For larger grids, precompute shared feature payloads with ledgr_precompute_features(). When a grid has more than 20 combinations and precomputed_features = NULL, ledgr warns because feature computation may be repeated per candidate.

The result carries row-level execution_seed and provenance. Provenance records what ran, including the candidate feature-set hash; it does not prove that parameter selection was out-of-sample. The normal discipline is to sweep on a train snapshot, select a candidate with ledgr_candidate(), and evaluate the locked params on a held-out test snapshot with ledgr_promote() or ledgr_run(). Same-snapshot promotion is useful for audit and replay, but remains in-sample.

Sweep candidate metrics use the experiment's metric context. The returned table has exactly one sweep-level metric context, available with ledgr_metric_context(results), and promotion context records that source sweep context separately from the committed run's own metric context. Candidate warnings, including LEDGR_LAST_BAR_NO_FILL, are row-level diagnostics. Inspect them before promotion; committed runs expose their own result tables and promotion context. Hash fields in sweep provenance and reproduction keys are summarized in ledgr_identity_fields.

Failed candidates are retained as rows when stop_on_error = FALSE. Contract errors such as invalid grids, invalid precomputed feature payloads, and Tier 3 strategy preflight failures still abort. Compatibility note: old feature-factory experiments use a flat parameter-grid contract. Executable grids with separate feature_params require active aliases through ledgr_feature_map(). Failed rows can be inspected with ledgr_candidate(..., allow_failed = TRUE), but ledgr_promote() rejects failed candidates. When stop_on_error = TRUE rethrows a strategy failure, assert with inherits(e, "ledgr_strategy_error") rather than exact class-vector equality.

Parallel sweep interruption is discard-all in v0.1.8.8. If a parallel sweep is interrupted before all workers return, ledgr stops the worker backend and throws ledgr_parallel_sweep_interrupted; no partially promotable sweep result is returned. Partial-result recovery is intentionally deferred.

Current sweep mode intentionally does not ship automatic ranking, ledgr_tune(), per-fold walk-forward PBO, CPCV, DSR, risk-layer insertion, cost-grid composition, paper/live adapters, intraday-specific support, or full per-candidate committed-run artifacts. Saved sweeps are compact candidate evidence, not batches of committed runs.

Articles

Exploratory sweeps and promotion: vignette("sweeps", package = "ledgr") system.file("doc", "sweeps.html", package = "ledgr") Selection-integrity diagnostics: vignette("selection-integrity", package = "ledgr") system.file("doc", "selection-integrity.html", package = "ledgr")