Coordination Analyzer Analysis

Coordination (valence satisfaction) analysis utilities.

This module provides functions for classifying atomic coordination in a frame by comparing each atom's total bond order (typically from fort.7) to its expected valence. The resulting labels help identify under- and over-coordinated sites (e.g., dangling bonds, over-saturated atoms, and coordination defects).

Typical use cases include:

• classifying atoms as under / well / over coordinated for a single frame
• attaching a numeric status code and a human-readable label
• using coordination labels as defect indicators in post-processing

classify_coordination_for_frame(*, sum_bos, atom_types, valences, threshold=0.3, require_all_valences=True)

Classify atoms in a single frame as under-, well-, or over-coordinated.

Classification is based on delta = sum_bos - valence and a tolerance threshold:

• status = -1: under-coordinated (delta < -threshold)
• status = 0: well-coordinated (|delta| <= threshold)
• status = +1: over-coordinated (delta > threshold)

Works on

Fort.7-derived arrays — sum_BOs + atom types (typically from fort.7 and xmolout)

Parameters:

Name	Type	Description	Default
sum_bos	sequence of float	Per-atom total bond order values (e.g., the sum_BOs column from fort.7).	required
atom_types	sequence of str	Per-atom type symbols corresponding to sum_bos (e.g., ["Al", "N", ...]).	required
valences	mapping of str to float	Expected valence for each atom type (e.g., {"Al": 3.0, "N": 3.0}).	required
threshold	float	Tolerance used for deciding under/over coordination.	0.3
require_all_valences	bool	If True, raise an error if any atom type is missing from valences.	True

Returns:

Type	Description
DataFrame	Per-atom classification table with columns: atom_id, atom_type, sum_BOs, valence, delta, status.

Examples:

>>> sum_bos = [2.8, 3.1, 0.9]
>>> atom_types = ["Al", "Al", "H"]
>>> valences = {"Al": 3.0, "H": 1.0}
>>> df = classify_coordination_for_frame(
...     sum_bos=sum_bos, atom_types=atom_types, valences=valences, threshold=0.3
... )

status_label(series)

Convert numeric coordination status codes into human-readable labels.

Mapping: - -1 → "under" - 0 → "coord" - +1 → "over" - NaN → None

Works on

Coordination status arrays — output from :func:classify_coordination_for_frame

Parameters:

Name	Type	Description	Default
series	sequence of int or float	Numeric status values (-1, 0, +1), optionally containing NaNs.	required

Returns:

Type	Description
list[str | None]	Coordination labels in the same order as input.

Examples:

>>> labels = status_label([-1, 0, 1, float("nan")])