Trial Log — TrialLog • dsprrr

R6 class for managing a collection of trials with optional persistence. Existing JSONL records are loaded when log_dir already contains a log. New trials are appended one record at a time; matching trial IDs are idempotent, while conflicting records with the same ID are rejected. The trials.jsonl journal is authoritative. metadata.json, README.md, and best_program.rds are independently refreshed, best-effort derived views; they may lag after an interruption and are rebuilt by a later successful save. Persistent Unix logs require an effective-user-owned directory with a safe parent chain and reject symbolic-link targets; Windows uses the account's filesystem ACLs, which base R cannot verify as owner-only, and fails closed if stable device and file identifiers are unavailable.

Public fields

optimizer_name: Name of the optimizer using this log.
log_dir: Directory for persistence (NULL for in-memory only).
trials: List of Trial objects.
metadata: Additional 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)

Arguments

optimizer_name: Name of the optimizer.
log_dir: Optional directory for persistence.
metadata: Optional metadata list.

`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.

Usage

TrialLog$add_trial(trial, persist = TRUE)

Arguments

trial: A Trial object.
persist: Whether to immediately persist to disk if log_dir is set.

`TrialLog$n_trials()`

Get the number of trials.

Usage

TrialLog$n_trials()

Returns

Integer count of trials.

`TrialLog$as_tibble()`

Get trials as a tibble.

Usage

TrialLog$as_tibble()

Returns

A tibble with one row per trial.

`TrialLog$best_trial()`

Get the best trial by score.

Usage

TrialLog$best_trial(objective = "maximize")

Arguments

objective: "maximize" or "minimize".

Returns

The best Trial object, or NULL if no completed trials.

`TrialLog$summary()`

Get summary statistics for all trials.

Usage

TrialLog$summary()

Returns

A list with summary statistics.

`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.

Usage

TrialLog$save(dir = NULL)

Arguments

dir: Optional directory override.

Returns

Invisibly returns self. Throws error on critical failure.

`TrialLog$print()`

Print the trial log summary.

Usage

TrialLog$print()

`TrialLog$clone()`

The objects of this class are cloneable with this method.

Usage

TrialLog$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.