Merge pull request #31 from The-Schultz-Lab/gpu-diagnostics-and-toggle

Fix misleading GPU probe diagnostics and add a GPU offload toggle (GPU.7, GPU.8)

Author: NCCU-Schultz-Lab

CHANGELOG.md

@@ -36,8 +36,31 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
   avoids the base image's implicit `defaults` channel. No change to the shipped
   package set or runtime behavior.
 
+### Added
+
+- **GPU offload can now be switched off from the UI** — Status tab → Settings →
+  "Use GPU when available". The preference persists across launches. This exists
+  because GPU offload is not always faster: quantum-chemistry SCF is
+  double-precision throughout, and consumer/workstation GPUs gate FP64 to roughly
+  1/32–1/64 of their FP32 rate, so offload on such a card can be *slower* than a
+  many-core CPU. `QUANTUI_DISABLE_GPU=1` still overrides the setting for scripted
+  runs.
+- **A warning when a detected GPU is unlikely to help.** `quantui gpu check` and
+  the Status tab now flag consumer-class devices with a note that double
+  precision is weak on them and offload may be slower than CPU, instead of
+  presenting any detected CUDA device as free speed.
+
 ### Fixed
 
+- **`quantui gpu check` no longer reports a broken CUDA install as "gpu4pyscf not
+  installed".** `ModuleNotFoundError` is a subclass of `ImportError`, so catching
+  the latter conflated "the package is absent" with "the package is present but
+  its CUDA libraries are missing" — the second case was reported as the first,
+  sending users back to an install step they had already completed. The two are
+  now distinguished, the underlying exception is included in the message (e.g.
+  the missing `libnvJitLink.so`), and both cases are logged. The reason string
+  now comes from the detection probe itself rather than being re-derived by the
+  CLI, so the message can no longer contradict what the run dispatcher decided.
 - **Exit is now a two-stage confirmation, so one click can no longer tear down an
   HPC allocation.** Exit shuts the server down by sending `SIGTERM` to the parent
   process. On a laptop that parent is just Voilà, but on a cluster interactive

quantui/app.py

@@ -896,6 +896,7 @@ class QuantUIApp:
         _files_root_dd: Any
         _files_status_html: Any
         _files_up_btn: Any
+        gpu_enabled_cb: Any
         help_content_html: Any
         help_tab_panel: Any
         help_topic_dd: Any
@@ -1207,11 +1208,14 @@ def _detect_gpu() -> None:
             except Exception:  # noqa: BLE001 — warm-up is best-effort
                 pass
             try:
-                from quantui.gpu_offload import is_gpu_available
+                from quantui.gpu_offload import probe_gpu
 
-                state = is_gpu_available()
+                # probe_gpu (not is_gpu_available) so the badge can show the
+                # actual reason offload isn't active instead of a generic
+                # "not installed or no CUDA device".
+                state = probe_gpu()
             except Exception:  # noqa: BLE001 — treat any failure as "no GPU"
-                state = (False, None)
+                state = (False, None, "")
             render = getattr(self, "_render_status_html", None)
             html_widget = getattr(self, "_status_html", None)
             if render is None or html_widget is None:
@@ -1404,6 +1408,7 @@ def _build_status_panel(self) -> None:
             visualization_available=VISUALIZATION_AVAILABLE,
             viz_default_backend=self._user_settings.viz.default_backend,
             vib_framerate_fps=self._user_settings.viz.vib_framerate_fps,
+            gpu_enabled=self._user_settings.compute.gpu_enabled,
         )
 
     # ── Welcome header ────────────────────────────────────────────────────
@@ -1699,6 +1704,10 @@ def _wire_callbacks(self) -> None:
         self.vib_framerate_si.observe(
             self._safe_cb(self._on_vib_framerate_changed), names="value"
         )
