This README file presents a quick overview of Qiskit Aqua Chemistry, with brief installation, setup and execution instructions. Please refer to the Aqua documentation for a detailed presentation of Aqua Chemistry and its components and capabilities, as well as step-by-step installation and execution instructions.
Aqua Chemistry is a set of tools, algorithms and software for use with quantum computers to carry out research and investigate how to take advantage of the quantum computational power to solve chemistry problems. Qiskit Aqua Chemistry translates chemistry-specific problem inputs into inputs for a quantum algorithm supplied by Qiskit Aqua, which then in turn uses Qiskit Terra for the actual quantum computation.
Qiskit Aqua Chemistry allows users with different levels of experience to execute chemistry experiments and contribute to the software stack. Users with pure chemistry background can continue to configure chemistry problems according to their favorite software packages, called drivers. These users do not need to learn the details of quantum computing; Qiskit Aqua Chemistry translates any chemistry program configuration entered by any end user in their favorite driver into quantum-specific input.
You can follow the installation instructions to install this software and its dependencies.
Once you have it installed, you can experiment with Aqua Chemistry using either the supplied GUI or command line tools.
More advanced users and developers may wish to develop and add their own algorithms or other code. Algorithms and supporting components may be added to Qiskit Aqua which was designed with an extensible, pluggable framework. Qiskit Aqua Chemistry utilizes a similar framework for drivers and the core computation.
If you'd like to contribute to Qiskit Aqua Chemistry, please take a look at our contribution guidelines.
Links to Sections:
As Qiskit Aqua Chemistry is built upon Qiskit Aqua you are encouraged to look over the Qiskit Aqua installation too.
Like Qiskit Aqua at least Python 3.5 or later is needed to use Qiskit Aqua Chemistry. In addition, Jupyter Notebook is recommended for interacting with the tutorials. For this reason we recommend installing the Anaconda 3 Python distribution, as it comes with all of these dependencies pre-installed.
We encourage you to install Qiskit Aqua Chemistry via pip, a Python package manager:
pip install qiskit-aqua-chemistry
pip will handle all dependencies automatically and you will always install the latest (and well-tested) release version.
We recommend using Python virtual environments to cleanly separate the installation of Terra, Aqua and Aqua Chemistry from other programs and improve your experience.
To run chemistry experiments on molecules, you will also need to install a supported chemistry program or library. Several so-called chemistry drivers are supported and while logic to interface these external libraries and programs is supplied, by the above pip install, the dependent chemistry library or program needs to be installed separately. The following chemistry drivers are supported:
- Gaussian 16, a commercial chemistry program
- PSI4, an open-source chemistry program built on Python
- PySCF, an open-source Python chemistry program
- PyQuante, a pure cross-platform open-source Python chemistry program
Please refer to the Aqua Chemistry drivers installation instructions in the Aqua documentation.
Even without installing one of the above drivers, it is still possible to run some chemistry experiments if
you have an Aqua Chemistry HDF5 file that has been previously created when using one of the above drivers.
The HDF5 driver takes such an input.
A few sample hdf5 files have been provided and these can be found in the
Qiskit Aqua Tutorials GitHub repository's chemistry folder.
Now that you have installed Aqua Chemistry you can run an experiment, for example to compute the ground state energy of a molecule.
Aqua Chemistry has both GUI and command line tools, which may be used when conducting chemistry simulation experiments on a quantum machine. Both can load and run an input file specifying the molecule, an algorithm to be used and its configuration, and various other options to tailor the experiment. You can find several input files to experiment with in the Aqua Chemistry Git Hub repository's [chemistry folder] (https://github.com/Qiskit/aqua-tutorials/tree/master/chemistry/input_files). If you are new to the library we highly recommend getting started with the GUI.
The GUI provides an easy means to load and run an input file specifying your chemistry problem. An input file can also be created, edited and saved with validation of values to provide ease of configuring the chemistry problem using the input file. The pip installation creates a script that allows you to start the GUI from the command line, as follows:
qiskit_aqua_chemistry_ui
If you clone and run directly from the repository, instead of using pip install, then it can be run using:
python qiskit_aqua_chemistry/ui
from the root folder of the aqua-chemistry repository clone.
Summary of qiskit_aqua_chemistry command line options:
qiskit_aqua_chemistry_cmd:
usage: qiskit_aqua_chemistry [-h] [-o output | -jo json output] input
Quantum Chemistry Program.
positional arguments:
input Chemistry Driver input or Algorithm JSON input file
optional arguments:
-h, --help show this help message and exit
-o output Algorithm Results Output file name
-jo json output Algorithm JSON Output file name
If you clone and run directly from the repository, instead of using pip install, then it can be run using
python qiskit_aqua_chemistry
from the root folder of the aqua-chemistry repository clone.
Chemistry experiments can be run programmatically too. Please refer to the
Aqua Chemistry's chemistry folder
for a number of examples. Here you will see different ways of programming an experiment. The simplest, which
matches closely to the input file, is used in many examples. Here a similar Python dictionary, which can
be automatically generated from the GUI, is used and an
AquaChemistry instance is used to run the experiment and return the result.
solver = AquaChemistry()
result = solver.run(aqua_chemistry_dict)
The aqua_chemistry_howto notebook details this simple example.
Since the Python dictionary can be updated programmatically it is possible to carry out more complicated experiments such as plotting a dissociation curve.
Qiskit Aqua Chemistry was inspired, authored and brought about by the collective work of a team of researchers.
Qiskit Aqua Chemistry continues now to grow with the help and work of many people who contribute to the project at different levels.
This project uses the Apache License Version 2.0 software license.
Some code supplied here for drivers, for interfacing to external chemistry programs/libraries, has additional licensing.
-
The Gaussian 16 driver contains work licensed under the Gaussian Open-Source Public License.
-
The Pyquante driver contains work licensed under the modified BSD license.