Trainset Analysis

Analyze parsed force-field training-set sections as structured task outputs.

This module exposes analyzer tasks for training-set records, including section-based extraction and comment grouping for optimization diagnostics. It is limited to already-parsed training-set content and does not parse raw trainset files directly.

Usage context

• Dataset inspection: Extract task-relevant rows from trainset sections.
• Comment analysis: Group and review training-set annotations.
• Optimization support: Supply curated trainset tables to report pipelines.

Request: TrainsetDataRequest

Request payload for trainset row extraction.

This request selects a single trainset section or all supported sections from parsed training-set data for tabular output.

Fields

Field	Type	Default	Help	Choices
section	str	all	Trainset section to return. Use 'all' to merge all sections with a leading 'section' column. Examples: 'energy', 'geometry', 'cell_parameters'.	all, charge, heatfo, geometry, cell_parameters, energy

Examples

request = GetTrainsetDataRequest(section="energy")

The request returns only ENERGY-section rows.

Task: TrainsetDataTask

Return trainset rows for one section or all sections.

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

Recommend table and fallback plot views for trainset row outputs.

Always emits a table view and adds a simple plot based on detected numeric columns and standard trainset axis fields.

Works on Analyzer task output for trainset_data.

Parameters

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

Returns

Type	Description
list[PresentationSpec]	Recommended presentation specs for trainset tables.

Examples

specs = GetTrainsetDataTask.recommended_presentations(
    _result,
    {"table": [{"section": "energy", "line_number": 142, "lit": -15.4}]},
)

The returned specs include a table and a default numeric plot.

Method: run(data: ForceFieldOptimizationTrainingSetData, request: TrainsetDataRequest, reporter=None)

Run trainset section extraction for the requested scope.

Resolves the section selector, materializes either one section table or a concatenated all-section table, and returns a typed analyzer result.

Works on ForceFieldOptimizationTrainingSetData.

Parameters

Name	Type	Description
data	ForceFieldOptimizationTrainingSetData	Parsed trainset data bundle.
request	TrainsetDataRequest	Request with section selector.
reporter	Any, optional	Progress callback accepted by analyzer tasks; unused here.

Returns

Type	Description
TrainsetDataResult	Result containing the extracted trainset table.

Examples

result = GetTrainsetDataTask().run(data, GetTrainsetDataRequest(section="all"))

The returned table contains all supported sections with a section label.

Result: TrainsetDataResult

Result payload for trainset section extraction.

The analyzer returns trainset rows for the requested scope as a normalized DataFrame suitable for table/plot rendering.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	TrainsetDataRequest

Notes

Column schemas vary by section because each trainset block has distinct row fields.

Examples

row = {
    "section": "energy",
    "line_number": 142,
    "op1": "+",
    "id1": "bulk_1",
    "n1": 1.0,
    "lit": -15.4,
}

The sample row illustrates one ENERGY entry in an all-sections output.

Request: TrainsetGroupCommentsRequest

Request payload for unique trainset group-comment extraction.

This request selects one trainset section or all sections when collecting unique non-empty group_comment annotations.

Fields

Field	Type	Default	Help	Choices
section	str	all	Trainset section to return comments for. Use 'all' for all sections. Examples: 'energy', 'geometry', 'cell_parameters'.	all, charge, heatfo, geometry, cell_parameters, energy

Examples

request = TrainsetGroupCommentsRequest(section="geometry")

The request limits comment extraction to GEOMETRY rows.

Task: TrainsetGroupCommentsTask

Return unique trainset group-comment annotations by section.

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

Recommend table and section-count plots for grouped comments output.

Emits a table view for all outputs and adds a section-count plot when section labels are available in serialized rows.

Works on Analyzer task output for trainset_group_comments.

Parameters

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

Returns

Type	Description
list[PresentationSpec]	Presentation specs suitable for comments tables and count plots.

Examples

specs = TrainsetGroupCommentsTask.recommended_presentations(
    _result,
    {"table": [{"section": "energy", "group_comment": "eos", "count": 1}]},
)

The output includes a table and a comment-count-by-section plot.

Method: run(data: ForceFieldOptimizationTrainingSetData, request: TrainsetGroupCommentsRequest, reporter=None)

Run unique group-comment extraction from parsed trainset data.

Builds the grouped-comment table across sections, then optionally filters rows to the request-selected section.

Works on ForceFieldOptimizationTrainingSetData.

Parameters

Name	Type	Description
data	ForceFieldOptimizationTrainingSetData	Parsed trainset data source.
request	TrainsetGroupCommentsRequest	Request containing section scope for comment extraction.
reporter	Any, optional	Progress callback accepted by analyzer tasks; unused here.

Returns

Type	Description
TrainsetGroupCommentsResult	Result containing grouped comments and metadata.

Examples

result = TrainsetGroupCommentsTask().run(
    data,
    TrainsetGroupCommentsRequest(section="all"),
)

The result table contains unique comments from all supported sections.

Result: TrainsetGroupCommentsResult

Result payload containing grouped trainset comments.

The analyzer returns unique per-section comments with earliest line numbers when available, suitable for quality checks and section-level summaries.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	TrainsetGroupCommentsRequest

Examples

row = {
    "section": "energy",
    "group_comment": "equation_of_state_reference_set",
    "line_number": 142,
    "count": 1,
}

The sample indicates one unique ENERGY comment entry.