Better UX and error display for circuits (#1318)

This improves the circuit UX and the handling of various known error
cases.

## Circuit


![image](https://github.com/microsoft/qsharp/assets/16928427/c4057853-fe1a-4e98-a2df-e843118a104f)


## Operation circuit

![Screenshot 2024-03-26
151611](https://github.com/microsoft/qsharp/assets/16928427/1c8aaf75-c22d-4ed2-b2cc-dacb0a3b9249)

## Unsupported due to result comparison

![Screenshot 2024-03-26
151551](https://github.com/microsoft/qsharp/assets/16928427/27ac98a5-04d6-4bf3-aaa6-2fb2fafba528)

## Runtime failure

![Screenshot 2024-03-26
152053](https://github.com/microsoft/qsharp/assets/16928427/bc2e75d3-049c-4b2e-9977-2bc27be7804a)

## Compiler error

![Screenshot 2024-03-26
152033](https://github.com/microsoft/qsharp/assets/16928427/5dc2dbe5-c81c-4a0a-ad33-d4e753b146be)

## Too much circuit

![Screenshot 2024-03-26
152020](https://github.com/microsoft/qsharp/assets/16928427/86a7d715-d0c5-414f-9987-d5a2e8b2610e)

## Not enough circuit

![Screenshot 2024-03-26
151736](https://github.com/microsoft/qsharp/assets/16928427/1b74b418-da97-40cc-8cc1-23bd6898b1cd)

Author: minestarks

Cargo.lock

@@ -39,6 +39,7 @@ use qsc_circuit::{
 };
 use qsc_codegen::qir_base::BaseProfSim;
 use qsc_data_structures::{
+    functors::FunctorApp,
     language_features::LanguageFeatures,
     line_column::{Encoding, Range},
     span::Span,
@@ -83,18 +84,19 @@ pub enum Error {
     #[error("runtime error")]
     #[diagnostic(transparent)]
     Eval(#[from] WithStack<WithSource<qsc_eval::Error>>),
+    #[error("circuit error")]
+    #[diagnostic(transparent)]
+    Circuit(#[from] qsc_circuit::Error),
     #[error("entry point not found")]
     #[diagnostic(code("Qsc.Interpret.NoEntryPoint"))]
     NoEntryPoint,
     #[error("unsupported runtime capabilities for code generation")]
     #[diagnostic(code("Qsc.Interpret.UnsupportedRuntimeCapabilities"))]
     UnsupportedRuntimeCapabilities,
-    #[error("expression does not evaluate to an operation that takes qubit parameters")]
-    #[diagnostic(code("Qsc.Interpret.NoCircuitForOperation"))]
-    #[diagnostic(help(
-        "provide the name of a callable or a lambda expression that only takes qubits as parameters"
-    ))]
-    NoCircuitForOperation,
+    #[error("expression does not evaluate to an operation")]
+    #[diagnostic(code("Qsc.Interpret.NotAnOperation"))]
+    #[diagnostic(help("provide the name of a callable or a lambda expression"))]
+    NotAnOperation,
 }
 
 /// A Q# interpreter.
@@ -338,52 +340,22 @@ impl Interpreter {
 
         let entry_expr = match entry {
             CircuitEntryPoint::Operation(operation_expr) => {
-                // To determine whether the passed in expression is a valid callable name
-                // or lambda, we evaluate it and inspect the runtime value.
-                let maybe_operation = match self.eval_fragments(&mut out, &operation_expr)? {
-                    Value::Closure(b) => Some((b.id, b.functor)),
-                    Value::Global(item_id, functor_app) => Some((item_id, functor_app)),
-                    _ => None,
-                };
-
-                let maybe_invoke_expr = if let Some((item_id, functor_app)) = maybe_operation {
-                    // Controlled operations are not supported at the moment.
-                    if functor_app.controlled > 0 {
-                        return Err(vec![Error::NoCircuitForOperation]);
-                    }
-
-                    // Find the item in the HIR
-                    let package = map_fir_package_to_hir(item_id.package);
-                    let local_item_id = crate::hir::LocalItemId::from(usize::from(item_id.item));
-                    let package_store = self.compiler.package_store();
-
-                    let item = package_store
-                        .get(package)
-                        .and_then(|unit| unit.package.items.get(local_item_id));
-
-                    // Generate the entry expression to invoke the operation.
-                    // Will return `None` if item is not a valid callable that takes qubits.
-                    item.and_then(|item| entry_expr_for_qubit_operation(item, &operation_expr))
-                } else {
-                    return Err(vec![Error::NoCircuitForOperation]);
-                };
-
-                if maybe_invoke_expr.is_none() {
-                    return Err(vec![Error::NoCircuitForOperation]);
-                }
-                maybe_invoke_expr
+                let (item, functor_app) = self.eval_to_operation(&operation_expr)?;
+                let expr = entry_expr_for_qubit_operation(item, functor_app, &operation_expr)
+                    .map_err(|e| vec![e.into()])?;
+                Some(expr)
             }
             CircuitEntryPoint::EntryExpr(expr) => Some(expr),
             CircuitEntryPoint::EntryPoint => None,
         };
 
-        let val = if let Some(entry_expr) = entry_expr {
+        if let Some(entry_expr) = entry_expr {
             self.run_with_sim(&mut sim, &mut out, &entry_expr)?
         } else {
             self.eval_entry_with_sim(&mut sim, &mut out)
         }?;
 
-        Ok(sim.finish(&val))
+        Ok(sim.finish())
     }
 
     /// Runs the given entry expression on the given simulator with a new instance of the environment
@@ -459,6 +431,36 @@ impl Interpreter {
         self.lines += 1;
         label
     }
+
+    /// Evaluate the name of an operation, or any expression that evaluates to a callable,
+    /// and return the Item ID and function application for the callable.
+    /// Examples: "Microsoft.Quantum.Diagnostics.DumpMachine", "(qs: Qubit[]) => H(qs[0])",
+    /// "Controlled SWAP"
+    fn eval_to_operation(
+        &mut self,
+        operation_expr: &str,
+    ) -> std::result::Result<(&qsc_hir::hir::Item, FunctorApp), Vec<Error>> {
+        let mut sink = std::io::sink();
+        let mut out = GenericReceiver::new(&mut sink);
+        let (store_item_id, functor_app) = match self.eval_fragments(&mut out, operation_expr)? {
+            Value::Closure(b) => (b.id, b.functor),
+            Value::Global(item_id, functor_app) => (item_id, functor_app),
+            _ => return Err(vec![Error::NotAnOperation]),
+        };
+        let package = map_fir_package_to_hir(store_item_id.package);
+        let local_item_id = crate::hir::LocalItemId::from(usize::from(store_item_id.item));
+        let unit = self
+            .compiler
+            .package_store()
+            .get(package)
+            .expect("package should exist in the package store");
+        let item = unit
+            .package
+            .items
+            .get(local_item_id)
+            .expect("item should exist in the package");
+        Ok((item, functor_app))
+    }
 }
 
 /// Describes the entry point for circuit generation.

compiler/qsc/src/interpret.rs

@@ -656,7 +656,9 @@ fn controlled_operation() {
     // We don't generate an accurate call signature with the tuple arguments.
     expect![[r"
         [
-            NoCircuitForOperation,
+            Circuit(
+                ControlledUnsupported,
+            ),
         ]
     "]]
     .assert_debug_eq(&circ_err);
@@ -734,7 +736,9 @@ fn operation_with_non_qubit_args() {
 
     expect![[r"
         [
-            NoCircuitForOperation,
+            Circuit(
+                NoQubitParameters,
+            ),
         ]
     "]]
     .assert_debug_eq(&circ_err);

compiler/qsc/src/interpret/circuit_tests.rs

@@ -10,6 +10,7 @@ license.workspace = true
 
 [dependencies]
 log = { workspace = true }
+miette = { workspace = true }
 num-bigint = { workspace = true }
 num-complex = { workspace = true }
 qsc_codegen = { path = "../qsc_codegen" }
@@ -21,6 +22,7 @@ qsc_hir = { path = "../qsc_hir" }
 rustc-hash = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
+thiserror = { workspace = true }
 
 [dev-dependencies]
 expect-test = { workspace = true }

compiler/qsc_circuit/Cargo.toml

@@ -227,7 +227,7 @@ impl Builder {
     }
 
     #[must_use]
-    pub fn finish(mut self, _val: &Value) -> Circuit {
+    pub fn finish(mut self) -> Circuit {
         let circuit = take(&mut self.circuit);
         self.finish_circuit(circuit)
     }

compiler/qsc_circuit/src/builder.rs

@@ -7,3 +7,4 @@ pub mod operations;
 
 pub use builder::Builder;
 pub use circuit::{Circuit, Config, Operation};
+pub use operations::Error;

compiler/qsc_circuit/src/lib.rs

@@ -4,10 +4,28 @@
 #[cfg(test)]
 mod tests;
 
+use miette::Diagnostic;
 use qsc_hir::{
     hir::{Item, ItemKind},
     ty::{Prim, Ty},
 };
+use thiserror::Error;
+
+#[derive(Clone, Debug, Diagnostic, Error)]
+pub enum Error {
+    #[error("expression does not evaluate to an operation that takes qubit parameters")]
+    #[diagnostic(code("Qsc.Circuit.NoCircuitForOperation"))]
+    #[diagnostic(help(
+        "provide the name of a callable or a lambda expression that only takes qubits as parameters"
+    ))]
+    NoQubitParameters,
+    #[error("cannot generate circuit for controlled invocation")]
+    #[diagnostic(code("Qsc.Circuit.ControlledUnsupported"))]
+    #[diagnostic(help(
+        "controlled invocations are not currently supported. consider wrapping the invocation in a lambda expression"
+    ))]
+    ControlledUnsupported,
+}
 
 /// If the item is a callable, returns the information that would
 /// be needed to generate a circuit for it.
@@ -46,16 +64,24 @@ pub fn qubit_param_info(item: &Item) -> Option<(Vec<u32>, u32)> {
 ///
 /// If the item is not a callable, returns `None`.
 /// If the callable takes any non-qubit parameters, returns `None`.
-#[must_use]
-pub fn entry_expr_for_qubit_operation(item: &Item, operation_expr: &str) -> Option<String> {
+pub fn entry_expr_for_qubit_operation(
+    item: &Item,
+    functor_app: qsc_data_structures::functors::FunctorApp,
+    operation_expr: &str,
+) -> Result<String, Error> {
+    if functor_app.controlled > 0 {
+        return Err(Error::ControlledUnsupported);
+    }
+
     if let Some((qubit_param_dimensions, total_num_qubits)) = qubit_param_info(item) {
-        return Some(operation_circuit_entry_expr(
+        return Ok(operation_circuit_entry_expr(
             operation_expr,
             &qubit_param_dimensions,
             total_num_qubits,
         ));
     }
-    None
+
+    Err(Error::NoQubitParameters)
 }
 
 /// Generates the entry expression to call the operation described by `params`.

compiler/qsc_circuit/src/operations.rs

@@ -3,7 +3,7 @@
 
 use super::*;
 use expect_test::expect;
-use qsc_data_structures::language_features::LanguageFeatures;
+use qsc_data_structures::{functors::FunctorApp, language_features::LanguageFeatures};
 use qsc_frontend::compile::{compile, core, std, PackageStore, RuntimeCapabilityFlags, SourceMap};
 use qsc_hir::hir::{Item, ItemKind};
 
@@ -58,10 +58,12 @@ fn no_params() {
         }
     ",
     );
-    let expr = entry_expr_for_qubit_operation(&item, &operation);
-    expect![[r"
-        None
-    "]]
+    let expr = entry_expr_for_qubit_operation(&item, FunctorApp::default(), &operation);
+    expect![[r#"
+        Err(
+            NoQubitParameters,
+        )
+    "#]]
     .assert_debug_eq(&expr);
 }
 
@@ -75,10 +77,12 @@ fn non_qubit_params() {
         }
     ",
     );
-    let expr = entry_expr_for_qubit_operation(&item, &operation);
-    expect![[r"
-        None
-    "]]
+    let expr = entry_expr_for_qubit_operation(&item, FunctorApp::default(), &operation);
+    expect![[r#"
+        Err(
+            NoQubitParameters,
+        )
+    "#]]
     .assert_debug_eq(&expr);
 }
 
@@ -92,10 +96,12 @@ fn non_qubit_array_param() {
         }
     ",
     );
-    let expr = entry_expr_for_qubit_operation(&item, &operation);
-    expect![[r"
-        None
-    "]]
+    let expr = entry_expr_for_qubit_operation(&item, FunctorApp::default(), &operation);
+    expect![[r#"
+        Err(
+            NoQubitParameters,
+        )
+    "#]]
     .assert_debug_eq(&expr);
 }
 
@@ -110,7 +116,8 @@ fn qubit_params() {
     ",
     );
 
-    let expr = entry_expr_for_qubit_operation(&item, &operation).expect("expression expected");
+    let expr = entry_expr_for_qubit_operation(&item, FunctorApp::default(), &operation)
+        .expect("expression expected");
 
     expect![[r"
         {
@@ -133,7 +140,8 @@ fn qubit_array_params() {
     ",
     );
 
-    let expr = entry_expr_for_qubit_operation(&item, &operation).expect("expression expected");
+    let expr = entry_expr_for_qubit_operation(&item, FunctorApp::default(), &operation)
+        .expect("expression expected");
 
     expect![[r"
         {

compiler/qsc_circuit/src/operations/tests.rs

@@ -115,8 +115,9 @@ pub enum Error {
     #[diagnostic(code("Qsc.Eval.ReleasedQubitNotZero"))]
     ReleasedQubitNotZero(usize, #[label("Qubit{0}")] PackageSpan),
 
-    #[error("Result comparison is unsupported for this backend")]
+    #[error("cannot compare measurement results")]
     #[diagnostic(code("Qsc.Eval.ResultComparisonUnsupported"))]
+    #[diagnostic(help("comparing measurement results is not supported when performing circuit synthesis or base profile QIR generation"))]
     ResultComparisonUnsupported(#[label("cannot compare to result")] PackageSpan),
 
     #[error("name is not bound")]