# QCElemental¶

QCElemental is a general purpose utility library that covers many fundamental areas of practical quantum chemistry:

• QCSchema models for input and output
• Molecule parsing
• Unit support
• Canonical physical quantities

Full QCElemental documentation is available.

## Molecule Parsing and Models¶

In [1]:
import qcelemental as qcel


The MolSSI QCSchema has been implemented in utility classes within QCElemental. Models can be created in a number of different ways, here we pull caffeine from pubchem.

In [2]:
qcel.models.Molecule.from_data("pubchem:caffeine")

	Searching PubChem database for caffeine (single best match returned)
Found 1 result(s)


You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension:
jupyter labextension install jupyterlab_3dmol

Out[2]:
<Molecule(name='IUPAC 1,3,7-trimethylpurine-2,6-dione' formula='C8H10N4O2' hash='a9e3599')>

More canonical forms are also available, for example we can import a geometry from a string:

In [3]:
water = qcel.models.Molecule.from_data("""
-1 2
O 0 0 0
H 0 0 1
H 0 1 0
""")
water


You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension:
jupyter labextension install jupyterlab_3dmol

Out[3]:
<Molecule(name='H2O' formula='H2O' hash='647b11e')>

In addition to visualization, there are many helper functions which can provide data about the molecule or can perform a variety of actions. It should be noted that all quantities are in atomic units.

In [4]:
print(f"Molecular Charge:       {water.molecular_charge}")
print(f"Molecular Multiplicity: {water.molecular_multiplicity}")
print(f"O-H distance (Bohr):    {water.measure([0, 1])}")
print(f"H-O-H angle (degrees):  {water.measure([1, 0, 2])}")
print("\nWater coordinates (Bohr):")
print(water.geometry)

Molecular Charge:       -1.0
Molecular Multiplicity: 2
O-H distance (Bohr):    1.88972613
H-O-H angle (degrees):  90.0

Water coordinates (Bohr):
[[0.         0.         0.        ]
[0.         0.         1.88972613]
[0.         1.88972613 0.        ]]


## Unit Support¶

Unit conversion between arbitrary units is supported out of the box. By default, 2014 CODATA is used.

In [5]:
qcel.constants.conversion_factor("bohr", "Angstrom")

Out[5]:
0.52917721067
In [6]:
qcel.constants.bohr2angstroms

Out[6]:
0.52917721067

Compound units are input with python-like syntax.

In [7]:
qcel.constants.conversion_factor("hartree / bohr ** 2", "eV / inches ** 2")

Out[7]:
6.269253498179915e+18

In addition to straight conversion factors, QCElemental supports Pint Quantity objects. Python floats and numpy arrays are supported for values.

In [8]:
distance = qcel.constants.Quantity("3 Bohr")
print(distance)
print(distance.to("mile"))

3 bohr
9.864464228965342e-14 mile


QCElemental's implementation of a Pint context includes many computational chemistry specific translations.

In [9]:
print(f"hartree -> kelvin:   {qcel.constants.conversion_factor('hartree', 'kelvin')}")
print(f"hartree -> kilogram: {qcel.constants.conversion_factor('hartree', 'kilogram')}")

hartree -> kelvin:   315775.13
hartree -> kilogram: 4.850870129000001e-35


## Physical Quantities¶

QCElemental can provide many canonical quantities from a variety of standard names:

In [10]:
print(qcel.periodictable.to_mass(6))
print(qcel.periodictable.to_mass("C"))
print(qcel.periodictable.to_mass("C12"))
print(qcel.periodictable.to_mass("Carbon"))

12.0
12.0
12.0
12.0


## Conclusion¶

These are some of the capabilities QCElemental offers, check out more documentation. If you like the project, consider starring us on GitHub or if you have any questions, join our Slack channel.