Skip to content

Diagnostics Analysis

Analyze parameter-optimization diagnostics in an engine-agnostic format.

This module extracts and normalizes optimization-diagnostic records, including parameter-change signals and section-aware summaries used during force-field tuning. It is scoped to diagnostic artifacts and does not mutate force-field parameters.

When using Standalone ReaxFF for force field optimization, this data will be available in 'fort.79' output file.

Usage context

  • Optimization debugging: Inspect parameter update behavior across iterations.
  • Section diagnostics: Break down signals by force-field parameter sections.
  • QA reporting: Export normalized diagnostic tables for review dashboards.

Request: FFieldOptimizationDiagnosticRequest

Request payload for optimization diagnostics analysis.

This request controls whether parsed diagnostic identifiers are returned as raw values or interpreted into section/parameter metadata using force-field parameter tables from the same analysis bundle.

Fields

Field Type Default Help Choices
interpret bool False If true, interpret identifier triplets (section, line, parameter) into descriptive force-field parameter names using loaded force-field data. True, False

Examples

request = ParameterOptimizationDiagnosticRequest(interpret=True)

The request asks for interpreted identifier metadata in the output table.

Task: FFieldOptimizationDiagnosticTask

Return sensitivity diagnostics derived from parameter-update diagnostics.

Recommend table and sensitivity plot views for diagnostics output.

Produces a table view for all outputs and adds a default min_sensitivity vs identifier plot when required columns exist.

Works on Analyzer task output for parameter_optimization_diagnostic.

Parameters

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

Returns

Type Description
list[PresentationSpec] Recommended renderer specifications for diagnostics outputs.

Examples

specs = ParameterOptimizationDiagnosticTask.recommended_presentations(
    _result,
    {"table": [{"identifier": "3 12 4", "min_sensitivity": 0.5}]},
)

The returned list includes a table and a one-series sensitivity plot.

Method: run(data: ForceFieldOptimizationDiagnosticBundleData, request: FFieldOptimizationDiagnosticRequest, reporter=None)

Run diagnostics analysis and optional identifier interpretation.

Builds the sensitivity-augmented diagnostics table from parsed optimization diagnostics and, when requested, enriches identifiers using parsed force-field parameter data from the same bundle.

Works on ForceFieldOptimizationDiagnosticBundleData.

Parameters

Name Type Description
data ForceFieldOptimizationDiagnosticBundleData Bundle containing diagnostics and force-field parameter records.
request FFieldOptimizationDiagnosticRequest Request controlling identifier interpretation.
reporter Any, optional Progress callback accepted by the analyzer interface; unused here.

Returns

Type Description
FFieldOptimizationDiagnosticResult Result containing raw/derived diagnostics and optional metadata.

Examples

result = ParameterOptimizationDiagnosticTask().run(
    data,
    ParameterOptimizationDiagnosticRequest(interpret=False),
)

The output contains sensitivity columns for each diagnostics row.

Result: FFieldOptimizationDiagnosticResult

Result payload for parameter-optimization diagnostics.

The analyzer returns raw diagnostic values plus derived sensitivity ratios, with optional interpreted force-field identifier metadata when requested.

Fields

Field Type Default Help Choices
table pd.DataFrame
request FFieldOptimizationDiagnosticRequest

Notes

Sensitivity ratios are computed as diff1/diff3, diff2/diff3, and diff4/diff3 after coercion to numeric values; zero diff3 values are treated as missing to avoid division-by-zero artifacts.

Examples

row = {
    "identifier": "3 12 4",
    "sensitivity1/3": 0.8,
    "sensitivity2/3": 1.2,
    "sensitivity4/3": 0.5,
    "min_sensitivity": 0.5,
    "max_sensitivity": 1.2,
}

min_sensitivity and max_sensitivity summarize each row's ratio span.