FIR Transforms by idavis · Pull Request #3187 · microsoft/qdk

idavis · 2026-04-29T17:28:33Z

Summary

This PR adds FIR passes to enable broader code generation scenarios.

QIR does not support:

Function pointers (and thus dynamic dispatch)
Structs
Tuples
Generics

RIR doesn't currently support:

Multiple returns: return_unify tries to remove this constraint but there are some odd things we can't deal with.

The passes peel each unsupported piece off in the pipepline.

Monomorphize cleans up generics
Return unify gets rid of multiple returns and allows us to better understand control flow
defunctionalization gets rid of callable exprs
erase_utds rewrites the FIR so that it uses tuples in place of structs
lower_tuple_comparison handles a special case of binop replacing it with short-circuiting element-wise comparisons which can be codegen'd
sroa and arg_promote work together to get rid of all possible tuple element usage
dce and gc passes clean up code that isn't called any longer so that RCA doesn't pay attention to it
there are some mini passes as well that collapse very specific patterns like the defunc prepass

Aside from the passes, this PR also tries to unify how the code goes through RCA and codegen compilation. There are some side effects which leak into circuits as we have to generate new functions as part of the passes that we don't necessarily want reflected in the circuit representation.

Suggested Review Assignment

Reviewer	Best-fit parts
@swernli	Core FIR transform pipeline, qsc_fir_transforms, QIR/codegen integration, partial eval, RCA, RIR, circuit behavior, root Cargo changes
@minestarks	Broad compiler integration, qsc/qsc_circuit/qsc_frontend/qsc_lowerer/qsc_openqasm_compiler/qsc_passes, Python/package-facing changes, RIR, circuit behavior, root Cargo changes
@billti	Python package tests/snapshots, fuzz target, wasm diagnostic touchpoint, resource estimator test, default-owned samples/index_map fallout
@ScottCarda-MS	Language service and npm snapshot changes

Crate organization

Integrating qsc_fir_transforms with qsc_passes was going to make the PR look much bigger with a lot of moved files. My plan was to merge qsc_fir_tranforms into qsc_passes and organize them by HIR and FIR. This way we'd have a clean refactoring PR with no functional changes. This PR is already very large and I thought this integration was just too much to add.

Error types

ErrorKind::FirTransform will merge with ErrorKind::Pass in source/compiler/qsc/src/compile.rs in a follow up PR unless we want to differentiate between HIR and FIR passes at this level. We may want to differentiate at the qsc_passes level but merge them at this level as diagnostic transparent pass errors. The same follows for Error::Pass and Error::FirTransform in source/compiler/qsc/src/interpret.rs.

Interpret

This crate has two major changes. First the codegen module has a lot of added code for preparing the compilation. When we have both callables with interpret values (which may themselves be callables/structs/tuples which may contain the same complicated values) and entry expressions, we need to update the compilation in very different ways. For callables we need to effectively generate a new synthetic entry expr which can use the interpreter values. There is a case when dealing with closures where we need to partially abandon this pass and use a fallback of pinned non-entry-reachable items which are passed into the pipeline for processing. Entry expresssions are the easy path and just work as normal heading into the pipeline.

The interpret module does some setup work to help the codegen module.

The openqasm module has some fixes that are related to profile not being plumbed correctly. We weren't handling the user's specified profile and the codes annotated profile correct when used together and making the assumtion that if it was missing from the code that the profile was unrestricted. You'll see this update propagated into the Python and parser.

qsc_fir

The big addition here is the assigner. The FIR transforms do a lot of code generation and mutation, but it is additive. When we are generating new code, we need consistent, non-overlapping ids, for blocks, exprs, items, etc. This assigner update allows us to create an assigner from a package which finds the next values of each id needed so that we can safely allocate.

Testing

Some tests have been added to seemingly random places. These tests were added after I broke things and didn't know as no tests were failing. They are there to prevent regressions.

New instruction `frem`

The frem instruction is added to support OpenQASM dynamic angle support. Hopefully it will be added to the adaptive profile soon. Without this instruction we cannot do runtime angle calculations in OpenQASM as the angle type requires this computation.

Codegen

The qir codegen now requires RCA to have been already done before calling into fir_to_rir. We had too many places where we were or were not running RCA and then having to run it after the fact. This made it difficult to know when RCA was actually taking place. There are a few refactorings around this so that we have this more consolidated, but we might want to take a deeper step towards unifying in the future.

