Add optional `prune_classical_qubits` setting for circuit generation #2802

swernli · 2025-12-04T19:05:57Z

This change adds a parameter to Q# and OpenQASM circuit generation called prune_classical_qubits that will generate a simplified circuit diagram where qubits that are unused or purely classical (never enter superposition) are removed. This can be handy for places where the program comes from generated logic that may use more qubits than strictly needed. This is purely for visualizing the simplified circuit and does not perform any kind of execution optimization.

So a program like this that has nine qubits but doesn't really use all of them:

will by default show the full circuit as it does today:

but with prune_classical_qubits = True will remove the purely classical q1, q2, q4, q5, and q8:

source/pip/qsharp/_qsharp.py

source/compiler/qsc_circuit/src/builder.rs

source/compiler/qsc_circuit/src/builder/tests.rs

source/compiler/qsc_circuit/src/builder.rs

DmitryVasilevsky · 2025-12-04T23:09:13Z

I'm a bit uneasy about this feature as it is. The trimmed circuit is not equivalent to the original and it may be confusing. For example, I can create this circuit:

operation Foo() : Result {
    use qs = Qubit[2];
    X(qs[0]);
    CNOT(qs[0], qs[1]);
    H(qs[1]);
    Ry(Std.Math.PI() / 2.0, qs[1]);
    X(qs[0]);
    MResetZ(qs[1])
}

In this circuit the first qubit is trimmable, but the second is not. We can compare original and resulting circuits.
Original:

Trimmed:

For the original circuit the result is always Zero. But for the trimmed circuit the result is always One.
I would rather see CNOT replaced with X in the resulting diagram, but that would not be easy. I think the feature still has merits as it is, but then I don't like the name of the parameter 'trim'. It feels like the diagrams should be equivalent. I think we need a scarier name for this parameter.
@minestarks already mentioned a different name would be better, but it was only from the 'trimming' point. I think the fact that the circuit becomes not equivalent should also be reflected in the name.

source/pip/qsharp/_qsharp.py

swernli · 2025-12-06T03:04:51Z

... I would rather see CNOT replaced with X in the resulting diagram, but that would not be easy. I think the feature still has merits as it is, but then I don't like the name of the parameter 'trim'. It feels like the diagrams should be equivalent.

@DmitryVasilevsky, I believe the new logic handles this appopriately. Using your same sample code, the output now looks the way you were hoping, keeping the circuit equivalent:

I'll need more tests to ensure this across different inputs though!

This change adds a parameter to Q# and OpenQASM circuit generation called `trim` that will generate a simplified circuit diagram where qubits that are unused or purely classical (never enter superposition) are removed. This can be handy for places where the program comes from generated logic that may use more qubits than strictly needed. This is purely for visualizing the simplified circuit and does not perform any kind of execution optimization.

…, still need tests

swernli · 2025-12-08T22:40:15Z

@DmitryVasilevsky @minestarks This is now ready for review with the updated behavior based on your feedback. No rush to get this in soon though.

minestarks · 2025-12-15T22:55:52Z

source/compiler/qsc_circuit/src/builder.rs

+        finish_circuit(qubits, operations, num_qubits, source_lookup)
+    }
+
+    fn should_keep_operation_mut(&self, op: &mut Operation) -> bool {


Can this operate on OperationOrGroup before we transform it into Operation? OperationOrGroup is the "working" data structure which is more ergonomic to manipulate, and already has methods like all_qubits() . Operation is essentially the final "wire format" that we serialize to JSON, so we have to keep it stable but is kind of annoying to manipulate. You shouldn't have to change this function too much.

minestarks · 2025-12-15T22:56:40Z

source/compiler/qsc_circuit/src/circuit.rs

+    #[must_use]
+    pub fn targets_mut(&mut self) -> &mut Vec<Register> {
+        match self {
+            Operation::Measurement(m) => &mut m.qubits,
+            Operation::Unitary(u) => &mut u.targets,
+            Operation::Ket(k) => &mut k.targets,
+        }
+    }
+
+    #[must_use]
+    pub fn all_qubits(&self) -> Vec<Register> {
+        match self {
+            Operation::Measurement(m) => m.qubits.clone(),
+            Operation::Unitary(u) => {
+                let mut qubits = u.targets.clone();
+                qubits.extend_from_slice(&u.controls);
+                qubits
+            }
+            Operation::Ket(k) => k.targets.clone(),
+        }
+    }
+


Please see above comment - if you use OperationOrGroup when manipulating the circuit, you shouldn't have to add these methods

minestarks · 2025-12-15T23:02:59Z

source/compiler/qsc_circuit/src/builder.rs

    circuit_builder: OperationListBuilder,
    next_result_id: usize,
    user_package_ids: Vec<PackageId>,
+    superposition_qubits: FxHashSet<usize>,


These are "wire ID"s right? Can we leave the type as QubitWire for clarity?

minestarks · 2025-12-15T23:06:51Z

source/compiler/qsc_circuit/src/builder.rs

    }
