qsharp-lang 1.25.4-dev → 1.25.5-dev

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

@@ -0,0 +1,152 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+// State visualization “prep” utilities.
+// Converts raw amplitude maps into a small set of render-ready columns
+// (normalization, thresholding, capping, and aggregating an "Others" bucket).
+// Kept DOM-free so it can run on the main thread or inside a Web Worker.
+
+import type {
+  StateColumn,
+  AmpComplex,
+  AmpPolar,
+  AmpLike,
+  AmpMap,
+} from "../stateViz.js";
+
+export type PrepareStateVizOptions = {
+  // normalize probabilities to unit mass (default true)
+  normalize?: boolean;
+  // Minimum probability (0..1) for a state to be shown as its own column.
+  // States below this threshold will be aggregated into Others bucket.
+  // Default: 0
+  minProbThreshold?: number;
+  // Maximum number of columns to render, including Others if present.
+  // Default: 16
+  maxColumns?: number;
+};
+
+const DEFAULT_MAX_COLUMNS = 16;
+const MIN_PROB_EPSILON = 1e-12;
+
+// Convert amplitude to polar `{ prob, phase }`.
+const toPolar = (a: AmpLike): { prob: number; phase: number } => {
+  const maybe = a as Partial<AmpComplex & AmpPolar>;
+  const hasPolar =
+    typeof maybe.prob === "number" || typeof maybe.phase === "number";
+  if (hasPolar) {
+    const prob = typeof maybe.prob === "number" ? maybe.prob : 0;
+    const phase = typeof maybe.phase === "number" ? maybe.phase : 0;
+    return { prob, phase };
+  }
+  const re = typeof maybe.re === "number" ? maybe.re : 0;
+  const im = typeof maybe.im === "number" ? maybe.im : 0;
+  return { prob: re * re + im * im, phase: Math.atan2(im, re) };
+};
+
+function normalizeColumns(columns: StateColumn[]): StateColumn[] {
+  const sum = columns.reduce((acc, c) => acc + (c.prob ?? 0), 0);
+  if (sum <= 0) return columns;
+  return columns.map((c) => ({ ...c, prob: (c.prob ?? 0) / sum }));
+}
+
+function splitByThreshold(
+  columns: StateColumn[],
+  minProb: number,
+): { significant: StateColumn[]; small: StateColumn[] } {
+  const minThresh = Math.max(0, Math.min(1, minProb));
+  const significant: StateColumn[] = [];
+  const small: StateColumn[] = [];
+  for (const c of columns) {
+    if ((c.prob ?? 0) >= minThresh) significant.push(c);
+    else small.push(c);
+  }
+  return { significant, small };
+}
+
+function capAndAggregateColumns(
+  significant: StateColumn[],
+  small: StateColumn[],
+  maxColumns: number,
+): StateColumn[] {
+  const needsOthers = small.length > 0 || significant.length > maxColumns;
+  const capacity = needsOthers
+    ? Math.max(0, maxColumns - 1)
+    : Math.max(1, maxColumns);
+
+  const topColumns = significant.slice(0, capacity);
+  const dropped = significant.slice(capacity);
+  const othersList = [...small, ...dropped];
+
+  const columns = [...topColumns];
+  if (othersList.length > 0) {
+    const othersProb = othersList.reduce((s, r) => s + (r.prob ?? 0), 0);
+    const othersCount = othersList.length;
+    columns.push({
+      label: "__OTHERS__",
+      prob: othersProb,
+      phase: 0,
+      isOthers: true,
+      othersCount,
+    });
+  }
+  return columns;
+}
+
+function sortColumnsByLabel(columns: StateColumn[]): StateColumn[] {
+  const numericRegex = /^[+-]?\d+(?:\.\d+)?$/;
+  const asNumber = (s: string) => (numericRegex.test(s) ? parseFloat(s) : NaN);
+  const isNumeric = (s: string) => numericRegex.test(s);
+  const labelCmp = (a: string, b: string) => a.localeCompare(b);
+  const labelOrderCmp = (a: StateColumn, b: StateColumn) => {
+    if (a.isOthers === true) return 1;
+    if (b.isOthers === true) return -1;
+    const an = isNumeric(a.label);
+    const bn = isNumeric(b.label);
+    if (an && bn) {
+      const av = asNumber(a.label);
+      const bv = asNumber(b.label);
+      return av - bv;
+    }
+    if (an !== bn) return an ? -1 : 1;
+    return labelCmp(a.label, b.label);
+  };
+  return columns.slice().sort(labelOrderCmp);
+}
+
+export function prepareStateVizColumnsFromAmpMap(
+  ampMap: AmpMap,
+  opts: PrepareStateVizOptions = {},
+): StateColumn[] {
+  const entries = Object.entries(ampMap ?? {});
+  if (entries.length === 0) return [];
+
+  const raw = entries.map(([label, a]) => {
+    const { prob, phase } = toPolar(a);
+    return {
+      label,
+      prob: prob < MIN_PROB_EPSILON ? 0 : prob,
+      phase,
+    } as StateColumn;
+  });
+
+  // Normalize probabilities
+  const doNormalize = opts.normalize ?? true;
+  const normalized = doNormalize ? normalizeColumns(raw) : raw;
+
+  // Split columns based on threshold value
+  const { significant, small } =
+    typeof opts.minProbThreshold === "number"
+      ? splitByThreshold(normalized, opts.minProbThreshold)
+      : { significant: normalized, small: [] };
+
+  // Sort by probability and cap to max column numbers, aggregating rest into "Others"
+  significant.sort((a, b) => (b.prob ?? 0) - (a.prob ?? 0));
+  const maxColumns =
+    typeof opts.maxColumns === "number" && isFinite(opts.maxColumns)
+      ? Math.max(1, Math.floor(opts.maxColumns))
+      : DEFAULT_MAX_COLUMNS;
+  const capped = capAndAggregateColumns(significant, small, maxColumns);
+  // Sort by top columns by label, with "Others" last
+  return sortColumnsByLabel(capped);
+}

