atomref.registry

This module contains the packaged data model.

If you want to understand how atomref classifies datasets, how aliases are resolved, or how built-in scalar CSV and radial ZIP/CSV payloads become typed in-memory objects, this is the key module to read.

The most important registry ideas are:

• quantity — the operational property family,
• domain — the key space used to index that quantity,
• dataset — one curated named source payload inside the quantity.

In the current runtime, the implemented lookup domain is element. The registry still stores domain explicitly because the metadata design is meant to stay reusable as the package grows.

get_builtin_set() dispatches element_scalar_csv and element_radial_csv_zip storage and returns the BuiltinSet union. Policy consumers explicitly narrow that result to ElementScalarSet; radial profiles do not participate in scalar policy or transfer behavior.

atomref.registry

Dataset registry and packaged element-set loading.

QuantityId module-attribute

QuantityId = str

Typing alias for a registry quantity identifier.

DomainId module-attribute

DomainId = str

Typing alias for a registry lookup-domain identifier.

BuiltinSet module-attribute

BuiltinSet = ElementScalarSet | ElementRadialSet

Union of packaged scalar and radial dataset payloads.

ScalarDatasetLike module-attribute

ScalarDatasetLike = DatasetRef | ElementScalarSet

Typing alias for packaged references and custom scalar datasets.

DatasetRef dataclass

DatasetRef(quantity: QuantityId, set_id: str)

Stable reference to a packaged dataset.

Attributes:

Name	Type	Description
quantity	QuantityId	Operational property family, such as "covalent_radius" or "proatomic_density".
set_id	str	Canonical dataset identifier or an accepted alias when the reference is passed to a registry lookup.

Examples:

>>> DatasetRef("covalent_radius", "cordero2008")
DatasetRef(quantity='covalent_radius', set_id='cordero2008')

Reference dataclass

Reference(authors: str | None = None, year: int | None = None, title: str | None = None, venue: str | None = None, doi: str | None = None, url: str | None = None, publisher: str | None = None, note: str | None = None)

Bibliographic record attached to packaged dataset metadata.

Attributes:

Name	Type	Description
authors	str | None	Author string as recorded by the curated metadata.
year	int | None	Publication year.
title	str | None	Work title.
venue	str | None	Journal, repository, or other publication venue.
doi	str | None	DOI without an implied URL prefix.
url	str | None	Source or publication URL.
publisher	str | None	Publisher or archive name.
note	str | None	Additional attribution or interpretation note.

CoverageInfo dataclass

CoverageInfo(n_values: int, z_min: int | None = None, z_max: int | None = None, has_placeholders: bool = False, covered_z: tuple[int, ...] = (), missing_z: tuple[int, ...] = ())

Coverage summary for an element-indexed dataset.

Attributes:

Name	Type	Description
n_values	int	Number of non-missing element values or profiles.
z_min	int | None	Lowest covered atomic number, or None for empty coverage.
z_max	int | None	Highest covered atomic number, or None for empty coverage.
has_placeholders	bool	Whether at least one covered scalar equals the dataset's declared placeholder value.
covered_z	tuple[int, ...]	Covered atomic numbers in increasing order.
missing_z	tuple[int, ...]	Missing atomic numbers in increasing order.

QuantityInfo dataclass

QuantityInfo(quantity: QuantityId, domain: DomainId, units: str | None = None, description: str | None = None)

Metadata shared by all datasets that belong to one quantity.

Attributes:

Name	Type	Description
quantity	QuantityId	Registry quantity identifier.
domain	DomainId	Lookup domain. The current resolver supports "element".
units	str | None	Scientific units shared by the quantity, or None when the quantity is unitless or unspecified.
description	str | None	Human-readable quantity description.

DatasetInfo dataclass

DatasetInfo(ref: DatasetRef, domain: DomainId, units: str | None, name: str, description: str | None = None, usage_role: str | None = None, semantic_class: str | None = None, origin_class: str | None = None, phase_context: str | None = None, method_summary: str | None = None, placeholder_value: float | None = None, extraction_source: str | None = None, aliases: tuple[str, ...] = (), references: tuple[Reference, ...] = (), notes: tuple[str, ...] = (), storage: Mapping[str, object] | None = None, coverage: CoverageInfo | None = None)

Curated metadata for one packaged dataset.

