Metadata-Version: 2.5
Name: qcref
Version: 0.3.0
Summary: Lightweight, dependency-free chemistry reference data (CODATA constants, periodic table, solvents) where every value carries its source.
Project-URL: Homepage, https://github.com/atomsforhumanity/qcref
Project-URL: Documentation, https://github.com/atomsforhumanity/qcref#readme
Project-URL: Source, https://github.com/atomsforhumanity/qcref
Project-URL: Changelog, https://github.com/atomsforhumanity/qcref/blob/master/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/atomsforhumanity/qcref/issues
Author-email: Colton Hicks <github@coltonhicks.com>
License: The MIT License (MIT)
        
        Copyright (c) 2025 Colton Hicks
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
License-File: LICENSE
Keywords: chemistry,constants,conversion factors,periodic table,physics,reference data,scientific computing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# QCRef

[![image](https://img.shields.io/pypi/v/qcref.svg)](https://pypi.python.org/pypi/qcref)
[![image](https://img.shields.io/pypi/l/qcref.svg)](https://pypi.python.org/pypi/qcref)
[![image](https://img.shields.io/pypi/pyversions/qcref.svg)](https://pypi.python.org/pypi/qcref)
[![Actions status](https://github.com/atomsforhumanity/qcref/workflows/Tests/badge.svg)](https://github.com/atomsforhumanity/qcref/actions)
[![Actions status](https://github.com/atomsforhumanity/qcref/workflows/Basic%20Code%20Quality/badge.svg)](https://github.com/atomsforhumanity/qcref/actions)

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:
| Data Name | Source | Source Links |
| -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Physical Constants` | NIST 2022 CODATA | [Individual Constant Lookup](http://physics.nist.gov/constants), [Fundamenal Constants Listing](https://physics.nist.gov/cuu/Constants/Table/allascii.txt), [Conversion Factors](https://www.nist.gov/pml/special-publication-811/nist-guide-si-appendix-b-conversion-factors/nist-guide-si-appendix-b8) |
| `Periodic Table` | PubChem, IUPAC, Cordero 2008, Pyykkö 2015, Alvarez 2013 | [Periodic Table](https://pubchem.ncbi.nlm.nih.gov/periodic-table/), [Raw CSV Data](https://pubchem.ncbi.nlm.nih.gov/rest/pug/periodictable/CSV?response_type=save&response_basename=PubChemElements_all), [IUPAC Periodic Table](https://iupac.org/what-we-do/periodic-table-of-elements/), [Cordero 2008](https://doi.org/10.1039/b801115j), [Pyykkö 2015](https://doi.org/10.1021/jp5065819), [Alvarez 2013](https://doi.org/10.1039/C3DT50599E) |
| `Solvent Data` | CRC Handbook of Chemistry and Physics | Permittivity (Dielectric Constant) of Liquids, C. Wohlfarth |

## Installation

```sh
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

```python
>>> 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.

```python
>>> 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

```python
>>> 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`.

```python
>>> 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](https://github.com/atomsforhumanity/qcref/tree/master/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](https://github.com/atomsforhumanity/qcref) - Lightweight, dependency-free chemistry reference data (CODATA constants, periodic table, solvents) where every value carries its source.
- [qcdata](https://github.com/atomsforhumanity/qcdata) - Elegant and intuitive data structures for quantum chemistry, featuring seamless Jupyter Notebook visualizations. [Documentation](https://qcdata.docs.atomsforhumanity.org)
- [qcinf](https://github.com/atomsforhumanity/qcinf) - Cheminformatics algorithms and structure utilities using standardized [qcdata](https://qcdata.docs.atomsforhumanity.org/) data structures.
- [qccodec](https://github.com/atomsforhumanity/qccodec) - A package for translating between standardized [qcdata](https://github.com/atomsforhumanity/qcdata) data structures and native QC program inputs and outputs.
- [qccompute](https://github.com/atomsforhumanity/qccompute) - A package for operating quantum chemistry programs using standardized [qcdata](https://qcdata.docs.atomsforhumanity.org/) data structures. Compatible with `TeraChem`, `psi4`, `QChem`, `NWChem`, `ORCA`, `Molpro`, `geomeTRIC` and many more.
- [BigChem](https://github.com/mtzgroup/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](https://github.com/mtzgroup/chemcloud-server) and associated [Python client](https://github.com/mtzgroup/chemcloud-client) for exposing a BigChem cluster securely over the internet.
