further progress on codebase cleanup and readme

Author: amicciche

README.md

@@ -1,6 +1,7 @@
 # CircuitCompilation2xn
-CircuitCompilation2xn offers some tools to manipulate syndrome extracting circuits for better use on 2xn quantum dot hardwares. For more information please refer to the [paper](https://arxiv.org/abs/2501.09061) , and if one would desire to cite this tool, please cite the paper.
-## How to use this?
+CircuitCompilation2xn offers some tools to manipulate syndrome extracting circuits for better use on 2xn quantum dot hardwares. For more information please refer to our [paper](https://arxiv.org/abs/2501.09061) , and if one would desire to cite this tool, please cite the paper.
+
+## Tutorial
 First, we state that this work is closely integrated with [QuantumClifford.jl](https://github.com/QuantumSavory/QuantumClifford.jl) 
 
 To begin, we will need either a parity check matrix (or stabilizer tableau), or a `Vector{QuantumClifford.AbstractOperation}` containing the syndrome extracting circuit. Currently, we enforce the constraint that syndrome extracting circuit will always be of a form where the two qubit gates act one one qubit in the data qubit region and one in the ancilla region (i.e. there are two qubit gates that go between data or ancilla qubits). 
@@ -9,6 +10,10 @@ To begin, we will need either a parity check matrix (or stabilizer tableau), or
 
 ![Figure 3 from paper:](assets/images/syndrome_circuits.png)
 
+From here on, this tutorial will contain a few examples, divided into sections below:
+- Naive syndrome circuits example
+- Shor syndrome circuits example
+
 ### Naive syndrome circuits example
 First we will need a error correction code, and while any will do, let's use one that's already defined within `QuantumClifford.jl`, and is quite pedagogical. Furthermore, one might want to consider the X and Z checks seperately to guarantee commutativity, however for this first example and for simplicity, we will consider them together. (This is addressed later in this README)
 
@@ -63,6 +68,125 @@ Now we can use CircuitCompilation2xn to compile this circuit in different ways,
 
 ```
 using CircuitCompilation2xn
+non_mz, mz = CircuitCompilation2xn.two_qubit_sieve(scirc)
+```
+`two_qubit_sieve` splits the input circuit into two-qubit gates, and non two-quibit gates, which for both types of syndrome extraction currently available in `QuantumClifford.jl`, will just consist two qubit gates and measurements. If cat states are used in the syndrome extracting circuit, those will need to be removed prior to using `two_qubit_sieve`. This function now gives us with only the two qubit gates in the first item returned, in this example `non_mz`:
+
+![Uncompiled naive Steane7 circuit's two qubit gates](assets/images/naive_steane_nonmz.png)
+
+The `calculate_shifts` function is used to evaluate the required shuttling operations required carry out the provided circuit. It returns a vector of vectors, each corresponding to a subcircuit that can be run in parallel. The length of this is then the number of shuttles required. Unsurprisingly, not doing any compilation leads to a requirement of quite a few shuttle operations:
+```
+julia> CircuitCompilation2xn.calculate_shifts(non_mz)
+24-element Vector{Vector{QuantumClifford.AbstractOperation}}:
+ [sXCX(4,8)]
+ [sXCX(5,8)]
+ [sXCX(6,8)]
+ [sXCX(7,8)]
+ [sXCX(2,9)]
+ [sXCX(3,9)]
+ [sXCX(6,9)]
+ [sXCX(7,9)]
+ [sXCX(1,10)]
+ [sXCX(3,10)]
+ [sXCX(5,10)]
+ [sXCX(7,10)]
+ [sCNOT(4,11)]
+ [sCNOT(5,11)]
+ [sCNOT(6,11)]
+ [sCNOT(7,11)]
+ [sCNOT(2,12)]
+ [sCNOT(3,12)]
+ [sCNOT(6,12)]
+ [sCNOT(7,12)]
+ [sCNOT(1,13)]
+ [sCNOT(3,13)]
+ [sCNOT(5,13)]
+ [sCNOT(7,13)]
+```
+
+We can trivially reduce this number by sorting the gates by their $\delta$ values as described in our [paper](https://arxiv.org/abs/2501.09061). 
+
+```
+julia> gate_shuffled_circ = CircuitCompilation2xn.gate_shuffle_circ(non_mz)
+julia> CircuitCompilation2xn.calculate_shifts(gate_shuffled_circ)
+11-element Vector{Vector{QuantumClifford.AbstractOperation}}:
+ [sXCX(7,8)]
+ [sXCX(6,8), sXCX(7,9)]
+ [sXCX(5,8), sXCX(6,9), sXCX(7,10)]
+ [sXCX(4,8), sCNOT(7,11)]
+ [sXCX(5,10), sCNOT(6,11), sCNOT(7,12)]
+ [sXCX(3,9), sCNOT(5,11), sCNOT(6,12), sCNOT(7,13)]
+ [sXCX(2,9), sXCX(3,10), sCNOT(4,11)]
+ [sCNOT(5,13)]
+ [sXCX(1,10), sCNOT(3,12)]
+ [sCNOT(2,12), sCNOT(3,13)]
+ [sCNOT(1,13)]
+```
+
+This circuit visualized with Quantikz:
+![Gate shuffled naive Steane7 circuit](assets/images/naive_steane_gate_shuffled.png)
+
+To further compile this, we can use the block packing heuristics also called AHR in our [paper](https://arxiv.org/abs/2501.09061)
+
+```
+julia> ahr_circ, ahr_order = CircuitCompilation2xn.ancil_reindex_pipeline(non_mz);
+julia> CircuitCompilation2xn.calculate_shifts(ahr_circ)
+9-element Vector{Vector{QuantumClifford.AbstractOperation}}:
+ [sXCX(7,8)]
+ [sCNOT(7,9)]
+ [sXCX(7,10), sXCX(5,8)]
+ [sXCX(6,10), sCNOT(7,11), sCNOT(5,9)]
+ [sXCX(7,12), sXCX(3,8), sCNOT(6,11)]
+ [sXCX(6,12), sCNOT(7,13), sCNOT(3,9)]
+ [sXCX(5,12), sXCX(3,10), sXCX(1,8), sCNOT(6,13)]
+ [sXCX(4,12), sXCX(2,10), sCNOT(5,13), sCNOT(3,11), sCNOT(1,9)]
+ [sCNOT(4,13), sCNOT(2,11)]
+ julia> ahr_circ
+```
+
+![AHR naive Steane](assets/images/naive_steane_ahr.png)
+
+The `ancil_reindex_pipeline` function returns first the reindexed circuit, and second a dictionary which was used to reindex the circuit. The function itself tries a variety of heurisitics and then picks the best one. Gate shuffling is also automatically applied. In the naive syndrome case, we won't need to relabel the measurement circuit (as they are all Z measurements), but for Shor syndrome extraction these dicitonaries will be needed to relabel the cat state generation. For thoroughness this is how one would generally finish up piecing the reindexed circuit back together:
+
+```
+julia> new_mz = CircuitCompilation2xn.reindex_by_dict(mz, ahr_order)
+julia> vcat(ahr_circ, new_mz)
+```
+
+![AHR naive Steane full](assets/images/naive_steane_ahr_full.png)
+
+
+Another thing to note: `ancil_reindex_pipeline`  applies the `two_qubit_sieve` function automatically, and then reindexes the qubits in the non-qubit portions as well, so we just as well could have done:
+
+```
+julia> scirc, _ = QuantumClifford.ECC.naive_syndrome_circuit(code);
+julia> code = Steane7();
+julia> ahr, _ = CircuitCompilation2xn.ancil_reindex_pipeline(scirc);
+julia> ahr
+```
+
+While not mentioned in the paper, for in practice it never affected Shor-style syndrome extraction, on naive syndrome circuit one can instead fix the ancilla and reindex the data qubits instead to achieve a reduction in shuttles with the same simple heuristic techniques：
+
+```
+julia> code = Steane7();
+julia> scirc, _ = QuantumClifford.ECC.naive_syndrome_circuit(code);
+julia> data_comp_circ, data_order = CircuitCompilation2xn.data_ancil_reindex(scirc, numQubits);
+julia> CircuitCompilation2xn.calculate_shifts(data_comp_circ)
+7-element Vector{Vector{QuantumClifford.AbstractOperation}}:
+ [sXCX(4,8), sXCX(6,10)]
+ [sCNOT(4,9), sCNOT(6,11), sXCX(3,8), sXCX(7,12), sXCX(5,10)]
+ [sXCX(4,10), sXCX(6,12), sCNOT(3,9), sCNOT(7,13), sXCX(2,8), sCNOT(5,11)]
+ [sCNOT(4,11), sCNOT(6,13), sCNOT(2,9), sXCX(1,8)]
+ [sXCX(4,12), sXCX(2,10), sCNOT(1,9)]
+ [sCNOT(4,13), sXCX(3,12), sCNOT(2,11)]
+ [sCNOT(3,13)]
+julia> data_comp_circ
 ```
+![Data compiled Steane circuit](assets/images/naive_steane_data.png)
 
+Note that if using an encoding circuit for simulation, that will also need to be reindexed if you reindex the data qubits:
+```
+julia> ecirc = QuantumClifford.ECC.naive_encoding_circuit(code)
+```
+## Further information
 README under construction....

assets/images/naive_steane_ahr.png

@@ -12,10 +12,6 @@ using NPZ
 using LDPCDecoders
 using SparseArrays
 
-threeRepCode = [sCNOT(1,4),sCNOT(2,4),sCNOT(2,5),sCNOT(3,5)]
-k4_example = [sCNOT(1,4),sCNOT(3,4),sCNOT(2,5),sCNOT(2,4),sCNOT(2,7),sCNOT(3,6),sCNOT(3,5)]
-example_that_broke_h1= [sCNOT(5,6), sCNOT(3,6),sCNOT(1,6),sCNOT(4,7),sCNOT(2,7),sCNOT(4,8)]
-
 struct qblock
     elements::Vector{Int}
     ancil::Int
@@ -326,56 +322,56 @@ function ancil_reindex_pipeline(circuit, inverted=false)
     blocks = create_blocks(circuit)
 
     h1_order = ancil_sort_h1(blocks)
-    h1_circuit = perfect_reindex(circuit, h1_order)
+    h1_circuit = reindex_by_dict(circuit, h1_order)
     h1_batches = gate_Shuffle(h1_circuit)
 
     h2_order = ancil_sort_h2(blocks)
-    h2_circuit = perfect_reindex(circuit, h2_order)
+    h2_circuit = reindex_by_dict(circuit, h2_order)
     h2_batches = gate_Shuffle(h2_circuit)
 
     h3_order = ancil_sort_h3(blocks)
-    h3_circuit = perfect_reindex(circuit, h3_order)
+    h3_circuit = reindex_by_dict(circuit, h3_order)
     h3_batches = gate_Shuffle(h3_circuit)
 
     iden_order = identity_sort(blocks)
-    iden_circuit = perfect_reindex(circuit, iden_order)
+    iden_circuit = reindex_by_dict(circuit, iden_order)
     iden_batches = gate_Shuffle(iden_circuit)
 
     # Returns the best reordered circuit
     if length(h1_batches)<=length(h2_batches) && length(h1_batches)<=length(iden_batches) && length(h1_batches)<=length(h3_batches)
         new_circuit = h1_circuit
         if !inverted
-            new_mz = perfect_reindex(measurement_circuit,h1_order)
+            new_mz = reindex_by_dict(measurement_circuit,h1_order)
         end
         order = h1_order
-        println("H1")
+        #println("H1")
     elseif length(h2_batches)<=length(h1_batches) && length(h2_batches)<=length(iden_batches) && length(h2_batches)<=length(h3_batches)
         new_circuit = h2_circuit 
         if !inverted
-            new_mz = perfect_reindex(measurement_circuit,h2_order)
+            new_mz = reindex_by_dict(measurement_circuit,h2_order)
         end
         order = h2_order
-        println("H2")
+        #println("H2")
     elseif length(h3_batches)<=length(h1_batches) && length(h3_batches)<=length(iden_batches) && length(h3_batches)<=length(h2_batches)
         new_circuit = h3_circuit
         if !inverted
-            new_mz = perfect_reindex(measurement_circuit,h3_order)
+            new_mz = reindex_by_dict(measurement_circuit,h3_order)
         end
         order = h3_order
-        println("H3")
+        #println("H3")
     else 
         new_circuit = iden_circuit
         if !inverted
-            new_mz = perfect_reindex(measurement_circuit,iden_order)
+            new_mz = reindex_by_dict(measurement_circuit,iden_order)
         end
         order = iden_order
-        println("IDEN")
+        #println("IDEN")
     end
 
     if inverted
         new_mz = measurement_circuit
     end
-    return vcat(gate_Shuffle!(new_circuit), new_mz), order
+    return vcat(gate_shuffle_circ(new_circuit), new_mz), order
 end
 
 """Special case of the reindexing pipeline that exploits the structure of Shor syndrome circuits"""
@@ -389,13 +385,13 @@ function ancil_reindex_pipeline_shor_syndrome(scirc, extra_info=false)
         order = shor_syndrome_sort(blocks)
     end
 
-    new_circuit = perfect_reindex(scirc, order)
-    new_mz = perfect_reindex(measurement_circuit, order)
+    new_circuit = reindex_by_dict(scirc, order)
+    new_mz = reindex_by_dict(measurement_circuit, order)
 
     if extra_info
-        return vcat(gate_Shuffle!(new_circuit), new_mz), order, chain_info
+        return vcat(gate_shuffle_circ(new_circuit), new_mz), order, chain_info
     else
-        return vcat(gate_Shuffle!(new_circuit), new_mz), order
+        return vcat(gate_shuffle_circ(new_circuit), new_mz), order
     end
 end
 
@@ -433,9 +429,8 @@ function gate_Shuffle(circuit)
     calculate_shifts(circuit)
 end
 
-# TODO Absolutely horrible name
-"""Sorts by [`get_delta`](@ref) and then returns the circuirt. One needs to do circ = gate_Shuffle!(circ)"""
-function gate_Shuffle!(circuit) # TODO 
+"""Sorts by [`get_delta`](@ref) and then returns the circuit. Legacy note, used to be called gate_Shuffle!"""
+function gate_shuffle_circ(circuit) 
     non_mz, mz = two_qubit_sieve(circuit)
     new_circ = sort!(non_mz, by = x -> get_delta(x))
     return vcat(new_circ, mz)
@@ -479,7 +474,7 @@ function ancil_sort_h2(blockset, startAncil=nothing)
     return order
 end
 
-"""Sorts first by total length of the block visualation and secondarily by the ghost length"""
+"""Sorts by the two norm of the total and ghost length"""
 function ancil_sort_h3(blockset, startAncil=nothing)
     if isnothing(startAncil)
         sort!(blockset, by = x -> (x.ancil), rev=false)
@@ -498,8 +493,8 @@ function ancil_sort_h3(blockset, startAncil=nothing)
     return order
 end
 
-"""This function should replace all other reindexing functions, and should work on an entire circuit."""
-function perfect_reindex(circ, order::Dict)
+"""This function should replace all other reindexing functions, and should work on an entire circuit. Legacy Note: used to be called perfect_reindex"""
+function reindex_by_dict(circ, order::Dict)
     function new_index(index::Int)
        get(order,index,index) 
     end
@@ -721,12 +716,13 @@ function shorNumbers(circuit)
     return shifts
 end
 
-function randCircuit(n, wr, wc)
-    H = LDPCDecoders.parity_check_matrix(n, wr, wc)
-    checks = Stabilizer(H, zeros(Bool, size(H)))
-    cat, scirc, _ = QuantumClifford.ECC.shor_syndrome_circuit(checks)
-    return scirc
-end
+# TODO delete after ensuring this is never used
+# function randCircuit(n, wr, wc)
+#     H = LDPCDecoders.parity_check_matrix(n, wr, wc)
+#     checks = Stabilizer(H, zeros(Bool, size(H)))
+#     cat, scirc, _ = QuantumClifford.ECC.shor_syndrome_circuit(checks)
+#     return scirc
+# end
 
 """Returns a binary matrix, taking the OR of the X and Z matrices"""
 function get_matrix(checks::Stabilizer)

assets/images/naive_steane_ahr_full.png

@@ -187,7 +187,7 @@ function CSS_my_plot_both_synd(code::bootleg_CSS, p_shift=0.0001, p_wait=1-exp(-
 
     # Circuit compilation
     new_circuit, order = CircuitCompilation2xn.ancil_reindex_pipeline(scirc)
-    new_cat = CircuitCompilation2xn.perfect_reindex(cat, order)
+    new_cat = CircuitCompilation2xn.reindex_by_dict(cat, order)
 
     # Circuit comp - no gate noise
     post_ec_error_rates_MC_CA_shor = [CSS_evaluate_code_decoder_shor_syndrome(code, new_cat, new_circuit, p, p_shift*p*m, p_wait*p*m, gate_noise*p*m, nsamples=nsamples) for p in error_rates]
@@ -207,7 +207,7 @@ function CSS_my_plot_both_synd(code::bootleg_CSS, p_shift=0.0001, p_wait=1-exp(-
     try
         # Special shor syndrome Compiled circuit
         shor_new_circuit, shor_order = CircuitCompilation2xn.ancil_reindex_pipeline_shor_syndrome(scirc)
-        shor_cat = CircuitCompilation2xn.perfect_reindex(cat, shor_order)
+        shor_cat = CircuitCompilation2xn.reindex_by_dict(cat, shor_order)
 
         # Special Shor circuit Compilation - no gate noise
         post_ec_error_rates_MD_CA_shor = [CSS_evaluate_code_decoder_shor_syndrome(code, shor_cat, shor_new_circuit, p, p_shift*p*m, p_wait*p*m, gate_noise*p*m, nsamples=nsamples) for p in error_rates]

assets/images/naive_steane_data.png

@@ -262,7 +262,7 @@ function vary_shift_errors_plot_pf(checks::Stabilizer, name="")
     for i in n-k+1:n
         push!(encoding_locs, data_order[i])
     end
-    renewed_ecirc = perfect_reindex(ecirc, data_order)
+    renewed_ecirc = reindex_by_dict(ecirc, data_order)
 
     dataQubits = n
     reverse_dict = Dict(value => key for (key, value) in data_order)
@@ -348,7 +348,7 @@ function vary_shift_errors_plot_shor_syndrome(code::AbstractECC, name=string(typ
 
     # Anc Compiled circuit
     new_circuit, order = ancil_reindex_pipeline(scirc)
-    new_cat = perfect_reindex(cat, order)
+    new_cat = reindex_by_dict(cat, order)
     compiled_post_ec_error_rates_s0 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, new_cat, new_circuit, p, 0) for p in error_rates]
     compiled_post_ec_error_rates_s10 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, new_cat, new_circuit, p, p/10) for p in error_rates]
     compiled_post_ec_error_rates_s100 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, new_cat, new_circuit, p, p) for p in error_rates]
@@ -361,7 +361,7 @@ function vary_shift_errors_plot_shor_syndrome(code::AbstractECC, name=string(typ
 
     # Special shor compilation
     shor_circuit, shorder = ancil_reindex_pipeline_shor_syndrome(scirc)
-    shor_cat = perfect_reindex(cat, shorder)
+    shor_cat = reindex_by_dict(cat, shorder)
     shor_post_ec_error_rates_s0 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, shor_cat, shor_circuit, p, 0) for p in error_rates]
     shor_post_ec_error_rates_s10 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, shor_cat, shor_circuit, p, p/10) for p in error_rates]
     shor_post_ec_error_rates_s100 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, shor_cat, shor_circuit, p, p) for p in error_rates]
@@ -374,8 +374,8 @@ function vary_shift_errors_plot_shor_syndrome(code::AbstractECC, name=string(typ
 
     # Data + Anc Compiled circuit
     renewed_circuit, data_order = data_ancil_reindex(scirc, total_qubits)
-    renewed_ecirc = perfect_reindex(ecirc, data_order)
-    renewed_cat = perfect_reindex(cat, data_order)
+    renewed_ecirc = reindex_by_dict(ecirc, data_order)
+    renewed_cat = reindex_by_dict(cat, data_order)
 
     # Data + Anc Compiled circuit
     s, n = size(checks)
@@ -480,7 +480,7 @@ function realistic_noise_logical_physical_error(code::AbstractECC, p_shift=0.000
 
     # # Anc Compiled circuit
     # new_circuit, order = ancil_reindex_pipeline(scirc)
-    # new_cat = perfect_reindex(cat, order)
+    # new_cat = reindex_by_dict(cat, order)
     # compiled_post_ec_error_rates_s0 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, new_cat, add_two_qubit_gate_noise(new_circuit, p_gate), p, p_shift, p_wait, nframes=nframes) for p in error_rates]
     # compiled_post_ec_error_rates_s1 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, new_cat, add_two_qubit_gate_noise(new_circuit, p_gate*m), p, p_shift*m, 1-exp(-14.5*m/28_000), nframes=nframes) for p in error_rates]
     # compiled_x_error_s0 = [compiled_post_ec_error_rates_s0[i][1] for i in eachindex(compiled_post_ec_error_rates_s0)]
@@ -490,7 +490,7 @@ function realistic_noise_logical_physical_error(code::AbstractECC, p_shift=0.000
 
     # Special shor syndrome Compiled circuit
     shor_new_circuit, shor_order = ancil_reindex_pipeline_shor_syndrome(scirc)
-    shor_cat = perfect_reindex(cat, shor_order)
+    shor_cat = reindex_by_dict(cat, shor_order)
     shor_post_ec_error_rates_s0 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, shor_cat, add_two_qubit_gate_noise(shor_new_circuit, p_gate), p, p_shift, p_wait, nframes=nframes) for p in error_rates]
     shor_post_ec_error_rates_s1 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, shor_cat, add_two_qubit_gate_noise(shor_new_circuit, p_gate*m), p, p_shift*m, 1-exp(-14.5*m/28_000), nframes=nframes) for p in error_rates]
     shor_x_error_s0 = [shor_post_ec_error_rates_s0[i][1] for i in eachindex(shor_post_ec_error_rates_s0)]
@@ -556,7 +556,7 @@ function realistic_noise_vary_params(code::AbstractECC, p_shift=0.01, p_wait=1-e
 
     # Anc Compiled circuit
     new_circuit, order = ancil_reindex_pipeline(scirc)
-    new_cat = perfect_reindex(cat, order)
+    new_cat = reindex_by_dict(cat, order)
     compiled_post_ec_error_rates_s0 = [evaluate_code_decoder_shor_syndrome(checks, ecirc, new_cat,
                                 add_two_qubit_gate_noise(new_circuit, p_gate*m), 0, p_shift*m, p_wait*m, nframes=nframes) for m in error_rates]