Skip to content

Kinematics Analysis

Provide analyzer tasks for atomic kinematics series extraction.

This module slices and normalizes coordinate, velocity, and acceleration streams from atomic kinematics data into tabular analyzer outputs. It is scoped to kinematics-domain series extraction and does not infer bonding or chemistry.

Usage context

  • Motion analysis: Inspect per-atom position/velocity/acceleration signals.
  • Frame selection: Extract kinematics series on selected frame subsets.
  • Diagnostics: Export normalized time-series tables for downstream plotting.

Request: AtomicKinematicsRequest

Request payload for atomic kinematics table extraction.

This request selects one kinematics dataset and optionally restricts output rows to a subset of atom indices.

Fields

Field Type Default Help Choices
key KinematicsKey Kinematics dataset to extract. Example: key='velocities' returns vx, vy, vz columns. metadata, coordinates, velocities, accelerations, prev_accelerations
atoms Optional[Sequence[int]] Optional 1-based atom ids to filter rows. Example: atoms=[1, 3, 7]. Empty means all atoms.

Examples

request = AtomicKinematicsRequest(key="velocities", atoms=[1, 3, 7])

The request returns velocity rows only for atoms 1, 3, and 7.

Task: AtomicKinematicsTask

Return metadata or a selected atomic-kinematics table from vels-style files.

Recommend table and simple axis plot views for kinematics outputs.

Always returns a table view and adds a single-series plot when atom_index and at least one numeric component column are present.

Works on Analyzer task output for get_kinematics.

Parameters

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

Returns

Type Description
list[PresentationSpec] Recommended renderer specifications for UI display.

Examples

specs = AtomicKinematicsTask.recommended_presentations(
    _result,
    {"table": [{"atom_index": 1, "vx": -0.24}]},
)

The returned list includes a table and one component-vs-atom plot.

Method: run(data: AtomicKinematicsData, request: AtomicKinematicsRequest, reporter=None)

Execute atomic kinematics extraction for the selected data key.

Selects one kinematics table from parsed atomic kinematics data and applies optional atom-index filtering before returning a typed result.

Works on AtomicKinematicsData parsed from kinematics/vels-style sources.

Parameters

Name Type Description
data AtomicKinematicsData Parsed kinematics data bundle.
request AtomicKinematicsRequest Request with dataset key and optional atom filter.
reporter Any, optional Progress callback accepted by analyzer tasks; unused here.

Returns

Type Description
AtomicKinematicsResult Result containing the extracted kinematics table.

Examples

result = AtomicKinematicsTask().run(
    data,
    AtomicKinematicsRequest(key="coordinates"),
)

result.table contains the selected coordinate rows.

Result: AtomicKinematicsResult

Result payload for atomic kinematics extraction.

The analyzer returns a normalized table corresponding to the selected kinematics key and optional atom filtering constraints.

Fields

Field Type Default Help Choices
table pd.DataFrame
request AtomicKinematicsRequest

Examples

row = {"atom_index": 1, "vx": -0.24, "vy": 0.03, "vz": 0.11}

The sample row represents one velocity record for one atom.