FIR Transforms

[idavis]

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.

[orpuente-MS]

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

[swernli]

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]

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

[swernli]

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]

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]

Looks like this allow isn't needed anymore.

[swernli]

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.

[minestarks]

Okay, am I hallucinating or did we already have a Q# pretty printer that we used for OpenQASM tests?

[swernli]

this test could make use of the pattern used in callables::check_rca_for_callable_block_with_dynamic_unreachable_binding, specifically having check_callable_compute_properties validate the callable properties via expect.

[swernli]

I'm just noticing that this pattern (which other tests in this file use) is unnecessary: there is a helper that checks for partial evaluation errors: get_partial_evaluation_error. This test and the three above it could be converted to that pattern rather than should_panic which makes test output cleaner and continues the expect-test patterns.

[swernli]

It occurs to me that since the InvariantLevel enum is strictly ordered, you could derive PartialOrd and Ord and then accomplish these checks via simple >= checks.