From 2311282245f959ab283f4cfaf23827833635728d Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Tue, 13 Aug 2024 11:30:15 +0100 Subject: [PATCH 01/11] update workflow and naming --- .github/workflows/check-docs-build.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/check-docs-build.yml b/.github/workflows/check-docs-build.yml index 2bb99148..2b0d1ac1 100644 --- a/.github/workflows/check-docs-build.yml +++ b/.github/workflows/check-docs-build.yml @@ -13,7 +13,7 @@ jobs: changes: runs-on: ubuntu-22.04 outputs: - manual: ${{ steps.filter.outputs.manual }} + user_guide: ${{ steps.filter.outputs.user_guide }} steps: - uses: actions/checkout@v4 - uses: dorny/paths-filter@v3 @@ -21,16 +21,16 @@ jobs: with: base: ${{ github.ref }} filters: | - manual: - - 'manual/**' - - 'manual_requirements.txt' - - 'manual_constraints.txt' + user guide: + - 'docs/**' - '.github/**' + - 'pyproject.toml' + - 'poetry.lock' check: name: check docs build needs: changes - if: github.event_name == 'schedule' || needs.changes.outputs.manual == 'true' + if: github.event_name == 'schedule' || needs.changes.outputs.user_guide == 'true' runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 @@ -50,6 +50,6 @@ jobs: run: | sudo apt-get update sudo apt-get install graphviz - - name: build manual and examples + - name: build manual and examples (user guide) run: | poetry run ./build-docs.sh From 3d9c069949fa370c44cff127876706c705af88fd Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Tue, 13 Aug 2024 11:32:19 +0100 Subject: [PATCH 02/11] test bumping pytket version --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 5cc1ca69..ce154fc3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,7 @@ readme = "README.md" [tool.poetry.dependencies] python = "^3.10" -pytket = { extras = ["zx"], version = "^1.28.0" } +pytket = { extras = ["zx"], version = "^1.31.0" } pytket-qiskit = "^0.53.0" pytket-cirq = "^0.36.0" pytket-qujax = "0.19.0" From 7516fa6a92f827e0ebdcdf87379e89a1ba243bf6 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Tue, 13 Aug 2024 11:33:03 +0100 Subject: [PATCH 03/11] Revert "test bumping pytket version" This reverts commit 3d9c069949fa370c44cff127876706c705af88fd. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index ce154fc3..5cc1ca69 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,7 @@ readme = "README.md" [tool.poetry.dependencies] python = "^3.10" -pytket = { extras = ["zx"], version = "^1.31.0" } +pytket = { extras = ["zx"], version = "^1.28.0" } pytket-qiskit = "^0.53.0" pytket-cirq = "^0.36.0" pytket-qujax = "0.19.0" From 22b588f22efee6390b2b922acd3bcf276ac31c05 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Tue, 13 Aug 2024 14:38:36 +0100 Subject: [PATCH 04/11] start writing TKET tips page --- docs/manual/tket_tips.md | 67 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/manual/tket_tips.md diff --git a/docs/manual/tket_tips.md b/docs/manual/tket_tips.md new file mode 100644 index 00000000..ca5a06b5 --- /dev/null +++ b/docs/manual/tket_tips.md @@ -0,0 +1,67 @@ +--- +file_format: mystnb +kernelspec: + name: python3 +--- + + +# TKET Tips + +## 1. How do I take the tensor product between two circuits? + +You can compose two circuits side by side by taking the tensor product with the `*` operator + +```{code-cell} ipython3 +--- +tags: [skip-execution] +--- +circ1 * circ2 +``` + +Note that the two circuits need to have qubits with distinct names. +See the docs on circuit composition. + +## 2. How can I export an image of my circuit? + + +You can export pytket circuits to LaTeX with the `Circuit.to_latex_file` method. This is handy for using circuit images in papers if you like using the Quantikz library. + +```{code-cell} ipython3 +--- +tags: [skip-execution] +--- +from pytket import Circuit + +circ = Circuit(2).CX(0, 1).Rz(0.61, 1).CX(0, 1) # Build circuit + +circ.to_latex_file("phase_gadget.tex") # Generates a phase_gadget.tex file +``` + +Alternatively you could use the svg image export in the circuit renderer. + +## 3. Can I do symbolic calculations in pytket? + +Yes! You can use the `pytket.utils.symbolic module` to calculate symbolic unitaries and statevectors for small pytket circuits. +Here we can use the circuit_to_symbolic_unitary function to calculate the unitary of a small parameterised circuit. If using a jupyter notebook we get a nice LaTeX rendering of the matrix (see image) + +```{code-cell} ipython3 +from pytket import Circuit +from pytket.circuit.display import render_circuit_jupyter as draw +from pytket.utils.symbolic import circuit_to_symbolic_unitary +from sympy import symbols + +a, b = symbols("a b") +circ = Circuit(2) +circ.X(0).CRy(a, 0, 1).Rz(b, 0) + +draw(circ) # Draw circuit diagram +circuit_to_symbolic_unitary(circ) # Get the symbolic unitary matrix +``` + +## 4. Do I have to use a jupyter notebook to use these interactive circuit diagrams? + +No you don't have to! if you prefer using python scripts or the terminal instead of junotebooks you can use the `view_browser` function to view the rendered circuit in a pop up browser window. + + + + From 0231a29377d42c0c6e5c89d6437b4bc600073311 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Tue, 13 Aug 2024 14:41:04 +0100 Subject: [PATCH 05/11] add document to index --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index a8597742..0b10352b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -134,6 +134,7 @@ for more. manual/manual_noise.rst manual/manual_assertion.rst manual/manual_zx.rst + manual/tket_tips.md .. toctree:: :glob: From 5cfb20c7125888b45da217bc344a0a0c0195d92a Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Tue, 13 Aug 2024 14:42:16 +0100 Subject: [PATCH 06/11] Revert "update workflow and naming" This reverts commit 2311282245f959ab283f4cfaf23827833635728d. --- .github/workflows/check-docs-build.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/check-docs-build.yml b/.github/workflows/check-docs-build.yml index 2b0d1ac1..2bb99148 100644 --- a/.github/workflows/check-docs-build.yml +++ b/.github/workflows/check-docs-build.yml @@ -13,7 +13,7 @@ jobs: changes: runs-on: ubuntu-22.04 outputs: - user_guide: ${{ steps.filter.outputs.user_guide }} + manual: ${{ steps.filter.outputs.manual }} steps: - uses: actions/checkout@v4 - uses: dorny/paths-filter@v3 @@ -21,16 +21,16 @@ jobs: with: base: ${{ github.ref }} filters: | - user guide: - - 'docs/**' + manual: + - 'manual/**' + - 'manual_requirements.txt' + - 'manual_constraints.txt' - '.github/**' - - 'pyproject.toml' - - 'poetry.lock' check: name: check docs build needs: changes - if: github.event_name == 'schedule' || needs.changes.outputs.user_guide == 'true' + if: github.event_name == 'schedule' || needs.changes.outputs.manual == 'true' runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 @@ -50,6 +50,6 @@ jobs: run: | sudo apt-get update sudo apt-get install graphviz - - name: build manual and examples (user guide) + - name: build manual and examples run: | poetry run ./build-docs.sh From 20e430ada6dbe6ce3fdbb40ca7be0b564e0d176a Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Fri, 23 Aug 2024 00:19:24 +0100 Subject: [PATCH 07/11] expand tips and use robust linking --- docs/manual/tket_tips.md | 80 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 75 insertions(+), 5 deletions(-) diff --git a/docs/manual/tket_tips.md b/docs/manual/tket_tips.md index ca5a06b5..0627f207 100644 --- a/docs/manual/tket_tips.md +++ b/docs/manual/tket_tips.md @@ -23,8 +23,19 @@ See the docs on circuit composition. ## 2. How can I export an image of my circuit? +There are multiple ways to do this. Firstly you can use the image export button in the interactive circuit renderer. -You can export pytket circuits to LaTeX with the `Circuit.to_latex_file` method. This is handy for using circuit images in papers if you like using the Quantikz library. +Try clicking the export button in the top right of the circuit diagram below. + +```{code-cell} ipython3 +from pytket import Circuit +from pytket.circuit.display import render_circuit_jupyter as draw + +circ = Circuit(2).CX(0, 1).Rz(0.61, 1).CX(0, 1) # Build circuit +draw(circ) +``` + +You can also export pytket circuits to LaTeX with the [Circuit.to_latex_file](inv:#*.Circuit.to_latex_file) method. This is handy for using circuit images in papers if you like using the Quantikz library. ```{code-cell} ipython3 --- @@ -37,12 +48,11 @@ circ = Circuit(2).CX(0, 1).Rz(0.61, 1).CX(0, 1) # Build circuit circ.to_latex_file("phase_gadget.tex") # Generates a phase_gadget.tex file ``` -Alternatively you could use the svg image export in the circuit renderer. ## 3. Can I do symbolic calculations in pytket? -Yes! You can use the `pytket.utils.symbolic module` to calculate symbolic unitaries and statevectors for small pytket circuits. -Here we can use the circuit_to_symbolic_unitary function to calculate the unitary of a small parameterised circuit. If using a jupyter notebook we get a nice LaTeX rendering of the matrix (see image) +Yes! You can use the `pytket.utils.symbolic` module to calculate symbolic unitaries and statevectors for small pytket circuits. +Here we can use the [circuit_to_symbolic_unitary](inv:#*.circuit_to_symbolic_unitary) function to calculate the unitary of a small parameterised circuit. If using a jupyter notebook we get a nice LaTeX rendering of the matrix (see image) ```{code-cell} ipython3 from pytket import Circuit @@ -60,7 +70,67 @@ circuit_to_symbolic_unitary(circ) # Get the symbolic unitary matrix ## 4. Do I have to use a jupyter notebook to use these interactive circuit diagrams? -No you don't have to! if you prefer using python scripts or the terminal instead of junotebooks you can use the `view_browser` function to view the rendered circuit in a pop up browser window. +No you don't have to! if you prefer using python scripts or the terminal instead of jupyter notebooks you can use the [view_browser](inv:#*.CircuitRenderer.view_browser) function to view the rendered circuit in a pop up browser window. + +## 5. Clifford circuit basics in pytket + +Clifford circuits are an important (non-universal) subclass of quantum circuits known to exhibit efficient classical simulation. The $\{H, S, CX\}$ gates are the typical Clifford generators. These circuits are particularly relevant for quantum error correction. + +Its easy to check whether your pytket Circuit is Clifford by using the [CliffordCircuitPredicate](inv:#*.CliffordCircuitPredicate). + + +```{code-cell} ipython3 +from pytket import Circuit +from pytket.predicates import CliffordCircuitPredicate + +circ = Circuit(2).H(0).CX(0, 1).S(0).CX(0, 1).H(0) # Build Clifford Circuit + +print(CliffordCircuitPredicate().verify(circ)) # prints True, circ is Clifford + +circ.Rz(0.91, 0) # Add non-Clifford gate + +print(CliffordCircuitPredicate().verify(circ)) # prints False, circ is non-Clifford +``` + +Given a circuit operation, we can check whether it is Clifford by using the [Op.is_clifford](inv:#*.Op.is_clifford) method + + + +```{code-cell} ipython3 +for command in circ: + print(command.op, command.op.is_clifford()) + # Only the Rz gate is non-Clifford +``` + +Finally if you want to simulate large Clifford circuits you can access the Stim and Simplex simulators from pytket through their extension modules. + +pytket-stim - https://github.com/CQCL/pytket-stim +pytket-pysimplex - https://github.com/CQCL/pytket-pysimplex + + +## 6. How can I check two quantum circuits for unitary equivalence? + + +```{code-cell} ipython3 +from pytket import Circuit +from pytket.utils import compare_unitaries + +# Create two simple circuits +circ1 = Circuit(3).CX(0, 2).CX(1, 2).Rz(0.74, 2).CX(1, 2).CX(0, 2) +circ2 = Circuit(3).CX(0, 1).CX(1, 2).Rz(0.74, 2).CX(1, 2).CX(0, 1) + +# Simulate circuits to calculate the unitaries +unitary1 = circ1.get_unitary() +unitary2 = circ2.get_unitary() + + +# Compare up to a global phase +compare_unitaries(unitary1, unitary2) +``` + + + + From 34adeadb5711e05a531c1cd13449249321c33341 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Fri, 23 Aug 2024 01:09:25 +0100 Subject: [PATCH 08/11] minor fixes and Quantikz image --- docs/manual/images/phase_gadget_latex.png | Bin 0 -> 40248 bytes docs/manual/tket_tips.md | 26 +++++++++++++++++++--- 2 files changed, 23 insertions(+), 3 deletions(-) create mode 100644 docs/manual/images/phase_gadget_latex.png diff --git a/docs/manual/images/phase_gadget_latex.png b/docs/manual/images/phase_gadget_latex.png new file mode 100644 index 0000000000000000000000000000000000000000..b49357cbe0a83fb5cfb9dfeec1d81bc0859a0703 GIT binary patch literal 40248 zcmeFZbyQSe+c%B~NJ>dc3?LvPAktkb(hAZgB_b_3bhm_*w5SL&bjQ%$O6MSrqzv7^ zJwD$@@Avju@B94wTkCc$oZ+0a_u1FAuf9H;&?m~W1h~|=XlQ5za*rRVqM>0R(a^4> zVq<|TYJ!nfXlVEn7BVtViLwg(=uX#;Nt&2Qe_ieP~%PSb40uUH6 z)ROYp96ozCOt-E`hjJ4=+vxn@XDQW&&hM!Hpm=B_B<*3*VVj>{2`BkRcgl^gPKL(_ zkJ;(tZ3*)Whvn%c_ieQI&TpAWmfo+SE#mIBaW`G;eOkOB{N>tvNs8xxJR@(R@Lion%ZIR`Quw-<2& z&~m;p9CY=iHTw&a8C$+&^3%#4czi0wx?r1Z(UMG~+^VO28-5ZD^ZxKT`->6-@!LLUV@4WY<=1|cAkZg5tbX2@ z*CWDu{k`r1zr5fE#}!fEi0||Wp`zDDaG@gk(@QalRxk5+(Kwp--ZDfvmNO_AL%4k? zrSTajzn@eQZUqLn!07Xo1+N}bCU>~FH>*jr&JoWEXNKFkm%M*`rWUs#Nij^Qy2!ZM zq4z!E$q?CLM_s1yvvwyt&*xFKk`jv36mHIecNK^$dD-_e$}ai+>C=OnBR3vD>SF5j zGF{J*&7I7xxej~maBkwYSp1n_C53N#x72%-aAKv2f5TkCirAS*Bsi^^^SNv>mSl(W z^EX;IofX4^HOELN)~J!>OyR6I*RU_qX_FvJi~<5(1q_#h%AT#W`fukSQ8wEbW5}cAsSo-|N3>hX z(-%s!LY7!(j<>Jc)rYbZQ*;XHxiK_W22f91xHV$GyJ9Iw&-xt;?n94_kqIGb^)
d`kiDIZLCSZ%B`je?<*m~ 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 literal 0 HcmV?d00001 diff --git a/docs/manual/tket_tips.md b/docs/manual/tket_tips.md index 0627f207..461a451f 100644 --- a/docs/manual/tket_tips.md +++ b/docs/manual/tket_tips.md @@ -19,7 +19,7 @@ circ1 * circ2 ``` Note that the two circuits need to have qubits with distinct names. -See the docs on circuit composition. +See the docs on [circuit composition](https://tket.quantinuum.com/user-guide/manual/manual_circuit.html#composing-circuits). ## 2. How can I export an image of my circuit? @@ -48,6 +48,26 @@ circ = Circuit(2).CX(0, 1).Rz(0.61, 1).CX(0, 1) # Build circuit circ.to_latex_file("phase_gadget.tex") # Generates a phase_gadget.tex file ``` +This generates a `phase_gadget.tex` file in the working directory. + +```latex +\documentclass[tikz]{standalone} +\usetikzlibrary{quantikz} +\begin{document} +\begin{quantikz} +\lstick{q[0]} & \ctrl{1} & \qw & \ctrl{1} & \qw \\ +\lstick{q[1]} & \targ{} & \gate[1]{\text{$R_Z$(0.61)}} & \targ{} & \qw \\ +\end{quantikz} +\end{document} +``` + +If we compile this LaTeX we get the following Quantikz image. + + +```{image} ./images/phase_gadget_latex.png +:align: center +:width: 400px +``` ## 3. Can I do symbolic calculations in pytket? @@ -124,8 +144,8 @@ unitary1 = circ1.get_unitary() unitary2 = circ2.get_unitary() -# Compare up to a global phase -compare_unitaries(unitary1, unitary2) +# Compare unitaries up to a global phase +print("Do the unitaries match?", compare_unitaries(unitary1, unitary2)) ``` From 732a22ec1a1131b3bb057c4f54d2b97bb8e2da04 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Fri, 23 Aug 2024 01:20:55 +0100 Subject: [PATCH 09/11] improve section on image exports --- docs/manual/tket_tips.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/manual/tket_tips.md b/docs/manual/tket_tips.md index 461a451f..23745b50 100644 --- a/docs/manual/tket_tips.md +++ b/docs/manual/tket_tips.md @@ -23,7 +23,9 @@ See the docs on [circuit composition](https://tket.quantinuum.com/user-guide/man ## 2. How can I export an image of my circuit? -There are multiple ways to do this. Firstly you can use the image export button in the interactive circuit renderer. +### Method 1: Using the circuit renderer + +Firstly you can use the image export button in the interactive circuit renderer. Exporting to `.png`, `.jpeg`, and `.svg` images is supported. Try clicking the export button in the top right of the circuit diagram below. @@ -35,6 +37,8 @@ circ = Circuit(2).CX(0, 1).Rz(0.61, 1).CX(0, 1) # Build circuit draw(circ) ``` +### Method 2: Generating a `.tex` file from the `Circuit` + You can also export pytket circuits to LaTeX with the [Circuit.to_latex_file](inv:#*.Circuit.to_latex_file) method. This is handy for using circuit images in papers if you like using the Quantikz library. ```{code-cell} ipython3 From 603a9967cc2487297fa5ab5af8db769a277dd622 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Fri, 23 Aug 2024 01:33:19 +0100 Subject: [PATCH 10/11] add some more circuit diagrams and fix github links --- docs/manual/tket_tips.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/manual/tket_tips.md b/docs/manual/tket_tips.md index 23745b50..7398de49 100644 --- a/docs/manual/tket_tips.md +++ b/docs/manual/tket_tips.md @@ -18,7 +18,7 @@ tags: [skip-execution] circ1 * circ2 ``` -Note that the two circuits need to have qubits with distinct names. +Note that the two circuits need to have qubits with distinct names for the tensor product to be well defined. See the docs on [circuit composition](https://tket.quantinuum.com/user-guide/manual/manual_circuit.html#composing-circuits). ## 2. How can I export an image of my circuit? @@ -106,17 +106,28 @@ Its easy to check whether your pytket Circuit is Clifford by using the [Clifford ```{code-cell} ipython3 from pytket import Circuit from pytket.predicates import CliffordCircuitPredicate +from pytket.circuit.display import render_circuit_jupyter as draw -circ = Circuit(2).H(0).CX(0, 1).S(0).CX(0, 1).H(0) # Build Clifford Circuit +circ = Circuit(2).H(0).CX(0, 1).CX(1, 0).S(1) # Build Clifford Circuit +draw(circ) -print(CliffordCircuitPredicate().verify(circ)) # prints True, circ is Clifford +print("Is circuit Clifford?", + CliffordCircuitPredicate().verify(circ)) # prints True, circ is Clifford +``` +Now, if we add a non-Clifford gate +```{code-cell} ipython3 circ.Rz(0.91, 0) # Add non-Clifford gate +draw(circ) +``` + -print(CliffordCircuitPredicate().verify(circ)) # prints False, circ is non-Clifford +```{code-cell} ipython3 +print("Is circuit Clifford?", + CliffordCircuitPredicate().verify(circ)) # prints False, circ is non-Clifford ``` -Given a circuit operation, we can check whether it is Clifford by using the [Op.is_clifford](inv:#*.Op.is_clifford) method +Given an individual circuit operation, we can check whether it is Clifford by using the [Op.is_clifford](inv:#*.Op.is_clifford) method @@ -128,8 +139,9 @@ for command in circ: Finally if you want to simulate large Clifford circuits you can access the Stim and Simplex simulators from pytket through their extension modules. -pytket-stim - https://github.com/CQCL/pytket-stim -pytket-pysimplex - https://github.com/CQCL/pytket-pysimplex +pytket-stim - + +pytket-pysimplex - ## 6. How can I check two quantum circuits for unitary equivalence? From 7ed41f249799d3a2ea59f0fea5aaf15bd6a3c841 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Fri, 23 Aug 2024 01:37:58 +0100 Subject: [PATCH 11/11] tket -> TKET --- docs/manual/manual_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manual/manual_intro.rst b/docs/manual/manual_intro.rst index 0652427f..75ef6946 100644 --- a/docs/manual/manual_intro.rst +++ b/docs/manual/manual_intro.rst @@ -1,5 +1,5 @@ ************* -What is tket? +What is TKET? ************* .. Two-sentence overview