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 <Qristal_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.
A description of the available gates and the syntax used to implement them in Python is given in the Quantum Computing section.
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).
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.
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 Qristal, using a noisy 2-qubit Bell state.
noise_model.py
qubits: 2 gate depth: 6 noise: true
A version of quickstart.py with noise. There are two options of noise models: default or qdk1 (the latter requires the Qristal Emulator. Details about the noise model are available here).
noise_model_custom_kraus.py
qubits: 2 gate depth: 6 noise: true
A version of noise_model.py demonstrating the use of Kraus matrices to generate custom noise channels. Custom noise channels are then used to generate a custom noise model.
noise_model_custom_parameterized.py
qubits: 2 gate depth: 6 noise: true
A version of noise_model.py demonstrating the use of custom noise model parameters (\(t_1\), \(t_2\), gate errors, etc) to generate a custom noise model. This noise model consists of common noise channels: amplitude damping, phase damping and depolarization.
noise_model_custom_channel.py
qubits: 2 gate depth: 6 noise: true
A version of noise_model.py demonstrating the use of noise channels to generate a user-defined noise model. The noise model consists of common noise channels: amplitude damping, phase damping and depolarization.
noise_model_custom_channel_qb_gateset.py
qubits: 2 gate depth: 6 noise: true
A version of noise_model_custom_channel.py demonstrating the use of a user-defined noise model in a different basis gate set.
parametrization_demo.py
qubits: 2 gate depth: 4 noise: false
An extremely simple demonstration of how to construct and execute parametrized circuits using Qristal.
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 Qristal’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.
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
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}\). The basic version of the example does not include noise. If you have the Qristal Emulator installed, two lines in the example file can be uncommented to convert it into an example of a simulation in a noisy environment, using noise models provided by the emulator. Details about the noise model are available here .
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: 1 for H2_explicit and 7 for H1_HEA noise: false
Demonstrates the access and run of predefined examples in Qristal’s built-in VQE routines.
vqee_example_2.py
qubits: 4 gate depth: 8 noise: false
Demonstrates manual problem setup and use and performance of different backends for Qristal’s built-in VQE routines. This example may take some time to run.
vqee_example_3.py
qubits: 4 gate depth: 83 noise: false
Demonstrates how to inject python code into our c++ libs. Shows inclusion of external python chemistry package pyscf into Qristal’s built-in VQE routines.
vqee_example_4.py
qubits: 4 gate depth: 1 noise: false
Demonstrates selection of a different classical optimization algorithm (Nelder-Mead), along with extra options to constrain the parameters and terminate the optimization.
vqee_example_5.py
qubits: 4 gate depth: 1 noise: false
Similar to vqee_example_4 except the classical algorithm used here is ADAM and L-BFGS.
vqee_example_6.py
qubits: 4 gate depth: 1 noise: false
Similar to vqee_example_4 except the classical algorithm used here is CMA-ES.
simple_placement.py
A simple example demonstrating circuit placement based on backend topology.
noise_aware_placement.py
A simple example demonstrating noise-aware circuit placement by setting up a toy hardware configuration.
noise_aware_placement_noise_model.py
A simple example demonstrating noise-aware circuit placement by setting up a toy noise model.
noise_aware_placement_aws_rigetti.py
An example demonstrating integrated noise-aware placement during circuit execution on a hardware backend (e.g., Rigetti devices on AWS). Valid AWS credentials are required to run the example.
aws_braket_qft.py
qubits: 4 noise: true
A simple example demonstrating asynchronous circuit execution on AWS Braket. Note that currently only asynchronous circuit execution (via run_async) is supported for AWS Braket. To run on AWS Braket:
Set up AWS account (e.g., using CLI) and enable AWS Braket;
Use an AWS Region that supports AWS Braket (e.g., us-east-1);
Create an S3 Bucket with prefix
amazon-braket-*and create a folder inside the S3 bucket to store results.
execute_GST_XY.py
qubits: 1 noise: true/false (depends on setting in C++ runner)
A simple example demonstrating the creation of a gate set tomography experiment design for 1-qubit gates Rx(pi/2) and Ry(pi/2) using pyGSTi. An exported circuit list is passed to a provided pyGSTi_runner (using qb::benchmark). The gathered results are loaded back into pyGSTi and used to create an html report.
C++
demo1
qubits: 2 gate depth: 3 noise: false
A C++ implementation of demo1.py.
h1qb
qubits: 2 gate depth: 2 noise: false
This example allows you to quickly switch circuit execution between a hardware QPU and a simulator. See cpp/h1qb/README.md for more information.
qaoa
qubits: 3 qaoa_steps: 2 noise: false
Demonstrates the use of Qristal’s built-in implementation of the QAOA simple algorithm. This example may take some time to run.
qbsdkcli
A command-line interface to Qristal. 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.
noise_model
qubits: 2 gate depth: 6 noise: true
A C++ implementation of noise_model.py.
noise_model_custom_kraus
qubits: 2 gate depth: 6 noise: true
A C++ implementation of noise_model_custom_kraus.py.
noise_model_custom_parameterized
qubits: 2 gate depth: 6 noise: true
A C++ implementation of noise_model_custom_parameterized.py.
noise_model_custom_channel
qubits: 2 gate depth: 6 noise: true
A C++ implementation of noise_model_custom_channel.py.
parametrization
qubits: 1-2 circuits: 2 gate depth: 1 noise: false
Demonstrates the use of parametrized gates/circuits in Qristal, as well as how to execute parametrized circuits after providing runtime parameters, and calculating jacobians for these parameters.
vqee
qubits: 4 gate depth: 83 noise: false
Demonstrates the use of Qristal’s built-in VQE routines. Can be built with MPI support and parallelization over Pauli terms.
vqeeCalculator
vqeeCalculator is a C++ compiled executable that enables command-line access to the functionality in vqee.
noise_aware_placement_simple
A simple example demonstrates noise-aware circuit placement by setting up a toy hardware configuration.
A C++ implementation of noise_aware_placement.py.
noise_aware_placement_aws
An example demonstrates integrated noise-aware placement during circuit execution on hardware backend (e.g., Rigetti devices on AWS). Valid AWS credentials are required to run the example.
A C++ implementation of noise_aware_placement_aws_rigetti.py.
circuit_optimization/circuit_optimizer.py
An example demonstrating the pattern-based circuit optimization pass.
circuit_optimization/remove_redundant_gates.py
An example demonstrating the redundant gate removal circuit optimization pass.
circuit_optimization/two_qubit_squash.py
An example demonstrating the two-qubit gate synthesis (squash) circuit optimization pass.
circuit_optimization/simplify_initial_conditions.py
An example demonstrating the contextual circuit optimization pass, which optimizes the circuit based on the knowledge of its initial state.
circuit_optimization/session_integration.py
An example demonstrating setting up a pipeline of circuit optimization passes when using Qristal.
cudaq_qft.py
Running QFT circuit constructed by the Qristal circuit builder on a CUDA Quantum simulator backend. Required CUDA Quantum support.
qst
qubits: 2 gate depth: 2 noise: false
This example shows the execution of a standard quantum state tomography workflow for a two qubit Bell state, evaluating and printing the quantum state density.
qst_fidelity
qubits: 2 gate depth: 1 noise: false
This example shows the execution of a standard quantum state tomography workflow wrapped around a SPAM benchmark. For each circuit, the quantum state fidelity metric is evaluated and printed.
qpt
qubits: 1 gate depth: 1 noise: false
This example shows the execution of a standard quantum process tomography workflow for a single Rx(pi/2) gate, evaluating and printing the quantum process matrix.
qpt_fidelity
qubits: 2 gate depth: 1 noise: false
This example shows the execution of a standard quantum process tomography workflow wrapped around a rotation sweep benchmark rotating qubit 0 from -pi to +pi applying Rx gates in 5 steps. For each circuit, the quantum process fidelity metric is evaluated and printed.
pyGSTi_runner
qubits: 1 gate depth: depends on pyGSTi experiment design noise: false/true
Example executor for 1-qubit pyGSTi experiments reading in pyGSTi circuits from std::cin and printing pyGSTi compatible results to std::cout. This example is used in the python example execute_GST_XY.py to create a pyGSTi report.
C++ with CUDA Quantum
A number of additional examples are only installed when Qristal is built with CUDA Quantum support. None of these examples has noise enabled.
cudaq_qft
Running QFT circuit constructed by the Qristal circuit builder on a CUDA Quantum simulator backend.
benchmark1_cudaq
A 20 qubit GHZ state designed for benchmarking performance of CUDA Quantum and QASM. This is the CUDAQ version.
benchmark1_qasm
A 20 qubit GHZ state designed for benchmarking performance of CUDA Quantum and QASM. This is the QASM version.
cudaq_vqe_cobyla
Determination of the deuteron’s ground state energy using VQE with the Cobyla optimiser.
cudaq_vqe_hydrogens
Determination of the ground state of a chain of four hydrogen atoms, using VQE with the L-BFGS optimiser.
cudaq_vqe_lbfgs
Determination of the deuteron’s ground state energy using VQE with the L-BFGS optimiser.