atomref.xh
This module provides focused X–H bond-length helpers.
It is intentionally narrow:
- one packaged sparse target dataset,
csd_legacy_xh_cno, - one wrapper policy, XHPolicy,
- convenience helpers for listing packaged X–H sets and resolving X–H values.
The built-in quantity is keyed by the parent element X in X–H and is
currently aimed at hydrogen-position normalisation or related geometry
workflows.
In the default policy:
C,N, andOuse curated ConQuest/CSD defaults,- other parent elements may be inferred from
cordero2008, - policy-backed predictors are supported as well, with conservative nested-fit defaults and one additional nested prediction step allowed by default,
- the API does not infer a rigorous molecular bond length or perform atom typing beyond the parent-element policy.
atomref.xh
X-H bond-length helpers built on the generic policy core.
XHSet
module-attribute
XHSet = ElementScalarSet
Typing alias for an immutable parent-element X-H bond-length dataset.
DEFAULT_XH_POLICY
module-attribute
DEFAULT_XH_POLICY = XHPolicy(base_set='csd_legacy_xh_cno', transfers=(LinearTransfer(predictors=(DatasetRef('covalent_radius', 'cordero2008'),), min_points=3, exclude_placeholders=True),))
Default X-H policy used by the convenience helpers.
XHPolicy
dataclass
XHPolicy(base_set: str | XHSet, transfers: tuple[TransferModel, ...] = (), overrides: Mapping[str, float] = dict(), fallback: float | None = None)
Policy wrapper specialized for parent-element X-H bond lengths.
Attributes:
| Name | Type | Description |
|---|---|---|
base_set |
str | XHSet
|
Packaged X-H set ID or custom ElementScalarSet. |
transfers |
tuple[TransferModel, ...]
|
Ordered substitution or linear-transfer rules. Defaults to no transfers. |
overrides |
Mapping[str, float]
|
Explicit finite, nonnegative parent-element values checked before the base set. Defaults to an empty mapping. |
fallback |
float | None
|
Final finite, nonnegative value, or |
Examples:
>>> policy = XHPolicy(base_set="csd_legacy_xh_cno")
>>> get_xh_bond_length("C", policy=policy)
1.089
Notes
The quantity key is fixed to "xh_bond_length" and uses parent
element X as its lookup key. H, D, and T are not valid parent elements.
Packaged values are in angstrom. Custom sources and policy values must
use compatible units because policies perform no unit conversion.
as_value_policy
as_value_policy() -> ValuePolicy[str]
Convert this wrapper into the generic scalar policy.
Returns:
| Type | Description |
|---|---|
ValuePolicy[str]
|
An element-domain ValuePolicy with hydrogen blocked as a parent. |
Raises:
| Type | Description |
|---|---|
DatasetError
|
If a packaged set is unknown or non-scalar. |
PolicyError
|
If the base quantity, override, or fallback is invalid, or if H/D/T is used as an override parent. |
list_xh_sets
list_xh_sets(*, usage_role: str | None = None) -> tuple[str, ...]
List packaged X-H set IDs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
usage_role
|
str | None
|
Optional case-insensitive metadata-role filter. |
None
|
Returns:
| Type | Description |
|---|---|
tuple[str, ...]
|
Canonical set IDs in curated registry order. |
Raises:
| Type | Description |
|---|---|
DatasetError
|
If registry metadata is malformed. |
list_xh_set_infos
list_xh_set_infos(*, usage_role: str | None = None) -> tuple[DatasetInfo, ...]
Return packaged metadata objects for X-H sets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
usage_role
|
str | None
|
Optional case-insensitive metadata-role filter. |
None
|
Returns:
| Type | Description |
|---|---|
tuple[DatasetInfo, ...]
|
Immutable DatasetInfo objects in curated registry order. |
Raises:
| Type | Description |
|---|---|
DatasetError
|
If registry metadata is malformed. |
get_xh_set_info
get_xh_set_info(set_id: str) -> DatasetInfo
Return metadata for one packaged X-H set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
set_id
|
str
|
Canonical packaged set ID or accepted alias. |
required |
Returns:
| Type | Description |
|---|---|
DatasetInfo
|
Curated metadata, including angstrom units and provenance. |
Raises:
| Type | Description |
|---|---|
DatasetError
|
If the set is unknown or metadata is malformed. |
get_xh_set
get_xh_set(set_id: str) -> XHSet
Load one packaged X-H set as an ElementScalarSet.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
set_id
|
str
|
Canonical packaged set ID or accepted alias. |
required |
Returns:
| Type | Description |
|---|---|
XHSet
|
A cached immutable parent-element set in angstrom. |
Raises:
| Type | Description |
|---|---|
DatasetError
|
If the set is unknown, malformed, or non-scalar. |
lookup_xh_bond_length
lookup_xh_bond_length(symbol: str | None, *, policy: XHPolicy | None = None) -> LookupResult
Resolve a parent-element X-H bond length with provenance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
symbol
|
str | None
|
Parent-element token, or |
required |
policy
|
XHPolicy | None
|
X-H policy; |
None
|
Returns:
| Type | Description |
|---|---|
LookupResult
|
Lookup result whose value is in angstrom, or an explicit missing result. A blocked hydrogen parent includes an explanatory note. |
Raises:
| Type | Description |
|---|---|
DatasetError
|
If a referenced dataset is unknown or non-scalar. |
PolicyError
|
If policy or transfer configuration is invalid. |
Examples:
>>> result = lookup_xh_bond_length("C")
>>> result.value, result.source
(1.089, 'base')
get_xh_bond_length
get_xh_bond_length(symbol: str | None, *, policy: XHPolicy | None = None) -> float | None
Return only the selected parent-element X-H bond length.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
symbol
|
str | None
|
Parent-element token, or |
required |
policy
|
XHPolicy | None
|
X-H policy; |
None
|
Returns:
| Type | Description |
|---|---|
float | None
|
Selected bond length in angstrom, or |
Raises:
| Type | Description |
|---|---|
DatasetError
|
If a referenced dataset is unknown or non-scalar. |
PolicyError
|
If policy or transfer configuration is invalid. |