FileLogger#

class lumopt2.utils.file_logger.FileLogger(log_file: str | None = None, log_params: bool = True, log_gradients: bool = True, max_logged_params: int | None = 10000)#

Record the numerical history of one optimization run to a text file.

This callback is a data record, not a progress log. Each evaluation and each iteration is written as a single line containing the FOM value, the parameter vector, optionally the gradient, and the elapsed wall time. The resulting file is intended for plotting, post-hoc inspection, and debugging – not for human-readable status updates (which are handled by the standard lumopt2 module logger / console).

The two streams are orthogonal: FileLogger writes dense per-eval numerical data to its own file, while Optimization.run emits high-level progress messages through logging.getLogger("lumopt2"). The only message FileLogger itself emits through the module logger is a single "Optimization data log: <path>" info line at the start of the run, so the user knows where the data file lives. All other output – banners, eval rows, iteration rows, gradient rows, the final summary – goes only to log_file.

Parameters:
log_filestr, optional

Path to the output file. If None, automatically saves as optimization.log in the project folder (default: None).

log_paramsbool, optional

If True, include the parameter vector on every evaluation / iteration row (default: True). Disable to keep the file compact when parameter vectors are very large and only the FOM trajectory is of interest.

log_gradientsbool, optional

If True, append a # Gradient: |grad|=..., [...] row after each iteration whose callback receives a gradient (default: True). Set to False to omit gradients for gradient-free optimizers or when the data file should stay small.

max_logged_paramsint or None, optional

Maximum parameter-vector length for which values are logged verbatim in per-evaluation rows, per-iteration rows, and the final parameter summary block (default: 10000). If a vector is longer than this threshold, the logger writes a compact “omitted” marker instead of the full array to avoid excessive file I/O and oversized logs. Set to None to disable the limit and always log full vectors.

See also

JSONLogger

Same data, but stored in a structured JSON format that is easier to load programmatically for benchmarking or comparison.

Notes

The file starts with a header banner that captures the run’s metadata (timestamp, parameter count, bounds), followed by one row per FDTD evaluation:

1eval    1, 0.421000, 12.34s, [ 1.000e-06  2.000e-06]

and one row per optimizer iteration:

1ITER    3, 0.756000, [ 1.234e-06  5.678e-06]

A trailing summary banner records the final FOM, iteration count, and full final parameter vector at full precision so the values can be copied back as initial_params for a follow-up run.

Examples

Default: write optimization.log into the project folder:

1file_logger = FileLogger()
2opt = Optimization(project, optimizer, callbacks=[file_logger])
3result = opt.run()

Or specify a custom path explicitly:

1file_logger = FileLogger(log_file="/path/to/run_history.txt")
2opt = Optimization(project, optimizer, callbacks=[file_logger])
3result = opt.run()

Methods

FileLogger.close()

Close the underlying log-file handle if one is open.

FileLogger.on_function_eval(project, ...[, ...])

Record one evaluation row in the data file.

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

Record one iteration-completion row in the data file.

FileLogger.on_iteration_start(iteration, ...)

No-op; iteration starts are intentionally silent.

FileLogger.on_optimization_end(success, ...)

Write the final summary banner and close the data file.

FileLogger.on_optimization_start(project, ...)

Write the run-header banner and resolve the output file path.
On this page