Qiskit Aqua — A Library of Quantum Algorithms and Applications

Dec 12, 2018 · 8 min read

Marco Pistoia, Jay Gambetta

Sitting atop the Qiskit ecosystem, Aqua is the element that encompasses cross-domain quantum algorithms and applications running on Noisy Intermediate-Scale Quantum (NISQ) computers. Aqua is an open-source library completely written in Python and specifically designed to be modular and extensible at multiple levels. As shown in Fig. 1, this flexibility allows users with differing levels of experience and scientific interests to contribute to, and extend, Aqua throughout the stack.

Image for post
Image for post
Fig. 1 — Aqua Software Stack

With the addition of Aqua, Qiskit has become the only scientific software framework for quantum computing that is capable of taking high-level domain-specific problem specifications down to circuit generation, compilation, and finally execution on IBM Q quantum hardware.

Input Generation

Currently, Aqua supports four applications, in domains that have long been identified as potential areas for quantum computing: Chemistry, Artificial Intelligence (AI), Optimization, and Finance. New domains can be easily added using the versatile Aqua interfaces. At this application level, Aqua allows for classical computational software to be leveraged as the quantum application front-end, without the need for the end user to learn a new programming language. Behind the scenes, Aqua employs hybrid classical/quantum processes; some initial computation is performed classically, and the results of those computations are then combined with problem-specific configuration data, and translated into inputs for one or more quantum algorithms. The Aqua algorithms run on top of Terra, the element of Qiskit responsible for building, compiling and executing quantum circuits on simulators or real quantum devices.

Programming an Experiment

The example code in Fig. 2 uses Aqua to conduct a simple chemistry experiment on top of a quantum machine.

Fig. 2 — Using Qiskit Chemistry to Compute the Ground State Energy of a Molecule

Specifically, the program in Fig. 2 uses a quantum computer to calculate the ground state energy of molecular Hydrogen, H2, where the two atoms are configured to be at a distance of 0.735 angstroms. The molecular configuration input is generated using PySCF, a standard classical computational chemistry software package. First, Aqua transparently executes PySCF, and extracts from it the one- and two-body molecular-orbital integrals; an inexpensive operation that scales well classically and does not require the use of a quantum computer. These integrals are then used to create a quantum fermionic-operator representation of the molecule. In this specific example, we use a parity mapping to generate a qubit operator from the fermionic one, with a unique precision-preserving optimization that allows for two qubits to be tapered off; a reduction in complexity that is particularly advantageous for NISQ computers. The qubit operator is then passed as an input to the Variational Quantum Eigensolver (VQE) algorithm, instantiated with a Limited-memory Broyden-Fletcher-Goldfarb-Shanno Bound (L-BFGS-B) classical optimizer and the RyRz variational form. The Hartree-Fock state is utilized to initialize the variational form. The output of the VQE algorithm is the ground state energy of the given input molecule. In addition, Aqua can easily be configured to compute a molecule’s dipole moment and excited states.

For clarity, the program in Fig. 2 deals with H2, the simplest possible molecule, and executes the experiment on the Qiskit Terra state vector simulator. However, it is straightforward to run this same example on a real quantum device by changing just a single line of code. In fact, a collection of more complex molecules has already been evaluated on IBM quantum hardware.

Quantum Algorithms

Researchers focusing on quantum algorithms can experiment with the many algorithms made readily available in Aqua. These include numerous domain-independent algorithms, such as the VQE algorithm (used in the example in Fig. 2), the Quantum Approximate Optimization Algorithm (QAOA), Grover’s Search Algorithm, and various forms of Quantum Phase Estimation (QPE). In addition, domain-specific algorithms, such as the Support Vector Machine (SVM) Quantum Kernel and Variational algorithms, suitable for supervised learning, are also available. It is also possible for researchers to contribute their own algorithms by extending the Aqua QuantumAlgorithm interface. These efforts are aided by a vast set of supporting components, such as local and global optimizers, variational forms, initial states for variational-form initialization, Inverse Quantum Fourier Transforms (IQFTs), oracles, feature maps, and binary-to-multiclass classification extensions. To facilitate the integration of new components, Aqua includes an automatic component-discovery mechanism that allows components to register themselves for dynamical loading at run time.

User Experience

Utilizing classical computational software at the front end of Aqua has unique advantages. Users at the top of the Aqua software stack are industry-domain experts, who are most likely very familiar with existing classical software specific to their own domains, such as the PySCF computational chemistry software driver used in the code of Fig. 2. These practitioners are interested in experimenting with the potential benefits of quantum computing, but at the same time they might be hesitant to learn the intricate details of the underlying quantum physics. Ideally, such practitioners would benefit from a workflow centered around the computational software they are comfortable with as the front end, without having to learn a new quantum programming language or Applicatiom Programming Interface (API). Moreover, such researchers may have collected, over time, numerous problem configurations, corresponding to various experiments that are all tied to a specific classical computational package. Aqua has been designed from the outset to accept input files in the language of any classical computational package it interfaces, thus not requiring users experienced in a particular domain to learn a new quantum-specific language for the same task.


While other quantum software libraries impose an intermediate programming layer or API between the classical and quantum parts of a hybrid program, Aqua is unique in its ability to directly interface with classical computational software, thus allowing for the computation of the intermediate data needed to construct the quantum-algorithm input to be performed at its highest level of precision, all without losing any functionality inherent in the underlying classical software.

