New `parallel` expression in Q# by swernli · Pull Request #3298 · microsoft/qdk

swernli · 2026-06-08T20:25:01Z

This change adds support for a new parallel expression that alters the behavior of qubit allocation and code generation. There are two forms of the expression:

parallel <expr>: For the duration of the expression after the keyword, all qubit release is deferred such that each qubit allocation uses a fresh qubit identifier. In addition, when configured for QIR code generation, no expressions that result in dynamic branching are allowed within the expression and all loops within the expression are unrolled. This ensures that the generated QIR for that expression will be contained within a single LLVM block. Combining these two features (defferred release and enforced single block) maximizs the likelihood that the code corresponding to the expression will be parallelized by the target's compilation and scheduling.
parallel within <limit> <expr>: This form has the same semantics as the first form, but with the added integer limit that expresses how many fresh qubit allocations will be used before normal qubit reuse begins. For example, parallel wthin 4 <expr> will defer the release of four qubits, and if a fifth allocation is made within the expression then that allocation will draw from the previously deferred qubits, returning to a reuse pattern. This allows the program to express a limited amount of parallelism while still allowing for some reuse, providing more fine grained control over the width/depth (space/time) tradeoff of the algorithm. The limit expression must be a static (compile-time constant) integer.

The new expression affects the behavior of QIR code generation, simulation, and resource estimation, and the change includes updated parser, AST, HIR, FIR, and lowering logic for the syntax as well as new RCA checks to enforce the requirements for control flow structure and static integer limits.

Fixes #3274

ScottCarda-MS · 2026-06-18T20:23:41Z

