Tequila

Tequila is an Extensible Quantum Information and Learning Architecture where the main goal is to simplify and accelerate implementation of new ideas for quantum algorithms. It operates on abstract data structures allowing the formulation, combination, automatic differentiation and optimization of generalized objectives. Tequila can execute the underlying quantum expectation values on state of the art simulators as well as on real quantum devices.

You can get an overview from this presentation or from it's video recording

Get started with our Tutorials

or checkout our overview article

Quantum Backends

Currently supported - Qulacs - Qibo -- currently needs to be qibo==0.1.1 - Qiskit -- currently needs to be qiskit<0.25 - Cirq - PyQuil - QLM (works also whith myQLM)

Tequila detects backends automatically if they are installed on your systems. All of them are available over standard pip installation like for example

pip install qulacs

qulacs

QuantumChemistry:

Currently supported - Psi4. In a conda environment this can be installed with

bash
conda install psi4 -c psi4

• Madness Currently you need to compile from a separate fork. See the github page of this fork for installation instruction. Here is a small tutorial that illustrates the usage.

• PySCF
  Works similar as Psi4. Classical methods are also integrated in the madness interface allowing to use them in a basis-set-free representation.

Install from source

Do not install like this: (Minecraft lovers excluded)

pip install tequila

We recommend installing in editable mode with

bash
git clone https://github.com/aspuru-guzik-group/tequila.git
cd tequila
pip install -e .

You can install

tequila

bash
pip install git+https://github.com/aspuru-guzik-group/tequila.git

bash
pip install git+https://github.com/aspuru-guzik-group/[email protected]

Recommended Python version is 3.7. Python 3.8 works, but not all (optional) dependencies support it yet (e.g. Psi4). Python 3.6 works, but some (optional) dependencies might have issues with numpy >= 1.20.

Install from PyPi

Do not install like this:

pip install tequila

this will install a Minecraft server manager (might be useful for other things, but probably not what you are looking for).

You can install tequila from PyPi as:

bash
pip install tequila-basic

install basic tequila

pip install tequila-basic

install qulacs and/or other backends and use it within tequila