package/ux/circuit.tsx

@@ -20,11 +20,10 @@ const MAX_CIRCUITS = 1;
 // This component is shared by the Python widget and the VS Code panel
 export function Circuit(props: {
   circuit?: qviz.CircuitGroup | qviz.Circuit;
-  isEditable: boolean;
-  editCallback?: (fileData: qviz.CircuitGroup) => void;
-  runCallback?: () => void;
   renderLocations?: (s: SourceLocation[]) => { title: string; href: string };
+  editor?: qviz.EditorHandlers;
 }) {
+  const isEditable = props.editor != null;
   let unrenderable = false;
   let qubits = 0;
   let operations = 0;
@@ -41,7 +40,7 @@ export function Circuit(props: {
     unrenderable =
       unrenderable ||
       result.circuitGroup.circuits.length > MAX_CIRCUITS ||
-      (!props.isEditable && qubits === 0) ||
+      (!isEditable && qubits === 0) ||
       operations > MAX_OPERATIONS ||
       qubits > MAX_QUBITS;
   } else {
@@ -65,16 +64,16 @@ export function Circuit(props: {
 
 function ZoomableCircuit(props: {
   circuitGroup: qviz.CircuitGroup;
-  isEditable: boolean;
-  editCallback?: (fileData: qviz.CircuitGroup) => void;
-  runCallback?: () => void;
   renderLocations?: (s: SourceLocation[]) => { title: string; href: string };
+  editor?: qviz.EditorHandlers;
 }) {
   const circuitDiv = useRef<HTMLDivElement>(null);
   const [zoomLevel, setZoomLevel] = useState(100);
   const [rendering, setRendering] = useState(true);
   const [zoomOnResize, setZoomOnResize] = useState(true);
 
+  const isEditable = props.editor != null;
+
   useEffect(() => {
     // Enable "rendering" text while the circuit is being drawn
     setRendering(true);
@@ -89,13 +88,11 @@ function ZoomableCircuit(props: {
       const svg = renderCircuits(
         props.circuitGroup,
         container,
-        props.isEditable,
         props.renderLocations,
-        props.editCallback,
-        props.runCallback,
+        props.editor,
       );
 
-      if (!props.isEditable) {
+      if (!isEditable) {
         const initialZoom = calculateZoomToFit(container, svg as SVGElement);
         // Set the initial zoom level
         setZoomLevel(initialZoom);
@@ -106,7 +103,7 @@ function ZoomableCircuit(props: {
       // Calculate the initial zoom level based on the container width
       // Disable "rendering" text
       setRendering(false);
-    } else if (!props.isEditable) {
+    } else if (!isEditable) {
       // Initial drawing done, attach window resize handler
       window.addEventListener("resize", onResize);
       return () => {
@@ -122,7 +119,7 @@ function ZoomableCircuit(props: {
   return (
     <div>
       <div>
-        {props.isEditable || rendering ? null : (
+        {isEditable || rendering ? null : (
           <ZoomControl zoom={zoomLevel} onInput={userSetZoomLevel} />
         )}
       </div>
@@ -176,17 +173,10 @@ function ZoomableCircuit(props: {
   function renderCircuits(
     circuitGroup: qviz.CircuitGroup,
     container: HTMLDivElement,
-    isEditable: boolean,
     renderLocations?: (s: SourceLocation[]) => { title: string; href: string },
-    editCallback?: (fileData: qviz.CircuitGroup) => void,
-    runCallback?: () => void,
+    editor?: qviz.EditorHandlers,
   ) {
-    qviz.draw(circuitGroup, container, {
-      isEditable,
-      editCallback,
-      runCallback,
-      renderLocations,
-    });
+    qviz.draw(circuitGroup, container, { renderLocations, editor });
     return container.getElementsByClassName("qviz")[0]!;
   }
 
@@ -283,6 +273,7 @@ function ZoomControl(props: { zoom: number; onInput: (zoom: number) => void }) {
 
 // This component is exclusive to the VS Code panel
 export function CircuitPanel(props: CircuitProps) {
+  const isEditable = props.editor != null;
   const error = props.errorHtml ? (
     <div>
       <p>
@@ -312,7 +303,7 @@ export function CircuitPanel(props: CircuitProps) {
       )}
       <p>
         Learn more at{" "}
-        {props.isEditable ? (
+        {isEditable ? (
           <a href="https://aka.ms/qdk.circuit-editor">
             https://aka.ms/qdk.circuit-editor
           </a>
@@ -328,10 +319,8 @@ export function CircuitPanel(props: CircuitProps) {
       {props.circuit ? (
         <Circuit
           circuit={props.circuit}
-          isEditable={props.isEditable}
-          editCallback={props.editCallback}
-          runCallback={props.runCallback}
           renderLocations={renderLocations}
+          editor={props.editor}
         ></Circuit>
       ) : null}
     </div>

package/ux/data.ts

@@ -73,9 +73,11 @@ export type CircuitProps = {
   simulated: boolean;
   /** Circuit is still being generated */
   calculating: boolean;
-  isEditable: boolean;
-  editCallback?: (fileData: CircuitGroup) => void;
-  runCallback?: () => void;
+  // Editor-specific handlers (callbacks, state-viz host offload, etc.).
+  // When omitted, the circuit is rendered read-only.
+  editor?: EditorHandlers;
 };
 
+export type EditorHandlers = import("./circuit-vis/index.js").EditorHandlers;
 export type CircuitGroup = import("./circuit-vis/circuit.js").CircuitGroup;
+export type CircuitModel = import("./circuit-vis/circuit.js").Circuit;

package/ux/index.ts

@@ -9,6 +9,8 @@ import "./qsharp-circuit.css";
 export {
   CreateSingleEstimateResult,
   type ReData,
+  type EditorHandlers,
+  type CircuitModel,
   type CircuitGroup,
   type CircuitProps,
 } from "./data.js";

package/ux/qdk-theme.css

@@ -102,6 +102,12 @@ body[data-vscode-theme-kind="vscode-high-contrast-light"] {
   --qdk-menu-fill-hover: #9cf;
   --qdk-menu-fill-selected: #7af;
 
+  /* Use for focus outlines in interactive widgets */
+  --qdk-focus-border: var(--vscode-focusBorder, var(--qdk-atom-fill));
+
+  /* Use for subdued explanatory text */
+  --qdk-description-foreground: var(--vscode-descriptionForeground, #666);
+
   /* Used for shapes in charts, etc. that may have overlapping text (which should contrast) */
   --qdk-shape-fill: #8ab8ff;
   --qdk-shape-fill-selected: #b5c5f2;
@@ -144,6 +150,15 @@ body[data-vscode-theme-kind="vscode-high-contrast"] {
   --qdk-menu-fill-hover: #468;
   --qdk-menu-fill-selected: #47a;
 
+  /* Use for focus outlines in interactive widgets */
+  --qdk-focus-border: var(--vscode-focusBorder, var(--qdk-atom-fill));
+
+  /* Use for subdued explanatory text */
+  --qdk-description-foreground: var(
+    --vscode-descriptionForeground,
+    var(--qdk-foreground-muted)
+  );
+
   /* Used for shapes in charts, etc. that may have overlapping text (which should contrast) */
   --qdk-shape-fill: #4aa3ff;
   --qdk-shape-fill-selected: #ffd54f;

package/ux/qsharp-circuit.css

@@ -306,6 +306,9 @@
   .panel {
     display: flex;
     flex-direction: row;
+    height: 100%;
+    align-items: stretch;
+    min-height: 0; /* allow flex children to scroll */
   }
 
   .container {
@@ -337,6 +340,10 @@
     width: 100px;
     min-height: var(--minToolboxHeight);
     border-right: medium solid var(--vscode-editorWidget-border, #000000);
+    height: 100%;
+    min-height: 0; /* enable internal scroll in flex container */
+    overflow-y: auto;
+    overflow-x: hidden;
   }
 
   .toolbox-panel .title {
@@ -346,7 +353,7 @@
   .toolbox-panel-svg {
     width: -webkit-fill-available;
     min-height: var(--minToolboxHeight);
-    height: 100%;
+    height: auto; /* let SVG expand to content height */
   }
 
   .ghost {
@@ -494,3 +501,306 @@
   line-height: 40px;
   font-size: 16px;
 }
+
+/* State visualizer panel */
+.state-panel {
+  flex: 0 0 0px;
+  border-left: none; /* replaced by clickable edge */
+  display: flex;
+  flex-direction: column;
+  background: var(--qdk-host-background, #ffffff);
+  pointer-events: auto;
+  height: 100%;
+  min-height: 0; /* allow scroll in short windows */
+  overflow-y: auto;
+  overflow-x: hidden;
+  position: relative; /* anchor toggle button */
+  transition:
+    flex-basis var(--stateAnimMs, 200ms) ease,
+    width var(--stateAnimMs, 200ms) ease,
+    padding-left var(--stateAnimMs, 200ms) ease;
+  padding-left: 36px; /* reserve space for the clickable edge */
+}
+
+.state-panel:not(.collapsed) {
+  flex-basis: 226px; /* 190px content + 36px edge */
+}
+
+.state-panel .state-svg {
+  flex: 0 0 auto; /* size to content */
+  width: 100%;
+  height: auto; /* allow panel to scroll when content is taller */
+  transition: opacity var(--stateAnimMs, 200ms) ease;
+}
+
+/* Loading overlay for async state compute */
+.state-loading-overlay {
+  position: absolute;
+  top: 0;
+  left: 36px; /* keep the clickable edge visible */
+  right: 0;
+  bottom: 0;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+  z-index: 10;
+  background: color-mix(
+    in srgb,
+    var(--qdk-host-background, #ffffff) 70%,
+    transparent
+  );
+  backdrop-filter: blur(0.5px);
+}
+
+.state-panel.loading:not(.collapsed):not(.message) .state-loading-overlay {
+  display: flex;
+}
+
+.state-loading-spinner {
+  width: 22px;
+  height: 22px;
+  border-radius: 999px;
+  border: 3px solid var(--qdk-host-foreground, #666);
+  border-right-color: transparent;
+  opacity: 0.8;
+  animation: stateLoadingSpin 0.85s linear infinite;
+}
+
+@keyframes stateLoadingSpin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* Developer toolbar above the visualizer */
+.dev-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+  row-gap: 4px;
+  width: 100%;
+  padding: 4px 6px;
+  font-size: 12px;
+  border-bottom: 1px solid #ddd;
+  transition: opacity var(--stateAnimMs, 200ms) ease;
+}
+
+.dev-toolbar-sep {
+  opacity: 0.6;
+}
+
+.dev-toolbar input {
+  width: 56px;
+}
+
+/* Collapsed state: shrink panel and hide content except the toggle */
+.state-panel.collapsed {
+  flex: 0 0 36px !important; /* match edge width */
+  width: 36px; /* assist transition in some browsers */
+  overflow: visible; /* keep toggle visible */
+  padding-left: 0; /* only the edge remains visible */
+}
+
+/* Fade content while collapsing instead of instantly hiding */
+.state-panel.collapsed .state-svg,
+.state-panel.collapsed .dev-toolbar,
+.state-panel.collapsed .state-panel-message {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* Full-height clickable edge with vertical text */
+.state-edge {
+  position: absolute;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  width: 36px;
+  background: var(--qdk-background-accent, #e6e6e6);
+  border-right: 1px solid var(--qdk-widget-outline, #c8c8c8);
+  box-shadow: inset -1px 0 0 rgba(0, 0, 0, 0.06);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 20;
+  pointer-events: auto;
+}
+
+.state-edge:focus {
+  outline: 2px solid var(--qdk-focus-border);
+  outline-offset: -2px;
+}
+
+.state-edge-text {
+  writing-mode: vertical-rl;
+  text-orientation: mixed;
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--qdk-host-foreground, #333);
+  letter-spacing: 0.65px;
+  user-select: none;
+}
+
+/* Edge icons (top and bottom triangles) */
+.state-edge .edge-icon {
+  position: absolute;
+  width: 18px;
+  height: 18px;
+  right: 8px;
+  pointer-events: none; /* clicks go to the edge */
+  transform-origin: 50% 50%;
+}
+
+.state-edge .edge-icon-top {
+  top: 8px;
+}
+.state-edge .edge-icon-bottom {
+  bottom: 8px;
+}
+
+.state-edge .edge-icon svg {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+.state-edge .edge-icon path {
+  fill: var(--qdk-host-foreground, #555);
+  stroke: none; /* sharp corners, no outline */
+}
+
+/* When collapsed, flip icons to point left */
+.state-panel.collapsed .state-edge .edge-icon {
+  transform: rotate(180deg);
+}
+
+/* Empty state: hide SVG and toolbar */
+.state-panel.message .state-svg,
+.state-panel.message .dev-toolbar {
+  height: auto;
+  display: none;
+}
+
+.state-svg .state-header {
+  font-size: 17px;
+  font-weight: 600;
+  text-anchor: start; /* override circuit default */
+  dominant-baseline: hanging;
+  pointer-events: none;
+}
+
+.state-svg .state-separator {
+  stroke: #ddd;
+  stroke-width: 1px;
+}
+
+.state-svg .state-bar {
+  opacity: 0.9;
+  transition:
+    fill var(--stateAnimMs, 200ms) ease,
+    opacity var(--stateAnimMs, 200ms) ease;
+}
+
+.state-svg .state-bar-label {
+  font-size: 14px;
+  text-anchor: middle;
+  dominant-baseline: hanging;
+  pointer-events: none;
+}
+
+.state-svg .state-phase-circle {
+  fill: none;
+  stroke: #666;
+  stroke-width: 1px;
+}
+
+.state-svg .state-phase-text {
+  text-anchor: middle;
+  dominant-baseline: hanging; /* align like percentage labels */
+  font-size: 14px; /* match percentage label size */
+  pointer-events: none;
+}
+
+.state-svg .state-phase-dot {
+  stroke: #333;
+  stroke-width: 0.5px;
+  transition:
+    fill var(--stateAnimMs, 200ms) ease,
+    opacity var(--stateAnimMs, 200ms) ease;
+}
+
+.state-svg .state-phase-wedge {
+  stroke: none;
+  fill-opacity: 0.75;
+  transition:
+    fill var(--stateAnimMs, 200ms) ease,
+    opacity var(--stateAnimMs, 200ms) ease;
+}
+
+.state-svg .state-bitstring {
+  font-size: 14px;
+  text-anchor: middle;
+  dominant-baseline: hanging;
+  pointer-events: none;
+}
+
+/* Vertical orientation for long state labels to avoid collisions */
+
+/* HTML-based vertical labels inside foreignObject */
+.state-svg .state-bitstring-fo {
+  writing-mode: vertical-rl;
+  text-orientation: mixed;
+  font-size: 14px;
+  line-height: 1;
+  text-align: center;
+  width: -moz-fit-content;
+  width: fit-content; /* shrink to content so we can center via margins */
+  margin-left: auto;
+  margin-right: auto; /* center within the column width */
+  color: var(--qdk-host-foreground, #000);
+  pointer-events: none;
+}
+
+/* Centered empty-state message in the panel */
+.state-panel-message {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  padding: 8px;
+  text-align: center;
+  font-size: 13px;
+  color: var(--qdk-description-foreground);
+  z-index: 20;
+  pointer-events: none;
+  transition: opacity var(--stateAnimMs, 200ms) ease;
+}
+
+/* Circuit container/wrapper layout extracted from inline styles */
+.circuit-editor-container {
+  display: flex;
+  height: 80vh;
+  width: 95vw;
+  align-items: stretch;
+}
+
+.circuit-wrapper {
+  display: block;
+  overflow: auto;
+  width: 100%;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/* Empty circuit message extracted from inline styles */
+.empty-circuit-message {
+  padding: 2em;
+  text-align: center;
+  color: var(--qdk-description-foreground);
+  font-size: 1.1em;
+}