fix(pytket-decoder): Avoid QAllocating and immediately freeing qubits (#1256)

aborgna-q · cqc-alec · web-flow · commit 228ff52c890f · 2025-11-13T14:44:08.000Z
When decoding a pytket circuit, when a qubit register is not present in
the region's inputs we delay `QAlloc`ating it until it is consumed.

On the other side, at the end of the decoding we insert `QFree`s on each
qubit that didn't get consumed and is not part of the region's outputs.

When a qubit falls in both categories (i.e. it didn't get used on pytket
commands and didn't appear in the input/outputs) we were allocating it
when requesting the wires to QFree.

This PR adds a simple check to avoid the extra operations.

---------

Co-authored-by: Alec Edgington &lt;54802828+cqc-alec@users.noreply.github.com&gt;
diff --git a/tket-py/tket/passes.py b/tket-py/tket/passes.py
@@ -6,7 +6,7 @@
 
 from tket import optimiser
 
-# Re-export native bindings
+# Re-export native bindings.
 from ._tket.passes import (
     CircuitChunks,
     greedy_depth_reduce,
diff --git a/tket/src/serialize/pytket/decoder.rs b/tket/src/serialize/pytket/decoder.rs
@@ -426,6 +426,11 @@ impl<'h> PytketDecoderContext<'h> {
         let mut bit_args: &[TrackedBit] = &[];
         let mut params: &[LoadedParameter] = &[];
         for q in qubits.iter() {
+            // Ignore qubits that didn't get initialized
+            if !self.wire_tracker.qubit_is_initialized(q) {
+                continue;
+            }
+
             let mut qubit_args: &[TrackedQubit] = std::slice::from_ref(q);
             let Ok(FoundWire::Register(wire)) = self.wire_tracker.find_typed_wire(
                 &self.config,
diff --git a/tket/src/serialize/pytket/decoder/wires.rs b/tket/src/serialize/pytket/decoder/wires.rs
@@ -442,6 +442,16 @@ impl WireTracker {
         &self.bits[id.0]
     }
 
+    /// Returns `true` if the tracked qubit has been initialized.
+    ///
+    /// Qubits that have been registered but not associated to any
+    /// wires do not need to be consumed at the end of the decoding.
+    pub(super) fn qubit_is_initialized(&self, qubit: &TrackedQubit) -> bool {
+        self.qubit_wires
+            .get(&qubit.id())
+            .is_some_and(|ws| !ws.is_empty())
+    }
+
     /// Returns the list of known pytket registers, in the order we expect to
     /// see them at the output.
     ///
diff --git a/tket/src/serialize/pytket/tests.rs b/tket/src/serialize/pytket/tests.rs
@@ -40,6 +40,14 @@ use crate::serialize::pytket::{
 };
 use crate::TketOp;
 
+const EMPTY_CIRCUIT: &str = r#"{
+        "phase": "0",
+        "bits": [["c", [0]]],
+        "qubits": [["q", [0]], ["q", [1]]],
+        "commands": [],
+        "implicit_permutation": [[["q", [0]], ["q", [0]]], [["q", [1]], ["q", [1]]]]
+    }"#;
+
 const SIMPLE_JSON: &str = r#"{
         "phase": "0",
         "bits": [],
@@ -1109,3 +1117,23 @@ fn test_inplace_decoding() {
     assert!(hugr.get_optype(func1).is_func_defn());
     assert!(hugr.get_optype(dfg).is_dfg());
 }
+
+/// Test the lazy qubit/bit decoding behaviour when the registers are not
+/// present in the decoded region signature.
+///
+/// If the registers are never consumed, they won't be initialized at all.
+#[rstest]
+fn test_qubit_elision() {
+    let ser: circuit_json::SerialCircuit = serde_json::from_str(EMPTY_CIRCUIT).unwrap();
+    assert_eq!(ser.commands.len(), 0);
+
+    let circ: Circuit = ser
+        .decode(DecodeOptions::new().with_signature(Signature::new_endo(vec![])))
+        .unwrap();
+    assert_eq!(circ.qubit_count(), 0);
+
+    check_no_tk1_ops(&circ);
+
+    // The circuit should have no alloc/frees or const definitions
+    assert_eq!(circ.num_operations(), 0);
+}
