DOCSEARCHbyAlgolia
Submit Docs

OpenQAOA

repository·main·Indexed 40 days ago

https://github.com/entropicalabs/openqaoa

A multi-backend Python library for quantum optimization using the Quantum Approximate Optimization Algorithm (QAOA). It supports building advanced QAOAs and RQAOAs for execution on local simulators and cloud-based QPUs via plugins for AWS Braket, Microsoft Azure Quantum, IBM Qiskit, and Rigetti Pyquil.

Tokens
35.4K
Snippets
116
Records
160
Agent score
48%

What's inside OpenQAOA

  1. Use training optimizers in OpenQAOA

    main

    OpenQAOA provides several optimizer classes for Variational Quantum Algorithms (VQA) training. These classes are used to update parameters during the optimization process.

    Key optimizer classes include:

    • OptimizeVQA: The primary class for VQA optimization.
    • ScipyOptimizer: An optimizer that leverages SciPy's optimization routines.
    • CustomScipyGradientOptimizer: A specialized SciPy-based optimizer for custom gradient handling.
    • PennyLaneOptimizer: An optimizer designed to work with the PennyLane ecosystem.

  2. Understand QAOA parametrisations

    main

    OpenQAOA provides 7 different parametrisations for the Quantum Approximate Optimization Algorithm (QAOA), located in the openqaoa.qaoa_components.variational_parameters module. These are categorized into three main mathematical approaches:

    1. Standard: Uses $\gamma$ (cost) and $\beta$ (mixer) parameters as free parameters, following the original Farhi et al. formulation.
    2. Fourier: Uses discrete cosine and sine transforms of the $\gamma$ and $\beta$ parameters as free parameters, following the Zhou et al. proposal.
    3. Annealing: Based on discretized adiabatic annealing, where function values $s(t_i)$ at equally spaced times $t_i$ are the free parameters.

    Most classes (except Annealing) offer three levels of detail:

    • Basic (StandardParams / FourierParams): Standard $\gamma$ and $\beta$ parameters.
    • With Bias (StandardWithBiasParams / FourierWithBiasParams): Includes extra parameters for single-qubit bias terms.
    • Extended (ExtendedParams / FourierExtendedParams): Provides full control with separate rotation angles (or Fourier coefficients) for each term in the cost and mixer Hamiltonians.

  3. Understand OpenQAOA package structure and plugins

    main

    OpenQAOA is modular. The core elements are located in openqaoa-core, which is included in every installation. Users can install specific backend plugins depending on their hardware or simulator requirements:

    • openqaoa-braket: For AWS Braket.
    • openqaoa-azure: For Microsoft Azure Quantum (this also installs openqaoa-qiskit as a requirement for circuit submissions).
    • openqaoa-pyquil: For Rigetti Pyquil.
    • openqaoa-qiskit: For IBM Qiskit.

    Installing the openqaoa metapackage installs all of these plugins together.

  4. Understand parameter transformations in QAOAVariationalFourierParams

    main

    The QAOAVariationalFourierParams class converts between $(u, v)$ parameters and $(\gamma, \beta)$ parameters using Type II discrete sine and cosine transformations (similar to scipy.fftpack).

    In OpenQAOA, the transformations follow these specific conventions:

    $$\gamma_i = 2 \sum_{k=0}^{q-1} u_k \sin\left[ (k + 1/2) (i+1) \frac{\pi}{p} \right]$$

    $$\beta_i = 2 \sum_{k=0}^{q-1} v_k \cos\left[ (2k + 1) i\frac{\pi}{2p} \right]$$

    These conventions may differ from some literature but are consistent within the OpenQAOA framework.

  5. How Factory Mode works (Manual QAOA construction)

    main

    If you need more control than the high-level Workflow API provides, you can use 'Factory Mode' to manually construct the components. This involves:

    1. Defining Hamiltonians: Use Hamiltonian.classical_hamiltonian for the cost and X_mixer_hamiltonian for the mixer.
    2. Creating Descriptors: Use QAODescriptor to bundle the Hamiltonians and circuit depth p.
    3. Generating Parameters: Use create_qaoa_variational_params to generate initial variational parameters.
    4. Instantiating Backend: Create a backend object (e.g., QAOAvectorizedBackendSimulator).
    5. Optimizing: Pass the backend and parameters to a ScipyOptimizer and call it.

    The results are retrieved via optimizer_obj.qaoa_result.asdict().

    from openqaoa.qaoa_components import Hamiltonian, QAOADescriptor, create_qaoa_variational_params
from openqaoa.utilities import X_mixer_hamiltonian
from openqaoa.backends.qaoa_backend import QAOAvectorizedBackendSimulator
from openqaoa.optimizers.qaoa_optimizer import ScipyOptimizer

