Report Analysis

Analyze force-field optimization report artifacts and derived fit summaries.

This module parses report-oriented optimization outputs, including EOS and bulk-modulus related records, into analyzer-ready tables. It is scoped to report extraction and derived fit metrics, not parameter optimization itself.

Usage context

• Report parsing: Normalize textual optimization-report sections into tables.
• EOS analysis: Build equation-of-state fit inputs and summary outputs.
• Materials metrics: Compute report-level bulk-modulus-related diagnostics.

Request: FFieldOptimizationReportRequest

Request payload for optimization-report table extraction.

This request configures the base optimization-report analyzer. The current task returns all parsed report rows and does not expose request-time filtering parameters.

Fields

Field	Type	Default	Help	Choices

Examples

request = ForceFieldOptimizationReportRequest()

The request returns the full parsed report table.

Task: FFieldOptimizationReportTask

Return the parsed optimization-report table with QM-FF differences.

Method: recommended_presentations(_result: FFieldOptimizationReportResult, payload: dict[str, Any])

Recommend table and QM-FF difference plot views for report output.

Returns a table view by default and adds a line/scatter-style plot when serialized rows expose lineno and qm_ff_difference columns.

Works on Analyzer task output for force_field_optimization_report.

Parameters

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

Returns

Type	Description
list[PresentationSpec]	Recommended presentation specifications for UI rendering.

Examples

specs = ForceFieldOptimizationReportTask.recommended_presentations(
    _result,
    {"table": [{"lineno": 12, "qm_ff_difference": 0.5}]},
)

The returned list includes a table and a qm_ff_difference plot.

Method: run(data: ForceFieldOptimizationReportData, request: FFieldOptimizationReportRequest, reporter=None)

Run base optimization-report extraction and difference computation.

Converts parsed report rows into a normalized table and augments each row with a QM-minus-force-field difference metric.

Works on ForceFieldOptimizationReportData.

Parameters

Name	Type	Description
data	ForceFieldOptimizationReportData	Parsed optimization-report data source.
request	FFieldOptimizationReportRequest	Request object for the analysis task.
reporter	Any, optional	Progress callback accepted by analyzer tasks; unused here.

Returns

Type	Description
FFieldOptimizationReportResult	Result containing the normalized report table.

Examples

result = ForceFieldOptimizationReportTask().run(
    data,
    ForceFieldOptimizationReportRequest(),
)

The result table includes qm_ff_difference for each report row.

Result: FFieldOptimizationReportResult

Result payload containing parsed optimization-report rows.

The analyzer returns normalized report records and a derived qm_ff_difference metric to simplify review of model-vs-reference gaps.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	FFieldOptimizationReportRequest

Examples

row = {
    "lineno": 12,
    "section": "ENERGY",
    "ffield_value": 11.9,
    "qm_value": 12.4,
    "qm_ff_difference": 0.5,
}

qm_ff_difference is computed as qm_value - ffield_value.

Request: FFieldOptimizationReportEOSRequest

Request payload for EOS table extraction from report artifacts.

This request optionally filters the derived base/other energy-volume table by one base identifier.

Fields

Field	Type	Default	Help	Choices
iden	Optional[str]		Optional identifier filter for base_iden. Example: 'MgO'. Use 'all' or None to keep all identifiers.

Examples

request = ForceFieldOptimizationReportEOSRequest(iden="bulk_0")

The request returns EOS rows only for base_iden == "bulk_0".

Task: FFieldOptimizationReportEOSTask

Return ENERGY-vs-volume data derived from report + geometry summary.

Method: recommended_presentations(_result: FFieldOptimizationReportEOSResult, payload: dict[str, Any])

Recommend table and energy-vs-volume presentations for EOS output.

Provides a table for all outputs and adds an EOS plot when V_other_iden and E_other_iden columns are available.

Works on Analyzer task output for force_field_optimization_report_eos.

Parameters

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

Returns

Type	Description
list[PresentationSpec]	Recommended specs for EOS table and plot rendering.

Examples

specs = ForceFieldOptimizationReportEOSTask.recommended_presentations(
    _result,
    {"table": [{"base_iden": "bulk_0", "V_other_iden": 10.0, "E_other_iden": -120.0}]},
)

The output includes a table and an energy-vs-volume plot.

Method: run(data: ForceFieldOptimizationReportEOSBundleData, request: FFieldOptimizationReportEOSRequest, reporter=None)

Run EOS table extraction from report and geometry summary bundles.

Builds the base/other energy-volume table and optionally filters it by one base identifier from the request.

Works on ForceFieldOptimizationReportEOSBundleData.

Parameters

