Atom utilities

pasted._atoms

Atomic data (Z → symbol mapping, Pyykkö covalent radii, Pauling electronegativities) and all input-parsing / validation helpers that do not depend on NumPy.

Public names

ATOMIC_NUMBERSdict[str, int]

Element symbol → atomic number, Z = 1–106.

ALL_METRICSfrozenset[str]

Names of all 17 disorder metrics returned by compute_all_metrics(). The set is unordered; use sorted(ALL_METRICS) for a deterministic listing.

PAULING_EN_FALLBACKfloat

Default electronegativity value (1.0) used for elements without a tabulated Pauling value (noble gases, etc.).

cov_radius_ang(sym) → float

Pyykkö covalent radius in Ångströms.

pauling_electronegativity(sym) → float

Pauling electronegativity (1960 / IUPAC 2016 scale).

parse_element_spec(spec) → list[str]

Accept a numeric string ("6,7,8" or "1-30"), a list of symbols (["C","N","O"]), or None (all Z = 1–106).

validate_charge_mult(atoms, charge, mult) → tuple[bool, str]

Return (True, "") when the electron count parity is consistent with the requested charge and multiplicity.

default_element_pool() → list[str]

All 106 elements ordered by atomic number.

parse_filter(spec) → tuple[str, float, float]

Parse a "METRIC:MIN:MAX" filter string.

pasted._atoms.ALL_METRICS: frozenset[str] = frozenset({'H_atom', 'H_spatial', 'H_total', 'Q4', 'Q6', 'Q8', 'RDF_dev', 'bond_angle_entropy', 'charge_frustration', 'coordination_variance', 'graph_cc', 'graph_lcc', 'local_anisotropy', 'moran_I_chi', 'radial_variance', 'ring_fraction', 'shape_aniso'})

Frozenset of all 17 disorder metric names returned by compute_all_metrics().

The set is unordered; use sorted(ALL_METRICS) whenever a deterministic order is required (e.g., for display or serialization). Membership testing ("H_total" in ALL_METRICS) is O(1).

pasted._atoms.PAULING_EN_FALLBACK: float = 1.0

Fallback Pauling electronegativity for elements without a literature value (any symbol not in the table; Kr/Xe/other noble gases have explicit entries).

pasted._atoms.cov_radius_ang(sym: str) → float

Return the Pyykkö single-bond covalent radius in Å for sym.

For Z > 86 the same-group nearest lighter element is used as a proxy (e.g. Fr → Cs, U → Nd, Rf → Hf).

pasted._atoms.default_element_pool() → list[str]

Return all supported element symbols (Z = 1–106), sorted by Z.

pasted._atoms.parse_element_spec(spec: str | list[str]) → list[str]

Parse an element specification into a sorted list of element symbols.

Three input forms are accepted:

Atomic-number string (most common)

"1-30" — Z = 1 through 30 "6,7,8" — Z = 6, 7, 8 (C, N, O) "1-10,26,28" — Z = 1–10 plus Z = 26 and 28

Symbol list

["C", "N", "O"] — explicit element-symbol list. Symbols must be present in the built-in atomic-number table (Z = 1–106).

Parameters:

spec – An atomic-number spec string or a list of element symbol strings.

Returns:

Element symbols sorted by atomic number (ascending Z).

Return type:

list[str]

Raises:

ValueError – On malformed input, unknown element symbols, or unsupported Z values.

pasted._atoms.parse_filter(f: str) → tuple[str, float, float]

Parse "METRIC:MIN:MAX" → (metric, lo, hi).

Use "-" for an open bound.

Raises:

ValueError – On unknown metric or malformed string.

pasted._atoms.parse_int_range(s: str) → tuple[int, int]

Parse "MIN:MAX" → (int, int) with MIN ≥ 1 and MIN ≤ MAX.

pasted._atoms.parse_lo_hi(s: str, name: str = 'range') → tuple[float, float]

Parse "LO:HI" → (float, float).

pasted._atoms.pauling_electronegativity(sym: str) → float

Return the Pauling electronegativity for element sym.

Values follow Pauling (1960) with IUPAC 2016 updates. Noble gases with no known compounds (He, Ne, Ar, Rn) are assigned 4.0 to model complete resistance to electron donation. Kr (≈ 3.0) and Xe (≈ 2.6) use literature estimates from the Allen / Allred-Rochow scale, reflecting their known tendency to form compounds (KrF₂, XeF₂, etc.). Any symbol not in the table returns PAULING_EN_FALLBACK (1.0).

Parameters:

sym – Element symbol (case-sensitive, e.g. "Fe").

Returns:

Pauling electronegativity. Noble gases return 4.0; any other element without a value returns 1.0.

Return type:

float

pasted._atoms.validate_charge_mult(atoms_list: list[str], charge: int, mult: int) → tuple[bool, str]

Check electron count and spin-parity for atoms_list.

Returns:

ok is True when both conditions pass. On the success path the message is an empty string ""; callers in the hot optimizer loop discard it (ok, _ = validate_charge_mult(...)), so building the full diagnostic string is unnecessary work. On failure the message contains the full diagnostic as before.

Return type:

(ok, message)

Electronegativity data

pasted._atoms.pauling_electronegativity(sym: str) → float

Return the Pauling electronegativity for element sym.