+        CircuitEntryPoint::EntryPoint,
+    );
+
+    expect![[r#"


It is difficult for me to understand what should be expected from the nested parallel within expressions, so I'll double-check with you. Is this correct and what is expected with the nested setup?

ScottCarda-MS · 2026-06-18T21:51:10Z

Because the limit of the parallel within <limit> <body> is also a full expression, it can become a block with side-effects and have its own qubit allocation and even sub-parallel expressions. We should be sure to test some of these scenarios for correct behavior.
For example, we should test

a parallel within expression doesn't take effect in its own limit expression, only its body
a surrounding parallel or parallel within does affect the limit expression of a parallel within contained inside of the surrounding parallel or parallel within's body expression.
i.e

parallel within X {
  parallel within {
    // Should be subject to `parallel within X`
    use q0 = Qubit();
    use q1 = Qubit();
    Y
  } {...}
}

parallel within expressions are effective inside the a block expression used for the limit expression of a surrounding parallel within, and that they don't affect the surrounding parallel within's body expression

idavis · 2026-06-23T16:00:32Z

    Lambda(CallableKind, Box<Pat>, Box<Expr>),
    /// A literal.
    Lit(Box<Lit>),
+    /// A parallel expression: `parallel a`


Do we want the target expr to be a block to force a scope on the feature rather than allowing any expr?

It gets turned into a block if it isn't one as part of lowering into HIR. But from a user-facing syntax perspective, there is value in having it support any expression. For example, for-loops are an expression, and one of the main motiviations is allowing parallel for syntax without having to add an extraneous block.

idavis · 2026-06-23T16:08:29Z

+            let ty = expr.ty.clone();
+            let stmt = hir::Stmt {
+                id: self.assigner.next_node(),
+                span: Span::default(),
+                kind: hir::StmtKind::Expr(expr),
+            };
+            let block = hir::Block {
+                id: self.assigner.next_node(),
+                span: Span::default(),
+                ty: ty.clone(),
+                stmts: vec![stmt],
+            };
+            hir::Expr {
+                id: self.assigner.next_node(),
+                span: Span::default(),
+                ty,
+                kind: hir::ExprKind::Block(block),
+            }


I think the stmt, block, and hir::Expr should use the expr.span rather than Span::default()

idavis · 2026-06-23T21:43:56Z

+    #[error("cannot use dynamic branching in parallel expression")]
+    #[diagnostic(help(
+        "using branching based on a measurement result in a parallel expression is not supported by the configured target profile"
+    ))]
+    #[diagnostic(url("https://aka.ms/qdk.qir#use-of-dynamic-branching-in-parallel-expr"))]
+    #[diagnostic(code("Qsc.CapabilitiesCk.UseOfDynamicBranchingInParallelExpr"))]
+    UseOfDynamicBranchingInParallelExpr(#[label] Span),
+
+    #[error("cannot use dynamic limit for a parallel expression")]
+    #[diagnostic(help(
+        "using a dynamic limit for a parallel expression is not supported by the configured target profile"
+    ))]
+    #[diagnostic(url("https://aka.ms/qdk.qir#use-of-dynamic-limit-in-parallel-expr"))]
+    #[diagnostic(code("Qsc.CapabilitiesCk.UseOfDynamicLimitInParallelExpr"))]
+    UseOfDynamicLimitInParallelExpr(#[label] Span),


These anchors don't work yet, need the docs updated.

This change adds support for a new parallel expression that alters the behavior of qubit allocation and code generation. There are two forms of the expression: - `parallel <expr>`: For the duration of the expression after the keyword, all qubit release is deferred such that each qubit allocation uses a fresh qubit identifier. In addition, when configured for QIR code generation, no expressions that result in dynamic branching are allowed within the expression and all loops within the expression are unrolled. This ensures that the generated QIR for that expression will be contained within a single LLVM block. Combining these two features (defferred release and enforced single block) maximizs the likelihood that the code corresponding to the expression will be parallelized by the target's compilation and scheduling. - `parallel within <limit> <expr>`: This form has the same semantics as the first form, but with the added integer limit that expresses how many fresh qubit allocations will be used before normal qubit reuse begins. For example, `parallel wthin 4 <expr>` will defer the release of four qubits, and if a fifth allocation is made within the expression then that allocation will draw from the previously deferred qubits, returning to a reuse pattern. This allows the program to express a limited amount of parallelism while still allowing for some reuse, providing more fine grained control over the width/depth (space/time) tradeoff of the algorithm. The limit expression must be a static (compile-time constant) integer. The new expression affects the behavior of QIR code generation, simulation, and resource estimation, and the change includes updated parser, AST, HIR, FIR, and lowering logic for the syntax as well as new RCA checks to enforce the requirements for control flow structure and static integer limits.

swernli · 2026-07-21T20:12:32Z

accidentally closed via bad force push

swernli requested review from billti, idavis and minestarks as code owners June 8, 2026 20:25

ScottCarda-MS reviewed Jun 18, 2026

View reviewed changes

Comment thread source/compiler/qsc_ast/src/ast.rs Outdated

ScottCarda-MS reviewed Jun 18, 2026

View reviewed changes

Comment thread source/compiler/qsc_ast/src/ast.rs Outdated

ScottCarda-MS reviewed Jun 18, 2026

View reviewed changes

Comment thread source/compiler/qsc_hir/src/hir.rs Outdated

idavis reviewed Jun 23, 2026

View reviewed changes

Comment thread source/compiler/qsc_ast/src/ast.rs Outdated

idavis reviewed Jun 23, 2026

View reviewed changes

Comment thread source/compiler/qsc_fir/src/fir.rs Outdated

idavis reviewed Jun 23, 2026

View reviewed changes

ScottCarda-MS approved these changes Jun 29, 2026

View reviewed changes

swernli marked this pull request as draft July 20, 2026 17:38

swernli closed this Jul 21, 2026

swernli force-pushed the swernli/parallel branch from 39a4783 to 134a7a6 Compare July 21, 2026 20:06

swernli reopened this Jul 21, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

New `parallel` expression in Q##3298

New `parallel` expression in Q##3298
swernli wants to merge 1 commit into
mainfrom
swernli/parallel

swernli commented Jun 8, 2026

Uh oh!

ScottCarda-MS Jun 18, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ScottCarda-MS commented Jun 18, 2026

Uh oh!

Uh oh!

Uh oh!

idavis Jun 23, 2026

Uh oh!

swernli Jun 29, 2026

Uh oh!

idavis Jun 23, 2026

Uh oh!

idavis Jun 23, 2026

Uh oh!

swernli commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

swernli commented Jun 8, 2026

Uh oh!

ScottCarda-MS Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ScottCarda-MS commented Jun 18, 2026

Uh oh!

Uh oh!

Uh oh!

idavis Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

swernli Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

idavis Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

idavis Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

swernli commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants