1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
Physical Constants
==================
NIST Physical constants are available from QCElemental with arbitrary
conversion factors using the `pint <https://pint.readthedocs.io/en/latest/>`_
package. The current default physical constants come from the `NIST CODATA
2014 <https://physics.nist.gov/cuu/Constants/>`_.
Conversion Factors
------------------
Conversion factors are available for any valid conversion:
.. code-block:: python
>>> 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.
.. code-block:: python
>>> 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:
.. code-block:: python
>>> 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:
.. code-block:: python
>>> 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:
.. code-block:: python
>>> 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:
.. code-block:: python
>>> 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:
.. code-block:: python
>>> 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:
.. code-block:: python
>>> context = qcel.PhysicalConstantsContext("CODATA2014")
>>> context.conversion_factor("hartree", "eV")
27.21138601949571
Currently only ``CODATA2014`` is available.
API
---
.. currentmodule:: qcelemental.constants
Top level user functions:
.. autosummary::
conversion_factor
get
Quantity
string_representation
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."
.. autoclass:: conversion_factor
:noindex:
.. autofunction:: get
:noindex:
.. autofunction:: Quantity
:noindex:
.. autofunction:: string_representation
:noindex:
|
