Welcome to EntropicaQAOA

EntropicaQAOA is a modular package for the quantum approximate optimisation algorithm (QAOA) built on top of Rigetti’s Forest SDK.

Features

• Multiple built-in parametrisations for QAOA, which facilitate prototyping and testing of different approaches to solving a problem.

• A range of utility functions allowing easy problem translation from NetworkX for graph theoretic problems, and Pandas integration for data science tasks.

• Convenient optimiser logging tools.

• Ability to run more general parametric circuits using the VQE library.

• Full native support for Rigetti’s QVM and QPUs. Run your experiments on real Quantum Computers!

• Modular code base that allows the user to customise and modify different components: use your favourite classical optimisation library, or write your own parameter class.

• Extensive examples explaining the usage of EntropicaQAOA in detail.

Installation

If you don’t have them already, you should first install Rigetti’s pyQuil package, as well as their QVM and Quil Compiler. For instructions on how to do so, see Rigetti’s documentation here.

You can install EntropicaQAOA using pip:

pip install entropica-qaoa

To upgrade to the latest version:

pip install --upgrade entropica-qaoa

If you want to run the Demo Notebooks, you will additionally need to install scikit-learn and scikit-optimize:

pip install scikit-learn && pip install scikit-optimize

You can also install EntropicaQAOA directly from GitHub. In your desired local directory, first clone the repository

git clone https://github.com/entropicalabs/entropica_qaoa.git

then move into the entropica_qaoa directory, and run pip:

cd entropica-qaoa
pip install -e

Testing the installation

Run the following short code to verify that EntropicaQAOA has been successfully installed. Here, we create a simple Hamiltonian and evaluate its expectation value with respect to the wavefunction produced by a QAOA circuit. We choose the StandardParams parametrisation, and initialise the parameter values by analogy to a quantum annealing process with a linear schedule function. These features are explained in depth in other sections of the documentation.

Before running the code, make sure you open the Rigetti QVM and Quil compiler in separate terminal windows using the commands qvm -S and quilc -S.

# pyquil imports
from pyquil import Program
from pyquil.api import WavefunctionSimulator
from pyquil.paulis import PauliSum, PauliTerm

# EntropicaQAOA imports
from entropica_qaoa.qaoa.parameters import StandardParams
from entropica_qaoa.qaoa.cost_function import QAOACostFunctionOnWFSim

# create a hamiltonian on 3 qubits with 2 coupling terms and 1 bias term
Term1 = PauliTerm("Z", 0, 0.7)*PauliTerm("Z", 1)
Term2 = PauliTerm("Z", 0, 1.2)*PauliTerm("Z", 2)
Term3 = PauliTerm("Z", 0, -0.5)
ham = PauliSum([Term1,Term2,Term3])

p = 3 # QAOA p parameter (number of timesteps)
params = StandardParams.linear_ramp_from_hamiltonian(ham,p) # initialise a set of StandardParams

# Build the cost function and compute its value with the circuit parameters initialised above
cost_fun = QAOACostFunctionOnWFSim(ham,params)
res = cost_fun(params.raw())
print(res)

You should find the value of res to be -1.4664694.

If you installed directly from GitHub, you can also run the full set of software tests. To do so, you will need to install pytest. To speed up the testing, we have tagged tests that require more computational time (~ 5 mins or so) with runslow, and the tests of the notebooks with notebooks. The commands are as follows:

• pytest runs the default tests, and skips both the longer tests that need heavier simulations, as well as tests of the Notebooks in the examples directory.

• pytest --runslow runs the the tests that require longer time.

• pytest --notebooks runs the Notebook tests. To achieve this, the notebooks are converted to python scripts, and then executed. Should any errors occur, this means that the line numbers given in the error messages refer to the lines in <TheNotebook>.py, and not in <TheNotebook>.ipynb.

• pytest --all runs all of the above tests.