This object keeps operational classification such as ref.quantity and usage_role separate from scientific classification such as semantic_class and phase_context.

Attributes:

Name	Type	Description
ref	DatasetRef	Canonical quantity and dataset identifier.
domain	DomainId	Lookup domain, currently "element" for packaged data.
units	str | None	Units of stored scalar values or density profiles.
name	str	Human-readable dataset name.
description	str | None	Concise scientific description.
usage_role	str | None	Operational role such as "target" or "support".
semantic_class	str | None	Scientific class of the values.
origin_class	str | None	Origin category used during curation.
phase_context	str | None	Physical phase or environment associated with values.
method_summary	str | None	Concise computational or experimental method.
placeholder_value	float | None	Declared scalar placeholder, if one exists.
extraction_source	str | None	Record of the upstream extraction source.
aliases	tuple[str, ...]	Accepted alternative dataset identifiers.
references	tuple[Reference, ...]	Bibliographic and source records.
notes	tuple[str, ...]	Additional immutable metadata notes.
storage	Mapping[str, object] | None	Read-only packaged-storage description, or None for a custom in-memory set.
coverage	CoverageInfo | None	Element-coverage summary, when available.

ElementScalarSet dataclass

ElementScalarSet(ref: DatasetRef, info: DatasetInfo, values_by_z: tuple[float | None, ...])

Immutable element-indexed scalar dataset stored by atomic number.

Attributes:

Name	Type	Description
ref	DatasetRef	Dataset identity.
info	DatasetInfo	Curated metadata, including the scientific units.
values_by_z	tuple[float | None, ...]	Dense immutable tuple indexed by atomic number. Index zero is unused and missing elements contain None.

Notes

Scalar values have the units recorded by info.units. Policies and transfers do not perform unit conversion, so custom sources combined in one policy must use compatible units.

from_mapping classmethod

from_mapping(*, ref: DatasetRef, values: Mapping[str, float | None], name: str, units: str | None, description: str | None = None, usage_role: str = 'user', semantic_class: str = 'user', origin_class: str = 'user', phase_context: str | None = None, references: Iterable[Reference] = (), notes: Iterable[str] = (), placeholder_value: float | None = None) -> 'ElementScalarSet'

Build a custom element-domain dataset from a symbol-keyed mapping.

Parameters:

Name	Type	Description	Default
ref	DatasetRef	Stable identity for the custom dataset.	required
values	Mapping[str, float | None]	Element symbols mapped to finite scalar values or None. Symbols are canonicalized, and D/T map to H.	required
name	str	Human-readable dataset name.	required
units	str | None	Scientific units for every non-missing value, or None.	required
description	str | None	Optional scientific description.	None
usage_role	str	Operational role. Defaults to "user".	'user'
semantic_class	str	Scientific classification. Defaults to "user".	'user'
origin_class	str	Origin classification. Defaults to "user".	'user'
phase_context	str | None	Optional physical phase or environment.	None
references	Iterable[Reference]	Bibliographic records to preserve with the set.	()
notes	Iterable[str]	Additional metadata notes.	()
placeholder_value	float | None	Optional finite scalar used as a placeholder.	None

Returns:

Type	Description
'ElementScalarSet'	A frozen ElementScalarSet with coverage metadata computed for the packaged periodic table.

Raises:

Type	Description
DatasetError	If an element key is invalid, two keys normalize to the same element, or a value is not finite.

Examples:

>>> custom = ElementScalarSet.from_mapping(
...     ref=DatasetRef("covalent_radius", "my_set"),
...     values={"C": 0.76, "O": 0.66},
...     name="My radii",
...     units="angstrom",
... )
>>> custom.get("O")
0.66

get

get(symbol: str | None) -> float | None

Return one element's scalar value.

Parameters:

Name	Type	Description	Default
symbol	str | None	Symbol-like element token, or None. D/T map to H.	required

Returns:

Type	Description
float | None	The stored scalar in info.units, or None for an invalid or uncovered element.

ElementRadialSet dataclass

ElementRadialSet(ref: DatasetRef, info: DatasetInfo, radii: tuple[float, ...], profiles_by_z: tuple[tuple[float, ...] | None, ...])

Immutable element-indexed radial profiles sampled on one shared grid.

Attributes:

