atomref.radii

This is the main user-facing module for radii workflows.

It provides radii policies, packaged radii-set discovery, lookup helpers, and policy-assessment reports.

atomref.radii

Radii-specific public API built on the generic policy core.

RadiiKind module-attribute

RadiiKind = Literal['covalent', 'van_der_waals']

Supported radii quantity selector.

RadiiSet module-attribute

RadiiSet = ElementScalarSet

Typing alias for an immutable element-indexed radii dataset.

DEFAULT_COVALENT_POLICY module-attribute

DEFAULT_COVALENT_POLICY = RadiiPolicy(kind='covalent', base_set='cordero2008', transfers=(SubstitutionTransfer(source=DatasetRef('covalent_radius', 'csd_legacy_cov')),))

Default covalent-radii policy used by the convenience helpers.

DEFAULT_VDW_POLICY module-attribute

DEFAULT_VDW_POLICY = RadiiPolicy(kind='van_der_waals', base_set='alvarez2013', transfers=(LinearTransfer(predictors=(DatasetRef('atomic_radius', 'rahm2016'),)),))

Default vdW-radii policy used by the convenience helpers.

RadiiPolicy dataclass

RadiiPolicy(kind: RadiiKind, base_set: str | RadiiSet, transfers: tuple[TransferModel, ...] = (), overrides: Mapping[str, float] = dict(), fallback: float | None = None)

Policy wrapper specialized for radii lookup.

Attributes:

Name	Type	Description
kind	RadiiKind	Target radii quantity, "covalent" or "van_der_waals".
base_set	str | RadiiSet	Packaged 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 element values checked before the base set. Defaults to an empty mapping.
fallback	float | None	Final finite, nonnegative value, or None. Defaults to None.

Examples:

>>> import atomref as ar
>>> policy = ar.RadiiPolicy(kind="covalent", base_set="cordero2008")
>>> ar.get_covalent_radius("C", policy=policy)
0.76

Notes

Packaged radii use angstrom. Custom sets, overrides, fallbacks, and transfer sources must use compatible units because policies do not perform 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 preserving the configured rule order.

Raises:

Type	Description
DatasetError	If a packaged set is unknown or non-scalar.
PolicyError	If kind, base quantity, override, or fallback is invalid.

RadiiElementAssessment dataclass

RadiiElementAssessment(symbol: str, lookup: LookupResult)

Per-element row in a radii policy assessment report.

Attributes:

Name	Type	Description
symbol	str	Canonical element symbol.
lookup	LookupResult	Full lookup result for that element.

RadiiPolicyAssessment dataclass

RadiiPolicyAssessment(kind: RadiiKind, policy: RadiiPolicy, elements: tuple[str, ...], n_elements: int, n_override: int, n_base: int, n_transfer_substitution: int, n_transfer_linear: int, n_fallback: int, n_missing: int, n_placeholders: int, missing_symbols: tuple[str, ...], placeholder_symbols: tuple[str, ...], fits: tuple[LinearFit, ...] = (), warnings: tuple[str, ...] = (), per_element: tuple[RadiiElementAssessment, ...] = ())

Summary of how a radii policy behaved over a set of elements.

Attributes:

Name	Type	Description
kind	RadiiKind	Assessed radii quantity.
policy	RadiiPolicy	Policy that was assessed.
elements	tuple[str, ...]	Canonical, deduplicated symbols in atomic-number order.
n_elements	int	Number of assessed elements.
n_override	int	Results supplied by explicit overrides.
n_base	int	Results supplied directly by the base set.
n_transfer_substitution	int	Results supplied by substitution transfers.
n_transfer_linear	int	Results supplied by linear transfers.
n_fallback	int	Results supplied by the fallback.
n_missing	int	Elements without a resolved value.
n_placeholders	int	Returned values equal to a declared placeholder.
missing_symbols	tuple[str, ...]	Symbols counted by n_missing.
placeholder_symbols	tuple[str, ...]	Symbols counted by n_placeholders.
fits	tuple[LinearFit, ...]	Successful linear-fit diagnostics for configured transfers.
warnings	tuple[str, ...]	Fit-assessment errors retained as report warnings.
per_element	tuple[RadiiElementAssessment, ...]	Detailed rows when assessment used detail=True; otherwise an empty tuple.

list_radii_sets

list_radii_sets(kind: RadiiKind, *, usage_role: str | None = None) -> tuple[str, ...]

List packaged radii-set IDs for one radii kind.

Parameters:

Name	Type	Description	Default
kind	RadiiKind	"covalent" or "van_der_waals".	required
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
PolicyError	If kind is unsupported.
DatasetError	If registry metadata is malformed.

list_radii_set_infos

list_radii_set_infos(kind: RadiiKind, *, usage_role: str | None = None) -> tuple[DatasetInfo, ...]

Return packaged metadata objects for radii sets of one kind.

Parameters:

Name	Type	Description	Default
kind	RadiiKind	"covalent" or "van_der_waals".	required
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
PolicyError	If kind is unsupported.
DatasetError	If registry metadata is malformed.

get_radii_set_info

get_radii_set_info(kind: RadiiKind, set_id: str) -> DatasetInfo

Return metadata for one packaged radii set.

Parameters:

Name	Type	Description	Default
kind	RadiiKind	"covalent" or "van_der_waals".	required
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
PolicyError	If kind is unsupported.
DatasetError	If set_id is unknown or metadata is malformed.

get_radii_set

get_radii_set(kind: RadiiKind, set_id: str) -> RadiiSet

Load one packaged radii set as an ElementScalarSet.

Parameters:

Name	Type	Description	Default
kind	RadiiKind	"covalent" or "van_der_waals".	required
set_id	str	Canonical packaged set ID or accepted alias.	required

Returns:

Type	Description
RadiiSet	A cached immutable scalar set whose values are in angstrom.

Raises:

Type	Description
PolicyError	If kind is unsupported.
DatasetError	If the set is unknown, malformed, or non-scalar.

lookup_covalent_radius

lookup_covalent_radius(symbol: str | None, *, policy: RadiiPolicy | None = None) -> LookupResult

Resolve a covalent radius together with provenance.

Parameters:

Name	Type	Description	Default
symbol	str | None	Symbol-like element token, or None. D/T map to H.	required
policy	RadiiPolicy | None	Covalent RadiiPolicy; None selects DEFAULT_COVALENT_POLICY.	None

Returns:

Type	Description
LookupResult	Lookup result whose value is in angstrom, or an explicit missing result.

Raises:

Type	Description
DatasetError	If a referenced dataset is unknown or non-scalar.
PolicyError	If the policy has the wrong kind or invalid configuration.

Examples:

>>> lookup_covalent_radius("C").value
0.76

get_covalent_radius

get_covalent_radius(symbol: str | None, *, policy: RadiiPolicy | None = None) -> float | None

Return only the selected covalent radius.

Parameters:

Name	Type	Description	Default
symbol	str | None	Symbol-like element token, or None. D/T map to H.	required
policy	RadiiPolicy | None	Covalent RadiiPolicy; None selects DEFAULT_COVALENT_POLICY.	None

Returns:

Type	Description
float | None	Selected radius in angstrom, or None when resolution is missing.

Raises:

Type	Description
DatasetError	If a referenced dataset is unknown or non-scalar.
PolicyError	If the policy has the wrong kind or invalid configuration.

lookup_vdw_radius

lookup_vdw_radius(symbol: str | None, *, policy: RadiiPolicy | None = None) -> LookupResult

Resolve a van der Waals radius together with provenance.

Parameters:

Name	Type	Description	Default
symbol	str | None	Symbol-like element token, or None. D/T map to H.	required
policy	RadiiPolicy | None	van der Waals RadiiPolicy; None selects DEFAULT_VDW_POLICY.	None

Returns:

Type	Description
LookupResult	Lookup result whose value is in angstrom, or an explicit missing result.

Raises:

Type	Description
DatasetError	If a referenced dataset is unknown or non-scalar.
PolicyError	If the policy has the wrong kind or invalid configuration.

get_vdw_radius

get_vdw_radius(symbol: str | None, *, policy: RadiiPolicy | None = None) -> float | None

Return only the selected van der Waals radius.

Parameters:

Name	Type	Description	Default
symbol	str | None	Symbol-like element token, or None. D/T map to H.	required
policy	RadiiPolicy | None	van der Waals RadiiPolicy; None selects DEFAULT_VDW_POLICY.	None

Returns:

Type	Description
float | None	Selected radius in angstrom, or None when resolution is missing.

Raises:

Type	Description
DatasetError	If a referenced dataset is unknown or non-scalar.
PolicyError	If the policy has the wrong kind or invalid configuration.

assess_radii_policy

assess_radii_policy(elements: Iterable[str], *, policy: RadiiPolicy, detail: bool = False) -> RadiiPolicyAssessment

Assess how a radii policy resolves values over a set of elements.

Parameters:

Name	Type	Description	Default
elements	Iterable[str]	Element tokens to normalize, deduplicate, and sort by atomic number.	required
policy	RadiiPolicy	Radii policy to evaluate.	required
detail	bool	Include a RadiiElementAssessment for each element when True. Defaults to False.	False

Returns:

Type	Description
RadiiPolicyAssessment	Counts, missing/placeholder symbols, fit summaries, warnings, and optional per-element detail in a RadiiPolicyAssessment.

Raises:

Type	Description
ValueError	If an element token is missing or invalid.
DatasetError	If a referenced dataset is unknown or non-scalar.
PolicyError	If policy or transfer configuration is invalid.

Examples:

>>> report = assess_radii_policy(
...     ["C", "O"], policy=DEFAULT_COVALENT_POLICY, detail=True
... )
>>> report.n_elements, len(report.per_element)
(2, 2)