atomref.proatoms

This module exposes the neutral-density and two-mode pairwise API:

ProatomicDensityProfile and ProatomicDensitySet for immutable radial data;
get_proatomic_density() for scalar positive-region log-log evaluation;
estimate_proatomic_boundary() for the stable default divider;
estimate_promolecular_density_minimum() for the optional cutoff-bounded, resolution-limited minimum proxy;
estimate_ias_position() for explicit mode dispatch;
IASPositionResult for coordinates, statuses, cutoff/search diagnostics, units, and provenance.

See the proatomic-density guide for source identity, units, the 20-bohr range, fixed cutoff, mode selection, statuses, and limitations.

atomref.proatoms

Neutral spherical proatomic-density profiles and scalar evaluation.

DEFAULT_PROATOMIC_DENSITY_SET `module-attribute`

DEFAULT_PROATOMIC_DENSITY_SET = 'pbe0_sfx2c_dyallv4z_h-lr_neutral_v2'

Identifier of the default packaged neutral proatomic-density set.

BOHR_TO_ANGSTROM `module-attribute`

BOHR_TO_ANGSTROM = 0.529177210903

Bohr radius in angstrom, used for public coordinate conversion.

PROATOMIC_TAIL_CUTOFF `module-attribute`

PROATOMIC_TAIL_CUTOFF = 0.0001

Fixed per-atom tail cutoff in electron/bohr^3 for pairwise estimates.

IAS_MINIMUM_RESOLUTION_BOHR `module-attribute`

IAS_MINIMUM_RESOLUTION_BOHR = 0.01

Declared spatial resolution of the practical minimum search, in bohr.

ProatomicDensitySet `module-attribute`

ProatomicDensitySet = ElementRadialSet

Loaded immutable element-indexed proatomic-density dataset.

IASPositionResult `dataclass`

IASPositionResult(atom_a: str, atom_b: str, distance: float, distance_unit: str, density_unit: str, requested_mode: _IASRequestedMode, method: _IASMethod, status: _IASStatus, position_from_a: float | None, position_from_b: float | None, fraction_from_a: float | None, rho_a: float | None, rho_b: float | None, rho_sum: float | None, cutoff_density: float, cutoff_radius_a: float, cutoff_radius_b: float, contour_separation: float, cutoff_regime: _CutoffRegime, dominant_atom: str | None, dominant_atom_role: _DominantAtomRole | None, alternative_position_from_a: float | None, alternative_position_from_b: float | None, alternative_rho_sum: float | None, relative_depth_gap: float | None, ambiguous: bool, search_resolution: float | None, search_converged: bool | None, search_passes: int | None, dataset_id: str, interpolation_contract: str, pairwise_contract: str, coordinate_orientation: str = 'from_atom_a_toward_atom_b')

Immutable result of one pairwise neutral-proatom estimate.

Attributes:

