Recursion support for CircuitOperation in map_clean_and_borrowable_qubits

[Vivek1106-04]

Describe the issue

The [map_clean_and_borrowable_qubits] transformer in [qubit_management_transformers.py] does not support recursive mapping for nested CircuitOperations.

As documented in the code (line 81):

Since this is not implemented using the cirq transformers infrastructure, we currently do not support recursive mapping within sub-circuits and that is left as a future TODO.

While the transformer attaches a [qubit_map] to the outer CircuitOperation, it does not traverse into the underlying FrozenCircuit to replace CleanQubit or BorrowableQubit instances. This results in the inner circuit retaining abstract placeholder qubits, which can cause failures in downstream operations that expect physical qubits.

Expected behavior: The transformer should recursively process nested CircuitOperations and replace all CleanQubit/BorrowableQubit placeholders with actual qubits.

Actual behavior: The inner FrozenCircuit retains its original placeholder qubits; only a [qubit_map] is applied to the outer CircuitOperation.

Explain how to reproduce the bug or problem

import cirq
from cirq.transformers.qubit_management_transformers import map_clean_and_borrowable_qubits

# Create a sub-circuit containing a CleanQubit placeholder
clean_qubit = cirq.ops.CleanQubit(0)
sub_circuit = cirq.Circuit(cirq.X(clean_qubit))

# Wrap in a CircuitOperation (nested circuit)
main_circuit = cirq.Circuit(cirq.CircuitOperation(sub_circuit.freeze()))

print("Original circuit:")
print(main_circuit)

# Apply the transformer
result = map_clean_and_borrowable_qubits(main_circuit)

print("Transformed circuit:")
print(result)

# Verify: check if placeholder was replaced in the inner circuit
circuit_op = list(result.all_operations())[0]
inner_qubit = list(circuit_op.circuit.all_operations())[0].qubits[0]

print(f"Inner qubit: {inner_qubit!r}")
print(f"Inner qubit type: {type(inner_qubit).__name__}")

Output:

Original circuit:
_c(0): ───[ _c(0): ───X─── ]───

Transformed circuit:
ancilla_0: ───[ _c(0): ───X─── ](qubit_map={_c(0): ancilla_0})───

Inner qubit: cirq.ops.CleanQubit(0)
Inner qubit type: CleanQubit

Tell us the version of Cirq where this happens

1.7.0.dev0

[Vivek1106-04]

Proposed Solution

I'm aware that Cirq's @transformer decorator provides add_deep_support=True for automatic recursive processing. However, that approach won't work correctly for this transformer due to two critical reasons:

1. The QubitManager Must Be Shared Across All Nesting Levels

[map_clean_and_borrowable_qubits] is stateful—it uses the qm (QubitManager) to track which ancilla qubits (ancilla_0, ancilla_1, etc.) have already been allocated.

• With @transformer(add_deep_support=True): The decorator's generic recursion logic doesn't know how to pass the specific qm instance to nested circuits. If a child circuit gets a new QubitManager, it will start allocating from ancilla_0 again, causing qubit collisions with the parent circuit.

• With explicit recursion: We call [map_clean_and_borrowable_qubits(op.circuit, qm=qm)] directly, guaranteeing that the exact same manager instance is shared everywhere. This ensures globally unique qubit allocation across all nesting levels.

2. Recursive Mapping Shouldn't Be Optional

The purpose of this transformer is to make a circuit executable by replacing abstract placeholders (CleanQubit/BorrowableQubit) with real qubits.

• With @transformer: Recursion only happens if the user remembers to pass context=TransformerContext(deep=True). If they forget, the circuit remains partially mapped and broken.

• With explicit recursion: The fix happens automatically—which is what users expect when they call "map clean and borrowable qubits."

Implementation

The fix involves modifying the [map_func] in [qubit_management_transformers.py] to handle CircuitOperation gates before processing qubit mappings:

def map_func(op: cirq.Operation, idx: int) -> cirq.OP_TREE:
    nonlocal last_op_idx, to_free
    assert isinstance(qm, ops.QubitManager)

    # Handle CircuitOperation recursively FIRST, sharing the same QubitManager
    if isinstance(op.untagged, circuits.CircuitOperation):
        inner_circuit = map_clean_and_borrowable_qubits(
            op.untagged.circuit, qm=qm
        )
        op = op.untagged.replace(circuit=inner_circuit.freeze()).with_tags(*op.tags)

    # ... rest of existing qubit freeing and allocation logic ...

[Vivek1106-04]

@pavoljuhas i would like to work on this

[Adithyaphani]

@pavoljuhas I would like to work on this . I hope you assign this task to me?

[Vivek1106-04]

@Adithyaphani! I have been already assigned. I have started writing core logic to solve this issue

[Adithyaphani]

Okay @Vivek1106-04 .