Skip to content

atomref.transfer

Transfer models describe how missing target values may be restored from other sources.

In the current runtime the built-in models are:

A transfer source may be:

  • a packaged dataset reference,
  • a custom ElementScalarSet,
  • a generic ValuePolicy,
  • a wrapper policy that exposes as_value_policy().

LinearTransfer currently accepts exactly one predictor source at runtime, even though the public API stores predictors as a tuple for forward compatibility.

For policy-backed linear predictors, LinearTransfer separates two questions:

  • which nested predictor values may be used to fit the linear model (fit_sources, fit_max_depth), and
  • which nested predictor values may be used to predict the final requested element (prediction_sources, prediction_max_depth).

The defaults are intentionally conservative:

  • fit only on nested predictor values that came directly from base or override,
  • but allow one additional nested transfer step when evaluating the predictor for the requested element.

That default is meant for workflows such as a sparse X–H target set correlated against a partial covalent-radii policy that is itself completed from a broader support set.

atomref.transfer

Transfer-model configuration types for policy-based lookup.

TransferValueSource module-attribute 

TransferValueSource = Literal['override', 'base', 'transfer_substitution', 'transfer_linear', 'fallback']

Source labels admitted into nested linear-transfer workflows.

TransferModel module-attribute 

TransferModel = SubstitutionTransfer | LinearTransfer

Closed union of transfer models supported by the core resolver.

SupportsValuePolicy

Bases: Protocol

Protocol for wrappers that expose a generic scalar value policy.

Notes

RadiiPolicy and XHPolicy implement this structural protocol. Custom wrappers need not inherit from it; providing a compatible as_value_policy() method is enough.

as_value_policy 

as_value_policy() -> 'ValuePolicy[str]'

Return the generic element-domain value policy.

Returns:

Type Description
'ValuePolicy[str]'

A ValuePolicy over canonical element symbols.

LinearFit dataclass 

LinearFit(coefficients: tuple[float, ...], intercept: float, n_points: int, r2: float, rmse: float)

Summary statistics for a fitted linear transfer model.

Parameters are stored in a compact, serializable form so they can be attached to LookupResult objects and reused in reporting code.

Attributes:

Name Type Description
coefficients tuple[float, ...]

Fitted slopes, one per predictor. The current runtime uses exactly one predictor. Units are target units divided by the corresponding predictor units.
intercept float

Fitted intercept in target-dataset units.
n_points int

Number of overlapping element values used in the fit.
r2 float

Dimensionless coefficient of determination.
rmse float

Root-mean-square residual in target-dataset units.

SubstitutionTransfer dataclass 

SubstitutionTransfer(source: ScalarDatasetLike | SupportsValuePolicy | ValuePolicy[str])

Use another dataset or policy directly when the base dataset is missing.

The selected value is copied from the source rather than inferred.

Attributes:

Name Type Description
source ScalarDatasetLike | SupportsValuePolicy | ValuePolicy[str]

Packaged scalar reference, custom ElementScalarSet, generic ValuePolicy, or compatible wrapper policy.

Examples:

>>> from atomref import DatasetRef, SubstitutionTransfer
>>> transfer = SubstitutionTransfer(
...     source=DatasetRef("covalent_radius", "csd_legacy_cov")
... )
Notes

Source and target values must use compatible units. The policy engine does not perform dimensional conversion.

LinearTransfer dataclass 

LinearTransfer(predictors: tuple[ScalarDatasetLike | SupportsValuePolicy | ValuePolicy[str], ...], min_points: int = 2, exclude_placeholders: bool = True, fit_sources: tuple[TransferValueSource, ...] = _DEFAULT_LINEAR_FIT_SOURCES, prediction_sources: tuple[TransferValueSource, ...] = _DEFAULT_LINEAR_PREDICTION_SOURCES, fit_max_depth: int = 0, prediction_max_depth: int = 1)

Infer missing target values from one or more predictor datasets or policies.

In the current implementation the public API stores predictors as a tuple for forward compatibility, but the runtime intentionally accepts exactly one predictor source.

Attributes:

Name Type Description
predictors tuple[ScalarDatasetLike | SupportsValuePolicy | ValuePolicy[str], ...]

Predictor sources. The tuple must be nonempty, and the current resolver supports exactly one predictor at evaluation time.
min_points int

Minimum overlapping fit values. Must be at least 2 and defaults to 2.
exclude_placeholders bool

Whether declared placeholder values are excluded from fitting. Defaults to True.
fit_sources tuple[TransferValueSource, ...]

Nested predictor result sources admitted to fitting. Defaults to direct "base" and "override" values.
prediction_sources tuple[TransferValueSource, ...]

Nested result sources admitted when predicting the requested element. Defaults to base, override, substitution, and linear-transfer values.
fit_max_depth int

Maximum nested transfer depth admitted to fitting. Defaults to 0 and must be nonnegative.
prediction_max_depth int

Maximum nested transfer depth admitted for the requested prediction. Defaults to 1 and must be nonnegative.

Raises:

Type Description
PolicyError

If predictors are empty, min_points is below 2, a source control is empty or unknown, or either depth limit is negative.

Examples:

>>> from atomref import DatasetRef, LinearTransfer
>>> transfer = LinearTransfer(
...     predictors=(DatasetRef("atomic_radius", "rahm2016"),)
... )
Notes

Fit controls and prediction controls are independent. Predictor and target units must be internally consistent; no unit conversion is performed.