Skip to content

Dihedral Analysis

Compute dihedral-angle analyzer outputs from trajectory coordinates.

This module evaluates signed dihedral angles for requested atom quartets across trajectory frames and returns normalized tables for downstream visualization. It is limited to geometric dihedral calculations and does not infer bonding.

Usage context

  • Conformational analysis: Track torsional motion over simulation time.
  • Targeted probes: Evaluate specific atom-quartet torsions frame by frame.
  • Reporting workflows: Export angle series for plots and summary stats.

Request: DihedralRequest

Request payload for trajectory dihedral-angle analysis.

Carries atom-quadruplet selection, frame sampling, unit selection, and backend choice for dihedral computation.

Fields

Field Type Default Help Choices
atom_ids Sequence[int] 1, 2, 3, 4 Exactly four atom IDs that define the dihedral.
frames Optional[Sequence[int]] Frame indices to evaluate. Empty means all frames.
every int 1 Stride over selected frames.
units str deg Angle units. deg, rad
backend str numpy Computation backend. numpy, mdanalysis

Examples

req = DihedralRequest(atom_ids=[4, 7, 12, 20], frames=[0, 50, 100], units="deg")

Sample output: DihedralRequest(...) Meaning: The request selects one atom quadruplet and sampled frames for torsion extraction.

Task: DihedralTask

Compute the signed dihedral angle for one atom quadruplet over time.

Build default table/plot presentations for dihedral task output.

Works on

Analyzer task output payloads

Parameters

Name Type Description
_result DihedralResult Analysis result object for the executed task.
payload dict[str, Any] Serialized result payload used by presentation dispatch.

Returns

Type Description
list[PresentationSpec] Recommended renderer specifications for table and line plot views.

Examples

specs = DihedralTask.recommended_presentations(result, payload)

Sample output: A list containing a table view and a dihedral-vs-time plot view. Meaning: UIs can render dihedral outputs without custom mapping logic.

Method: run(data: TrajectoryData, request: DihedralRequest, reporter=None)

Compute a dihedral-angle series for one atom quadruplet.

Evaluates the requested four-atom torsion on selected frames and returns one row per frame in the result table.

Works on

TrajectoryData plus DihedralRequest analyzer inputs

Parameters

Name Type Description
data TrajectoryData Trajectory positions, atom IDs/types, and optional iteration values.
request DihedralRequest Analysis configuration including atom IDs, frame selection, and backend/unit options.
reporter Any, optional Optional progress callback invoked during processing.

Returns

Type Description
DihedralResult Result object containing dihedral time-series rows and request echo.

Examples

req = DihedralRequest(atom_ids=[1, 2, 3, 4], units="deg")
result = DihedralTask().run(data, req)

Sample output: result.table with columns including iter and dihedral. Meaning: Each row is the torsion value for the selected quadruplet at one frame.

Result: DihedralResult

Result payload for dihedral-angle analysis.

Stores the per-frame torsion table and the request used to generate it.

Fields

Field Type Default Help Choices
table pd.DataFrame
request DihedralRequest

Examples

result = task.run(data, req)
print(result.table.head())

Sample output: DataFrame rows containing one torsion value per selected frame. Meaning: The table is directly usable for time-series plotting or export.