pp now boots safely on Spaces without tripping the LLVM SmallVector assertion

README.md

@@ -32,3 +32,19 @@ reverse proxy. Set the following environment variables (the Dockerfile already d
 
 The bundled `docker/nginx.conf` proxies incoming traffic on `${PORT:-7860}` to the
 individual services so the browser never tries to contact `127.0.0.1` directly.
+
+## CUDA-Q backend on CPU-only hosts
+
+The 3D lattice Boltzmann solver relies on CUDA-Q, which expects a CUDA-capable GPU.
+CPU-only runtimes such as Hugging Face Spaces will now automatically skip loading the
+quantum backend so the UI can still boot. Use the following environment variables to
+override the default:
+
+| Variable | Effect |
+| --- | --- |
+| `DISABLE_CUDAQ=1` | Force-disable the CUDA-Q backend regardless of GPU availability. |
+| `FORCE_ENABLE_CUDAQ=1` | Attempt to load the CUDA-Q backend even if the platform was auto-detected as CPU-only. |
+
+When the backend is disabled the "Run Simulation" button is greyed out and a warning
+appears in the UI explaining why. Run the app locally on a CUDA-enabled machine and
+set `FORCE_ENABLE_CUDAQ=1` if you still want to attempt a run on a constrained host.

qlbm.py

@@ -1,18 +1,9 @@
 import os
 os.environ["OMP_NUM_THREADS"] = "1"
 
-# Defer cudaq import to avoid LLVM crash on CPU-only environments
-_cudaq_available = False
-try:
-    import cudaq
-    _cudaq_available = True
-except ImportError:
-    pass
-
 import numpy as np
 import math
 import time
-import shutil
 import plotly.graph_objects as go
 import pyvista as pv
 from trame.app import get_server
@@ -22,46 +13,61 @@ from trame.widgets import html  # <--- IMPORT ADDED HERE
 from trame_plotly.widgets import plotly as plotly_widgets
 from pyvista.trame.ui import plotter_ui
 
-# Defer import of fluid3d_pyvista to avoid triggering cudaq on CPU-only environments
+
+def _env_flag(name: str) -> bool:
+    value = os.environ.get(name)
+    return str(value).lower() in {"1", "true", "yes", "on"} if value is not None else False
+
+
+def _should_disable_quantum_backend():
+    if _env_flag("FORCE_ENABLE_CUDAQ"):
+        return False, ""
+
+    reasons = []
+    if _env_flag("DISABLE_CUDAQ"):
+        reasons.append("disabled via DISABLE_CUDAQ=1")
+
+    hf_space = os.environ.get("SPACE_ID") or os.environ.get("HF_SPACE_ID")
+    if hf_space:
+        reasons.append("running inside Hugging Face Spaces (CPU runtime)")
+
+    cuda_visible = os.environ.get("CUDA_VISIBLE_DEVICES")
+    if cuda_visible is not None and cuda_visible.strip() in {"", "-1"}:
+        reasons.append("no CUDA device exposed (CUDA_VISIBLE_DEVICES is empty)")
+
+    nvidia_visible = os.environ.get("NVIDIA_VISIBLE_DEVICES")
+    if nvidia_visible is not None and nvidia_visible.strip() in {"", "void"}:
+        reasons.append("no NVIDIA device exposed (NVIDIA_VISIBLE_DEVICES is empty)")
+
+    if reasons:
+        msg = "; ".join(reasons)
+        return True, f"Quantum backend disabled because {msg}. Set FORCE_ENABLE_CUDAQ=1 to override."
+
+    return False, ""
+
+
 simulate_qlbm_3D_and_animate = None
+_SIMULATION_BACKEND_DISABLED, _SIMULATION_DISABLED_REASON = _should_disable_quantum_backend()
 
-def _detect_gpu_available():
-    """Check if NVIDIA GPU is available."""
-    nvidia_devices = os.environ.get("NVIDIA_VISIBLE_DEVICES")
-    cuda_devices = os.environ.get("CUDA_VISIBLE_DEVICES")
-    
-    def _has_devices(val):
-        if not val:
-            return False
-        return val.strip().lower() not in ("", "none", "nodevfiles", "-1")
-    
-    has_env = _has_devices(nvidia_devices) or _has_devices(cuda_devices)
-    has_proc = os.path.exists("/proc/driver/nvidia/version")
-    has_smi = shutil.which("nvidia-smi") is not None
-    return has_env or has_proc or has_smi
-
-def _lazy_import_simulation():
-    """Lazily import simulation module only when GPU is available."""
-    global simulate_qlbm_3D_and_animate
-    if simulate_qlbm_3D_and_animate is not None:
-        return simulate_qlbm_3D_and_animate
-    
-    if not _detect_gpu_available():
-        print("Warning: No GPU detected, simulation module not loaded.")
-        return None
-    
+if not _SIMULATION_BACKEND_DISABLED:
     try:
-        from fluid3d_pyvista import simulate_qlbm_3D_and_animate as sim_func
-        simulate_qlbm_3D_and_animate = sim_func
-        return sim_func
+        from fluid3d_pyvista import simulate_qlbm_3D_and_animate  # type: ignore
     except ImportError:
         try:
-            from quantum.fluid3d_pyvista import simulate_qlbm_3D_and_animate as sim_func
-            simulate_qlbm_3D_and_animate = sim_func
-            return sim_func
-        except ImportError:
-            print("Warning: fluid3d_pyvista not found.")
-            return None
+            from quantum.fluid3d_pyvista import simulate_qlbm_3D_and_animate  # type: ignore
+        except ImportError as exc:
+            _SIMULATION_DISABLED_REASON = "Simulation module not found."
+            simulate_qlbm_3D_and_animate = None
+            print(f"Warning: {exc}")
+    except Exception as exc:  # pragma: no cover - defensive guard for HF runtime
+        _SIMULATION_DISABLED_REASON = f"Failed to load CUDA-Q backend: {exc}"
+        simulate_qlbm_3D_and_animate = None
+else:
+    _SIMULATION_DISABLED_REASON = _SIMULATION_DISABLED_REASON or "Quantum backend disabled by environment settings."
+
+_SIMULATION_BACKEND_READY = simulate_qlbm_3D_and_animate is not None
+if not _SIMULATION_BACKEND_READY and _SIMULATION_DISABLED_REASON:
+    print(f"Warning: {_SIMULATION_DISABLED_REASON}")
 
 # --- Server Setup ---
 server = get_server()
@@ -115,6 +121,8 @@ state.update({
     "simulation_has_run": False,
     "time_val": 0,
     "max_time_step": 0,
+    "simulation_backend_ready": _SIMULATION_BACKEND_READY,
+    "simulation_disabled_reason": _SIMULATION_DISABLED_REASON,
     # Workflow guidance styles
     "workflow_step": 0,
     "overview_card_style": _WORKFLOW_BASE_STYLE,
@@ -508,13 +516,8 @@ def update_geometry_view():
 def run_simulation():
     global simulation_data_frames, simulation_times, current_grid_object
     
-    # Lazy import with GPU check
-    sim_func = _lazy_import_simulation()
-    if sim_func is None:
-        if not _detect_gpu_available():
-            state.run_error = "Simulation requires NVIDIA GPU which is not available in this environment."
-        else:
-            state.run_error = "Simulation module not found."
+    if simulate_qlbm_3D_and_animate is None:
+        state.run_error = _SIMULATION_DISABLED_REASON or "Simulation module is not available on this platform."
         return
 
     state.is_running = True
@@ -537,7 +540,7 @@ def run_simulation():
         # 2. Run Simulation
         # Note: simulate_qlbm_3D_and_animate updates the passed plotter with the first frame
         plotter.clear()
-        _, frames, times, grid_obj = sim_func(
+        _, frames, times, grid_obj = simulate_qlbm_3D_and_animate(
             num_reg_qubits=num_reg_qubits,
             T=T,
             distribution_type=distribution_type,
@@ -1004,10 +1007,18 @@ with SinglePageLayout(server) as layout:
                                 text="Run Simulation",
                                 color="primary",
                                 block=True,
-                                disabled=("is_running", False),
+                                disabled=("is_running || !simulation_backend_ready", False),
                                 click=run_simulation,
                                 style=("is_running ? '' : 'background-color:#87CEFA;'", ""),
                             )
+                            vuetify3.VAlert(
+                                v_if="simulation_disabled_reason",
+                                type="warning",
+                                variant="tonal",
+                                density="compact",
+                                children=["{{ simulation_disabled_reason }}"],
+                                classes="mt-2",
+                            )
                             with vuetify3.VRow(dense=True, classes="mt-2"):
                                 with vuetify3.VCol(cols=6):
                                     vuetify3.VBtn(