Run a parameter sweep

ledgr_sweep() evaluates a rectangular strategy grid or a composed ledgr 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

An ordinary rectangular data frame, a ledgr_strategy_grid, or a ledgr_executable_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. Each row keeps its status and completion_json; the columns directly after completion_json are derived from it: stop_reason, affected_instrument_ids, and the valuation flags valuation_state, frozen_instrument_sessions, max_frozen_equity_weight, frozen_at_end_value, and assumed_terminal_outcomes (NA without availability evidence). Print reports attempted, done, incomplete, and failed counts. Only DONE rows enter ranking, filtering, promotion, and validation panels.

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. Feature factories consume the strategy-parameter namespace. 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")