Physical Constants

NIST Physical constants are available from QCElemental with arbitrary conversion factors using the pint package. The current default physical constants come from the NIST CODATA 2014.

Conversion Factors

Conversion factors are available for any valid conversion:

>>> qcel.constants.conversion_factor("nanometer", "angstrom")
10.0

>>> qcel.constants.conversion_factor("eV / nanometer ** 2", "hartree / angstrom ** 2")
0.00036749322481535707

Warning

QCElemental is explicit: kcal is quite different from kcal / mol. Be careful of common shorthands.

>>> qcel.constants.conversion_factor("kcal", "eV")
2.611447418269555e+22

>>> qcel.constants.conversion_factor("kcal / mol", "eV")
0.043364103900593226

Quantities

QCElemental supports the pint “values with units” Quantity objects:

>>> q = qcel.constants.Quantity("5 kcal / mol")
>>> q
<Quantity(5, 'kilocalorie')>

>>> q.magnitude
5.0

>>> q.dimensionality
<UnitsContainer({'[length]': 2.0, '[mass]': 1.0, '[substance]': -1.0, '[time]': -2.0})>

These objects are often used for code that has many different units to make the requisite bookkeeping nearly effortless. In addition, these objects have NumPy and Pandas support built-in:

>>> import numpy as np
>>> a = qcel.constants.Quantity("kcal") * np.arange(4)
>>> a
<Quantity([0 1 2 3], 'kilocalorie')>

An example of array manipulation using a NumPy array with a pint quantity:

>>> a * qcel.constants.Quantity("eV")
<Quantity([0 1 2 3], 'electron_volt * kilocalorie')>

>>> a.to("eV")
<Quantity([0.00000000e+00 2.61144742e+22 5.22289484e+22 7.83434225e+22], 'electron_volt')>

NIST CODATA

The exact values from the NIST CODATA can be queried explicitly:

>>> qcel.constants.get("hartree energy in ev")
27.21138602

The complete NIST CODATA record is held and can be obtained via the Python- API. The following example shows how to obtain a comprehensive overview of the individual CODATA record:

>>> datum = qcel.constants.get("hartree energy in ev", return_tuple=True)
>>> datum
<----------------------------------------
       Datum Hartree energy in eV
----------------------------------------
Data:     27.21138602
Units:    [eV]
doi:      10.18434/T4WW24
Comment:  uncertainty=0.000 000 17
Glossary:
---------------------------------------->

Each of these quantities is API accessible:

>>> datum.doi
'10.18434/T4WW24'
>>> datum.comment
'uncertainty=0.000 000 17'

Contexts

Physical constants are continuously refined over time as experimental precision increases or redefinition occurs. To prepare for future changes, physical constants are contained in contexts. The qcel.constants context will be updated over time to the latest NIST data. To “pin” a context version, a specific context can be created like so:

>>> context = qcel.PhysicalConstantsContext("CODATA2014")
>>> context.conversion_factor("hartree", "eV")
27.21138601949571

Currently only CODATA2014 is available.

API

Top level user functions:

`conversion_factor`(base_unit, conv_unit)	Provides the conversion factor from one unit to another.
`get`([return_tuple])	Access a physical constant, physical_constant.
`Quantity`()	Returns a Pint Quantity.
`string_representation`()	Print name, value, and units of all physical constants.

Function Definitions

Note

conversion_factor is a function, not a class, but cannot be documented in Sphinx as such due to the way the LRU Cache wraps it. Please disregard the marking of it being a “class.”

class qcelemental.constants.conversion_factor(self, base_unit, conv_unit)

Provides the conversion factor from one unit to another.

The conversion factor is based on the current contexts CODATA.

Parameters:

base_unit (Union[str, Quantity]) – The original units
conv_unit (Union[str, Quantity]) – The units to convert to

Return type:

float

Examples

>>> conversion_factor("meter", "picometer")
1e-12

>>> conversion_factor("feet", "meter")
0.30479999999999996

>>> conversion_factor(10 * ureg.feet, "meter")
3.0479999999999996

Returns:

The requested conversion factor

Return type:

float

Parameters:

base_unit (Union[str, Quantity]) –
conv_unit (Union[str, Quantity]) –

qcelemental.constants.get(physical_constant, return_tuple=False)

Access a physical constant, physical_constant.

Parameters:

physical_constant (str) – Case-insensitive string of physical constant with NIST name.
return_tuple (bool) – See below.

Returns:

When return_tuple=False, value of physical constant. When return_tuple=True, Datum with units, description, uncertainty, and value of physical constant as Decimal.

Return type:

Union[float, Datum]

qcelemental.constants.Quantity(data)

Returns a Pint Quantity.

Return type:: Quantity
Parameters:: data (str) –

qcelemental.constants.string_representation()

Print name, value, and units of all physical constants.

Return type:: str