QCRef

Lightweight, dependency-free reference data for computational chemistry: CODATA physical constants, conversion factors, a periodic table, and solvent permittivities.

• Every value carries its source. Each number is a float with .source, .unit, .uncertainty, and .notes; the package refuses to load a value without a source.
• Data releases are versioned. CODATA releases live side by side (codata[2022]), and phys and the curated conversion factors always follow the latest.
• Adding data never requires code changes. All values live in CSV files with a metadata sidecar citing their source.

Formerly qcconst. pip install qcconst now installs qcref and warns on import; switch to import qcref.

Data Sources

Each piece of data contains a link to its source. Primary data sources include:

Installation

python -m pip install qcref

Quickstart

Each dataset in qcref is a collection keyed the same way everywhere:

• Every entry has exactly one key, stored in the dataset's CSV file: UPPER_SNAKE_CASE for constants and solvents, the element symbol (Ni) for the periodic table.
• collection.KEY and collection["KEY"] are equivalent and are the only ways to look up by key.
• collection.by_name(...) looks an entry up by its original source name, ignoring case.
• Every value carries .source, .unit, .uncertainty, and .notes.

Constants

>>> from qcref import constants

>>> constants.BOHR_TO_ANGSTROM
0.529177210544, unit=Å, uncertainty=8.2e-11, source=CODATA 2022: https://physics.nist.gov/cuu/Constants/Table/allascii.txt, name=BOHR_TO_ANGSTROM, notes=Computed as BOHR_RADIUS * 1e10.

# Use constants just like a float
>>> constants.BOHR_TO_ANGSTROM * 10
5.29177210544

>>> constants["BOHR_TO_ANGSTROM"].source
'CODATA 2022: https://physics.nist.gov/cuu/Constants/Table/allascii.txt'

>>> constants.as_list()[:4]
['BOHR_TO_ANGSTROM', 'ANGSTROM_TO_BOHR', 'HARTREE_TO_JOULE', 'AVOGADRO_NUMBER']

# Curated constants can also be imported directly
>>> from qcref.constants import HARTREE_TO_EV

All CODATA Physical Constants

Every CODATA release in the package is available as codata[<year>] (also constants.codata2022, ...). phys always points to the latest release, currently 2022. Keys are the UPPER_SNAKE_CASE form of the NIST quantity name; by_name accepts the NIST name itself.

>>> from qcref import phys

>>> phys.SPEED_OF_LIGHT_IN_VACUUM
299792458.0, unit=m s^-1, uncertainty=0.0, source=CODATA 2022: https://physics.nist.gov/cuu/Constants/Table/allascii.txt, name=speed of light in vacuum

>>> phys.by_name("atomic unit of permittivity")
1.1126500562e-10, unit=F m^-1, uncertainty=1.7e-20, source=CODATA 2022: https://physics.nist.gov/cuu/Constants/Table/allascii.txt, name=atomic unit of permittivity

Periodic Table

>>> from qcref import periodic_table as pt

>>> pt.Ni
Element(symbol='Ni', number=28, name='Nickel', ...)

>>> pt["Ni"] is pt.Ni
True

>>> pt.by_name("Nickel").number
28

Solvents

Solvent keys are the UPPER_SNAKE_CASE form of the CRC name. A leading locant is moved to the end, following the CAS index convention, so 1,4-Dioxane is DIOXANE_1_4.

>>> from qcref import solvents

>>> solvents.ACETONE
Solvent(name='Acetone', formula='C3H6O', dielectric=21.01, dielectric_temperature_k=293.15, ...)

>>> solvents.DIOXANE_1_4
Solvent(name='1,4-Dioxane', formula='C4H8O2', dielectric=2.2189, dielectric_temperature_k=293.15, ...)

>>> solvents.by_name("1,4-Dioxane") is solvents.DIOXANE_1_4
True

>>> solvents.ACETONE.dielectric_at(298.15)
20.49331470812499

The solvent dataset is generated from the CRC permittivity table. dielectric is the tabulated static relative permittivity, dielectric_temperature_k is the CRC superscript temperature converted from °C to K, and dielectric_at(T) evaluates the CRC polynomial fit when one is available.

Adding New Values

All data live in CSV files under src/qcref/data, one folder per dataset. Adding data never requires a code change:

• New entries: add a row to the dataset's CSV, including its key. Keys are UPPER_SNAKE_CASE (element symbols for the periodic table) and must be unique; the package refuses to import otherwise.
• New CODATA release: add data/codata/<year>.csv and <year>.meta.json. phys and every curated constant in data/constants/constants.csv automatically use the latest release, and older releases stay available as codata[<year>].
• New curated constants: add a row to data/constants/constants.csv with an expression over CODATA keys or earlier rows (e.g. BOHR_RADIUS * 1e10). Value, uncertainty, and source are computed from the inputs.

Every CSV has a <name>.meta.json sidecar with a required source (plus optional citation, notes, and per-column units). Values are stored exactly as published; conversions such as Å to Bohr happen at load time and are recorded in each value's notes. Every loaded value must have a source.

Keys are visible to type checkers and IDEs through the generated src/qcref/_keys.py, so pt.Ni autocompletes and a mistyped key is a mypy error. The pre-commit hook and the build regenerate it whenever data change (or run python build_tools/gen_keys.py); a test fails if it is stale.

Open a PR and that's it! ✨

The QC Suite of Programs

The QC Suite works in harmony to provide fast, structured, and interoperable quantum chemistry tools.

• qcref - Lightweight, dependency-free chemistry reference data (CODATA constants, periodic table, solvents) where every value carries its source.
• qcdata - Elegant and intuitive data structures for quantum chemistry, featuring seamless Jupyter Notebook visualizations. Documentation
• qcinf - Cheminformatics algorithms and structure utilities using standardized qcdata data structures.
• qccodec - A package for translating between standardized qcdata data structures and native QC program inputs and outputs.
• qccompute - A package for operating quantum chemistry programs using standardized qcdata data structures. Compatible with TeraChem, psi4, QChem, NWChem, ORCA, Molpro, geomeTRIC and many more.
• BigChem - A distributed application for running quantum chemistry calculations at scale across clusters of computers or the cloud. Bring multi-node scaling to your favorite quantum chemistry program.
• ChemCloud - A web application and associated Python client for exposing a BigChem cluster securely over the internet.