+        # Settings → GPU offload on/off (Status tab; persisted).
+        self.gpu_enabled_cb.observe(
+            self._safe_cb(self._on_gpu_enabled_changed), names="value"
+        )
         # 3D viewer style and lighting controls
         if VISUALIZATION_AVAILABLE:
             self.viz_style_dd.observe(
@@ -2824,6 +2833,38 @@ def _on_viz_default_backend_changed(self, change) -> None:
             return
         self._set_viz_preference(change["new"], persist=True)
 
+    def _on_gpu_enabled_changed(self, change) -> None:
+        """Persist the GPU-offload preference and re-probe immediately.
+
+        The detection probe is cached for the process lifetime, so flipping this
+        without clearing the cache would leave the next run using the old
+        decision — the toggle would appear to do nothing until restart.
+        """
+        new_val = bool(change["new"])
+        if new_val == self._user_settings.compute.gpu_enabled:
+            return
+        self._user_settings.compute.gpu_enabled = new_val
+        self._user_settings.save()
+        try:
+            from quantui.gpu_offload import is_gpu_available, probe_gpu
+
+            is_gpu_available.cache_clear()
+            state = probe_gpu()
+        except Exception:  # noqa: BLE001 — a probe failure must not break the UI
+            state = (False, None, "")
+        # Refresh the Status badge so it reflects the new decision right away.
+        render = getattr(self, "_render_status_html", None)
+        html_widget = getattr(self, "_status_html", None)
+        if render is not None and html_widget is not None:
+            try:
+                html_widget.value = render(state)
+            except Exception:  # noqa: BLE001 — best-effort badge refresh
+                pass
+        try:
+            _calc_log.log_event("gpu_enabled_changed", f"gpu_enabled={new_val}")
+        except OSError:
+            pass
+
     def _on_vib_framerate_changed(self, change) -> None:
         """Persist the vibrational-animation framerate and re-render the
         current mode so the new fps applies immediately. Re-rendering also

quantui/app_builders.py

@@ -65,6 +65,7 @@ def build_status_panel(
     visualization_available: bool,
     viz_default_backend: str = "auto",
     vib_framerate_fps: int = 10,
+    gpu_enabled: bool = True,
 ) -> None:
     """Build the Status tab panel."""
     cores, mem_gb = get_session_resources_fn()
@@ -106,12 +107,29 @@ def _ok(flag: bool, extra: str = "") -> str:
     def _gpu_cell(gpu_state: Any) -> str:
         if gpu_state is None:
             return '<span style="color:#94a3b8">&#8987; checking&hellip;</span>'
-        avail, name = gpu_state
+        # Accepts the 2-tuple from is_gpu_available() or the 3-tuple from
+        # probe_gpu() — the app passes the latter so the real reason can be
+        # shown instead of a guess.
+        avail, name = gpu_state[0], gpu_state[1]
+        reason = gpu_state[2] if len(gpu_state) > 2 else ""
         if avail:
-            return _ok(True, f"&mdash; <code>{name}</code>")
-        return _ok(
-            False, "&mdash; <code>gpu4pyscf</code> not installed or no CUDA device"
-        )
+            cell = _ok(True, f"&mdash; <code>{name}</code>")
+            from quantui.gpu_offload import is_low_fp64_device
+
+            if is_low_fp64_device(name):
+                # Detected is not the same as beneficial. Consumer cards gate
+                # FP64 to ~1/32–1/64 of FP32 and PySCF SCF is FP64 throughout,
+                # so offload can be slower than the CPU. Warn in place rather
+                # than let it look like free speed.
+                cell += (
+                    '<div style="color:#b45309;font-size:11px;margin-top:2px">'
+                    "&#9888; consumer-class GPU &mdash; weak double precision; "
+                    "may run <b>slower</b> than CPU. Benchmark before relying "
+                    "on it.</div>"
+                )
+            return cell
+        detail = reason if reason else "not installed or no CUDA device"
+        return _ok(False, f'&mdash; <span style="font-size:12px">{detail}</span>')
 
     def _render_status(gpu_state: Any) -> str:
         items = [
@@ -203,12 +221,31 @@ def _render_status(gpu_state: Any) -> str:
         "(persists across launches)</span></div>"
     )
 
+    # GPU offload toggle (persists across launches). Off is a legitimate choice
+    # on consumer cards, where FP64 offload can be slower than the CPU — see
+    # gpu_offload.is_low_fp64_device. QUANTUI_DISABLE_GPU=1 overrides this.
+    gpu_toggle_label = widgets.HTML(
+        '<div style="font-size:12px;color:#475569;margin-top:12px;'
+        'margin-bottom:0px">GPU offload '
+        '<span style="color:#94a3b8;font-size:11px">'
+        "(persists across launches; only applies when a CUDA device is "
+        "detected)</span></div>"
+    )
+    app.gpu_enabled_cb = widgets.Checkbox(
+        value=gpu_enabled,
+        description="Use GPU when available",
+        indent=False,
+        layout=layout_fn(width="320px", margin="2px 0 0 0"),
+    )
+
     settings_box = widgets.VBox(
         [
             settings_html,
             app.viz_default_backend_dd,
             vib_fps_label,
             app.vib_framerate_si,
+            gpu_toggle_label,
+            app.gpu_enabled_cb,
         ],
         layout=layout_fn(margin="0 0 8px 0"),
     )

quantui/cli.py

@@ -89,52 +89,35 @@ def _cmd_gpu_check(args: argparse.Namespace) -> int:
     Returns exit code 0 when GPU offload is available, 1 when it's not —
     so ``if quantui gpu check; then ...; fi`` works in shell scripts.
     """
-    from quantui.gpu_offload import is_gpu_available
+    from quantui.gpu_offload import is_gpu_available, is_low_fp64_device, probe_gpu
 
     # The detection probe is cached; clear so each CLI invocation is
     # fresh (the user may have just installed gpu4pyscf and wants to
     # confirm without restarting their shell).
     is_gpu_available.cache_clear()
-    available, name = is_gpu_available()
+    available, name, reason = probe_gpu()
     if available:
         print(f"GPU offload available: {name}")
-        return 0
-    print("GPU offload not available", file=sys.stderr)
-    # Surface the most common reasons so a user knows where to look next.
-    import os as _os
-
-    if _os.environ.get("QUANTUI_DISABLE_GPU", "").strip() in ("1", "true", "True"):
-        print(
-            "  reason: QUANTUI_DISABLE_GPU is set in the environment",
-            file=sys.stderr,
-        )
-    else:
-        try:
-            import gpu4pyscf  # noqa: F401
-        except ImportError:
+        if is_low_fp64_device(name):
+            # Available is not the same as worth using: PySCF is FP64
+            # throughout, and consumer cards gate double precision to a small
+            # fraction of single. Say so here rather than let the user discover
+            # it as an unexplained slowdown.
             print(
-                "  reason: gpu4pyscf not installed "
-                "(see README → 'Optional: GPU acceleration')",
+                f"  note: {name} looks like a consumer/workstation GPU, whose "
+                "double-precision throughput is typically 1/32–1/64 of its "
+                "single-precision. Quantum-chemistry SCF is double-precision "
+                "throughout, so offload here may be SLOWER than your CPU. "
+                "Benchmark before relying on it; switch it off in the Status "
+                "tab or with QUANTUI_DISABLE_GPU=1.",
                 file=sys.stderr,
             )
-            return 1
-        try:
-            import cupy as _cupy
-
-            n = int(_cupy.cuda.runtime.getDeviceCount())
-            if n < 1:
-                print("  reason: cupy reports 0 CUDA devices", file=sys.stderr)
-            else:
-                print(
-                    "  reason: cupy/gpu4pyscf import succeeded but probe "
-                    "raised — run "
-                    '`python -c "import cupy; cupy.show_config()"` to inspect',
-                    file=sys.stderr,
-                )
-        except ImportError:
-            print("  reason: cupy not installed", file=sys.stderr)
-        except Exception as exc:
-            print(f"  reason: cupy raised: {exc}", file=sys.stderr)
+        return 0
+    # The reason comes straight from the probe, so this can never contradict
+    # what the dispatcher actually decided.
+    print("GPU offload not available", file=sys.stderr)
+    if reason:
+        print(f"  reason: {reason}", file=sys.stderr)
     return 1