chemcloud - A Python Client for ChemCloud

chemcloud is a python client for the ChemCloud Server that makes performing computational chemistry calculations easy, fast, and fun. All input and output data structures are based on the QCSchema specification designed by The Molecular Sciences Software Institute. The client provides a simple, yet powerful interface to perform computational chemistry calculation using nothing but modern python and an internet connection.

Documentation: https://mtzgroup.github.io/chemcloud-client

Source Code: https://github.com/mtzgroup/chemcloud-client

Requirements

• Python 3.7+
• chemcloud stands on the shoulders of giants. It internally depends upon QCElemental, httpx, and toml.
• The AtomicInput, Molecule, Model, and AtomicResult models used throughout the package come directly from QCElemental. They are included in chemcloud.models for your convenience.

Installation

pip install chemcloud

Usage

• Create a ChemCloud account at https://chemcloud.mtzlab.com/signup (or wherever a ChemCloud Server is running)
• Instantiate a client
• Configure client (only required the very first time you use CCClient)

>>> from chemcloud import CCClient

>>> client = CCClient()
>>> client.configure() # only run this the very first time you use CCClient
# See supported compute engines on the ChemCloud Server
>>> client.supported_engines
['psi4', 'terachem_fe', ...]
# Test connection to ChemCloud
>>> client.hello_world("Colton")
'Welcome to ChemCloud, Colton'

• Create a Molecule.
• Molecules can be created from pubchem, local files such as .xyz or .psi4 files, or using pure python.

>>> from chemcloud.models import Molecule
>>> water = Molecule.from_data("pubchem:water")

• Specify your compute job using an AtomicInput

>>> from chemcloud.models import AtomicInput
>>> atomic_input = AtomicInput(molecule=water, model={"method": "B3LYP", "basis": "6-31g"}, driver="energy")

• Submit a computation, specify a target quantum chemistry engine, and get back an AtomicResult

>>> future_result = client.compute(atomic_input, engine="terachem_fe")
>>> future_result.status
'STARTED'

# Get result
>>> result = future_result.get()
# Successful result
>>> result.success
True
>>> result
AtomicResult(driver='energy', model={'method': 'B3LYP', 'basis': '6-31g'}, molecule_hash='b6ec4fa')
>>> result.return_result
-76.38545794119997

# Failed result
>>> result.success
False
# View result
>>> result
>>> FailedOperation(error=ComputeError(error_type='input_error', error_message='QCEngine Input Error: Traceback (most recent call last):...'))
>>> from pprint import pprint
>>> pprint(result.error.error_message)

• Putting it all together

>>> from chemcloud import CCClient
>>> from chemcloud.models import AtomicInput, Molecule

>>> client = CCClient()
>>> water = Molecule.from_data("pubchem:water")
>>> atomic_input = AtomicInput(molecule=water, model={"method": "B3LYP", "basis": "6-31g"}, driver="energy")
>>> future_result = client.compute(atomic_input, engine="terachem_fe")
>>> result = future_result.get()
>>> result
AtomicResult(driver='energy', model={'method': 'B3LYP', 'basis': '6-31g'}, molecule_hash='b6ec4fa')
>>> result.return_result
-76.38545794119997

Examples

Examples of various computations can be found in the documentation and in the GiHub repo's examples directory.

Development

Create and source a virtual environment using python 3.7+

python -m venv env
source ./env/bin/activate

Install flit

python -m pip install flit

Install chemcloud package and its dependencies

flit install --deps develop --symlink

Source the newly installed packages

source ./env/bin/activate

Run tests to check install

pytest

Licence

This project is licensed under the terms of the MIT license.