Skip to content

atomref.policy

This module contains the generic resolver that sits below the radii-specific and X–H-specific convenience APIs.

Use it when you want to work directly with the shared value-selection engine:

A few practical notes:

  • The current runtime supports element-domain scalar policies.
  • ValuePolicy normalizes element-symbol overrides eagerly.
  • Transfer sources may be packaged datasets, custom sets, generic policies, or wrapper policies that expose as_value_policy().
  • LookupResult.is_placeholder refers to the returned numeric value itself, not to whether any transfer happened.
  • LookupResult.transfer_depth counts how many transfer steps were involved in the returned numeric value.
  • Nested lookup is cycle-checked across both generic ValuePolicy objects and wrapper policies such as RadiiPolicy and XHPolicy.

atomref.policy

Generic value-policy resolution for element-indexed scalar datasets.

LookupSource module-attribute 

LookupSource = Literal['override', 'base', 'transfer_substitution', 'transfer_linear', 'fallback', 'missing']

Provenance labels emitted by the scalar policy resolver.

LookupResult dataclass 

LookupResult(value: float | None, source: LookupSource, target: DatasetRef, resolved_from: tuple[DatasetRef, ...] = (), is_placeholder: bool = False, fit: LinearFit | None = None, notes: tuple[str, ...] = (), transfer_depth: int = 0)

Result of resolving one value through a policy.

Attributes:

Name Type Description
value float | None

Resolved scalar in the target policy's units, or None when no rule supplied a value.
source LookupSource

Rule that supplied value, or "missing".
target DatasetRef

Dataset identity the policy is resolving.
resolved_from tuple[DatasetRef, ...]

Ordered source datasets contributing to a transferred value.
is_placeholder bool

Whether the returned scalar equals its source dataset's declared placeholder value.
fit LinearFit | None

Linear-fit diagnostics when source is "transfer_linear".
notes tuple[str, ...]

Human-readable resolution and rejection diagnostics.
transfer_depth int

Number of transfer steps involved. Base, override, fallback, and missing results have depth 0.

Examples:

>>> import atomref as ar
>>> result = ar.lookup_covalent_radius("C")
>>> result.value, result.source
(0.76, 'base')
Notes

is_placeholder describes the returned numeric value, not whether a transfer occurred.

__float__ 

__float__() -> float

Coerce a present resolved value to float.

Returns:

Type Description
float

The resolved scalar value.

Raises:

Type Description
TypeError

If this result represents a missing value.

ValuePolicy dataclass 

ValuePolicy(base: ScalarDatasetLike, transfers: tuple[TransferModel, ...] = (), overrides: Mapping[K, float] = dict(), fallback: float | None = None, blocked: tuple[str, ...] = ())

Bases: Generic[K]

Ordered rule set for resolving element-domain scalar values.

Attributes:

Name Type Description
base ScalarDatasetLike

Packaged DatasetRef or custom ElementScalarSet that owns the target quantity and units.
transfers tuple[TransferModel, ...]

Ordered substitution or linear-transfer rules. Defaults to no transfers.
overrides Mapping[K, float]

Explicit key-to-value replacements checked before the base set. Element keys are canonicalized and values must be finite.
fallback float | None

Final finite scalar used after all transfers fail, or None. Defaults to None.
blocked tuple[str, ...]

Element symbols that must resolve as missing. Blocked keys take precedence over overrides and all other rules.

Raises:

Type Description
DatasetError

If the base reference is unknown or has a radial payload.
PolicyError

If fallback, override, or blocked configuration is invalid.

Examples:

>>> import atomref as ar
>>> policy = ar.ValuePolicy(
...     base=ar.DatasetRef("covalent_radius", "cordero2008"),
...     overrides={"C": 0.77},
... )
>>> ar.get_value("C", policy=policy)
0.77
Notes

Resolution order is blocked, override, base, transfers, fallback, then missing. The current resolver supports element-domain scalar data only. Values are not converted between units; every source in one policy must be dimensionally compatible with the base set.

lookup_value 

lookup_value(symbol: str | None, *, policy: ValuePolicy[str]) -> LookupResult

Public entry point for generic element-domain scalar lookup.

Parameters:

Name Type Description Default
symbol str | None

Symbol-like element token, or None. D/T map to H.

 required
policy ValuePolicy[str]

Element-domain scalar policy to apply.

 required

Returns:

Type Description
LookupResult

A LookupResult containing the value or an explicit missing result, together with provenance and transfer diagnostics.

Raises:

Type Description
DatasetError

If a referenced dataset is unknown or non-scalar.
PolicyError

If transfer configuration is invalid, fitting cannot meet its contract, or nested policies form a cycle.

Examples:

>>> import atomref as ar
>>> policy = ar.DEFAULT_COVALENT_POLICY.as_value_policy()
>>> result = ar.lookup_value("O", policy=policy)
>>> result.value
0.66
Notes

Invalid or uncovered elements normally produce source="missing" rather than raising. This is the same resolver used by the radii and X-H convenience layers.

get_value 

get_value(symbol: str | None, *, policy: ValuePolicy[str]) -> float | None

Return only the scalar selected by an element-domain policy.

Parameters:

Name Type Description Default
symbol str | None

Symbol-like element token, or None. D/T map to H.

 required
policy ValuePolicy[str]

Element-domain scalar policy to apply.

 required

Returns:

Type Description
float | None

The selected finite scalar in the policy's target units, or None when resolution is missing.

Raises:

Type Description
DatasetError

If a referenced dataset is unknown or non-scalar.
PolicyError

If transfer configuration or nested resolution is invalid.