Remove debug with circuit menu item; more helpful handling for result comparison error (#1323)

More UX improvements and an attempt to be more helpful with known error
conditions.

## "Show circuit" command (or Code Lens)


![image](https://github.com/microsoft/qsharp/assets/16928427/b30b79e3-2d9f-444a-b203-d7b4043d52c8)


## "Run file and show circuit diagram" command (i.e. running in
simulator)


![image](https://github.com/microsoft/qsharp/assets/16928427/787f925c-5a75-4d16-af9d-9af06069c105)


## Program that compares measurement results, Target Profile =
Unrestricted


![image](https://github.com/microsoft/qsharp/assets/16928427/b40dd857-3452-4cd8-ac72-1d08ecef298b)


## Same program, but with "Run file and show circuit diagram" 


![image](https://github.com/microsoft/qsharp/assets/16928427/5674be51-6f73-4770-8ad5-b00c17797755)


## Same program, but with Target Profile = Base


![image](https://github.com/microsoft/qsharp/assets/16928427/3a9af968-75fd-4760-80b1-3d372ac27b55)

---------

Co-authored-by: Bill Ticehurst <billti@microsoft.com>

Author: minestarks

npm/ux/circuit.tsx

@@ -3,6 +3,7 @@
 
 import * as qviz from "@microsoft/quantum-viz.js/lib";
 import { useEffect, useRef } from "preact/hooks";
+import { CircuitProps } from "./data.js";
 
 // For perf reasons we set a limit on how many gates/qubits
 // we attempt to render. This is still a lot higher than a human would
@@ -19,12 +20,6 @@ export function Circuit(props: { circuit: qviz.Circuit }) {
     props.circuit.qubits.length === 0 ? (
       <div>
         <p>No circuit to display. No qubits have been allocated.</p>
-        <p>
-          <em>
-            Tip: you can generate a circuit diagram for any operation that takes
-            qubits or arrays of qubits as input.
-          </em>
-        </p>
       </div>
     ) : props.circuit.operations.length > MAX_OPERATIONS ? (
       <div>
@@ -67,31 +62,52 @@ export function Circuit(props: { circuit: qviz.Circuit }) {
 }
 
 /* This component is exclusive to the VS Code panel */
-export function CircuitPanel(props: {
-  title: string;
-  subtitle: string;
-  circuit?: qviz.Circuit;
-  errorHtml?: string;
-}) {
+export function CircuitPanel(props: CircuitProps) {
+  const error = props.errorHtml ? (
+    <div>
+      <p>
+        {props.circuit
+          ? "The program encountered a failure. See the error(s) below."
+          : "A circuit could not be generated for this program. See the error(s) below."}
+        <br />
+      </p>
+      <div dangerouslySetInnerHTML={{ __html: props.errorHtml }}></div>
+    </div>
+  ) : null;
+
   return (
     <div class="qs-circuit-panel">
       <div>
         <h1>{props.title}</h1>
       </div>
       {props.circuit ? <Circuit circuit={props.circuit}></Circuit> : null}
-      <div class="qs-circuit-error">
-        {props.errorHtml ? (
-          <div>
-            <p>
-              A circuit could not be generated for this program. See the
-              error(s) below.
-              <br />
-            </p>
-            <div dangerouslySetInnerHTML={{ __html: props.errorHtml }}></div>
-          </div>
-        ) : null}
-      </div>
-      <p>{props.subtitle /* target profile */}</p>
+      <div class="qs-circuit-error">{error}</div>
+      <p>{props.targetProfile}</p>
+      {props.simulating ? (
+        <p>
+          This circuit diagram was generated while running the program in the
+          simulator.
+          <br />
+          <br />
+          If your program contains behavior that is conditional on a qubit
+          measurement result, note that this circuit only shows the outcome that
+          was encountered during this simulation. Running the program again may
+          result in a different circuit being generated.
+        </p>
+      ) : null}
+      {
+        // show tip when the circuit is empty and we didn't run under the simulator (i.e. debugging)
+        !props.simulating &&
+        !props.errorHtml &&
+        props.circuit?.qubits.length === 0 ? (
+          <p>
+            <em>
+              Tip: you can generate a circuit diagram for any operation that
+              takes qubits or arrays of qubits as input.
+            </em>
+          </p>
+        ) : null
+      }
       <p>
         <a href="https://github.com/microsoft/qsharp/wiki/Circuit-Diagrams-from-Q%23-Code">
           Learn more
@@ -100,5 +116,3 @@ export function CircuitPanel(props: {
     </div>
   );
 }
-
-export type CircuitData = qviz.Circuit;

npm/ux/data.ts

@@ -63,3 +63,13 @@ export function CreateSingleEstimateResult(
     };
   }
 }
+
+export type CircuitProps = {
+  title: string;
+  circuit?: CircuitData;
+  errorHtml?: string;
+  targetProfile: string;
+  simulating: boolean;
+};
+
+export type CircuitData = import("@microsoft/quantum-viz.js/lib").Circuit;

npm/ux/index.ts

@@ -6,11 +6,16 @@
 import "./qsharp-ux.css";
 import "./qsharp-circuit.css";
 
-export { CreateSingleEstimateResult, type ReData } from "./data.js";
+export {
+  CreateSingleEstimateResult,
+  type ReData,
+  type CircuitData,
+  type CircuitProps,
+} from "./data.js";
 export { Histogram } from "./histogram.js";
 export { ReTable } from "./reTable.js";
 export { SpaceChart } from "./spaceChart.js";
 export { ScatterChart } from "./scatterChart.js";
 export { EstimatesOverview } from "./estimatesOverview.js";
 export { EstimatesPanel } from "./estimatesPanel.js";
-export { Circuit, CircuitPanel, type CircuitData } from "./circuit.js";
+export { Circuit, CircuitPanel } from "./circuit.js";

vscode/package.json

@@ -132,11 +132,6 @@
           "command": "qsharp-vscode.debugEditorContents",
           "when": "resourceLangId == qsharp",
           "group": "navigation@2"
-        },
-        {
-          "command": "qsharp-vscode.debugEditorContentsWithCircuit",
-          "when": "resourceLangId == qsharp",
-          "group": "navigation@2"
         }
       ],
       "commandPalette": [
@@ -149,7 +144,7 @@
           "when": "resourceLangId == qsharp"
         },
         {
-          "command": "qsharp-vscode.debugEditorContentsWithCircuit",
+          "command": "qsharp-vscode.runEditorContentsWithCircuit",
           "when": "resourceLangId == qsharp"
         },
         {
@@ -285,11 +280,9 @@
         "icon": "$(play)"
       },
       {
-        "command": "qsharp-vscode.debugEditorContentsWithCircuit",
-        "title": "Debug Q# File with Circuit Diagram",
-        "category": "Debug",
-        "enablement": "!inDebugMode",
-        "icon": "$(debug-alt)"
+        "command": "qsharp-vscode.runEditorContentsWithCircuit",
+        "title": "Run file and show circuit diagram",
+        "category": "Q#"
       },
       {
         "command": "qsharp-vscode.showHistogram",

vscode/src/circuit.ts

@@ -1,7 +1,8 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-import { type Circuit as CircuitData } from "@microsoft/quantum-viz.js/lib/circuit.js";
+import { type Circuit as CircuitData } from "@microsoft/quantum-viz.js/lib";
+import { escapeHtml } from "markdown-it/lib/common/utils";
 import {
   IOperationInfo,
   IRange,
@@ -52,7 +53,9 @@ export async function showCircuitCommand(
     log.info("terminating circuit worker due to timeout");
     worker.terminate();
   }, compilerRunTimeoutMs);
-  const sources = await loadProject(editor.document.uri);
+
+  const docUri = editor.document.uri;
+  const sources = await loadProject(docUri);
   const targetProfile = getTarget();
 
   try {
@@ -63,10 +66,9 @@ export async function showCircuitCommand(
 
     updateCircuitPanel(
       targetProfile,
-      editor.document.uri.path,
-      circuit,
+      docUri.path,
       true, // reveal
-      operation,
+      { circuit, operation },
     );
 
     sendTelemetryEvent(EventType.CircuitEnd, {
@@ -81,7 +83,7 @@ export async function showCircuitCommand(
       typeof e === "string" ? JSON.parse(e) : undefined;
     let errorHtml = "There was an error generating the circuit.";
     if (errors) {
-      errorHtml = errorsToHtml(errors);
+      errorHtml = errorsToHtml(errors, docUri);
     }
 
     if (!timeout) {
@@ -94,46 +96,16 @@ export async function showCircuitCommand(
 
     updateCircuitPanel(
       targetProfile,
-      editor.document.uri.path,
-      errorHtml,
+      docUri.path,
       false, // reveal
-      operation,
+      { errorHtml, operation },
     );
   } finally {
     log.info("terminating circuit worker");
     worker.terminate();
   }
 }
 
-export function updateCircuitPanel(
-  targetProfile: string,
-  docPath: string,
-  circuitOrErrorHtml: CircuitData | string,
-  reveal: boolean,
-  operation?: IOperationInfo | undefined,
-) {
-  let title;
-  let subtitle;
-  if (operation) {
-    title = `${operation.operation} with ${operation.totalNumQubits} input qubits`;
-    subtitle = `Target profile: ${getTargetFriendlyName(targetProfile)} `;
-  } else {
-    title = basename(docPath) || "Circuit";
-    subtitle = `Target profile: ${getTargetFriendlyName(targetProfile)}`;
-  }
-
-  const message = {
-    command: "circuit",
-    title,
-    subtitle,
-    circuit:
-      typeof circuitOrErrorHtml === "object" ? circuitOrErrorHtml : undefined,
-    errorHtml:
-      typeof circuitOrErrorHtml === "string" ? circuitOrErrorHtml : undefined,
-  };
-  sendMessageToPanel("circuit", reveal, message);
-}
-
 /**
  * Formats an array of compiler/runtime errors into HTML to be presented to the user.
  *
@@ -145,20 +117,37 @@ export function updateCircuitPanel(
  * @returns The HTML formatted errors, to be set as the inner contents of a container element.
  */
 function errorsToHtml(
-  errors: [string, VSDiagnostic, string | undefined][],
-): string {
+  errors: [string, VSDiagnostic, string][],
+  programUri: Uri,
+) {
   let errorHtml = "";
   for (const error of errors) {
     const [document, diag, rawStack] = error;
 
-    const location = documentHtml(document, diag.range);
-
-    const message = escapeHtml(`(${diag.code}) ${diag.message}`).replace(
-      "\n",
-      "<br/><br/>",
-    );
-
-    errorHtml += `<p>${location}: ${message}<br/></p>`;
+    if (diag.code === "Qsc.Eval.ResultComparisonUnsupported") {
+      const commandUri = Uri.parse(
+        `command:qsharp-vscode.runEditorContentsWithCircuit?${encodeURIComponent(JSON.stringify([programUri]))}`,
+        true,
+      );
+      const messageHtml =
+        `<p>Synthesizing circuits is unsupported for programs that ` +
+        `contain behavior that is conditional on a qubit measurement result, ` +
+        `since the resulting circuit may depend on the outcome of the measurement.</p>` +
+        `<p>If you would like to generate a circuit for this program, you can ` +
+        `<a href="${commandUri}">run the program in the simulator and show the resulting circuit</a>, ` +
+        `or edit your code to avoid the result comparison indicated by the call stack below.</p>`;
+
+      errorHtml += messageHtml;
+    } else {
+      const location = documentHtml(document, diag.range);
+
+      const message = escapeHtml(`(${diag.code}) ${diag.message}`).replace(
+        "\n",
+        "<br/><br/>",
+      );
+
+      errorHtml += `<p>${location}: ${message}<br/></p>`;
+    }
 
     if (rawStack) {
       const stack = rawStack
@@ -181,6 +170,39 @@ function errorsToHtml(
   return errorHtml;
 }
 
+export function updateCircuitPanel(
+  targetProfile: string,
+  docPath: string,
+  reveal: boolean,
+  params: {
+    circuit?: CircuitData;
+    errorHtml?: string;
+    simulating?: boolean;
+    operation?: IOperationInfo | undefined;
+  },
+) {
+  const title = params?.operation
+    ? `${params.operation.operation} with ${params.operation.totalNumQubits} input qubits`
+    : basename(docPath) || "Circuit";
+
+  // Trim the Q#: prefix from the target profile name - that's meant for the ui text in the status bar
+  const target = `Target profile: ${getTargetFriendlyName(targetProfile).replace("Q#: ", "")} `;
+
+  const props = {
+    title,
+    targetProfile: target,
+    simulating: params?.simulating || false,
+    circuit: params?.circuit,
+    errorHtml: params?.errorHtml,
+  };
+
+  const message = {
+    command: "circuit",
+    props,
+  };
+  sendMessageToPanel("circuit", reveal, message);
+}
+
 /**
  * If the input is a URI, turns it into a document open link.
  * Otherwise returns the HTML-escaped input
@@ -218,12 +240,3 @@ function documentHtml(maybeUri: string, range?: IRange) {
 
   return location;
 }
-
-function escapeHtml(unsafe: string): string {
-  return unsafe
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#039;");
-}