Add histogram widget (#922)

This adds a histogram IPyWidget similar to that used in the playground
and VS Code, complete with animating incoming results, menu, zoom,
scroll, etc. as shown below.

Open to discussing the API. By having 'run' on the widget launch the
execution, it allows it to easily wire up events and animate as they
come in.

<img width="731" alt="image"
src="https://github.com/microsoft/qsharp/assets/993909/d0c16703-f46f-4a08-804e-2c3e8390ef62">

Author: billti

npm/ux/qsharp-ux.css

@@ -325,6 +325,7 @@ html {
 
 .histogram {
   max-height: calc(100vh - 40px);
+  max-width: 600px;
   border: 1px solid var(--border-color);
   background-color: var(--vscode-sideBar-background, white);
 }

pip/qsharp/__init__.py

@@ -1,7 +1,15 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
-from ._qsharp import init, eval, eval_file, run, compile, estimate, dump_machine
+from ._qsharp import (
+    init,
+    eval,
+    eval_file,
+    run,
+    compile,
+    estimate,
+    dump_machine,
+)
 
 from ._native import Result, Pauli, QSharpError, TargetProfile, StateDump
 

pip/qsharp/_qsharp.py

@@ -1,7 +1,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
-from typing import Any, Dict, Optional, Union, List
+from typing import Any, Callable, Dict, Optional, TypedDict, Union, List
 from ._native import Interpreter, Output, TargetProfile, StateDump
 from .estimator._estimator import EstimatorResult, EstimatorParams
 import json
@@ -61,6 +61,7 @@ def get_interpreter() -> Interpreter:
     global _interpreter
     if _interpreter is None:
         init()
+        assert _interpreter is not None, "Failed to initialize the Q# interpreter."
     return _interpreter
 
 
@@ -93,23 +94,59 @@ def eval_file(path: str) -> Any:
     return eval(f.read())
 
 
-def run(entry_expr: str, shots: int) -> Any:
+class ShotResult(TypedDict):
+    """
+    A single result of a shot.
+    """
+
+    events: List[Output]
+    result: Any
+
+
+def run(
+    entry_expr: str,
+    shots: int,
+    *,
+    on_result: Optional[Callable[[ShotResult], None]] = None,
+    save_events: bool = False,
+) -> List[Any]:
     """
     Runs the given Q# expression for the given number of shots.
     Each shot uses an independent instance of the simulator.
 
     :param entry_expr: The entry expression.
     :param shots: The number of shots to run.
+    :param on_result: A callback function that will be called with each result.
+    :param save_events: If true, the output of each shot will be saved. If false, they will be printed.
 
-    :returns values: A list of results or runtime errors.
+    :returns values: A list of results or runtime errors. If `save_events` is true,
+    a List of ShotResults is returned.
 
     :raises QSharpError: If there is an error interpreting the input.
     """
 
-    def callback(output: Output) -> None:
+    results: List[ShotResult] = []
+
+    def print_output(output: Output) -> None:
         print(output)
 
-    return get_interpreter().run(entry_expr, shots, callback)
+    def on_save_events(output: Output) -> None:
+        # Append the output to the last shot's output list
+        results[-1]["events"].append(output)
+
+    for _ in range(shots):
+        results.append({"result": None, "events": []})
+        run_results = get_interpreter().run(
+            entry_expr, 1, on_save_events if save_events else print_output
+        )
+        results[-1]["result"] = run_results[0]
+        if on_result:
+            on_result(results[-1])
+
+    if save_events:
+        return results
+    else:
+        return [shot["result"] for shot in results]
 
 
 # Class that wraps generated QIR, which can be used by

pip/tests/test_qsharp.py

@@ -67,3 +67,32 @@ def test_compile_qir_str() -> None:
     operation = qsharp.compile("Program()")
     qir = str(operation)
     assert "define void @ENTRYPOINT__main()" in qir
+
+
+def test_run_with_result(capsys) -> None:
+    qsharp.init()
+    qsharp.eval('operation Foo() : Result { Message("Hello, world!"); Zero }')
+    results = qsharp.run("Foo()", 3)
+    assert results == [qsharp.Result.Zero, qsharp.Result.Zero, qsharp.Result.Zero]
+    stdout = capsys.readouterr().out
+    assert stdout == "Hello, world!\nHello, world!\nHello, world!\n"
+
+
+def test_run_with_result_callback(capsys) -> None:
+    def on_result(result):
+        nonlocal called
+        called = True
+        assert result["result"] == qsharp.Result.Zero
+        assert str(result["events"]) == "[Hello, world!]"
+
+    called = False
+    qsharp.init()
+    qsharp.eval('operation Foo() : Result { Message("Hello, world!"); Zero }')
+    results = qsharp.run("Foo()", 3, on_result=on_result, save_events=True)
+    assert (
+        str(results)
+        == "[{'result': Zero, 'events': [Hello, world!]}, {'result': Zero, 'events': [Hello, world!]}, {'result': Zero, 'events': [Hello, world!]}]"
+    )
+    stdout = capsys.readouterr().out
+    assert stdout == ""
+    assert called

widgets/js/index.tsx

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 import { render as prender } from "preact";
-import { ReTable, SpaceChart } from "qsharp-lang/ux";
+import { ReTable, SpaceChart, Histogram } from "qsharp-lang/ux";
 import markdownIt from "markdown-it";
 
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
@@ -35,6 +35,9 @@ export function render({ model, el }: RenderArgs) {
     case "EstimateDetails":
       renderTable({ model, el });
       break;
+    case "Histogram":
+      renderHistogram({ model, el });
+      break;
     default:
       throw new Error(`Unknown component type ${componentType}`);
   }
@@ -62,3 +65,26 @@ function renderChart({ model, el }: RenderArgs) {
   onChange();
   model.on("change:estimates", onChange);
 }
+
+function renderHistogram({ model, el }: RenderArgs) {
+  const onChange = () => {
+    const buckets = model.get("buckets") as { [key: string]: number };
+    const bucketMap = new Map(Object.entries(buckets));
+    const shot_count = model.get("shot_count") as number;
+
+    prender(
+      <Histogram
+        data={bucketMap}
+        shotCount={shot_count}
+        filter={""}
+        onFilter={() => undefined}
+        shotsHeader={true}
+      ></Histogram>,
+      el,
+    );
+  };
+
+  onChange();
+  model.on("change:buckets", onChange);
+  model.on("change:shot_count", onChange);
+}

widgets/src/qsharp_widgets/__init__.py

@@ -3,6 +3,7 @@
 
 import importlib.metadata
 import pathlib
+import time
 
 import anywidget
 import traitlets
@@ -35,3 +36,62 @@ class EstimateDetails(anywidget.AnyWidget):
     def __init__(self, estimates):
         super().__init__()
         self.estimates = estimates
+
+
+class Histogram(anywidget.AnyWidget):
+    _esm = pathlib.Path(__file__).parent / "static" / "index.js"
+    _css = pathlib.Path(__file__).parent / "static" / "index.css"
+
+    comp = traitlets.Unicode("Histogram").tag(sync=True)
+    buckets = traitlets.Dict().tag(sync=True)
+    shot_count = traitlets.Integer().tag(sync=True)
+
+    def _update_ui(self):
+        self.buckets = self._new_buckets.copy()
+        self.shot_count = self._new_count
+        self._last_message = time.time()
+
+    def _add_result(self, result):
+        result_str = str(result["result"])
+        old_value = self._new_buckets.get(result_str, 0)
+        self._new_buckets.update({result_str: old_value + 1})
+        self._new_count += 1
+
+        # Only update the UI max 10 times per second
+        if time.time() - self._last_message >= 0.1:
+            self._update_ui()
+
+    def __init__(self, results=None):
+        super().__init__()
+
+        self._new_buckets = {}
+        self._new_count = 0
+        self._last_message = time.time()
+
+        # If provided a list of results, count the buckets and update.
+        # Need to distinguish between the case where we're provided a list of results
+        # or a list of ShotResults
+        if results is not None:
+            for result in results:
+                if isinstance(result, dict) and "result" in result:
+                    self._add_result(result)
+                else:
+                    # Convert the raw result to a ShotResult for the call
+                    self._add_result({"result": result, "events": []})
+
+            self._update_ui()
+
+    def run(self, entry_expr, shots):
+        import qsharp
+
+        self._new_buckets = {}
+        self._new_count = 0
+
+        # Note: For now, we don't care about saving the results, just counting
+        # up the results for each bucket. If/when we add output details and
+        # navigation, then we'll need to save the results. However, we pass
+        # 'save_results=True' to avoid printing to the console.
+        qsharp.run(entry_expr, shots, on_result=self._add_result, save_events=True)
+
+        # Update the UI one last time to make sure we show the final results
+        self._update_ui()