A TrialLog collects the trial records of an optimizer run (see
create_trial()). Without log_dir it lives in memory. With log_dir it
writes every trial to a JSON Lines journal, trials.jsonl, as it is added,
so a long run can be inspected or resumed later with load_trial_log().
Optimizers create one when you give them a log_dir.
Details
A log directory holds trials.jsonl, the authoritative journal, and three
derived files that are refreshed after each change: metadata.json,
README.md (a readable summary) and best_program.rds (the best trial's
program, when recorded). The derived files can lag behind after an
interruption; the next successful save rebuilds them. Existing records in
log_dir are loaded when the log is created. Adding a trial whose ID is
already present is a no-op when the records match and an error when they
differ.
File permissions
Logs are private to the current user. On Unix, an existing log directory
must be owned by the effective user with mode 0700, existing log files
must have mode 0600 without special bits, and every existing parent
directory must be owned by root or the effective user. Paths that break
these rules, and symbolic links, are rejected without being read or
repaired. New directories and files are created owner-only. On Windows,
where base R cannot verify owner-only access, the account's filesystem ACLs
apply, and logging fails if stable file identifiers are unavailable.
See also
Other optimizer building blocks:
complete_trial(),
create_trial(),
eval_program(),
load_trial_log(),
optimizer_control(),
read_trials_jsonl(),
sample_dataset(),
split_dataset(),
write_trials_jsonl()
Public fields
optimizer_nameName of the optimizer using this log.
log_dirDirectory for persistence (NULL for in-memory only).
trialsList of optimization trial records.
metadataAdditional metadata about the optimization run.
Methods
TrialLog$new()
Create or resume a TrialLog. Existing JSONL records are loaded without rewriting the file.
Usage
TrialLog$new(optimizer_name, log_dir = NULL, metadata = NULL)TrialLog$add_trial()
Add a trial to the log. Persisted trials atomically append one authoritative JSONL record. Derived metadata, summaries, and the best program are then refreshed independently on a best-effort basis.
Arguments
trialA trial record created by
create_trial().persistWhether to immediately persist to disk if log_dir is set.
TrialLog$save()
Save the trial log to disk. Only records missing from the destination are appended to the authoritative journal. Derived files are independently refreshed on a best-effort basis and may lag if that refresh warns.
Examples
log <- TrialLog$new("my-search")
log$add_trial(create_trial("my-search", params = list(k = 2L)))
log$add_trial(create_trial("my-search", params = list(k = 4L)))
log$n_trials()
#> [1] 2
log$as_tibble()[, c("trial_id", "status", "mean_score")]
#> # A tibble: 2 × 3
#> trial_id status mean_score
#> <chr> <chr> <dbl>
#> 1 trial_20260930_174348_ncnyz0 pending NA
#> 2 trial_20260930_174348_e01i28 pending NA
# Persist to a directory and load it again
dir <- file.path(tempdir(), "trial-log-example")
saved <- TrialLog$new("my-search", log_dir = dir)
saved$add_trial(create_trial("my-search", params = list(k = 2L)))
list.files(dir)
#> [1] "README.md" "metadata.json" "trials.jsonl"
load_trial_log(dir)
#>
#> ── Trial Log: my-search
#> Trials: 1 (0 completed, 0 failed)
#> Log Dir: /tmp/Rtmp4xxnp9/trial-log-example