Circuits

Transformed callables are cloned into the user package. In order to maintain the same visualization as before, we have to detect whether we are in a 'synthetic' callable context so that we don't emit the call as a grouping context.

Partial eval

There is a lot of code in partial eval for dealing with return statements. I've documented source/compiler/qsc_partial_eval/src/evaluation_context.rs indicating that this is no longer required, but such a refactoring adds a lot of risk and code change which is better defferred to a follow up PR.

LLVM IR Changes

There are a few test files which are updated as the passes enable better code generation options that were impossible to handle before and were forced to be inlined.

Performance

The FIR transforms can be made faster, but they take less than 1/5 the time of the regular compilation and 1/15 as much time as RCA, so they are fast enough for the moment.

Random looking changes

source/compiler/qsc_frontend/src/closure.rs - documented here as the exact shape of closures has downstream effects and we can't vary from this structure without also changing many other sites.
source/compiler/qsc_frontend/src/resolve.rs - fixes a bug in type resolution where supplying an explicit : Qubit type on use statements leads to the var's pat type being error.

Co-authored-by: Copilot <copilot@github.com>

…e values as input. Co-authored-by: Copilot <copilot@github.com>

…r codegen. Use pinning as a fallback for stateful captures Co-authored-by: Copilot <copilot@github.com>

Co-authored-by: Copilot <copilot@github.com>

orpuente-MS · 2026-05-14T20:25:49Z

+    fn clone_fir_package(package: &Package) -> Package {
+        Package {
+            items: package.items.clone(),
+            entry: package.entry,
+            entry_exec_graph: package.entry_exec_graph.clone(),
+            blocks: package.blocks.clone(),
+            exprs: package.exprs.clone(),
+            pats: package.pats.clone(),
+            stmts: package.stmts.clone(),
+        }
+    }


Why not just add #[derive(Clone)] to package?

orpuente-MS · 2026-05-14T20:26:56Z

+    fn clone_fir_store(fir_store: &qsc_fir::fir::PackageStore) -> qsc_fir::fir::PackageStore {
+        let mut cloned_store = qsc_fir::fir::PackageStore::new();
+        for (package_id, package) in fir_store {
+            cloned_store.insert(package_id, clone_fir_package(package));
+        }
+        cloned_store
+    }


Same here, could implement Clone for qsc_fir::fir::PackageStore.

orpuente-MS · 2026-05-14T20:35:27Z

+    /// Pin-based fallback for callable args containing closures with captures.
+    ///
+    /// Seeds concrete (non-arrow-input) callables into the entry for reachability,
+    /// pins arrow-input callables and the target for DCE survival, and lets
+    /// `fir_to_qir_from_callable` handle specialization at QIR generation time.
+    fn prepare_codegen_fir_from_callable_args_pinned(
+        package_store: &PackageStore,
+        callable: qsc_hir::hir::ItemId,
+        _args: &Value,
+        capabilities: TargetCapabilityFlags,
+        mut concrete_callables: FxHashSet<qsc_fir::fir::StoreItemId>,
+    ) -> Result<CodegenFir, Vec<Error>> {


Not using _args here? Maybe can delete the _args parameter?

swernli · 2026-05-18T16:46:23Z

+            assigner.set_next_block(BlockId::from(max + 1));
+        }


Since IndexMap is ordered, we can cheat by just using next_back()

Suggested change

assigner.set_next_block(BlockId::from(max + 1));

}

let max_block = package.blocks.iter().next_back();

if let Some((max, _)) = max_block {

assigner.set_next_block(max.successor());

}

swernli · 2026-05-18T16:47:06Z

+            assigner.set_next_stmt(StmtId::from(max + 1));
+        }
+
+        // NodeId — scan callable and spec decls


As it turns out, NodeId is only used in three places in FIR where it is set as an id, but then never read. I think we can drop it from FIR entirely.

swernli · 2026-05-18T20:24:54Z

+pub mod fir_transforms {
+    pub use qsc_fir_transforms::{
+        PipelineResult, PipelineStage, defunctionalize, run_pipeline_to_with_diagnostics,
+        run_pipeline_with_diagnostics,
+    };
+}


