Skip to content

Optimization Progress Analysis

Provide analyzer tasks for force-field optimization progress data.

This module extracts epoch-level optimization metrics and structured progress tables from optimization logs. It is scoped to progress/error-series analysis and does not generate final optimization reports.

Usage context

  • Training monitoring: Track optimization error across epochs.
  • Subset analysis: Slice progress by selected epoch ranges.
  • Plotting/reporting: Feed normalized progress tables into visual summaries.

Request: FFieldOptimizationProgressRequest

Request payload for optimization-progress extraction.

This request optionally filters the optimization progression table to a selected subset of epochs while preserving epoch ordering.

Fields

Field Type Default Help Choices
epochs Optional[Sequence[int]] Optional optimization epochs to include. Example: [1, 5, 10]. If omitted, all available epochs are returned.

Examples

request = ForceFieldOptimizationRequest(epochs=[1, 5, 10])

The request keeps only epochs 1, 5, and 10 in the output table.

Task: FFieldOptimizationProgressTask

Return total force-field error versus optimization epoch.

Suggest default table/plot renderers for optimization progress output.

Returns a tabular view for all outputs and adds an error-vs-epoch plot when the serialized table contains the expected numeric columns.

Works on Analyzer task output for force_field_optimization.

Parameters

Name Type Description
_result FFieldOptimizationProgressResult Typed analyzer result instance (unused by current logic).
payload dict[str, Any] Serialized analyzer payload expected to include table rows.

Returns

Type Description
list[PresentationSpec] Presentation specs appropriate for UI rendering.

Examples

specs = ForceFieldOptimizationTask.recommended_presentations(
    _result,
    {"table": [{"epoch": 1, "total_ff_error": 15324.4}]},
)

The returned specs include a table and a total_ff_error vs epoch plot.

Method: run(data: ForceFieldOptimizationProgressData, request: FFieldOptimizationProgressRequest, reporter=None)

Run the optimization-progress analyzer task.

Extracts epoch/error rows from parsed optimization progress data, applies optional epoch filtering, and returns a typed result payload.

Works on ForceFieldOptimizationProgressData parsed from optimization logs.

Parameters

Name Type Description
data ForceFieldOptimizationProgressData Parsed optimization progress record source.
request FFieldOptimizationProgressRequest Request containing optional epoch filters.
reporter Any, optional Progress callback accepted by the task interface; unused here.

Returns

Type Description
FFieldOptimizationProgressResult Analyzer result with the normalized progress table.

Examples

task = ForceFieldOptimizationTask()
result = task.run(data, ForceFieldOptimizationRequest(epochs=[1, 2, 3]))

The output table contains only the requested epochs when available.

Result: FFieldOptimizationProgressResult

Result payload for optimization-progress analysis.

The analyzer returns an epoch-indexed error trajectory suitable for trend inspection, convergence diagnostics, and downstream plotting.

Fields

Field Type Default Help Choices
table pd.DataFrame
request FFieldOptimizationProgressRequest

Examples

rows = [
    {"epoch": 1, "total_ff_error": 15324.4},
    {"epoch": 2, "total_ff_error": 14980.1},
]

Each row records model error at one optimization epoch.