Skip to content

Force Field Analysis

Expose analyzer tasks for structured force-field parameter content.

This module provides section-oriented extraction and filtering over parsed force-field parameter data. It focuses on parameter-table retrieval and normalization, and does not run optimization or diagnostic computations.

Usage context

  • Parameter inspection: Query specific parameter sections for review.
  • Data export: Build normalized parameter tables for external tooling.
  • Workflow composition: Feed section slices into optimization/report analyzers.

Request: FFieldDataRequest

Request payload for force-field section extraction.

This request controls section selection and whether bonded/multi-body rows are returned as raw atom-index values or augmented with symbolic term labels derived from atom parameters.

Fields

Field Type Default Help Choices
section Optional[str] Single force-field section to load. Example: 'bond' or 'off_diagonal'. general, atom, bond, off_diagonal, angle, torsion, hbond
interpret bool True If true, include interpreted symbolic terms for multi-body sections (for example C-H, C-C-H). If false, keep raw atom-index based rows. True, False

Examples

request = ForceFieldDataRequest(section="bond", interpret=True)

The request returns only the bond section with symbolic term labels.

Task: FFieldDataTask

Return raw or interpreted force-field section data.

Recommend default table and quick-look plot presentations.

Selects a table view in all cases and adds a simple plot when at least one numeric column can be paired with a suitable categorical/index axis.

Works on Analyzer task output for force_field_data.

Parameters

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

Returns

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

Examples

specs = ForceFieldDataTask.recommended_presentations(
    _result,
    {"table": [{"section": "bond", "term": "C-H", "De": 78.2}]},
)

The output includes a table and a one-series plot when numeric data exists.

Method: run(data: ForceFieldParametersData, request: FFieldDataRequest, reporter=None)

Run section-oriented extraction over parsed force-field parameters.

Resolves the requested section scope, materializes section tables in raw or interpreted mode, and returns the assembled DataFrame result.

Works on ForceFieldParametersData parsed from force-field parameter sources.

Parameters

Name Type Description
data ForceFieldParametersData Parsed force-field parameter bundle.
request FFieldDataRequest Section and interpretation options for extraction.
reporter Any, optional Optional progress callback invoked per processed section.

Returns

Type Description
FFieldDataResult Result containing one extracted/combined section table.

Examples

result = ForceFieldDataTask().run(
    data,
    ForceFieldDataRequest(section="angle", interpret=True),
)

The returned table contains only interpreted angle-parameter rows.

Result: FFieldDataResult

Result payload for force-field section table analysis.

The analyzer returns one normalized DataFrame containing either a single section or a concatenated multi-section table based on request scope.

Fields

Field Type Default Help Choices
table pd.DataFrame
request FFieldDataRequest

Notes

Column schemas vary by section because each force-field block has its own parameter layout.

Examples

row = {"section": "bond", "i": 1, "j": 2, "term": "C-H"}

The sample row shows one interpreted bonded parameter entry.