qsharp-lang 1.25.3-dev → 1.25.5-dev

package/ux/circuit-vis/state-viz/stateVizController.ts

@@ -0,0 +1,285 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+// State visualization controller for the circuit side panel.
+// Responsible for: ensuring the state panel exists, coordinating async state
+// computation + rendering, suppressing stale renders, and managing the loading
+// spinner/dev toolbar wiring.
+
+// Here is a general overview of the flow for the state visualization:
+// panel.ts
+//   └─ ensureStateVisualization(...)
+//        └─ stateVizController.ts  (loading spinner, request-id cancellation, retries)
+//             ├─ computeStateVizColumnsFromCurrentModelAsync(...)
+//             │    ├─ getCurrentCircuitModel(...) from events.ts
+//             │    ├─ if compute callback is provided (via DrawOptions.editor):
+//             │    │     computeStateVizColumnsForCircuitModel(...)
+//             │    │        (e.g., VS Code webview uses a Web Worker)
+//             │    │         └─ editor.tsx → stateComputeWorker.ts
+//             │    │              ├─ uses state-viz/worker/stateCompute.ts (compute ampMap)
+//             │    │              └─ uses state-viz/worker/stateVizPrep.ts (prep columns)
+//             │    └─ else fallback (main thread):
+//             │          ├─ state-viz/worker/stateCompute.ts (compute ampMap)
+//             │          └─ state-viz/worker/stateVizPrep.ts (prep columns)
+//             └─ updateStatePanelFromColumns(...)  (render)
+//                  stateViz.ts
+
+import {
+  createStatePanel,
+  updateStatePanelFromColumns,
+  renderBlankStatePanel,
+  renderMessageStatePanel,
+  setStatePanelLoading,
+} from "./stateViz.js";
+
+import { getCurrentCircuitModel } from "../events.js";
+import type { Circuit } from "../circuit.js";
+import {
+  computeAmpMapForCircuit,
+  UnsupportedStateComputeError,
+} from "./worker/stateCompute.js";
+import {
+  prepareStateVizColumnsFromAmpMap,
+  type PrepareStateVizOptions,
+} from "./worker/stateVizPrep.js";
+import type { StateColumn } from "./stateViz.js";
+
+const DEFAULT_MIN_PROB_THRESHOLD = 0.0;
+const MAX_QUBITS_FOR_STATE_VIZ = 20;
+
+type StateVizController = {
+  requestRenderState: () => void;
+  setComputeCallback: (cb?: ComputeStateVizColumnsForCircuitModel) => void;
+  setHostContainer: (container: HTMLElement) => void;
+};
+
+type ComputeStateVizColumnsForCircuitModel = (
+  model: Circuit,
+  opts?: PrepareStateVizOptions,
+) => Promise<StateColumn[]>;
+
+export function ensureStateVisualization(
+  container: HTMLElement,
+  computeStateVizColumnsForCircuitModel?: ComputeStateVizColumnsForCircuitModel,
+): void {
+  // Ensure a right-side state panel exists.
+  if (container.querySelector(".state-panel") == null) {
+    const statePanel = createStatePanel();
+    container.appendChild(statePanel);
+  }
+
+  const panelElem = container.querySelector(
+    ".state-panel",
+  ) as HTMLElement | null;
+  if (!panelElem) return;
+
+  const existingController = (panelElem as any)._stateVizController as
+    | StateVizController
+    | undefined;
+
+  if (existingController) {
+    // Sqore calls createPanel() on every edit (it re-renders the SVG). Keep a
+    // single state-viz controller per panel element so in-flight renders from
+    // previous calls can't toggle loading off underneath new renders.
+    existingController.setHostContainer(container);
+    existingController.setComputeCallback(
+      computeStateVizColumnsForCircuitModel,
+    );
+    existingController.requestRenderState();
+    return;
+  }
+
+  // Captured, mutable inputs that can be updated by future calls to
+  // ensureStateVisualization(...).
+  let hostContainer: HTMLElement = container;
+  let computeCallback: ComputeStateVizColumnsForCircuitModel | undefined =
+    computeStateVizColumnsForCircuitModel;
+
+  let renderRequestId = 0;
+  let loadingTimer: number | null = null;
+  let hideLoadingTimer: number | null = null;
+  let activeLoadingRequestId = 0;
+  let loadingShownAtMs = 0;
+
+  const clearLoadingTimer = () => {
+    if (loadingTimer != null) {
+      clearTimeout(loadingTimer);
+      loadingTimer = null;
+    }
+  };
+
+  const clearHideLoadingTimer = () => {
+    if (hideLoadingTimer != null) {
+      clearTimeout(hideLoadingTimer);
+      hideLoadingTimer = null;
+    }
+  };
+
+  const beginLoadingForRequest = (requestId: number) => {
+    // Always point loading at the newest request.
+    activeLoadingRequestId = requestId;
+    clearLoadingTimer();
+    clearHideLoadingTimer();
+
+    // If we're already showing loading (e.g., rapid edits), keep it on.
+    if (panelElem.classList.contains("loading")) return;
+
+    // Avoid flicker for fast computations by delaying the spinner.
+    loadingTimer = setTimeout(() => {
+      if (activeLoadingRequestId !== requestId) return;
+      loadingShownAtMs = performance.now();
+      setStatePanelLoading(panelElem, true);
+    }, 200) as unknown as number;
+  };
+
+  const endLoadingForRequest = (requestId: number) => {
+    if (activeLoadingRequestId !== requestId) return;
+    clearLoadingTimer();
+
+    // If loading was never shown (fast compute), there's nothing to hide.
+    if (!panelElem.classList.contains("loading")) {
+      activeLoadingRequestId = 0;
+      return;
+    }
+
+    // Avoid flicker: once visible, keep loading on briefly, and debounce the
+    // hide so rapid successive edits don't flash the spinner.
+    const minVisibleMs = 250;
+    const hideDebounceMs = 150;
+    const elapsed = performance.now() - (loadingShownAtMs || 0);
+    const remainingVisible = Math.max(0, minVisibleMs - elapsed);
+
+    clearHideLoadingTimer();
+    hideLoadingTimer = setTimeout(() => {
+      if (activeLoadingRequestId !== requestId) return;
+      activeLoadingRequestId = 0;
+      setStatePanelLoading(panelElem, false);
+    }, remainingVisible + hideDebounceMs) as unknown as number;
+  };
+
+  const renderState = async (panel: HTMLElement): Promise<void> => {
+    const requestId = ++renderRequestId;
+
+    try {
+      beginLoadingForRequest(requestId);
+
+      // If we were previously showing a message (e.g., unsupported/too many
+      // qubits), clear it immediately so the loading overlay can be shown while
+      // the new request is computing.
+      if (panel.classList.contains("message")) {
+        renderBlankStatePanel(panel);
+      }
+
+      // Determine current wire count and SVG for this render from the DOM.
+      const circuitSvg = hostContainer.querySelector(
+        "svg.qviz",
+      ) as SVGElement | null;
+
+      const columns = await computeStateVizColumnsFromCurrentModelAsync(
+        {
+          minProbThreshold: DEFAULT_MIN_PROB_THRESHOLD,
+        },
+        circuitSvg,
+        computeCallback,
+      );
+
+      // Ignore late results if a newer render request started.
+      if (requestId !== renderRequestId) return;
+
+      if (columns == null) {
+        // Model isn't ready for this render yet (events not enabled), or the
+        // model corresponds to a different SVG (during a re-render). Keep the
+        // panel blank for non-empty circuits so the loading overlay can show;
+        // show a message state only when the circuit is truly empty.
+        const wiresGroup = circuitSvg?.querySelector(".wires");
+        const wireCount = wiresGroup ? wiresGroup.children.length : 0;
+        if (wireCount <= 0) {
+          renderMessageStatePanel(panel);
+        } else {
+          renderBlankStatePanel(panel);
+        }
+        return;
+      }
+
+      if (columns.length > 0) {
+        updateStatePanelFromColumns(panel, columns);
+      } else {
+        // Empty model: show a message state.
+        renderMessageStatePanel(panel);
+      }
+
+      return;
+    } catch (e) {
+      // Ignore cancellation from host worker termination.
+      if (requestId !== renderRequestId) return;
+
+      const err = e as Error;
+      if (err?.name === "AbortError") {
+        return;
+      }
+      if (err?.name === "UnsupportedStateComputeError") {
+        renderMessageStatePanel(panel, err.message);
+        return;
+      }
+      renderMessageStatePanel(
+        panel,
+        "State visualization is unavailable for this circuit.",
+      );
+      return;
+    } finally {
+      endLoadingForRequest(requestId);
+    }
+  };
+
+  const requestRenderState = () => {
+    void renderState(panelElem);
+  };
+
+  (panelElem as any)._stateVizController = {
+    requestRenderState,
+    setComputeCallback: (cb?: ComputeStateVizColumnsForCircuitModel) => {
+      computeCallback = cb;
+    },
+    setHostContainer: (c: HTMLElement) => {
+      hostContainer = c;
+    },
+  } satisfies StateVizController;
+
+  // Re-render when the circuit model becomes available. The circuit SVG is
+  // replaced before `enableEvents(...)` runs, so computing state immediately in
+  // `createPanel(...)` would otherwise risk using a stale model.
+  try {
+    container.addEventListener("qsharp:circuit:modelReady", () => {
+      requestRenderState();
+    });
+  } catch {
+    // ignore
+  }
+
+  // Initial render.
+  void renderState(panelElem);
+}
+
+async function computeStateVizColumnsFromCurrentModelAsync(
+  opts: PrepareStateVizOptions = {},
+  expectedCircuitSvg?: SVGElement | null,
+  computeStateVizColumnsForCircuitModel?: ComputeStateVizColumnsForCircuitModel,
+): Promise<StateColumn[] | null> {
+  const model = getCurrentCircuitModel(expectedCircuitSvg);
+  if (!model) return null;
+  if (model.qubits.length === 0) return [];
+
+  if (model.qubits.length > MAX_QUBITS_FOR_STATE_VIZ) {
+    throw new UnsupportedStateComputeError(
+      `Too many qubits for state visualization (limit: ${MAX_QUBITS_FOR_STATE_VIZ}). This circuit has ${model.qubits.length} qubits.`,
+    );
+  }
+
+  if (computeStateVizColumnsForCircuitModel) {
+    return await computeStateVizColumnsForCircuitModel(model, opts);
+  }
+
+  // Fallback: compute and prepare on the main thread.
+  const ampMap = computeAmpMapForCircuit(model.qubits, model.componentGrid);
+  return prepareStateVizColumnsFromAmpMap(ampMap as any, opts);
+}

