From 9a095acc36bf8e6eb41d9914f8e7ce48de495b0f Mon Sep 17 00:00:00 2001 From: mat70593 Date: Wed, 11 Jun 2025 14:51:09 +0200 Subject: [PATCH 01/15] Added LCU tutorial to the appropriate folder, outlining the topics described later on --- documentation/source/general/tutorial/LCU.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 documentation/source/general/tutorial/LCU.rst diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst new file mode 100644 index 000000000..5378cbc8d --- /dev/null +++ b/documentation/source/general/tutorial/LCU.rst @@ -0,0 +1,14 @@ +.. _LCU_tutorial: + +Linear Combination of Unitaries (LCU) primitive and its applications +==================================================================== + + +LCU in theory +------------- + +LCU in Qrisp +------------ + +Trotterization + LCU = LCHS +--------------------------- \ No newline at end of file From 744c7194a40f91c85f91699bf2eb6903c427ca88 Mon Sep 17 00:00:00 2001 From: mat70593 Date: Wed, 11 Jun 2025 16:23:44 +0200 Subject: [PATCH 02/15] First additions to the tutorial, very rough --- documentation/source/conf.py | 3 +- documentation/source/general/tutorial/LCU.rst | 53 +++++++++++++++++++ .../source/general/tutorial/index.rst | 1 + 3 files changed, 56 insertions(+), 1 deletion(-) diff --git a/documentation/source/conf.py b/documentation/source/conf.py index 48ad04b4d..84a4539a7 100644 --- a/documentation/source/conf.py +++ b/documentation/source/conf.py @@ -64,7 +64,8 @@ "sphinx_sitemap", "sphinx_copybutton", "sphinx_design", - "sphinx_thebe" + "sphinx_thebe", + "sphinxcontrib.youtube" #"nb2plots", ] diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index 5378cbc8d..e81986db1 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -3,10 +3,63 @@ Linear Combination of Unitaries (LCU) primitive and its applications ==================================================================== +If you’ve ever wondered how to bend the rules of quantum mechanics (without actually breaking them), you’re in the right place. This tutorial is your roadmap to the Linear Combination of Unitaries (LCU) protocol—a powerful tool that lets you simulate non-unitary operations by cleverly mixing unitaries, opening doors to advanced quantum algorithms and simulations. + +Here’s what you’ll discover as you journey through these pages: + +- We’ll start by demystifying the LCU protocol: why it’s needed, what problems it solves, and how it transforms the impossible into the executable. You’ll learn the core ideas behind representing complex quantum operations as sums of simpler, unitary building blocks. + +- Next, we’ll roll up our sleeves and see how LCU comes alive in Qrisp. This section is hands-on: you’ll explore annotated code examples, understand the structure of Qrisp’s LCU implementation, and see how to prepare ancilla registers, orchestrate controlled unitaries, and interpret the results. Whether you’re a Qrisp novice or a seasoned quantum coder, you’ll pick up practical techniques for integrating LCU into your own projects. + +- The adventure doesn’t stop at LCU! In our final section, we combine the strengths of Trotterization and LCU to unlock the Linear Combination of Hamiltonian Simulation (LCHS) protocol. Here, you’ll learn how to simulate functions of Hamiltonians—like $\cos(H)$. + +If all goes well (if not, let us know about which parts should be elaborated upon further), you'll be motivated to apply LCU and extend it to tackle `Quantum Signal +Processing (QSP) `_, and/or `Quantum Singular Value Transformation (QSVT) `_. Until the implementation in Qrisp, the proof to this is left for the reader (which is not a broad time-window). + +Nothing more to say other than let's go! + LCU in theory ------------- +So, you want to perform operations that aren't strictly allowed by the quantum rulebook? +Enter the Linear Combination of Unitaries (LCU) protocol—a foundational quantum algorithmic primitive that lets you implement a non-unitary operator $A$ by cleverly expressing it as a weighted sum of unitary operators: + +.. math:: + A=\sum_i\alpha_iU_i + +This is the quantum equivalent of ordering a custom pizza: you pick your favorite toppings (unitaries), assign them weights (coefficients), and hope the outcome is deliciously non-classical. + +Core components +^^^^^^^^^^^^^^^ + +The LCU protocol works by embedding your non-unitary operator into a larger, unitary quantum circuit. The magic happens in three acts, known as block encoding: + +- **PREPARE**: Prepares an ancilla quantum variable in a superposition encoding the normalized coefficients $\alpha_i\geq0$ of the target operator + +.. math :: + + \mathrm{PREPARE}|0\rangle=\sum_i\sqrt{\frac{\alpha_i}{\lambda}}|i\rangle + +- **SELECT**: Applies the unitary $U_i$ to the input state $\ket{\psi}$, controlled on the ancilla variable being in state $|i\rangle$. + +.. math :: + + \mathrm{SELECT}|i\rangle|\psi\rangle=|i\rangle U_i|\psi\rangle + +- **PREPARE**$^\dagger$: Applies the inverse prepartion to the ancilla. + +Success condition +^^^^^^^^^^^^^^^^^ + +The LCU protocol is deemed successful only if the ancilla variable is measured in the $\ket{0}$ state, which occurs with a probability proportional to :math:`\frac{\langle\psi|A^{\dagger}A|\psi\rangle}{\lambda^2}` where $\lambda=\sum_i\alpha_i$. +This function does not perform the measurement; it returns the ancilla variable and the transformed target variable. + +The approach you’ve just studied was pioneered by Nathan Wiebe, whose contributions have fundamentally shaped the field of quantum algorithm design, particularly in Hamiltonian simulation and quantum linear systems. + +If you’re eager for more than equations and want intuition delivered with clarity, Nathan Wiebe’s YouTube seminar series is a goldmine. His channel is packed with lucid explanations of quantum primitives and routines, making even the most complex ideas accessible. The video below, authored by Wiebe himself, distills the essence of the LCU protocol and its applications—so whether you’re seeking a first encounter or a deeper understanding, this is a resource not to miss. + +.. youtube:: irMKrOIrHP4 LCU in Qrisp ------------ diff --git a/documentation/source/general/tutorial/index.rst b/documentation/source/general/tutorial/index.rst index 3a86c37a9..d4a1fcfca 100644 --- a/documentation/source/general/tutorial/index.rst +++ b/documentation/source/general/tutorial/index.rst @@ -375,6 +375,7 @@ By the end of this tutorial, you'll have a solid foundation of our high-level fr H2 Jasp HHL + LCU Shor FT_compilation TSP From abcfd6b8c26d7710f58ad3c2f4cebaea14f9b743 Mon Sep 17 00:00:00 2001 From: mat70593 Date: Wed, 11 Jun 2025 20:27:55 +0200 Subject: [PATCH 03/15] Slight changes to the existing material --- documentation/source/general/tutorial/LCU.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index e81986db1..15e05282f 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -5,13 +5,13 @@ Linear Combination of Unitaries (LCU) primitive and its applications If you’ve ever wondered how to bend the rules of quantum mechanics (without actually breaking them), you’re in the right place. This tutorial is your roadmap to the Linear Combination of Unitaries (LCU) protocol—a powerful tool that lets you simulate non-unitary operations by cleverly mixing unitaries, opening doors to advanced quantum algorithms and simulations. -Here’s what you’ll discover as you journey through these pages: +Here’s what you’ll discover as you journey through this tutorial: -- We’ll start by demystifying the LCU protocol: why it’s needed, what problems it solves, and how it transforms the impossible into the executable. You’ll learn the core ideas behind representing complex quantum operations as sums of simpler, unitary building blocks. +- We’ll start by demystifying the LCU protocol: why it’s needed and what problems it solves. You’ll learn the core ideas behind representing complex quantum operations as sums of simpler, unitary building blocks aka block encodings. -- Next, we’ll roll up our sleeves and see how LCU comes alive in Qrisp. This section is hands-on: you’ll explore annotated code examples, understand the structure of Qrisp’s LCU implementation, and see how to prepare ancilla registers, orchestrate controlled unitaries, and interpret the results. Whether you’re a Qrisp novice or a seasoned quantum coder, you’ll pick up practical techniques for integrating LCU into your own projects. +- Next, we’ll roll up our sleeves and see how LCU comes alive in Qrisp (Frankenstein intensifies). This section is hands-on: you’ll explore annotated code examples, understand the structure of Qrisp’s LCU implementation, and see how to prepare ancilla registers, orchestrate controlled unitaries, and interpret the results. -- The adventure doesn’t stop at LCU! In our final section, we combine the strengths of Trotterization and LCU to unlock the Linear Combination of Hamiltonian Simulation (LCHS) protocol. Here, you’ll learn how to simulate functions of Hamiltonians—like $\cos(H)$. +- We won't stop at just understanding LCU, but instead also use it as an algorithmic building block (primitive) to perform another algorithm. In our final section, we combine the strengths of Trotterization and LCU to unlock the Linear Combination of Hamiltonian Simulation (LCHS) protocol. Here, you’ll learn how to simulate functions of Hamiltonians—like $\cos(H)$. If all goes well (if not, let us know about which parts should be elaborated upon further), you'll be motivated to apply LCU and extend it to tackle `Quantum Signal Processing (QSP) `_, and/or `Quantum Singular Value Transformation (QSVT) `_. Until the implementation in Qrisp, the proof to this is left for the reader (which is not a broad time-window). From 0f5fa8f9d8de59bd6fba6f055c235879e40a0adf Mon Sep 17 00:00:00 2001 From: mat70593 Date: Tue, 17 Jun 2025 16:31:32 +0200 Subject: [PATCH 04/15] Added content for the implementation part - some hyperlinks need fixing. Only the LCHS section left --- documentation/source/general/tutorial/LCU.rst | 89 ++++++++++++++++++- 1 file changed, 87 insertions(+), 2 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index 15e05282f..d6434bfd0 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -22,7 +22,8 @@ Nothing more to say other than let's go! LCU in theory ------------- -So, you want to perform operations that aren't strictly allowed by the quantum rulebook? +So, you want to perform operations that aren't strictly allowed by the quantum computing rulebook? + Enter the Linear Combination of Unitaries (LCU) protocol—a foundational quantum algorithmic primitive that lets you implement a non-unitary operator $A$ by cleverly expressing it as a weighted sum of unitary operators: .. math:: @@ -33,7 +34,7 @@ This is the quantum equivalent of ordering a custom pizza: you pick your favorit Core components ^^^^^^^^^^^^^^^ -The LCU protocol works by embedding your non-unitary operator into a larger, unitary quantum circuit. The magic happens in three acts, known as block encoding: +The LCU protocol works by embedding your non-unitary operator into a larger, unitary quantum circuit. The magic happens in three acts, known as **block encoding**: - **PREPARE**: Prepares an ancilla quantum variable in a superposition encoding the normalized coefficients $\alpha_i\geq0$ of the target operator @@ -60,8 +61,92 @@ The approach you’ve just studied was pioneered by Nathan Wiebe, whose contribu If you’re eager for more than equations and want intuition delivered with clarity, Nathan Wiebe’s YouTube seminar series is a goldmine. His channel is packed with lucid explanations of quantum primitives and routines, making even the most complex ideas accessible. The video below, authored by Wiebe himself, distills the essence of the LCU protocol and its applications—so whether you’re seeking a first encounter or a deeper understanding, this is a resource not to miss. .. youtube:: irMKrOIrHP4 + LCU in Qrisp ------------ +With the theoretical foundation of the Linear Combination of Unitaries (LCU) protocol in place, it’s time to see how these abstract concepts translate into practical quantum programming using Qrisp. This section will connect the dots between the block-encoding theory and Qrisp’s implementation, showing how to realize LCU’s power on real quantum circuits and simulations. + +Qrisp provides a collection of functions, three to be exact, that directly mirror the theoretical structure of LCU, allowing you to implement, visualize, and experiment with the protocol as described in the previous section. Let's take a closer look and disect the inner workings of these aforementioned functions. + +Underlying protocol in two lines of code in :func:`qrisp.inner_LCU` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:func:`qrisp.inner_LCU` implements the core LCU protocol (prepare-select/qswitch-unprepare) without the Repeat-Until_Success (RUS) protocol validating the correct execution of the primitive. + +At its core, the LCU protocol in Qrisp is realized by two key operations: preparing the ancilla in the right superposition (encoding the coefficients) and applying the controlled unitaries. The function inner_LCU exposes this structure directly, without any success-checking or repetition logic. + +:: + + # Prepare the operand (target quantum variable) + operand = operand_prep() + + # Prepare the ancilla register (case indicator) + case_indicator = QuantumFloat(n) # n = number of ancilla qubits needed + + # 1. PREPARE + SELECT + PREPARE† (block encoding) + def LCU_state_prep(case_indicator, operand): + with conjugate(state_prep)(case_indicator): + qswitch(operand, case_indicator, unitaries) + + LCU_state_prep(case_indicator, operand) + +:func:`state_prep` ``(case_indicator)`` prepares the ancilla in a superposition reflecting the coefficients $\alpha_i$. :func:`qswitch` ``(operand, case_indicator, unitaries)`` applies the correct unitary $U_i$ controlled on the ancilla. + +The :func:`conjugate` ensures the inverse preparation (PREPARE $^\dagger$) is applied after SELECT, matching the block-encoding structure. + +Success condition and performing LCU with :func:`qrisp.LCU` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Wraps inner_LCU with a Repeat-Until-Success (RUS) protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. + +The LCU protocol is only "successful" if, after running the block-encoded circuit, the ancilla is measured in the $\ket{0}$ state. Qrisp's LCU function wraps inner_LCU with a :func:`RUS` (Repeat-Until-Success) protocol, automating this process. + +:: + + # Run the inner protocol + case_indicator, qv = inner_LCU(operand_prep, state_prep, unitaries, num_unitaries, oaa_iter) + + # Measure the ancilla for success + success_bool = measure(case_indicator) == 0 + + # Return the result only if successful + return success_bool, qv + +``measure(case_indicator) == 0`` checks if the ancillae are in the $\ket{0}$ state, signalling success. If not, the protocol is repeated (handled by the :func:`RUS` in Qrisp). This matches the theoretical requirement that the LCU protocol only works when the ancillae are measured in the $\ket{0}$ state. + +Increasing the success probability: Oblivious Amplitude Amplification +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The probability of success in LCU can be low, especially for certain coefficient choices. Qrisp allows you to boost this probability using oblivious amplitude amplification (OAA), which iteratively amplifies the "good" outcome. + +:: + + if oaa_iter > 0: + amplitude_amplification( + [case_indicator, operand], + LCU_state_prep, + oracle_func, + reflection_indices=[0], + iter=oaa_iter, + ) + +:func:`amplitude_amplification` repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. ``oaa_iter`` controls how many amplification iterations are performed. The oracle tags the success state, and the reflection boosts its amplitude, increasing the chance of success in fewer repetitions. + +For more information on Oblivious Amplitude Amplification, here is Nathan Wiebe's seminar on this primitive: + +.. youtube:: FmZcj7O4U2w + +Underlying circuit (purely educational) with :func:`qrisp.view_LCU` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For educational and debugging purposes, Qrisp provides :func:`qrisp.view_LCU`, which constructs and returns the explicit quantum circuit corresponding to your LCU protocol. This lets you see how the ancilla preparation, controlled unitaries, and inverse preparation are realized at the gate level. + +:: + + jaspr = make_jaspr(inner_LCU)(operand_prep, state_prep, unitaries, num_unitaries) + qc = jaspr.to_qc(num_unitaries)[-1].transpile(3) + return qc + +``make_jaspr(inner_LCU)`` wraps the protocol for circuit extraction. ``to_qc`` converts the protocol to a quantum circuit object. ``.transpile(3)`` optimiyes and formats the circuit for visualiyation. Printing ``qc`` reveals the gate sequence showing PREPARE, qswitch, and PREPARE$^\dagger$ as described in theory. + Trotterization + LCU = LCHS --------------------------- \ No newline at end of file From 45d20c85ba4b361624ce3165f80b8cb0e7f5b57b Mon Sep 17 00:00:00 2001 From: mat70593 Date: Thu, 19 Jun 2025 10:11:23 +0200 Subject: [PATCH 05/15] Fixed a typo, added another subsection --- documentation/source/general/tutorial/LCU.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index d6434bfd0..1369e486e 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -50,6 +50,12 @@ The LCU protocol works by embedding your non-unitary operator into a larger, uni - **PREPARE**$^\dagger$: Applies the inverse prepartion to the ancilla. +Unitaries passed as static lists or dynamic functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Qrisp's LCU functions support two ways to pass unitaries statically by providing unitaries as a list. Not to limit ourselves, we also allow passing unitaries as dynamic functions - this way we can pass trotterization unitaries elegantly. + + Success condition ^^^^^^^^^^^^^^^^^ @@ -91,15 +97,15 @@ At its core, the LCU protocol in Qrisp is realized by two key operations: prepar LCU_state_prep(case_indicator, operand) -:func:`state_prep` ``(case_indicator)`` prepares the ancilla in a superposition reflecting the coefficients $\alpha_i$. :func:`qswitch` ``(operand, case_indicator, unitaries)`` applies the correct unitary $U_i$ controlled on the ancilla. +``state_prep(case_indicator)`` prepares the ancilla in a superposition reflecting the coefficients $\alpha_i$. :func:`qrisp.qswitch` ``(operand, case_indicator, unitaries)`` applies the correct unitary $U_i$ controlled on the ancilla. -The :func:`conjugate` ensures the inverse preparation (PREPARE $^\dagger$) is applied after SELECT, matching the block-encoding structure. +The ``qrisp.conjugate`` ensures the inverse preparation (PREPARE $^\dagger$) is applied after SELECT, matching the block-encoding structure. Success condition and performing LCU with :func:`qrisp.LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Wraps inner_LCU with a Repeat-Until-Success (RUS) protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. +Wraps inner_LCU with a :ref:`repeat-until-success (RUS) routine ` protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. -The LCU protocol is only "successful" if, after running the block-encoded circuit, the ancilla is measured in the $\ket{0}$ state. Qrisp's LCU function wraps inner_LCU with a :func:`RUS` (Repeat-Until-Success) protocol, automating this process. +The LCU protocol is only "successful" if, after running the block-encoded circuit, the ancilla is measured in the $\ket{0}$ state. Qrisp's LCU function wraps inner_LCU with :ref:`RUS `, automating this process. :: @@ -129,7 +135,7 @@ The probability of success in LCU can be low, especially for certain coefficient iter=oaa_iter, ) -:func:`amplitude_amplification` repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. ``oaa_iter`` controls how many amplification iterations are performed. The oracle tags the success state, and the reflection boosts its amplitude, increasing the chance of success in fewer repetitions. +:func:`qrisp.amplitude_amplification` repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. ``oaa_iter`` controls how many amplification iterations are performed. The oracle tags the success state, and the reflection boosts its amplitude, increasing the chance of success in fewer repetitions. For more information on Oblivious Amplitude Amplification, here is Nathan Wiebe's seminar on this primitive: @@ -146,7 +152,7 @@ For educational and debugging purposes, Qrisp provides :func:`qrisp.view_LCU`, w qc = jaspr.to_qc(num_unitaries)[-1].transpile(3) return qc -``make_jaspr(inner_LCU)`` wraps the protocol for circuit extraction. ``to_qc`` converts the protocol to a quantum circuit object. ``.transpile(3)`` optimiyes and formats the circuit for visualiyation. Printing ``qc`` reveals the gate sequence showing PREPARE, qswitch, and PREPARE$^\dagger$ as described in theory. +``make_jaspr(inner_LCU)`` wraps the protocol for circuit extraction. ``to_qc`` converts the protocol to a quantum circuit object. ``.transpile(3)`` optimizes and formats the circuit for visualiyation. Printing ``qc`` reveals the gate sequence showing PREPARE, qswitch, and PREPARE$^\dagger$ as described in theory. Trotterization + LCU = LCHS --------------------------- \ No newline at end of file From c46742f6dfad8166018484d4092df10d9c754010 Mon Sep 17 00:00:00 2001 From: mat70593 Date: Thu, 19 Jun 2025 11:15:59 +0200 Subject: [PATCH 06/15] small changes to the order of the subsections --- documentation/source/general/tutorial/LCU.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index 1369e486e..612b5dff5 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -48,13 +48,7 @@ The LCU protocol works by embedding your non-unitary operator into a larger, uni \mathrm{SELECT}|i\rangle|\psi\rangle=|i\rangle U_i|\psi\rangle -- **PREPARE**$^\dagger$: Applies the inverse prepartion to the ancilla. - -Unitaries passed as static lists or dynamic functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Qrisp's LCU functions support two ways to pass unitaries statically by providing unitaries as a list. Not to limit ourselves, we also allow passing unitaries as dynamic functions - this way we can pass trotterization unitaries elegantly. - +- **PREPARE** $^\dagger$: Applies the inverse prepartion to the ancilla. Success condition ^^^^^^^^^^^^^^^^^ @@ -141,6 +135,13 @@ For more information on Oblivious Amplitude Amplification, here is Nathan Wiebe' .. youtube:: FmZcj7O4U2w +Unitaries passed as static lists or dynamic functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Qrisp's LCU functions support two ways to pass unitaries statically by providing unitaries as a list. Not to limit ourselves, we also allow passing unitaries as dynamic functions - this way we can pass trotterization unitaries elegantly. + + + Underlying circuit (purely educational) with :func:`qrisp.view_LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From d5f836a7fc813465887744f0f39393f4a97b5a7d Mon Sep 17 00:00:00 2001 From: mat70593 Date: Wed, 9 Jul 2025 11:29:01 +0200 Subject: [PATCH 07/15] added LCU thumbnail in tutorial, minor changes until that point --- documentation/source/general/tutorial/LCU.png | Bin 0 -> 129305 bytes documentation/source/general/tutorial/LCU.rst | 21 +++++++++++++++--- 2 files changed, 18 insertions(+), 3 deletions(-) create mode 100644 documentation/source/general/tutorial/LCU.png diff --git a/documentation/source/general/tutorial/LCU.png b/documentation/source/general/tutorial/LCU.png new file mode 100644 index 0000000000000000000000000000000000000000..ca7f189675928cfad79435ba418379950750be0d GIT binary patch literal 129305 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℞F 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