Name	Type	Description
`atom_a`	`str`	Canonical symbol of the first requested atom.
`atom_b`	`str`	Canonical symbol of the second requested atom.
`distance`	`float`	Requested positive pair distance, no greater than 20 bohr after conversion.
`distance_unit`	`str`	Unit used by `distance`, coordinates, cutoff radii, contour separation, and search resolution: `"angstrom"` or `"bohr"`.
`density_unit`	`str`	Unit used by all density-valued fields: `"electron/bohr^3"` or `"electron/angstrom^3"`.
`requested_mode`	`_IASRequestedMode`	Requested `"boundary"` or `"minimum"` policy.
`method`	`_IASMethod`	Actual construction: symmetry midpoint, equal-proatom divider, cutoff-gap midpoint, promolecular minimum, or `"none"`.
`status`	`_IASStatus`	Scientific and numerical outcome. Callers should inspect this together with `method` and `position_from_a`.
`position_from_a`	`float \| None`	Primary coordinate measured from atom A toward atom B in `distance_unit`, or `None` for a typed non-result.
`position_from_b`	`float \| None`	Complementary coordinate measured from atom B in `distance_unit`, or `None`.
`fraction_from_a`	`float \| None`	`position_from_a / distance`, normally in [0, 1], or `None` when no coordinate is returned.
`rho_a`	`float \| None`	Atom A component density at the primary coordinate, or `None`.
`rho_b`	`float \| None`	Atom B component density at the primary coordinate, or `None`.
`rho_sum`	`float \| None`	Sum of the two components at the primary coordinate, or `None`.
`cutoff_density`	`float`	Fixed per-atom tail cutoff converted to `density_unit`.
`cutoff_radius_a`	`float`	Atom A radius at the fixed cutoff in `distance_unit`.
`cutoff_radius_b`	`float`	Atom B radius at the fixed cutoff in `distance_unit`.
`contour_separation`	`float`	Signed `distance - cutoff_radius_a - cutoff_radius_b` in `distance_unit`; positive values indicate a gap.
`cutoff_regime`	`_CutoffRegime`	`"overlap"`, `"contact"`, or `"gap"` according to the signed contour separation.
`dominant_atom`	`str \| None`	Canonical symbol of the atom that dominates an unlike interval, or `None`.
`dominant_atom_role`	`_DominantAtomRole \| None`	Whether `dominant_atom` is `"atom_a"` or `"atom_b"`, or `None`.
`alternative_position_from_a`	`float \| None`	Competitive alternative-minimum coordinate from atom A in `distance_unit`, or `None`.
`alternative_position_from_b`	`float \| None`	Complementary alternative coordinate from atom B in `distance_unit`, or `None`.
`alternative_rho_sum`	`float \| None`	Summed density at the alternative, or `None`.
`relative_depth_gap`	`float \| None`	Nonnegative dimensionless relative density gap between alternative and selected minima, or `None`.
`ambiguous`	`bool`	Whether a competitive resolved alternative meets the fixed relative-depth criterion.
`search_resolution`	`float \| None`	Finest minimum-search spacing in `distance_unit`, or `None` when minimum search is not applicable.
`search_converged`	`bool \| None`	Whether required minimum-search passes agreed, or `None` outside applicable minimum searches.
`search_passes`	`int \| None`	Number of practical minimum-search passes, or `None` when not applicable.
`dataset_id`	`str`	Canonical packaged proatomic-density dataset ID.
`interpolation_contract`	`str`	Stable radial interpolation identifier.
`pairwise_contract`	`str`	Stable cutoff and numerical-search identifier.
`coordinate_orientation`	`str`	Explicit orientation label. The default and current value is `"from_atom_a_toward_atom_b"`.

Notes

A valid but scientifically non-applicable request uses method="none" and leaves coordinate fields as None. Reversing the atoms maps each coordinate x to R - x, swaps A/B fields, and relabels dominance.

"boundary_dominated" takes status precedence over "search_unstable", which takes precedence over "ambiguous_competing_minima". Separate boolean diagnostics preserve the underlying conditions. Neither mode is an exact molecular QTAIM surface or critical-point calculation.

At an odd subnormal homonuclear distance, the mathematical midpoint may not be representable in binary64. The exposed coordinate then uses the ordinary R / 2 result and preserves the complementary distance.

ProatomicDensityProfile `dataclass`

ProatomicDensityProfile(dataset: ElementRadialSet, atomic_number: int)

Immutable view of one neutral spherical proatomic-density profile.

Attributes:

Name	Type	Description
`dataset`	`ElementRadialSet`	Immutable radial dataset owning the shared grid and profiles.
`atomic_number`	`int`	Selected integer atomic number. The packaged neutral set supports 1 (H) through 103 (Lr).
`symbol`	`str`	Canonical element symbol initialized from `atomic_number`.
`ref`	`DatasetRef`	Canonical registry reference for `dataset`.
`info`	`DatasetInfo`	Curated metadata and provenance for `dataset`.
`radii`	`tuple[float, ...]`	Shared immutable source grid in bohr, including the endpoint bracket above the public domain.
`densities`	`tuple[float, ...]`	Immutable sampled values in electron/bohr^3.
`interpolation_contract`	`str`	Stable identifier for evaluation behavior.
`public_max_radius_bohr`	`float`	Inclusive public radius limit in bohr; 20 for the packaged neutral H-Lr set.