package/ux/circuit-vis/state-viz/worker/index.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+// Worker-safe exports for state visualization.
+// Intentionally avoids importing UI modules (DOM/CSS).
+
+export {
+  computeAmpMapForCircuit,
+  UnsupportedStateComputeError,
+  type AmpMap,
+} from "./stateCompute.js";
+
+export {
+  prepareStateVizColumnsFromAmpMap,
+  type PrepareStateVizOptions,
+} from "./stateVizPrep.js";
+
+export type { Circuit as CircuitModel } from "../../circuit.js";

package/ux/circuit-vis/state-viz/worker/stateCompute.ts

@@ -0,0 +1,260 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+// Core state computation for circuit-vis.
+// Implements a small statevector simulator that evaluates the circuit model and
+// produces an amplitude map. Intentionally avoids DOM/visualization concerns so
+// it can run on the main thread or in a Web Worker.
+
+import type { ComponentGrid, Operation, Qubit } from "../../circuit.js";
+import { evaluateAngleExpression } from "../../angleExpression.js";
+
+// This holds the complex amplitudes of the different basis states.
+export type AmpMap = Record<string, { re: number; im: number }>;
+
+export class UnsupportedStateComputeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnsupportedStateComputeError";
+  }
+}
+
+// Small complex helpers
+class Complex {
+  constructor(
+    public re: number,
+    public im: number,
+  ) {}
+  static add(a: Complex, b: Complex) {
+    return new Complex(a.re + b.re, a.im + b.im);
+  }
+  static mul(a: Complex, b: Complex) {
+    return new Complex(a.re * b.re - a.im * b.im, a.re * b.im + a.im * b.re);
+  }
+  static conj(a: Complex) {
+    return new Complex(a.re, -a.im);
+  }
+}
+
+function adjointMat2(mat: Complex[]): Complex[] {
+  // 2x2 matrix stored as [m00, m01, m10, m11].
+  // Adjoint is conjugate transpose: [[conj(m00), conj(m10)], [conj(m01), conj(m11)]].
+  return [
+    Complex.conj(mat[0]),
+    Complex.conj(mat[2]),
+    Complex.conj(mat[1]),
+    Complex.conj(mat[3]),
+  ];
+}
+
+// Matrices for single-qubit gates
+const GATE = {
+  X: [
+    new Complex(0, 0),
+    new Complex(1, 0),
+    new Complex(1, 0),
+    new Complex(0, 0),
+  ],
+  Y: [
+    new Complex(0, 0),
+    new Complex(0, -1),
+    new Complex(0, 1),
+    new Complex(0, 0),
+  ],
+  Z: [
+    new Complex(1, 0),
+    new Complex(0, 0),
+    new Complex(0, 0),
+    new Complex(-1, 0),
+  ],
+  H: [
+    new Complex(Math.SQRT1_2, 0),
+    new Complex(Math.SQRT1_2, 0),
+    new Complex(Math.SQRT1_2, 0),
+    new Complex(-Math.SQRT1_2, 0),
+  ],
+  S: [
+    new Complex(1, 0),
+    new Complex(0, 0),
+    new Complex(0, 0),
+    new Complex(0, 1),
+  ], // [[1,0],[0,i]]
+  T: [
+    new Complex(1, 0),
+    new Complex(0, 0),
+    new Complex(0, 0),
+    new Complex(Math.SQRT1_2, Math.SQRT1_2),
+  ],
+  SX: [
+    // sqrt(X)
+    new Complex(0.5, 0.5),
+    new Complex(0.5, -0.5),
+    new Complex(0.5, -0.5),
+    new Complex(0.5, 0.5),
+  ],
+};
+
+function rotationX(theta: number) {
+  const c = Math.cos(theta / 2);
+  const s = Math.sin(theta / 2);
+  return [
+    new Complex(c, 0),
+    new Complex(0, -s),
+    new Complex(0, -s),
+    new Complex(c, 0),
+  ];
+}
+function rotationY(theta: number) {
+  const c = Math.cos(theta / 2);
+  const s = Math.sin(theta / 2);
+  return [
+    new Complex(c, 0),
+    new Complex(-s, 0),
+    new Complex(s, 0),
+    new Complex(c, 0),
+  ];
+}
+function rotationZ(theta: number) {
+  const eNeg = new Complex(Math.cos(-theta / 2), Math.sin(-theta / 2));
+  const ePos = new Complex(Math.cos(theta / 2), Math.sin(theta / 2));
+  return [eNeg, new Complex(0, 0), new Complex(0, 0), ePos];
+}
+
+function parseTheta(op: Operation): number | undefined {
+  const arg = op.args?.[0];
+  if (!arg) return undefined;
+  const v = evaluateAngleExpression(arg);
+  return v;
+}
+
+function applySingleQubit(
+  state: Complex[],
+  target: number,
+  mat: Complex[],
+  controls: number[] = [],
+): void {
+  const N = state.length;
+  const mask = 1 << target;
+  for (let i = 0; i < N; i += 2 * mask) {
+    for (let j = 0; j < mask; j++) {
+      const i0 = i + j;
+      const i1 = i + j + mask;
+      const okControls = controls.every((c) => ((i0 >> c) & 1) === 1);
+      if (!okControls) continue;
+      const a0 = state[i0];
+      const a1 = state[i1];
+      const n0 = Complex.add(Complex.mul(mat[0], a0), Complex.mul(mat[1], a1));
+      const n1 = Complex.add(Complex.mul(mat[2], a0), Complex.mul(mat[3], a1));
+      state[i0] = n0;
+      state[i1] = n1;
+    }
+  }
+}
+
+export function computeAmpMapForCircuit(
+  qubits: Qubit[],
+  componentGrid: ComponentGrid,
+): AmpMap {
+  const n = qubits.length;
+  if (n === 0) return {};
+  const dim = 1 << n;
+  const state: Complex[] = new Array(dim);
+  for (let i = 0; i < dim; i++) state[i] = new Complex(0, 0);
+  state[0] = new Complex(1, 0);
+
+  for (const col of componentGrid) {
+    for (const op of col.components) {
+      switch (op.kind) {
+        case "unitary": {
+          const targetQubits = op.targets.map((r) => r.qubit);
+          const controls = (op.controls ?? []).map((r) => r.qubit);
+          const isAdjoint = op.isAdjoint ?? false;
+          if (targetQubits.length !== 1) {
+            // Unsupported multi-qubit unitary: skip
+            continue;
+          }
+          const t = targetQubits[0];
+          let mat: Complex[] | undefined;
+          switch (op.gate) {
+            case "X":
+              mat = GATE.X;
+              break;
+            case "Y":
+              mat = GATE.Y;
+              break;
+            case "Z":
+              mat = GATE.Z;
+              break;
+            case "H":
+              mat = GATE.H;
+              break;
+            case "S":
+              mat = GATE.S;
+              break;
+            case "T":
+              mat = GATE.T;
+              break;
+            case "SX":
+              mat = GATE.SX;
+              break;
+            case "Rx": {
+              const th = parseTheta(op);
+              if (th !== undefined) mat = rotationX(th);
+              break;
+            }
+            case "Ry": {
+              const th = parseTheta(op);
+              if (th !== undefined) mat = rotationY(th);
+              break;
+            }
+            case "Rz": {
+              const th = parseTheta(op);
+              if (th !== undefined) mat = rotationZ(th);
+              break;
+            }
+            default:
+              break;
+          }
+          if (mat) {
+            mat = isAdjoint ? adjointMat2(mat) : mat;
+            applySingleQubit(state, t, mat, controls);
+          }
+          break;
+        }
+        case "ket": {
+          // Reset is non-unitary and generally produces mixed states.
+          // The state visualizer currently only supports pure state vectors.
+          if (op.gate === "0") {
+            throw new UnsupportedStateComputeError(
+              "State visualization does not currently support measurement or ResetZ / |0⟩ reset operations.",
+            );
+          }
+          break;
+        }
+        case "measurement": {
+          // Measurement is non-unitary and generally produces mixed states.
+          // The state visualizer currently only supports pure state vectors.
+          throw new UnsupportedStateComputeError(
+            "State visualization does not currently support measurement or ResetZ / |0⟩ reset operations.",
+          );
+        }
+      }
+    }
+  }
+
+  const ampMap: AmpMap = {};
+  const eps = 1e-12;
+  for (let i = 0; i < dim; i++) {
+    const a = state[i];
+    const p = a.re * a.re + a.im * a.im;
+    if (p > eps) {
+      // Build bitstring label (editor qubit 0 is the most significant/leftmost bit)
+      let bits = "";
+      for (let q = 0; q < n; q++) {
+        bits += (i >> q) & 1 ? "1" : "0";
+      }
+      ampMap[bits] = { re: a.re, im: a.im };
+    }
+  }
+  return ampMap;
+}