JSONLogger#

class lumopt2.utils.file_logger.JSONLogger(problem_name: str | None = None, optimizer_name: str | None = None, budget_multiplier: int | None = None, log_dir: str | None = None)#

Record the structured numerical history of an optimization run as JSON.

This callback is a machine-readable data record, not a progress log – the JSON output is intended to be loaded back into Python (or a notebook, or a benchmark aggregator) for plotting, comparison, and post-hoc analysis. Like FileLogger, it is orthogonal to the standard lumopt2 module logger: progress messages still go through logging, and the data file produced here contains only numerical artefacts.

Parameters:
problem_namestr, optional

Identifier for the benchmark problem. Stored verbatim in the JSON and useful when the same script runs multiple problems.

optimizer_namestr, optional

Short optimizer label used in the output filename (default "optimizer" when unset).

budget_multiplierint, optional

Budget multiplier used in the output filename (default "auto" when unset).

log_dirstr, optional

Directory to save the JSON file. If None, the project folder is used when available; otherwise a timestamped name is dropped in the current working directory.

See also

FileLogger

Same data, but as a plain-text optimization.log that is easier to read directly with less/grep and which appends a human-readable banner.

Notes

Each run produces one JSON file with the following top-level keys:

  • problem, optimizer, dimensions, budget_multiplier – run metadata supplied at construction time.

  • success, num_iterations, final_fom – final outcome.

  • initial_fom, improvement, pct_improvement – present when Optimization.run provides the baseline FOM.

  • fom_history – one FOM value per evaluation.

  • param_history – one parameter vector per evaluation.

  • eval_times – wall-clock seconds per evaluation.

  • grad_eval_history – the cumulative adjoint count at each evaluation (so consumers can plot FOM vs. number of adjoint passes, not just FOM vs. evaluation index). Entries are 0 for evals that did not trigger an adjoint.

  • early_exit (and, on early exit, early_exit_reason / early_exit_timestamp) – crash-recovery metadata.

The default filename pattern is <optimizer>_<dimensions>Dx<budget>_history.json so multiple runs in the same directory can be collected programmatically by glob. Existing files are never overwritten – collisions get a numeric suffix (..._history_0001.json, ..._history_0002.json, …).

Methods

JSONLogger.on_function_eval(project, ...)

Append one evaluation record to the in-memory history.

JSONLogger.on_iteration_end(project, ...[, ...])

No-op; per-eval entries already capture the same information.

JSONLogger.on_iteration_start(iteration, ...)

No-op; iteration boundaries are not separately recorded in JSON.

JSONLogger.on_optimization_end(success, ...)

Flush the in-memory history to disk as a JSON document.

JSONLogger.on_optimization_start(project, ...)

Resolve the JSON output path and reset the in-memory history.

JSONLogger.save_early_exit([reason])

Save partial optimization history to disk with early_exit flag.
On this page