Raises:

Type	Description
`DatasetError`	If the atomic number is invalid, the profile is absent, or radial data or metadata violate the interpolation contract.

Examples:

>>> profile = get_proatomic_density_profile("O")
>>> profile is not None
True
>>> profile(1.5, radius_unit="bohr") > 0.0
True

Notes

Evaluation is scalar and uses positive-region log-log interpolation. At the origin and below the first finite grid point, the first stored value is returned as a finite-grid convention, not an exact nuclear density.

densities `property`

densities: tuple[float, ...]

Return immutable stored density values.

Returns:

Type	Description
`tuple[float, ...]`	Positive sampled values in electron/bohr^3, aligned with `radii`.

info `property`

info: DatasetInfo

Return curated source metadata and provenance.

Returns:

Type	Description
`DatasetInfo`	Source DatasetInfo.

interpolation_contract `property`

interpolation_contract: str

Return the interpolation-contract identifier.

Returns:

Type	Description
`str`	`"loglog_positive_bracketed_v1"`.

public_max_radius_bohr `property`

public_max_radius_bohr: float

Return the inclusive public radius limit.

Returns:

Type	Description
`float`	Largest supported coordinate in bohr; 20 for the packaged neutral dataset.

radii `property`

radii: tuple[float, ...]

Return the shared immutable source grid.

Returns:

Type	Description
`tuple[float, ...]`	Positive radii in bohr, including the endpoint bracket above the 20-bohr public domain.

ref `property`

ref: DatasetRef

Return the canonical registry reference.

Returns:

Type	Description
`DatasetRef`	Source DatasetRef.

call

__call__(radius: float, *, radius_unit: Literal['angstrom', 'bohr'] = 'angstrom', density_unit: Literal['electron/bohr^3', 'electron/angstrom^3'] = 'electron/bohr^3') -> float

Evaluate the density; equivalent to evaluate.

Parameters:

Name	Type	Description	Default
`radius`	`float`	Finite coordinate from 0 through the public 20-bohr limit.	required
`radius_unit`	`Literal['angstrom', 'bohr']`	`"angstrom"` (default) or `"bohr"`.	`'angstrom'`
`density_unit`	`Literal['electron/bohr^3', 'electron/angstrom^3']`	`"electron/bohr^3"` (default) or `"electron/angstrom^3"`.	`'electron/bohr^3'`

Returns:

Type	Description
`float`	Finite positive interpolated density in `density_unit`.

Raises:

Type	Description
`ValueError`	If a unit or radius is outside the public contract.
`DatasetError`	If the stored radial data cannot support evaluation.

evaluate

evaluate(radius: float, *, radius_unit: Literal['angstrom', 'bohr'] = 'angstrom', density_unit: Literal['electron/bohr^3', 'electron/angstrom^3'] = 'electron/bohr^3') -> float

Evaluate the density at one radius.

Parameters:

Name	Type	Description	Default
`radius`	`float`	Finite scalar coordinate in `radius_unit`. It must map to the inclusive interval 0 through 20 bohr for the packaged set.	required
`radius_unit`	`Literal['angstrom', 'bohr']`	`"angstrom"` (default) or `"bohr"`.	`'angstrom'`
`density_unit`	`Literal['electron/bohr^3', 'electron/angstrom^3']`	`"electron/bohr^3"` (default) or `"electron/angstrom^3"`. This choice is independent of the coordinate unit.	`'electron/bohr^3'`

Returns:

Type	Description
`float`	Finite positive interpolated density in `density_unit`.

Raises:

Type	Description
`ValueError`	If a unit is unknown or `radius` is negative, non-finite, nonscalar, or above the public limit.
`DatasetError`	If the stored radial grid cannot bracket evaluation.

Examples:

>>> profile = get_proatomic_density_profile("O")
>>> profile is not None
True
>>> profile.evaluate(0.75) > 0.0
True

list_proatomic_density_sets

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

List packaged proatomic-density dataset identifiers.

Returns:

Type	Description
`tuple[str, ...]`	Canonical set IDs in curated registry order.

Raises:

Type	Description
`DatasetError`	If registry metadata is unavailable or malformed.

list_proatomic_density_set_infos

list_proatomic_density_set_infos() -> tuple[DatasetInfo, ...]

Return metadata for all packaged proatomic-density datasets.

Returns:

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

Raises:

Type	Description
`DatasetError`	If registry metadata is unavailable or malformed.

get_proatomic_density_set_info

get_proatomic_density_set_info(set_id: str = DEFAULT_PROATOMIC_DENSITY_SET) -> DatasetInfo

Return metadata for one packaged proatomic-density dataset.

Parameters:

Name	Type	Description	Default
`set_id`	`str`	Canonical set ID or accepted alias. Defaults to DEFAULT_PROATOMIC_DENSITY_SET.	`DEFAULT_PROATOMIC_DENSITY_SET`

Returns:

Type	Description
`DatasetInfo`	Curated method, units, provenance, coverage, and storage metadata.

Raises:

Type	Description
`DatasetError`	If the set is unknown or metadata is malformed.

get_proatomic_density_set

get_proatomic_density_set(set_id: str = DEFAULT_PROATOMIC_DENSITY_SET) -> ProatomicDensitySet

Return one cached immutable packaged proatomic-density dataset.

Parameters:

Name	Type	Description	Default
`set_id`	`str`	Canonical set ID or accepted alias. Defaults to DEFAULT_PROATOMIC_DENSITY_SET.	`DEFAULT_PROATOMIC_DENSITY_SET`

Returns:

Type	Description
`ProatomicDensitySet`	Element-indexed neutral profiles sharing one radial grid.

Raises:

Type	Description
`DatasetError`	If the set is unknown, malformed, or has a scalar rather than radial payload.

get_proatomic_density_profile

get_proatomic_density_profile(element: str | int | None, *, set_id: str = DEFAULT_PROATOMIC_DENSITY_SET) -> ProatomicDensityProfile | None

Return a cached neutral profile, or None for unsupported elements.

Parameters:

Name	Type	Description	Default
`element`	`str \| int \| None`	Element symbol, integer atomic number, or `None`. D/T map to hydrogen's electronic profile; booleans are rejected.	required
`set_id`	`str`	Canonical set ID or accepted alias. Defaults to DEFAULT_PROATOMIC_DENSITY_SET.	`DEFAULT_PROATOMIC_DENSITY_SET`

Returns:

Type	Description
`ProatomicDensityProfile \| None`	A cached ProatomicDensityProfile, or `None` for an invalid, unsupported, or uncovered element. The packaged set covers H through Lr.

Raises:

Type	Description
`DatasetError`	If the selected dataset is unknown, malformed, or non-radial.

Examples:

>>> get_proatomic_density_profile(8).symbol
'O'
>>> get_proatomic_density_profile("Og") is None
True

Notes

No neighboring-element substitution, correlation, ionic selection, or scalar ValuePolicy is applied.

get_proatomic_density

get_proatomic_density(element: str | int | None, radius: float, *, set_id: str = DEFAULT_PROATOMIC_DENSITY_SET, radius_unit: Literal['angstrom', 'bohr'] = 'angstrom', density_unit: Literal['electron/bohr^3', 'electron/angstrom^3'] = 'electron/bohr^3') -> float | None

Evaluate one neutral proatomic density, or return None if absent.

Parameters:

Name	Type	Description	Default
`element`	`str \| int \| None`	Element symbol, integer atomic number, or `None`. D/T map to H.	required
`radius`	`float`	Finite nonnegative scalar coordinate in `radius_unit`, no greater than 20 bohr after conversion.	required
`set_id`	`str`	Canonical set ID or alias. Defaults to the packaged neutral set.	`DEFAULT_PROATOMIC_DENSITY_SET`
`radius_unit`	`Literal['angstrom', 'bohr']`	`"angstrom"` (default) or `"bohr"`.	`'angstrom'`
`density_unit`	`Literal['electron/bohr^3', 'electron/angstrom^3']`	`"electron/bohr^3"` (default) or `"electron/angstrom^3"`.	`'electron/bohr^3'`

Returns:

Type	Description
`float \| None`	Finite positive scalar density in `density_unit`, or `None` for an invalid, unsupported, or uncovered element.

Raises:

Type	Description
`ValueError`	If a unit is unknown or the radius is negative, non-finite, nonscalar, or above 20 bohr after conversion.
`DatasetError`	If the selected dataset is unknown, malformed, or non-radial.

Examples:

>>> rho = get_proatomic_density("O", 0.75)
>>> rho is not None and rho > 0.0
True

Notes

Radius and density units are independent. Evaluation is scalar and dependency-free, with no extrapolation beyond 20 bohr.

estimate_proatomic_boundary

estimate_proatomic_boundary(atom_a: str | int | None, atom_b: str | int | None, distance: float, *, distance_unit: Literal['angstrom', 'bohr'] = 'angstrom', density_unit: Literal['electron/bohr^3', 'electron/angstrom^3'] = 'electron/bohr^3', set_id: str = DEFAULT_PROATOMIC_DENSITY_SET) -> IASPositionResult | None

Estimate a stable pairwise neutral-proatom boundary.

Parameters:

Name	Type	Description	Default
`atom_a`	`str \| int \| None`	First element symbol or atomic number. D/T map to H.	required
`atom_b`	`str \| int \| None`	Second element symbol or atomic number. D/T map to H.	required
`distance`	`float`	Finite positive pair distance in `distance_unit`, no greater than 20 bohr after conversion.	required
`distance_unit`	`Literal['angstrom', 'bohr']`	`"angstrom"` (default) or `"bohr"`. Returned coordinates and cutoff radii use the same unit.	`'angstrom'`
`density_unit`	`Literal['electron/bohr^3', 'electron/angstrom^3']`	`"electron/bohr^3"` (default) or `"electron/angstrom^3"` for reported density fields.	`'electron/bohr^3'`
`set_id`	`str`	Canonical proatomic-density set ID or alias. Defaults to DEFAULT_PROATOMIC_DENSITY_SET.	`DEFAULT_PROATOMIC_DENSITY_SET`

Returns:

Type	Description
`IASPositionResult \| None`	An IASPositionResult oriented from atom A toward atom B, or `None` when either profile is invalid or unavailable. A valid one-atom-dominance case returns a typed result with no coordinate.

Raises:

Type	Description
`ValueError`	If distance or a unit is outside the public contract.
`DatasetError`	If the selected dataset is unknown, malformed, or non-radial.

Examples:

>>> result = estimate_proatomic_boundary("C", "O", 1.5)
>>> result is not None
True
>>> result.requested_mode
'boundary'

Notes

Homonuclear pairs use the exact midpoint. Overlapping unlike profiles use equal neutral-proatom density; separated fixed-cutoff contours use the midpoint of their gap. This stable divider is not a molecular QTAIM zero-flux surface.

estimate_promolecular_density_minimum

estimate_promolecular_density_minimum(atom_a: str | int | None, atom_b: str | int | None, distance: float, *, distance_unit: Literal['angstrom', 'bohr'] = 'angstrom', density_unit: Literal['electron/bohr^3', 'electron/angstrom^3'] = 'electron/bohr^3', set_id: str = DEFAULT_PROATOMIC_DENSITY_SET) -> IASPositionResult | None

Estimate one practically resolved promolecular line-density minimum.

Parameters:

Name	Type	Description	Default
`atom_a`	`str \| int \| None`	First element symbol or atomic number. D/T map to H.	required
`atom_b`	`str \| int \| None`	Second element symbol or atomic number. D/T map to H.	required
`distance`	`float`	Finite positive pair distance in `distance_unit`, no greater than 20 bohr after conversion.	required
`distance_unit`	`Literal['angstrom', 'bohr']`	`"angstrom"` (default) or `"bohr"`. Returned coordinates and search resolution use the same unit.	`'angstrom'`
`density_unit`	`Literal['electron/bohr^3', 'electron/angstrom^3']`	`"electron/bohr^3"` (default) or `"electron/angstrom^3"` for reported density fields.	`'electron/bohr^3'`
`set_id`	`str`	Canonical proatomic-density set ID or alias. Defaults to DEFAULT_PROATOMIC_DENSITY_SET.	`DEFAULT_PROATOMIC_DENSITY_SET`

Returns:

Type	Description
`IASPositionResult \| None`	An IASPositionResult oriented from atom A toward atom B, or `None` when either profile is invalid or unavailable. A valid pair with no resolved strict-interior minimum returns a typed result with no coordinate.

Raises:

Type	Description
`ValueError`	If distance or a unit is outside the public contract.
`DatasetError`	If the selected dataset is unknown, malformed, or non-radial.

Examples:

>>> result = estimate_promolecular_density_minimum("C", "O", 1.5)
>>> result is not None
True
>>> result.requested_mode
'minimum'

Notes

Search is confined to the interval where both neutral components meet PROATOMIC_TAIL_CUTOFF. It has declared resolution IAS_MINIMUM_RESOLUTION_BOHR, exposes only strict-interior unlike-atom candidates, and never falls back to boundary mode. It is a practical neutral-promolecular proxy, not an exact molecular-density critical point.

estimate_ias_position

estimate_ias_position(atom_a: str | int | None, atom_b: str | int | None, distance: float, *, mode: Literal['boundary', 'minimum'] = 'boundary', distance_unit: Literal['angstrom', 'bohr'] = 'angstrom', density_unit: Literal['electron/bohr^3', 'electron/angstrom^3'] = 'electron/bohr^3', set_id: str = DEFAULT_PROATOMIC_DENSITY_SET) -> IASPositionResult | None

Dispatch explicitly to one pairwise neutral-proatom mode.

Parameters:

Name	Type	Description	Default
`atom_a`	`str \| int \| None`	First element symbol or atomic number. D/T map to H.	required
`atom_b`	`str \| int \| None`	Second element symbol or atomic number. D/T map to H.	required
`distance`	`float`	Finite positive pair distance in `distance_unit`, no greater than 20 bohr after conversion.	required
`mode`	`Literal['boundary', 'minimum']`	`"boundary"` (default) or `"minimum"`.	`'boundary'`
`distance_unit`	`Literal['angstrom', 'bohr']`	`"angstrom"` (default) or `"bohr"`.	`'angstrom'`
`density_unit`	`Literal['electron/bohr^3', 'electron/angstrom^3']`	`"electron/bohr^3"` (default) or `"electron/angstrom^3"`.	`'electron/bohr^3'`
`set_id`	`str`	Canonical proatomic-density set ID or alias. Defaults to DEFAULT_PROATOMIC_DENSITY_SET.	`DEFAULT_PROATOMIC_DENSITY_SET`

Returns:

Type	Description
`IASPositionResult \| None`	The same IASPositionResult or missing-profile `None` produced by the corresponding direct estimator.

Raises:

Type	Description
`ValueError`	If `mode`, distance, or a unit is outside the public contract.
`DatasetError`	If the selected dataset is unknown, malformed, or non-radial.

Examples:

>>> direct = estimate_proatomic_boundary("C", "O", 1.5)
>>> selected = estimate_ias_position("C", "O", 1.5)
>>> selected == direct
True

Notes

The minimum mode never silently falls back to boundary mode. The two modes are related scientific approximations, not interchangeable names for one calculation.

atomref.proatoms