SvUmJY}JUPZRmxz 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 LI9&X*=O_OIHIZjV literal 0 HcmV?d00001 diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index 612b5dff5..735ff20b6 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -9,7 +9,7 @@ Here’s what you’ll discover as you journey through this tutorial: - We’ll start by demystifying the LCU protocol: why it’s needed and what problems it solves. You’ll learn the core ideas behind representing complex quantum operations as sums of simpler, unitary building blocks aka block encodings. -- Next, we’ll roll up our sleeves and see how LCU comes alive in Qrisp (Frankenstein intensifies). This section is hands-on: you’ll explore annotated code examples, understand the structure of Qrisp’s LCU implementation, and see how to prepare ancilla registers, orchestrate controlled unitaries, and interpret the results. +- Next, we’ll roll up our sleeves and see how LCU comes alive in Qrisp (Frankenstein intensifies). This section is hands-on: you’ll explore annotated code examples, understand the structure of Qrisp’s LCU implementation, and see how to prepare ancilla variables, orchestrate controlled unitaries, and interpret the results. - We won't stop at just understanding LCU, but instead also use it as an algorithmic building block (primitive) to perform another algorithm. In our final section, we combine the strengths of Trotterization and LCU to unlock the Linear Combination of Hamiltonian Simulation (LCHS) protocol. Here, you’ll learn how to simulate functions of Hamiltonians—like $\cos(H)$. @@ -50,11 +50,13 @@ The LCU protocol works by embedding your non-unitary operator into a larger, uni - **PREPARE** $^\dagger$: Applies the inverse prepartion to the ancilla. +.. image:: LCU.png + Success condition ^^^^^^^^^^^^^^^^^ The LCU protocol is deemed successful only if the ancilla variable is measured in the $\ket{0}$ state, which occurs with a probability proportional to :math:`\frac{\langle\psi|A^{\dagger}A|\psi\rangle}{\lambda^2}` where $\lambda=\sum_i\alpha_i$. -This function does not perform the measurement; it returns the ancilla variable and the transformed target variable. +The qrisp.inner_LCU does not perform the measurement; it returns the ancilla variable and the transformed target variable. The approach you’ve just studied was pioneered by Nathan Wiebe, whose contributions have fundamentally shaped the field of quantum algorithm design, particularly in Hamiltonian simulation and quantum linear systems. @@ -78,11 +80,24 @@ At its core, the LCU protocol in Qrisp is realized by two key operations: prepar :: + def inner_LCU(operand_prep, state_prep, unitaries, num_unitaries=None, oaa_iter=0): + + if not callable(unitaries): + if not isinstance(unitaries, list): + raise TypeError("unitaries must be callable or list[callable].") + num_unitaries = len(unitaries) + else: + if num_unitaries == None: + raise ValueError( + "The number of unitiaries must be specified if unitaries is callable." + ) + # Prepare the operand (target quantum variable) operand = operand_prep() # Prepare the ancilla register (case indicator) - case_indicator = QuantumFloat(n) # n = number of ancilla qubits needed + n = np.int64(np.ceil(np.log2(num_unitaries))) # n = number of ancilla qubits needed + case_indicator = QuantumFloat(n) # 1. PREPARE + SELECT + PREPARE† (block encoding) def LCU_state_prep(case_indicator, operand): From 68d94847305f31f79b5ac64d3aaf70bd5fdccfa9 Mon Sep 17 00:00:00 2001 From: mat70593 Date: Wed, 9 Jul 2025 11:31:53 +0200 Subject: [PATCH 08/15] extended the inner_LCU function, included oaa, yet to be described/unpacked --- documentation/source/general/tutorial/LCU.rst | 38 +++++++++++++------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index 735ff20b6..d4b5af3fd 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -92,19 +92,33 @@ At its core, the LCU protocol in Qrisp is realized by two key operations: prepar "The number of unitiaries must be specified if unitaries is callable." ) - # Prepare the operand (target quantum variable) - operand = operand_prep() - - # Prepare the ancilla register (case indicator) - n = np.int64(np.ceil(np.log2(num_unitaries))) # n = number of ancilla qubits needed - case_indicator = QuantumFloat(n) - - # 1. PREPARE + SELECT + PREPARE† (block encoding) - def LCU_state_prep(case_indicator, operand): - with conjugate(state_prep)(case_indicator): - qswitch(operand, case_indicator, unitaries) + # Prepare the operand (target quantum variable) + operand = operand_prep() + + # Prepare the ancilla register (case indicator) + n = np.int64(np.ceil(np.log2(num_unitaries))) # n = number of ancilla qubits needed + case_indicator = QuantumFloat(n) + + # 1. PREPARE + SELECT + PREPARE† (block encoding) + def LCU_state_prep(case_indicator, operand): + with conjugate(state_prep)(case_indicator): + qswitch(operand, case_indicator, unitaries) + + def oracle_func(case_indicator, operand): + tag_state({case_indicator: 0}) + + LCU_state_prep(case_indicator, operand) + + if oaa_iter > 0: + amplitude_amplification( + [case_indicator, operand], + LCU_state_prep, + oracle_func, + reflection_indices=[0], + iter=oaa_iter, + ) - LCU_state_prep(case_indicator, operand) + return case_indicator, operand ``state_prep(case_indicator)`` prepares the ancilla in a superposition reflecting the coefficients $\alpha_i$. :func:`qrisp.qswitch` ``(operand, case_indicator, unitaries)`` applies the correct unitary $U_i$ controlled on the ancilla. From 219e57babe874316468e78260c876575e2327e39 Mon Sep 17 00:00:00 2001 From: mat70593 Date: Thu, 10 Jul 2025 17:42:54 +0200 Subject: [PATCH 09/15] Updated tutorial. Thanks @renezander for the feedback! --- documentation/source/general/tutorial/LCU.rst | 93 ++++++++++--------- 1 file changed, 51 insertions(+), 42 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index d4b5af3fd..5bd0b28f9 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -56,7 +56,7 @@ Success condition ^^^^^^^^^^^^^^^^^ The LCU protocol is deemed successful only if the ancilla variable is measured in the $\ket{0}$ state, which occurs with a probability proportional to :math:`\frac{\langle\psi|A^{\dagger}A|\psi\rangle}{\lambda^2}` where $\lambda=\sum_i\alpha_i$. -The qrisp.inner_LCU does not perform the measurement; it returns the ancilla variable and the transformed target variable. +The :func:`qrisp.inner_LCU` does not perform the measurement; it returns the ancilla variable and the transformed target variable. The approach you’ve just studied was pioneered by Nathan Wiebe, whose contributions have fundamentally shaped the field of quantum algorithm design, particularly in Hamiltonian simulation and quantum linear systems. @@ -67,7 +67,7 @@ If you’re eager for more than equations and want intuition delivered with clar LCU in Qrisp ------------ -With the theoretical foundation of the Linear Combination of Unitaries (LCU) protocol in place, it’s time to see how these abstract concepts translate into practical quantum programming using Qrisp. This section will connect the dots between the block-encoding theory and Qrisp’s implementation, showing how to realize LCU’s power on real quantum circuits and simulations. +With the theoretical foundation of the Linear Combination of Unitaries (LCU) protocol in place, it’s time to see how these abstract concepts translate into practical quantum programming using Qrisp. This section will connect the dots between the block-encoding theory and Qrisp’s implementation, showing how to realize LCU’s power on real quantum programms and simulations. Qrisp provides a collection of functions, three to be exact, that directly mirror the theoretical structure of LCU, allowing you to implement, visualize, and experiment with the protocol as described in the previous section. Let's take a closer look and disect the inner workings of these aforementioned functions. @@ -78,6 +78,7 @@ Underlying protocol in two lines of code in :func:`qrisp.inner_LCU` At its core, the LCU protocol in Qrisp is realized by two key operations: preparing the ancilla in the right superposition (encoding the coefficients) and applying the controlled unitaries. The function inner_LCU exposes this structure directly, without any success-checking or repetition logic. +In order to have this tutorial reproduceable, this is the entire :func:`qrisp.inner_LCU`, as it is defined in the Qrisp repository: :: def inner_LCU(operand_prep, state_prep, unitaries, num_unitaries=None, oaa_iter=0): @@ -95,17 +96,17 @@ At its core, the LCU protocol in Qrisp is realized by two key operations: prepar # Prepare the operand (target quantum variable) operand = operand_prep() - # Prepare the ancilla register (case indicator) + # Prepare the ancilla variable (case indicator) n = np.int64(np.ceil(np.log2(num_unitaries))) # n = number of ancilla qubits needed case_indicator = QuantumFloat(n) - # 1. PREPARE + SELECT + PREPARE† (block encoding) + # PREPARE + SELECT + PREPARE† (block encoding) def LCU_state_prep(case_indicator, operand): with conjugate(state_prep)(case_indicator): qswitch(operand, case_indicator, unitaries) def oracle_func(case_indicator, operand): - tag_state({case_indicator: 0}) + tag_state({case_indicator: 0}) LCU_state_prep(case_indicator, operand) @@ -120,54 +121,48 @@ At its core, the LCU protocol in Qrisp is realized by two key operations: prepar return case_indicator, operand -``state_prep(case_indicator)`` prepares the ancilla in a superposition reflecting the coefficients $\alpha_i$. :func:`qrisp.qswitch` ``(operand, case_indicator, unitaries)`` applies the correct unitary $U_i$ controlled on the ancilla. +Unpacking the code (which pack a hefty punch) becomes self explenatory because of the modularity that Qrisp offers through various modules. Let's unveil the concepts bit by bit. -The ``qrisp.conjugate`` ensures the inverse preparation (PREPARE $^\dagger$) is applied after SELECT, matching the block-encoding structure. +First we have to prepare the ancilla variables with ``state_prep(case_indicator)``. This step transforms the ancilla in a superposition reflecting the coefficients $\alpha_i$. -Success condition and performing LCU with :func:`qrisp.LCU` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Wraps inner_LCU with a :ref:`repeat-until-success (RUS) routine ` protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. +We already learned about the SELECT operator in the theoretical overview. Here we put it in action using :func:`qrisp.qswitch` ``(operand, case_indicator, unitaries)``. This applies the correct unitary $U_i$ controlled on the ancilla. -The LCU protocol is only "successful" if, after running the block-encoded circuit, the ancilla is measured in the $\ket{0}$ state. Qrisp's LCU function wraps inner_LCU with :ref:`RUS `, automating this process. - -:: +the ``qrisp.conjugate`` environment ensures the inverse preparation (PREPARE $^\dagger$) is applied after SELECT, matching the block-encoding structure. - # Run the inner protocol - case_indicator, qv = inner_LCU(operand_prep, state_prep, unitaries, num_unitaries, oaa_iter) +The probability of success in LCU can be low, especially for certain coefficient choices. Qrisp allows you to boost this probability using oblivious amplitude amplification (OAA), which iteratively amplifies the "good" outcome. This is done by +:func:`qrisp.amplitude_amplification`, which repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. The ``oaa_iter`` keyword controls how many amplification iterations are performed. +The oracle tags the success state, and the reflection boosts its amplitude, increasing the chance of success in fewer repetitions. - # Measure the ancilla for success - success_bool = measure(case_indicator) == 0 +It is also possible to do too many iterations and therefore getting a lower probability of success, when we reflect beyond the ideal state. - # Return the result only if successful - return success_bool, qv +For more information on Oblivious Amplitude Amplification, here is Nathan Wiebe's seminar on this primitive: -``measure(case_indicator) == 0`` checks if the ancillae are in the $\ket{0}$ state, signalling success. If not, the protocol is repeated (handled by the :func:`RUS` in Qrisp). This matches the theoretical requirement that the LCU protocol only works when the ancillae are measured in the $\ket{0}$ state. +.. youtube:: FmZcj7O4U2w -Increasing the success probability: Oblivious Amplitude Amplification -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The probability of success in LCU can be low, especially for certain coefficient choices. Qrisp allows you to boost this probability using oblivious amplitude amplification (OAA), which iteratively amplifies the "good" outcome. +Exactly this is done in the ``oracle_func``, where we tag the state where ``measure(case_indicator) == 0``. As we will see, this is equivalent to successfully adding the unitaries +to our ``operand`` QuantumVariable. -:: +The oblivious amplitude amplification is then performed based on how many iterations we have specified in the ``oaa_iter`` keyword. - if oaa_iter > 0: - amplitude_amplification( - [case_indicator, operand], - LCU_state_prep, - oracle_func, - reflection_indices=[0], - iter=oaa_iter, - ) +Success condition with :func:`qrisp.LCU` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:func:`qrisp.LCU` wraps inner_LCU with a :ref:`repeat-until-success (RUS) routine ` protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. -:func:`qrisp.amplitude_amplification` repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. ``oaa_iter`` controls how many amplification iterations are performed. The oracle tags the success state, and the reflection boosts its amplitude, increasing the chance of success in fewer repetitions. +The LCU protocol is only "successful" if, after running the block-encoded circuit, the ancilla is measured in the $\ket{0}$ state. Qrisp's LCU function wraps inner_LCU with :ref:`RUS `, automating this process. -For more information on Oblivious Amplitude Amplification, here is Nathan Wiebe's seminar on this primitive: +:: -.. youtube:: FmZcj7O4U2w + @RUS + def LCU(operand_prep, state_prep, unitaries, num_unitaries=None, oaa_iter=0): + case_indicator, qv = inner_LCU( + operand_prep, state_prep, unitaries, num_unitaries, oaa_iter + ) -Unitaries passed as static lists or dynamic functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + # Success condition + success_bool = measure(case_indicator) == 0 + return success_bool, qv -Qrisp's LCU functions support two ways to pass unitaries statically by providing unitaries as a list. Not to limit ourselves, we also allow passing unitaries as dynamic functions - this way we can pass trotterization unitaries elegantly. +The ``measure(case_indicator) == 0`` checks if the ancillae are in the $\ket{0}$ state, signalling success. If not, the protocol is repeated (handled by the :func:`RUS` in Qrisp). This matches the theoretical requirement that the LCU protocol only works when the ancillae are measured in the $\ket{0}$ state. @@ -178,11 +173,25 @@ For educational and debugging purposes, Qrisp provides :func:`qrisp.view_LCU`, w :: - jaspr = make_jaspr(inner_LCU)(operand_prep, state_prep, unitaries, num_unitaries) - qc = jaspr.to_qc(num_unitaries)[-1].transpile(3) - return qc + def view_LCU(operand_prep, state_prep, unitaries, num_unitaries=None): + + if not callable(unitaries): + if not isinstance(unitaries, list): + raise TypeError("unitaries must be callable or list[callable].") + num_unitaries = len(unitaries) + else: + if num_unitaries == None: + raise ValueError( + "The number of unitiaries must be specified if unitaries is callable." + ) + + jaspr = make_jaspr(inner_LCU)(operand_prep, state_prep, unitaries, num_unitaries) + + # Convert Jaspr to quantum circuit and return the circuit + return jaspr.to_qc(num_unitaries)[-1].transpile(3) + -``make_jaspr(inner_LCU)`` wraps the protocol for circuit extraction. ``to_qc`` converts the protocol to a quantum circuit object. ``.transpile(3)`` optimizes and formats the circuit for visualiyation. Printing ``qc`` reveals the gate sequence showing PREPARE, qswitch, and PREPARE$^\dagger$ as described in theory. +``make_jaspr(inner_LCU)`` wraps the protocol for circuit extraction. ``to_qc`` converts the protocol to a quantum circuit object. ``.transpile(3)`` optimizes and formats the circuit for visualization. Printing ``qc`` reveals the gate sequence showing PREPARE, qswitch, and PREPARE$^\dagger$ as described in theory. Trotterization + LCU = LCHS --------------------------- \ No newline at end of file From 28a3f9e4c11080d11e783e85561b6566f4ccdc4d Mon Sep 17 00:00:00 2001 From: mat70593 Date: Wed, 16 Jul 2025 14:13:00 +0200 Subject: [PATCH 10/15] replaced alphas with c's to be consistent with the graphic --- documentation/source/general/tutorial/LCU.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index 5bd0b28f9..3a2c65c6f 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -27,7 +27,7 @@ So, you want to perform operations that aren't strictly allowed by the quantum c Enter the Linear Combination of Unitaries (LCU) protocol—a foundational quantum algorithmic primitive that lets you implement a non-unitary operator $A$ by cleverly expressing it as a weighted sum of unitary operators: .. math:: - A=\sum_i\alpha_iU_i + A=\sum_ic_iU_i This is the quantum equivalent of ordering a custom pizza: you pick your favorite toppings (unitaries), assign them weights (coefficients), and hope the outcome is deliciously non-classical. @@ -36,11 +36,11 @@ Core components The LCU protocol works by embedding your non-unitary operator into a larger, unitary quantum circuit. The magic happens in three acts, known as **block encoding**: -- **PREPARE**: Prepares an ancilla quantum variable in a superposition encoding the normalized coefficients $\alpha_i\geq0$ of the target operator +- **PREPARE**: Prepares an ancilla quantum variable in a superposition encoding the normalized coefficients $c_i\geq0$ of the target operator .. math :: - \mathrm{PREPARE}|0\rangle=\sum_i\sqrt{\frac{\alpha_i}{\lambda}}|i\rangle + \mathrm{PREPARE}|0\rangle=\sum_i\sqrt{\frac{c_i}{\lambda}}|i\rangle - **SELECT**: Applies the unitary $U_i$ to the input state $\ket{\psi}$, controlled on the ancilla variable being in state $|i\rangle$. @@ -55,7 +55,7 @@ The LCU protocol works by embedding your non-unitary operator into a larger, uni Success condition ^^^^^^^^^^^^^^^^^ -The LCU protocol is deemed successful only if the ancilla variable is measured in the $\ket{0}$ state, which occurs with a probability proportional to :math:`\frac{\langle\psi|A^{\dagger}A|\psi\rangle}{\lambda^2}` where $\lambda=\sum_i\alpha_i$. +The LCU protocol is deemed successful only if the ancilla variable is measured in the $\ket{0}$ state, which occurs with a probability proportional to :math:`\frac{\langle\psi|A^{\dagger}A|\psi\rangle}{\lambda^2}` where $\lambda=\sum_ic_i$. The :func:`qrisp.inner_LCU` does not perform the measurement; it returns the ancilla variable and the transformed target variable. The approach you’ve just studied was pioneered by Nathan Wiebe, whose contributions have fundamentally shaped the field of quantum algorithm design, particularly in Hamiltonian simulation and quantum linear systems. @@ -123,7 +123,7 @@ In order to have this tutorial reproduceable, this is the entire :func:`qrisp.in Unpacking the code (which pack a hefty punch) becomes self explenatory because of the modularity that Qrisp offers through various modules. Let's unveil the concepts bit by bit. -First we have to prepare the ancilla variables with ``state_prep(case_indicator)``. This step transforms the ancilla in a superposition reflecting the coefficients $\alpha_i$. +First we have to prepare the ancilla variables with ``state_prep(case_indicator)``. This step transforms the ancilla in a superposition reflecting the coefficients $c_i$. We already learned about the SELECT operator in the theoretical overview. Here we put it in action using :func:`qrisp.qswitch` ``(operand, case_indicator, unitaries)``. This applies the correct unitary $U_i$ controlled on the ancilla. From fc03a19bcf2c49a5ac35f69b0e27e1feaeb148de Mon Sep 17 00:00:00 2001 From: mat70593 Date: Wed, 16 Jul 2025 16:16:01 +0200 Subject: [PATCH 11/15] Brief extension and linking to sections of the tutorial --- documentation/source/general/tutorial/LCU.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index 3a2c65c6f..e2bc9ed2b 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -18,7 +18,6 @@ Processing (QSP) `: implements the core LCU protocol (prepare-select/qswitch-unprepare) without the Repeat-Until_Success (RUS) protocol. +- :ref:`LCU `: wraps inner_LCU with a repeat-until-success (RUS) routine protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0} state (the success condition described in theory). +- :ref:`view_LCU `: constructs and returns the explicit quantum circuit corresponding to your LCU protocol. + +Let's take a closer look and disect the inner workings of these functions. + +.. _inner_LCU_tut: Underlying protocol in two lines of code in :func:`qrisp.inner_LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -144,6 +151,8 @@ to our ``operand`` QuantumVariable. The oblivious amplitude amplification is then performed based on how many iterations we have specified in the ``oaa_iter`` keyword. +.. _LCU_func_tut: + Success condition with :func:`qrisp.LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :func:`qrisp.LCU` wraps inner_LCU with a :ref:`repeat-until-success (RUS) routine ` protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. @@ -164,7 +173,7 @@ The LCU protocol is only "successful" if, after running the block-encoded circui The ``measure(case_indicator) == 0`` checks if the ancillae are in the $\ket{0}$ state, signalling success. If not, the protocol is repeated (handled by the :func:`RUS` in Qrisp). This matches the theoretical requirement that the LCU protocol only works when the ancillae are measured in the $\ket{0}$ state. - +.. _view_LCU_tut: Underlying circuit (purely educational) with :func:`qrisp.view_LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From c9dadcf04bd63e437140635069c44a9e50e10d25 Mon Sep 17 00:00:00 2001 From: Steinmann Date: Thu, 17 Jul 2025 15:05:28 +0200 Subject: [PATCH 12/15] first proofreading iteration - some typos, stylistic suggestions --- documentation/source/general/tutorial/LCU.rst | 29 +++++++++++-------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index e2bc9ed2b..5b4a5464f 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -26,7 +26,7 @@ So, you want to perform operations that aren't strictly allowed by the quantum c Enter the Linear Combination of Unitaries (LCU) protocol—a foundational quantum algorithmic primitive that lets you implement a non-unitary operator $A$ by cleverly expressing it as a weighted sum of unitary operators: .. math:: - A=\sum_ic_iU_i + A=\sum_ic_i \, U_i This is the quantum equivalent of ordering a custom pizza: you pick your favorite toppings (unitaries), assign them weights (coefficients), and hope the outcome is deliciously non-classical. @@ -39,13 +39,13 @@ The LCU protocol works by embedding your non-unitary operator into a larger, uni .. math :: - \mathrm{PREPARE}|0\rangle=\sum_i\sqrt{\frac{c_i}{\lambda}}|i\rangle + \mathrm{PREPARE} \, |0\rangle=\sum_i\sqrt{\frac{c_i}{\lambda}} \, |i\rangle - **SELECT**: Applies the unitary $U_i$ to the input state $\ket{\psi}$, controlled on the ancilla variable being in state $|i\rangle$. .. math :: - \mathrm{SELECT}|i\rangle|\psi\rangle=|i\rangle U_i|\psi\rangle + \mathrm{SELECT} \, |i\rangle|\psi\rangle=|i\rangle U_i \, |\psi\rangle - **PREPARE** $^\dagger$: Applies the inverse prepartion to the ancilla. @@ -71,7 +71,7 @@ With the theoretical foundation of the Linear Combination of Unitaries (LCU) pro Qrisp provides a collection of functions, three to be exact, that directly mirror the theoretical structure of LCU, allowing you to implement, visualize, and experiment with the protocol as described in the previous section: - :ref:`inner_LCU `: implements the core LCU protocol (prepare-select/qswitch-unprepare) without the Repeat-Until_Success (RUS) protocol. -- :ref:`LCU `: wraps inner_LCU with a repeat-until-success (RUS) routine protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0} state (the success condition described in theory). +- :ref:`LCU `: wraps inner_LCU with a repeat-until-success (RUS) routine protocol, repeatedly running the circuit until the ancilla is measured in the :math:`\ket{0}` state (the success condition described in the theory). - :ref:`view_LCU `: constructs and returns the explicit quantum circuit corresponding to your LCU protocol. Let's take a closer look and disect the inner workings of these functions. @@ -81,9 +81,9 @@ Let's take a closer look and disect the inner workings of these functions. Underlying protocol in two lines of code in :func:`qrisp.inner_LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:func:`qrisp.inner_LCU` implements the core LCU protocol (prepare-select/qswitch-unprepare) without the Repeat-Until_Success (RUS) protocol validating the correct execution of the primitive. +:func:`qrisp.inner_LCU` implements the core LCU protocol (prepare-select/qswitch-unprepare), without the Repeat-Until_Success (RUS) protocol validating the correct execution of the primitive. -At its core, the LCU protocol in Qrisp is realized by two key operations: preparing the ancilla in the right superposition (encoding the coefficients) and applying the controlled unitaries. The function inner_LCU exposes this structure directly, without any success-checking or repetition logic. +At its core, the LCU protocol in Qrisp is realized by two key operations: preparing the ancilla in the right superposition (encoding the coefficients) and applying the controlled unitaries. The function ``inner_LCU`` exposes this structure directly, without any success-checking or repetition logic. In order to have this tutorial reproduceable, this is the entire :func:`qrisp.inner_LCU`, as it is defined in the Qrisp repository: :: @@ -128,13 +128,13 @@ In order to have this tutorial reproduceable, this is the entire :func:`qrisp.in return case_indicator, operand -Unpacking the code (which pack a hefty punch) becomes self explenatory because of the modularity that Qrisp offers through various modules. Let's unveil the concepts bit by bit. +Unpacking the code (which packs a hefty punch) becomes self explenatory because of the modularity that Qrisp offers through various modules. Let's unveil the concepts bit by bit. First we have to prepare the ancilla variables with ``state_prep(case_indicator)``. This step transforms the ancilla in a superposition reflecting the coefficients $c_i$. We already learned about the SELECT operator in the theoretical overview. Here we put it in action using :func:`qrisp.qswitch` ``(operand, case_indicator, unitaries)``. This applies the correct unitary $U_i$ controlled on the ancilla. -the ``qrisp.conjugate`` environment ensures the inverse preparation (PREPARE $^\dagger$) is applied after SELECT, matching the block-encoding structure. +the ``qrisp.conjugate`` environment ensures the inverse preparation (PREPARE` $^\dagger$) is applied after SELECT, matching the block-encoding structure. The probability of success in LCU can be low, especially for certain coefficient choices. Qrisp allows you to boost this probability using oblivious amplitude amplification (OAA), which iteratively amplifies the "good" outcome. This is done by :func:`qrisp.amplitude_amplification`, which repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. The ``oaa_iter`` keyword controls how many amplification iterations are performed. @@ -155,17 +155,22 @@ The oblivious amplitude amplification is then performed based on how many iterat Success condition with :func:`qrisp.LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:func:`qrisp.LCU` wraps inner_LCU with a :ref:`repeat-until-success (RUS) routine ` protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. +:func:`qrisp.LCU` wraps ``inner_LCU`` with a :ref:`repeat-until-success (RUS) routine ` protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. -The LCU protocol is only "successful" if, after running the block-encoded circuit, the ancilla is measured in the $\ket{0}$ state. Qrisp's LCU function wraps inner_LCU with :ref:`RUS `, automating this process. +The LCU protocol is only "successful" if, after running the block-encoded circuit, the ancilla is measured in the $\ket{0}$ state. Qrisp's ``LCU`` function wraps ``inner_LCU`` with :ref:`RUS `, automating this process. :: @RUS def LCU(operand_prep, state_prep, unitaries, num_unitaries=None, oaa_iter=0): + case_indicator, qv = inner_LCU( - operand_prep, state_prep, unitaries, num_unitaries, oaa_iter - ) + operand_prep, + state_prep, + unitaries, + num_unitaries, + oaa_iter + ) # Success condition success_bool = measure(case_indicator) == 0 From e6b818e0adaa4b544df69ab02a346fdab5bfcded Mon Sep 17 00:00:00 2001 From: mat70593 Date: Thu, 17 Jul 2025 15:22:36 +0200 Subject: [PATCH 13/15] reverted some stylistic changes in previous commit --- documentation/source/general/tutorial/LCU.rst | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index 5b4a5464f..dbf975253 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -26,7 +26,7 @@ So, you want to perform operations that aren't strictly allowed by the quantum c Enter the Linear Combination of Unitaries (LCU) protocol—a foundational quantum algorithmic primitive that lets you implement a non-unitary operator $A$ by cleverly expressing it as a weighted sum of unitary operators: .. math:: - A=\sum_ic_i \, U_i + A=\sum_ic_iU_i This is the quantum equivalent of ordering a custom pizza: you pick your favorite toppings (unitaries), assign them weights (coefficients), and hope the outcome is deliciously non-classical. @@ -39,13 +39,13 @@ The LCU protocol works by embedding your non-unitary operator into a larger, uni .. math :: - \mathrm{PREPARE} \, |0\rangle=\sum_i\sqrt{\frac{c_i}{\lambda}} \, |i\rangle + \mathrm{PREPARE}|0\rangle=\sum_i\sqrt{\frac{c_i}{\lambda}}|i\rangle - **SELECT**: Applies the unitary $U_i$ to the input state $\ket{\psi}$, controlled on the ancilla variable being in state $|i\rangle$. .. math :: - \mathrm{SELECT} \, |i\rangle|\psi\rangle=|i\rangle U_i \, |\psi\rangle + \mathrm{SELECT}|i\rangle|\psi\rangle=|i\rangleU_i|\psi\rangle - **PREPARE** $^\dagger$: Applies the inverse prepartion to the ancilla. @@ -134,7 +134,7 @@ First we have to prepare the ancilla variables with ``state_prep(case_indicator) We already learned about the SELECT operator in the theoretical overview. Here we put it in action using :func:`qrisp.qswitch` ``(operand, case_indicator, unitaries)``. This applies the correct unitary $U_i$ controlled on the ancilla. -the ``qrisp.conjugate`` environment ensures the inverse preparation (PREPARE` $^\dagger$) is applied after SELECT, matching the block-encoding structure. +the ``qrisp.conjugate`` environment ensures the inverse preparation (PREPARE$^\dagger$) is applied after SELECT, matching the block-encoding structure. The probability of success in LCU can be low, especially for certain coefficient choices. Qrisp allows you to boost this probability using oblivious amplitude amplification (OAA), which iteratively amplifies the "good" outcome. This is done by :func:`qrisp.amplitude_amplification`, which repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. The ``oaa_iter`` keyword controls how many amplification iterations are performed. @@ -164,13 +164,7 @@ The LCU protocol is only "successful" if, after running the block-encoded circui @RUS def LCU(operand_prep, state_prep, unitaries, num_unitaries=None, oaa_iter=0): - case_indicator, qv = inner_LCU( - operand_prep, - state_prep, - unitaries, - num_unitaries, - oaa_iter - ) + case_indicator, qv = inner_LCU(operand_prep, state_prep, unitaries, num_unitaries, oaa_iter) # Success condition success_bool = measure(case_indicator) == 0 From d8210d01291903dccf6cfe101458d0c7552e034c Mon Sep 17 00:00:00 2001 From: mat70593 Date: Thu, 24 Jul 2025 19:04:35 +0200 Subject: [PATCH 14/15] Removed the .qrisp in all functions. Thanks @Nik-SteinFraunh --- documentation/source/general/tutorial/LCU.rst | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index dbf975253..a871eb330 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -1,5 +1,7 @@ .. _LCU_tutorial: +.. currentmodule:: qrisp + Linear Combination of Unitaries (LCU) primitive and its applications ==================================================================== @@ -55,7 +57,7 @@ Success condition ^^^^^^^^^^^^^^^^^ The LCU protocol is deemed successful only if the ancilla variable is measured in the $\ket{0}$ state, which occurs with a probability proportional to :math:`\frac{\langle\psi|A^{\dagger}A|\psi\rangle}{\lambda^2}` where $\lambda=\sum_ic_i$. -The :func:`qrisp.inner_LCU` does not perform the measurement; it returns the ancilla variable and the transformed target variable. +The :func:`inner_LCU` does not perform the measurement; it returns the ancilla variable and the transformed target variable. The approach you’ve just studied was pioneered by Nathan Wiebe, whose contributions have fundamentally shaped the field of quantum algorithm design, particularly in Hamiltonian simulation and quantum linear systems. @@ -78,14 +80,14 @@ Let's take a closer look and disect the inner workings of these functions. .. _inner_LCU_tut: -Underlying protocol in two lines of code in :func:`qrisp.inner_LCU` +Underlying protocol in two lines of code in :func:`inner_LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:func:`qrisp.inner_LCU` implements the core LCU protocol (prepare-select/qswitch-unprepare), without the Repeat-Until_Success (RUS) protocol validating the correct execution of the primitive. +:func:`inner_LCU` implements the core LCU protocol (prepare-select/qswitch-unprepare), without the Repeat-Until_Success (RUS) protocol validating the correct execution of the primitive. At its core, the LCU protocol in Qrisp is realized by two key operations: preparing the ancilla in the right superposition (encoding the coefficients) and applying the controlled unitaries. The function ``inner_LCU`` exposes this structure directly, without any success-checking or repetition logic. -In order to have this tutorial reproduceable, this is the entire :func:`qrisp.inner_LCU`, as it is defined in the Qrisp repository: +In order to have this tutorial reproduceable, this is the entire :func:`inner_LCU`, as it is defined in the Qrisp repository: :: def inner_LCU(operand_prep, state_prep, unitaries, num_unitaries=None, oaa_iter=0): @@ -132,12 +134,12 @@ Unpacking the code (which packs a hefty punch) becomes self explenatory because First we have to prepare the ancilla variables with ``state_prep(case_indicator)``. This step transforms the ancilla in a superposition reflecting the coefficients $c_i$. -We already learned about the SELECT operator in the theoretical overview. Here we put it in action using :func:`qrisp.qswitch` ``(operand, case_indicator, unitaries)``. This applies the correct unitary $U_i$ controlled on the ancilla. +We already learned about the SELECT operator in the theoretical overview. Here we put it in action using :func:`qswitch` ``(operand, case_indicator, unitaries)``. This applies the correct unitary $U_i$ controlled on the ancilla. -the ``qrisp.conjugate`` environment ensures the inverse preparation (PREPARE$^\dagger$) is applied after SELECT, matching the block-encoding structure. +the ``conjugate`` environment ensures the inverse preparation (PREPARE$^\dagger$) is applied after SELECT, matching the block-encoding structure. The probability of success in LCU can be low, especially for certain coefficient choices. Qrisp allows you to boost this probability using oblivious amplitude amplification (OAA), which iteratively amplifies the "good" outcome. This is done by -:func:`qrisp.amplitude_amplification`, which repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. The ``oaa_iter`` keyword controls how many amplification iterations are performed. +:func:`amplitude_amplification`, which repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. The ``oaa_iter`` keyword controls how many amplification iterations are performed. The oracle tags the success state, and the reflection boosts its amplitude, increasing the chance of success in fewer repetitions. It is also possible to do too many iterations and therefore getting a lower probability of success, when we reflect beyond the ideal state. @@ -153,9 +155,9 @@ The oblivious amplitude amplification is then performed based on how many iterat .. _LCU_func_tut: -Success condition with :func:`qrisp.LCU` +Success condition with :func:`LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:func:`qrisp.LCU` wraps ``inner_LCU`` with a :ref:`repeat-until-success (RUS) routine ` protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. +:func:`LCU` wraps ``inner_LCU`` with a :ref:`repeat-until-success (RUS) routine ` protocol, repeatedly running the circuit until the ancilla is measured in the $\ket{0}$ state (the success condition described in theory). This matches the probabilistic nature of LCU’s success and automates the process for the user. The LCU protocol is only "successful" if, after running the block-encoded circuit, the ancilla is measured in the $\ket{0}$ state. Qrisp's ``LCU`` function wraps ``inner_LCU`` with :ref:`RUS `, automating this process. @@ -174,10 +176,10 @@ The ``measure(case_indicator) == 0`` checks if the ancillae are in the $\ket{0}$ .. _view_LCU_tut: -Underlying circuit (purely educational) with :func:`qrisp.view_LCU` +Underlying circuit (purely educational) with :func:`view_LCU` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For educational and debugging purposes, Qrisp provides :func:`qrisp.view_LCU`, which constructs and returns the explicit quantum circuit corresponding to your LCU protocol. This lets you see how the ancilla preparation, controlled unitaries, and inverse preparation are realized at the gate level. +For educational and debugging purposes, Qrisp provides :func:`view_LCU`, which constructs and returns the explicit quantum circuit corresponding to your LCU protocol. This lets you see how the ancilla preparation, controlled unitaries, and inverse preparation are realized at the gate level. :: From db7314f164b56ebebf3dc83dcd1805471610288f Mon Sep 17 00:00:00 2001 From: mat70593 Date: Thu, 24 Jul 2025 19:10:29 +0200 Subject: [PATCH 15/15] Reiterated the tutorial based on the feedback from @diehoq --- documentation/source/general/tutorial/LCU.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/documentation/source/general/tutorial/LCU.rst b/documentation/source/general/tutorial/LCU.rst index a871eb330..5828f1638 100644 --- a/documentation/source/general/tutorial/LCU.rst +++ b/documentation/source/general/tutorial/LCU.rst @@ -5,7 +5,7 @@ Linear Combination of Unitaries (LCU) primitive and its applications ==================================================================== -If you’ve ever wondered how to bend the rules of quantum mechanics (without actually breaking them), you’re in the right place. This tutorial is your roadmap to the Linear Combination of Unitaries (LCU) protocol—a powerful tool that lets you simulate non-unitary operations by cleverly mixing unitaries, opening doors to advanced quantum algorithms and simulations. +If you’ve ever wondered how to bend the rules of quantum mechanics (without actually breaking them), you’re in the right place. This tutorial is your roadmap to the Linear Combination of Unitaries (LCU) protocol, which is a powerful tool that lets you simulate non-unitary operations by cleverly mixing unitaries, opening doors to advanced quantum algorithms and simulations. Here’s what you’ll discover as you journey through this tutorial: @@ -13,7 +13,7 @@ Here’s what you’ll discover as you journey through this tutorial: - Next, we’ll roll up our sleeves and see how LCU comes alive in Qrisp (Frankenstein intensifies). This section is hands-on: you’ll explore annotated code examples, understand the structure of Qrisp’s LCU implementation, and see how to prepare ancilla variables, orchestrate controlled unitaries, and interpret the results. -- We won't stop at just understanding LCU, but instead also use it as an algorithmic building block (primitive) to perform another algorithm. In our final section, we combine the strengths of Trotterization and LCU to unlock the Linear Combination of Hamiltonian Simulation (LCHS) protocol. Here, you’ll learn how to simulate functions of Hamiltonians—like $\cos(H)$. +- We won't stop at just understanding LCU, but instead also use it as an algorithmic building block (primitive) to perform another algorithm. Then combine the strengths of Trotterization and LCU to unlock the Linear Combination of Hamiltonian Simulation (LCHS) protocol. Here, you’ll learn how to simulate functions of Hamiltonians with the example of $\cos(H)$. If all goes well (if not, let us know about which parts should be elaborated upon further), you'll be motivated to apply LCU and extend it to tackle `Quantum Signal Processing (QSP) `_, and/or `Quantum Singular Value Transformation (QSVT) `_. Until the implementation in Qrisp, the proof to this is left for the reader (which is not a broad time-window). @@ -49,7 +49,7 @@ The LCU protocol works by embedding your non-unitary operator into a larger, uni \mathrm{SELECT}|i\rangle|\psi\rangle=|i\rangleU_i|\psi\rangle -- **PREPARE** $^\dagger$: Applies the inverse prepartion to the ancilla. +- **PREPARE** $^\dagger$: Applies the conjugated/daggered prepartion unitary to the ancilla. .. image:: LCU.png @@ -73,7 +73,7 @@ With the theoretical foundation of the Linear Combination of Unitaries (LCU) pro Qrisp provides a collection of functions, three to be exact, that directly mirror the theoretical structure of LCU, allowing you to implement, visualize, and experiment with the protocol as described in the previous section: - :ref:`inner_LCU `: implements the core LCU protocol (prepare-select/qswitch-unprepare) without the Repeat-Until_Success (RUS) protocol. -- :ref:`LCU `: wraps inner_LCU with a repeat-until-success (RUS) routine protocol, repeatedly running the circuit until the ancilla is measured in the :math:`\ket{0}` state (the success condition described in the theory). +- :ref:`LCU `: wraps inner_LCU with a repeat-until-success (RUS) routine protocol, repeatedly running the circuit until the ancilla is measured in the :math:`\ket{0}` state (the success condition described in the theory section). - :ref:`view_LCU `: constructs and returns the explicit quantum circuit corresponding to your LCU protocol. Let's take a closer look and disect the inner workings of these functions. @@ -132,15 +132,15 @@ In order to have this tutorial reproduceable, this is the entire :func:`inner_LC Unpacking the code (which packs a hefty punch) becomes self explenatory because of the modularity that Qrisp offers through various modules. Let's unveil the concepts bit by bit. -First we have to prepare the ancilla variables with ``state_prep(case_indicator)``. This step transforms the ancilla in a superposition reflecting the coefficients $c_i$. +First we have to prepare the ancilla variables with ``state_prep(case_indicator)``. This step transforms the ancilla in a superposition reflecting the coefficients $c_i$ accordingly. We already learned about the SELECT operator in the theoretical overview. Here we put it in action using :func:`qswitch` ``(operand, case_indicator, unitaries)``. This applies the correct unitary $U_i$ controlled on the ancilla. the ``conjugate`` environment ensures the inverse preparation (PREPARE$^\dagger$) is applied after SELECT, matching the block-encoding structure. The probability of success in LCU can be low, especially for certain coefficient choices. Qrisp allows you to boost this probability using oblivious amplitude amplification (OAA), which iteratively amplifies the "good" outcome. This is done by -:func:`amplitude_amplification`, which repeatedly applies the LCU block and a reflection (oracle) to amplify the amplitude of the $\ket{0}$ state. The ``oaa_iter`` keyword controls how many amplification iterations are performed. -The oracle tags the success state, and the reflection boosts its amplitude, increasing the chance of success in fewer repetitions. +:func:`amplitude_amplification`, which repeatedly applies the LCU block and a reflection to amplify the amplitude of the $\ket{0}$ state. The ``oaa_iter`` keyword controls how many amplification iterations are performed. +The oracle keyword tags the success state, and the reflection boosts its amplitude, increasing the chance of success in fewer repetitions. It is also possible to do too many iterations and therefore getting a lower probability of success, when we reflect beyond the ideal state.