Values follow Pauling (1960) with IUPAC 2016 updates. Noble gases with no known compounds (He, Ne, Ar, Rn) are assigned 4.0 to model complete resistance to electron donation. Kr (≈ 3.0) and Xe (≈ 2.6) use literature estimates from the Allen / Allred-Rochow scale, reflecting their known tendency to form compounds (KrF₂, XeF₂, etc.). Any symbol not in the table returns PAULING_EN_FALLBACK (1.0).

Parameters:

sym – Element symbol (case-sensitive, e.g. "Fe").

Returns:

Pauling electronegativity. Noble gases return 4.0; any other element without a value returns 1.0.

Return type:

float

pasted._atoms.PAULING_EN_FALLBACK: float = 1.0

Fallback Pauling electronegativity for elements without a literature value (any symbol not in the table; Kr/Xe/other noble gases have explicit entries).

ALL_METRICS

pasted._atoms.ALL_METRICS: frozenset[str] = frozenset({'H_atom', 'H_spatial', 'H_total', 'Q4', 'Q6', 'Q8', 'RDF_dev', 'bond_angle_entropy', 'charge_frustration', 'coordination_variance', 'graph_cc', 'graph_lcc', 'local_anisotropy', 'moran_I_chi', 'radial_variance', 'ring_fraction', 'shape_aniso'})

Frozenset of all 17 disorder metric names returned by compute_all_metrics().

The set is unordered; use sorted(ALL_METRICS) whenever a deterministic order is required (e.g., for display or serialization). Membership testing ("H_total" in ALL_METRICS) is O(1).

ALL_METRICS is a frozenset[str] containing all 17 metric names accepted by filters=, --filter, and the objective= dict. They are also the keys present in Structure.metrics and EvalContext.metrics. Because frozenset is unordered, use sorted(ALL_METRICS) when a deterministic listing is required.

Key	What it measures
H_atom	Shannon entropy of the element composition (0 = pure, ln k = k equal elements)
H_spatial	Shannon entropy of the pairwise-distance histogram within cutoff
H_total	w_atom · H_atom + w_spatial · H_spatial
RDF_dev	RMS deviation of the normalized RDF from a flat distribution
shape_aniso	Relative shape anisotropy κ² from the gyration tensor: 0 = spherical, 1 = rod-like ([0, 1])
Q4	Steinhardt bond-orientational order parameter l = 4
Q6	Steinhardt bond-orientational order parameter l = 6
Q8	Steinhardt bond-orientational order parameter l = 8
graph_lcc	Fraction of atoms in the largest connected component of the covalent-bond graph
graph_cc	Mean local clustering coefficient of the covalent-bond graph: 0 = no triangles, 1 = fully triangulated ([0, 1])
ring_fraction	Fraction of atoms participating in at least one ring
charge_frustration	Population variance of |Δχ| (Pauling electronegativity difference) across cutoff-adjacent atom pairs
moran_I_chi	Moran’s spatial autocorrelation of electronegativity on the bond graph
bond_angle_entropy	Mean per-atom Shannon entropy of the bond-angle distribution (added in v0.4.0)
coordination_variance	Population variance of per-atom coordination numbers (added in v0.4.0)
radial_variance	Mean per-atom variance of neighbor distances in Ų (added in v0.4.0)
local_anisotropy	Mean per-atom local covariance-tensor anisotropy [0, 1] (added in v0.4.0)

Element pool specification

pasted._atoms.parse_element_spec(spec: str | list[str]) → list[str]

Parse an element specification into a sorted list of element symbols.

Three input forms are accepted:

Atomic-number string (most common)

"1-30" — Z = 1 through 30 "6,7,8" — Z = 6, 7, 8 (C, N, O) "1-10,26,28" — Z = 1–10 plus Z = 26 and 28

Symbol list

["C", "N", "O"] — explicit element-symbol list. Symbols must be present in the built-in atomic-number table (Z = 1–106).

Parameters:

spec – An atomic-number spec string or a list of element symbol strings.

Returns:

Element symbols sorted by atomic number (ascending Z).

Return type:

list[str]

Raises:

ValueError – On malformed input, unknown element symbols, or unsupported Z values.

Note

When passing elements= as a string, it must contain atomic numbers (integers), not element symbols. elements="C,N,O" raises ValueError; use elements="6,7,8" or elements=["C","N","O"] instead.

parse_element_spec() accepts two input forms:

Form	Example	Meaning
Comma-separated atomic numbers	"6,7,8"	C, N, O
Atomic-number range	"1-30"	H through Zn
Mixed ranges and singles	"1-10,26,28"	H–Ne plus Fe and Ni
Symbol list (new in v0.3.5)	["C", "N", "O"]	Explicit list of element symbols

Changed in version 0.3.5: parse_element_spec now accepts a list[str] of element symbols in addition to atomic-number strings. Previously, passing a list raised AttributeError because the function tried to call .split(",") on the list object. The fix aligns the public API with the behavior already documented in Quick start.

Changed in version 0.3.5: Structure.from_xyz() now raises FileNotFoundError when given a path that does not exist, instead of silently treating the path string as XYZ content and raising a confusing ValueError.

Changed in version 0.4.0: read_xyz() now raises FileNotFoundError (or IsADirectoryError) for invalid paths, matching Structure.from_xyz() behavior. Previously it raised a confusing ValueError by attempting to parse the path string as XYZ text.