Name	Type	Description
data	ForceFieldOptimizationReportEOSBundleData	Bundle with parsed report rows and geometry summary values.
request	FFieldOptimizationReportEOSRequest	Optional identifier filter for EOS table scope.
reporter	Any, optional	Progress callback accepted by analyzer tasks; unused here.

Returns

Type	Description
FFieldOptimizationReportEOSResult	Result containing EOS-compatible energy-volume rows.

Examples

result = ForceFieldOptimizationReportEOSTask().run(
    data,
    ForceFieldOptimizationReportEOSRequest(iden="all"),
)

The output table includes all eligible base-identifier EOS rows.

Result: FFieldOptimizationReportEOSResult

Result payload containing EOS-compatible energy-volume rows.

The analyzer joins repeated report identifiers with geometry summary values to produce per-base equation-of-state inputs.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	FFieldOptimizationReportEOSRequest

Examples

rows = [
    {"base_iden": "bulk_0", "other_iden": "bulk_1", "V_other_iden": 10.0, "E_other_iden": -120.0},
    {"base_iden": "bulk_0", "other_iden": "bulk_0", "V_other_iden": 9.0, "E_other_iden": -90.0},
]

Each row is one point in a base-identifier EOS series.

Request: FFieldOptimizationReportBulkModulusRequest

Request payload for Vinet bulk-modulus fitting from EOS rows.

This request controls optional base filtering and fitting options used to derive equilibrium and bulk-modulus parameters from energy-volume data.

Fields

Field	Type	Default	Help	Choices
iden	Optional[str]		Optional base_iden filter. Example: 'bulk_0'. Use 'all' or None to evaluate all eligible base identifiers.
shift_min_to_zero	bool	True	If true, shift each fitted energy series so its minimum is zero before EOS fitting.	True, False
flip_sign	bool	False	If true, multiply energies by -1 before fitting.	True, False
min_points	int	6	Minimum number of finite (V_other_iden, E_other_iden) rows needed to fit one base_iden series.

Examples

request = ForceFieldOptimizationReportBulkModulusRequest(
    iden="bulk_0",
    shift_min_to_zero=True,
    flip_sign=False,
    min_points=6,
)

The request fits one selected base EOS series using standard defaults.

Task: FFieldOptimizationReportBulkModulusTask

Return a Vinet bulk-modulus fit derived from report + geometry summary.

Method: recommended_presentations(_result: FFieldOptimizationReportBulkModulusResult, payload: dict[str, Any])

Recommend table and bulk-modulus summary plot presentations.

Returns a table view by default and adds a K0_GPa plot keyed by base_iden when those fields are present in serialized rows.

Works on Analyzer task output for force_field_optimization_report_bulk_modulus.

Parameters

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

Returns

Type	Description
list[PresentationSpec]	Recommended presentation specifications for fit summaries.

Examples

specs = ForceFieldOptimizationReportBulkModulusTask.recommended_presentations(
    _result,
    {"table": [{"base_iden": "bulk_0", "K0_GPa": 76.9}]},
)

The returned specs include a table and one bulk-modulus comparison plot.

Method: run(data: ForceFieldOptimizationReportEOSBundleData, request: FFieldOptimizationReportBulkModulusRequest, reporter=None)

Run bulk-modulus fitting on EOS rows derived from report artifacts.

Derives EOS rows from report and geometry summary data, applies request fit options, and returns one fit summary row per eligible base series.

Works on ForceFieldOptimizationReportEOSBundleData.

Parameters

Name	Type	Description
data	ForceFieldOptimizationReportEOSBundleData	Bundle with report and geometry summary inputs for EOS derivation.
request	FFieldOptimizationReportBulkModulusRequest	Fit configuration and optional identifier filter.
reporter	Any, optional	Progress callback accepted by analyzer tasks; unused here.

Returns

Type	Description
FFieldOptimizationReportBulkModulusResult	Result containing Vinet fit parameters per base identifier.

Examples

result = ForceFieldOptimizationReportBulkModulusTask().run(
    data,
    ForceFieldOptimizationReportBulkModulusRequest(min_points=6),
)

The output table includes one row per successful bulk-modulus fit.

Result: FFieldOptimizationReportBulkModulusResult

Result payload for EOS-derived bulk-modulus fitting.

The analyzer returns one row per successfully fitted base identifier, including equilibrium volume and bulk modulus in multiple units.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	FFieldOptimizationReportBulkModulusRequest

Examples

row = {
    "base_iden": "bulk_0",
    "n_points": 8,
    "V0_A3": 11.2,
    "K0_GPa": 76.9,
    "success": True,
}

The row indicates a successful Vinet fit for one base EOS series.