Examples
The examples folder contains a series of example C++ and Python main programs.
After installing the core (make install in the main project build folder of either the core or SDK), the Python programs can be run by simply invoking
python3 <name_of_example>.py
The C++ examples are installed as source files with working CMakeLists.txt build scripts, to demonstrate how to use the core library to build your own C++ main program. To build and run an example in the installation directory, do
cd <SDK_installation_directory>
mkdir build
cd build
cmake ../examples/cpp/<name_of_example>
make
./<name_of_example>
The C++ example programs are also built and properly linked automatically when running make install in the build folder of the core and SDK projects, but the resulting binaries are not installed. They simply appear in the main project build folder, and can be executed directly from there.
Notes on specific examples
Python
demo1.py
qubits: 2 gate depth: 3 noise: false
A simple example showing a 2 qubit circuit consisting of just a Hadamard and a regular 1-qubit NOT gate.
quickstart.py
qubits: 2 gate depth: 6 noise: false
The 2-qubit Bell state quickstart example given in the README of the main project.
aer_simulator/aer_mps_simple.py
qubits: 2 gate depth: 6 noise: true
Example usage of the aer matrix-product-state-based simulator for computing a 2-qubit Bell state circuit.
aer_simulator/aer_mps_dj_large.py
qubits: 41 gate depth: 204 noise: true
Example usage of the aer matrix-product-state-based simulator for computing a larger Deutsch-Jozsa circuit. This example may take some time to run.
amcu.py
qubits: 5 gate depth: 3392 noise: false
Stands for “ancilla multi-controlled unitary” and is a Python binding of MultiControlledUWithAncilla. Performs a multi-controlled unitary operator U on the target qubit conditioned on the controlled qubits. In this example, the unitary U is defined to be the x gate. The control qubits are first encoded with the bitstring[j] = 1. Ancilla qubits act as scratch qubits used to check whether the desired condition is met, i.e. the jth control qubit is equal to 1. Once the condition is met, the target qubit is flipped by U.
amplitude_amplification/amp_amplification.py
qubits: 3 gate depth: 111 noise: false
A simple amplitude amplification example using Grover’s algorithm, targeting the state \(\ket{111}\).
amplitude_amplification/amplitude_amplification.py
qubits: 3 gate depth: 371 noise: false
A slightly more complex example of amplitude amplification using Grover’s algorithm, targeting the \(\ket{101} - \ket{011}\) state. This example may take some time to run.
amplitude_amplification/amp_amplification_iteration.py
qubits: 1 gate depth: 6318 noise: false
A demonstration of iterative amplitude amplification of the \(\ket{1}\) state. Requires matplotlib and outputs a plot of the results named qaa.png.
amplitude_estimation/canonical_amplitude_estimation.py
qubits: 1 + number of precision qubits (user defined) noise: false
An implementation of the canonical amplitude estimation example described here, implemented by constructing the required Grover operator.
amplitude_estimation/canonical_amplitude_estimation_oracle.py
qubits: 9 noise: false
An implementation of the canonical amplitude estimation example described here, implemented by passing the desired oracle. This example may take some time to run.
amplitude_estimation/methods_comparison.py
qubits: 11 noise: false
Compares the results and runtimes of canonical and maximum likelihood amplitude estimation.
amplitude_estimation/ML_amplitude_estimation.py
qubits: 1 noise: false
Example demonstrating maximum likelihood amplitude estimation (MLQAE) as described here.
amplitude_estimation/ML_amplitude_estimation_parameter_testing.py
qubits: 1 noise: false
As per ML_amplitude_estimation.py, but repeated for different numbers of runs and shots. Requires matplotlib and outputs a plot of the results named MLQAE_parameter_test.png.
amplitude_estimation/MLQAE_parameter_scaling.py
qubits: 15 noise: false
As per ML_amplitude_estimation_parameter_testing.py, but repeated for different numbers of qubits. Also offers an internal option to perform the same parameter scan for canonical amplitude estimation. This example requires matplotlib and produces a series of plots named MLQAE_parameter_test_*_qubits.png. It may take some time to run.
async_example_1.py
qubits: 2 gate depth: 6 noise: false
An example of asynchronous circuit execution, using 32 workers to perform 200 circuit executions.
async_example_2.py
qubits: 2 gate depth: 6 noise: false
An example of asynchronous circuit execution, using 32 workers to perform 3200 circuit executions.
comparator.py
qubits: 9 (comparator), 2 (comparator_as_oracle) gate depth: 226 (comparator), 113 (comparator_as_oracle) noise: false
Example comparing whether two bitstrings/registers are equivalent.
compare_beam_oracle.py
qubits: 11 gate depth: 238 noise: false
This calls a quantum decoder-specific module. Example to check whether a string (\(S_A\)) is equal to a string of ones \(\ket{11 \ldots 1}\). This module is used in the quantum decoder kernel algorithm. The registers of flags, \(F_A\) and \(F_B\) are initialised as \(\ket{1}\). Then they are turned off if the symbol is neither null or repetition flagged. Therefore the symbols in \(S_{A}\) will be flagged in \(F_{A/B}\) if and only if they are null or repeated or both. Once this flagging is done, the oracle flag \(q_0\) returns 1 true if and only if 1. corresponding symbols are either both flagged or both unflagged, and 2. if both unflagged then the symbols must match.
compare_gt.py
qubits: 12 gate depth: 244 noise: false
Example comparing whether the value of bitstring/register \(A\) is greater than the value of bitstring/register \(B\).
controlled_addition.py
qubits: 7 gate depth: 343 noise: false
Example demonstrating adding two numbers condition on the the flag qubit being on or off. If the flag qubit is on (off), the the addition is (is not) performed.
controlled_subtraction.py
qubits: 10 noise: false
Example demonstrating subtracting two numbers condition on the the flag qubit being on or off. If the flag qubit is on (off), the the subtraction is (is not) performed. This example takes a very long time to complete.
controlled_swap.py
qubits: 10 gate depth: 685 noise: false
Example performing a swap operation conditioned on the alphabet is “b”. If the given alphabet is “b”, then a swap operation is performed to move the given alphabet to the end of the string. This example starts with a string “babba” and returns “aabbb”.
cpfd.py
qubits: 13 noise: false
Stands for “controlled proper fraction division”. Given two registers A and B, this module performs the division between the value of A and the value of B. The example performs every 3-qubit proper fraction division with 3 precision bits. This example takes a very long time to complete.
efficient_encoding.py
qubits: 14 gate depth: 3392 (with ancilla), 10245 (without ancilla) noise: false
This calls the EfficientEncoding module to perform a simple encoding using Gray code flips. This example takes the input \(\ket{i}\ket{i}\) with three qubits in each register and returns all possible configurations of the two three-qubit registers \(\ket{000}\ket{000} + \ldots + \ket{111}\ket{111}\).
equality_checker.py
qubits: 9 (with ancilla), 7 (without ancilla) gate depth: 106 (with ancilla), 92 (without ancilla) noise: false
Example checking for equality between the values of two registers. The flag qubit returns 1 (0) if the values are equal (unequal).
generalised_mcx.py
qubits: 3 gate depth: 46 noise: false
Example performing a generalized MCX gate on all possible 3-qubit bit strings (\(\ket{000}, \ldots, \ket{111}\)) with all combinations of control qubit conditions ((on,on), \(\ldots\) , (off,off)).
mcx.py
qubits: 3 gate depth: 46 noise: false
Example of performing an MCX operation on all possible 3-qubit strings (\(\ket{000}, \ldots, \ket{111}\)). The target qubit is flipped if the \(i\)th bitstring/control qubit is equal to 1.
multiplication.py
qubits: 9 gate depth: 686 noise: false
Example of a multiplication of values encoded in registers \(\ket{a}\) and \(\ket{b}\).
noise_mitigation.py
qubits: 2 gate depth: 6 noise: true
This example shows the effects of various noise mitigation strategies available in QB SDK, using a noisy 2-qubit Bell state.
pfd.py
qubits: 12 gate depth: 4690 noise: false
Example of proper fraction division. This example performs every 3-qubit proper fraction division with 3 precision bits.
qaoa_example.py
qubits: 5 noise: false
Demonstrates the use of the SDK’s built-in implementation of the QAOA algorithm. This example may take some time to run.
qaoa_API_demo.py
qubits: 9 noise: false
Demonstrates the use of the QAOA and QUBO APIs at a QAP problem. This example may take some time to run.
qft.py
qubits: 5 noise: false
Example of a quantum Fourier transform.
qml/RDBMS_query_optimization.py
qubits: 4 variational_params: 40 noise: false
Example showing QML wrapped in pytorch for join order optimization.
qpe.py
qubits: 5 gate depth: 16 noise: false
Example of a quantum phase estimation, \(\hat{O}\ket{\psi} = e^{i\phi}\ket{\psi}\), where the goal is to estimate the phase \(\phi\). The oracle operator \(\hat{O}\) in this case is a general \(U1\) rotation, i.e. \(U1(\theta) \ket{1} = e^{i\theta}\ket{1}\). Test value: \(-5\pi/8\).
qsim_noisy.py
qubits: 3 gate depth: 46 noise: true
Example of a simulation in a noisy environment. A generalized mcx gate operates on a target qubit in the state \(\ket{1}\) conditioned on 2 control qubits in the state \(\ket{11}\). This flips the target qubit to \(\ket{0}\).
remote_workstation_example.py
qubits: 18 noise: false
An example of a random circuit, offloaded to the dual-GPU QB Lambda server in Canberra.
set_circuit.py
qubits: 3 gate depth: 46 noise: false
Example of performing an MCX operation on a target qubit initially in the \(\ket{0}\) state conditional on 2 control qubits in the \(\ket{11}\) state. The expected result is that the target qubit is flipped to the \(\ket{1}\) state.
subtraction.py
qubits: 10 gate depth: 13834 noise: false
Example demonstrating subtraction between two registers, each containing 5 qubits each. Subtraction of all possible values of the 5-qubit configuration is performed.
superposition_adder.py
qubits: 33 noise: false
Example using amplitude estimation to find the mean amplitude of a superposition state. Takes a really long time to complete execution.
topology.py
A simple example that prints out circuit topology and connectedness.
vqee_example_1.py
qubits: 4 gate depth: 83 noise: false
Demonstrates the use of the SDK’s built-in VQE routines. This example may take some time to run.
vqee_example_2.py
qubits: 4 gate depth: 83 noise: false
Demonstrates the use and performance of different backends for the SDK’s built-in VQE routines. This example may take some time to run.
C++
demo1
qubits: 2 gate depth: 3 noise: false
A C++ implementation of demo1.py.
qbsdkcli
A command-line interface to the QB SDK. A simple invocation after compiling the CLI is:
./qbsdkcli -q2 --random=2
which will run a random circuit on 2 qubits, with gate depth of 2. Further details can be found here if viewing the html docs (or in examples/cpp/qbsdkcli/README.md if viewing this document as markdown).
vqee
qubits: 4 gate depth: 83 noise: false
Demonstrates the use of the SDK’s built-in VQE routines. Can be built with MPI support and parallelization over Pauli terms.
qaoa
qubits: 3 qaoa_steps: 2 noise: false
Demonstrates the use of the SDK’s built-in implementation of the QAOA simple algorithm. This example may take some time to run.
Further notes for beta testers
The qb-lambda accelerator used in remote_workstation_example.py submits jobs to a reverse proxy that forwards them on to the Lambda machine. We will try to leave this reverse proxy up for the duration of the beta testing, to give you the opportunity to test some things out using GPUs. Please let us know if the server seems to be down.
This folder is to some extent a work in progress. The examples listed above are the ones that have been properly converted to run under the latest version of the code, and fully tested. The others listed below do not presently run or still need additional testing. This is a known issue, and thus not worth reporting as a new bug.
aws_braket
These need work on the aws_s3 argument. You should be able to get the first two to run by just setting s.aws_s3 to the name of an s3 bucket that you personally have access to (you need to have run aws configure, set up the bucket, etc).
aws_noise_demo.pyAn example of circuit offload to AWS Braket, and an explicit test of the decay of coherence over time, as implemented in the default noise model.qft.pyA Fourier transform performed on an AWS simulator.verbatim.pyA circuit run on Rigetti hardware using the AWSverbatimoption.
q_chemistry
vqe_calculator.pyImplementation in Python of a generic VQE calculator for quantum chemistry. Requiresopenfermionpyscf(can be installed with pip). Parses successfully with Python, but a tested example that uses the class has yet to be developed.external_potential.pyAn add-in class forvqe_calculator.pyallowing for the specification of an external potential arising from a point charge.
exponential_search.py
Example demonstrating the use of the exponential search algorithm to find the largest number, or “best score”, in a dataset. If sufficient search iterations are done, the algorithm should return the best score of 3.
lambda_accelerator
Further examples using a remote accelerator.
qap
Some QAOA examples that require upcoming recursive QAOA routines.
vqe
h2_vqe_aswap.pyExample using the variational quantum eigensolver and ASWAP ansatz to obtain the ground state energy of a H2 molecule.h2_vqe_uccsd.pyExample using the variational quantum eigensolver and UCCSD ansatz to obtain the ground state energy of a H2 molecule.h4_vqe_uccsd.pyExample using the variational quantum eigensolver and UCCSD ansatz to obtain the ground state energy of H4.h4_vqe_uccsd_aerExample using the variational quantum eigensolver, a UCCSD ansatz and the AER simulator to obtain the ground state energy of H4.h6_vqe_uccsd_aerExample using the variational quantum eigensolver, a UCCSD ansatz and the AER simulator to obtain the ground state energy of H6.