Add Optional Data Overlay for MoleculeViewer (#3059)

This pull request adds support for displaying per-orbital metadata
overlays in the `MoleculeViewer` widget, allowing users to view
additional information (such as energy, symmetry, and occupation)
alongside the 3D molecular visualization. The changes span the Python
widget, the TypeScript/React component, and the notebook sample,
ensuring that metadata is passed through and rendered in the user
interface.

---------

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

Author: wavefunction91

samples/notebooks/benzene_molecule/benzene.ipynb

@@ -132,9 +132,17 @@
     "\n",
     "# Load cached molecule data from file.\n",
     "molecule_data = Path(\"benzene_diradical.structure.xyz\").read_text()\n",
+    "\n",
+    "# Note: The \"info\" field is optional and can contain any metadata you want to display with the cube data.\n",
     "cube_data = {\n",
-    "    \"alpha_18\": Path(\"MO_alpha_18.cube\").read_text(),\n",
-    "    \"alpha_19\": Path(\"MO_alpha_19.cube\").read_text(),\n",
+    "    \"alpha_18\": {\n",
+    "        \"data\": Path(\"MO_alpha_18.cube\").read_text(),\n",
+    "        \"info\": {\"Energy (Ha)\": -0.392, \"Symmetry\": \"A1\", \"Occupation\": 1.0}\n",
+    "    },\n",
+    "    \"alpha_19\": {\n",
+    "        \"data\": Path(\"MO_alpha_19.cube\").read_text(),\n",
+    "        \"info\": {\"Energy (Ha)\":  0.581, \"Symmetry\": \"B2\", \"Occupation\": 0.0}\n",
+    "    }\n",
     "}\n",
     "\n",
     "MoleculeViewer(molecule_data=molecule_data, cube_data=cube_data, isoval=0.03)"

source/npm/qsharp/ux/chem/index.tsx

@@ -7,9 +7,14 @@ import { createViewer, GLViewer } from "3dmol";
 import "./style.css";
 import { detectThemeChange } from "../themeObserver.js";
 
+type CubeData = {
+  data: string;
+  info?: { [key: string]: string | number };
+};
+
 export function MoleculeViewer(props: {
   moleculeData: string;
-  cubeData: { [key: string]: string };
+  cubeData: { [key: string]: string | CubeData };
   isoValue?: number;
 }) {
   // Holds reference to the viewer div and 3Dmol viewer object.
@@ -21,6 +26,14 @@ export function MoleculeViewer(props: {
   const [isoval, setIsoval] = useState(props.isoValue || 0.02);
   const [cubeKey, setCubeKey] = useState(Object.keys(props.cubeData)[0] || "");
 
+  const cubeData: CubeData | null =
+    !cubeKey || !props.cubeData[cubeKey]
+      ? null
+      : // Normalize the cube data to the expected form
+        typeof props.cubeData[cubeKey] === "string"
+        ? { data: props.cubeData[cubeKey] }
+        : (props.cubeData[cubeKey] as CubeData);
+
   // Runs after the DOM has been created. Create the 3Dmol viewer and adds the model.
   useEffect(() => {
     if (props.moleculeData && viewerRef.current) {
@@ -60,21 +73,21 @@ export function MoleculeViewer(props: {
       return;
     }
 
-    if (cubeKey && props.cubeData[cubeKey]) {
+    if (cubeData) {
       activeCubeData.current.forEach((voldata) => {
         currViewer.removeShape(voldata);
       });
       activeCubeData.current = [];
-      const cubeData = props.cubeData[cubeKey];
+
       activeCubeData.current.push(
-        currViewer.addVolumetricData(cubeData.trim(), "cube", {
+        currViewer.addVolumetricData(cubeData.data.trim(), "cube", {
           isoval,
           opacity: 1,
           color: "#0072B2",
         }),
       );
       activeCubeData.current.push(
-        currViewer.addVolumetricData(cubeData.trim(), "cube", {
+        currViewer.addVolumetricData(cubeData.data.trim(), "cube", {
           isoval: -1 * isoval,
           opacity: 1,
           color: "#FFA500",
@@ -110,74 +123,88 @@ export function MoleculeViewer(props: {
         style="width: 640px; height: 480px;"
       ></div>
 
-      <div id="view-dropdown-container" class="view-option">
-        <label for="viewSelector">Visualization Style:</label>
-        <select
-          id="viewSelector"
-          onChange={(e) => {
-            const style = (e.target as HTMLSelectElement).value;
-            setViewStyle(style);
-          }}
-        >
-          <option value="Sphere">Sphere</option>
-          <option value="Stick">Stick</option>
-          <option value="Line">Line</option>
-        </select>
-      </div>
-      {cubeKey ? (
-        <>
-          <div id="cube-dropdown-container" class="view-option">
-            <label for="cubeSelector">Cube selection:</label>
+      <div id="controls-overlay">
+        <div class="controls-column">
+          <div id="view-dropdown-container" class="view-option">
+            <label for="viewSelector">Visualization Style:</label>
             <select
-              id="cubeSelector"
+              id="viewSelector"
               onChange={(e) => {
-                const key = (e.target as HTMLSelectElement).value;
-                setCubeKey(key);
+                const style = (e.target as HTMLSelectElement).value;
+                setViewStyle(style);
               }}
             >
-              {Object.keys(props.cubeData).map((key) => (
-                <option value={key} selected={key === cubeKey}>
-                  {key}
-                </option>
-              ))}
+              <option value="Sphere">Sphere</option>
+              <option value="Stick">Stick</option>
+              <option value="Line">Line</option>
             </select>
           </div>
+          {cubeKey ? (
+            <>
+              <div id="cube-dropdown-container" class="view-option">
+                <label for="cubeSelector">Cube selection:</label>
+                <select
+                  id="cubeSelector"
+                  onChange={(e) => {
+                    const key = (e.target as HTMLSelectElement).value;
+                    setCubeKey(key);
+                  }}
+                >
+                  {Object.keys(props.cubeData).map((key) => (
+                    <option value={key} selected={key === cubeKey}>
+                      {key}
+                    </option>
+                  ))}
+                </select>
+              </div>
 
-          <div id="isoval-slider-container" class="view-option">
-            <label for="isovalSlider">Adjust isovalue:</label>
-            <input
-              type="range"
-              id="isovalSlider"
-              min="0.005"
-              max="0.1"
-              step="0.005"
-              value={isoval}
-              onInput={(e) => {
-                const new_isoval = parseFloat(
-                  (e.target as HTMLInputElement).value,
-                );
-                setIsoval(new_isoval);
-              }}
-            />
-            <input
-              type="number"
-              id="isovalInput"
-              min="0.005"
-              max="0.1"
-              step="0.001"
-              value={isoval}
-              onInput={(e) => {
-                const new_isoval = parseFloat(
-                  (e.target as HTMLInputElement).value,
-                );
-                if (!isNaN(new_isoval)) {
-                  setIsoval(new_isoval);
-                }
-              }}
-            />
+              <div id="isoval-slider-container" class="view-option">
+                <label for="isovalSlider">Adjust isovalue:</label>
+                <input
+                  type="range"
+                  id="isovalSlider"
+                  min="0.005"
+                  max="0.1"
+                  step="0.005"
+                  value={isoval}
+                  onInput={(e) => {
+                    const new_isoval = parseFloat(
+                      (e.target as HTMLInputElement).value,
+                    );
+                    setIsoval(new_isoval);
+                  }}
+                />
+                <input
+                  type="number"
+                  id="isovalInput"
+                  min="0.005"
+                  max="0.1"
+                  step="0.001"
+                  value={isoval}
+                  onInput={(e) => {
+                    const new_isoval = parseFloat(
+                      (e.target as HTMLInputElement).value,
+                    );
+                    if (!isNaN(new_isoval)) {
+                      setIsoval(new_isoval);
+                    }
+                  }}
+                />
+              </div>
+            </>
+          ) : null}
+        </div>
+        {cubeData?.info && (
+          <div class="controls-column">
+            {Object.entries(cubeData.info).map(([key, value]) => (
+              <div class="data-overlay-row" key={key}>
+                <label class="data-overlay-key">{key}:</label>
+                <span class="data-overlay-value">{value}</span>
+              </div>
+            ))}
           </div>
-        </>
-      ) : null}
+        )}
+      </div>
     </div>
   );
 }

source/npm/qsharp/ux/chem/style.css

@@ -10,6 +10,7 @@
   height: 100%;
   margin: 0;
   overflow: hidden;
+  position: relative;
   /* border: 1px solid gray; */
 }
 
@@ -18,17 +19,24 @@
   height: 100%;
 }
 
-#view-dropdown-container {
+#controls-overlay {
   position: absolute;
-  top: 10px; /* distance from bottom */
-  left: 10px; /* distance from right */
-  height: 20px;
+  top: 10px;
+  left: 10px;
+  display: flex;
+  align-items: flex-start;
+  gap: 32px;
   padding: 10px;
-  border-radius: 4px;
   z-index: 10;
   font-family: system-ui;
 }
 
+.controls-column {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
 #viewSelector {
   padding-left: 4px;
 }
@@ -51,31 +59,25 @@
   background-color: var(--qdk-host-background);
 }
 
-#cube-dropdown-container {
-  position: absolute;
-  top: 40px; /* distance from bottom */
-  left: 10px; /* distance from right */
-  padding: 10px;
-  height: 20px;
-  border-radius: 4px;
-  z-index: 10;
-  font-family: system-ui;
+#isovalSlider {
+  width: 100px;
+  outline: none;
 }
 
-#isoval-slider-container {
-  position: absolute;
-  top: 70px; /* distance from bottom */
-  left: 10px; /* distance from right */
-  padding: 10px;
-  height: 40px;
-  border-radius: 4px;
-  z-index: 10;
-  font-family: system-ui;
+.data-overlay-row {
+  display: flex;
+  gap: 8px;
 }
 
-#isovalSlider {
-  width: 100px;
-  outline: none;
+.data-overlay-key {
+  min-width: 80px;
+  font-weight: normal;
+  white-space: nowrap;
+}
+
+.data-overlay-value {
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
 }
 
 #isovalInput {

source/widgets/src/qsharp_widgets/__init__.py

@@ -239,6 +239,9 @@ def __init__(self, molecule_data, cube_data={}, isoval=0.02):
 
         Parameters:
         - molecule_data: string containing the molecular data in XYZ format.
+        - cube_data (optional): a dictionary where keys are cube names and values are dictionaries with the following structure:
+          - "data": string containing the cube data in .cube file format.
+          - "info": (optional) a dictionary containing any metadata you want to display with the cube data.
         """
         super().__init__(
             molecule_data=molecule_data, cube_data=cube_data, isoval=isoval