From dc4f9742b683b4a46686fb70aa6c229f9d3d1b53 Mon Sep 17 00:00:00 2001 From: soranjh Date: Mon, 2 Oct 2023 10:49:42 -0400 Subject: [PATCH 01/61] add block encoding demo --- demonstrations/tutorial_block_encoding.py | 117 ++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 demonstrations/tutorial_block_encoding.py diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py new file mode 100644 index 0000000000..563d5a87b2 --- /dev/null +++ b/demonstrations/tutorial_block_encoding.py @@ -0,0 +1,117 @@ +r"""Block encoding +============================================================= + +.. meta:: + :property="og:description": Learn how to perform block encoding + :property="og:image": https://pennylane.ai/qml/_images/thumbnail_block_encoding.png + +.. related:: + + tutorial_intro_qsvt Intro to QSVT + +*Author: XXX — Posted: September 29, 2023.* + +Prominent quantum algorithms such as Quantum Phase estimation and Quantum Singular Value +Transformation require implementing a non-unitary operator in a quantum circuit. This is problematic +because quantum computers can only perform unitary evolutions. Block encoding is a general technique +that solves this problem by embedding the non-unitary operator in a unitary matrix that can be +implemented in a quantum circuit containing a set of ancilla qubits. In this tutorial, you learn +several block encoding methods that are commonly used in quantum algorithms. + +| + +.. figure:: ../demonstrations/intro_qsvt/thumbnail_intro_qsvt.png + :align: center + :width: 50% + :target: javascript:void(0) + +| + +Block encoding a matrix +----------------------- +We define block encoding as embedding a given non-unitary matrix, :math:`A`, into a matrix :math:`U` + +.. math:: U(a) = \begin{pmatrix} A & *\\ + * & * + \end{pmatrix}, + +such that :math:`U\{\dagger} U = I`. A general recipe for this encoding is to construct :math:`U` as + +.. math:: U(a) = \begin{pmatrix} a & \sqrt{1-a^2}\\ + \sqrt{1-a^2} & -a + \end{pmatrix}. + +The only condition is that the singular values of :math:`A` should be bounded by 1. This block +encoding can be done in PennyLane using the :class:`~pennylane.BlockEncode` operation. The following +code shows block encoding for a :math:`2 \time 2` matrix. +""" +import pennylane as qml + +A = [[0.1, 0.2], [0.3, 0.4]] +U = qml.BlockEncode(A, wires=range(2)) +print(qml.matrix(U)) + +############################################################################## +# We can directly implement this operator in a circuit that will be executed on a quantum simulator. +# This is great but we also need to know how to implement a block encoding unitary using a set of +# quantum gates. In the following sections we learn three main techniques for constructing circuits +# that implement a block encoding unitary for a given matrix. + +# Block encoding sparce matrices +# ------------------------------ +# Sparse matrices that have specific structures can be efficiently block encoded. A general +# circuit for block encoding s-sparce matrices can be constructed as +# +# Fig 5 of https://arxiv.org/abs/2203.10236 +# +# The circuit has n qubits and m + 1 ancilla qubits. +# Ds is defined as HxHxH +# O_A, O_s can be constructed for structured sparse matrices +# Let's look at O_A, O_s for the Banded circulant matrix +# +# Block encoding with FABLE +# ------------------------- +# The fast approximate quantum circuits for block encodings (FABLE) is a general method +# for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted +# to compress and sparsify the resulting circuits. The general circuit is constructed from a set of +# rotation and C-NOT gates. The rotation angles are obtained from the elements of the encoded +# matrix. ... + +# Block encoding with LCU +# ----------------------- +# A powerful method for block encoding a matrix is to decompose it into a linear combination of +# unitaries (LCU) and then block encode the LCU. The circuit for this block encoding is constructed +# using two important building blocks: Prepare and Select operations. + + +# Summary and conclusions +# ----------------------- +# Block encoding is a powerful technique in quantum computing that allows implementing a non-unitary +# operation in a quantum circuit typically by embedding the operation in a larger unitary operation. +# Here we reviewed some important block encoding methods with code examples. The choice of the block +# encoding approach depends on the non-unitary operation we want to implement. The functionality +# provided in PennyLane allows you to explore and benchmark different approaches for a desired +# problem. Can you select a matrix and compare different block encoding methods for it? +# +# References +# ---------- +# +# .. [#sparse] +# +# Daan Camps, Lin Lin, Roel Van Beeumen, Chao Yang, +# "Explicit quantum circuits for block encodings of certain sparse matrices", +# `arXiv:2203.10236 `__, 2022 +# +# +# .. [#fable] +# +# Daan Camps, Roel Van Beeumen, +# "FABLE: fast approximate quantum circuits for block-encodings", +# `arXiv:2205.00081 `__, 2022 +# +# + +############################################################################## +# About the author +# ---------------- +# .. include:: ../_static/authors/xxx.txt From 5fa21263662ecbbe8700314aac1ebf947cef8578 Mon Sep 17 00:00:00 2001 From: soranjh Date: Mon, 2 Oct 2023 17:45:17 -0400 Subject: [PATCH 02/61] add text for fable --- demonstrations/tutorial_block_encoding.py | 28 ++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 563d5a87b2..d4cb5e01cf 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -75,8 +75,34 @@ # for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted # to compress and sparsify the resulting circuits. The general circuit is constructed from a set of # rotation and C-NOT gates. The rotation angles are obtained from the elements of the encoded -# matrix. ... +# matrix. For a :math:`2 \time 2` matrix, the circuit can be constructed as +# +# .... +# qml.draw() +# +# The rotation angles, :math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained with +# +# .. math:: \left ( H^{\otimes 2n} P \right ) \Theta = C, +# +# where P is a permutation that transforms a binary ordering to the Gray code ordering, +# :math:`C = (arccos(A_00), ..., arccos(A_nn))` is obtained from the matrix elements of the matrix A +# and H is defined as +# .. math:: H = \begin{pmatrix} 1 & 1\\ +# 1 & -1 +# \end{pmatrix}. +# +# +# We now compute the matrix representation of the circuit +# +# You can see that the matrix is a block encoding of the original matrix A. +# +# The interesting thing about the Fable method is that one can eliminate those rotation gates that +# have an angle smaller than a pre-defined threshold. This leaves a sequence of C-NOT gates that in +# most cases cancel each other out. You can confirm that two C-NOT gates applied to the same wires +# cancel each other. Compressing the circuit in this way is an approximation. Let's see how good +# this approximation is in the case of our example. +# # Block encoding with LCU # ----------------------- # A powerful method for block encoding a matrix is to decompose it into a linear combination of From 54b109bb64e806a30a77071164f1b528549bf211 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Tue, 3 Oct 2023 14:40:19 -0400 Subject: [PATCH 03/61] messy sparse block encoding section --- .../block_encoding/fable_circuit.png | Bin 0 -> 19262 bytes .../tutorial_block_encoding.metadata.json | 59 ++++++ demonstrations/tutorial_block_encoding.py | 179 +++++++++++++++--- 3 files changed, 212 insertions(+), 26 deletions(-) create mode 100644 demonstrations/block_encoding/fable_circuit.png create mode 100644 demonstrations/tutorial_block_encoding.metadata.json diff --git a/demonstrations/block_encoding/fable_circuit.png b/demonstrations/block_encoding/fable_circuit.png new file mode 100644 index 0000000000000000000000000000000000000000..14852b2b4ef6e41189ad8f2564dd262b3c5576a7 GIT binary patch literal 19262 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 literal 0 HcmV?d00001 diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json new file mode 100644 index 0000000000..85ee356942 --- /dev/null +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -0,0 +1,59 @@ +{ + "title": "Block Encodings", + "authors": [ + { + "id": "soran_jahangiri" + }, + { + "id": "jay_soni" + }, + { + "id": "diego_guala" + } + ], + "dateOfPublication": "2019-10-11T00:00:00+00:00", + "dateOfLastModification": "2020-10-26T00:00:00+00:00", + "categories": [ + "Quantum Computing", + "Algorithms" + ], + "tags": [], + "previewImages": [ + { + "type": "thumbnail", + "uri": "/_images/xxx.png" + } + ], + "seoDescription": "Learn about the many different methods to achieve a block-encoding for a given matrix.", + "doi": "", + "canonicalURL": "/qml/demos/tutorial_block_encoding", + "references": [ + { + "id": "Daan2023", + "type": "article", + "title": "Explicit Quantum Circuits for Block Encodings of Certain Sparse Matrices.", + "authors": "Daan C., Lin L., Roel V. B, Chao Y.", + "year": "2023", + "journal": "Preprint", + "url": "https://arxiv.org/pdf/2203.10236.pdf" + }, + { + "id": "McClean2018", + "type": "article", + "title": "FABLE: Fast Approximate Quantum Circuits for Block-Encodings", + "authors": "Daan C., Roel V. B.", + "year": "2022", + "journal": "arXiv", + "url": "https://arxiv.org/pdf/2205.00081.pdf" + } + ], + "basedOnPapers": [], + "referencedByPapers": [], + "relatedContent": [ + { + "type": "demonstration", + "id": "tutorial_local_cost_functions", + "weight": 1.0 + } + ] +} \ No newline at end of file diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index d4cb5e01cf..2016ff1948 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -1,4 +1,4 @@ -r"""Block encoding +r"""Block Encodings ============================================================= .. meta:: @@ -9,7 +9,7 @@ tutorial_intro_qsvt Intro to QSVT -*Author: XXX — Posted: September 29, 2023.* +*Author: Diego Guala, Soran Jahangiri, Jay Soni, — Posted: September 29, 2023.* Prominent quantum algorithms such as Quantum Phase estimation and Quantum Singular Value Transformation require implementing a non-unitary operator in a quantum circuit. This is problematic @@ -46,6 +46,7 @@ code shows block encoding for a :math:`2 \time 2` matrix. """ import pennylane as qml +from pennylane import numpy as qnp A = [[0.1, 0.2], [0.3, 0.4]] U = qml.BlockEncode(A, wires=range(2)) @@ -57,20 +58,30 @@ # quantum gates. In the following sections we learn three main techniques for constructing circuits # that implement a block encoding unitary for a given matrix. -# Block encoding sparce matrices -# ------------------------------ -# Sparse matrices that have specific structures can be efficiently block encoded. A general -# circuit for block encoding s-sparce matrices can be constructed as +# Block encoding with LCU +# ----------------------- +# A powerful method for block encoding a matrix is to decompose it into a linear combination of +# unitaries (LCU) and then block encode the LCU. The circuit for this block encoding is constructed +# using two important building blocks: Prepare and Select operations. + +# Block encoding with FABLE +# ------------------------- +# One way to create approach block-encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N x N}`, is by relying on +# oracle access to the entries in the matrix (see [#fable]_, [#sparse]_). Suppose we have access to an oracle +# :math:`\hat{O}_{A}` such that: # -# Fig 5 of https://arxiv.org/abs/2203.10236 +# .. math:: # -# The circuit has n qubits and m + 1 ancilla qubits. -# Ds is defined as HxHxH -# O_A, O_s can be constructed for structured sparse matrices -# Let's look at O_A, O_s for the Banded circulant matrix +# \hat{O}_{A} |0\rangle |i\rangle |j\rangle \ \rightarrow \ (a_{i,j}|0\rangle + \sqrt{1 - |a_{i,j}|^2})|i\rangle |j\rangle +# +# Given two registers representing the :math:`i`th row and :math:`j`th column, this oracle extracts the matrix entry +# at that position. Where :math:`A_{i,j} = \alpha \cdot a_{i,j}` are rescaled to guarantee it is unitary. Using this +# oracle and a :math:`SWAP` operation, we can construct a quantum circuit for block-encoding :math:`\frac{A}{\alpha}`: +# +# .. figure:: ../demonstrations/qonn/fable_circuit.png +# :width: 50% +# :align: center # -# Block encoding with FABLE -# ------------------------- # The fast approximate quantum circuits for block encodings (FABLE) is a general method # for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted # to compress and sparsify the resulting circuits. The general circuit is constructed from a set of @@ -102,14 +113,126 @@ # most cases cancel each other out. You can confirm that two C-NOT gates applied to the same wires # cancel each other. Compressing the circuit in this way is an approximation. Let's see how good # this approximation is in the case of our example. + +# Block-encoding structured sparse matrices +# ----------------------------------------- +# The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, requires on the order of :math:`~ O(N^{2})` +# gates to implement. In the case where :math:`A` is a structured sparse matrix, we can generate a more efficient +# quantum circuit representation for the oracle. +# Sparse matrices that have specific structures can be efficiently block encoded. A general +# circuit for block encoding s-sparce matrices can be constructed # -# Block encoding with LCU -# ----------------------- -# A powerful method for block encoding a matrix is to decompose it into a linear combination of -# unitaries (LCU) and then block encode the LCU. The circuit for this block encoding is constructed -# using two important building blocks: Prepare and Select operations. +# Fig 5 of https://arxiv.org/abs/2203.10236 +# +# The circuit has n qubits and m + 1 ancilla qubits. +# Ds is defined as HxHxH +# O_A, O_s can be constructed for structured sparse matrices +# Let's look at O_A, O_s for the Banded circulant matrix + +# Problem setup: --------------------------- +s = 4 +alpha = 0.1 +gamma = 0.3 + 0.6j +beta = 0.3 - 0.6j + +A = qnp.array([[alpha, gamma, 0, 0, 0, 0, 0, beta], + [beta, alpha, gamma, 0, 0, 0, 0, 0], + [0, beta, alpha, gamma, 0, 0, 0, 0], + [0, 0, beta, alpha, gamma, 0, 0, 0], + [0, 0, 0, beta, alpha, gamma, 0, 0], + [0, 0, 0, 0, beta, alpha, gamma, 0], + [0, 0, 0, 0, 0, beta, alpha, gamma], + [gamma, 0, 0, 0, 0, 0, beta, alpha]]) + +print(f"Original A:\n{A}", "\n") + +A2 = qml.math.array(A) / s +evs = qnp.linalg.eigvals(A) +print(evs) +g = qnp.linalg.cond(A) +print(max(qnp.abs(evs)), min(qnp.abs(evs)), g, 1 / min(qnp.abs(evs)), "\n") +evs = qnp.linalg.eigvals(A2) +print(evs) +g = qnp.linalg.cond(A2) +print(max(qnp.abs(evs)), min(qnp.abs(evs)), g, 1 / min(qnp.abs(evs)), "\n") +>>>>>>> 04f8302b (messy sparse block encoding section) + + +# Soln: --------------------------- + +def shift_circ(s_wires, shift="L"): + control_values = [1, 1] if shift == "L" else [0, 0] + + qml.ctrl(qml.PauliX, control=s_wires[:2], control_values=control_values)(wires=s_wires[2]) + qml.ctrl(qml.PauliX, control=s_wires[0], control_values=control_values[0])(wires=s_wires[1]) + qml.PauliX(s_wires[0]) + + +# Sanity check: ~~~~~~~~~~~~~~~~~~~~~~ +# with qml.tape.QuantumTape() as t: +# shift_circ([0, 1, 2], shift="L") +# print(t.draw(wire_order=[2,1,0])) +# print(t.operations) +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +def oracle_c(wires_l, wires_j): + qml.ctrl(shift_circ, control=wires_l[0])(wires_j, shift="L") + qml.ctrl(shift_circ, control=wires_l[1])(wires_j, shift="R") + + +def oracle_a(ancilla, wire_l, wire_j, a, b, g): + theta_0 = 2 * qnp.arccos(a - 1) + theta_1 = 2 * qnp.arccos(b) + theta_2 = 2 * qnp.arccos(g) + + # print(theta_0, theta_1, theta_2) + + qml.ctrl(qml.RY, control=wire_l, control_values=[0, 0])(theta_0, wires=ancilla) + qml.ctrl(qml.RY, control=wire_l, control_values=[1, 0])(theta_1, wires=ancilla) + qml.ctrl(qml.RY, control=wire_l, control_values=[0, 1])(theta_2, wires=ancilla) + + +# Sanity check: ~~~~~~~~~~~~~~~~~~~~~~ +# with qml.tape.QuantumTape() as t: +# oracle_a("ancilla", ["l0", "l1"], "j", 0.1, -0.6, 0.3) + +# print(t.draw(wire_order=["ancilla", "l1", "l0", "j"])) +# print(t.operations) +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +dev = qml.device("lightning.qubit", wires=["ancilla", "l1", "l0", "j2", "j1", "j0"]) + + +@qml.qnode(dev) +def complete_circuit(a, b, g): + for w in ["l0", "l1"]: # hadamard transform over |l> register + qml.Hadamard(w) + + # qml.Barrier() + + oracle_a("ancilla", ["l0", "l1"], ["j0", "j1", "j2"], a, b, g) + + # qml.Barrier() + + oracle_c(["l0", "l1"], ["j0", "j1", "j2"]) + + # qml.Barrier() + + for w in ["l0", "l1"]: # hadamard transform over |l> register + qml.Hadamard(w) + return qml.state() + + +print("Quantum Circuit:") +print(qml.draw(complete_circuit)(alpha, beta, gamma), "\n") + +print("BlockEncoded Mat:") +mat = qml.matrix(complete_circuit)(alpha, beta, gamma)[:8, :8] * s +print(mat, "\n") + +############################################################################## # Summary and conclusions # ----------------------- # Block encoding is a powerful technique in quantum computing that allows implementing a non-unitary @@ -122,13 +245,6 @@ # References # ---------- # -# .. [#sparse] -# -# Daan Camps, Lin Lin, Roel Van Beeumen, Chao Yang, -# "Explicit quantum circuits for block encodings of certain sparse matrices", -# `arXiv:2203.10236 `__, 2022 -# -# # .. [#fable] # # Daan Camps, Roel Van Beeumen, @@ -136,8 +252,19 @@ # `arXiv:2205.00081 `__, 2022 # # +# .. [#sparse] +# +# Daan Camps, Lin Lin, Roel Van Beeumen, Chao Yang, +# "Explicit quantum circuits for block encodings of certain sparse matrices", +# `arXiv:2203.10236 `__, 2022 +# +# ############################################################################## # About the author # ---------------- -# .. include:: ../_static/authors/xxx.txt +# .. include:: ../_static/authors/diego_guala.txt +# +# .. include:: ../_static/authors/soran_jahangiri.txt +# +# .. include:: ../_static/authors/jay_soni.txt.txt From 6a644066386645ebd5c8b3ae07fcbf2057100951 Mon Sep 17 00:00:00 2001 From: Diego Date: Wed, 4 Oct 2023 09:40:30 -0400 Subject: [PATCH 04/61] add FABLE code blocks --- demonstrations/tutorial_block_encoding.py | 99 ++++++++++++++++++++++- 1 file changed, 95 insertions(+), 4 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 2016ff1948..4367d41271 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -88,8 +88,49 @@ # rotation and C-NOT gates. The rotation angles are obtained from the elements of the encoded # matrix. For a :math:`2 \time 2` matrix, the circuit can be constructed as # -# .... -# qml.draw() +from pennylane.templates.state_preparations.mottonen import compute_theta, gray_code +#define the matrix +n = 2 +N = 2**n +qnp.random.seed(1) +A = qnp.random.randn(N, N) + +#turn the matrix into a vector and normalize +Avec = qnp.ravel(A) +alpha = max(1,qnp.linalg.norm(Avec,qnp.inf)) +Avec = Avec/alpha + +#obtain single qubit rotation angles +alphas = 2*qnp.arccos(Avec) +thetas = compute_theta(alphas) + +#define control wires +code = gray_code(N) +num_selections=len(code) + +control_wires = control_indices = [ + int(qnp.log2(int(code[i], 2) ^ int(code[(i + 1) % num_selections], 2))) + for i in range(num_selections) +] + + +#create a circuit that block encodes on 5 qubits, 4x4 matrix +# hard-coded circuit +dev = qml.device('default.qubit', wires=5) +@qml.qnode(dev) +def circuit(): + qml.Hadamard(wires=2) + qml.Hadamard(wires=3) + for idx in range(len(thetas)): + qml.RY(thetas[idx],wires=4) + qml.CNOT(wires=[control_wires[idx],4]) + qml.SWAP(wires=[0,2]) + qml.SWAP(wires=[1,3]) + qml.Hadamard(wires=2) + qml.Hadamard(wires=3) + return qml.state() + +print(qml.draw(circuit)()) # # The rotation angles, :math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained with # @@ -105,15 +146,65 @@ # # # We now compute the matrix representation of the circuit -# + +print(A) +#print top left of circuit unitary +print(alpha*N*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:N,0:N]) + # You can see that the matrix is a block encoding of the original matrix A. # # The interesting thing about the Fable method is that one can eliminate those rotation gates that # have an angle smaller than a pre-defined threshold. This leaves a sequence of C-NOT gates that in -# most cases cancel each other out. You can confirm that two C-NOT gates applied to the same wires +# most cases cancel each other out. + +tolerance= 0.07 + +dev = qml.device('default.qubit', wires=5) + +@qml.qnode(dev) +def circuit(): + qml.Hadamard(wires=2) + qml.Hadamard(wires=3) + for idx in range(len(thetas)): + if abs(thetas[idx])>tolerance: + qml.RY(thetas[idx],wires=4) + qml.CNOT(wires=[control_wires[idx],4]) + qml.SWAP(wires=[0,2]) + qml.SWAP(wires=[1,3]) + qml.Hadamard(wires=2) + qml.Hadamard(wires=3) + return qml.state() + +print(qml.draw(circuit)()) + +# You can confirm that two C-NOT gates applied to the same wires # cancel each other. Compressing the circuit in this way is an approximation. Let's see how good # this approximation is in the case of our example. +tolerance= 0.07 + +dev = qml.device('default.qubit', wires=5) + +@qml.qnode(dev) +def circuit(): + qml.Hadamard(wires=2) + qml.Hadamard(wires=3) + for idx in range(len(thetas)): + if abs(thetas[idx])>tolerance: + qml.RY(thetas[idx],wires=4) + # [add process to remove extra CNOTs] + qml.CNOT(wires=[control_wires[idx],4]) + qml.SWAP(wires=[0,2]) + qml.SWAP(wires=[1,3]) + qml.Hadamard(wires=2) + qml.Hadamard(wires=3) + return qml.state() + +print(qml.draw(circuit)()) + +print(A) +print(alpha*N*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:N,0:N]) + # Block-encoding structured sparse matrices # ----------------------------------------- # The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, requires on the order of :math:`~ O(N^{2})` From 90aa2dd037ea412aad005ef4b477d08dd0247866 Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 12:05:51 -0400 Subject: [PATCH 05/61] add general circuit --- demonstrations/tutorial_block_encoding.py | 82 +++++++++-------------- 1 file changed, 32 insertions(+), 50 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 4367d41271..973339f0c3 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -1,5 +1,5 @@ -r"""Block Encodings -============================================================= +r"""Block Encoding of Sparse and Structured Matrices +==================================================== .. meta:: :property="og:description": Learn how to perform block encoding @@ -9,14 +9,20 @@ tutorial_intro_qsvt Intro to QSVT -*Author: Diego Guala, Soran Jahangiri, Jay Soni, — Posted: September 29, 2023.* +*Author: Diego Guala, Soran Jahangiri, Jay Soni — Posted: September 29, 2023.* Prominent quantum algorithms such as Quantum Phase estimation and Quantum Singular Value Transformation require implementing a non-unitary operator in a quantum circuit. This is problematic because quantum computers can only perform unitary evolutions. Block encoding is a general technique that solves this problem by embedding the non-unitary operator in a unitary matrix that can be -implemented in a quantum circuit containing a set of ancilla qubits. In this tutorial, you learn -several block encoding methods that are commonly used in quantum algorithms. +implemented in a quantum circuit containing a set of ancilla qubits. In this [link] demo, we +learned how to block encode a matrix by simply embedding it in a larger unitary matrix using the +:class:`~pennylane.BlockEncode` operation. We also learned [link] a powerful method for block encoding a +matrix by decomposing it into a linear combination of unitaries (LCU) and then block encode the LCU. + +In this tutorial we explore a general block encoding method that can be efficiently implemented for +sparse and structured matrices. We first explain the method and then apply it to specific examples +that can be efficiently block-encoded with this approach. | @@ -27,48 +33,11 @@ | -Block encoding a matrix ------------------------ -We define block encoding as embedding a given non-unitary matrix, :math:`A`, into a matrix :math:`U` - -.. math:: U(a) = \begin{pmatrix} A & *\\ - * & * - \end{pmatrix}, - -such that :math:`U\{\dagger} U = I`. A general recipe for this encoding is to construct :math:`U` as - -.. math:: U(a) = \begin{pmatrix} a & \sqrt{1-a^2}\\ - \sqrt{1-a^2} & -a - \end{pmatrix}. - -The only condition is that the singular values of :math:`A` should be bounded by 1. This block -encoding can be done in PennyLane using the :class:`~pennylane.BlockEncode` operation. The following -code shows block encoding for a :math:`2 \time 2` matrix. -""" -import pennylane as qml -from pennylane import numpy as qnp - -A = [[0.1, 0.2], [0.3, 0.4]] -U = qml.BlockEncode(A, wires=range(2)) -print(qml.matrix(U)) - -############################################################################## -# We can directly implement this operator in a circuit that will be executed on a quantum simulator. -# This is great but we also need to know how to implement a block encoding unitary using a set of -# quantum gates. In the following sections we learn three main techniques for constructing circuits -# that implement a block encoding unitary for a given matrix. - -# Block encoding with LCU -# ----------------------- -# A powerful method for block encoding a matrix is to decompose it into a linear combination of -# unitaries (LCU) and then block encode the LCU. The circuit for this block encoding is constructed -# using two important building blocks: Prepare and Select operations. - -# Block encoding with FABLE -# ------------------------- -# One way to create approach block-encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N x N}`, is by relying on -# oracle access to the entries in the matrix (see [#fable]_, [#sparse]_). Suppose we have access to an oracle -# :math:`\hat{O}_{A}` such that: +# A generic circuit for block encoding +# ------------------------------------ +# An arbitrary matrix :math:`A \in \mathbb{C}^{N x N}`, can be block encoded by relying on +# oracle access to the entries in the matrix (see [#fable]_, [#sparse]_). Suppose we have access to +# an oracle :math:`\hat{O}_{A}` such that: # # .. math:: # @@ -82,11 +51,24 @@ # :width: 50% # :align: center # +# Finding the optimal sequence of the quantum gates that implement the :math:`\hat{O}_{A}` and +# :math:`\hat{O}_{C}` oracles is not straightforward for random matriceses. In the general case, the +# circuit can be constructed as +# +# Fig 3-a of [#fable]_ +# +# The gate complexity of this circuit is O(N4) which makes its impelmentation highly-inefficent. +# Here we explain two approaches that provide alternative construtions that can be very effcient +# for specific problems. +# +# Block encoding with FABLE +# ------------------------- # The fast approximate quantum circuits for block encodings (FABLE) is a general method # for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted -# to compress and sparsify the resulting circuits. The general circuit is constructed from a set of -# rotation and C-NOT gates. The rotation angles are obtained from the elements of the encoded -# matrix. For a :math:`2 \time 2` matrix, the circuit can be constructed as +# to compress and sparsify the resulting circuit. For matrices with specific-structures, FABLE +# provides an effcient circuit without sacrificing the accuracy. The general circuit is constructed +# from a set of rotation and C-NOT gates where the rotation angles are obtained from the elements +# of the encoded matrix. # from pennylane.templates.state_preparations.mottonen import compute_theta, gray_code #define the matrix From feb6f3d4c2d9d6da6d51bda9e22fab8629831240 Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 15:12:45 -0400 Subject: [PATCH 06/61] add general circuit --- .../block_encoding/general_circuit.png | Bin 0 -> 18758 bytes .../block_encoding/rotation_circuit.png | Bin 0 -> 30469 bytes demonstrations/tutorial_block_encoding.py | 165 +++++++----------- 3 files changed, 65 insertions(+), 100 deletions(-) create mode 100644 demonstrations/block_encoding/general_circuit.png create mode 100644 demonstrations/block_encoding/rotation_circuit.png diff --git a/demonstrations/block_encoding/general_circuit.png b/demonstrations/block_encoding/general_circuit.png new file mode 100644 index 0000000000000000000000000000000000000000..433948003291d2fb28b0c7c60d4bd95fb919246f GIT binary patch literal 18758 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