Name	Type	Description
ref	DatasetRef	Dataset identity.
info	DatasetInfo	Curated metadata and storage description.
radii	tuple[float, ...]	Shared immutable radial grid in the storage-declared coordinate unit.
profiles_by_z	tuple[tuple[float, ...] | None, ...]	Dense immutable tuple of profiles indexed by atomic number. Index zero is unused and missing profiles contain None.

get

get(element: str | int | None) -> tuple[float, ...] | None

Return the immutable sampled profile for one element.

Parameters:

Name	Type	Description	Default
element	str | int | None	Symbol-like token, integer atomic number, or None. D/T map to H; booleans are rejected despite being integer subclasses.	required

Returns:

Type	Description
tuple[float, ...] | None	The stored profile in the density units described by info, or None for an invalid or uncovered element.

list_quantities

list_quantities() -> tuple[str, ...]

List packaged quantity identifiers in registry order.

Returns:

Type	Description
tuple[str, ...]	Canonical quantity identifiers in their curated registry order.

Raises:

Type	Description
DatasetError	If the packaged registry is unavailable or malformed.

get_quantity_info

get_quantity_info(quantity: QuantityId) -> QuantityInfo

Return quantity-level metadata for a packaged quantity.

Parameters:

Name	Type	Description	Default
quantity	QuantityId	Canonical registry quantity identifier.	required

Returns:

Type	Description
QuantityInfo	Immutable QuantityInfo for the requested quantity.

Raises:

Type	Description
DatasetError	If the quantity is unknown or its metadata is malformed.

Examples:

>>> get_quantity_info("covalent_radius").units
'angstrom'

list_dataset_ids

list_dataset_ids(quantity: QuantityId, *, usage_role: str | None = None) -> tuple[str, ...]

List packaged dataset identifiers for a quantity.

Parameters:

Name	Type	Description	Default
quantity	QuantityId	Canonical registry quantity identifier.	required
usage_role	str | None	Optional case-insensitive role filter, such as "target" or "support". None includes every role.	None

Returns:

Type	Description
tuple[str, ...]	Canonical dataset identifiers in curated registry order.

Raises:

Type	Description
DatasetError	If the quantity is unknown or registry metadata is malformed.

list_dataset_infos

list_dataset_infos(quantity: QuantityId, *, usage_role: str | None = None) -> tuple[DatasetInfo, ...]

Return packaged dataset metadata objects for a quantity.

Parameters:

Name	Type	Description	Default
quantity	QuantityId	Canonical registry quantity identifier.	required
usage_role	str | None	Optional case-insensitive role filter. None includes every role.	None

Returns:

Type	Description
tuple[DatasetInfo, ...]	Immutable DatasetInfo objects in curated registry order.

Raises:

Type	Description
DatasetError	If the quantity is unknown or registry metadata is malformed.

get_dataset_info

get_dataset_info(ref: DatasetRef) -> DatasetInfo

Return curated metadata for a packaged dataset reference.

Parameters:

Name	Type	Description	Default
ref	DatasetRef	Quantity and dataset identifier. Dataset aliases are accepted with Unicode-dash, case, and surrounding-whitespace normalization.	required

Returns:

Type	Description
DatasetInfo	Immutable metadata whose ref contains the canonical dataset ID.

Raises:

Type	Description
DatasetError	If the quantity or dataset is unknown, or registry metadata is malformed.

Examples:

>>> info = get_dataset_info(
...     DatasetRef("covalent_radius", "cordero2008")
... )
>>> info.units
'angstrom'

get_builtin_set

get_builtin_set(ref: DatasetRef) -> BuiltinSet

Load a scalar or radial packaged dataset through the shared registry.

Parameters:

Name	Type	Description	Default
ref	DatasetRef	Quantity and packaged dataset identifier or alias.	required

Returns:

Type	Description
BuiltinSet	A cached immutable ElementScalarSet or ElementRadialSet, chosen from the dataset's declared storage kind.

Raises:

Type	Description
DatasetError	If the reference is unknown, storage metadata is invalid, or the packaged payload fails validation.

Examples:

>>> loaded = get_builtin_set(
...     DatasetRef("covalent_radius", "cordero2008")
... )
>>> isinstance(loaded, ElementScalarSet)
True

Notes

Scalar policies narrow this union internally. Radial profiles never participate in substitution or linear-transfer policy behavior.