pip install qulacs ```

Install with Windows

pip install git+https://github.com/aspuru-guzik-group/[email protected]

See also the troubleshooting below if you want to tweak things manually.
The command above will not install the qulacs simulator.
You can install it on windows OS, but you need to have cmake and c++ compilers ready (can be installed for example over visual studio).
Of course you can also use one of the other backends (see above).

Getting Started

Check out the tutorial notebooks provided in tutorials.

Tequila Hello World

# optimize a one qubit example

define a variable
a = tq.Variable("a")
define a simple circuit
U = tq.gates.Ry(angle=a*pi, target=0)
define an Hamiltonian
H = tq.paulis.X(0)
define an expectation value
E = tq.ExpectationValue(H=H, U=U)
optimize the expectation value
result = tq.minimize(method="bfgs", objective=E**2)
check out the optimized wavefunction
wfn = tq.simulate(U, variables=result.angles)
print("optimized wavefunction = ", wfn)
plot information about the optimization
result.history.plot("energies")
result.history.plot("angles")
result.history.plot("gradients")

Chemistry Hello World

# define a molecule within an active space
active = {"a1": [1], "b1":[0]}
molecule = tq.quantumchemistry.Molecule(geometry="lih.xyz", basis_set='6-31g', active_orbitals=active, transformation="bravyi-kitaev")

get the qubit hamiltonian
H = molecule.make_hamiltonian()
create an k-UpCCGSD circuit of order k
U = molecule.make_upccgsd_ansatz(order=1, include_singles=True)
define the expectationvalue
E = tq.ExpectationValue(H=H, U=U)
compute reference energies
fci = molecule.compute_energy("fci")
cisd = molecule.compute_energy("detci", options={"detci__ex_level": 2})
optimize
result = tq.minimize(objective=E, method="BFGS", initial_values=0.0)
print("VQE : {:+2.8}f".format(result.energy))
print("CISD: {:+2.8}f".format(cisd))
print("FCI : {:+2.8}f".format(fci))

Do you want to create your own methods? Check out the tutorials!

Research projects using Tequila

J.S. Kottmann, A. Anand, A. Aspuru-Guzik.
A Feasible Approach for Automatically Differentiable Unitary Coupled-Cluster on Quantum Computers.
Chemical Science, 2021, doi.org/10.1039/D0SC06627C.
arxiv.org/abs/2011.05938
General techniques are implemented in the chemistry modules of tequila.
See the tutorials for examples.

J.S. Kottmann, P. Schleich, T. Tamayo-Mendoza, A. Aspuru-Guzik.
Reducing Qubit Requirements while Maintaining Numerical Precision for the Variational Quantum Eigensolver: A Basis-Set-Free Approach.
J.Phys.Chem.Lett., 2021, doi.org/10.1021/acs.jpclett.0c03410.
arxiv.org/abs/2008.02819
example code
tutorial on the madness interface

A. Cervera-Lierta, J.S. Kottmann, A. Aspuru-Guzik.
The Meta-Variational Quantum Eigensolver.
arxiv.org/abs/2009.13545
example code

J.S. Kottmann, M. Krenn, T.H. Kyaw, S. Alperin-Lea, A. Aspuru-Guzik.
Quantum Computer-Aided design of Quantum Optics Hardware.
arxiv.org/abs/2006.03075
example code
slides

A. Anand, M. Degroote, A. Aspuru-Guzik.
Natural Evolutionary Strategies for Variational Quantum Computation.
arxiv.org/abs/2012.00101

J. S. Kottmann, A. Aspuru-Guzik,
Optimized Low-Depth Quantum Circuits for Molecular Electronic Structure using a Separable Pair Approximation,
arxiv.org/abs/2105.03836
example code

K. Choudhary,
Quantum Computation for Predicting Electron and Phonon Properties of Solids
arxiv.org/abs/2102.11452

Let us know, if you want your research project and/or tutorial to be included in this list!

Dependencies

Support for additional optimizers or quantum backends can be activated by intalling them in your environment. Tequila will then detect them automatically. Currently those are: Phoenics and GPyOpt. Quantum backends are treated in the same way.

Documentation

You can build the documentation by navigating to

docs

make html

firefox docs/build/html/index.html

sphinx

mr2

You can also visit our prebuild online documentation that will correspond to the github master branch

How to contribute

If you find any bugs or inconveniences in

tequila

If you already found a solution you can contribute to

tequila

1. Make a fork of

   tequila

   to your own github account.
2. Checkout the

   devel

   branch and make sure it is up to date with the main github repository.
3. Create and checkout a new branch from

   devel

   via

   git branch pr-my-branch-name

   followed by

   git checkout pr-my-branch-name

   . By typing

   git branch

   afterwards you can check which branch is currently checked out on your computer.
4. Introduce changes to the code and commit them with git.
5. Push the changes to your github account
6. Log into github and create a pull request to the main github repository. The pull-request should be directed to the

   devel

   branch (but we can also change that afterwards).

If you plan to introduce major changes to the base library it can be beneficial to contact us first. This way we might be able to avoid conflicts before they arise.

If you used

tequila

Troubleshooting

If you experience trouble of any kind or if you either want to implement a new feature or want us to implement a new feature that you need: Don't hesitate to contact us directly or raise an issue here on github.

PySCF

If pyscf crashes on import with

Using default_file_mode other than 'r' is no longer supported. Pass the mode to h5py.File() instead

pip install --upgrade 'h5py <= 3.1' 

import errors on openfermion and cirq

This is fixed on master and devel but not yet on PyPi (v1.5.1)
You can avoid it by downgrading cirq and openfermion

bash
pip install --upgrade "openfermion<=1.0.0"
pip install --upgrade "cirq<=0.9.1"

Qiskit backend

Qiskit version 0.25 is not yet supported.

pip install --upgrade qiskit<0.25

Circuit drawing

Standard graphical circuit representation within a Jupyter environment is often done using

tq.draw

tequial

convert

tq.draw

In general, there is no reason to worry if

tq.draw

tq.draw(circuit, backend="qiskit")

backend=cirq

qiskit_circuit = tq.compile(circuit, backend='qiskit').circuit

tq.circuit.export_to(circuit, filename="my_name.pdf")

my_name.qpic

print(circuit)

Qulacs simulator

You will need cmake to install the qulacs simulator

pip install cmake

You don't need

qulacs

qulacs

qulacs

requirements.txt

tequila

tequila

Windows

You can in principle use tequila with windows as OS and have almost full functionality. You will need to replace

Jax

autograd

jax

jaxlib

setup.py

requirements.txt

autograd

In order to install qulacs you will need latest GNU compilers (at least gcc-7). They can be installed for example over visual studio.

Mac OS

Tequila runs on Mac OSX. You might get in trouble with installing qulacs since it currently does not work with Apple's clang compiler. You need to install latest GNU compile (at least gcc-7 and g++7) and set them as default before installing qulacs over pip.

Qibo and GPyOpt

Currently you can't use Qibo and GPyOpt within the same environment.