To better illustrate this point, let us consider some popular computational chemistry software packages such as Gaussian™ 16, PSI4 and PySCF, all integrated into Qiskit Chemistry. These classical chemistry drivers allow a user to select different basis sets for each atom in a molecule, as opposed to forcing a single basis set on all atoms. As an example, the following code snippet, written in the PSI4 language, configures the basis sets for a molecule of benzene, whose chemical formula is C6H6:

basis {
assign DZ
assign C 3–21G
assign H1 STO-3G
assign C1 STO-3G

In the first assignment, the chemist has chosen to apply basis DZ to all atoms. The second assignment then overwrites this basis selection for all six carbon atoms with the 3-21G basis set. The third statement assigns basis set STO-3G to the Hydrogen atom labeled with index 1, while all the other five Hydrogen atoms are still represented in the originally assigned DZ basis. Finally, the last statement selects basis set STO-3G for the Carbon atom with index 1, leaving the remaining five carbon atoms with basis set 3-21G as defined by the second assignment. Qiskit Chemistry readily supports this atom-dependent basis specification as there is no additional software layer between Aqua and the classical software used for computing inputs. Conversely, systems that have chosen to interpose an API in front of the computational drivers currently do not support atom-dependent basis-set assignment, even though the drivers they interface would enable such feature.

Atom-dependent basis selection is only one of many examples of how directly exposing classical computational software input parameters maximizes the functionality available to the underlying quantum algorithms. Another, perhaps more important, example deals with the Hartree-Fock wave function that is computed by the underlying classical software. This wave function is used in the computation of the one- and two-body molecular-orbital integrals that are needed for the calculation of the full Configuration Interaction (CI) and/or the Unitary Coupled Cluster Singles and Doubles (UCCSD) energies on the quantum computer. Classical chemistry software drivers expose their own unique configuration parameters to make the computation of the Hartree-Fock wave function converge should the default parameter values fail. Aqua has no problem supporting such advanced configuration parameters, which can be passed directly into the configuration file as an input to the classical computational chemistry software package. Once again, other quantum-computing software libraries do not support this functionality, and are limited to only those features that are exposed by the intermediate software API layer. Only Qiskit Aqua puts the full power of domain-specific classical software into the hands of its users.

Configuration Correctness

Given that Aqua allows domain-specific applications to be executed on a quantum system, configuring an experiment may require a hybrid configuration involving both classical- and quantum-specific parameters, whose values cannot be assigned in isolation from one another. The chances of introducing configuration errors, making typos, or assigning incompatible values to different parameters is thus an issue that needs to be addressed. This is especially important for those users who are experts in a given domain, but new to the realm of quantum computing. To avoid these conflicts, Aqua cross-validates configuration data for correctness, so that the combination of classical and quantum inputs is resilient to configuration errors. Most importantly, this correctness is dynamically enforced even for components that are discovered and loaded at run time.

Automatic Code Generation

In addition to the programmatic interface shown above in Fig. 2, Aqua provides a simplified graphical approach to both configure and execute a quantum experiment, as illustrated in Fig. 3.

Image for post
Image for post
Fig. 3 — Configuring and Executing a Chemistry Experiment Using the Qiskit Chemistry Wizard

The wizard in Fig. 3 lets the user automatically generate and extract a Python dictionary that summarizes the entire experiment configuration. The whole experiment can then be executed with the addition of just four lines of code, as demonstrated in Fig. 4.

Fig. 4 — Using the Dictionary Automatically Generated by the Aqua Wizard to Program a Chemistry Experiment

Note that the program in Fig. 4 encodes, in a declarative programming style, exactly the same experiment programmed in Fig. 2 via subsequent Aqua API calls. This simplified approach may be useful when a user wants to repeat an experiment multiple times, changing only a few parameters. This is beneficial, for example, to compare the results of two different algorithms across a molecule’s dissociation profile.

Experimenting with Other Domains

The Aqua program detailed in Fig. 5 below demonstrates how Grover’s search algorithm can be used in conjunction with the Satisfiability (SAT) oracle to compute one of the many possible solutions of a Conjunctive Normal Form (CNF):

Fig. 5 — Aqua Program Using the Quantum Grover Algorithm to Compute a Solution of a CNF

Variable sat_cnf in the program of Fig. 5 corresponds to the following CNF:


The code in Fig. 5 prints out one possible solution for this CNF. For example, output 1, -2, 3 indicates that (x1, ¬x2, x3) satisfies the given CNF.

In future blogs, we will show how easy it is to program experiments using other Aqua applications, such as AI and Finance. Meanwhile, the Qiskit Aqua and community tutorials provide numerous examples demonstrating how to use Aqua to carry out quantum computing experiments in different domains.


Aqua was inspired, authored and brought about by the collective work of an international team of researchers.


A community to discuss Qiskit, programming quantum…


Written by


An open source quantum computing framework for writing quantum experiments and applications



A community to discuss Qiskit, programming quantum computers, and anything else related to quantum computing.


Written by


An open source quantum computing framework for writing quantum experiments and applications



A community to discuss Qiskit, programming quantum computers, and anything else related to quantum computing.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store