Looks like most of these are unused, so only run_pipeline_with_diagnostics needs to be preserved:

Suggested change

pub mod fir_transforms {

pub use qsc_fir_transforms::{

PipelineResult, PipelineStage, defunctionalize, run_pipeline_to_with_diagnostics,

run_pipeline_with_diagnostics,

};

}

pub mod fir_transforms {

pub use qsc_fir_transforms::run_pipeline_with_diagnostics;

}

swernli · 2026-05-18T20:32:45Z

@@ -65,6 +87,38 @@ fn test_single_qubit() {
    );
 }

+#[test]
+fn test_explicitly_annotated_single_qubit_rewrite_preserves_binding_name_and_types() {


This test and the one above are effectively identical... they don't verify anything different just use different mechanisms to do so.

swernli · 2026-05-18T20:36:19Z

+    let qir = generate_qir_from_ast(
+        package,
+        unit.source_map,
+        unit.profile.unwrap_or(Profile::Unrestricted),


I get that this is only used for tests, but it seems odd for the default for QIR generation to be a profile that we know will fail QIR generation. Should this be Adaptive_RIF?

swernli · 2026-05-18T21:39:35Z

+            Value::Array(vs) => {
+                let mut lowered_ids = Vec::with_capacity(vs.len());
+                for v in vs.iter() {
+                    lowered_ids.push(lower_value_to_expr(package, assigner, v, callable_types));
+                }
+                let elem_ty = lowered_ids.first().map_or(qsc_fir::ty::Ty::Err, |id| {
+                    package.exprs.get(*id).expect("just inserted").ty.clone()
+                });
+                (
+                    qsc_fir::fir::ExprKind::Array(lowered_ids),
+                    qsc_fir::ty::Ty::Array(Box::new(elem_ty)),
+                )
+            }
+            Value::Range(r) => {


Since we know some folks invoke Q# callables with very large arrays (RE and chemistry scenarios, for example), we may pay a high cost of generating a large array literal into the synthetic entry expression only for it to be mostly ignored (since the synthetic entry is used for analysis in the passes and not execution). It might be worth trying to detect this case and avoid emitting constant arrays when not needed.

swernli · 2026-05-19T20:36:33Z

+/// 3. Asserts the two results match (both succeed with equal values, or
+///    both fail).
+#[cfg(test)]
+#[allow(dead_code)]


Looks like this allow isn't needed anymore.

swernli · 2026-05-19T20:48:59Z

+testutil = ["qsc_frontend", "qsc_hir", "qsc_passes"]
+
+[dev-dependencies]
+qsc_fir_transforms = { path = ".", features = ["testutil"] }


We started talking about this, and I see why it's needed now to make the testutil functionality available via the public API to scenario tests. It seems like there might be another way around that (maybe moving the tests, maybe moving the utils), but it's not critical for this PR.

swernli · 2026-05-19T20:52:01Z

+    qsc_fir::assigner::Assigner,
+);
+
+const EXCESSIVE_SPECIALIZATIONS_SOURCE: &str = r#"


nit, this could be inlined, as it's the only case pulled out into a const and isn't actually reused across tests.

swernli · 2026-05-19T21:10:44Z

+///
+/// Panics if the package has no entry expression.
+#[must_use]
+pub fn collect_reachable_package_closure_from_entry(


This appears to be dead code...

Along those lines, it's worth doing a pass over the crate to update visibility so that only things really needed across crates are pub and the rest are pub(crate) which should enable clippy to warn on unused code.

swernli · 2026-05-19T21:17:35Z

+fn entry_expression_followed() {
+    // A single entry point with no calls — only Main is reachable.


This test is technically redundant with unreachable_callable_excluded so only one of them is required.

swernli · 2026-05-19T21:24:39Z

+}
+
+#[test]
+fn lambda_in_entry_expression() {


It would also be good to include a test that confirms that callables used within lambda bodies are seen as reachable. Something like:

#[test] fn callable_only_in_closure_body() { check( indoc! {" namespace Test { function Other() : Unit {} @EntryPoint() function Main() : Unit { let f = () -> Other(); } } "}, &expect![[r#" <lambda> Main Other"#]], ); }

swernli · 2026-05-19T21:35:01Z

+
+    // Temporarily take the target package out of the store so we can hold
+    // `&source_pkg` (for cross-package) and `&mut target_pkg` simultaneously.
+    let empty_pkg = empty_package();


This could just be Package::default()

swernli · 2026-05-19T21:40:15Z

+            let source_decl = match &source_item.kind {
+                ItemKind::Callable(decl) => decl.as_ref(),
+                _ => continue,
+            };
+            let body_pkg = extract_callable_body(source_pkg, source_decl);


it's possible this could let-else with a panic rather than a continue.

swernli · 2026-05-19T21:58:31Z

+    // entry yet. Those new specializations may reference newly-cloned
+    // closure items that are also unreachable from entry until call sites
+    // are redirected.
+    let mut walked_items: FxHashSet<LocalItemId> = local_item_ids.iter().copied().collect();


Suggested change

let mut walked_items: FxHashSet<LocalItemId> = local_item_ids.iter().copied().collect();

let mut walked_items: FxHashSet<LocalItemId> = local_item_ids.into_iter().collect();

swernli · 2026-05-19T22:00:12Z

+    // closure items that are also unreachable from entry until call sites
+    // are redirected.
+    let mut walked_items: FxHashSet<LocalItemId> = local_item_ids.iter().copied().collect();
+    walked_items.extend(new_item_ids.iter().copied());


Suggested change

walked_items.extend(new_item_ids.iter().copied());

walked_items.extend(new_item_ids.iter());

swernli · 2026-05-19T22:02:55Z

+    package_id: PackageId,
+    specializations: &[Specialization],
+) -> Vec<ExprId> {
+    let reachable = collect_reachable_from_entry(store, package_id);


It may be possible to reuse the reachable set computed in discover_instantiations since in theory it should be the same as what we get here.

swernli · 2026-05-21T19:59:14Z

+    for (pkg_id, package) in store {
+        for (item_id, item) in &package.items {
+            if let ItemKind::Ty(_, udt) = &item.kind {
+                cache.insert((pkg_id, item_id), udt.get_pure_ty());


not sure if this provides any specific benefit, but I couldn't help but notice that this key is essentially a StoreItemId which already support impl From<(PackageId, LocalItemId)> for StoreItemId. So the UdtCache type could be defined as FxHashMap<StoreItemId, Ty> instead of having the raw tuple.

swernli · 2026-05-21T20:06:38Z

+            mutated_exprs
+        } else {
+            let mut cloner = FirCloner::new(store.get(pkg_id));
+            erase_udts_in_package(store.get_mut(pkg_id), &udt_cache, &mut cloner)


not critical, but worth noting for possible future perf efforts: this will perform udt erasure across the whole package while technically only the UDTs needed for the reachable subset of items need to be erased. If erase_udts_in_package where changed to erase_udts_in_item then this could iterate over reachable and potentially reduce the workload quite significantly (in particular, the whole stdlib would go through erasure where item-based iteration could likely avoid much of the stdlib).

oh, I see. Iterating over the whole package down in erase_udts_in_package is easier then identifying the subset of exprs that correspond to the reachable items. So this one might be a toss up, perf-wise, as you'd have to do extra iteration to find the subset of exprs, pats, and items that are reachable from the reachable set.

swernli · 2026-05-21T20:37:35Z

+    let structurally_mutated_external_specs: Vec<_> = structurally_mutated_specs
+        .into_iter()
+        .filter(|spec_id| spec_id.callable.package != package_id)
+        .collect();


Since only erase_udts populates structurally_mutated_external_specs it seems possible that other passes that modify signatures or expressions might miss having their exec graphs rebuilt.

swernli · 2026-05-21T20:40:52Z

+
+use crate::EMPTY_EXEC_RANGE;
+
+/// Runs the SROA pass on the entry-reachable portion of a package.


nitpick: this name is technically accurage, because here "aggregates" really means fixed length aggregates, of which Q# only supports tuples (arrays are really more like vectors with variable size). But it almost implies arrays are handled, which makes me wonder if "srot" for scalar replacement of tuples or something might be more clear.

idavis and others added 2 commits April 29, 2026 10:25

Create qsc_fir_transforms

5d69c33

Co-authored-by: Copilot <copilot@github.com>

Updates from feedback

e755065

Co-authored-by: Copilot <copilot@github.com>

idavis self-assigned this Apr 29, 2026

Fix lint

255d852

swernli reviewed Apr 29, 2026

View reviewed changes

Comment thread source/compiler/qsc_eval/src/lib.rs Outdated

swernli reviewed Apr 29, 2026

View reviewed changes

Comment thread source/index_map/src/lib.rs Outdated

swernli reviewed Apr 29, 2026

View reviewed changes

Comment thread source/compiler/qsc_codegen/src/qir/v1.rs Outdated

swernli reviewed Apr 29, 2026

View reviewed changes

Comment thread source/compiler/qsc_partial_eval/src/evaluation_context.rs

idavis added 4 commits April 29, 2026 11:34

Clippy

4aa56c5

Remove old debugging code.

ce5107b

Clippy in tests

8b69edd

Tuple return fallback

ec01879

swernli reviewed Apr 30, 2026

View reviewed changes

Comment thread source/compiler/qsc/src/interpret.rs

swernli reviewed Apr 30, 2026

View reviewed changes

Comment thread source/compiler/qsc/src/codegen/tests.rs Outdated

swernli reviewed Apr 30, 2026

View reviewed changes

Comment thread source/compiler/qsc/src/codegen.rs Outdated

swernli reviewed Apr 30, 2026

View reviewed changes

Comment thread source/compiler/qsc/src/codegen.rs Outdated

idavis and others added 12 commits May 1, 2026 09:28

Renaming and lints

8d0be01

Co-authored-by: Copilot <copilot@github.com>

Refactor tests into their own file

4ae2c9d

Documenting entry call expr usage and cleaning up naming

2e0676b

Co-authored-by: Copilot <copilot@github.com>

Fixing v1 frem usage

e6e6db4

Make concise QIR tests expect based.

4dba6a0

Co-authored-by: Copilot <copilot@github.com>

thread pinned items to exec_graph_rebuild enabling nested udt callabl…

a09718c

…e values as input. Co-authored-by: Copilot <copilot@github.com>

Add lowering for callable entry with callables on structs as input fo…

44658e2

…r codegen. Use pinning as a fallback for stateful captures Co-authored-by: Copilot <copilot@github.com>

Clean up tests and pretty rendering.

b1f991b

Updating docs and tests

793f618

Co-authored-by: Copilot <copilot@github.com>

Deduping code. Fixing bugs

79df941

Renaming and cleanup of old workarounds

cf6f7b6

Cleanup, refactoring, bug fixes

6faf273

swernli reviewed May 7, 2026

View reviewed changes

Comment thread source/compiler/qsc/src/codegen/tests.rs Outdated

Cleanup and refactoring, stronger invariant validation on pass entry

d57568d

Cleanup

be40734

orpuente-MS reviewed May 14, 2026

View reviewed changes

swernli reviewed May 18, 2026

View reviewed changes

idavis marked this pull request as ready for review May 18, 2026 17:06

idavis requested review from ScottCarda-MS, billti and minestarks as code owners May 18, 2026 17:06

swernli reviewed May 18, 2026

View reviewed changes

swernli reviewed May 19, 2026

View reviewed changes

Reimplement return unification

2c7776d

swernli reviewed May 21, 2026

View reviewed changes

-            assigner.set_next_block(BlockId::from(max + 1));
-        }
+        let max_block = package.blocks.iter().next_back();
+        if let Some((max, _)) = max_block {
+            assigner.set_next_block(max.successor());
+        }

		fn entry_expression_followed() {
		// A single entry point with no calls — only Main is reachable.

	let mut walked_items: FxHashSet<LocalItemId> = local_item_ids.iter().copied().collect();
	let mut walked_items: FxHashSet<LocalItemId> = local_item_ids.into_iter().collect();

	walked_items.extend(new_item_ids.iter().copied());
	walked_items.extend(new_item_ids.iter());


		use crate::EMPTY_EXEC_RANGE;

		/// Runs the SROA pass on the entry-reachable portion of a package.

Conversation

idavis commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Suggested Review Assignment

Crate organization

Error types

Interpret

qsc_fir

Testing

New instruction frem

Codegen

Circuits

Partial eval

LLVM IR Changes

Performance

Random looking changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

swernli May 19, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

idavis commented Apr 29, 2026 •

edited

Loading

New instruction `frem`

swernli May 19, 2026 •

edited

Loading