atomref

Documentation: https://delonecommons.github.io/atomref

atomref provides cited atomic properties and frozen spherical free-atom electron densities through a small Python API for crystallographic, quantum-chemical, and molecular-structure algorithms.

Use it when your software needs dependable atomic radii, X–H reference lengths, neutral proatomic densities, or pairwise reference-atom boundaries without embedding another project-local table and its fallback rules. The core runtime is pure Python and has no required third-party dependencies.

Install and get a useful result

pip install atomref

import atomref as ar

covalent_c = ar.get_covalent_radius("C")
xh_n = ar.get_xh_bond_length("N")
rho_o = ar.get_proatomic_density("O", 0.75)
boundary = ar.estimate_proatomic_boundary("C", "O", 1.43)
minimum = ar.estimate_promolecular_density_minimum("C", "O", 1.43)

The scalar results above are in documented units: radii and X–H lengths use angstrom, while the density call returns electron/bohr³ by default. Pairwise coordinates are measured from the first atom toward the second. For this C–O example, boundary is the stable equal-proatom divider and minimum is the optional, resolution-limited minimum of the summed promolecular line density.

Start with the quickstart or open the complete API reference.

What it solves

• Bond and contact geometry: select named covalent and van der Waals radii instead of scattering constants through structure code.
• Hydrogen normalization: obtain provisional, provenance-aware X–H target lengths keyed by the parent element.
• Incomplete reference tables: use explicit substitution or fitted transfer policies and inspect how a value was obtained.
• Free-atom density sampling: evaluate immutable neutral H–Lr spherical profiles with explicit coordinate and density units over a strict 0–20 bohr domain.
• Pairwise reference-atom models: choose a stable proatomic boundary or an explicitly cutoff-bounded promolecular-minimum proxy without presenting either as an exact molecular QTAIM surface.

Most convenience functions come in two forms:

>>> import atomref as ar
>>> ar.get_vdw_radius("Pm")
2.8972265395148358
>>> result = ar.lookup_vdw_radius("Pm")
>>> result.source, result.transfer_depth
('transfer_linear', 1)
>>> result.resolved_from
(DatasetRef(quantity='atomic_radius', set_id='rahm2016'),)

get_* returns the selected number. lookup_* returns a typed LookupResult with the source, supporting datasets, placeholder state, fit information, and transfer depth.

Why adopt atomref?

A local constants file is easy to start and difficult to maintain. It usually accumulates uncited values, silent replacements for missing elements, ambiguous units, and behavior that cannot be reviewed independently of the consuming algorithm. atomref keeps those concerns in one versioned layer:

• every packaged dataset has a stable identifier, coverage metadata, and bibliographic provenance;
• lookup rules are explicit and deterministic rather than hidden in callers;
• direct, substituted, fitted, fallback, placeholder, and missing results stay distinguishable;
• public types, units, valid ranges, and failure behavior are documented;
• packaged data and attribution are checked in both wheel and source distributions;
• the dependency-free runtime can be embedded in lightweight scientific tools.

The package does not claim that one table or policy is universally correct. It makes the selected reference and the assumptions around it visible.

Installation choices

The base install is sufficient for every runtime API:

pip install atomref

Install the notebooks extra to execute or render the shipped Jupyter examples and their plots:

pip install "atomref[notebooks]"

Install every optional dependency declared by the project with:

pip install "atomref[all]"

all is the exact union of test, notebooks, docs, and dev, so it is appropriate for a complete contributor or release environment. See the installation guide for the narrower groups.

Data, provenance, and scientific scope

The scalar catalog includes named covalent, van der Waals, atomic-isodensity, and provisional X–H datasets. Registry metadata separates the requested quantity from scientific classification and from whether a dataset is a direct target or transfer support.

The neutral proatomic profiles are a deterministic packaged snapshot of the atomref-proatoms 2.0.0 dataset pbe0_sfx2c_dyallv4z_h-lr_spherical_v2. They cover H–Lr and record the PBE0, self-consistent spherical fractional-occupation UKS, spin-free one-electron X2C, and dyall-v4z definition, source hashes, CC BY 4.0 data license, and both concept and version-specific DOIs.

These profiles are isolated, neutral, spherical reference atoms—not molecular electron densities. Density evaluation is scalar, and the public radius domain is exactly 0–20 bohr. Pairwise boundary mode is the stable default. Optional minimum mode searches only where both proatoms remain above 1e-4 electron/bohr^3, has a declared 0.01 bohr resolution, and may return a typed diagnostic without a coordinate.

• Dataset catalog and provenance
• Proatomic-density and pairwise scientific guide
• Policy guide
• Explicit non-goals

Citation and licenses

Cite atomref as software using the repository-level CITATION.cff. There is no preferred paper citation; the versioned software release is the canonical object to cite.

Except for separately identified material, the software and accompanying repository content are licensed under LGPL-3.0-or-later. The bundled neutral proatomic-density snapshot is licensed separately under CC BY 4.0. NOTICE.md records the exact boundary, attribution, and source DOIs. The packaged registry metadata records the exact source commit and SHA-256 hashes.

Executable notebook documentation

The documentation renders the actual committed .ipynb files directly, including Markdown, code, mathematics, saved text, and saved PNG plots. Site builds do not execute or rewrite them; separate bounded Jupyter workers verify temporary copies without retaining their results.

• Notebook overview
• Quickstart notebook
• Policies and assessment notebook
• Custom sets and discovery notebook
• IAS method-selection study
• Proatomic density and IAS workflows

Dataset and policy discovery

The lower-level registry is available when an application needs to choose or report an exact source:

>>> import atomref as ar
>>> ar.list_quantities()
('covalent_radius', 'van_der_waals_radius', 'atomic_radius', 'xh_bond_length', 'proatomic_density')
>>> [info.ref.set_id for info in ar.list_dataset_infos(
...     "van_der_waals_radius", usage_role="target"
... )]
['bondi1964', 'rowland_taylor1996', 'alvarez2013', 'chernyshov2020']
>>> profile_info = ar.get_proatomic_density_set_info()
>>> profile_info.ref.set_id
'pbe0_sfx2c_dyallv4z_h-lr_neutral_v2'

Custom element-indexed scalar sets can participate in the same policy layer. Radial profiles deliberately do not: no scalar ValuePolicy, neighboring- element substitution, or fitted correlation is applied to density data.

Use in scientific software

atomref is a standalone package for physicochemical and structural-analysis software that needs curated atomic properties, proatomic densities, or explicit reference-data policy. Purely mathematical packages can remain independent of those choices until a consuming application needs atomic context.

Maintainer checks

The repository keeps a small set of release tools:

• python tools/check_registry.py validates registry metadata against every packaged scalar and radial payload;
• python tools/check_notebooks.py smoke-executes each temporary notebook copy in its own bounded standard Jupyter process, then discards the results;
• python tools/gen_readme.py regenerates this README from docs/index.md;
• python tools/release_check.py runs lint, tests, strict docs, distribution checks, and clean artifact-installation checks.

See the tools README for the maintainer-only data snapshot workflow and command details.

---

This README is generated from docs/index.md.

To regenerate it:

python tools/gen_readme.py

Edit the documentation sources instead of editing README.md directly.