# 1. Define Hamiltonians
terms = [(1,2),(2,3),(0,3),(4,0),(1,),(3,)]
coeffs = [1,2,3,4,3,5]
n_qubits = 5
cost_hamil = Hamiltonian.classical_hamiltonian(terms=terms, coeffs=coeffs, constant=0)
mixer_hamil = X_mixer_hamiltonian(n_qubits=n_qubits)

# 2. Create Descriptor and Params
qaoa_descriptor = QAOADescriptor(cost_hamil, mixer_hamil, p=1)
params = create_qaoa_variational_params(qaoa_descriptor, params_type='fourier', init_type='rand', q=1)

# 3. Setup Backend and Optimizer
backend_obj = QAOAvectorizedBackendSimulator(qaoa_descriptor=qaoa_descriptor, append_state=None, prepend_state=None, init_hadamard=True)
optimizer_dict = {'method': 'cobyla', 'maxiter': 200}
optimizer_obj = ScipyOptimizer(backend_obj, params, optimizer_dict)

# 4. Run
optimizer_obj()
print(optimizer_obj.qaoa_result.asdict())

  6. Understand the difference between Logger and Result classes

    main

    OpenQAOA uses two distinct types of classes to handle QAOA execution data:

    1. Logger: This class is updated continuously every time the classical optimizer performs an optimization step. It captures the raw, granular data during the execution process.
    2. Result: These classes (e.g., QAOAResult, RQAOAResult) take the raw data from a Logger and format it into a more human-friendly, structured representation for analysis.

    Use the Logger to track real-time optimization progress and the Result classes to inspect the final outcome of your algorithm.

  7. Understand the mixer Hamiltonian sign convention in OpenQAOA

    main

    In OpenQAOA, the mixer Hamiltonian is defined as $-\sum_i \hat{X}_i$. This differs from the original QAOA paper which uses $\sum_i \hat{X}_i$.

    By using the negative sign, the initial state $|+ \cdots +\rangle$ becomes the minimum energy eigenstate (ground state) of the mixer Hamiltonian. This convention is used to maintain a clear conceptual analogy to adiabatic computing, where the goal is to evolve from the ground state of the mixer Hamiltonian to the ground state of the cost Hamiltonian.

  8. How circuit rotation angles are implemented

    main

    OpenQAOA maps Hamiltonian evolution parameters to quantum gate rotation angles using the following conventions:

    1. Mixer Hamiltonian ($\beta$): The time evolution operator $\exp(i\beta X)$ is implemented using the RX(\theta) operator by setting $\theta = -2\beta$.
    2. Cost Hamiltonian ($\gamma$): The operator $\exp(-i\gamma hZ)$ is implemented via an RZ(\theta) rotation by setting $\theta = 2\gamma h$.

    Detailed logic for these conversions can be found in the openqaoa.qaoa_parameters.standardparams.QAOAVariationalStandardParams class.

  9. Understand the OpenQAOA Backend and Device hierarchy

    main

    OpenQAOA uses a hierarchical structure to manage execution environments.

    • Devices (DeviceBase): Represent the physical or simulated hardware layer where quantum operations are executed.
    • Backends: Represent the high-level interface used to run QAOA algorithms. There are several specialized backend types:
      • VQABaseBackend: For Variational Quantum Algorithms.
      • QAOABaseBackend: The base class for QAOA-specific backends.
      • QAOABaseBackendStatevector: Backends that simulate the full statevector.
      • QAOABaseBackendShotBased: Backends that execute based on a specific number of shots.
      • QAOABaseBackendCloud: Backends that interface with cloud-based quantum hardware.
      • QAOABaseBackendParametric: Backends designed for parametric execution.

  10. Convert between QAOA parametrisations

    main

    You can convert a parametrisation with fewer degrees of freedom to one with more degrees of freedom using the .from_other_parameters() classmethod.

    The hierarchy of possible conversions is as follows:

    • AnnealingParams $\rightarrow$ StandardParams $\rightarrow$ StandardWithBiasParams $\rightarrow$ ExtendedParams $
    • FourierParams $\rightarrow$ FourierWithBiasParams $\rightarrow$ FourierExtendedParams $\rightarrow$ ExtendedParams

    Note that ExtendedParams can be reached from either the Standard or Fourier extended branches.

  11. Install OpenQAOA from source (Developer Mode)

    main

    To contribute to OpenQAOA or install in an editable mode, follow these steps:

    1. Clone the repository:
    git clone https://github.com/entropicalabs/openqaoa.git
cd openqaoa
    1. Create a virtual environment with Python 3.8 or newer.
    2. Install the package:
    pip install .

    Editable Installation via Makefile

    For a clean editable install, use the provided Makefile:

    make dev-install

    To install extra requirements for running tests or generating documentation, use:

    make dev-install-{tests|docs|all}
    make dev-install