Note that the Quil compiler and QVM need to be running for all of the tests to pass successfully.

The tutorials in this documentation can also downloaded as Jupyter notebooks from our GitHub page .

QPU access

EntropicaQAOA provides full native support for Rigetti’s QVM and QPUs. For access to the QPUs, sign up online at https://qcs.rigetti.com/, or reach out to support@rigetti.com.

Contributing and feedback

If you find any bugs or errors, have feature requests, or code you would like to contribute, feel free to open an issue or send us a pull request on GitHub .

We are always interested to hear about projects built with EntropicaQAOA. If you have an application you’d like to tell us about, drop us an email at devteam@entropicalabs.com.

License

EntropicaQAOA is released open source under the Apache License, Version 2.0.

Contents

About Entropica Labs

• About Entropica Labs

Tutorials

• Overview of tutorials
• First steps: An example workflow
  • Creating a problem instance
  • Specifying the parameters
  • Creating the cost function
  • Optimising the parameters
  • An alternative parametrisation
  • References
• Working with the Parameter classes
  • Creating the problem Hamiltonian and setting up hyperparameters
  • QAOA variable parameter classes
  • Parameter creation and conversion routines
    • Building parameters from the AbstractParams class
    • Building parameters directly
    • Using .empty()
    • “Linear ramp from Hamiltonian” parametrisation
    • Converting between parametrisations
  • Working with parametrisations
    • Parameters under the hood
    • Modifying parameters
    • Erroneous parameter catching
    • Iterating over parameter ranges
    • Parameter iterator use case: Landscape sweeps
  • Footnotes
  • References
• Advanced QAOA parameter classes
  • The Annealing parameter class
  • The Fourier parameter class
  • Parameter constraints with ExtendedParams
  • References
• Cost function features and VQE
  • Short Intro: The Variational Quantum Eigensolver (VQE)
  • Setting up the problem
  • Simulating sampling noise
  • Getting the measurement variance
  • Logging of the optimisation process
  • Running on the QVM or QPU
  • Using other optimisers
  • Towards QAOA
  • Appendix: Simulated measurement noise - statistics implementation details
• Utility functions for QAOA
  • Hamiltonians and graphs
    • Hyperparameters to Hamiltonian
    • Random Hamiltonian
    • Hamiltonians to Graphs
    • Graphs to Hamiltonians
    • Hyperparameters to Graphs
    • Random, regular Graphs
  • Hamiltonians and data
    • Cluster generation and distance calculations
    • Distance datasets to Hamiltonians
  • Example 1: Using QAOA to solve MaxCut for the clustering problem
  • Example 2: The Ring of Disagrees
  • More miscellaneous utilities
    • Different initial states for QAOA
    • Get the bitstring corresponding to the maximum probability state
    • Accuracy scores for QAOA
    • Get nice plots of probabilties
  • References
• Solving a simple QUBO with QAOA
  • Defining the problem
  • Mapping to QAOA
  • Solution with StandardParams
  • References
• Solve the clustering problem using QAOA
  • Variational Hybrid Algorithms
  • The Maxcut Problem
  • From Maxcut to QUBO
  • From QUBO to a Hamiltonian
  • Minimize the Hamiltonian with QAOA

General Reference

• Implementation details, conventions, and FAQ
  • References
• Changelog
  • v1.2 (October 9, 2019)
    • Improvements and changes
    • Bugfixes
  • v1.0-beta (September 12, 2019)

API Reference

• VQE cost functions
  • On the Wavefunction Simulator
  • On the QVM / QPU
• QAOA cost functions
  • On the Wavefunction Simulator
  • On the QVM / QPU
• QAOA Parametrisations
  • Standard Parameters
  • Fourier Parameters
  • Annealing Parameters
  • Parameter Iterators
• VQE and QAOA utilities
• Measurement utilities
  • Some preliminary explanation

Indices and tables

• Index

• Module Index

• Search Page