Skip to content

Coordination Analysis

Classify per-atom coordination states from connectivity-domain inputs.

This module evaluates coordination status by comparing observed bond-order coordination against expected valence targets. It is scoped to coordination label assignment and tabular output, and it does not infer hybridization states.

Usage context

  • Coordination auditing: Label atoms as under/over/coordinated per frame.
  • Quality control: Compare observed coordination against force-field valences.
  • Relabeling support: Supply coordination tags for downstream trajectory tasks.

Request: CoordinationStatusRequest

Request for per-atom coordination-status classification.

Fields

Field Type Default Help Choices
valences Optional[Mapping[str, float]] Optional element->valence map. Example: {'C': 4, 'O': 2, 'H': 1}.
threshold float 0.9 Absolute tolerance for assigning coordinated status. Example: 0.9.
frames Optional[Sequence[int]] Optional frame indices to analyze. Example: [0, 10, 20].
every int 1 Stride for selected frames. Example: every=5.
require_all_valences bool True If true, raise when any atom type has no valence mapping. If false, keep rows with undefined status. True, False

Examples

req = CoordinationStatusRequest(valences={"C": 4.0, "O": 2.0}, threshold=0.9)

Sample output: CoordinationStatusRequest(...) Meaning: The request defines valence targets and tolerance for status labeling.

Task: CoordinationStatusTask

Per-atom coordination status over selected frames.

Build default table/plot presentations for coordination outputs.

Works on

Analyzer task output payloads

Parameters

Name Type Description
_result CoordinationStatusResult 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 specs for table and trend plotting.

Examples

specs = CoordinationStatusTask.recommended_presentations(result, payload)

Sample output: A table view plus a delta/sum_BOs-vs-frame plot view when columns exist. Meaning: Coordination outputs can be rendered with default mappings.

Method: run(data: CoordinationStatusBundleData, request: CoordinationStatusRequest, reporter=None)

Compute per-atom coordination status across selected frames.

Classify atoms as under-, coordinated-, or over-coordinated. Classification compares bond-order totals against target valences from explicit maps or inferred values. For example, if an atom's valence is 3 and the threshold is 0.5, then: - sum_BOs < 2.5 -> under-coordinated - 2.5 <= sum_BOs <= 3.5 -> coordinated - sum_BOs > 3.5 -> over-coordinated

Works on

CoordinationStatusBundleData plus CoordinationStatusRequest inputs

Parameters

Name Type Description
data CoordinationStatusBundleData Bundle containing connectivity and force-field parameter data.
request CoordinationStatusRequest Selection, valence mapping, and tolerance configuration.
reporter Any, optional Optional progress callback invoked during frame processing.

Returns

Type Description
CoordinationStatusResult Coordination status table with one row per atom-frame.

Examples

result = CoordinationStatusTask().run(bundle, req)

Sample output: result.table with status and status_label columns. Meaning: Atom coordination is classified using BO sums versus valence targets.

Result: CoordinationStatusResult

Coordination-status analysis result.

Fields

Field Type Default Help Choices
table pd.DataFrame
request CoordinationStatusRequest

Examples

result = CoordinationStatusTask().run(bundle, req)
result.table.head()

Sample output: DataFrame rows labeled as under, coord, or over. Meaning: Each row is one atom-frame coordination classification.