O`6{pI~fc{+-kdt7dO5KRNIx9*WYhs5-fsp0Aup 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 literal 0 HcmV?d00001 diff --git a/demonstrations/block_encoding/rotation_circuit.png b/demonstrations/block_encoding/rotation_circuit.png new file mode 100644 index 0000000000000000000000000000000000000000..58084e5378ee94d244e738a49422d6f7ee150ff9 GIT binary patch literal 30469 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�ohN08lZz5gLew+^# z+H+rENKO}CLZ_9h9md4M%8O9j_#ojIDB=9QqM^Y%jO&Zf)kT7KTY&PS967*9uj9WS zr~6qoH8oXLZn2bGubO|_MdliU70k!scYg#gl;A(%l8$!K5 z>6sINSLE(gS6^SO3O|qx*R6Nwh<0%3lDrLdH)hCe6P5@HvGO#vun$pcQ65@7qud#V zLaLCSs;Y^-{al_(PHikkTBH^K#2IXOh8uP(9;=j`+`Y#JKL*mpl9Q4?LjwS;3rVJa zHN@|@)B&8hShvOzpoLmW`|sb-AkhOvS0-zJB{mrG)m{M#I1_t^Z)9)3Ge7@xmx+i^ zhpS%WHX;M?Wi2o>Utix14h%7|W`IZXDFQXHPA)s>FQuiC@c8sPwDpPQkO`oo=!f!M z{rydVZ50(2rKCE5VtmuB83HB%`VP=={nDU=nYI8${~1Xgb2~yMD7{BO^py!Oz&)?SJ^) zfDbr4K7Qz*^wi-#C#NIeT3iqw&L;bdLp%FpVP*p{uTzF(Fd<_80acp`UuqY;$B7y3K znzUvmq~6}%FOgS2s8g_|)Ix8bGBH`f<6DmvPFC7}DJ$bTz*36P#R~XUX5L?_2HVTQ zVPk52|8lPiQwD(9YF{#Bh`je%TU%Q=DTioJAG>~i8V@ijkfZKj^+4V9x%gM|?c2AW zMpKj#=8X46d3VCNsqXVlO!f50^-O#Kh_0ihrSvmVzr21QdtiQkekAapiM^rWr-TG8 zfC9R@JxklK1BCukp7_Vi6Fk_T*Yu-5t{ zGUg%|^%)iPqkB~$vH-kkO}2m6s8%+DhSC+w-1--=i>=lB&VQEq!&AMz@(VfVH;ASn zB-REj?d|(b0_$2@UU*Kow0!+l2TS?As>&Bqva<3RvOpo}>GK9EDk_DUElN;m0>pB| zA$h)pk`c(GuLEivHN86C0=ZzCeDg0mj}E?x2uNjf$1-Q3=$F&|44u{AT(-J>A>>K$zjvB z^!0sfbD;)a5JAZ=@tEc&`FDP|?SX0R)IWoRgXvYwyp2~^SGsH(uU>%!XfyHM5Wwij zrfRgUkrC&cf4i7LzZ<;b9+QUegRG)Vp_aYWrK+X|(I|6GN`?D{N#K3RI{|z2mtLHZ*K^* zt&I&pQyZ|s&3M8Bprw+Fk5Lo1&4tX>R6;e111Z7^|7%D{hzN~lsfl##c}!d!1ZzBg zMp2PBls z=)P-U#m~wr@7&o8K?fx@F3~-ud7ee5lI8K^NT0qu^?z@Kj$&s!JEcpx5Kr)-xI=k) z1u~1JWnMwSCdiu_kiA(R0szbNv^HQJwNG&=2tk3t#l#E=4*vfAyZiN3!~6Hm5Mbh| zUh149|8%VC+RQ4|VI96G8d3`TB;hY?Z?pMS!8@x^_k@zLGBGm~dKZ+J$B^F~s&-f$ z7*Kq8H|wk)`qM*?8N@!<|JMAhT~sYB)?WEuRzLxr^Eog26@nq?dAPf`cM6KD+xG8- zlob6LvilDntoQ!{wRE5uxXRS@G_s%9*Vq4|g|_+i7-W~c-Lb(;$-JuBMsFSCJ%Ahj z_z?apO*??S(XdHH^xieke*{bc$YO+=GRtLi3_wcHOHH!T9pJH^hq)~b4o*%F{Qpjt z<*>yfI_?}H=6<|IEtsYS*3t!nW$oLyZ->5_Lvr}zgRJ)J*Dt;lCSl>ZnVIA>b0LEt zen2~!+%m@sl$Dh77MGWT?IO`|$mx7udK&1ze*N9XD*Enn|Cng{V~{AxxlJuCYXGzX zodh+~2Hw*FQ~ejum-bU7W(oOjlTs=e$gX zHS0Qm38E4HP^oEmm%Y-f4=}MwAZoIm=3%<;3m9O2hnWa7Pp3APfp&c`vwgO~OIAiE zJ~dy)di-0KkmBZ0JdMu#48qhRAmB1Hts7Gn%+c&aE-_!e$ja;A!N>nG_6*`#L4N5s zd;l~P_1WhbrQE6gIc;-}HNWAR)v7221=>KvqQUPd6`i!kpVVd~`WzE;^VTi-_{Tp- zMj)BhWMvDy&yN8#02npBx}F#xkHhDL($A-gL-R7q)Vh+6fdMelSX-L}REh58O3Pt0 z!0e+(ct?LHAu%9%Pgyr~O1^xdhz>O~HB|}?g3XtEmk0tJyKXf;5z!$Ovx|#27=4Oa zYVUyjLPFKdidsp%j^Uj?+F3<2vxfyGj z%3QRxCSj(KH!Tn1U1=WOvu6p3ROgV7g{k#vX$DXt{qbE~j)3TdHfG(M)b2R`rz4)z z)6c1%qrOQn{HwVcq+DRc&rCY-$7E3~EUc0uK9eWJMMpn4Gcq)!i7fC{HK+#A9 zWgN;psPt==60w~lc`AVKt!!=Odrz7`BhLNrf;}j=pSuDq1{n&hj`E2`WIc0iKwx|k zy_mf976_o*_l^*X^!E1l5XyjI28LG~-1mMB4u0|^ngQ_sOC{C_n~bw%a#D*1|L;_V ztoAbJ=PzH*p*Q1;su%0C?r0-6l7Ia80ctF-)yNu%kq|{Oz2a~;o}dvv3~iN?)6=`0 zC@~(PqdQb}mT4Os;{mGA$k+kwZ+v`wcD519KLFr$m|lUp2Ot{~ZCNk#Bjdpo2TNCX zH^1+dKv1)xLzW@}AE}(0_a%Y2r3DEAuLa2PYxQ8fP%AnmB_%moZ@NYaxq6V|0O476 ztG|03tPDL$u%sWsS?I!AK>Wy6$^_-gtUsmKq=cbTF|-v)-sg=tqF|UaVj~L;Dt1B=pbQ2{=$1l@g|sJjEI!o}q!H#hgD7#^R9;0UBGq+Tbd z<}ipxWhYWPAgYr~E!faBnZ-sHk)_}ESA3~~@GBSexp>ORm|I@13c6%hS664}dONkR zs)mNJBhU;avZH+6Z*ACrT3nkfBv-^1&pu z6`>kvqgNJ>yhtBBcz_|)cO$J5Fq1LB@0Ar-q{KU(nUR5e@2Lp--oe4}=xEWFWkp2= zNahvgmNxMrR6nPrT){kqi;F8k@CgRajZ&B1Tm@@4 zH#e(yREWrY=ue{PLCxtaCE38Q!zlSH%gaal`y;f~B~X(2-9SZh_VldH$ualvc*Z=+ ziL4#4jV>@`SsTp6IaPlo(g11X0Ob~mDt;#Wz)=2wyZ|uR7)R+sovgk6MkrO=iwsp1 zVFD13%0H4-r}F93r}&}(`$61?cuRiAq%*l|Ngyu_s()S`}E(x@0_hcb#-;1ECvNhg1pLWGog4w7!ns3 z#|wHqv|QcBHzmDV>1IF959SR0;hPshQsUEnh+nrTfTY{Bk(I=Q=yr2 z3kkto(dF;N;ICirW*mr&+rukLOKU-I4_z%(Ff^QpaU%(frr&c@@XEeLF}H^C7GO5n zb0&aXz88Bz<;5rnVp4K)fHNANt5v1QD{A)Cl2yB06J%s;q%q*=M%({$r^Bt3Iix#+ zXa?Ycn3&kIUcj5B)z$90n+DYX;}L+#BML1Y507g{BrO;TQf{KWt(Qgc&>}z5@7_lU zE#N93I)L5W8D}_TeeyQ$PPny3|f%=_P=F4=Z9_qnMF&- z$jHdc%gfKNGaK;40&*z&d8Lrsc2Yq>L3y$AHHfs(eB{9(WF1*VQ40u%P!t9j0J#3U zNnoCW9{XQm`VP5~rf&f)&dzQdIt-Y69>P;(0N?~xUuiWeb9)?mQq)hi4Pl{F_8kIb zUW%a8LdLEMM8?6~hESAzpH&H=G@=*@%@CJ@M{c&_$qR5@93LIU_WIoeHCwa;7yxq8 z{kq0;4eSx%hgo#o+x?>a^IGA*%=y3eS_SR*5Gw2H-XkaXgtddI&c~0~#KgovAb>uH zk#lzq4k`g`pS^`VB;XgN0{u@>@jI{+P|jpuy_%bx^k@mblbxN7^7ap)I|l~`uvsiG zF9R|Hw?GP1pZZXw0W1s33v%oZx-BpYu*5_P2lS6Yc_Dl#2dmTz8+jX#O4kGJt;p-; zu2`rAJK)gx6@Uepr<9!l-XTWKz~B$KY|anY5B~f_g|4-qGqG3%6A3<$$w03X0+Q5a zAde37c4%PWWH~(r_szv#dt@X&*_~AoyuVD4OqhW>eRf>b*n9cx_|yPpsN{Z z&;6;wvWm|-L>wIUVDDg{iL^S|+Rngp-gzL=lPY`-y%n&-{x@6%IZ3&c%wJH>fa1cK z6;KT55VOl7-b&(4E&ypIB-)^(z_gpG0Sh?GGY*cy_V#v|>Z?__&a6TXQ#^g078^@^ z*#&bKe_Q1xZDg^ zKRu8HXOh+vookTnpcVk?XYk)WeIqIbUMeuUgo7YEFA)(Ns|Ml(Xd2dPTv8Nf#y9=W zP+6mf>Hz#mNd?!|@_FB-^!v3UK#TGgjE9fsQa7+ar=6U@u0a}pyQp3JgU|63h6|v} z0L&N`_JQsU`hs&yM0j{M4+*=zuE$L^u%FTTcdPw*q#lE3W^6+v6Q52FkI4CuA1grA z<61k-X5juK!M7scK|2=hcy|kHs?wHu$8jTb%1qQ$dE8G^T^%WEa2U6h+s$YLmQhhD z1I_@Xr`}~#J&0nB5EtgEW2xxM{={Y-12i=(J#8%oV^FfG2$P=mS0{u;0L2?^O+X+HNmE z351*G;^DD_(N`EhNULDLV+R=~&wVg<_r`N%!lVQ|5^CEdd3VczSvQ z559{T05t?=Xi#g4>c5E4JO!fwcJ(oeM5cm@)l>4~4Py<`pwY zW}opL!Sz*}D)T|EGx3*goKoqmly5}hy`ME@bbQtkpXp*^sxaVS{6_U zI0jooJj|bS?cR48r_VO|&Si*)GWGj{%~3QMG&E4g znVP&7S};VVARG$#>uJ59n}Dl`_JxW{bS>G}{CpXCSygp7_I3b57-*?M%{5S8)^byD zD0q_iTtaG}7lS$u7t+pm2QvWaB*gnWUOWe8BJpCW-ZrT@sUo{tQkej04d|F)sVIlCjQsBLky_d&ZFm_Hb2|94E2SzqlrSOQ1S4P?D6FPa;*$d|qQn_7GLuNvzh%Se^HlNM? z{r&%BF3{7!3|27B%FV4NFCT`#u(rndaHd$RED)d5W8Y-u6*^=n2jDGCb_sEDGIH{( ztMi>hW|X%Eun%g-`hW*KA#K%CfWoc#ltIt>5sQzNBZs(?@~g92O^lTn?_Ky1H{{^YHM{%Ea;N!A%WsmaUMyv9zQ*?~@B%sI06E z2xwK+30UTsbsYfaK~p5wFDxw%-k=5xgIGW^$ZRi@p3RZ7vbxP)GI)XaQxYwn4r>*jF`+azN&F-g$d4~eh*+r=9|_sv3qAwVy331U`~+xW(BaS z@-5)`>OOIvjGB6S$?c0u#TT&L4jaPpteqLfa^PHCAIcgzh8mJ9Q(jR4aNyPa1XS5r zd?QoS)?JMP+){4BjKsg+BrG2aw^*po1 zGxWs(<0#jN5eF=wCQD$O-9uG^*u~0!KAWIOdm8qW?@;O2yMLNe(b1^`yGiW~1hyFZ z`dAUg!Ol&9TfCf{;1w4eWLUg& zcUDeLmGyWy{t$QztXfc*zmC|mZb?X!vqmXWg%O+;6%dk;NT4feXcXHe-o#+^Y^r#| znNE;)-nJd1FQ;E;EpJPZuUFr!1d_Tl-7U{l?9 zX-2&S?S5Coc>4s}c$Z*kXeb8lNEv%9RJ+dE*(<03!WX+@?ctPgLVzh^5)G4BixC<+ zb_8^u^Rpx7ikWH$<2|fcj)X7{28N*K`4LwhiTtb|HXjEDUO!EO?gwv?la}@aghvQI zBiAcXIstJS85x1g0D7e~tCdcwbR9C6k$X!4)>lZxb|a1_mL{U~iks(d8GBW2mXu&@ zSla^0G1ccRuM0_u!I0$kcLHV^yD<8DTxbHY4RH6+;GoubgXdxVPEV7-5qSw*34Thz z6|xB73&PnZwDZ^PkdA0X|E>%>9uPzK^s*4j*#Lhanh4yE-sF*Q}I!o9<7j7^I?GZ8z7gNqB) z;As+o_~1tbA|;A@iTI_Uug^CJ0byAL1-7tW$J6u7?*{4>_Ur=ZgL#fF*%taZDk}yo}h>^!lyIb8yy~wd(@Fb3Z(L|@}JN;fIDzZFG93} zxJ-P|@G2%Sunp2PTP|S;zJQ!P*gVL@%+3y6WCFS>=&xYRVas-S^7wJCV|fyzwYBx$ zW!`Jhv-bBLt?Gca%O^fDbWdAr*9>#wG~$s!Smxpv!x%@M_Ct1777poSBsWlc$Nfn< zlWvRTLz+?)^*Sqwin1~^)~h+idt_2CUz&61$UY)us?|1!2Ezj5^YZY-#Kgm6NT-&+ zmY|H9n*+KmgR>kPfhMZiFpME0DhKfy++n9@XP{cP!gHrsNHY=v?LP+TAPARo;ouah zzk*YunM+J>gz5gUzbNe`%OgYAVOOYCF!L_lozXZn{)j|h$2)VvPAff3!aZOm%im;8 z+tyS&ecc8vI`@$&tU;~@;4=of_#YP-kNwW%p6ExAax4H^cCJ^Dm34A<2B(vHnt{B@ zD5G?R_$UM*^SfGc)6svX63qv?L}osclDK2CuFnD=nQaAy<07 zYjkVK{j(BJSk$35T{<=ey+F6-b9Hsl)2V2eAO#9jbq7;TWAq=YT2y#_R$?TAv9;nf z_NsP<8~E`TPQZSWQCaEw;>8Qd%cA`I{!gq%fWwI+CF;&jq*)#&jCl8+;!{#y0&zmB z1qobep$wgJFzK3U=LW$hgxW^_r_D#ikeKk4rmE@_kRza3F&Ra0e=^LZYxpltQjs3z z_QlERX_ZSFk!UOA?NAUZYics$qhFm!wfTkvgZIZj^A&M9JUrCZ(*r5gacv+S+U8jP z<3xZQZ{I!#hELC5e>KtMD}2;aRj%|hS%vWH_XW7Y!&d~>)|*V!n|V<;U+xv;=7I)b zxzdvWUT>JB-x0RN=GN=^NXC_`Qv&u7klXPa=9xFZDejLC9)Bk4H_)MKeXko!N;qig z9y~Axm<^>U?wzy+ui~i%cmgDH?ww5)zqn(HLmq;KPAR zRR!m);HX9WA~6XG9DZPnD=025hED?e4upG@Njt+Miv^=)fEe*9&2YdwzTYQqP)*x!Ui3H%6qJ_Kc`f{nR zKi}QLj>v!f!RE~yfdgjXAV?eA)81#^v{t1Dpt6KarfSC+f(!-h2W*XCM!^j-wzdWd zu+DCVZ)H?nec4!Ak^WH_hT*@9CmloZClhB)EQ|lst^&h`p#7U(Tqn-IM!_&KH%}Gx za@|{K1=M5#J6JTv1C<&YQ#!#h#6Dp5ud1|46CAWdef}W@u9ssYs6|A9ul~F^r}Doq zW}80(Ee(zyf|XGhP7#3lv?5 zKDKyjSP599VI4t8Qh9gII&=UU6Tk|Y^(Bx?+Nph9+y!P~K(|Iw4d@btxW`;v(X+&W zpcBDYUScd+slfQ(GZ8=>k2HFFi3XRH?7`raUI;@BWK&qoujVuc;z~+`5TUb1LkjJgD2;P%?8f}GpMUh>5y-FYO4TtdycVE9KdIHRSfDePvOYT_t5YAt` zGNoZ++5qi0`+u+#+%AwV2ivZ9&Gq1i#RK5z$Diy&3RI4nLGzVzzdOKLreweC<+r6eSDj{TY` zwMU}PJ7hdEs$>xQoc|;p0Cxb?57ClHsey-uLIK|XePD)%XZ$d}g>JM3unxp1_{|*1 zgn@H>5T44)$}l!d0gFADo?+$%qBX!4xImO@guj7ZiGOS;ih8ZU_FgVGjjn%eBshV5 z&^H{L`b`3-X%~otplN-MjTN5>y>W|xj7&PB@qUz#n89qxi)N@vg_-YMtgNhHPXVHV zR17u27zTl$Sa5WAjqo~J#thu=973vGz%k&EmiOs?fG12#t)Q6$*ntkj4KAHONuXQ+ z%>(KW%@>ba$Oe`W&eK8|f!)djG6kqD!~o!_5_l6(HNaD45x>}F5{W^qx>Z`S_J9T+ z-rNy=CRa&iVx$9%Bt1PWFw+$hqMFp651#c(21x=YyYctb^!4qmt!0Zy<>4 zeItaFAHn_7@Ou6iC=~GB<@rt%Aa`5Pe_+F-^uP@crl_WHZm#FO(ZjHz>U|H9TVyq3 zZ);%@4|bFIUKZLj^WI(lF5n}|Dk{j%_$HAqSNMf+TT*gzf$m6EDGV;pxRCbq3UV90 z8{8C&fKz}9!>jZ7yWw++v@0?|T=ygYa2u&qhgQz&vhe~xjf@sjeXrJcc91AxitTsD z>H!8Qga*fdCks{eAIQpf0~#rDWFj*Wy`{G4LIw))^UG%>|KmOOjSyeeG<>>shnp)G z1ZD!f7A18!=y|A&rOOs~%3x<3XKW&B2~uPv2S|&e@>K0m1W`~RW~c}V7XJL9iBq;# z^(Ch-m$Ct+8b-HBK{-G)9Sq)pe(v)RiEh0*B8pDB!9gIr>f*)J!JqBcO8>$_oZAlKzKV$PGy@0)bOO{t5Vo zJOonyeUdvpJw4=!=E;J#!^jwn&k2ZsisZH<1K$T0?pwsor~n9M?YUlslOi-F(KbQg zL;Cn@8|kgq37Je(_G&?6)mzW^oQN)ynef)hV6oKc%P2z0d&0++OC6T0BA; zh?|^1du^BjEJ6O#2h@#>jQd_*=d~X(5gvCMPPCW14Als(=IU37D$k0*hd_GU8Z)RF zWXEgZ9axx{;9*8`?}X9Ld*t+4cPJ^5+B&`L=Uw-D@MMF3Z55W~^UYGSuK(=?kofKc zv=<5y9h|6u3JuyOzx!?)6n*F#0Q~u!R^&X}2u$fm<#MZGS;d2%!_**n?in|C?3ALK zn(2^$5~}E9!i0BGe~teF-8gKX0i!I7f)y5`2bwtt-WU;X5a>kLJ&D|*A>*K8a^{w) z4=_Huk*-(`)&lS`z-h~=mX;+D+@anKZ61Ne+5yZ(Fu{S2${xq263tRz|^P z_VJ(7=g*(1_+395hy?$Na@T#3LWYuyhm_x7z}8uc71Ru6OkPtnKHsV+H6o7ci45iz z6jA6RFf@fjQXma{`bp#hRp>)_IM0(Ohj9L4*&n8%U;+|wTnYx`FmeirL;fOyTlwKo zhkuAdluc23I`G^ykS={Y3kvJ&-vE&E$G5fJf~m*2JK8FM05}7+4WJ~od(ZnAv> zB&_wyHgF|F^D4Z18-YVePT%SRrz_3PSHTqt#1!1Jh1*y)hm<^gCR4PzgI2wZKvkD7s#tO9{ zTA=|#J>!i2z>s%?7N$0Fg;bHnzklm`-XlJ}#^VjX3syY)#aU*=_gi663;QQ0NPvK} zqzMWl1-H!12k%4SlzglbH&_HWm z-Q4_=oLrQhjqLLSd<;NutZAtuaIQX<-9HvZzUn(`1 zsan35l)zNO0eNgj0k_T^kfq{wf;z=Rh_QT#I=H|Sf4WsQXW}}j%}Vm11VC_LP!Q5n z2fEKtUC6zXSd3T^y;Ocsklf%5tBVW0KOCgMxcUQzYq)WY6eCqlIG_VZ9@BiGblq)6 z;zqD*RTSmtTUlCm`Z%Pq)Vl5T38+PoajgKXgQ!hfR1#lL`_pp6zY%FLMaGpc~2q*+z3ZDy; z-SGPsfRyO8$gwHgO%t>*0x7f3D0*O)pcxXdkf0hpnJ|!_=pBnnPcb^&-xn>*5`hK_ z7W*_{32>#SgOUpeQ~gB^p{Xk<^u0wz1N$DtC=i!At5K%2TnPND<7s<9v?FgpapUIU z$;Q0^=bF2_yOb1qYQKht2Aoy@4)p$>?{kDAi$#nG3RsGua*huSOu)#x-ulKe?Wzqp z?A)#{JaB_Df4lu3?Oka&m2J4)jeJs3s7PiR8-zlJWY#u|>`+MNN*OZ57rvroCL}{r zXp2mlQ)EiBEfQtQR8r;)XT5yixz4%HaGi6Vzi0m}ws*hp^W4w6*IM`5n$fz)kKbCY zE_2`jbfjDh>0#nF%*^o|{)>4+`2ZSa4ACOF3&3`PKel>H(T4-^mcdi)=A)JNhDMJJK4<)b~0`IEcc~b8>y+Ssnl6 z-}K@Ie;`;7u#xqjT_<9dxWhgEcp_*s{MQYKc93{`xYB&|lTVYvZ{0dV-$p!*b@oV% zd24ev1`DC_v&cj;VUbxflI_2+YAvH(S7il65ePZuj`k@SDoTinL4A}&;*8$zBk>Z5 znYoY70m}g<8Xgf?a4_!*DwQ#(ue&=kIoZ;}Vpo7;3k7Qsox{(Zl^+6~KD{0s8iJdk zzKnt7zgUPe4b8Wyj3J!aLD-IT>hkGr|J&G~|I$nJKTi(&|F`(Z-KDn+2;2@DFNN^9tE#AABBk{)&IEJVv#~gHEGink*1H8Rr9Gw0!GC}*iA=9aCdYV) z8+$_l2WgBY*l6<=)bD0xLOttCb6CIpXBvV~?+={2+^(am8+T@J%OC634daZ2G#5WI z^5sivP7XSd$cPA@Z%-Z8EdNS;Ol<7S#Qk9ld7ZYySFc_L=GoWLR$p%i`U`?IkV=Gu zaUpz-*r_Qm!17G?H*?I^;W(|&yE%m5f%cA zEm>3jA8Bf6{P^|jBgzZGCk8h4CEUFEdX!e2sSJh)$`EKDfde#5yTf__2?7Hr6HouS zN+*c^r>(8w?b|*})TFl`C#YS-tvH%L8f<{W+rwk$M1Qc_-*?#+eG#xX5V32?BH1hL zaL%bHDw-cOD+P9Mcoh|^;3Xb%&vwbhh(df-RTX+jl;j%As|f?M=s0l^ZoA8FEGLac z(}mTc+l|0TDF_o4%eZq@6HxfkcUR#&M%PERtm>rE+##kIe?Ru=#IUeohL~yY3A7Lx z1{D()WP* zA~;_uN00XR^!$Q)*eIv2q5=Z#XaOaO>1odxOarRUI|T(h%RF@FSTlFB4?oLgTD}1S z%p4qL&28V}DJhg4Dm4E*F1^ZV;c{we|T)QHTILesmSA(s4Q0^BKK%E#LhptCA zTgSfc_P-^+%|jl_Ex+k0gabha$70?tWa>l1R1PP?q+yG!WC zjwhjqG$XjVuQ{Ep3xB~ibwqG8KR*x8wXRoOw-cwnmrd2B$}g19RCvRI*Q*&0)*>Av zc9<{-h5(@jjjW3+qZ9IeIqBQ2X7;?SGz8S%lR_FHxw0h9wBT~oiWFY zU7VbHf6WYCO)V^x!i*_8ZbA{WL@Ow34{y81L|k6J)U{e1aJE3kI~rSM;ErAOEbif()QLr%%>yMLF|P@B{nREsBs1P>p%K42rD!2@)?eefdhosTFrHO^9fG{8EH1$BpET>wuAIB&SZ*AmY{!5=bu?!WTS zC$+VzFWctl=Fm5y3S%@}b3^)wcl}cS-UZXsr%!_?)!+w5%X+5y4WAUJH;gKN4Pk?W zgD{J-sAB5Eu z0O%O|X&;co-n|h8zx(af#&)y-r;4#@5A7nq!{?J2l9$-GZ^ow*Ncz@0oFV|iaK@p7 z7uj-llxO+*7^6_*ECLHK@#Dup-g&Tpmi@Gqe{y34si0x)MFX2H6hjs_jAo!;M_1P* z!#lc`=Um`(_kEiSmq>1Ic!gj)QnV6V(x;de5VBo${dDfrHD`5(Qox~_9PRgIHY}z}TKfHZwK%qD~ zIAq-(5YpoH#o1=nS|&-RfDLJDtC(s77>4=^S6aOyr!f67kOAEhS(_Y`aXq99uh6+# z8XH4U5nSZM^2sC|wskHt3ju6~h~YuR(b; z6fuo?Gue^QL}XB5PdJMBV+IIC5cSetg!l_2VVoT>tkSPvKR<9MtksG_%ecm%TaFdL*LX23@$UV^qOUac7 z;{I|o*@-NH_&jhd*iMKazyP%9?1SFFJceFUapP2_<8v}IHMO;)%3I9y+-z<8F`AFT zK^!i<$pfgYy@BkZTLSgklPSf;#n%>%#1k^)t^#)jCU7Pp;3$uAvX^|Kdwn&3$FO|i<^0f{R1n~=$WL?zbOe-1mOea<#P~n zBBf|JqyfM%2M(7Y#JBIIG3ukBFa!kzsK@egj_$`*pmxD94nI+hSW(XX`&Z#z_;Q5{ zNs{nF;YaQbh^2Gabah!4R*QaJ)l9_z5}Yo5nh%6Seojn$Ds(h~dVrHtb|D{wC8Y2# zFb<$tVas!HU?rjyK7^MN4q5CV3b>eM-_y^$_gTDn8=(j4ZNu$l3~l0}b>Bl2W^8^{reM((bzvLN!q z!ooncr1iwb#zK;ZKn&45i|>-EZ%T<2`JKe1NSu|eElfj^&|(O$WtZ<%lG&=IYlnZV zx2Q4mk3&xH@`>3JZrc?WVMpNDe5`2iI%ddEQp1q+0~ zSd^Q-lrnUCH|gc*#{Dp(QNh}fVJ4PGP*9D3Q>LgG@fa&?U0f8-bRNWg1Xl}^3Rx@X zp*L1&K2YUlZhJxI=(OTjsOd;3PY_vD8)i{0DJw(eA>5&o)S}14TZ|{CY2T6nVUvIV zem&Oer%&brt0p_I+@!pdlt+Wfc1>WB?}%X3voCs!;<0q3P`kJ=J)v|VEzGOF+h(b@ zf;29Ws&_Lc=5AI;0>3S+(m#)EZ+;tlU^Y^@mS)x4>JH}>%)xFdYe*7v!aGMUzGd z6(oGdKme+BvhU(=;QA^@OUCUhjjO8O~x$pD|T;_afzuQ08!D#c%;( zQUV9P1H(qr_+eNF+}sM4y$jv0@LMY=D1eL|owpN7-&x{@u?~c$pd)_v>=}e(n)!YM zr%#34kh|u_-|1qz5g7|3!Sz!cpuoaoSh10Vq@*1f6y*E+Td|Kq*Ry9mXk%OzR5uNS z?8N0C$CTdd9|76>R+EBmCM1A{2m={gvHc#E`VDI{dXhCzZ#IGgdfE}N31$=U>IdL? zL*5SFpz~vXnUy18G@NQkiOX*rnVfXrb{%E`3qJv2Ox0&y?VrCo<0yQS)&9-2vCs$syv`BGtKY8^^*Kh?YC?Y4O&>JQ&D6ReU zl8WWdw(EHPm$S-;4>z#>+$fx?=ZR)BXTFQ#gh+?(-d_HNX&4LJqH;|0tl%J&B%d$o z=v=*#l;T`7=!RJtf~L|2^M6Sm##F_H=~cwvw1<5Ih%-^a7qR49aZAC=!`mmt>d#o3 zM1d3p&Jz#*+C$hOBGoiCgN?p^51|T&XlZI9(?ZZ0r-`=#C@hQ`hok}2#oX9VQj*iW zOK8%uLwW`VmuuLu$z*R~GNcHK@pot@xVY|X;M#Vsr=z3GT##@tvduGv%#tqtYSJhD zES6eje!gMJ=M|)aSR1c-7?8CxTKV&KiHIm$ttb7kz?-2h9h;fMOh(8<78Vxl{+k75 zF76ud3V>fcea#pWn+0XOTGPw3A=S$rH~?qtU)!mSq?FUR6*v&%EH53SP_*^mqiezf z_&wAj%8z{KPj9|-%mRMFW5uc9^LRSsv4%BrSJ0hD4ej~0uO*nYFnZ}AfGCXWVxSfu~2p{$Iq}497Pwd zP3oYMQYeW0)XHl712Q4s@2}LMlwN>hVGpOQsy>c#$VH$+;F(L!=y_|w8*vpWO$d0H zp4?!!YHh$5td0_$d&+>VLM&O0Z`~Tn77y6)m1a=)15-oDrO{(Kb>c)W2-M7% z=^xCVmloQpte(oj zz`#)O&GV$c#ViVecgH0Y8RQV~Mrd&I1!TN$ZJqj{e&xKQaJPKcr;ZL&vDo+K2^o+8 zY~FiACx@#Bq=3x5rpCtZF;5^qqlS_s1DtJa;$}!aN&gu!VE{j%y80C=Rs3l1xT&)< zb+)nrCi!oz50ewtwz>fo;2a(p7~tkw&&W9P?Hjh36i1A-ql?QfadGgQgcg@!y`n_S ztU!azw_j3{yO_4`=iI5(oh5}z+!{JMg3gZ)-DYX4rLm|c$((=Q(qg<&y3)WNF~bgS zb1_bKcAj6Ju8G;WE~N}ktol6i&<|)_$jW==z<&H5puf!deqiJy$qMqA<%69JrCL~2 zv<$M|z2r+-g9D_3PiS`}Iak{GZ>VY#8U%3bHujQE6n8U0^H>8v6E+i2NZ&1>$Kc+| zUes&S{NYWGJHqxu>lq)vfSvsK@c~6e#kM+VqCTI;`HK<8q+pMs)?=oo8lS%9eei;J z0H!Jw7gwD)xHdXE4#JA_?I069DJ8BZxDZjfIHMpL3WZon#KYyYeFNQ~6iLYg@5RPt zq;RggCdb1*0d^~>YTl#yJ9Td1j5invS2bWtt2}dm1xa$CB3P>0Mgl%jFvb@n+h@mxqkW!NHW`tVs-(z%{&S*N4JfF@3RI{EbLE7qo>S>JAfu_)YJ4`fN z=WdZmX4<;0!;oJh$QkHUKqK>?aWipBijS88djsb^5`kxSLjUHJNnN{!2PJ}k^DtD> zdWDM-)h95TFqC+v(%#AGmZIM!v~9_?f25Rw(>s6|4LBciis2W6T@ohxH&gn;fBt8! z$b>DE)VwS{5CX@}Ubr9`)sQX}^6bkG&x2#Y{Ky_bXohIzTjZLd>&00CFb1f6G?g3y zmHGyt2@Xtq9zUIhLx$`B7=HO;yVJQ0m5w* zEAhz@;+NOvw2aUE7Jemz3nttMDEus(RnV-&#hdHv>k<6QIkt*q*SIs;ryF#uo)vk| z*6Zj|M<9&B3GoY~sx2%#NaLMd3zNlJSt226{8gQ;B4E{UY-CfZG57Wz8$jP!kPu*S z^Y*PKAwVoP=+)b|AIA;W(?bRz`;HwiZS&QyZ_Pu@*Oo0?u%GYJp&`Kh5YYY(8P{|M z>$RlUj|unXyjVc>2OtrKfEA>evWvfLF)wd_&0`l$8d?VWB3IjEFfc+vg(+TKRCL&@ zD0uB4#YG(W9WPk54=>~QsY^-`8Y)`-V{ClD<^$ot6wV)V56$U2o_9>hICU#cycQFe zP}#t*&EY(){QX_7aBT)tMb;mKLx6D-H>{27(TYJzhi4jNSjH0Ecq1h)@XgaxRg2;a z$P3J>K2dsDntW8qneP-2Xa-bu^OM3l$>$N^@;8t#uLVG-YuYzkm ziA8mR%&}ufPJ8Q7B-_>otRfBE1<*64PyiqNCR$8-L)`mml4RYRd%$}&EYe3c^qxHc zFotWyT^hPZ=9#@k0sWacvi|MwRAfLvw8Uq`w)IwICkZ(;MhjyrgF?eAi?hUUaRE)Q z$+w%R9lZF41gO@qp8du|W6hRA>EfeS^3l(}jC55k0#%~RL;GZ+ej?=U*A{kGHi|XH zk<>ifWVrxy6rVu=bgDCzGivV?xk&y)g+)aelN-!_SP7Cn>bS#$>}*4DwKr&BVk|eIqP5a0ZVmb=ePyVSxkzys^6FW-5)FVs+QXCTL;QJZQ zp?K7SM*EDj)eMeIh|Z^URoIj^Z`xG3& z6AAXNS?fxawR|ul12Uv+((g=OArv#5DAU$qD<1y47NP5J4t4xb4Sw9l3Yhl$5-xBJc4RjhB!Ov6ij1^EC{a7(+QXCSg5dl+J6Tj~pFbDjEcu6$ zro-+-oFDeJ->7+m+b}Yw6p|m_*orNTfh0_Z@Lb%~3uZ?1S#|ZHtg7ot)MH{tjf`0A zoATwkF5cPuPZMCgvSf+8e2KK?HW0_~Xu$vTqjQ58TQ+)`?l1?lQUtj}4Z<`(i>0uT zkSD_4?LFlG3d^tuJvBC4z#^SUb{)^ryl8^)0{63L5&PK;i(d3~3)b+Z@RNaZbm;51 zNg!6?e%Xd2f`+aWCghR{ROr}U=HPSAj-3`O|X_GL8AsKqYF8SCP)s}mq)p|pT|70XAZk8eN7F+ zwd>b=T}xo60GIm68&iq`f`XCmUE7<5I`1GyF|^i7^V41Xc6>gy3Uyfgl3yWAGx9vX zg+mNb)U{Uw9*Vw|-{pIkz89x73mhsxzYWxWpiX&rpwI739cJ82NEnNfZsXPs8L@H< zNyD^P&(M%8s*KEO{umkzd$B%_`C(to0dh$sbExd@I2zzaYkXJo>P8q35R;yzrEa^E zG-W6UOC%U0Vvv}i5;V$~0|X z7XuG(u_D4E3BLQ_@E9>jfkqIfR&={DAtq9PuY}t;b)kPffWENMZq;yS8+d33M@J|D zEt@%2HPc54u;3M!VULFc32jONQ?J1|GcjyGbB}Kg4^%GWg9gURWO{rc|L-#}o@Hlc zfurd4t3fbo!<^;!dl^*anwm@>FpjNd5+PJHbl@0#U;+C6vU*Si$X-tFhz{^l=>8RF2l!@^B_t(B0(z`#F!8Cy4tx?*Dsbn6?C#yKkS2+S6<=EN z^OY(al`yOJ*a{E*wM^j0!Mft<<;4*66jO3$Z%zyBFE{jXkwt-_zHJ$^yC=kCkudd%JS(K;@<7lX4i=Ed;?L0a_@;0jO@E4X7V@X{-)r4_3OV zMdW1Q#*(x24s6HV;O4G0`}U_#tq>{IE!y1NOw0)(Clh-aOwu;Szveb04;~9jPF5C6 z#4u<~ln$bY-R=kte#CTb4ErXZswcE5*ho$gDG|m%c_#!$wD}3M3iKG8#X6KHJ+6g;o$N0jnLw%DnjJfc!Gzg`*qC41suY2mx&2 z#Ez_`p`;=u1fz8UnVI&0yabN?2l7gL_Ca=gZGdn5z#{@zfNyaMW4MC(-Ejy%__`yE zcBMT%xq_tR3mst_3yX?=G?9O`EJ-Tr5mX_9HVxI&mI{ zI=*@VY5{=B@9Alry~47Wz!c!o0!%88aNj<*w?})sgC@fA$O={02jZ<>dO_2Ipoj{BH*u2oM#2hk_=R)l zQ26z|eoRk$!Y=DM){T3Twa4}@l(5&bP;cPsEBISvkrMhN%E* z0FR9>T9Kg$d#+O2~@1mx!uirDw>Igu;8M-~0J^~I9r SXJv^3sHv)>lB0a$^1lFPP-6@L literal 0 HcmV?d00001 diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 973339f0c3..482543311f 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -1,12 +1,13 @@ -r"""Block Encoding of Sparse and Structured Matrices -==================================================== +r""" + +Block Encoding +============== .. meta:: :property="og:description": Learn how to perform block encoding :property="og:image": https://pennylane.ai/qml/_images/thumbnail_block_encoding.png .. related:: - tutorial_intro_qsvt Intro to QSVT *Author: Diego Guala, Soran Jahangiri, Jay Soni — Posted: September 29, 2023.* @@ -19,74 +20,68 @@ learned how to block encode a matrix by simply embedding it in a larger unitary matrix using the :class:`~pennylane.BlockEncode` operation. We also learned [link] a powerful method for block encoding a matrix by decomposing it into a linear combination of unitaries (LCU) and then block encode the LCU. - In this tutorial we explore a general block encoding method that can be efficiently implemented for sparse and structured matrices. We first explain the method and then apply it to specific examples -that can be efficiently block-encoded with this approach. +that can be efficiently block-encoded. -| +A general circuit for block encoding +------------------------------------ +An arbitrary matrix :math:`A`, can be block encoded by relying on oracle access to the entries in +the matrix (see [#fable]_, [#sparse]_). A general circuit for block encoding :math:`A` can be +constructed from such oracles as illustrated in the following. -.. figure:: ../demonstrations/intro_qsvt/thumbnail_intro_qsvt.png - :align: center +.. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% - :target: javascript:void(0) + :align: center -| +Finding the optimal sequence of the quantum gates that implement the :math:`\hat{O}_{A}` and +:math:`\hat{O}_{C}` oracles is not straightforward for random matrices. In the general case, +:math:`\hat{O}_{C}` can be represented by a set of SWAP gates and :math:`\hat{O}_{A}` can be +constructed from a sequence of uniformly controlled rotation gates: -# A generic circuit for block encoding -# ------------------------------------ -# An arbitrary matrix :math:`A \in \mathbb{C}^{N x N}`, can be block encoded by relying on -# oracle access to the entries in the matrix (see [#fable]_, [#sparse]_). Suppose we have access to -# an oracle :math:`\hat{O}_{A}` such that: -# -# .. math:: -# -# \hat{O}_{A} |0\rangle |i\rangle |j\rangle \ \rightarrow \ (a_{i,j}|0\rangle + \sqrt{1 - |a_{i,j}|^2})|i\rangle |j\rangle -# -# Given two registers representing the :math:`i`th row and :math:`j`th column, this oracle extracts the matrix entry -# at that position. Where :math:`A_{i,j} = \alpha \cdot a_{i,j}` are rescaled to guarantee it is unitary. Using this -# oracle and a :math:`SWAP` operation, we can construct a quantum circuit for block-encoding :math:`\frac{A}{\alpha}`: -# -# .. figure:: ../demonstrations/qonn/fable_circuit.png -# :width: 50% -# :align: center -# -# Finding the optimal sequence of the quantum gates that implement the :math:`\hat{O}_{A}` and -# :math:`\hat{O}_{C}` oracles is not straightforward for random matriceses. In the general case, the -# circuit can be constructed as -# -# Fig 3-a of [#fable]_ -# -# The gate complexity of this circuit is O(N4) which makes its impelmentation highly-inefficent. -# Here we explain two approaches that provide alternative construtions that can be very effcient -# for specific problems. -# -# Block encoding with FABLE -# ------------------------- -# The fast approximate quantum circuits for block encodings (FABLE) is a general method -# for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted -# to compress and sparsify the resulting circuit. For matrices with specific-structures, FABLE -# provides an effcient circuit without sacrificing the accuracy. The general circuit is constructed -# from a set of rotation and C-NOT gates where the rotation angles are obtained from the elements -# of the encoded matrix. -# +.. figure:: ../demonstrations/block_encoding/rotation_circuit.png + :width: 50% + :align: center + +The rotation angles are computed from the matrix elements of the block encoded matrix as +:math:`\theta = arcsin(a_{ij}`. The gate complexity of this circuit is O(N4) which makes its +implementation highly inefficent. We now explain two approaches that provide alternative +constructions of :math:`\hat{O}_{A}` and :math:`\hat{O}_{C}` that can be very efficient for matrices +with specific sparsity and structure. + +Block encoding with FABLE +------------------------- +The fast approximate quantum circuits for block encodings (FABLE) is a general method +for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted +to compress and sparsify the resulting circuit. For matrices with specific structures, FABLE +provides an efficient circuit without sacrificing accuracy. The general circuit is constructed +from a set of rotation and C-NOT gates where the rotation angles are obtained from a transformation +of the elements of the block encoded matrix. Let's construct a FABLE circuit for a matrix that is +structured. +""" + +import pennylane as qml from pennylane.templates.state_preparations.mottonen import compute_theta, gray_code -#define the matrix +from pennylnae import numpy as qnp + n = 2 N = 2**n -qnp.random.seed(1) -A = qnp.random.randn(N, N) -#turn the matrix into a vector and normalize +A = qnp.array([[-0.51192128, -0.51192128, 0.6237114 , 0.6237114 ], + [ 0.97041007, 0.97041007, 0.99999329, 0.99999329], + [ 0.82429855, 0.82429855, 0.98175843, 0.98175843], + [ 0.99675093, 0.99675093, 0.83514837, 0.83514837]]) + + Avec = qnp.ravel(A) alpha = max(1,qnp.linalg.norm(Avec,qnp.inf)) Avec = Avec/alpha -#obtain single qubit rotation angles + alphas = 2*qnp.arccos(Avec) thetas = compute_theta(alphas) -#define control wires + code = gray_code(N) num_selections=len(code) @@ -95,9 +90,6 @@ for i in range(num_selections) ] - -#create a circuit that block encodes on 5 qubits, 4x4 matrix -# hard-coded circuit dev = qml.device('default.qubit', wires=5) @qml.qnode(dev) def circuit(): @@ -113,7 +105,8 @@ def circuit(): return qml.state() print(qml.draw(circuit)()) -# + +############################################################################## # The rotation angles, :math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained with # # .. math:: \left ( H^{\otimes 2n} P \right ) \Theta = C, @@ -130,9 +123,9 @@ def circuit(): # We now compute the matrix representation of the circuit print(A) -#print top left of circuit unitary print(alpha*N*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:N,0:N]) +############################################################################## # You can see that the matrix is a block encoding of the original matrix A. # # The interesting thing about the Fable method is that one can eliminate those rotation gates that @@ -159,6 +152,7 @@ def circuit(): print(qml.draw(circuit)()) +############################################################################## # You can confirm that two C-NOT gates applied to the same wires # cancel each other. Compressing the circuit in this way is an approximation. Let's see how good # this approximation is in the case of our example. @@ -187,22 +181,14 @@ def circuit(): print(A) print(alpha*N*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:N,0:N]) -# Block-encoding structured sparse matrices -# ----------------------------------------- -# The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, requires on the order of :math:`~ O(N^{2})` -# gates to implement. In the case where :math:`A` is a structured sparse matrix, we can generate a more efficient -# quantum circuit representation for the oracle. -# Sparse matrices that have specific structures can be efficiently block encoded. A general -# circuit for block encoding s-sparce matrices can be constructed -# -# Fig 5 of https://arxiv.org/abs/2203.10236 -# -# The circuit has n qubits and m + 1 ancilla qubits. -# Ds is defined as HxHxH -# O_A, O_s can be constructed for structured sparse matrices -# Let's look at O_A, O_s for the Banded circulant matrix +############################################################################## +# Block-encoding sparse matrices +# ------------------------------ +# The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, requires on the order of +# :math:`~ O(N^{2})` gates to implement. In the case where :math:`A` is a structured sparse matrix, +# we can generate a more efficient quantum circuit representation for the oracle. Let's construct +# the circuit for a sparse matrix that has repeated entries. -# Problem setup: --------------------------- s = 4 alpha = 0.1 gamma = 0.3 + 0.6j @@ -228,10 +214,7 @@ def circuit(): print(evs) g = qnp.linalg.cond(A2) print(max(qnp.abs(evs)), min(qnp.abs(evs)), g, 1 / min(qnp.abs(evs)), "\n") ->>>>>>> 04f8302b (messy sparse block encoding section) - -# Soln: --------------------------- def shift_circ(s_wires, shift="L"): control_values = [1, 1] if shift == "L" else [0, 0] @@ -241,14 +224,6 @@ def shift_circ(s_wires, shift="L"): qml.PauliX(s_wires[0]) -# Sanity check: ~~~~~~~~~~~~~~~~~~~~~~ -# with qml.tape.QuantumTape() as t: -# shift_circ([0, 1, 2], shift="L") - -# print(t.draw(wire_order=[2,1,0])) -# print(t.operations) -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - def oracle_c(wires_l, wires_j): qml.ctrl(shift_circ, control=wires_l[0])(wires_j, shift="L") qml.ctrl(shift_circ, control=wires_l[1])(wires_j, shift="R") @@ -266,14 +241,6 @@ def oracle_a(ancilla, wire_l, wire_j, a, b, g): qml.ctrl(qml.RY, control=wire_l, control_values=[0, 1])(theta_2, wires=ancilla) -# Sanity check: ~~~~~~~~~~~~~~~~~~~~~~ -# with qml.tape.QuantumTape() as t: -# oracle_a("ancilla", ["l0", "l1"], "j", 0.1, -0.6, 0.3) - -# print(t.draw(wire_order=["ancilla", "l1", "l0", "j"])) -# print(t.operations) -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - dev = qml.device("lightning.qubit", wires=["ancilla", "l1", "l0", "j2", "j1", "j0"]) @@ -283,15 +250,12 @@ def complete_circuit(a, b, g): for w in ["l0", "l1"]: # hadamard transform over |l> register qml.Hadamard(w) - # qml.Barrier() oracle_a("ancilla", ["l0", "l1"], ["j0", "j1", "j2"], a, b, g) - # qml.Barrier() oracle_c(["l0", "l1"], ["j0", "j1", "j2"]) - # qml.Barrier() for w in ["l0", "l1"]: # hadamard transform over |l> register qml.Hadamard(w) @@ -310,10 +274,11 @@ def complete_circuit(a, b, g): # ----------------------- # Block encoding is a powerful technique in quantum computing that allows implementing a non-unitary # operation in a quantum circuit typically by embedding the operation in a larger unitary operation. -# Here we reviewed some important block encoding methods with code examples. The choice of the block -# encoding approach depends on the non-unitary operation we want to implement. The functionality -# provided in PennyLane allows you to explore and benchmark different approaches for a desired -# problem. Can you select a matrix and compare different block encoding methods for it? +# Here we reviewed some important block encoding methods with code examples using PennyLane. The +# efficiency of the block encoding scheme depends on the sparsity and structure of the matrix we +# want to block encode. The block encoding functionality provided in PennyLane allows you to explore +# and benchmark different approaches for a desired problem. Can you select a matrix and compare +# different block encoding methods for it? # # References # ---------- @@ -340,4 +305,4 @@ def complete_circuit(a, b, g): # # .. include:: ../_static/authors/soran_jahangiri.txt # -# .. include:: ../_static/authors/jay_soni.txt.txt +# .. include:: ../_static/authors/jay_soni.txt From 021873cafeb301c2b33d7d6d9315b47c4c18a8cc Mon Sep 17 00:00:00 2001 From: Diego Date: Wed, 4 Oct 2023 15:15:39 -0400 Subject: [PATCH 07/61] Edit fable code --- demonstrations/tutorial_block_encoding.py | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 4367d41271..a5ad0d9166 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -92,8 +92,10 @@ #define the matrix n = 2 N = 2**n -qnp.random.seed(1) -A = qnp.random.randn(N, N) +A = [[-0.51192128, -0.51192128, 0.6237114 , 0.6237114 ], + [ 0.97041007, 0.97041007, 0.99999329, 0.99999329], + [ 0.82429855, 0.82429855, 0.98175843, 0.98175843], + [ 0.99675093, 0.99675093, 0.83514837, 0.83514837]] #turn the matrix into a vector and normalize Avec = qnp.ravel(A) @@ -157,7 +159,7 @@ def circuit(): # have an angle smaller than a pre-defined threshold. This leaves a sequence of C-NOT gates that in # most cases cancel each other out. -tolerance= 0.07 +tolerance= 0.01 dev = qml.device('default.qubit', wires=5) @@ -181,7 +183,7 @@ def circuit(): # cancel each other. Compressing the circuit in this way is an approximation. Let's see how good # this approximation is in the case of our example. -tolerance= 0.07 +tolerance= 0.01 dev = qml.device('default.qubit', wires=5) @@ -189,11 +191,19 @@ def circuit(): def circuit(): qml.Hadamard(wires=2) qml.Hadamard(wires=3) + nots=[] for idx in range(len(thetas)): if abs(thetas[idx])>tolerance: + for cidx in nots: + qml.CNOT(wires=[cidx,4]) qml.RY(thetas[idx],wires=4) - # [add process to remove extra CNOTs] - qml.CNOT(wires=[control_wires[idx],4]) + nots=[] + if control_wires[idx] in nots: + del(nots[nots.index(control_wires[idx])]) + else: + nots.append(control_wires[idx]) + + qml.CNOT(nots+[4]) qml.SWAP(wires=[0,2]) qml.SWAP(wires=[1,3]) qml.Hadamard(wires=2) From 6ee17edf4c647bd27d1fbfd0a568ac4d0d5ab4dd Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 16:03:47 -0400 Subject: [PATCH 08/61] add better images --- .../block_encoding/fable_circuit.png | Bin 19262 -> 30502 bytes .../block_encoding/general_circuit.png | Bin 18758 -> 19246 bytes .../block_encoding/rotation_circuit.png | Bin 30469 -> 0 bytes demonstrations/tutorial_block_encoding.py | 2 +- 4 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 demonstrations/block_encoding/rotation_circuit.png diff --git a/demonstrations/block_encoding/fable_circuit.png b/demonstrations/block_encoding/fable_circuit.png index 14852b2b4ef6e41189ad8f2564dd262b3c5576a7..356a4aed4f9138149c5be76a4431fd1ec45091a4 100644 GIT binary patch literal 30502 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 literal 19262 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 diff --git a/demonstrations/block_encoding/general_circuit.png b/demonstrations/block_encoding/general_circuit.png index 433948003291d2fb28b0c7c60d4bd95fb919246f..842f12b6aad63a49749dea4fbc1ce1693d1909f4 100644 GIT binary patch literal 19246 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

*0& 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

O`6{pI~fc{+-kdt7dO5KRNIx9*WYhs5-fsp0Aup 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 diff --git a/demonstrations/block_encoding/rotation_circuit.png b/demonstrations/block_encoding/rotation_circuit.png deleted file mode 100644 index 58084e5378ee94d244e738a49422d6f7ee150ff9..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 30469 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�ohN08lZz5gLew+^# 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 SXJv^3sHv)>lB0a$^1lFPP-6@L diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 482543311f..d36764ffd6 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -39,7 +39,7 @@ :math:`\hat{O}_{C}` can be represented by a set of SWAP gates and :math:`\hat{O}_{A}` can be constructed from a sequence of uniformly controlled rotation gates: -.. figure:: ../demonstrations/block_encoding/rotation_circuit.png +.. figure:: ../demonstrations/block_encoding/fable_circuit.png :width: 50% :align: center From 30d6919c07e6e59976f6fc9c1b12bf9039536cca Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Wed, 4 Oct 2023 17:26:39 -0400 Subject: [PATCH 09/61] Clean up section on block_encoding --- demonstrations/tutorial_block_encoding.py | 79 ++++++++++++----------- 1 file changed, 40 insertions(+), 39 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 50c2bd4a54..ad0572a70e 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -12,7 +12,7 @@ *Author: Diego Guala, Soran Jahangiri, Jay Soni — Posted: September 29, 2023.* -Prominent quantum algorithms such as Quantum Phase estimation and Quantum Singular Value +Prominent quantum algorithms such as Quantum Phase Estimation and Quantum Singular Value Transformation require implementing a non-unitary operator in a quantum circuit. This is problematic because quantum computers can only perform unitary evolutions. Block encoding is a general technique that solves this problem by embedding the non-unitary operator in a unitary matrix that can be @@ -192,40 +192,46 @@ def circuit(): ############################################################################## # Block-encoding sparse matrices # ------------------------------ -# The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, requires on the order of -# :math:`~ O(N^{2})` gates to implement. In the case where :math:`A` is a structured sparse matrix, -# we can generate a more efficient quantum circuit representation for the oracle. Let's construct -# the circuit for a sparse matrix that has repeated entries. +# The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, accesses every entry of +# :math:`A` and thus requires on the order of :math:`~ O(N^{2})` gates to implement ([#fable]_). +# In the case where :math:`A` is a structured sparse matrix, we can generate a more efficient quantum +# circuit representation for both oracles. Let's see how we can implment these oracles for a given +# structured sparse matrix. +# +# Consider the s-sparse matrix given by: +# +# .. math:: A = \begin{bmatrix} +# \alpha & \gamma & 0 & \hdots & beta\\ +# \beta & \alpha & \ddots \ddots & 0 \\ +# 0 & \beta & \ddots & \gamma & \vdots\\ +# \vdots & \ddots & \ddots & \alpha & \gamma\\ +# \gamma & 0 & \hdots & \beta & \alpha \\ +# \end{bmatrix} +# +# The following code block prepares the matrix representation for an :math:`8x8` sparse matrix: -s = 4 +s = 4 # normalization constant alpha = 0.1 -gamma = 0.3 + 0.6j -beta = 0.3 - 0.6j - -A = qnp.array([[alpha, gamma, 0, 0, 0, 0, 0, beta], - [beta, alpha, gamma, 0, 0, 0, 0, 0], - [0, beta, alpha, gamma, 0, 0, 0, 0], - [0, 0, beta, alpha, gamma, 0, 0, 0], - [0, 0, 0, beta, alpha, gamma, 0, 0], - [0, 0, 0, 0, beta, alpha, gamma, 0], - [0, 0, 0, 0, 0, beta, alpha, gamma], - [gamma, 0, 0, 0, 0, 0, beta, alpha]]) +beta = 0.6 +gamma = 0.3 + +A = qnp.array([[alpha, gamma, 0, 0, 0, 0, 0, beta], + [ beta, alpha, gamma, 0, 0, 0, 0, 0], + [ 0, beta, alpha, gamma, 0, 0, 0, 0], + [ 0, 0, beta, alpha, gamma, 0, 0, 0], + [ 0, 0, 0, beta, alpha, gamma, 0, 0], + [ 0, 0, 0, 0, beta, alpha, gamma, 0], + [ 0, 0, 0, 0, 0, beta, alpha, gamma], + [gamma, 0, 0, 0, 0, 0, beta, alpha]]) print(f"Original A:\n{A}", "\n") -A2 = qml.math.array(A) / s -evs = qnp.linalg.eigvals(A) -print(evs) -g = qnp.linalg.cond(A) -print(max(qnp.abs(evs)), min(qnp.abs(evs)), g, 1 / min(qnp.abs(evs)), "\n") -evs = qnp.linalg.eigvals(A2) -print(evs) -g = qnp.linalg.cond(A2) -print(max(qnp.abs(evs)), min(qnp.abs(evs)), g, 1 / min(qnp.abs(evs)), "\n") - +############################################################################## +# The :math:`\hat{O}_{C}` oracle for this matrix is defined in terms of the so called "Left" and "Right" +# shift operators ([#sparse]_). -def shift_circ(s_wires, shift="L"): - control_values = [1, 1] if shift == "L" else [0, 0] +def shift_op(s_wires, shift="Left"): + control_values = [1, 1] if shift == "Left" else [0, 0] qml.ctrl(qml.PauliX, control=s_wires[:2], control_values=control_values)(wires=s_wires[2]) qml.ctrl(qml.PauliX, control=s_wires[0], control_values=control_values[0])(wires=s_wires[1]) @@ -233,8 +239,8 @@ def shift_circ(s_wires, shift="L"): def oracle_c(wires_l, wires_j): - qml.ctrl(shift_circ, control=wires_l[0])(wires_j, shift="L") - qml.ctrl(shift_circ, control=wires_l[1])(wires_j, shift="R") + qml.ctrl(shift_op, control=wires_l[0])(wires_j, shift="Left") + qml.ctrl(shift_op, control=wires_l[1])(wires_j, shift="Right") def oracle_a(ancilla, wire_l, wire_j, a, b, g): @@ -242,29 +248,24 @@ def oracle_a(ancilla, wire_l, wire_j, a, b, g): theta_1 = 2 * qnp.arccos(b) theta_2 = 2 * qnp.arccos(g) - # print(theta_0, theta_1, theta_2) - qml.ctrl(qml.RY, control=wire_l, control_values=[0, 0])(theta_0, wires=ancilla) qml.ctrl(qml.RY, control=wire_l, control_values=[1, 0])(theta_1, wires=ancilla) qml.ctrl(qml.RY, control=wire_l, control_values=[0, 1])(theta_2, wires=ancilla) +############################################################################## +# Finally, we can bring the oracles together in our circuit to block encode the sparse matrix: - -dev = qml.device("lightning.qubit", wires=["ancilla", "l1", "l0", "j2", "j1", "j0"]) - +dev = qml.device("default.qubit", wires=["ancilla", "l1", "l0", "j2", "j1", "j0"]) @qml.qnode(dev) def complete_circuit(a, b, g): for w in ["l0", "l1"]: # hadamard transform over |l> register qml.Hadamard(w) - oracle_a("ancilla", ["l0", "l1"], ["j0", "j1", "j2"], a, b, g) - oracle_c(["l0", "l1"], ["j0", "j1", "j2"]) - for w in ["l0", "l1"]: # hadamard transform over |l> register qml.Hadamard(w) return qml.state() From 7fee215bdc7f6d18ec515db6342615cc2c95db57 Mon Sep 17 00:00:00 2001 From: Diego Date: Wed, 4 Oct 2023 17:35:36 -0400 Subject: [PATCH 10/61] add oracle definitions --- demonstrations/tutorial_block_encoding.py | 47 ++++++++--------------- 1 file changed, 16 insertions(+), 31 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 50c2bd4a54..d152869332 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -62,7 +62,7 @@ import pennylane as qml from pennylane.templates.state_preparations.mottonen import compute_theta, gray_code -from pennylnae import numpy as qnp +from pennylane import numpy as qnp n = 2 N = 2**n @@ -90,18 +90,26 @@ for i in range(num_selections) ] -dev = qml.device('default.qubit', wires=5) -@qml.qnode(dev) -def circuit(): - qml.Hadamard(wires=2) - qml.Hadamard(wires=3) +def OA(): for idx in range(len(thetas)): qml.RY(thetas[idx],wires=4) qml.CNOT(wires=[control_wires[idx],4]) + +def OC(): qml.SWAP(wires=[0,2]) qml.SWAP(wires=[1,3]) + +def Ds(): qml.Hadamard(wires=2) qml.Hadamard(wires=3) + +dev = qml.device('default.qubit', wires=5) +@qml.qnode(dev) +def circuit(): + Ds() + OA() + OC() + Ds() return qml.state() print(qml.draw(circuit)()) @@ -134,21 +142,11 @@ def circuit(): tolerance= 0.01 -dev = qml.device('default.qubit', wires=5) - -@qml.qnode(dev) -def circuit(): - qml.Hadamard(wires=2) - qml.Hadamard(wires=3) +def OA(): for idx in range(len(thetas)): if abs(thetas[idx])>tolerance: qml.RY(thetas[idx],wires=4) qml.CNOT(wires=[control_wires[idx],4]) - qml.SWAP(wires=[0,2]) - qml.SWAP(wires=[1,3]) - qml.Hadamard(wires=2) - qml.Hadamard(wires=3) - return qml.state() print(qml.draw(circuit)()) @@ -157,14 +155,7 @@ def circuit(): # cancel each other. Compressing the circuit in this way is an approximation. Let's see how good # this approximation is in the case of our example. -tolerance= 0.01 - -dev = qml.device('default.qubit', wires=5) - -@qml.qnode(dev) -def circuit(): - qml.Hadamard(wires=2) - qml.Hadamard(wires=3) +def OA(): nots=[] for idx in range(len(thetas)): if abs(thetas[idx])>tolerance: @@ -176,13 +167,7 @@ def circuit(): del(nots[nots.index(control_wires[idx])]) else: nots.append(control_wires[idx]) - qml.CNOT(nots+[4]) - qml.SWAP(wires=[0,2]) - qml.SWAP(wires=[1,3]) - qml.Hadamard(wires=2) - qml.Hadamard(wires=3) - return qml.state() print(qml.draw(circuit)()) From faef859f6a415a74f1c8da65731dd402b425c57d Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 18:40:17 -0400 Subject: [PATCH 11/61] edit text --- demonstrations/tutorial_block_encoding.py | 135 ++++++++++++---------- 1 file changed, 75 insertions(+), 60 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index f73b45a5c4..621edd3ccb 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -1,7 +1,7 @@ r""" -Block Encoding -============== +Block encoding with matrix query oracles +======================================== .. meta:: :property="og:description": Learn how to perform block encoding @@ -10,44 +10,46 @@ .. related:: tutorial_intro_qsvt Intro to QSVT -*Author: Diego Guala, Soran Jahangiri, Jay Soni — Posted: September 29, 2023.* +*Author: Diego Guala, Jay Soni, Soran Jahangiri — Posted: September 29, 2023.* Prominent quantum algorithms such as Quantum Phase Estimation and Quantum Singular Value Transformation require implementing a non-unitary operator in a quantum circuit. This is problematic because quantum computers can only perform unitary evolutions. Block encoding is a general technique that solves this problem by embedding the non-unitary operator in a unitary matrix that can be -implemented in a quantum circuit containing a set of ancilla qubits. In this [link] demo, we -learned how to block encode a matrix by simply embedding it in a larger unitary matrix using the -:class:`~pennylane.BlockEncode` operation. We also learned [link] a powerful method for block encoding a +implemented in a quantum circuit using a set of ancilla qubits. In +`this `_ +demo, we learned how to block encode a matrix by simply embedding it in a larger unitary matrix +using the :class:`~pennylane.BlockEncode` operation. We also +`learned `_ a powerful method for block encoding a matrix by decomposing it into a linear combination of unitaries (LCU) and then block encode the LCU. -In this tutorial we explore a general block encoding method that can be efficiently implemented for -sparse and structured matrices. We first explain the method and then apply it to specific examples -that can be efficiently block-encoded. +In this tutorial we explore another general block encoding method that can be particularly +efficient for sparse and structured matrices. We first explain the method and then apply it to +some selected examples. -A general circuit for block encoding ------------------------------------- -An arbitrary matrix :math:`A`, can be block encoded by relying on oracle access to the entries in -the matrix (see [#fable]_, [#sparse]_). A general circuit for block encoding :math:`A` can be -constructed from such oracles as illustrated in the following. +Matrix query oracles +-------------------- +An arbitrary matrix :math:`A`, can be block encoded by relying on oracle access to its entries +(see [#fable]_, [#sparse]_). A general circuit for block encoding :math:`A` can be constructed from +such oracles. .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% :align: center -Finding the optimal sequence of the quantum gates that implement the :math:`\hat{O}_{A}` and -:math:`\hat{O}_{C}` oracles is not straightforward for random matrices. In the general case, -:math:`\hat{O}_{C}` can be represented by a set of SWAP gates and :math:`\hat{O}_{A}` can be -constructed from a sequence of uniformly controlled rotation gates: +Finding the optimal sequence of the quantum gates that implement the :math:`O_A` and :math:`O_C` +oracles is not straightforward for random matrices. In the general case, :math:`O_A` can be +constructed from a sequence of uniformly controlled rotation gates and :math:`O_C` can be +represented by a set of SWAP gates. .. figure:: ../demonstrations/block_encoding/fable_circuit.png :width: 50% :align: center -The rotation angles are computed from the matrix elements of the block encoded matrix as -:math:`\theta = arcsin(a_{ij}`. The gate complexity of this circuit is O(N4) which makes its -implementation highly inefficent. We now explain two approaches that provide alternative -constructions of :math:`\hat{O}_{A}` and :math:`\hat{O}_{C}` that can be very efficient for matrices -with specific sparsity and structure. +The rotation angles are computed from the elements of the block encoded matrix as +:math:`\theta = \text{arccos}(a_{ij}`. The gate complexity of this circuit is :math:`O(N^4)` which +makes its implementation highly inefficient. We now explain two approaches that provide alternative +constructions of :math:`O_A` and :math:`O_C` that can be very efficient specially for matrices with +specific sparsity and structure. Block encoding with FABLE ------------------------- @@ -56,23 +58,35 @@ to compress and sparsify the resulting circuit. For matrices with specific structures, FABLE provides an efficient circuit without sacrificing accuracy. The general circuit is constructed from a set of rotation and C-NOT gates where the rotation angles are obtained from a transformation -of the elements of the block encoded matrix. Let's construct a FABLE circuit for a matrix that is -structured. +of the elements of the block encoded matrix. The rotation angles, +:math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained with + +.. math:: \left ( H^{\otimes 2n} P \right ) \Theta = C, + +where :math:`P` is a permutation that transforms a binary ordering to the Gray code ordering, +:math:`C = (\text{arccos}(A_00), ..., \text{arccos}(A_nn))` is obtained from the matrix elements of +the matrix :math:`A` and :math:`H` is defined as + +.. math:: H = \begin{pmatrix} 1 & 1\\ + 1 & -1 + \end{pmatrix}. + +Let's now construct the block encoding circuit for a structured matrix. """ import pennylane as qml from pennylane.templates.state_preparations.mottonen import compute_theta, gray_code from pennylane import numpy as qnp -n = 2 -N = 2**n - A = qnp.array([[-0.51192128, -0.51192128, 0.6237114 , 0.6237114 ], [ 0.97041007, 0.97041007, 0.99999329, 0.99999329], [ 0.82429855, 0.82429855, 0.98175843, 0.98175843], [ 0.99675093, 0.99675093, 0.83514837, 0.83514837]]) +############################################################################## +# We now normalize the matrix and compute the rotation angles. + Avec = qnp.ravel(A) alpha = max(1,qnp.linalg.norm(Avec,qnp.inf)) Avec = Avec/alpha @@ -82,7 +96,7 @@ thetas = compute_theta(alphas) -code = gray_code(N) +code = gray_code(len(A)) num_selections=len(code) control_wires = control_indices = [ @@ -90,6 +104,10 @@ for i in range(num_selections) ] +############################################################################## +# We construct the :math:`O_A` and :math:`O_C` oracles as well as the Ds operator, which is a tensor +# product of Hadamard gates. + def OA(): for idx in range(len(thetas)): qml.RY(thetas[idx],wires=4) @@ -103,6 +121,9 @@ def Ds(): qml.Hadamard(wires=2) qml.Hadamard(wires=3) +############################################################################## +# We construct the circuit using these oracles and draw it. + dev = qml.device('default.qubit', wires=5) @qml.qnode(dev) def circuit(): @@ -115,29 +136,17 @@ def circuit(): print(qml.draw(circuit)()) ############################################################################## -# The rotation angles, :math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained with -# -# .. math:: \left ( H^{\otimes 2n} P \right ) \Theta = C, -# -# where P is a permutation that transforms a binary ordering to the Gray code ordering, -# :math:`C = (arccos(A_00), ..., arccos(A_nn))` is obtained from the matrix elements of the matrix A -# and H is defined as - -# .. math:: H = \begin{pmatrix} 1 & 1\\ -# 1 & -1 -# \end{pmatrix}. -# -# -# We now compute the matrix representation of the circuit +# We compute the matrix representation of the circuit and print its top-left block to compare it +# with the original matrix print(A) -print(alpha*N*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:N,0:N]) +print(alpha*len(A)*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)]) ############################################################################## -# You can see that the matrix is a block encoding of the original matrix A. +# You can easily confirm that the circuit block encodes the original matrix defined above. # -# The interesting thing about the Fable method is that one can eliminate those rotation gates that -# have an angle smaller than a pre-defined threshold. This leaves a sequence of C-NOT gates that in +# The interesting thing about the FABLE method is that one can eliminate those rotation gates that +# have an angle smaller than a selected threshold. This leaves a sequence of C-NOT gates that in # most cases cancel each other out. tolerance= 0.01 @@ -151,9 +160,9 @@ def OA(): print(qml.draw(circuit)()) ############################################################################## -# You can confirm that two C-NOT gates applied to the same wires -# cancel each other. Compressing the circuit in this way is an approximation. Let's see how good -# this approximation is in the case of our example. +# You can confirm that two C-NOT gates applied to the same wires cancel each other. Compressing the +# circuit in this way is an approximation. Let's see how good this approximation is in the case of +# our example. def OA(): nots=[] @@ -172,25 +181,31 @@ def OA(): print(qml.draw(circuit)()) print(A) -print(alpha*N*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:N,0:N]) +print(alpha*len(A)*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)]) + +############################################################################## +# You can see that the compressed circuit is equivalent to the original circuit simply because our +# matrix is highly structured and many of the rotation angles are zero. This is not the case for any +# given matrix. Can you construct a matrix that also allows a significant compression of the block +# encoding circuit without affecting the accuracy? ############################################################################## # Block-encoding sparse matrices # ------------------------------ # The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, accesses every entry of -# :math:`A` and thus requires on the order of :math:`~ O(N^{2})` gates to implement ([#fable]_). +# :math:`A` and thus requires on the order of :math:`~ O(N^2)` gates to implement ([#fable]_). # In the case where :math:`A` is a structured sparse matrix, we can generate a more efficient quantum -# circuit representation for both oracles. Let's see how we can implment these oracles for a given +# circuit representation for both oracles. Let's see how we can implement these oracles for a given # structured sparse matrix. # # Consider the s-sparse matrix given by: # # .. math:: A = \begin{bmatrix} -# \alpha & \gamma & 0 & \hdots & beta\\ -# \beta & \alpha & \ddots \ddots & 0 \\ -# 0 & \beta & \ddots & \gamma & \vdots\\ -# \vdots & \ddots & \ddots & \alpha & \gamma\\ -# \gamma & 0 & \hdots & \beta & \alpha \\ +# \alpha & \gamma & 0 & \dots & \beta\\ +# \beta & \alpha & \gamma & \ddots & 0 \\ +# 0 & \beta & \alpha & \gamma \ddots & 0\\ +# 0 & \ddots & \beta & \alpha & \gamma\\ +# \gamma & 0 & \dots & \beta & \alpha \\ # \end{bmatrix} # # The following code block prepares the matrix representation for an :math:`8x8` sparse matrix: @@ -297,6 +312,6 @@ def complete_circuit(a, b, g): # ---------------- # .. include:: ../_static/authors/diego_guala.txt # -# .. include:: ../_static/authors/soran_jahangiri.txt -# # .. include:: ../_static/authors/jay_soni.txt +# +# .. include:: ../_static/authors/soran_jahangiri.txt From eb6dcffaf799f423d0a6da57b7e5793a248397a0 Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 18:42:02 -0400 Subject: [PATCH 12/61] edit title --- demonstrations/tutorial_block_encoding.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 621edd3ccb..a8d34e63bc 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -26,8 +26,8 @@ efficient for sparse and structured matrices. We first explain the method and then apply it to some selected examples. -Matrix query oracles --------------------- +Circuits with matrix query oracles +---------------------------------- An arbitrary matrix :math:`A`, can be block encoded by relying on oracle access to its entries (see [#fable]_, [#sparse]_). A general circuit for block encoding :math:`A` can be constructed from such oracles. From 611553441b6e7fc52b71b196f15e168c8edfcb46 Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 19:45:02 -0400 Subject: [PATCH 13/61] add demo to rst --- demonstrations/tutorial_block_encoding.metadata.json | 6 +++--- demos_quantum-computing.rst | 7 +++++++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index 85ee356942..c8625af7a0 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -11,8 +11,8 @@ "id": "diego_guala" } ], - "dateOfPublication": "2019-10-11T00:00:00+00:00", - "dateOfLastModification": "2020-10-26T00:00:00+00:00", + "dateOfPublication": "2023-10-04T00:00:00+00:00", + "dateOfLastModification": "2023-10-04T00:00:00+00:00", "categories": [ "Quantum Computing", "Algorithms" @@ -21,7 +21,7 @@ "previewImages": [ { "type": "thumbnail", - "uri": "/_images/xxx.png" + "uri": "/_images/thumbnail_block_encoding.png" } ], "seoDescription": "Learn about the many different methods to achieve a block-encoding for a given matrix.", diff --git a/demos_quantum-computing.rst b/demos_quantum-computing.rst index c87cb185f8..906583d405 100644 --- a/demos_quantum-computing.rst +++ b/demos_quantum-computing.rst @@ -173,6 +173,12 @@ such as benchmarking and characterizing quantum processors. :figure: demonstrations/apply_qsvt/thumbnail_tutorial_QSVT_for_Matrix_Inversion.png :description: :doc:`demos/tutorial_apply_qsvt` :tags: quantumcomputing qsvt optimization + +.. gallery-item:: + :tooltip: Block Encoding + :figure: demonstrations/block_encoding/fable_circuit.png + :description: :doc:`demos/tutorial_block_encoding` + :tags: quantumcomputing qsvt optimization :html:`

` @@ -205,5 +211,6 @@ such as benchmarking and characterizing quantum processors. demos/tutorial_intro_qsvt demos/tutorial_grovers_algorithm demos/tutorial_apply_qsvt + demos/tutorial_block_encoding From 636489392fe144584e56d060b993c0505f4f884f Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 20:56:32 -0400 Subject: [PATCH 14/61] add thumbnail image --- demonstrations/thumbnail_block_encoding.png | Bin 0 -> 19246 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 demonstrations/thumbnail_block_encoding.png diff --git a/demonstrations/thumbnail_block_encoding.png b/demonstrations/thumbnail_block_encoding.png new file mode 100644 index 0000000000000000000000000000000000000000..842f12b6aad63a49749dea4fbc1ce1693d1909f4 GIT binary patch literal 19246 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
*0& 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 PzaS^AD3u|3 Date: Wed, 4 Oct 2023 21:41:19 -0400 Subject: [PATCH 15/61] add thumbnail image --- .../thumbnail_block_encoding.png | Bin 1 file changed, 0 insertions(+), 0 deletions(-) rename demonstrations/{ => block_encoding}/thumbnail_block_encoding.png (100%) diff --git a/demonstrations/thumbnail_block_encoding.png b/demonstrations/block_encoding/thumbnail_block_encoding.png similarity index 100% rename from demonstrations/thumbnail_block_encoding.png rename to demonstrations/block_encoding/thumbnail_block_encoding.png From 6222b9f3d4eba106b566e7d88a470160cc22153f Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 22:34:41 -0400 Subject: [PATCH 16/61] add thumbnail image --- demonstrations/tutorial_block_encoding.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index a8d34e63bc..7308487262 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -5,7 +5,7 @@ .. meta:: :property="og:description": Learn how to perform block encoding - :property="og:image": https://pennylane.ai/qml/_images/thumbnail_block_encoding.png + :property="og:image": https://pennylane.ai/qml/_images/thumbnail_intro_qsvt.png .. related:: tutorial_intro_qsvt Intro to QSVT From c648b79697faa35ac49275bbac1549915251e3e6 Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 4 Oct 2023 23:30:13 -0400 Subject: [PATCH 17/61] add thumbnail image --- demonstrations/tutorial_block_encoding.metadata.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index c8625af7a0..f76271821a 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -21,7 +21,7 @@ "previewImages": [ { "type": "thumbnail", - "uri": "/_images/thumbnail_block_encoding.png" + "uri": "/_images/thumbnail_intro_qsvt.png" } ], "seoDescription": "Learn about the many different methods to achieve a block-encoding for a given matrix.", From 0a3a05a557fb306574373565a5801b8ba2afac70 Mon Sep 17 00:00:00 2001 From: soranjh Date: Mon, 23 Oct 2023 16:12:59 -0400 Subject: [PATCH 18/61] modify text --- .../tutorial_block_encoding.metadata.json | 2 +- demonstrations/tutorial_block_encoding.py | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index f76271821a..a3bb8c9fd3 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -56,4 +56,4 @@ "weight": 1.0 } ] -} \ No newline at end of file +} diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 7308487262..12fe14af1e 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -12,23 +12,23 @@ *Author: Diego Guala, Jay Soni, Soran Jahangiri — Posted: September 29, 2023.* -Prominent quantum algorithms such as Quantum Phase Estimation and Quantum Singular Value -Transformation require implementing a non-unitary operator in a quantum circuit. This is problematic +Prominent quantum algorithms such as quantum phase estimation and quantum singular value +transformation algorithms require encoding a non-unitary matrix in a quantum circuit. This is problematic because quantum computers can only perform unitary evolutions. Block encoding is a general technique that solves this problem by embedding the non-unitary operator in a unitary matrix that can be -implemented in a quantum circuit using a set of ancilla qubits. In +implemented in a quantum circuit. In `this `_ -demo, we learned how to block encode a matrix by simply embedding it in a larger unitary matrix +demo, we learned how to block encode a non-unitary matrix by simply embedding it in a larger unitary matrix using the :class:`~pennylane.BlockEncode` operation. We also `learned `_ a powerful method for block encoding a matrix by decomposing it into a linear combination of unitaries (LCU) and then block encode the LCU. -In this tutorial we explore another general block encoding method that can be particularly +In this tutorial we explore another general block encoding method that can be very efficient for sparse and structured matrices. We first explain the method and then apply it to -some selected examples. +some examples. Circuits with matrix query oracles ---------------------------------- -An arbitrary matrix :math:`A`, can be block encoded by relying on oracle access to its entries +An arbitrary matrix :math:`A`, can be block-encoded by relying on oracle access to its entries (see [#fable]_, [#sparse]_). A general circuit for block encoding :math:`A` can be constructed from such oracles. From 5053a2fa39cd5fdf16e1f1493f03c02131ea4522 Mon Sep 17 00:00:00 2001 From: soranjh Date: Thu, 26 Oct 2023 21:48:03 -0400 Subject: [PATCH 19/61] modify text --- demonstrations/tutorial_block_encoding.py | 66 +++++++++++------------ 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 12fe14af1e..2f249cabdf 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -1,7 +1,7 @@ r""" -Block encoding with matrix query oracles -======================================== +Block encoding with matrix access oracles +========================================= .. meta:: :property="og:description": Learn how to perform block encoding @@ -13,53 +13,50 @@ *Author: Diego Guala, Jay Soni, Soran Jahangiri — Posted: September 29, 2023.* Prominent quantum algorithms such as quantum phase estimation and quantum singular value -transformation algorithms require encoding a non-unitary matrix in a quantum circuit. This is problematic -because quantum computers can only perform unitary evolutions. Block encoding is a general technique -that solves this problem by embedding the non-unitary operator in a unitary matrix that can be -implemented in a quantum circuit. In +transformation algorithms require encoding a non-unitary matrix in a quantum circuit. This requires +using sophisticated methods because quantum computers can only perform unitary evolutions. Block +encoding is a general technique that solves this problem by embedding a non-unitary operator in a +unitary matrix that can be implemented in a quantum circuit. In `this `_ -demo, we learned how to block encode a non-unitary matrix by simply embedding it in a larger unitary matrix -using the :class:`~pennylane.BlockEncode` operation. We also +demo, we learned how to block encode a non-unitary matrix by simply embedding it in a larger unitary +matrix using the :class:`~pennylane.BlockEncode` operation. We also `learned `_ a powerful method for block encoding a matrix by decomposing it into a linear combination of unitaries (LCU) and then block encode the LCU. -In this tutorial we explore another general block encoding method that can be very -efficient for sparse and structured matrices. We first explain the method and then apply it to -some examples. +In this tutorial we explore another general block encoding method that can be very efficient for +sparse and structured matrices. We first explain the method and then apply it to some examples. -Circuits with matrix query oracles ----------------------------------- -An arbitrary matrix :math:`A`, can be block-encoded by relying on oracle access to its entries -(see [#fable]_, [#sparse]_). A general circuit for block encoding :math:`A` can be constructed from -such oracles. +Circuits with matrix access oracles +----------------------------------- +A general circuit for block encoding an arbitrary matrix :math:`A` can be constructed as shown in +the figure below. .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% :align: center -Finding the optimal sequence of the quantum gates that implement the :math:`O_A` and :math:`O_C` -oracles is not straightforward for random matrices. In the general case, :math:`O_A` can be -constructed from a sequence of uniformly controlled rotation gates and :math:`O_C` can be -represented by a set of SWAP gates. +The :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The +:math:`U_A` and :math:`U_A` operations, in the most general case, can be constructed from a sequence +of uniformly controlled rotation gates and a set of SWAP gates, respectively. The rotation angles +are computed from the elements of the block encoded matrix as :math:`\theta = \text{arccos}(a_{ij}`. +The gate complexity of this circuit is :math:`O(N^4)` which makes its implementation highly +inefficient. -.. figure:: ../demonstrations/block_encoding/fable_circuit.png - :width: 50% - :align: center - -The rotation angles are computed from the elements of the block encoded matrix as -:math:`\theta = \text{arccos}(a_{ij}`. The gate complexity of this circuit is :math:`O(N^4)` which -makes its implementation highly inefficient. We now explain two approaches that provide alternative -constructions of :math:`O_A` and :math:`O_C` that can be very efficient specially for matrices with -specific sparsity and structure. +Finding the optimal sequence of the quantum gates that implement :math:`U_A` and +:math:`U_B` is not always straightforward. We now explain two approaches for the construction of +these oracles that can be very efficient specially for matrices with specific sparsity and +structure. Block encoding with FABLE ------------------------- The fast approximate quantum circuits for block encodings (FABLE) is a general method for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted to compress and sparsify the resulting circuit. For matrices with specific structures, FABLE -provides an efficient circuit without sacrificing accuracy. The general circuit is constructed -from a set of rotation and C-NOT gates where the rotation angles are obtained from a transformation -of the elements of the block encoded matrix. The rotation angles, -:math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained with +provides an efficient circuit without reducing accuracy. The general circuit is constructed +from a set of rotation and C-NOT gates. + + +The rotation angles are obtained from a transformation of the elements of the block encoded matrix. +The rotation angles, :math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained with .. math:: \left ( H^{\otimes 2n} P \right ) \Theta = C, @@ -192,6 +189,9 @@ def OA(): ############################################################################## # Block-encoding sparse matrices # ------------------------------ +# In the special case where :math:`A` is sparse, these oracles can +# be designed +# based on the structure and sparsity of the matrix. # The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, accesses every entry of # :math:`A` and thus requires on the order of :math:`~ O(N^2)` gates to implement ([#fable]_). # In the case where :math:`A` is a structured sparse matrix, we can generate a more efficient quantum From e017d983d36417757d3318141373cd54b9b7f268 Mon Sep 17 00:00:00 2001 From: soranjh Date: Fri, 27 Oct 2023 13:59:01 -0400 Subject: [PATCH 20/61] modify text and code --- demonstrations/tutorial_block_encoding.py | 162 ++++++++++------------ 1 file changed, 76 insertions(+), 86 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 2f249cabdf..4f8ded5c57 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -50,13 +50,12 @@ ------------------------- The fast approximate quantum circuits for block encodings (FABLE) is a general method for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted -to compress and sparsify the resulting circuit. For matrices with specific structures, FABLE -provides an efficient circuit without reducing accuracy. The general circuit is constructed -from a set of rotation and C-NOT gates. +to simplify the resulting circuit. For matrices with specific structures, FABLE provides an +efficient circuit without reducing accuracy. - -The rotation angles are obtained from a transformation of the elements of the block encoded matrix. -The rotation angles, :math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained with +The FABLE circuit is constructed from a set of rotation and C-NOT gates. The rotation angles, +:math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements of +the block encoded matrix .. math:: \left ( H^{\otimes 2n} P \right ) \Theta = C, @@ -68,53 +67,46 @@ 1 & -1 \end{pmatrix}. -Let's now construct the block encoding circuit for a structured matrix. +Let's now construct the FABLE block encoding circuit for a structured matrix. """ import pennylane as qml from pennylane.templates.state_preparations.mottonen import compute_theta, gray_code -from pennylane import numpy as qnp - -A = qnp.array([[-0.51192128, -0.51192128, 0.6237114 , 0.6237114 ], - [ 0.97041007, 0.97041007, 0.99999329, 0.99999329], - [ 0.82429855, 0.82429855, 0.98175843, 0.98175843], - [ 0.99675093, 0.99675093, 0.83514837, 0.83514837]]) +from pennylane import numpy as np +A = np.array([[-0.51192128, -0.51192128, 0.6237114 , 0.6237114 ], + [ 0.97041007, 0.97041007, 0.99999329, 0.99999329], + [ 0.82429855, 0.82429855, 0.98175843, 0.98175843], + [ 0.99675093, 0.99675093, 0.83514837, 0.83514837]]) ############################################################################## -# We now normalize the matrix and compute the rotation angles. - -Avec = qnp.ravel(A) -alpha = max(1,qnp.linalg.norm(Avec,qnp.inf)) -Avec = Avec/alpha - +# We now compute the rotation angles and obtain the control wires for the C-NOT gates. -alphas = 2*qnp.arccos(Avec) +alphas = 2 * np.arccos(A).flatten() thetas = compute_theta(alphas) - code = gray_code(len(A)) -num_selections=len(code) +n_selections = len(code) -control_wires = control_indices = [ - int(qnp.log2(int(code[i], 2) ^ int(code[(i + 1) % num_selections], 2))) - for i in range(num_selections) +control_wires = [ + int(np.log2(int(code[i], 2) ^ int(code[(i + 1) % n_selections], 2))) + for i in range(n_selections) ] ############################################################################## -# We construct the :math:`O_A` and :math:`O_C` oracles as well as the Ds operator, which is a tensor -# product of Hadamard gates. +# We construct the :math:`U_A` and :math:`U_B` oracles as well as an operator representing the +# tensor product of Hadamard gates. -def OA(): +def UA(): for idx in range(len(thetas)): qml.RY(thetas[idx],wires=4) qml.CNOT(wires=[control_wires[idx],4]) -def OC(): +def UB(): qml.SWAP(wires=[0,2]) qml.SWAP(wires=[1,3]) -def Ds(): +def HN(): qml.Hadamard(wires=2) qml.Hadamard(wires=3) @@ -124,31 +116,33 @@ def Ds(): dev = qml.device('default.qubit', wires=5) @qml.qnode(dev) def circuit(): - Ds() - OA() - OC() - Ds() + HN() + UA() + UB() + HN() return qml.state() print(qml.draw(circuit)()) ############################################################################## # We compute the matrix representation of the circuit and print its top-left block to compare it -# with the original matrix +# with the original matrix. print(A) -print(alpha*len(A)*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)]) +print(len(A) * qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)]) ############################################################################## # You can easily confirm that the circuit block encodes the original matrix defined above. # -# The interesting thing about the FABLE method is that one can eliminate those rotation gates that -# have an angle smaller than a selected threshold. This leaves a sequence of C-NOT gates that in -# most cases cancel each other out. +# The interesting point about the FABLE method is that we can eliminate those rotation gates that +# have an angle smaller than a defined threshold. This leaves a sequence of C-NOT gates that in +# most cases cancel each other out. You can confirm that two C-NOT gates applied to the same wires +# cancel each other. Let's now remove all the rotation gates that have an angle smaller than +# :math:`0.01` and draw the circuit. tolerance= 0.01 -def OA(): +def UA(): for idx in range(len(thetas)): if abs(thetas[idx])>tolerance: qml.RY(thetas[idx],wires=4) @@ -157,14 +151,13 @@ def OA(): print(qml.draw(circuit)()) ############################################################################## -# You can confirm that two C-NOT gates applied to the same wires cancel each other. Compressing the -# circuit in this way is an approximation. Let's see how good this approximation is in the case of -# our example. +# Compressing the circuit by removing some of the rotations is an approximation. We can now see how +# good this approximation is in the case of our example. -def OA(): +def UA(): nots=[] for idx in range(len(thetas)): - if abs(thetas[idx])>tolerance: + if abs(thetas[idx]) > tolerance: for cidx in nots: qml.CNOT(wires=[cidx,4]) qml.RY(thetas[idx],wires=4) @@ -178,27 +171,22 @@ def OA(): print(qml.draw(circuit)()) print(A) -print(alpha*len(A)*qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)]) - -############################################################################## -# You can see that the compressed circuit is equivalent to the original circuit simply because our -# matrix is highly structured and many of the rotation angles are zero. This is not the case for any -# given matrix. Can you construct a matrix that also allows a significant compression of the block -# encoding circuit without affecting the accuracy? +print(len(A) * qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)]) ############################################################################## +# You can see that the compressed circuit is equivalent to the original circuit. This happens +# because our original matrix is highly structured and many of the rotation angles are zero. +# However, this is not always true for an arbitrary matrix. Can you construct another matrix that +# allows a significant compression of the block encoding circuit without affecting the accuracy? +# # Block-encoding sparse matrices # ------------------------------ -# In the special case where :math:`A` is sparse, these oracles can -# be designed -# based on the structure and sparsity of the matrix. -# The quantum circuit for the oracle :math:`\hat{O}_{A}`, presented above, accesses every entry of -# :math:`A` and thus requires on the order of :math:`~ O(N^2)` gates to implement ([#fable]_). -# In the case where :math:`A` is a structured sparse matrix, we can generate a more efficient quantum -# circuit representation for both oracles. Let's see how we can implement these oracles for a given -# structured sparse matrix. +# The quantum circuit for the oracle :math:`U_A`, presented above, accesses every entry of +# :math:`A` and thus requires :math:`~ O(N^2)` gates to implement the oracle ([#fable]_). In the +# special cases where :math:`A` is structured and sparse, we can generate a more efficient quantum +# circuit representation for :math:`U_A` and :math:`U_B`. Let's look at an example. # -# Consider the s-sparse matrix given by: +# Consider the sparse matrix given by: # # .. math:: A = \begin{bmatrix} # \alpha & \gamma & 0 & \dots & \beta\\ @@ -206,28 +194,27 @@ def OA(): # 0 & \beta & \alpha & \gamma \ddots & 0\\ # 0 & \ddots & \beta & \alpha & \gamma\\ # \gamma & 0 & \dots & \beta & \alpha \\ -# \end{bmatrix} +# \end{bmatrix}, # -# The following code block prepares the matrix representation for an :math:`8x8` sparse matrix: +# where :math:`alpha`, :math:`beta` and :math:`gamma` are real numbers. The following code block +# prepares the matrix representation of :math:`A` for an :math:`8 x 8` sparse matrix. s = 4 # normalization constant -alpha = 0.1 -beta = 0.6 -gamma = 0.3 - -A = qnp.array([[alpha, gamma, 0, 0, 0, 0, 0, beta], - [ beta, alpha, gamma, 0, 0, 0, 0, 0], - [ 0, beta, alpha, gamma, 0, 0, 0, 0], - [ 0, 0, beta, alpha, gamma, 0, 0, 0], - [ 0, 0, 0, beta, alpha, gamma, 0, 0], - [ 0, 0, 0, 0, beta, alpha, gamma, 0], - [ 0, 0, 0, 0, 0, beta, alpha, gamma], - [gamma, 0, 0, 0, 0, 0, beta, alpha]]) +alpha, beta, gamma = 0.1, 0.6, 0.3 + +A = np.array([[alpha, gamma, 0, 0, 0, 0, 0, beta], + [ beta, alpha, gamma, 0, 0, 0, 0, 0], + [ 0, beta, alpha, gamma, 0, 0, 0, 0], + [ 0, 0, beta, alpha, gamma, 0, 0, 0], + [ 0, 0, 0, beta, alpha, gamma, 0, 0], + [ 0, 0, 0, 0, beta, alpha, gamma, 0], + [ 0, 0, 0, 0, 0, beta, alpha, gamma], + [gamma, 0, 0, 0, 0, 0, beta, alpha]]) print(f"Original A:\n{A}", "\n") ############################################################################## -# The :math:`\hat{O}_{C}` oracle for this matrix is defined in terms of the so called "Left" and "Right" +# The :math:`U_B` oracle for this matrix is defined in terms of the so-called "Left" and "Right" # shift operators ([#sparse]_). def shift_op(s_wires, shift="Left"): @@ -238,22 +225,22 @@ def shift_op(s_wires, shift="Left"): qml.PauliX(s_wires[0]) -def oracle_c(wires_l, wires_j): +def UB(wires_l, wires_j): qml.ctrl(shift_op, control=wires_l[0])(wires_j, shift="Left") qml.ctrl(shift_op, control=wires_l[1])(wires_j, shift="Right") -def oracle_a(ancilla, wire_l, wire_j, a, b, g): - theta_0 = 2 * qnp.arccos(a - 1) - theta_1 = 2 * qnp.arccos(b) - theta_2 = 2 * qnp.arccos(g) +def UA(ancilla, wire_l, wire_j, a, b, g): + theta_0 = 2 * np.arccos(a - 1) + theta_1 = 2 * np.arccos(b) + theta_2 = 2 * np.arccos(g) qml.ctrl(qml.RY, control=wire_l, control_values=[0, 0])(theta_0, wires=ancilla) qml.ctrl(qml.RY, control=wire_l, control_values=[1, 0])(theta_1, wires=ancilla) qml.ctrl(qml.RY, control=wire_l, control_values=[0, 1])(theta_2, wires=ancilla) ############################################################################## -# Finally, we can bring the oracles together in our circuit to block encode the sparse matrix: +# We construct our circuit to block encode the sparse matrix. dev = qml.device("default.qubit", wires=["ancilla", "l1", "l0", "j2", "j1", "j0"]) @@ -262,12 +249,13 @@ def complete_circuit(a, b, g): for w in ["l0", "l1"]: # hadamard transform over |l> register qml.Hadamard(w) - oracle_a("ancilla", ["l0", "l1"], ["j0", "j1", "j2"], a, b, g) + UA("ancilla", ["l0", "l1"], ["j0", "j1", "j2"], a, b, g) - oracle_c(["l0", "l1"], ["j0", "j1", "j2"]) + UB(["l0", "l1"], ["j0", "j1", "j2"]) for w in ["l0", "l1"]: # hadamard transform over |l> register qml.Hadamard(w) + return qml.state() @@ -279,6 +267,8 @@ def complete_circuit(a, b, g): print(mat, "\n") ############################################################################## +# You can confirm that the circuit block encodes the original sparse matrix defined above. +# # Summary and conclusions # ----------------------- # Block encoding is a powerful technique in quantum computing that allows implementing a non-unitary @@ -310,8 +300,8 @@ def complete_circuit(a, b, g): ############################################################################## # About the author # ---------------- -# .. include:: ../_static/authors/diego_guala.txt -# # .. include:: ../_static/authors/jay_soni.txt # +# .. include:: ../_static/authors/diego_guala.txt +# # .. include:: ../_static/authors/soran_jahangiri.txt From 11f0e4c4448c9ff3ae7bc5ccc19ef4fdbd475b17 Mon Sep 17 00:00:00 2001 From: soranjh Date: Fri, 27 Oct 2023 15:45:56 -0400 Subject: [PATCH 21/61] clean up code --- .../block_encoding/general_circuit.png | Bin 19246 -> 11721 bytes demonstrations/tutorial_block_encoding.py | 48 +++++++++--------- 2 files changed, 23 insertions(+), 25 deletions(-) diff --git a/demonstrations/block_encoding/general_circuit.png b/demonstrations/block_encoding/general_circuit.png index 842f12b6aad63a49749dea4fbc1ce1693d1909f4..73720a75a643c7521df1fe1751e08e31559af19e 100644 GIT binary patch literal 11721 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 literal 19246 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
*0& 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 PzaS^AD3u|3 register qml.Hadamard(w) - UA("ancilla", ["l0", "l1"], ["j0", "j1", "j2"], a, b, g) + UA("ancilla", ["l0", "l1"], theta) UB(["l0", "l1"], ["j0", "j1", "j2"]) @@ -258,12 +255,13 @@ def complete_circuit(a, b, g): return qml.state() +theta = 2 * np.arccos(np.array([alpha - 1, beta, gamma])) print("Quantum Circuit:") -print(qml.draw(complete_circuit)(alpha, beta, gamma), "\n") +print(qml.draw(complete_circuit)(theta), "\n") print("BlockEncoded Mat:") -mat = qml.matrix(complete_circuit)(alpha, beta, gamma)[:8, :8] * s +mat = qml.matrix(complete_circuit)(theta).real[:8, :8] * s print(mat, "\n") ############################################################################## @@ -273,11 +271,11 @@ def complete_circuit(a, b, g): # ----------------------- # Block encoding is a powerful technique in quantum computing that allows implementing a non-unitary # operation in a quantum circuit typically by embedding the operation in a larger unitary operation. -# Here we reviewed some important block encoding methods with code examples using PennyLane. The -# efficiency of the block encoding scheme depends on the sparsity and structure of the matrix we -# want to block encode. The block encoding functionality provided in PennyLane allows you to explore -# and benchmark different approaches for a desired problem. Can you select a matrix and compare -# different block encoding methods for it? +# In this demo, we reviewed two important block encoding methods with code examples using PennyLane. +# The block encoding functionality provided in PennyLane allows you to explore and benchmark several +# block encoding approaches for a desired problem. The efficiency of the block encoding methods +# typically depends on the sparsity and structure of the original matrix. Can you select a matrix +# and find which block encoding method is the most efficient one for your matrix? # # References # ---------- From d27315e715b5ddb858654d9a41c27b2e3b39d8b3 Mon Sep 17 00:00:00 2001 From: soranjh Date: Fri, 27 Oct 2023 16:48:09 -0400 Subject: [PATCH 22/61] correct code --- demonstrations/tutorial_block_encoding.py | 1 + 1 file changed, 1 insertion(+) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 84e42081cb..3fdecd3086 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -255,6 +255,7 @@ def complete_circuit(theta): return qml.state() +s = 4 # normalization constant theta = 2 * np.arccos(np.array([alpha - 1, beta, gamma])) print("Quantum Circuit:") From e11383634b26d4adbfcef84df358ab991a1894b5 Mon Sep 17 00:00:00 2001 From: soranjh Date: Mon, 30 Oct 2023 14:14:53 -0400 Subject: [PATCH 23/61] modify print --- demonstrations/tutorial_block_encoding.py | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 3fdecd3086..8e453af4d5 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -37,7 +37,7 @@ The :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The :math:`U_A` and :math:`U_A` operations, in the most general case, can be constructed from a sequence of uniformly controlled rotation gates and a set of SWAP gates, respectively. The rotation angles -are computed from the elements of the block encoded matrix as :math:`\theta = \text{arccos}(a_{ij}`. +are computed from the elements of the block encoded matrix as :math:`\theta = \text{arccos}(a_{ij})`. The gate complexity of this circuit is :math:`O(N^4)` which makes its implementation highly inefficient. @@ -60,8 +60,8 @@ .. math:: \left ( H^{\otimes 2n} P \right ) \Theta = C, where :math:`P` is a permutation that transforms a binary ordering to the Gray code ordering, -:math:`C = (\text{arccos}(A_00), ..., \text{arccos}(A_nn))` is obtained from the matrix elements of -the matrix :math:`A` and :math:`H` is defined as +:math:`C = (\text{arccos}(A_{00}), ..., \text{arccos}(A_{nn}))` is obtained from the matrix elements +of the matrix :math:`A`, and :math:`H` is defined as .. math:: H = \begin{pmatrix} 1 & 1\\ 1 & -1 @@ -128,8 +128,9 @@ def circuit(): # We compute the matrix representation of the circuit and print its top-left block to compare it # with the original matrix. -print(A) -print(len(A) * qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)]) +print(f"Original matrix:\n{A}", "\n") +M = len(A) * qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)] +print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## # You can easily confirm that the circuit block encodes the original matrix defined above. @@ -170,8 +171,9 @@ def UA(): print(qml.draw(circuit)()) -print(A) -print(len(A) * qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)]) +print(f"Original matrix:\n{A}", "\n") +M = len(A) * qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)] +print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## # You can see that the compressed circuit is equivalent to the original circuit. This happens @@ -196,8 +198,8 @@ def UA(): # \gamma & 0 & \dots & \beta & \alpha \\ # \end{bmatrix}, # -# where :math:`alpha`, :math:`beta` and :math:`gamma` are real numbers. The following code block -# prepares the matrix representation of :math:`A` for an :math:`8 x 8` sparse matrix. +# where :math:`\alpha`, :math:`\beta` and :math:`\gamma` are real numbers. The following code block +# prepares the matrix representation of :math:`A` for an :math:`8 \times 8` sparse matrix. alpha, beta, gamma = 0.1, 0.6, 0.3 From a4fdd0f173897ebe9b6dae558045c4a8d3a46495 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 2 Nov 2023 16:47:01 -0400 Subject: [PATCH 24/61] Added more theory --- demonstrations/tutorial_block_encoding.py | 62 +++++++++++++---------- 1 file changed, 35 insertions(+), 27 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 8e453af4d5..6bb1c5d405 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -13,42 +13,50 @@ *Author: Jay Soni, Diego Guala, Soran Jahangiri — Posted: September 29, 2023.* Prominent quantum algorithms such as quantum phase estimation and quantum singular value -transformation algorithms require encoding a non-unitary matrix in a quantum circuit. This requires -using sophisticated methods because quantum computers can only perform unitary evolutions. Block -encoding is a general technique that solves this problem by embedding a non-unitary operator in a -unitary matrix that can be implemented in a quantum circuit. In -`this `_ -demo, we learned how to block encode a non-unitary matrix by simply embedding it in a larger unitary -matrix using the :class:`~pennylane.BlockEncode` operation. We also -`learned `_ a powerful method for block encoding a -matrix by decomposing it into a linear combination of unitaries (LCU) and then block encode the LCU. -In this tutorial we explore another general block encoding method that can be very efficient for -sparse and structured matrices. We first explain the method and then apply it to some examples. +transform require encoding a non-unitary matrix in a quantum circuit. This seems problematic +because quantum computers can only perform unitary evolutions. Block encoding is a technique +that solves this problem by embedding a non-unitary operator as a sub-block of a larger unitary +matrix. + +In previous demos we have discussed methods for `simulator-friendly `_ +encodings and block encodings using `linear combination of unitaries (LCU) decompositions `_. +In this tutorial we explore another general block encoding method that can be very efficient for +sparse and structured matrices. Circuits with matrix access oracles ----------------------------------- -A general circuit for block encoding an arbitrary matrix :math:`A` can be constructed as shown in -the figure below. +A general circuit for block encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N x N}` with :math:`N = 2^{n}` +can be constructed as shown in the figure below. .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% :align: center -The :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The -:math:`U_A` and :math:`U_A` operations, in the most general case, can be constructed from a sequence -of uniformly controlled rotation gates and a set of SWAP gates, respectively. The rotation angles -are computed from the elements of the block encoded matrix as :math:`\theta = \text{arccos}(a_{ij})`. -The gate complexity of this circuit is :math:`O(N^4)` which makes its implementation highly -inefficient. +Where the :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The +:math:`U_A` and :math:`U_B` operations are oracles which give us access to the elements of +the matrix we wish to block encode. The specific action of the oracles are defined below: + +.. math:: U_A |i\rangle |j\rangle \ = ( A_{i, b(i,j)}|0\rangle + \sqrt{1 - |A_{i, b(i,j)}|^2}|1\rangle ) |i\rangle |j\rangle + +:math:`U_A`, in the most general case, can be constructed from a sequence of uniformly +controlled rotation gates. The rotation angles are computed from the elements of the block encoded +matrix as :math:`\theta = \text{arccos}(a_{ij})`. The gate complexity of this circuit is :math:`O(N^4)` +which makes its implementation highly inefficient. + +Let :math:`b(i,j)` be a function such that it takes a column index (:math:`j`) and returns the +row index for the :math:`i^{th}` non-zero entry in that column of :math:`A`. Note, if :math:`A` +is treated as completely dense (no non-zero entries), this function simply returns :math:`i`. +We use this to define the oracle :math:`U_B`: + +.. math:: U_B \cdot |i\rangle|j\rangle \ = \ |i\rangle |b(i,j)\rangle -Finding the optimal sequence of the quantum gates that implement :math:`U_A` and -:math:`U_B` is not always straightforward. We now explain two approaches for the construction of -these oracles that can be very efficient specially for matrices with specific sparsity and -structure. +Finding an optimal quantum gates decomposition that implements :math:`U_A` and +:math:`U_B` is not always possible. We now explore two approaches for the construction of +these oracles that can be very efficient for matrices with specific sparsity and structure. Block encoding with FABLE ------------------------- -The fast approximate quantum circuits for block encodings (FABLE) is a general method +The "Fast Approximate quantum circuits for BLock Encodings" (FABLE) technique is a general method for block encoding dense and sparse matrices. The level of approximation in FABLE can be adjusted to simplify the resulting circuit. For matrices with specific structures, FABLE provides an efficient circuit without reducing accuracy. @@ -285,9 +293,9 @@ def complete_circuit(theta): # # .. [#fable] # -# Daan Camps, Roel Van Beeumen, -# "FABLE: fast approximate quantum circuits for block-encodings", -# `arXiv:2205.00081 `__, 2022 +# Daan Camps, Roel Van Beeumen, +# "FABLE: fast approximate quantum circuits for block-encodings", +# `arXiv:2205.00081 `__, 2022 # # # .. [#sparse] From 05ef7a8ef006dc7929c06a1bd4503fd612fd1fd8 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 2 Nov 2023 16:54:35 -0400 Subject: [PATCH 25/61] re-word conclusion --- demonstrations/tutorial_block_encoding.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 6bb1c5d405..cd654c61b4 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -280,13 +280,13 @@ def complete_circuit(theta): # # Summary and conclusions # ----------------------- -# Block encoding is a powerful technique in quantum computing that allows implementing a non-unitary -# operation in a quantum circuit typically by embedding the operation in a larger unitary operation. +# Block encoding is a powerful technique in quantum computing that allows us to implement a non-unitary +# operation in a quantum circuit by embedding the operation in a larger unitary gate. # In this demo, we reviewed two important block encoding methods with code examples using PennyLane. # The block encoding functionality provided in PennyLane allows you to explore and benchmark several # block encoding approaches for a desired problem. The efficiency of the block encoding methods -# typically depends on the sparsity and structure of the original matrix. Can you select a matrix -# and find which block encoding method is the most efficient one for your matrix? +# typically depends on the sparsity and structure of the original matrix. We hope that you can use +# these tips and tricks to find a more efficient block encoding your matrix! # # References # ---------- From c291518b197d4aeda6f7e85004f71e526550823d Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Mon, 6 Nov 2023 18:09:47 -0500 Subject: [PATCH 26/61] Apply suggestions from code review Co-authored-by: Guillermo Alonso-Linaje <65235481+KetpuntoG@users.noreply.github.com> --- demonstrations/tutorial_block_encoding.py | 32 +++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index cd654c61b4..a124f3cf6f 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -226,14 +226,14 @@ def UA(): # The :math:`U_A` oracle for this matrix is constructed from controlled rotation gates, similar to # the FABLE circuit. -def UA(ancilla, wire_l, theta): - qml.ctrl(qml.RY, control=wire_l, control_values=[0, 0])(theta[0], wires=ancilla) - qml.ctrl(qml.RY, control=wire_l, control_values=[1, 0])(theta[1], wires=ancilla) - qml.ctrl(qml.RY, control=wire_l, control_values=[0, 1])(theta[2], wires=ancilla) +def UA(ancilla, wire_i, theta): + qml.ctrl(qml.RY, control=wire_i, control_values=[0, 0])(theta[0], wires=ancilla) + qml.ctrl(qml.RY, control=wire_i, control_values=[1, 0])(theta[1], wires=ancilla) + qml.ctrl(qml.RY, control=wire_i, control_values=[0, 1])(theta[2], wires=ancilla) ############################################################################## -# The :math:`U_B` oracle is defined in terms of the so-called "Left" and "Right" shift operators -# ([#sparse]_). +# The :math:`U_B` oracle is defined in terms of the so-called "Left" and "Right" shift operators. +# They correspond to the modular arithmetic operations :math:`+1` or :math:`-1` respectively ([#sparse]_). def shift_op(s_wires, shift="Left"): control_values = [1, 1] if shift == "Left" else [0, 0] @@ -242,25 +242,25 @@ def shift_op(s_wires, shift="Left"): qml.PauliX(s_wires[0]) -def UB(wires_l, wires_j): - qml.ctrl(shift_op, control=wires_l[0])(wires_j, shift="Left") - qml.ctrl(shift_op, control=wires_l[1])(wires_j, shift="Right") +def UB(wires_i, wires_j): + qml.ctrl(shift_op, control=wires_i[0])(wires_j, shift="Left") + qml.ctrl(shift_op, control=wires_i[1])(wires_j, shift="Right") ############################################################################## # We now construct our circuit to block encode the sparse matrix. -dev = qml.device("default.qubit", wires=["ancilla", "l1", "l0", "j2", "j1", "j0"]) +dev = qml.device("default.qubit", wires=["ancilla", "i1", "i0", "j2", "j1", "j0"]) @qml.qnode(dev) def complete_circuit(theta): - for w in ["l0", "l1"]: # hadamard transform over |l> register + for w in ["i0", "i1"]: # hadamard transform over |i> register qml.Hadamard(w) - UA("ancilla", ["l0", "l1"], theta) + UA("ancilla", ["i0", "i1"], theta) - UB(["l0", "l1"], ["j0", "j1", "j2"]) + UB(["i0", "i1"], ["j0", "j1", "j2"]) - for w in ["l0", "l1"]: # hadamard transform over |l> register + for w in ["i0", "i1"]: # hadamard transform over |l> register qml.Hadamard(w) return qml.state() @@ -278,7 +278,7 @@ def complete_circuit(theta): ############################################################################## # You can confirm that the circuit block encodes the original sparse matrix defined above. # -# Summary and conclusions +# Conclusion # ----------------------- # Block encoding is a powerful technique in quantum computing that allows us to implement a non-unitary # operation in a quantum circuit by embedding the operation in a larger unitary gate. @@ -286,7 +286,7 @@ def complete_circuit(theta): # The block encoding functionality provided in PennyLane allows you to explore and benchmark several # block encoding approaches for a desired problem. The efficiency of the block encoding methods # typically depends on the sparsity and structure of the original matrix. We hope that you can use -# these tips and tricks to find a more efficient block encoding your matrix! +# these tips and tricks to find a more efficient block encoding for your matrix! # # References # ---------- From ff5c3f14149eb97c70bc3c7ab14546270628a6ca Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 8 Nov 2023 11:37:11 -0500 Subject: [PATCH 27/61] update text --- demonstrations/tutorial_block_encoding.py | 55 +++++++---------------- 1 file changed, 17 insertions(+), 38 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index a124f3cf6f..53191faaee 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -13,44 +13,26 @@ *Author: Jay Soni, Diego Guala, Soran Jahangiri — Posted: September 29, 2023.* Prominent quantum algorithms such as quantum phase estimation and quantum singular value -transform require encoding a non-unitary matrix in a quantum circuit. This seems problematic +transform require encoding a non-unitary matrix in a quantum circuit. This is problematic because quantum computers can only perform unitary evolutions. Block encoding is a technique that solves this problem by embedding a non-unitary operator as a sub-block of a larger unitary matrix. In previous demos we have discussed methods for `simulator-friendly `_ encodings and block encodings using `linear combination of unitaries (LCU) decompositions `_. -In this tutorial we explore another general block encoding method that can be very efficient for +In this tutorial we explore another general block encoding method that can be very efficient for sparse and structured matrices. -Circuits with matrix access oracles ------------------------------------ -A general circuit for block encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N x N}` with :math:`N = 2^{n}` -can be constructed as shown in the figure below. +A general circuit for block encoding an arbitrary matrix :math:`A` can be constructed using matrix +access oracles as shown in the figure below. .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% :align: center -Where the :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The -:math:`U_A` and :math:`U_B` operations are oracles which give us access to the elements of -the matrix we wish to block encode. The specific action of the oracles are defined below: - -.. math:: U_A |i\rangle |j\rangle \ = ( A_{i, b(i,j)}|0\rangle + \sqrt{1 - |A_{i, b(i,j)}|^2}|1\rangle ) |i\rangle |j\rangle - -:math:`U_A`, in the most general case, can be constructed from a sequence of uniformly -controlled rotation gates. The rotation angles are computed from the elements of the block encoded -matrix as :math:`\theta = \text{arccos}(a_{ij})`. The gate complexity of this circuit is :math:`O(N^4)` -which makes its implementation highly inefficient. - -Let :math:`b(i,j)` be a function such that it takes a column index (:math:`j`) and returns the -row index for the :math:`i^{th}` non-zero entry in that column of :math:`A`. Note, if :math:`A` -is treated as completely dense (no non-zero entries), this function simply returns :math:`i`. -We use this to define the oracle :math:`U_B`: - -.. math:: U_B \cdot |i\rangle|j\rangle \ = \ |i\rangle |b(i,j)\rangle - -Finding an optimal quantum gates decomposition that implements :math:`U_A` and +The :math:`U_A` and :math:`U_B` operations are oracles which give us access to the elements of the +matrix we wish to block encode and the :math:`H^{\otimes n}` operation a Hadamard transformation on +:math:`n` qubits. Finding the optimal sequence of the quantum gates that implement :math:`U_A` and :math:`U_B` is not always possible. We now explore two approaches for the construction of these oracles that can be very efficient for matrices with specific sparsity and structure. @@ -62,18 +44,14 @@ efficient circuit without reducing accuracy. The FABLE circuit is constructed from a set of rotation and C-NOT gates. The rotation angles, -:math:`\Theta = (\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements of +:math:`(\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements of the block encoded matrix -.. math:: \left ( H^{\otimes 2n} P \right ) \Theta = C, - -where :math:`P` is a permutation that transforms a binary ordering to the Gray code ordering, -:math:`C = (\text{arccos}(A_{00}), ..., \text{arccos}(A_{nn}))` is obtained from the matrix elements -of the matrix :math:`A`, and :math:`H` is defined as +.. math:: \begin{pmatrix} \theta_1 \\ \hdots \\ \theta_n \end{pmatrix} = M \begin{pmatrix} \alpha_1 \\ \hdots \\ \alpha_n \end{pmatrix}, -.. math:: H = \begin{pmatrix} 1 & 1\\ - 1 & -1 - \end{pmatrix}. +where the angles :math:`\alpha` are obtained from the matrix elements of the matrix :math:`A` as +:math:`\alpha_1 = \text{arccos}(A_{00}), ...` and :math:`M` is the transformation matrix that can be +obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta` function. Let's now construct the FABLE block encoding circuit for a structured matrix. """ @@ -103,12 +81,13 @@ ############################################################################## # We construct the :math:`U_A` and :math:`U_B` oracles as well as an operator representing the -# tensor product of Hadamard gates. +# tensor product of Hadamard gates. Note that :math:`U_B` in FABLE is constructed as a set of SWAP +# gates. def UA(): for idx in range(len(thetas)): - qml.RY(thetas[idx],wires=4) - qml.CNOT(wires=[control_wires[idx],4]) + qml.RY(thetas[idx], wires = 4) + qml.CNOT(wires=[control_wires[idx], 4]) def UB(): qml.SWAP(wires=[0,2]) @@ -121,7 +100,7 @@ def HN(): ############################################################################## # We construct the circuit using these oracles and draw it. -dev = qml.device('default.qubit', wires=5) +dev = qml.device('default.qubit', wires = 5) @qml.qnode(dev) def circuit(): HN() From 3470a2ac4b71b460f9a49a5826ff07ef7dd2828a Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 8 Nov 2023 15:55:40 -0500 Subject: [PATCH 28/61] add input args --- .../block_encoding/fable_circuit.png | Bin 30502 -> 0 bytes .../thumbnail_block_encoding.png | Bin 19246 -> 11721 bytes demonstrations/tutorial_block_encoding.py | 61 ++++++++++-------- 3 files changed, 34 insertions(+), 27 deletions(-) delete mode 100644 demonstrations/block_encoding/fable_circuit.png diff --git a/demonstrations/block_encoding/fable_circuit.png b/demonstrations/block_encoding/fable_circuit.png deleted file mode 100644 index 356a4aed4f9138149c5be76a4431fd1ec45091a4..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 30502 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 diff --git a/demonstrations/block_encoding/thumbnail_block_encoding.png b/demonstrations/block_encoding/thumbnail_block_encoding.png index 842f12b6aad63a49749dea4fbc1ce1693d1909f4..73720a75a643c7521df1fe1751e08e31559af19e 100644 GIT binary patch literal 11721 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 literal 19246 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
*0& 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 PzaS^AD3u|3tolerance: qml.RY(thetas[idx],wires=4) qml.CNOT(wires=[control_wires[idx],4]) -print(qml.draw(circuit)()) +print(qml.draw_mpl(circuit, style='pennylane')(thetas, control_wires)) ############################################################################## # Compressing the circuit by removing some of the rotations is an approximation. We can now see how # good this approximation is in the case of our example. -def UA(): +def UA(thetas, control_wires): nots=[] for idx in range(len(thetas)): if abs(thetas[idx]) > tolerance: @@ -156,10 +163,10 @@ def UA(): nots.append(control_wires[idx]) qml.CNOT(nots+[4]) -print(qml.draw(circuit)()) +print(qml.draw_mpl(circuit, style='pennylane')(thetas, control_wires)) print(f"Original matrix:\n{A}", "\n") -M = len(A) * qml.matrix(circuit,wire_order=[0,1,2,3,4][::-1])()[0:len(A),0:len(A)] +M = len(A) * qml.matrix(circuit,wire_order=[4,3,2,1,0])(thetas, control_wires)[0:len(A),0:len(A)] print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## @@ -173,7 +180,7 @@ def UA(): # The quantum circuit for the oracle :math:`U_A`, presented above, accesses every entry of # :math:`A` and thus requires :math:`~ O(N^2)` gates to implement the oracle ([#fable]_). In the # special cases where :math:`A` is structured and sparse, we can generate a more efficient quantum -# circuit representation for :math:`U_A` and :math:`U_B`. Let's look at an example. +# circuit representation for :math:`U_A` and :math:`U_B` [#sparse]. Let's look at an example. # # Consider the sparse matrix given by: # From 6d630f1797448edca108c3d9a6537094c12cea24 Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 8 Nov 2023 16:02:45 -0500 Subject: [PATCH 29/61] add review comments --- demonstrations/tutorial_block_encoding.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index c26e240055..724be6142d 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -13,7 +13,7 @@ *Author: Jay Soni, Diego Guala, Soran Jahangiri — Posted: September 29, 2023.* Prominent quantum algorithms such as quantum phase estimation and quantum singular value -transform require encoding a non-unitary matrix in a quantum circuit. This is problematic +transformation sometimes use **non-unitary** matrices inside quantum circuits. This is problematic because quantum computers can only perform unitary evolutions. Block encoding is a technique that solves this problem by embedding a non-unitary operator as a sub-block of a larger unitary matrix. From d925a4ebb727a3df2c284ee9053c53b984c81219 Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 8 Nov 2023 16:22:57 -0500 Subject: [PATCH 30/61] correct code --- demonstrations/tutorial_block_encoding.py | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 724be6142d..673c74726f 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -74,10 +74,8 @@ code = gray_code(len(A)) n_selections = len(code) -control_wires = [ - int(np.log2(int(code[i], 2) ^ int(code[(i + 1) % n_selections], 2))) - for i in range(n_selections) -] +control_wires = [int(np.log2(int(code[i], 2) ^ int(code[(i + 1) % + n_selections], 2))) for i in range(n_selections)] ############################################################################## # We construct the :math:`U_A` and :math:`U_B` oracles as well as an operator representing the @@ -143,7 +141,7 @@ def UA(thetas, control_wires): qml.RY(thetas[idx],wires=4) qml.CNOT(wires=[control_wires[idx],4]) -print(qml.draw_mpl(circuit, style='pennylane')(thetas, control_wires)) +print(qml.draw_mpl(circuit, style='pennylane')()) ############################################################################## # Compressing the circuit by removing some of the rotations is an approximation. We can now see how @@ -163,10 +161,10 @@ def UA(thetas, control_wires): nots.append(control_wires[idx]) qml.CNOT(nots+[4]) -print(qml.draw_mpl(circuit, style='pennylane')(thetas, control_wires)) +print(qml.draw_mpl(circuit, style='pennylane')()) print(f"Original matrix:\n{A}", "\n") -M = len(A) * qml.matrix(circuit,wire_order=[4,3,2,1,0])(thetas, control_wires)[0:len(A),0:len(A)] +M = len(A) * qml.matrix(circuit,wire_order=[4,3,2,1,0])()[0:len(A),0:len(A)] print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## From b763630b9522ae816975155b79ce75c49d662e96 Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 8 Nov 2023 16:28:15 -0500 Subject: [PATCH 31/61] update metadata --- demonstrations/tutorial_block_encoding.metadata.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index a3bb8c9fd3..3cb892c778 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -21,10 +21,10 @@ "previewImages": [ { "type": "thumbnail", - "uri": "/_images/thumbnail_intro_qsvt.png" + "uri": "/_images/thumbnail_block_encoding.png" } ], - "seoDescription": "Learn about the many different methods to achieve a block-encoding for a given matrix.", + "seoDescription": "Learn about methods to achieve block-encoding for a given matrix.", "doi": "", "canonicalURL": "/qml/demos/tutorial_block_encoding", "references": [ @@ -52,7 +52,7 @@ "relatedContent": [ { "type": "demonstration", - "id": "tutorial_local_cost_functions", + "id": "tutorial_block_encoding", "weight": 1.0 } ] From 1c7cbf06f4a718d8a0cec0a32f7c8d5b2d30da4c Mon Sep 17 00:00:00 2001 From: soranjh Date: Wed, 8 Nov 2023 18:33:31 -0500 Subject: [PATCH 32/61] update rst file --- demos_quantum-computing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demos_quantum-computing.rst b/demos_quantum-computing.rst index 95424c3144..94f48a14ee 100644 --- a/demos_quantum-computing.rst +++ b/demos_quantum-computing.rst @@ -182,7 +182,7 @@ such as benchmarking and characterizing quantum processors. .. gallery-item:: :tooltip: Block Encoding - :figure: demonstrations/block_encoding/fable_circuit.png + :figure: demonstrations/block_encoding/general_circuit.png :description: :doc:`demos/tutorial_block_encoding` :tags: quantumcomputing qsvt optimization From be741466cb6356db48376b969f0ec5c8c7496af3 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 9 Nov 2023 11:20:12 -0500 Subject: [PATCH 33/61] address review comments --- demonstrations/tutorial_block_encoding.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 673c74726f..916236dc73 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -210,7 +210,7 @@ def UA(thetas, control_wires): # The :math:`U_A` oracle for this matrix is constructed from controlled rotation gates, similar to # the FABLE circuit. -def UA(ancilla, wire_i, theta): +def UA(theta, wire_i, ancilla): qml.ctrl(qml.RY, control=wire_i, control_values=[0, 0])(theta[0], wires=ancilla) qml.ctrl(qml.RY, control=wire_i, control_values=[1, 0])(theta[1], wires=ancilla) qml.ctrl(qml.RY, control=wire_i, control_values=[0, 1])(theta[2], wires=ancilla) @@ -219,10 +219,10 @@ def UA(ancilla, wire_i, theta): # The :math:`U_B` oracle is defined in terms of the so-called "Left" and "Right" shift operators. # They correspond to the modular arithmetic operations :math:`+1` or :math:`-1` respectively ([#sparse]_). -def shift_op(s_wires, shift="Left"): - control_values = [1, 1] if shift == "Left" else [0, 0] - qml.ctrl(qml.PauliX, control=s_wires[:2], control_values=control_values)(wires=s_wires[2]) - qml.ctrl(qml.PauliX, control=s_wires[0], control_values=control_values[0])(wires=s_wires[1]) +def shift_op(s_wires, shift="Left"): + for index in range(len(s_wires)-1, 0, -1): + control_values = [1] * index if shift == "Left" else [0] * index + qml.ctrl(qml.PauliX, control=s_wires[:index], control_values=control_values)(wires=s_wires[index]) qml.PauliX(s_wires[0]) @@ -240,11 +240,11 @@ def complete_circuit(theta): for w in ["i0", "i1"]: # hadamard transform over |i> register qml.Hadamard(w) - UA("ancilla", ["i0", "i1"], theta) + UA(theta, ["i0", "i1"], "ancilla") UB(["i0", "i1"], ["j0", "j1", "j2"]) - for w in ["i0", "i1"]: # hadamard transform over |l> register + for w in ["i0", "i1"]: # hadamard transform over |i> register qml.Hadamard(w) return qml.state() @@ -261,6 +261,8 @@ def complete_circuit(theta): ############################################################################## # You can confirm that the circuit block encodes the original sparse matrix defined above. +# Note that if we wanted to increase the dimension of A (for example 16 x 16), then we need +# only to add more wires to the "j" register in the device and :code:`UB`. # # Conclusion # ----------------------- From 9bc5f3a162478feb2706d180c921e2dc40ae3ef2 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 9 Nov 2023 11:46:31 -0500 Subject: [PATCH 34/61] more code review comments --- demonstrations/tutorial_block_encoding.py | 28 ++++++++++++++++++----- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 916236dc73..68960a0563 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -206,6 +206,21 @@ def UA(thetas, control_wires): print(f"Original A:\n{A}", "\n") +############################################################################## +# The next step is to identify and prepare the qubit registers used in the oracle access framework. +# There are three registers ("ancilla", "wires_i", "wires_j"): +# +# The "ancilla" register will always contain a single qubit, this is the target where we apply the +# controlled rotation gates. The "wires_i" register needs to be large enough to binary encode the +# maximum number of non-zero entries in any column or row. Given the structure of :math:`A` defined +# above, we have at most 3 non-zero entries, thus this register will have 2 qubits. Finally, the +# "wires_j" register will be used to encode :math:`A` itself, so it will have 3 qubits. We prepare +# the wires below: + +ancilla_wires = ["ancilla"] # always 1 qubit for controlled rotations +wires_i = ["i0", "i1"] # depends on the sparse structure of A +wires_j = ["j0", "j1", "j2"] # depends on the size of A + ############################################################################## # The :math:`U_A` oracle for this matrix is constructed from controlled rotation gates, similar to # the FABLE circuit. @@ -233,18 +248,18 @@ def UB(wires_i, wires_j): ############################################################################## # We now construct our circuit to block encode the sparse matrix. -dev = qml.device("default.qubit", wires=["ancilla", "i1", "i0", "j2", "j1", "j0"]) +dev = qml.device("default.qubit", wires=(ancilla_wires + wires_i + wires_j)) @qml.qnode(dev) def complete_circuit(theta): - for w in ["i0", "i1"]: # hadamard transform over |i> register + for w in wires_i: # hadamard transform over |i> register qml.Hadamard(w) - UA(theta, ["i0", "i1"], "ancilla") + UA(theta, wires_i, ancilla_wires) - UB(["i0", "i1"], ["j0", "j1", "j2"]) + UB(wires_i, wires_j) - for w in ["i0", "i1"]: # hadamard transform over |i> register + for w in wires_i: # hadamard transform over |i> register qml.Hadamard(w) return qml.state() @@ -256,7 +271,8 @@ def complete_circuit(theta): print(qml.draw(complete_circuit)(theta), "\n") print("BlockEncoded Mat:") -mat = qml.matrix(complete_circuit)(theta).real[:8, :8] * s +wire_order = ancilla_wires + wires_i[::-1] + wires_j[::-1] +mat = qml.matrix(complete_circuit, wire_order=wire_order)(theta).real[:8, :8] * s print(mat, "\n") ############################################################################## From 4cc5d20ff64819aa56c6825f79577e4c31d5f8d4 Mon Sep 17 00:00:00 2001 From: Diego Date: Thu, 9 Nov 2023 11:53:55 -0500 Subject: [PATCH 35/61] FABLE: change oracle signatures, allow arbitrary matrix size --- demonstrations/tutorial_block_encoding.py | 64 ++++++++++++----------- 1 file changed, 34 insertions(+), 30 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 916236dc73..4329fcec91 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -71,57 +71,60 @@ alphas = 2 * np.arccos(A).flatten() thetas = compute_theta(alphas) -code = gray_code(len(A)) +code = gray_code(2*np.sqrt(len(A))) n_selections = len(code) control_wires = [int(np.log2(int(code[i], 2) ^ int(code[(i + 1) % n_selections], 2))) for i in range(n_selections)] +target_wire = max(control_wires)+1 + +wires_i = list(range(int((max(control_wires)+1)/2))) + +wires_j = list(range(int((max(control_wires)+1)/2),int(max(control_wires)+1))) + +hn_wires = wires_j + ############################################################################## # We construct the :math:`U_A` and :math:`U_B` oracles as well as an operator representing the # tensor product of Hadamard gates. Note that :math:`U_B` in FABLE is constructed as a set of SWAP # gates. -def UA(thetas, input_wires): - wire = max(input_wires) + 1 - +def UA(thetas, control_wires, target_wire): for i in range(len(thetas)): - qml.RY(thetas[i], wires=wire) - qml.CNOT(wires=[input_wires[i], wire]) + qml.RY(thetas[i], wires=target_wire) + qml.CNOT(wires=[control_wires[i], target_wire]) -def UB(input_wires): - wires = list(set(input_wires))[:-2] - for w in wires: - qml.SWAP(wires=[w, w + 2]) +def UB(wires_i, wires_j): + for idx,val in enumerate(wires_i): + qml.SWAP(wires=[val,wires_j[idx]]) def HN(input_wires): - m = int(np.log2(max(input_wires) + 1)) - wires = list(set(input_wires))[-m:] - for w in wires: + for w in input_wires: qml.Hadamard(wires=w) ############################################################################## # We construct the circuit using these oracles and draw it. -dev = qml.device('default.qubit', wires = 5) +dev = qml.device('default.qubit') @qml.qnode(dev) def circuit(): - HN(control_wires) - UA(thetas, control_wires) - UB(control_wires) - HN(control_wires) + HN(hn_wires,) + UA(thetas, control_wires,target_wire) + UB(wires_i, wires_j) + HN(hn_wires) return qml.state() -print(qml.draw_mpl(circuit, style='pennylane')()) +qml.draw_mpl(circuit,wire_order=range(target_wire+1))() ############################################################################## # We compute the matrix representation of the circuit and print its top-left block to compare it # with the original matrix. print(f"Original matrix:\n{A}", "\n") -M = len(A) * qml.matrix(circuit,wire_order=[4,3,2,1,0])()[0:len(A),0:len(A)] +M = len(A) * qml.matrix(circuit,wire_order=range(target_wire,-1,-1))()[0:len(A),0:len(A)] print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## @@ -135,36 +138,37 @@ def circuit(): tolerance= 0.01 -def UA(thetas, control_wires): +def UA(thetas, control_wires, target_wire): for idx in range(len(thetas)): if abs(thetas[idx])>tolerance: - qml.RY(thetas[idx],wires=4) - qml.CNOT(wires=[control_wires[idx],4]) + qml.RY(thetas[idx], wires=target_wire) + qml.CNOT(wires=[control_wires[idx], target_wire]) -print(qml.draw_mpl(circuit, style='pennylane')()) +qml.draw_mpl(circuit, wire_order=range(target_wire+1), style='pennylane')() ############################################################################## # Compressing the circuit by removing some of the rotations is an approximation. We can now see how # good this approximation is in the case of our example. -def UA(thetas, control_wires): +def UA(thetas, control_wires, target_wire): nots=[] for idx in range(len(thetas)): if abs(thetas[idx]) > tolerance: for cidx in nots: - qml.CNOT(wires=[cidx,4]) - qml.RY(thetas[idx],wires=4) + qml.CNOT(wires=[cidx,target_wire]) + qml.RY(thetas[idx],wires=target_wire) nots=[] if control_wires[idx] in nots: del(nots[nots.index(control_wires[idx])]) else: nots.append(control_wires[idx]) - qml.CNOT(nots+[4]) + for cidx in nots: + qml.CNOT([cidx,target_wire]) -print(qml.draw_mpl(circuit, style='pennylane')()) +qml.draw_mpl(circuit, wire_order=range(target_wire+1), style='pennylane')() print(f"Original matrix:\n{A}", "\n") -M = len(A) * qml.matrix(circuit,wire_order=[4,3,2,1,0])()[0:len(A),0:len(A)] +M = len(A) * qml.matrix(circuit,wire_order=range(target_wire,-1,-1))()[0:len(A),0:len(A)] print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## From f6f17ca2d8f832196e01592c77a6d137af661745 Mon Sep 17 00:00:00 2001 From: soranjh Date: Thu, 9 Nov 2023 14:06:14 -0500 Subject: [PATCH 36/61] update code --- demonstrations/tutorial_block_encoding.py | 42 ++++++++++++++--------- demos_quantum-computing.rst | 2 +- 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index bb7efacea7..052776d182 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -38,20 +38,22 @@ Block encoding with FABLE ------------------------- -The "Fast Approximate quantum circuits for BLock Encodings" (FABLE) technique is a general method -for block encoding dense and sparse matrices [#fable]. The level of approximation in FABLE can be adjusted -to simplify the resulting circuit. For matrices with specific structures, FABLE provides an -efficient circuit without reducing accuracy. +The Fast Approximate BLock Encodings (FABLE) technique is a general method for block encoding dense +and sparse matrices [#fable]_. The level of approximation in FABLE can be adjusted to simplify the +resulting circuit. For matrices with specific structures, FABLE provides an efficient circuit +without reducing accuracy. The FABLE circuit is constructed from a set of rotation and C-NOT gates. The rotation angles, :math:`(\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements of the block encoded matrix -.. math:: \begin{pmatrix} \theta_1 \\ \hdots \\ \theta_n \end{pmatrix} = M \begin{pmatrix} \alpha_1 \\ \hdots \\ \alpha_n \end{pmatrix}, +.. math:: \begin{pmatrix} \theta_1 \\ \cdots \\ \theta_n \end{pmatrix} = + M \begin{pmatrix} \alpha_1 \\ \cdots \\ \alpha_n \end{pmatrix}, where the angles :math:`\alpha` are obtained from the matrix elements of the matrix :math:`A` as -:math:`\alpha_1 = \text{arccos}(A_{00}), ...` and :math:`M` is the transformation matrix that can be -obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta` function. +:math:`\alpha_1 = \text{arccos}(A_{00}), ...`, and :math:`M` is the transformation matrix that can be +obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta()` +function. Let's now construct the FABLE block encoding circuit for a structured matrix. """ @@ -66,7 +68,7 @@ [ 0.99675093, 0.99675093, 0.83514837, 0.83514837]]) ############################################################################## -# We now compute the rotation angles and obtain the control wires for the C-NOT gates. +# We now compute the rotation angles and obtain the wires for the rotation and C-NOT gates. alphas = 2 * np.arccos(A).flatten() thetas = compute_theta(alphas) @@ -79,14 +81,16 @@ target_wire = max(control_wires)+1 -wires_i = list(range(int((max(control_wires)+1)/2))) +############################################################################## +# We also need to define the wires for the :math:`U_B` and :math:`H^{\otimes n}` operations. +wires_i = list(range(int((max(control_wires)+1)/2))) wires_j = list(range(int((max(control_wires)+1)/2),int(max(control_wires)+1))) hn_wires = wires_j ############################################################################## -# We construct the :math:`U_A` and :math:`U_B` oracles as well as an operator representing the +# We now construct the :math:`U_A` and :math:`U_B` oracles as well as the operator representing the # tensor product of Hadamard gates. Note that :math:`U_B` in FABLE is constructed as a set of SWAP # gates. @@ -117,7 +121,7 @@ def circuit(): HN(hn_wires) return qml.state() -qml.draw_mpl(circuit,wire_order=range(target_wire+1))() +qml.draw_mpl(circuit, wire_order=range(target_wire+1), style='pennylane')() ############################################################################## # We compute the matrix representation of the circuit and print its top-left block to compare it @@ -180,9 +184,9 @@ def UA(thetas, control_wires, target_wire): # Block-encoding sparse matrices # ------------------------------ # The quantum circuit for the oracle :math:`U_A`, presented above, accesses every entry of -# :math:`A` and thus requires :math:`~ O(N^2)` gates to implement the oracle ([#fable]_). In the +# :math:`A` and thus requires :math:`~ O(N^2)` gates to implement the oracle [#fable]_. In the # special cases where :math:`A` is structured and sparse, we can generate a more efficient quantum -# circuit representation for :math:`U_A` and :math:`U_B` [#sparse]. Let's look at an example. +# circuit representation for :math:`U_A` and :math:`U_B` [#sparse]_. Let's look at an example. # # Consider the sparse matrix given by: # @@ -236,7 +240,7 @@ def UA(theta, wire_i, ancilla): ############################################################################## # The :math:`U_B` oracle is defined in terms of the so-called "Left" and "Right" shift operators. -# They correspond to the modular arithmetic operations :math:`+1` or :math:`-1` respectively ([#sparse]_). +# They correspond to the modular arithmetic operations :math:`+1` or :math:`-1` respectively [#sparse]_. def shift_op(s_wires, shift="Left"): for index in range(len(s_wires)-1, 0, -1): @@ -250,7 +254,7 @@ def UB(wires_i, wires_j): qml.ctrl(shift_op, control=wires_i[1])(wires_j, shift="Right") ############################################################################## -# We now construct our circuit to block encode the sparse matrix. +# We now construct our circuit to block encode the sparse matrix and draw it. dev = qml.device("default.qubit", wires=(ancilla_wires + wires_i + wires_j)) @@ -274,6 +278,10 @@ def complete_circuit(theta): print("Quantum Circuit:") print(qml.draw(complete_circuit)(theta), "\n") +############################################################################## +# We compute the matrix representation of the circuit and print its top-left block to compare it +# with the original matrix. + print("BlockEncoded Mat:") wire_order = ancilla_wires + wires_i[::-1] + wires_j[::-1] mat = qml.matrix(complete_circuit, wire_order=wire_order)(theta).real[:8, :8] * s @@ -286,8 +294,8 @@ def complete_circuit(theta): # # Conclusion # ----------------------- -# Block encoding is a powerful technique in quantum computing that allows us to implement a non-unitary -# operation in a quantum circuit by embedding the operation in a larger unitary gate. +# Block encoding is a powerful technique in quantum computing that allows us to implement a +# non-unitary operation in a quantum circuit by embedding the operation in a larger unitary gate. # In this demo, we reviewed two important block encoding methods with code examples using PennyLane. # The block encoding functionality provided in PennyLane allows you to explore and benchmark several # block encoding approaches for a desired problem. The efficiency of the block encoding methods diff --git a/demos_quantum-computing.rst b/demos_quantum-computing.rst index 94f48a14ee..ba4f8941ef 100644 --- a/demos_quantum-computing.rst +++ b/demos_quantum-computing.rst @@ -182,7 +182,7 @@ such as benchmarking and characterizing quantum processors. .. gallery-item:: :tooltip: Block Encoding - :figure: demonstrations/block_encoding/general_circuit.png + :figure: demonstrations/block_encoding/thumbnail_block_encoding.png :description: :doc:`demos/tutorial_block_encoding` :tags: quantumcomputing qsvt optimization From e440af520d8350f098c009a0b853fe446eb75c8b Mon Sep 17 00:00:00 2001 From: soranjh Date: Thu, 9 Nov 2023 14:15:24 -0500 Subject: [PATCH 37/61] modify code --- demonstrations/tutorial_block_encoding.py | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 052776d182..e062cd79da 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -259,24 +259,18 @@ def UB(wires_i, wires_j): dev = qml.device("default.qubit", wires=(ancilla_wires + wires_i + wires_j)) @qml.qnode(dev) -def complete_circuit(theta): - for w in wires_i: # hadamard transform over |i> register - qml.Hadamard(w) - - UA(theta, wires_i, ancilla_wires) - +def complete_circuit(thetas): + HN(wires_i) # hadamard transform over |i> register + UA(thetas, wires_i, ancilla_wires) UB(wires_i, wires_j) - - for w in wires_i: # hadamard transform over |i> register - qml.Hadamard(w) - + HN(wires_i) # hadamard transform over |i> register return qml.state() s = 4 # normalization constant -theta = 2 * np.arccos(np.array([alpha - 1, beta, gamma])) +thetas = 2 * np.arccos(np.array([alpha - 1, beta, gamma])) print("Quantum Circuit:") -print(qml.draw(complete_circuit)(theta), "\n") +print(qml.draw_mpl(complete_circuit, style='pennylane')(thetas), "\n") ############################################################################## # We compute the matrix representation of the circuit and print its top-left block to compare it @@ -284,7 +278,7 @@ def complete_circuit(theta): print("BlockEncoded Mat:") wire_order = ancilla_wires + wires_i[::-1] + wires_j[::-1] -mat = qml.matrix(complete_circuit, wire_order=wire_order)(theta).real[:8, :8] * s +mat = qml.matrix(complete_circuit, wire_order=wire_order)(thetas).real[:8, :8] * s print(mat, "\n") ############################################################################## From 50802872006cdba2de90f44822fecf145946073f Mon Sep 17 00:00:00 2001 From: Diego Date: Fri, 10 Nov 2023 10:55:08 -0500 Subject: [PATCH 38/61] update images --- .../block_encoding/general_circuit.png | Bin 11721 -> 15729 bytes .../thumbnail_block_encoding.png | Bin 11721 -> 15729 bytes 2 files changed, 0 insertions(+), 0 deletions(-) diff --git a/demonstrations/block_encoding/general_circuit.png b/demonstrations/block_encoding/general_circuit.png index 73720a75a643c7521df1fe1751e08e31559af19e..cb15db5dfa1e0d4ec30191e792a3602adb8ce9c2 100644 GIT binary patch literal 15729 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 diff --git a/demonstrations/block_encoding/thumbnail_block_encoding.png b/demonstrations/block_encoding/thumbnail_block_encoding.png index 73720a75a643c7521df1fe1751e08e31559af19e..cb15db5dfa1e0d4ec30191e792a3602adb8ce9c2 100644 GIT binary patch literal 15729 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 From 2497e7bab445a995288ba797e233ff705127176e Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Fri, 10 Nov 2023 12:56:05 -0500 Subject: [PATCH 39/61] fix wire labeling and make uniform --- demonstrations/tutorial_block_encoding.py | 100 ++++++++++++---------- 1 file changed, 56 insertions(+), 44 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index e062cd79da..c802e02e9e 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -79,30 +79,39 @@ control_wires = [int(np.log2(int(code[i], 2) ^ int(code[(i + 1) % n_selections], 2))) for i in range(n_selections)] -target_wire = max(control_wires)+1 - ############################################################################## -# We also need to define the wires for the :math:`U_B` and :math:`H^{\otimes n}` operations. +# The next step is to identify and prepare the qubit registers used in the oracle access framework. +# There are three registers :code:`("ancilla", "wires_i", "wires_j")`: +# +# The :code:`"ancilla"` register will always contain a single qubit, this is the target where we apply the +# controlled rotation gates. The :code:`"wires_i"` and :code:`"wires_j"` registers are the same size +# and need to be able to encode :math:`A` itself, so they will both have 2 qubits. +# +# Finally, we construct a wire map to translate the :code:`control_wires` we defined above into the +# wire registers we prepare here: -wires_i = list(range(int((max(control_wires)+1)/2))) -wires_j = list(range(int((max(control_wires)+1)/2),int(max(control_wires)+1))) +ancilla_wire = "ancilla" -hn_wires = wires_j +s = int(np.log2(A.shape[0])) # number of qubits needed to encode A +wires_i = [f"i{index}" for index in range(s)] # depend on the size of A +wires_j = [f"j{index}" for index in range(s)] + +wire_map = {control_index : wire for control_index, wire in enumerate(wires_j+wires_i)} ############################################################################## # We now construct the :math:`U_A` and :math:`U_B` oracles as well as the operator representing the # tensor product of Hadamard gates. Note that :math:`U_B` in FABLE is constructed as a set of SWAP # gates. -def UA(thetas, control_wires, target_wire): - for i in range(len(thetas)): - qml.RY(thetas[i], wires=target_wire) - qml.CNOT(wires=[control_wires[i], target_wire]) +def UA(thetas, control_wires, ancilla): + for theta, control_index in zip(thetas, control_wires): + qml.RY(theta, wires=ancilla) + qml.CNOT(wires=[wire_map[control_index], ancilla]) def UB(wires_i, wires_j): - for idx,val in enumerate(wires_i): - qml.SWAP(wires=[val,wires_j[idx]]) + for w_i, w_j in zip(wires_i, wires_j): + qml.SWAP(wires=[w_i, w_j]) def HN(input_wires): @@ -112,23 +121,24 @@ def HN(input_wires): ############################################################################## # We construct the circuit using these oracles and draw it. -dev = qml.device('default.qubit') +dev = qml.device('default.qubit', wires=[ancilla_wire] + wires_i + wires_j) @qml.qnode(dev) def circuit(): - HN(hn_wires,) - UA(thetas, control_wires,target_wire) + HN(wires_i) + UA(thetas, control_wires, ancilla_wire) UB(wires_i, wires_j) - HN(hn_wires) + HN(wires_i) return qml.state() -qml.draw_mpl(circuit, wire_order=range(target_wire+1), style='pennylane')() +qml.draw_mpl(circuit, style='pennylane')() ############################################################################## # We compute the matrix representation of the circuit and print its top-left block to compare it # with the original matrix. print(f"Original matrix:\n{A}", "\n") -M = len(A) * qml.matrix(circuit,wire_order=range(target_wire,-1,-1))()[0:len(A),0:len(A)] +wire_order = [ancilla_wire] + wires_i[::-1] + wires_j[::-1] +M = len(A) * qml.matrix(circuit, wire_order=wire_order)().real[0:len(A),0:len(A)] print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## @@ -142,37 +152,38 @@ def circuit(): tolerance= 0.01 -def UA(thetas, control_wires, target_wire): - for idx in range(len(thetas)): - if abs(thetas[idx])>tolerance: - qml.RY(thetas[idx], wires=target_wire) - qml.CNOT(wires=[control_wires[idx], target_wire]) +def UA(thetas, control_wires, ancilla): + for theta, control_index in zip(thetas, control_wires): + if abs(theta)>tolerance: + qml.RY(theta, wires=ancilla) + qml.CNOT(wires=[wire_map[control_index], ancilla]) -qml.draw_mpl(circuit, wire_order=range(target_wire+1), style='pennylane')() +qml.draw_mpl(circuit, style='pennylane')() ############################################################################## # Compressing the circuit by removing some of the rotations is an approximation. We can now see how # good this approximation is in the case of our example. -def UA(thetas, control_wires, target_wire): +def UA(thetas, control_wires, ancilla): nots=[] - for idx in range(len(thetas)): - if abs(thetas[idx]) > tolerance: - for cidx in nots: - qml.CNOT(wires=[cidx,target_wire]) - qml.RY(thetas[idx],wires=target_wire) + for theta, control_index in zip(thetas, control_wires): + if abs(theta) > tolerance: + for c_wire in nots: + qml.CNOT(wires=[c_wire, ancilla]) + qml.RY(theta,wires=ancilla) nots=[] - if control_wires[idx] in nots: - del(nots[nots.index(control_wires[idx])]) + if (cw := wire_map[control_index]) in nots: + del(nots[nots.index(cw)]) else: - nots.append(control_wires[idx]) - for cidx in nots: - qml.CNOT([cidx,target_wire]) + nots.append(wire_map[control_index]) + for c_wire in nots: + qml.CNOT([c_wire, ancilla]) -qml.draw_mpl(circuit, wire_order=range(target_wire+1), style='pennylane')() +qml.draw_mpl(circuit, style='pennylane')() print(f"Original matrix:\n{A}", "\n") -M = len(A) * qml.matrix(circuit,wire_order=range(target_wire,-1,-1))()[0:len(A),0:len(A)] +wire_order = [ancilla_wire] + wires_i[::-1] + wires_j[::-1] +M = len(A) * qml.matrix(circuit,wire_order=wire_order)().real[0:len(A),0:len(A)] print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## @@ -215,19 +226,20 @@ def UA(thetas, control_wires, target_wire): print(f"Original A:\n{A}", "\n") ############################################################################## -# The next step is to identify and prepare the qubit registers used in the oracle access framework. -# There are three registers ("ancilla", "wires_i", "wires_j"): +# Once again we identify and prepare the qubit registers used in the oracle access framework: # -# The "ancilla" register will always contain a single qubit, this is the target where we apply the -# controlled rotation gates. The "wires_i" register needs to be large enough to binary encode the +# The :code:`"ancilla"` register will still contain a single qubit, the target where for the +# controlled rotation gates. The :code:`"wires_i"` register needs to be large enough to binary encode the # maximum number of non-zero entries in any column or row. Given the structure of :math:`A` defined # above, we have at most 3 non-zero entries, thus this register will have 2 qubits. Finally, the -# "wires_j" register will be used to encode :math:`A` itself, so it will have 3 qubits. We prepare +# :code:`"wires_j"` register will be used to encode :math:`A` itself, so it will have 3 qubits. We prepare # the wires below: +s = int(np.log2(A.shape[0])) # number of qubits needed to encode A + ancilla_wires = ["ancilla"] # always 1 qubit for controlled rotations wires_i = ["i0", "i1"] # depends on the sparse structure of A -wires_j = ["j0", "j1", "j2"] # depends on the size of A +wires_j = [f"j{index}" for index in range(s)] # depends on the size of A ############################################################################## # The :math:`U_A` oracle for this matrix is constructed from controlled rotation gates, similar to @@ -278,7 +290,7 @@ def complete_circuit(thetas): print("BlockEncoded Mat:") wire_order = ancilla_wires + wires_i[::-1] + wires_j[::-1] -mat = qml.matrix(complete_circuit, wire_order=wire_order)(thetas).real[:8, :8] * s +mat = qml.matrix(complete_circuit, wire_order=wire_order)(thetas).real[:len(A), :len(A)] * s print(mat, "\n") ############################################################################## From 77cf815d6fa506d40de034d28fadabb45c834069 Mon Sep 17 00:00:00 2001 From: soranjh Date: Fri, 10 Nov 2023 14:07:37 -0500 Subject: [PATCH 40/61] correct text --- demonstrations/tutorial_block_encoding.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index e062cd79da..0f74c10dee 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -16,7 +16,7 @@ transformation sometimes use **non-unitary** matrices inside quantum circuits. This is problematic because quantum computers can only perform unitary evolutions. Block encoding is a technique that solves this problem by embedding a non-unitary operator as a sub-block of a larger unitary -matrix. +matrix. In previous demos we have discussed methods for `simulator-friendly `_ encodings and block encodings using `linear combination of unitaries (LCU) decompositions `_. From 7f18d6788efc9ac1dc8cab7d6950175bb409fa76 Mon Sep 17 00:00:00 2001 From: soranjh Date: Fri, 10 Nov 2023 15:48:47 -0500 Subject: [PATCH 41/61] modify text and code --- demonstrations/tutorial_block_encoding.py | 108 +++++++++++----------- 1 file changed, 56 insertions(+), 52 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 11504d20c8..19ca20cc03 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -14,27 +14,27 @@ Prominent quantum algorithms such as quantum phase estimation and quantum singular value transformation sometimes use **non-unitary** matrices inside quantum circuits. This is problematic -because quantum computers can only perform unitary evolutions. Block encoding is a technique +because quantum computers can only perform unitary evolutions. 🔥 Block encoding is a technique that solves this problem by embedding a non-unitary operator as a sub-block of a larger unitary -matrix. +matrix. 🧯 In previous demos we have discussed methods for `simulator-friendly `_ -encodings and block encodings using `linear combination of unitaries (LCU) decompositions `_. -In this tutorial we explore another general block encoding method that can be very efficient for -sparse and structured matrices. +encodings and block encodings using `linear combination of unitaries `_ +(LCU) decompositions. In this tutorial we explore another general block encoding method that can be +very efficient for sparse and structured matrices. -Circuits with matrix access oracles can block encode an arbitrary matrix :math:`A`. These circuits -can be constructed as shown in the figure below. +Circuits with matrix access oracles [[#fable]_, [#sparse]_] can block encode an arbitrary matrix +:math:`A`. These circuits can be constructed as shown in the figure below. .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% :align: center -The :math:`U_A` and :math:`U_B` operations are oracles which give us access to the elements of the -matrix we wish to block encode and the :math:`H^{\otimes n}` operation a Hadamard transformation on -:math:`n` qubits. Finding the optimal sequence of the quantum gates that implement :math:`U_A` and -:math:`U_B` is not always possible. We now explore two approaches for the construction of -these oracles that can be very efficient for matrices with specific sparsity and structure. +The :math:`U_A` and :math:`U_B` operations are oracles which provide access to the elements of the +matrix we wish to block encode and the :math:`H^{\otimes n}` operation is a Hadamard transformation +on :math:`n` qubits. Finding the optimal sequence of the quantum gates that implement :math:`U_A` +and :math:`U_B` is not always trivial. We now explore two approaches for constructing these oracles +that can be very efficient for matrices with specific sparsity and structure. Block encoding with FABLE ------------------------- @@ -45,14 +45,14 @@ The FABLE circuit is constructed from a set of rotation and C-NOT gates. The rotation angles, :math:`(\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements of -the block encoded matrix +the block-encoded matrix .. math:: \begin{pmatrix} \theta_1 \\ \cdots \\ \theta_n \end{pmatrix} = M \begin{pmatrix} \alpha_1 \\ \cdots \\ \alpha_n \end{pmatrix}, where the angles :math:`\alpha` are obtained from the matrix elements of the matrix :math:`A` as -:math:`\alpha_1 = \text{arccos}(A_{00}), ...`, and :math:`M` is the transformation matrix that can be -obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta()` +:math:`\alpha_1 = \text{arccos}(A_{00}), ...,` and :math:`M` is the transformation matrix that can +be obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta()` function. Let's now construct the FABLE block encoding circuit for a structured matrix. @@ -68,7 +68,7 @@ [ 0.99675093, 0.99675093, 0.83514837, 0.83514837]]) ############################################################################## -# We now compute the rotation angles and obtain the wires for the rotation and C-NOT gates. +# We compute the rotation angles. alphas = 2 * np.arccos(A).flatten() thetas = compute_theta(alphas) @@ -76,27 +76,29 @@ code = gray_code(2*np.sqrt(len(A))) n_selections = len(code) -control_wires = [int(np.log2(int(code[i], 2) ^ int(code[(i + 1) % - n_selections], 2))) for i in range(n_selections)] - ############################################################################## -# The next step is to identify and prepare the qubit registers used in the oracle access framework. +# The next step is to identify and prepare the qubit registers used in the oracle access framework. # There are three registers :code:`("ancilla", "wires_i", "wires_j")`: # -# The :code:`"ancilla"` register will always contain a single qubit, this is the target where we apply the -# controlled rotation gates. The :code:`"wires_i"` and :code:`"wires_j"` registers are the same size -# and need to be able to encode :math:`A` itself, so they will both have 2 qubits. -# -# Finally, we construct a wire map to translate the :code:`control_wires` we defined above into the -# wire registers we prepare here: +# The :code:`"ancilla"` register will always contain a single qubit, this is the target where we +# apply the rotation gates. The :code:`"wires_i"` and :code:`"wires_j"` registers are the same size +# and need to be able to encode :math:`A` itself, so they will both have :math:`4` qubits for our +# matrix. ancilla_wire = "ancilla" -s = int(np.log2(A.shape[0])) # number of qubits needed to encode A +s = int(np.log2(A.shape[0])) # number of qubits needed to encode A wires_i = [f"i{index}" for index in range(s)] # depend on the size of A wires_j = [f"j{index}" for index in range(s)] -wire_map = {control_index : wire for control_index, wire in enumerate(wires_j+wires_i)} +############################################################################## +# Finally, we obtain the control wires for the C-NOT gates and a wire map that we later use to +# translate the :code:`control_wires` into the wire registers we prepared. + +control_wires = [int(np.log2(int(code[i], 2) ^ int(code[(i + 1) % + n_selections], 2))) for i in range(n_selections)] + +wire_map = {control_index : wire for control_index, wire in enumerate(wires_j + wires_i)} ############################################################################## # We now construct the :math:`U_A` and :math:`U_B` oracles as well as the operator representing the @@ -133,8 +135,8 @@ def circuit(): qml.draw_mpl(circuit, style='pennylane')() ############################################################################## -# We compute the matrix representation of the circuit and print its top-left block to compare it -# with the original matrix. +# Finally, we compute the matrix representation of the circuit and print its top-left block to +# compare it with the original matrix. print(f"Original matrix:\n{A}", "\n") wire_order = [ancilla_wire] + wires_i[::-1] + wires_j[::-1] @@ -142,7 +144,9 @@ def circuit(): print(f"Block-encoded matrix:\n{M}", "\n") ############################################################################## -# You can easily confirm that the circuit block encodes the original matrix defined above. +# You can easily confirm that the circuit block encodes the original matrix defined above. Note that +# the dimension of :math:`A` should be :math:`2^n, n = 1, 2, 3, ...`. For matrices with an arbitrary +# size, we can add zeros to reach the correct dimension. # # The interesting point about the FABLE method is that we can eliminate those rotation gates that # have an angle smaller than a defined threshold. This leaves a sequence of C-NOT gates that in @@ -192,7 +196,7 @@ def UA(thetas, control_wires, ancilla): # However, this is not always true for an arbitrary matrix. Can you construct another matrix that # allows a significant compression of the block encoding circuit without affecting the accuracy? # -# Block-encoding sparse matrices +# Block encoding sparse matrices # ------------------------------ # The quantum circuit for the oracle :math:`U_A`, presented above, accesses every entry of # :math:`A` and thus requires :math:`~ O(N^2)` gates to implement the oracle [#fable]_. In the @@ -229,16 +233,16 @@ def UA(thetas, control_wires, ancilla): # Once again we identify and prepare the qubit registers used in the oracle access framework: # # The :code:`"ancilla"` register will still contain a single qubit, the target where for the -# controlled rotation gates. The :code:`"wires_i"` register needs to be large enough to binary encode the -# maximum number of non-zero entries in any column or row. Given the structure of :math:`A` defined -# above, we have at most 3 non-zero entries, thus this register will have 2 qubits. Finally, the -# :code:`"wires_j"` register will be used to encode :math:`A` itself, so it will have 3 qubits. We prepare -# the wires below: +# controlled rotation gates. The :code:`"wires_i"` register needs to be large enough to binary +# encode the maximum number of non-zero entries in any column or row. Given the structure of +# :math:`A` defined above, we have at most 3 non-zero entries, thus this register will have 2 +# qubits. Finally, the :code:`"wires_j"` register will be used to encode :math:`A` itself, so it +# will have 3 qubits. We prepare the wires below: -s = int(np.log2(A.shape[0])) # number of qubits needed to encode A +s = int(np.log2(A.shape[0])) # number of qubits needed to encode A -ancilla_wires = ["ancilla"] # always 1 qubit for controlled rotations -wires_i = ["i0", "i1"] # depends on the sparse structure of A +ancilla_wires = ["ancilla"] # always 1 qubit for controlled rotations +wires_i = ["i0", "i1"] # depends on the sparse structure of A wires_j = [f"j{index}" for index in range(s)] # depends on the size of A ############################################################################## @@ -251,7 +255,7 @@ def UA(theta, wire_i, ancilla): qml.ctrl(qml.RY, control=wire_i, control_values=[0, 1])(theta[2], wires=ancilla) ############################################################################## -# The :math:`U_B` oracle is defined in terms of the so-called "Left" and "Right" shift operators. +# The :math:`U_B` oracle is defined in terms of the so-called ``Left`` and ``Right`` shift operators. # They correspond to the modular arithmetic operations :math:`+1` or :math:`-1` respectively [#sparse]_. def shift_op(s_wires, shift="Left"): @@ -272,10 +276,10 @@ def UB(wires_i, wires_j): @qml.qnode(dev) def complete_circuit(thetas): - HN(wires_i) # hadamard transform over |i> register + HN(wires_i) UA(thetas, wires_i, ancilla_wires) UB(wires_i, wires_j) - HN(wires_i) # hadamard transform over |i> register + HN(wires_i) return qml.state() s = 4 # normalization constant @@ -285,8 +289,8 @@ def complete_circuit(thetas): print(qml.draw_mpl(complete_circuit, style='pennylane')(thetas), "\n") ############################################################################## -# We compute the matrix representation of the circuit and print its top-left block to compare it -# with the original matrix. +# Finally, we compute the matrix representation of the circuit and print its top-left block to +# compare it with the original matrix. print("BlockEncoded Mat:") wire_order = ancilla_wires + wires_i[::-1] + wires_j[::-1] @@ -295,18 +299,18 @@ def complete_circuit(thetas): ############################################################################## # You can confirm that the circuit block encodes the original sparse matrix defined above. -# Note that if we wanted to increase the dimension of A (for example 16 x 16), then we need -# only to add more wires to the "j" register in the device and :code:`UB`. +# Note that if we wanted to increase the dimension of A (for example :math:`16 \times 16`), then we +# need only to add more wires to the ``j`` register in the device and :code:`UB`. # # Conclusion # ----------------------- # Block encoding is a powerful technique in quantum computing that allows us to implement a # non-unitary operation in a quantum circuit by embedding the operation in a larger unitary gate. -# In this demo, we reviewed two important block encoding methods with code examples using PennyLane. -# The block encoding functionality provided in PennyLane allows you to explore and benchmark several -# block encoding approaches for a desired problem. The efficiency of the block encoding methods -# typically depends on the sparsity and structure of the original matrix. We hope that you can use -# these tips and tricks to find a more efficient block encoding for your matrix! +# In this tutorial, we reviewed two important block encoding methods with code examples using +# PennyLane. This allows you to use PennyLane explore and benchmark several block encoding +# approaches for a desired problem. The efficiency of the block encoding methods typically depends +# on the sparsity and structure of the original matrix. We hope that you can use these tips and +# tricks to find a more efficient block encoding for your matrix! # # References # ---------- From 7fcf79342780da5d1d467603a9587f69fda0507e Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Mon, 13 Nov 2023 10:54:28 -0500 Subject: [PATCH 42/61] Update demonstrations/tutorial_block_encoding.py --- demonstrations/tutorial_block_encoding.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 19ca20cc03..5d592f3bc2 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -82,7 +82,7 @@ # # The :code:`"ancilla"` register will always contain a single qubit, this is the target where we # apply the rotation gates. The :code:`"wires_i"` and :code:`"wires_j"` registers are the same size -# and need to be able to encode :math:`A` itself, so they will both have :math:`4` qubits for our +# and need to be able to encode :math:`A` itself, so they will both have :math:`2` qubits for our # matrix. ancilla_wire = "ancilla" From 6883b07454a7aa10d3d828931c8cab9b55dd0e30 Mon Sep 17 00:00:00 2001 From: soranjh Date: Mon, 13 Nov 2023 11:32:28 -0500 Subject: [PATCH 43/61] add small corrections --- demonstrations/tutorial_block_encoding.py | 42 +++++++++++------------ 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 19ca20cc03..6160195404 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -13,7 +13,7 @@ *Author: Jay Soni, Diego Guala, Soran Jahangiri — Posted: September 29, 2023.* Prominent quantum algorithms such as quantum phase estimation and quantum singular value -transformation sometimes use **non-unitary** matrices inside quantum circuits. This is problematic +transformation sometimes need to use **non-unitary** matrices inside quantum circuits. This is problematic because quantum computers can only perform unitary evolutions. 🔥 Block encoding is a technique that solves this problem by embedding a non-unitary operator as a sub-block of a larger unitary matrix. 🧯 @@ -23,7 +23,7 @@ (LCU) decompositions. In this tutorial we explore another general block encoding method that can be very efficient for sparse and structured matrices. -Circuits with matrix access oracles [[#fable]_, [#sparse]_] can block encode an arbitrary matrix +Circuits with matrix access oracles [#fable, #sparse]_ can block encode an arbitrary matrix :math:`A`. These circuits can be constructed as shown in the figure below. .. figure:: ../demonstrations/block_encoding/general_circuit.png @@ -45,12 +45,12 @@ The FABLE circuit is constructed from a set of rotation and C-NOT gates. The rotation angles, :math:`(\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements of -the block-encoded matrix +the block-encoded matrix. .. math:: \begin{pmatrix} \theta_1 \\ \cdots \\ \theta_n \end{pmatrix} = M \begin{pmatrix} \alpha_1 \\ \cdots \\ \alpha_n \end{pmatrix}, -where the angles :math:`\alpha` are obtained from the matrix elements of the matrix :math:`A` as +The angles :math:`\alpha` are obtained from the matrix elements of the matrix :math:`A` as :math:`\alpha_1 = \text{arccos}(A_{00}), ...,` and :math:`M` is the transformation matrix that can be obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta()` function. @@ -68,33 +68,32 @@ [ 0.99675093, 0.99675093, 0.83514837, 0.83514837]]) ############################################################################## -# We compute the rotation angles. +# We also compute the rotation angles. -alphas = 2 * np.arccos(A).flatten() +alphas = np.arccos(A).flatten() thetas = compute_theta(alphas) -code = gray_code(2*np.sqrt(len(A))) -n_selections = len(code) - ############################################################################## # The next step is to identify and prepare the qubit registers used in the oracle access framework. -# There are three registers :code:`("ancilla", "wires_i", "wires_j")`: -# -# The :code:`"ancilla"` register will always contain a single qubit, this is the target where we +# There are three registers :code:`"ancilla"`, :code:`"wires_i"`, :code:`"wires_j"`. The +# :code:`"ancilla"` register will always contain a single qubit, this is the target where we # apply the rotation gates. The :code:`"wires_i"` and :code:`"wires_j"` registers are the same size -# and need to be able to encode :math:`A` itself, so they will both have :math:`4` qubits for our +# and need to be able to encode :math:`A` itself, so they will both have :math:`2` qubits for our # matrix. ancilla_wire = "ancilla" -s = int(np.log2(A.shape[0])) # number of qubits needed to encode A -wires_i = [f"i{index}" for index in range(s)] # depend on the size of A +s = int(np.log2(A.shape[0])) +wires_i = [f"i{index}" for index in range(s)] wires_j = [f"j{index}" for index in range(s)] ############################################################################## # Finally, we obtain the control wires for the C-NOT gates and a wire map that we later use to # translate the :code:`control_wires` into the wire registers we prepared. +code = gray_code(2*np.sqrt(len(A))) +n_selections = len(code) + control_wires = [int(np.log2(int(code[i], 2) ^ int(code[(i + 1) % n_selections], 2))) for i in range(n_selections)] @@ -107,7 +106,7 @@ def UA(thetas, control_wires, ancilla): for theta, control_index in zip(thetas, control_wires): - qml.RY(theta, wires=ancilla) + qml.RY(2 * theta, wires=ancilla) qml.CNOT(wires=[wire_map[control_index], ancilla]) @@ -145,8 +144,8 @@ def circuit(): ############################################################################## # You can easily confirm that the circuit block encodes the original matrix defined above. Note that -# the dimension of :math:`A` should be :math:`2^n, n = 1, 2, 3, ...`. For matrices with an arbitrary -# size, we can add zeros to reach the correct dimension. +# the dimension of :math:`A` should be :math:`2^n` where :math:`n` is an integer. For matrices with +# an arbitrary size, we can add zeros to reach the correct dimension. # # The interesting point about the FABLE method is that we can eliminate those rotation gates that # have an angle smaller than a defined threshold. This leaves a sequence of C-NOT gates that in @@ -165,8 +164,9 @@ def UA(thetas, control_wires, ancilla): qml.draw_mpl(circuit, style='pennylane')() ############################################################################## -# Compressing the circuit by removing some of the rotations is an approximation. We can now see how -# good this approximation is in the case of our example. +# Compressing the circuit by removing some of the rotations is an approximation. We can now remove +# the C-NOT gates that cancel each other out and see how good this approximation is in the case +# of our example. def UA(thetas, control_wires, ancilla): nots=[] @@ -307,7 +307,7 @@ def complete_circuit(thetas): # Block encoding is a powerful technique in quantum computing that allows us to implement a # non-unitary operation in a quantum circuit by embedding the operation in a larger unitary gate. # In this tutorial, we reviewed two important block encoding methods with code examples using -# PennyLane. This allows you to use PennyLane explore and benchmark several block encoding +# PennyLane. This allows you to use PennyLane to explore and benchmark several block encoding # approaches for a desired problem. The efficiency of the block encoding methods typically depends # on the sparsity and structure of the original matrix. We hope that you can use these tips and # tricks to find a more efficient block encoding for your matrix! From efe409af159dd87725eeb19d88e0a720d7c04700 Mon Sep 17 00:00:00 2001 From: soranjh Date: Mon, 13 Nov 2023 11:57:59 -0500 Subject: [PATCH 44/61] add small corrections --- demonstrations/tutorial_block_encoding.py | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 6160195404..e38e58461c 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -23,8 +23,8 @@ (LCU) decompositions. In this tutorial we explore another general block encoding method that can be very efficient for sparse and structured matrices. -Circuits with matrix access oracles [#fable, #sparse]_ can block encode an arbitrary matrix -:math:`A`. These circuits can be constructed as shown in the figure below. +Circuits with matrix access oracles, [#fable]_ [#sparse]_, can block encode an arbitrary +matrix :math:`A`. These circuits can be constructed as shown in the figure below. .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% @@ -138,7 +138,7 @@ def circuit(): # compare it with the original matrix. print(f"Original matrix:\n{A}", "\n") -wire_order = [ancilla_wire] + wires_i[::-1] + wires_j[::-1] +wire_order = [ancilla_wire] + wires_i[::-1] + wires_j[::-1] M = len(A) * qml.matrix(circuit, wire_order=wire_order)().real[0:len(A),0:len(A)] print(f"Block-encoded matrix:\n{M}", "\n") @@ -157,8 +157,8 @@ def circuit(): def UA(thetas, control_wires, ancilla): for theta, control_index in zip(thetas, control_wires): - if abs(theta)>tolerance: - qml.RY(theta, wires=ancilla) + if abs(2 * theta)>tolerance: + qml.RY(2 * theta, wires=ancilla) qml.CNOT(wires=[wire_map[control_index], ancilla]) qml.draw_mpl(circuit, style='pennylane')() @@ -166,15 +166,16 @@ def UA(thetas, control_wires, ancilla): ############################################################################## # Compressing the circuit by removing some of the rotations is an approximation. We can now remove # the C-NOT gates that cancel each other out and see how good this approximation is in the case -# of our example. +# of our example. We will make a small modification to :math:`U_A` so that it removes those +# C-NOT gates that cancel each other out. def UA(thetas, control_wires, ancilla): nots=[] for theta, control_index in zip(thetas, control_wires): - if abs(theta) > tolerance: + if abs(2 * theta) > tolerance: for c_wire in nots: qml.CNOT(wires=[c_wire, ancilla]) - qml.RY(theta,wires=ancilla) + qml.RY(2 * theta,wires=ancilla) nots=[] if (cw := wire_map[control_index]) in nots: del(nots[nots.index(cw)]) @@ -299,8 +300,8 @@ def complete_circuit(thetas): ############################################################################## # You can confirm that the circuit block encodes the original sparse matrix defined above. -# Note that if we wanted to increase the dimension of A (for example :math:`16 \times 16`), then we -# need only to add more wires to the ``j`` register in the device and :code:`UB`. +# Note that if we wanted to increase the dimension of :math:`A` (for example :math:`16 \times 16`), +# then we need only to add more wires to the ``j`` register in the device and in :code:`UB`. # # Conclusion # ----------------------- From f1954072a784efe7d21a592f02a0ed3eb17121cc Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 16 Nov 2023 12:42:43 -0500 Subject: [PATCH 45/61] review comments + new thumbnail --- ...humbnail_Block_Encodings_Matrix_Oracle.png | Bin 0 -> 32823 bytes .../thumbnail_block_encoding.png | Bin 15729 -> 0 bytes ...il_large_Block_Encodings_Matrix_Oracle.png | Bin 0 -> 132798 bytes .../tutorial_block_encoding.metadata.json | 2 +- demonstrations/tutorial_block_encoding.py | 51 +++++++++++++----- 5 files changed, 38 insertions(+), 15 deletions(-) create mode 100644 demonstrations/block_encoding/thumbnail_Block_Encodings_Matrix_Oracle.png delete mode 100644 demonstrations/block_encoding/thumbnail_block_encoding.png create mode 100644 demonstrations/block_encoding/thumbnail_large_Block_Encodings_Matrix_Oracle.png diff --git a/demonstrations/block_encoding/thumbnail_Block_Encodings_Matrix_Oracle.png b/demonstrations/block_encoding/thumbnail_Block_Encodings_Matrix_Oracle.png new file mode 100644 index 0000000000000000000000000000000000000000..e748868689bd3d468e8c5f2ffce1fecb8a8ba30d GIT binary patch literal 32823 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 E2PHKCg#Z8m literal 0 HcmV?d00001 diff --git a/demonstrations/block_encoding/thumbnail_block_encoding.png b/demonstrations/block_encoding/thumbnail_block_encoding.png deleted file mode 100644 index cb15db5dfa1e0d4ec30191e792a3602adb8ce9c2..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 15729 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

@)j0o6H5v0gg})6nzQ?4B@i+Niu4`sDDN?P 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 WYxBiHuO(|Gj_^}1C(BRx-~10|ttolerance: qml.RY(2 * theta, wires=ancilla) - qml.CNOT(wires=[wire_map[control_index], ancilla]) + qml.CNOT(wires=[wire_map[control_index]] + ancilla) qml.draw_mpl(circuit, style='pennylane')() +plt.show() ############################################################################## # Compressing the circuit by removing some of the rotations is an approximation. We can now remove @@ -174,7 +186,7 @@ def UA(thetas, control_wires, ancilla): for theta, control_index in zip(thetas, control_wires): if abs(2 * theta) > tolerance: for c_wire in nots: - qml.CNOT(wires=[c_wire, ancilla]) + qml.CNOT(wires=[c_wire] + ancilla) qml.RY(2 * theta,wires=ancilla) nots=[] if (cw := wire_map[control_index]) in nots: @@ -182,12 +194,13 @@ def UA(thetas, control_wires, ancilla): else: nots.append(wire_map[control_index]) for c_wire in nots: - qml.CNOT([c_wire, ancilla]) + qml.CNOT([c_wire] + ancilla) qml.draw_mpl(circuit, style='pennylane')() +plt.show() print(f"Original matrix:\n{A}", "\n") -wire_order = [ancilla_wire] + wires_i[::-1] + wires_j[::-1] +wire_order = ancilla_wires + wires_i[::-1] + wires_j[::-1] M = len(A) * qml.matrix(circuit,wire_order=wire_order)().real[0:len(A),0:len(A)] print(f"Block-encoded matrix:\n{M}", "\n") @@ -278,22 +291,32 @@ def UB(wires_i, wires_j): @qml.qnode(dev) def complete_circuit(thetas): HN(wires_i) + + qml.Barrier() + UA(thetas, wires_i, ancilla_wires) + + qml.Barrier() + UB(wires_i, wires_j) + + qml.Barrier() + HN(wires_i) - return qml.state() + return qml.probs(wires=ancilla_wires + wires_i) s = 4 # normalization constant thetas = 2 * np.arccos(np.array([alpha - 1, beta, gamma])) print("Quantum Circuit:") -print(qml.draw_mpl(complete_circuit, style='pennylane')(thetas), "\n") +qml.draw_mpl(complete_circuit, style='pennylane')(thetas) +plt.show() ############################################################################## # Finally, we compute the matrix representation of the circuit and print its top-left block to # compare it with the original matrix. -print("BlockEncoded Mat:") +print("\nBlockEncoded Mat:") wire_order = ancilla_wires + wires_i[::-1] + wires_j[::-1] mat = qml.matrix(complete_circuit, wire_order=wire_order)(thetas).real[:len(A), :len(A)] * s print(mat, "\n") From cc1fa9e4da4166c7ffd2bc7f290734fb46c33e00 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 16 Nov 2023 13:44:31 -0500 Subject: [PATCH 46/61] missed rst file --- demos_quantum-computing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demos_quantum-computing.rst b/demos_quantum-computing.rst index ba4f8941ef..360fca83e8 100644 --- a/demos_quantum-computing.rst +++ b/demos_quantum-computing.rst @@ -182,7 +182,7 @@ such as benchmarking and characterizing quantum processors. .. gallery-item:: :tooltip: Block Encoding - :figure: demonstrations/block_encoding/thumbnail_block_encoding.png + :figure: demonstrations/block_encoding/thumbnail_Block_Encodings_Matrix_Oracle.png :description: :doc:`demos/tutorial_block_encoding` :tags: quantumcomputing qsvt optimization From 047a229d2cda6144e655e6efd7e5405a2ae00306 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 16 Nov 2023 15:29:21 -0500 Subject: [PATCH 47/61] code review comments --- demonstrations/tutorial_block_encoding.py | 51 ++++++++++++++++++----- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 94419eba0d..e2df18f77d 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -26,15 +26,44 @@ Circuits with matrix access oracles, [#fable]_ [#sparse]_, can block encode an arbitrary matrix :math:`A`. These circuits can be constructed as shown in the figure below. +Circuits with matrix access oracles +----------------------------------- +A general circuit for block encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N x N}` with :math:`N = 2^{n}` +can be constructed as shown in the figure below, if we have access to the oracles :math:`U_A` and :math:`U_B`: + .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% :align: center -The :math:`U_A` and :math:`U_B` operations are oracles which provide access to the elements of the -matrix we wish to block encode and the :math:`H^{\otimes n}` operation is a Hadamard transformation -on :math:`n` qubits. Finding the optimal sequence of the quantum gates that implement :math:`U_A` -and :math:`U_B` is not always trivial. We now explore two approaches for constructing these oracles -that can be very efficient for matrices with specific sparsity and structure. +Where the :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The +:math:`U_A` and :math:`U_B` operations are oracles which accomplish a specific task, their form +depends on the matrix we wish to block encode. In order to define them, we first need a function +which relates the column indices and row indicies for the non-zero entries of :math:`A`, this +function improves the efficiency of this algorithm when working with very sparse matrices. + +Let :math:`b(i,j)` be a function such that it takes a column index (:math:`j`) and returns the +row index for the :math:`i^{th}` non-zero entry in that column of :math:`A`. Note, if :math:`A` +is treated as completely dense (no non-zero entries), this function simply returns :math:`i`. +We use this to define :math:`U_A` and :math:`U_B`: + +The :math:`U_A` oracle is responsible for encoding the matrix entries of :math:`A` into the +amplitude of an auxillary qubit :math:`|0\rangle_{\text{aux}}`: + +.. math:: + + |0\range_{\text{aux}} \ \rightarrow \ A_{i,j}|0\rangle_{\text{aux}} + \sqrt{1 - A_{i,j}^2}|1\rangle_{\text{aux}} \ \equiv \ |A_{i,j}\rangle_{\text{aux}} \\ + U_A |0\rangle_{\text{aux}} |i\rangle |j\rangle \ = \ A_{i,b(i,j)}\rangle_{\text{aux}} |i\rangle |j\rangle + +:math:`U_A`, in the most general case, can be constructed from a sequence of uniformly controlled +rotation gates with rotation angles computed as :math:`\theta = \text{arccos}(a_{ij})`. The +:math:`U_B` oracle is responsible for implmenting the :math:`b(i,j)` function over two sets +of qubits: + +.. math:: U_B |i\rangle|j\rangle \ = \ |i\rangle |b(i,j)\rangle + +Finding an optimal quantum gate decomposition that implements :math:`U_A` and :math:`U_B` is not +always possible. We now explore two approaches for the construction of these oracles that can be +very efficient for matrices with specific sparsity and structure. Block encoding with FABLE ------------------------- @@ -77,10 +106,10 @@ ############################################################################## # The next step is to identify and prepare the qubit registers used in the oracle access framework. # There are three registers :code:`"ancilla"`, :code:`"wires_i"`, :code:`"wires_j"`. The -# :code:`"ancilla"` register will always contain a single qubit, this is the target where we -# apply the rotation gates. The :code:`"wires_i"` and :code:`"wires_j"` registers are the same size -# and need to be able to encode :math:`A` itself, so they will both have :math:`2` qubits for our -# matrix. +# :code:`"ancilla"` register will always contain a single qubit, this is the auxillary qubit where we +# apply the rotation gates methioned above. The :code:`"wires_i"` and :code:`"wires_j"` registers are +# the same size and need to be able to encode :math:`A` itself, so they will both have :math:`2` qubits +# for our matrix. ancilla_wires = ["ancilla"] @@ -102,8 +131,8 @@ ############################################################################## # We now construct the :math:`U_A` and :math:`U_B` oracles as well as the operator representing the -# tensor product of Hadamard gates. Note that :math:`U_B` in FABLE is constructed as a set of SWAP -# gates. +# tensor product of Hadamard gates. Note in the case where we have no non-zero elements in the matrix +# then :math:`U_B` in FABLE is constructed as a set of SWAP gates. We invite you to think about why this is so. def UA(thetas, control_wires, ancilla): for theta, control_index in zip(thetas, control_wires): From 564b311148767b7134374f3f8609157c41a9ec20 Mon Sep 17 00:00:00 2001 From: KetpuntoG <65235481+KetpuntoG@users.noreply.github.com> Date: Thu, 16 Nov 2023 15:40:43 -0500 Subject: [PATCH 48/61] changing large thumbnail path --- ...humbnail_large_Block_Encodings_Matrix_Oracle.png | Bin .../tutorial_block_encoding.metadata.json | 4 ++++ demonstrations/tutorial_block_encoding.py | 8 -------- 3 files changed, 4 insertions(+), 8 deletions(-) rename {demonstrations/block_encoding => _static/large_demo_thumbnails}/thumbnail_large_Block_Encodings_Matrix_Oracle.png (100%) diff --git a/demonstrations/block_encoding/thumbnail_large_Block_Encodings_Matrix_Oracle.png b/_static/large_demo_thumbnails/thumbnail_large_Block_Encodings_Matrix_Oracle.png similarity index 100% rename from demonstrations/block_encoding/thumbnail_large_Block_Encodings_Matrix_Oracle.png rename to _static/large_demo_thumbnails/thumbnail_large_Block_Encodings_Matrix_Oracle.png diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index 098fe64da3..16ffa2aee9 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -22,6 +22,10 @@ { "type": "thumbnail", "uri": "/_images/thumbnail_Block_Encodings_Matrix_Oracle.png" + }, + { + "type": "large_thumbnail", + "uri": "/_static/large_demo_thumbnails/thumbnail_large_Block_Encodings_Matrix_Oracle.png" } ], "seoDescription": "Learn about methods to achieve block-encoding for a given matrix.", diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index e2df18f77d..1de86d0ece 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -3,14 +3,6 @@ Block encoding with matrix access oracles ========================================= -.. meta:: - :property="og:description": Learn how to perform block encoding - :property="og:image": https://pennylane.ai/qml/_images/thumbnail_Block_Encodings_Matrix_Oracle.png - -.. related:: - tutorial_intro_qsvt Intro to QSVT - -*Author: Jay Soni, Diego Guala, Soran Jahangiri — Posted: September 29, 2023.* Prominent quantum algorithms such as quantum phase estimation and quantum singular value transformation sometimes need to use **non-unitary** matrices inside quantum circuits. This is problematic From 3e04701c3439f083c69ecca98bac705caa539447 Mon Sep 17 00:00:00 2001 From: KetpuntoG <65235481+KetpuntoG@users.noreply.github.com> Date: Thu, 16 Nov 2023 15:42:33 -0500 Subject: [PATCH 49/61] empty commit to redeploy --- demonstrations/tutorial_block_encoding.metadata.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index 16ffa2aee9..c23689aac4 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -24,7 +24,7 @@ "uri": "/_images/thumbnail_Block_Encodings_Matrix_Oracle.png" }, { - "type": "large_thumbnail", + "type": "large_thumbnail", "uri": "/_static/large_demo_thumbnails/thumbnail_large_Block_Encodings_Matrix_Oracle.png" } ], From aadd90e2ddd7bfa4b5ffb9ac11bdc82b9cdce381 Mon Sep 17 00:00:00 2001 From: KetpuntoG <65235481+KetpuntoG@users.noreply.github.com> Date: Fri, 17 Nov 2023 09:26:44 -0500 Subject: [PATCH 50/61] smalls modifications --- .../tutorial_block_encoding.metadata.json | 6 ++-- demonstrations/tutorial_block_encoding.py | 29 ++++++++++++------- 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index c23689aac4..b99700bd9b 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -11,8 +11,8 @@ "id": "diego_guala" } ], - "dateOfPublication": "2023-10-04T00:00:00+00:00", - "dateOfLastModification": "2023-10-04T00:00:00+00:00", + "dateOfPublication": "2023-11-28T00:00:00+00:00", + "dateOfLastModification": "2023-11-28T00:00:00+00:00", "categories": [ "Quantum Computing", "Algorithms" @@ -24,7 +24,7 @@ "uri": "/_images/thumbnail_Block_Encodings_Matrix_Oracle.png" }, { - "type": "large_thumbnail", + "type": "large_thumbnail", "uri": "/_static/large_demo_thumbnails/thumbnail_large_Block_Encodings_Matrix_Oracle.png" } ], diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 1de86d0ece..4c798240f5 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -13,15 +13,18 @@ In previous demos we have discussed methods for `simulator-friendly `_ encodings and block encodings using `linear combination of unitaries `_ (LCU) decompositions. In this tutorial we explore another general block encoding method that can be -very efficient for sparse and structured matrices. +very efficient for sparse and structured matrices: block encoding with matrix access oracles. + +.. figure:: ../demonstrations/block_encoding/thumbnail_Block_Encodings_Matrix_Oracle.png + :align: center + :width: 50% + :target: javascript:void(0) -Circuits with matrix access oracles, [#fable]_ [#sparse]_, can block encode an arbitrary -matrix :math:`A`. These circuits can be constructed as shown in the figure below. Circuits with matrix access oracles ----------------------------------- -A general circuit for block encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N x N}` with :math:`N = 2^{n}` -can be constructed as shown in the figure below, if we have access to the oracles :math:`U_A` and :math:`U_B`: +A general circuit for block encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N \times N}` with :math:`N = 2^{n}` +can be constructed as shown in the figure below, if we have access to the oracles :math:`U_A` and :math:`U_B` [#fable]_ [#sparse]_: .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% @@ -33,7 +36,7 @@ which relates the column indices and row indicies for the non-zero entries of :math:`A`, this function improves the efficiency of this algorithm when working with very sparse matrices. -Let :math:`b(i,j)` be a function such that it takes a column index (:math:`j`) and returns the +Let :math:`b(i,j)` be a function such that it takes a column index :math:`j` and returns the row index for the :math:`i^{th}` non-zero entry in that column of :math:`A`. Note, if :math:`A` is treated as completely dense (no non-zero entries), this function simply returns :math:`i`. We use this to define :math:`U_A` and :math:`U_B`: @@ -41,10 +44,15 @@ The :math:`U_A` oracle is responsible for encoding the matrix entries of :math:`A` into the amplitude of an auxillary qubit :math:`|0\rangle_{\text{aux}}`: -.. math:: - - |0\range_{\text{aux}} \ \rightarrow \ A_{i,j}|0\rangle_{\text{aux}} + \sqrt{1 - A_{i,j}^2}|1\rangle_{\text{aux}} \ \equiv \ |A_{i,j}\rangle_{\text{aux}} \\ - U_A |0\rangle_{\text{aux}} |i\rangle |j\rangle \ = \ A_{i,b(i,j)}\rangle_{\text{aux}} |i\rangle |j\rangle +.. math:: + + U_A |0\rangle_{\text{aux}} |i\rangle |j\rangle = A_{i,b(i,j)}\rangle_{\text{aux}} |i\rangle |j\rangle, + +where + +.. math:: + + |A_{i,j}\rangle_{\text{aux}} \equiv A_{i,j}|0\rangle_{\text{aux}} + \sqrt{1 - A_{i,j}^2}|1\rangle_{\text{aux}}. :math:`U_A`, in the most general case, can be constructed from a sequence of uniformly controlled rotation gates with rotation angles computed as :math:`\theta = \text{arccos}(a_{ij})`. The @@ -329,7 +337,6 @@ def complete_circuit(thetas): s = 4 # normalization constant thetas = 2 * np.arccos(np.array([alpha - 1, beta, gamma])) -print("Quantum Circuit:") qml.draw_mpl(complete_circuit, style='pennylane')(thetas) plt.show() From 761f663211847f28242be1bda461ade625742c18 Mon Sep 17 00:00:00 2001 From: KetpuntoG <65235481+KetpuntoG@users.noreply.github.com> Date: Fri, 17 Nov 2023 09:47:34 -0500 Subject: [PATCH 51/61] Update tutorial_block_encoding.py --- demonstrations/tutorial_block_encoding.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 4c798240f5..e137b2893a 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -46,7 +46,7 @@ .. math:: - U_A |0\rangle_{\text{aux}} |i\rangle |j\rangle = A_{i,b(i,j)}\rangle_{\text{aux}} |i\rangle |j\rangle, + U_A |0\rangle_{\text{aux}} |i\rangle |j\rangle = |A_{i,b(i,j)}\rangle_{\text{aux}} |i\rangle |j\rangle, where From c38619d69f559aad6c71dd22c9485edb0f2fadb3 Mon Sep 17 00:00:00 2001 From: KetpuntoG <65235481+KetpuntoG@users.noreply.github.com> Date: Fri, 17 Nov 2023 10:22:20 -0500 Subject: [PATCH 52/61] update related demos --- demonstrations/tutorial_block_encoding.metadata.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index b99700bd9b..6b99ff936f 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -56,7 +56,12 @@ "relatedContent": [ { "type": "demonstration", - "id": "tutorial_block_encoding", + "id": "tutorial_lcu_blockencoding", + "weight": 1.0 + }, + { + "type": "demonstration", + "id": "tutorial_intro_qsvt", "weight": 1.0 } ] From 988564b0a24547501868890c456e6ba8e2750006 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Fri, 17 Nov 2023 15:41:27 -0500 Subject: [PATCH 53/61] remove theory --- demonstrations/tutorial_block_encoding.py | 38 +++-------------------- 1 file changed, 5 insertions(+), 33 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index e137b2893a..4cab9bd093 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -20,11 +20,9 @@ :width: 50% :target: javascript:void(0) - -Circuits with matrix access oracles ------------------------------------ -A general circuit for block encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N \times N}` with :math:`N = 2^{n}` -can be constructed as shown in the figure below, if we have access to the oracles :math:`U_A` and :math:`U_B` [#fable]_ [#sparse]_: +A general circuit for block encoding an arbitrary matrix :math:`A \in \mathbb{C}^{N \times N}` with +:math:`N = 2^{n}` can be constructed as shown in the figure below, if we have access to the oracles +:math:`U_A` and :math:`U_B`: .. figure:: ../demonstrations/block_encoding/general_circuit.png :width: 50% @@ -32,34 +30,8 @@ Where the :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The :math:`U_A` and :math:`U_B` operations are oracles which accomplish a specific task, their form -depends on the matrix we wish to block encode. In order to define them, we first need a function -which relates the column indices and row indicies for the non-zero entries of :math:`A`, this -function improves the efficiency of this algorithm when working with very sparse matrices. - -Let :math:`b(i,j)` be a function such that it takes a column index :math:`j` and returns the -row index for the :math:`i^{th}` non-zero entry in that column of :math:`A`. Note, if :math:`A` -is treated as completely dense (no non-zero entries), this function simply returns :math:`i`. -We use this to define :math:`U_A` and :math:`U_B`: - -The :math:`U_A` oracle is responsible for encoding the matrix entries of :math:`A` into the -amplitude of an auxillary qubit :math:`|0\rangle_{\text{aux}}`: - -.. math:: - - U_A |0\rangle_{\text{aux}} |i\rangle |j\rangle = |A_{i,b(i,j)}\rangle_{\text{aux}} |i\rangle |j\rangle, - -where - -.. math:: - - |A_{i,j}\rangle_{\text{aux}} \equiv A_{i,j}|0\rangle_{\text{aux}} + \sqrt{1 - A_{i,j}^2}|1\rangle_{\text{aux}}. - -:math:`U_A`, in the most general case, can be constructed from a sequence of uniformly controlled -rotation gates with rotation angles computed as :math:`\theta = \text{arccos}(a_{ij})`. The -:math:`U_B` oracle is responsible for implmenting the :math:`b(i,j)` function over two sets -of qubits: - -.. math:: U_B |i\rangle|j\rangle \ = \ |i\rangle |b(i,j)\rangle +depends on the matrix we wish to block encode. See ([#fable]_, [#sparse]_) for an explanation +on the action of these oracles. Finding an optimal quantum gate decomposition that implements :math:`U_A` and :math:`U_B` is not always possible. We now explore two approaches for the construction of these oracles that can be From a57dc3a137ccc33a309debbb43f0ba910de90b85 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Tue, 21 Nov 2023 14:32:31 -0500 Subject: [PATCH 54/61] add theory --- demonstrations/tutorial_block_encoding.py | 55 ++++++++++++++++++++++- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 4cab9bd093..66026581d6 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -33,6 +33,11 @@ depends on the matrix we wish to block encode. See ([#fable]_, [#sparse]_) for an explanation on the action of these oracles. +Where the :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The +:math:`U_A` operation is an oracle which encodes the matrix element :math:`A_{i,j}` into the the +amplitude of the ancilla qubit. The :math:`U_B` oracle ensures that we iterate over every +combination of :math:`(i,j)`. + Finding an optimal quantum gate decomposition that implements :math:`U_A` and :math:`U_B` is not always possible. We now explore two approaches for the construction of these oracles that can be very efficient for matrices with specific sparsity and structure. @@ -44,6 +49,26 @@ resulting circuit. For matrices with specific structures, FABLE provides an efficient circuit without reducing accuracy. +First we define :math:`U_A` and :math:`U_B`. The :math:`U_A` oracle is responsible for encoding the +matrix entries of :math:`A` into the amplitude of an auxillary qubit :math:`|0\rangle_{\text{anc}}`: + +.. math:: + + U_A |0\rangle_{\text{anc}} |i\rangle |j\rangle = |A_{i,j}\rangle_{\text{anc}} |i\rangle |j\rangle, + +where + +.. math:: + + |A_{i,j}\rangle_{\text{anc}} \equiv A_{i,j}|0\rangle_{\text{anc}} + \sqrt{1 - |A_{i,j}|^2}|1\rangle_{\text{anc}}. + +:math:`U_A`, in the most general case, can be constructed from a sequence of uniformly controlled +rotation gates with rotation angles computed as :math:`\theta = \text{arccos}(A_{i,j})`. The +:math:`U_B` oracle is responsible for ensuring proper indexing of each entry in :math:`A` and for +this case simplifies to be the :math:`SWAP` gate: + +.. math:: U_B |i\rangle|j\rangle \ = \ |j\rangle |i\rangle + The FABLE circuit is constructed from a set of rotation and C-NOT gates. The rotation angles, :math:`(\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements of the block-encoded matrix. @@ -216,9 +241,35 @@ def UA(thetas, control_wires, ancilla): # The quantum circuit for the oracle :math:`U_A`, presented above, accesses every entry of # :math:`A` and thus requires :math:`~ O(N^2)` gates to implement the oracle [#fable]_. In the # special cases where :math:`A` is structured and sparse, we can generate a more efficient quantum -# circuit representation for :math:`U_A` and :math:`U_B` [#sparse]_. Let's look at an example. +# circuit representation for :math:`U_A` and :math:`U_B` [#sparse]_. In order to define them, we +# first need a function which relates the column indices and row indicies for the non-zero entries +# of :math:`A`, this function improves the efficiency of this algorithm when working with very +# sparse matrices. +# +# Let :math:`b(i,j)` be a function such that it takes a column index :math:`j` and returns the +# row index for the :math:`i^{th}` non-zero entry in that column of :math:`A`. Note, if :math:`A` +# is treated as completely dense (no non-zero entries), this function simply returns :math:`i`. +# We use this to define :math:`U_A` and :math:`U_B`: +# +# The :math:`U_A` oracle is responsible for encoding the matrix entries of :math:`A` into the +# amplitude of an ancilla qubit :math:`|0\rangle_{\text{anc}}`: +# +# .. math:: +# +# U_A |0\rangle_{\text{anc}} |i\rangle |j\rangle = |A_{i,b(i,j)}\rangle_{\text{anc}} |i\rangle |j\rangle, +# +# where +# +# .. math:: +# +# |A_{i,j}\rangle_{\text{anc}} \equiv A_{i,j}|0\rangle_{\text{anc}} + \sqrt{1 - A_{i,j}^2}|1\rangle_{\text{anc}}. +# +# In this case the :math:`U_B` oracle is responsible for implmenting the :math:`b(i,j)` function +# over two sets of qubits: +# +# .. math:: U_B |i\rangle|j\rangle \ = \ |i\rangle |b(i,j)\rangle # -# Consider the sparse matrix given by: +# Lets work through an example. Consider the sparse matrix given by: # # .. math:: A = \begin{bmatrix} # \alpha & \gamma & 0 & \dots & \beta\\ From 682d80a36ffa21c2cf4497a4904337c703ae462e Mon Sep 17 00:00:00 2001 From: Diego Date: Tue, 21 Nov 2023 14:47:30 -0500 Subject: [PATCH 55/61] add anc to image --- .../block_encoding/general_circuit.png | Bin 15729 -> 12520 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/demonstrations/block_encoding/general_circuit.png b/demonstrations/block_encoding/general_circuit.png index cb15db5dfa1e0d4ec30191e792a3602adb8ce9c2..128d9c585bf7b19257cd79bf8b3bb08381b19f28 100644 GIT binary patch delta 10094 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 From b7686fcf49e27c6d15e6c232c05b031dd5addc92 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 23 Nov 2023 16:08:37 -0500 Subject: [PATCH 56/61] clean up explanation --- demonstrations/tutorial_block_encoding.py | 82 +++++++++++------------ 1 file changed, 40 insertions(+), 42 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 66026581d6..f4b6cc8916 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -6,13 +6,13 @@ Prominent quantum algorithms such as quantum phase estimation and quantum singular value transformation sometimes need to use **non-unitary** matrices inside quantum circuits. This is problematic -because quantum computers can only perform unitary evolutions. 🔥 Block encoding is a technique +because quantum computers can only perform unitary evolutions 🔥. Block encoding is a technique that solves this problem by embedding a non-unitary operator as a sub-block of a larger unitary -matrix. 🧯 +matrix 🧯. In previous demos we have discussed methods for `simulator-friendly `_ encodings and block encodings using `linear combination of unitaries `_ -(LCU) decompositions. In this tutorial we explore another general block encoding method that can be +(LCU) decompositions. In this tutorial we explore another general block encoding framework that can be very efficient for sparse and structured matrices: block encoding with matrix access oracles. .. figure:: ../demonstrations/block_encoding/thumbnail_Block_Encodings_Matrix_Oracle.png @@ -28,28 +28,19 @@ :width: 50% :align: center -Where the :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The -:math:`U_A` and :math:`U_B` operations are oracles which accomplish a specific task, their form -depends on the matrix we wish to block encode. See ([#fable]_, [#sparse]_) for an explanation -on the action of these oracles. - Where the :math:`H^{\otimes n}` operation is a Hadamard transformation on :math:`n` qubits. The :math:`U_A` operation is an oracle which encodes the matrix element :math:`A_{i,j}` into the the amplitude of the ancilla qubit. The :math:`U_B` oracle ensures that we iterate over every combination of :math:`(i,j)`. Finding an optimal quantum gate decomposition that implements :math:`U_A` and :math:`U_B` is not -always possible. We now explore two approaches for the construction of these oracles that can be -very efficient for matrices with specific sparsity and structure. - -Block encoding with FABLE -------------------------- -The Fast Approximate BLock Encodings (FABLE) technique is a general method for block encoding dense -and sparse matrices [#fable]_. The level of approximation in FABLE can be adjusted to simplify the -resulting circuit. For matrices with specific structures, FABLE provides an efficient circuit -without reducing accuracy. +always possible. We now explore two different approaches for constructing these oracles that can be +very efficient for matrices with specific structure or sparsity. -First we define :math:`U_A` and :math:`U_B`. The :math:`U_A` oracle is responsible for encoding the +Block encoding structured matricies +----------------------------------- +In order to better understand the oracle access framework let us first define :math:`U_A` and :math:`U_B` +For the exact block-encoding of :math:`A`. The :math:`U_A` oracle is responsible for encoding the matrix entries of :math:`A` into the amplitude of an auxillary qubit :math:`|0\rangle_{\text{anc}}`: .. math:: @@ -62,19 +53,27 @@ |A_{i,j}\rangle_{\text{anc}} \equiv A_{i,j}|0\rangle_{\text{anc}} + \sqrt{1 - |A_{i,j}|^2}|1\rangle_{\text{anc}}. -:math:`U_A`, in the most general case, can be constructed from a sequence of uniformly controlled -rotation gates with rotation angles computed as :math:`\theta = \text{arccos}(A_{i,j})`. The -:math:`U_B` oracle is responsible for ensuring proper indexing of each entry in :math:`A` and for -this case simplifies to be the :math:`SWAP` gate: +The :math:`U_B` oracle is responsible for ensuring proper indexing of each entry in :math:`A` +and for this algorithm, it simplifies to be the :class:`~.pennylane.SWAP` gate: .. math:: U_B |i\rangle|j\rangle \ = \ |j\rangle |i\rangle -The FABLE circuit is constructed from a set of rotation and C-NOT gates. The rotation angles, -:math:`(\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements of -the block-encoded matrix. +The naive approach is to construct :math:`U_A` using a sequence of multi-controlled :math:`Ry(\alpha)` +rotation gates with rotation angles computed as :math:`\alpha = \text{arccos}(A_{i,j})`. It turns out +that this requires :math:`O(N^{4})` gates and is very inefficient. A more efficient approach is a + +The Fast Approximate BLock Encodings (FABLE) technique is a method for block encoding matrices [#fable]_ +using the oracle access framework and some clever approximations 🧠. The level of approximation in FABLE +can be adjusted to simplify the resulting circuit. For matrices with specific structures, FABLE provides an +efficient circuit *without* reducing accuracy. + +The FABLE circuit is constructed from a set of single :math:`Ry` rotation and C-NOT gates. We can remove +the need for multi-controlled rotations using a special transformation of the angles (see [#fable]_ for details). +The rotation angles, :math:`(\theta_1, ..., \theta_n)`, are obtained from a transformation of the elements +of the block-encoded matrix. .. math:: \begin{pmatrix} \theta_1 \\ \cdots \\ \theta_n \end{pmatrix} = - M \begin{pmatrix} \alpha_1 \\ \cdots \\ \alpha_n \end{pmatrix}, + M \begin{pmatrix} \alpha_1 \\ \cdots \\ \alpha_n \end{pmatrix}. The angles :math:`\alpha` are obtained from the matrix elements of the matrix :math:`A` as :math:`\alpha_1 = \text{arccos}(A_{00}), ...,` and :math:`M` is the transformation matrix that can @@ -105,8 +104,8 @@ # There are three registers :code:`"ancilla"`, :code:`"wires_i"`, :code:`"wires_j"`. The # :code:`"ancilla"` register will always contain a single qubit, this is the auxillary qubit where we # apply the rotation gates methioned above. The :code:`"wires_i"` and :code:`"wires_j"` registers are -# the same size and need to be able to encode :math:`A` itself, so they will both have :math:`2` qubits -# for our matrix. +# the same size for this algorithm and need to be able to encode :math:`A` itself, so they will both +# have :math:`2` qubits for our matrix. ancilla_wires = ["ancilla"] @@ -128,8 +127,7 @@ ############################################################################## # We now construct the :math:`U_A` and :math:`U_B` oracles as well as the operator representing the -# tensor product of Hadamard gates. Note in the case where we have no non-zero elements in the matrix -# then :math:`U_B` in FABLE is constructed as a set of SWAP gates. We invite you to think about why this is so. +# tensor product of Hadamard gates. def UA(thetas, control_wires, ancilla): for theta, control_index in zip(thetas, control_wires): @@ -241,31 +239,31 @@ def UA(thetas, control_wires, ancilla): # The quantum circuit for the oracle :math:`U_A`, presented above, accesses every entry of # :math:`A` and thus requires :math:`~ O(N^2)` gates to implement the oracle [#fable]_. In the # special cases where :math:`A` is structured and sparse, we can generate a more efficient quantum -# circuit representation for :math:`U_A` and :math:`U_B` [#sparse]_. In order to define them, we -# first need a function which relates the column indices and row indicies for the non-zero entries -# of :math:`A`, this function improves the efficiency of this algorithm when working with very -# sparse matrices. +# circuit representation for :math:`U_A` and :math:`U_B` [#sparse]_ by only keeping track of the +# non-zero entries of the matrix. # # Let :math:`b(i,j)` be a function such that it takes a column index :math:`j` and returns the -# row index for the :math:`i^{th}` non-zero entry in that column of :math:`A`. Note, if :math:`A` -# is treated as completely dense (no non-zero entries), this function simply returns :math:`i`. -# We use this to define :math:`U_A` and :math:`U_B`: +# row index for the :math:`i^{th}` non-zero entry in that column of :math:`A`. Note, in this +# formulation, the :math:`|i\rangle` qubit register now refers to the number of non-zero entries +# in :math:`A`. For sparse matrices, this can be much smaller than :math:`N`, thus saving us many +# qubits. We use this to define :math:`U_A` and :math:`U_B`. # -# The :math:`U_A` oracle is responsible for encoding the matrix entries of :math:`A` into the -# amplitude of an ancilla qubit :math:`|0\rangle_{\text{anc}}`: +# Like in the structured approach the :math:`U_A` oracle is responsible for encoding the matrix +# entries of :math:`A` into the amplitude of the ancilla qubit. However, we now use :math:`b(i,j)` +# to access the row index of the non-zero entries: # # .. math:: # -# U_A |0\rangle_{\text{anc}} |i\rangle |j\rangle = |A_{i,b(i,j)}\rangle_{\text{anc}} |i\rangle |j\rangle, +# U_A |0\rangle_{\text{anc}} |i\rangle |j\rangle = |A_{b(i,j),j}\rangle_{\text{anc}} |i\rangle |j\rangle, # # where # # .. math:: # -# |A_{i,j}\rangle_{\text{anc}} \equiv A_{i,j}|0\rangle_{\text{anc}} + \sqrt{1 - A_{i,j}^2}|1\rangle_{\text{anc}}. +# |A_{l,j}\rangle_{\text{anc}} \equiv A_{l,j}|0\rangle_{\text{anc}} + \sqrt{1 - A_{l,j}^2}|1\rangle_{\text{anc}}. # # In this case the :math:`U_B` oracle is responsible for implmenting the :math:`b(i,j)` function -# over two sets of qubits: +# and taking us from the column index to the row index in the qubit register: # # .. math:: U_B |i\rangle|j\rangle \ = \ |i\rangle |b(i,j)\rangle # From fa49d61f4ae6d5fc8fc86b24f3a51167eba87ab3 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 23 Nov 2023 17:04:56 -0500 Subject: [PATCH 57/61] Update demonstrations/tutorial_block_encoding.py Co-authored-by: Guillermo Alonso-Linaje <65235481+KetpuntoG@users.noreply.github.com> --- demonstrations/tutorial_block_encoding.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index f4b6cc8916..808bd509b2 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -103,7 +103,7 @@ # The next step is to identify and prepare the qubit registers used in the oracle access framework. # There are three registers :code:`"ancilla"`, :code:`"wires_i"`, :code:`"wires_j"`. The # :code:`"ancilla"` register will always contain a single qubit, this is the auxillary qubit where we -# apply the rotation gates methioned above. The :code:`"wires_i"` and :code:`"wires_j"` registers are +# apply the rotation gates mentioned above. The :code:`"wires_i"` and :code:`"wires_j"` registers are # the same size for this algorithm and need to be able to encode :math:`A` itself, so they will both # have :math:`2` qubits for our matrix. From 54e9d6d34de5049fedc0d34a9d05107070bc4bef Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Thu, 23 Nov 2023 17:06:47 -0500 Subject: [PATCH 58/61] fix sentence --- demonstrations/tutorial_block_encoding.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 808bd509b2..0707627393 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -62,7 +62,7 @@ rotation gates with rotation angles computed as :math:`\alpha = \text{arccos}(A_{i,j})`. It turns out that this requires :math:`O(N^{4})` gates and is very inefficient. A more efficient approach is a -The Fast Approximate BLock Encodings (FABLE) technique is a method for block encoding matrices [#fable]_ +The Fast Approximate BLock Encoding (FABLE) technique is a method for block encoding matrices [#fable]_ using the oracle access framework and some clever approximations 🧠. The level of approximation in FABLE can be adjusted to simplify the resulting circuit. For matrices with specific structures, FABLE provides an efficient circuit *without* reducing accuracy. From 4b305bb293777855cc3bc443208d1f4e9fafce5d Mon Sep 17 00:00:00 2001 From: soranjh <40344468+soranjh@users.noreply.github.com> Date: Fri, 24 Nov 2023 10:42:32 -0500 Subject: [PATCH 59/61] Apply suggestions from code review Co-authored-by: Guillermo Alonso-Linaje <65235481+KetpuntoG@users.noreply.github.com> --- .../tutorial_block_encoding.metadata.json | 6 ++-- demonstrations/tutorial_block_encoding.py | 33 +++++++++---------- 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.metadata.json b/demonstrations/tutorial_block_encoding.metadata.json index 6b99ff936f..2a73717113 100644 --- a/demonstrations/tutorial_block_encoding.metadata.json +++ b/demonstrations/tutorial_block_encoding.metadata.json @@ -1,14 +1,14 @@ { "title": "Block Encodings", "authors": [ - { - "id": "soran_jahangiri" - }, { "id": "jay_soni" }, { "id": "diego_guala" + }, + { + "id": "soran_jahangiri" } ], "dateOfPublication": "2023-11-28T00:00:00+00:00", diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 0707627393..07e14e5e6d 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -37,11 +37,11 @@ always possible. We now explore two different approaches for constructing these oracles that can be very efficient for matrices with specific structure or sparsity. -Block encoding structured matricies +Block encoding structured matrices ----------------------------------- -In order to better understand the oracle access framework let us first define :math:`U_A` and :math:`U_B` -For the exact block-encoding of :math:`A`. The :math:`U_A` oracle is responsible for encoding the -matrix entries of :math:`A` into the amplitude of an auxillary qubit :math:`|0\rangle_{\text{anc}}`: +In order to better understand the oracle access framework, let us first define :math:`U_A` and :math:`U_B` +for the exact block-encoding of :math:`A`. The :math:`U_A` oracle is responsible for encoding the +matrix entries of :math:`A` into the amplitude of an auxilary qubit :math:`|0\rangle_{\text{anc}}`: .. math:: @@ -60,10 +60,9 @@ The naive approach is to construct :math:`U_A` using a sequence of multi-controlled :math:`Ry(\alpha)` rotation gates with rotation angles computed as :math:`\alpha = \text{arccos}(A_{i,j})`. It turns out -that this requires :math:`O(N^{4})` gates and is very inefficient. A more efficient approach is a - -The Fast Approximate BLock Encoding (FABLE) technique is a method for block encoding matrices [#fable]_ -using the oracle access framework and some clever approximations 🧠. The level of approximation in FABLE +that this requires :math:`O(N^{4})` gates and is very inefficient. A more efficient approach is the +Fast Approximate BLock Encodings (FABLE) technique [#fable]_, which +uses the oracle access framework and some clever approximations 🧠. The level of approximation in FABLE can be adjusted to simplify the resulting circuit. For matrices with specific structures, FABLE provides an efficient circuit *without* reducing accuracy. @@ -77,7 +76,7 @@ The angles :math:`\alpha` are obtained from the matrix elements of the matrix :math:`A` as :math:`\alpha_1 = \text{arccos}(A_{00}), ...,` and :math:`M` is the transformation matrix that can -be obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta()` +be obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta` function. Let's now construct the FABLE block encoding circuit for a structured matrix. @@ -102,7 +101,7 @@ ############################################################################## # The next step is to identify and prepare the qubit registers used in the oracle access framework. # There are three registers :code:`"ancilla"`, :code:`"wires_i"`, :code:`"wires_j"`. The -# :code:`"ancilla"` register will always contain a single qubit, this is the auxillary qubit where we +# :code:`"ancilla"` register will always contain a single qubit, this is the auxilary qubit where we # apply the rotation gates mentioned above. The :code:`"wires_i"` and :code:`"wires_j"` registers are # the same size for this algorithm and need to be able to encode :math:`A` itself, so they will both # have :math:`2` qubits for our matrix. @@ -115,7 +114,7 @@ ############################################################################## # Finally, we obtain the control wires for the C-NOT gates and a wire map that we later use to -# translate the :code:`control_wires` into the wire registers we prepared. +# translate the control wires into the wire registers we prepared. code = gray_code(2*np.sqrt(len(A))) n_selections = len(code) @@ -152,7 +151,7 @@ def HN(input_wires): def circuit(): HN(wires_i) - qml.Barrier() # to seperate the sections in the circuit + qml.Barrier() # to separate the sections in the circuit UA(thetas, control_wires, ancilla_wires) @@ -248,7 +247,7 @@ def UA(thetas, control_wires, ancilla): # in :math:`A`. For sparse matrices, this can be much smaller than :math:`N`, thus saving us many # qubits. We use this to define :math:`U_A` and :math:`U_B`. # -# Like in the structured approach the :math:`U_A` oracle is responsible for encoding the matrix +# Like in the structured approach, the :math:`U_A` oracle is responsible for encoding the matrix # entries of :math:`A` into the amplitude of the ancilla qubit. However, we now use :math:`b(i,j)` # to access the row index of the non-zero entries: # @@ -262,12 +261,12 @@ def UA(thetas, control_wires, ancilla): # # |A_{l,j}\rangle_{\text{anc}} \equiv A_{l,j}|0\rangle_{\text{anc}} + \sqrt{1 - A_{l,j}^2}|1\rangle_{\text{anc}}. # -# In this case the :math:`U_B` oracle is responsible for implmenting the :math:`b(i,j)` function +# In this case the :math:`U_B` oracle is responsible for implementing the :math:`b(i,j)` function # and taking us from the column index to the row index in the qubit register: # # .. math:: U_B |i\rangle|j\rangle \ = \ |i\rangle |b(i,j)\rangle # -# Lets work through an example. Consider the sparse matrix given by: +# Let's work through an example. Consider the sparse matrix given by: # # .. math:: A = \begin{bmatrix} # \alpha & \gamma & 0 & \dots & \beta\\ @@ -294,9 +293,9 @@ def UA(thetas, control_wires, ancilla): print(f"Original A:\n{A}", "\n") ############################################################################## -# Once again we identify and prepare the qubit registers used in the oracle access framework: +# Once again we identify and prepare the qubit registers used in the oracle access framework. # -# The :code:`"ancilla"` register will still contain a single qubit, the target where for the +# The :code:`"ancilla"` register will still contain a single qubit, the target for the # controlled rotation gates. The :code:`"wires_i"` register needs to be large enough to binary # encode the maximum number of non-zero entries in any column or row. Given the structure of # :math:`A` defined above, we have at most 3 non-zero entries, thus this register will have 2 From e5c175ba9a3d96a64149fcec3a09a39ffd3c6f50 Mon Sep 17 00:00:00 2001 From: soranjh Date: Fri, 24 Nov 2023 10:47:09 -0500 Subject: [PATCH 60/61] make circuit compact --- demonstrations/tutorial_block_encoding.py | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index 07e14e5e6d..a8dbfdb2e6 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -77,7 +77,7 @@ The angles :math:`\alpha` are obtained from the matrix elements of the matrix :math:`A` as :math:`\alpha_1 = \text{arccos}(A_{00}), ...,` and :math:`M` is the transformation matrix that can be obtained with the :func:`~.pennylane.templates.state_preparations.mottonen.compute_theta` -function. +function of PennyLane. Let's now construct the FABLE block encoding circuit for a structured matrix. """ @@ -150,17 +150,11 @@ def HN(input_wires): @qml.qnode(dev) def circuit(): HN(wires_i) - - qml.Barrier() # to separate the sections in the circuit - + qml.Barrier() # to separate the sections in the circuit UA(thetas, control_wires, ancilla_wires) - qml.Barrier() - UB(wires_i, wires_j) - qml.Barrier() - HN(wires_i) return qml.probs(wires=ancilla_wires + wires_i) @@ -340,17 +334,11 @@ def UB(wires_i, wires_j): @qml.qnode(dev) def complete_circuit(thetas): HN(wires_i) - - qml.Barrier() - + qml.Barrier() # to separate the sections in the circuit UA(thetas, wires_i, ancilla_wires) - qml.Barrier() - UB(wires_i, wires_j) - qml.Barrier() - HN(wires_i) return qml.probs(wires=ancilla_wires + wires_i) From dcb9146d45c77fcec6bef5cb0d89c78bc8145aa4 Mon Sep 17 00:00:00 2001 From: Jay Soni Date: Fri, 24 Nov 2023 15:59:07 -0500 Subject: [PATCH 61/61] Apply suggestions from code review --- demonstrations/tutorial_block_encoding.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/demonstrations/tutorial_block_encoding.py b/demonstrations/tutorial_block_encoding.py index a8dbfdb2e6..d1adc1f9c8 100644 --- a/demonstrations/tutorial_block_encoding.py +++ b/demonstrations/tutorial_block_encoding.py @@ -249,12 +249,6 @@ def UA(thetas, control_wires, ancilla): # # U_A |0\rangle_{\text{anc}} |i\rangle |j\rangle = |A_{b(i,j),j}\rangle_{\text{anc}} |i\rangle |j\rangle, # -# where -# -# .. math:: -# -# |A_{l,j}\rangle_{\text{anc}} \equiv A_{l,j}|0\rangle_{\text{anc}} + \sqrt{1 - A_{l,j}^2}|1\rangle_{\text{anc}}. -# # In this case the :math:`U_B` oracle is responsible for implementing the :math:`b(i,j)` function # and taking us from the column index to the row index in the qubit register: #