Hybridization Analysis

Assign per-atom hybridization status from connectivity-derived metrics.

This module classifies atoms into configured hybridization states using bond-order-sum targets and tolerances, optionally with element-specific rules. It focuses on hybridization labels and summary tables rather than coordination or event-detection logic.

Usage context

• Hybridization tagging: Label atoms as sp, sp2, sp3, or custom states.
• Force-field validation: Compare expected hybridization against trajectories.
• Chemistry post-processing: Feed state labels into reporting or filtering flows.

Request: HybridizationStatusRequest

Request for per-atom hybridization-status classification.

Fields

Field	Type	Default	Help	Choices
hybridizations	Optional[Mapping[str, float]]		Global hybridization mapping as state->target sum_BOs. Example: {'sp': 1, 'sp2': 2, 'sp3': 3}.
element_hybridizations	Optional[Mapping[str, Mapping[str, float]]]		Per-element hybridization map overriding global values. Example: {'C': {'sp': 1, 'sp2': 2, 'sp3': 3}}.
target_elements	Optional[Sequence[str]]		Optional element filter. Example: ['C', 'O'].
target_atom_ids	Optional[Sequence[int]]		Optional atom-id filter (1-based). Example: [1, 2, 5].
threshold	float	0.3	Absolute tolerance for match classification. Example: 0.2.
frames	Optional[Sequence[int]]		Optional frame indices to evaluate. Example: [0, 10, 20].
every	int	1	Stride for selected frames. Example: every=5.
require_defined_hybridization	bool	True	If true, fail when an element has no mapping. If false, emit undefined rows instead.	True, False

Examples

req = HybridizationStatusRequest(
    hybridizations={"sp": 1.0, "sp2": 2.0, "sp3": 3.0},
    target_elements=["C"],
    threshold=0.2,
)

Sample output: HybridizationStatusRequest(...) Meaning: The request configures atom selection and matching tolerance for hybridization classification.

Task: HybridizationStatusTask

Per-atom hybridization status over selected frames.

Method: recommended_presentations(_result: HybridizationStatusResult, _payload: dict[str, Any])

Return default table presentation for hybridization outputs.

Works on

Analyzer task output payloads

Parameters

Name	Type	Description
_result	HybridizationStatusResult	Analysis result object for the executed task.
_payload	dict[str, Any]	Serialized result payload.

Returns

Type	Description
list[PresentationSpec]	Table presentation specification.

Examples

specs = HybridizationStatusTask.recommended_presentations(result, payload)

Sample output: [PresentationSpec(renderer="table", ...)] Meaning: Hybridization results default to tabular rendering.

Method: run(data: ConnectivityData, request: HybridizationStatusRequest, reporter=None)

Classify per-atom hybridization status across selected frames.

For example, with hybridizations={"sp": 1.0, "sp2": 2.0, "sp3": 3.0} and threshold=0.2, a carbon atom with a sum of bond orders of 2.1 would be classified as sp2 (matched), while one with a sum of 1.7 would be classified as sp (unmatched).

Works on

ConnectivityData plus HybridizationStatusRequest analyzer inputs

Parameters

Name	Type	Description
data	ConnectivityData	Connectivity input containing sum bond orders or bond-order matrices.
request	HybridizationStatusRequest	Selection and hybridization-target configuration.
reporter	Any, optional	Optional progress callback invoked during frame processing.

Returns

Type	Description
HybridizationStatusResult	Result table with matched/unmatched hybridization assignments.

Examples

result = HybridizationStatusTask().run(data, req)

Sample output: result.table with status_label and hybridization columns. Meaning: One row is produced per selected atom per selected frame.

Result: HybridizationStatusResult

Hybridization-status analysis result.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	HybridizationStatusRequest

Examples

result = HybridizationStatusTask().run(data, req)
result.table.head()

Sample output: DataFrame rows with matched/unmatched hybridization assignments. Meaning: Each row captures one atom-frame classification decision.