+
+    fn mark_qubit_in_superposition(&mut self, wire: QubitWire) {
+        self.superposition_qubits.insert(wire.into());


Perhaps we can have an assert here (and in flip_classical_qubit below) that the prune_classical_qubits config is set to true. Reading this, I get a bit nervous that we might be doing this work regardless of config flag. I can see you obviously took it into consideration this in this PR, but it feels like it could be accidentally regressed with a future change.

minestarks · 2025-12-15T23:11:12Z

source/compiler/qsc_circuit/src/builder.rs

    circuit_builder: OperationListBuilder,
    next_result_id: usize,
    user_package_ids: Vec<PackageId>,
+    superposition_qubits: FxHashSet<usize>,


Since this is expected to be very dense with a range of 0..max_qubits ... is FxHashSet<usize> still the right choice or should we use Vec<bool>?

(I can totally buy "it doesn't matter for circuits this small" though)

minestarks · 2025-12-15T23:15:19Z

source/pip/src/interpreter.rs

        generation_method: Option<CircuitGenerationMethod>,
        source_locations: Option<bool>,
        group_by_scope: Option<bool>,
+        prune_classical_qubits: bool,


I can't process why this flag looks different than the others. Why not Option<bool>? Should the others have been bool?

minestarks · 2025-12-15T23:16:22Z

source/wasm/src/lib.rs

        source_locations: config.source_locations,
        max_operations: config.max_operations,
        group_by_scope: config.group_by_scope,
+        prune_classical_qubits: false,


Don't we want to plumb this up to VS Code?

minestarks · 2025-12-15T23:29:01Z

source/compiler/qsc_circuit/src/builder.rs

+        // We need to pass the original number of qubits, before any trimming, to finish the circuit below.
+        let num_qubits = qubits.len();


Just curious, why do we need the original num_qubits? Should we need it? I'm not familiar with the code in operation_list_to_grid so I'm genuinely asking to see if there's something that can be improved there.

minestarks

Looks good, but lots of little suggestions

msoeken · 2025-12-16T10:52:08Z

... I would rather see CNOT replaced with X in the resulting diagram, but that would not be easy. I think the feature still has merits as it is, but then I don't like the name of the parameter 'trim'. It feels like the diagrams should be equivalent.

@DmitryVasilevsky, I believe the new logic handles this appopriately. Using your same sample code, the output now looks the way you were hoping, keeping the circuit equivalent:

I'll need more tests to ensure this across different inputs though!

This is better than the original approach after including @DmitryVasilevsky's feedback, but I still find this confusing. I do like the underlying motivation for the feature though. Could one alternative highlight qubits that are 100% "classical" (either in |0> or |1> state) with some color. Their value might affect different gates/operations in different ways, e.g., |0> on a CNOT's control removes the gate, |1> on a CNOT's control removes the control (other gates behave differently). Further, not meant to be part of this PR, but if we have logic to determine these values, we could also apply the optimization to the circuit and then visualize it (and have the same benefits for other tasks, to, e.g., speed up simulation, reduce resources, ...)

swernli requested review from billti, idavis and minestarks as code owners December 4, 2025 19:05

minestarks reviewed Dec 4, 2025

View reviewed changes

source/pip/qsharp/_qsharp.py Outdated Show resolved Hide resolved

minestarks reviewed Dec 4, 2025

View reviewed changes

source/compiler/qsc_circuit/src/builder.rs Outdated Show resolved Hide resolved

minestarks reviewed Dec 4, 2025

View reviewed changes

source/compiler/qsc_circuit/src/builder.rs Show resolved Hide resolved

DmitryVasilevsky reviewed Dec 4, 2025

View reviewed changes

source/compiler/qsc_circuit/src/builder.rs Outdated Show resolved Hide resolved

minestarks reviewed Dec 4, 2025

View reviewed changes

source/compiler/qsc_circuit/src/builder/tests.rs Outdated Show resolved Hide resolved

DmitryVasilevsky reviewed Dec 4, 2025

View reviewed changes

source/compiler/qsc_circuit/src/builder.rs Show resolved Hide resolved

DmitryVasilevsky reviewed Dec 4, 2025

View reviewed changes

source/compiler/qsc_circuit/src/builder.rs Outdated Show resolved Hide resolved

DmitryVasilevsky reviewed Dec 4, 2025

View reviewed changes

source/pip/qsharp/_qsharp.py Outdated Show resolved Hide resolved

swernli changed the title ~~Add optional trim setting for circuit generation~~ Add optional prune_classical_qubits setting for circuit generation Dec 6, 2025

swernli force-pushed the swernli/circuit-trimming branch from 920cd6c to 260bf32 Compare December 6, 2025 03:01

swernli added 4 commits December 8, 2025 13:26

Require all controls to be non-trimmable

0cfde5a

Track classical qubits with basic Toffoli sim, rename config property…

3b2e08f

…, still need tests

Fix test

88b2c87

swernli force-pushed the swernli/circuit-trimming branch from 260bf32 to 88b2c87 Compare December 8, 2025 21:28

Split out pruning test cases, add pruning + grouping tests

bde1544

minestarks reviewed Dec 15, 2025

View reviewed changes

minestarks approved these changes Dec 15, 2025

View reviewed changes

		// We need to pass the original number of qubits, before any trimming, to finish the circuit below.
		let num_qubits = qubits.len();

Add optional prune_classical_qubits setting for circuit generation #2802

Are you sure you want to change the base?

Add optional prune_classical_qubits setting for circuit generation #2802

Uh oh!

Conversation

swernli commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DmitryVasilevsky commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

swernli commented Dec 6, 2025

Uh oh!

swernli commented Dec 8, 2025

Uh oh!

minestarks Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

minestarks Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

minestarks Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

minestarks Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

minestarks Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

minestarks Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

minestarks Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

minestarks Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

minestarks left a comment

Choose a reason for hiding this comment

Uh oh!

msoeken commented Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Add optional `prune_classical_qubits` setting for circuit generation #2802

Add optional `prune_classical_qubits` setting for circuit generation #2802

swernli commented Dec 4, 2025 •

edited

Loading

DmitryVasilevsky commented Dec 4, 2025 •

edited

Loading

minestarks Dec 15, 2025 •

edited

Loading