quantui 0.5.1__py3-none-any.whl

quantui/user_settings.py

@@ -0,0 +1,238 @@
+"""
+User preference persistence for QuantUI.
+
+Settings are stored at ``~/.quantui/settings.json`` (override with the
+``QUANTUI_SETTINGS_PATH`` environment variable for testing). The schema is
+section-based for additive growth — new feature areas (theme, defaults,
+etc.) add their own top-level sections without breaking existing readers.
+
+Robustness rules
+----------------
+- **Atomic writes** — write to ``settings.json.tmp`` then rename, so a
+  crash mid-write cannot corrupt the file.
+- **Graceful fallback** — missing file, malformed JSON, unknown schema
+  version, missing sections, or invalid field values all silently fall
+  back to defaults with a single warning log. Startup never crashes on
+  bad settings.
+- **Additive-friendly** — new fields use defaults if absent in older
+  saved files. Unknown fields are tolerated on read (no crash).
+- **Schema versioning** — ``_schema_version`` is bumped only for breaking
+  changes; additive changes keep the same version. Mismatched versions
+  fall back to defaults.
+
+Typical usage
+-------------
+>>> from quantui.user_settings import UserSettings
+>>> settings = UserSettings.load()              # at app startup
+>>> settings.viz.default_backend = "py3dmol"
+>>> settings.save()                              # on settings change
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+_SCHEMA_VERSION = 1
+_LOG = logging.getLogger(__name__)
+
+# Valid values for VizSettings.default_backend. Kept in sync with
+# quantui.viz_backend_router.VizPreference values; not imported here to keep
+# this module zero-dependency for unit testing.
+_VALID_VIZ_BACKENDS = ("auto", "py3dmol", "plotlymol")
+
+# Vibrational animation playback rate. Clamped to a sensible range on load
+# so a corrupt value can't produce a 0-ms or absurdly high interval.
+_VIB_FPS_MIN = 1
+_VIB_FPS_MAX = 120
+_VIB_FPS_DEFAULT = 10
+
+# Default settings path. The QUANTUI_SETTINGS_PATH env var overrides for tests.
+DEFAULT_SETTINGS_PATH = Path.home() / ".quantui" / "settings.json"
+
+
+@dataclass
+class VizSettings:
+    """Visualization-related user preferences."""
+
+    default_backend: str = "auto"  # one of _VALID_VIZ_BACKENDS
+    vib_framerate_fps: int = _VIB_FPS_DEFAULT  # py3Dmol vib-animation fps
+
+
+@dataclass
+class ComputeSettings:
+    """Compute-related user preferences."""
+
+    # Whether GPU offload may engage when a CUDA device is detected. Default on
+    # — the historical behavior. Users on consumer cards (weak FP64, see
+    # gpu_offload.is_low_fp64_device) may want this off, since offload can be
+    # slower than a many-core CPU there. ``QUANTUI_DISABLE_GPU=1`` still wins
+    # over this setting.
+    gpu_enabled: bool = True
+
+
+@dataclass
+class UserSettings:
+    """Root user settings container — section-based for additive growth."""
+
+    viz: VizSettings = field(default_factory=VizSettings)
+    compute: ComputeSettings = field(default_factory=ComputeSettings)
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> UserSettings:
+        """Load settings from disk, falling back to defaults on any failure.
+
+        Missing file, malformed JSON, unknown schema version, malformed
+        sections, and invalid field values all return the default
+        ``UserSettings`` with one warning log per failure mode.
+        """
+        resolved = cls._resolve_path(path)
+        if not resolved.exists():
+            return cls()
+        try:
+            data = json.loads(resolved.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            _LOG.warning(
+                "Failed to read settings at %s (%s); using defaults",
+                resolved,
+                exc,
+            )
+            return cls()
+        return cls._from_dict(data)
+
+    @classmethod
+    def _from_dict(cls, data: object) -> UserSettings:
+        """Parse a deserialized JSON object into a UserSettings instance."""
+        if not isinstance(data, dict):
+            _LOG.warning(
+                "Settings root is not a JSON object (got %s); using defaults",
+                type(data).__name__,
+            )
+            return cls()
+
+        version = data.get("_schema_version")
+        if version != _SCHEMA_VERSION:
+            _LOG.warning(
+                "Settings schema version %r does not match current %r; "
+                "using defaults",
+                version,
+                _SCHEMA_VERSION,
+            )
+            return cls()
+
+        viz_section = data.get("viz", {})
+        if not isinstance(viz_section, dict):
+            _LOG.warning(
+                "Settings 'viz' section is not an object (got %s); "
+                "using viz defaults",
+                type(viz_section).__name__,
+            )
+            viz_section = {}
+
+        viz = VizSettings()
+        candidate_backend = viz_section.get("default_backend", viz.default_backend)
+        if (
+            isinstance(candidate_backend, str)
+            and candidate_backend in _VALID_VIZ_BACKENDS
+        ):
+            viz.default_backend = candidate_backend
+        else:
+            _LOG.warning(
+                "Invalid viz.default_backend %r; using %r",
+                candidate_backend,
+                viz.default_backend,
+            )
+
+        candidate_fps = viz_section.get("vib_framerate_fps", viz.vib_framerate_fps)
+        if (
+            isinstance(candidate_fps, int)
+            and not isinstance(candidate_fps, bool)
+            and _VIB_FPS_MIN <= candidate_fps <= _VIB_FPS_MAX
+        ):
+            viz.vib_framerate_fps = candidate_fps
+        else:
+            _LOG.warning(
+                "Invalid viz.vib_framerate_fps %r; using %r",
+                candidate_fps,
+                viz.vib_framerate_fps,
+            )
+
+        compute_section = data.get("compute", {})
+        if not isinstance(compute_section, dict):
+            _LOG.warning(
+                "Settings 'compute' section is not an object (got %s); "
+                "using compute defaults",
+                type(compute_section).__name__,
+            )
+            compute_section = {}
+
+        compute = ComputeSettings()
+        if "gpu_enabled" in compute_section:
+            candidate_gpu = compute_section["gpu_enabled"]
+            if isinstance(candidate_gpu, bool):
+                compute.gpu_enabled = candidate_gpu
+            else:
+                _LOG.warning(
+                    "Invalid compute.gpu_enabled %r; using %r",
+                    candidate_gpu,
+                    compute.gpu_enabled,
+                )
+
+        return cls(viz=viz, compute=compute)
+
+    def to_dict(self) -> dict:
+        """Serialize to a dict for JSON storage with the current schema version."""
+        return {
+            "_schema_version": _SCHEMA_VERSION,
+            "viz": asdict(self.viz),
+            "compute": asdict(self.compute),
+        }
+
+    def save(self, path: Path | None = None) -> None:
+        """Write settings to disk atomically (write to .tmp then rename).
+
+        Does not raise on filesystem failure — logs a warning and continues.
+        Callers should not assume the save succeeded on a hostile filesystem;
+        the next load will fall back to defaults if the file is missing.
+        """
+        resolved = self._resolve_path(path)
+        try:
+            resolved.parent.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            _LOG.warning(
+                "Failed to create settings parent dir %s (%s); save aborted",
+                resolved.parent,
+                exc,
+            )
+            return
+
+        tmp = resolved.with_suffix(resolved.suffix + ".tmp")
+        try:
+            tmp.write_text(
+                json.dumps(self.to_dict(), indent=2) + "\n",
+                encoding="utf-8",
+            )
+            os.replace(tmp, resolved)
+        except OSError as exc:
+            _LOG.warning(
+                "Failed to save settings to %s (%s)",
+                resolved,
+                exc,
+            )
+            try:
+                if tmp.exists():
+                    tmp.unlink()
+            except OSError:
+                pass
+
+    @classmethod
+    def _resolve_path(cls, path: Path | None) -> Path:
+        if path is not None:
+            return Path(path)
+        env_override = os.environ.get("QUANTUI_SETTINGS_PATH")
+        if env_override:
+            return Path(env_override)
+        return DEFAULT_SETTINGS_PATH

quantui/utils.py

@@ -0,0 +1,287 @@
+"""
+QuantUI Utilities Module
+
+Helper functions for validation, session resource detection, and general
+utilities used across the application. SLURM-specific helpers (job ID
+parsing, walltime formatting, job directory management) have been removed.
+"""
+
+import logging
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from . import config
+
+# M14 audit fix (2026-07-14): logging.basicConfig() configures the *root*
+# logger process-wide the moment this module is imported (which
+# quantui/__init__ always does) — a library must never do this, since it
+# silently hijacks/duplicates whatever logging setup the host application
+# or notebook already has. quantui/__init__.py already attaches a
+# NullHandler to the package logger; host apps that want console output
+# can call logging.basicConfig() themselves, optionally using
+# config.LOG_LEVEL / config.LOG_FORMAT as defaults.
+logger = logging.getLogger(__name__)
+
+
+def get_username() -> str:
+    """
+    Detect the current username from environment variables.
+
+    Tries multiple environment variables to handle different systems:
+    - JUPYTERHUB_USER (JupyterHub)
+    - USER (Linux/Mac)
+    - USERNAME (Windows)
+
+    Returns:
+        str: The detected username
+
+    Raises:
+        RuntimeError: If username cannot be detected
+    """
+    username = (
+        os.getenv("JUPYTERHUB_USER") or os.getenv("USER") or os.getenv("USERNAME")
+    )
+
+    if not username:
+        raise RuntimeError(
+            "Could not detect username. Please ensure you are running in a "
+            "supported environment (JupyterHub, Linux, Mac, or Windows)."
+        )
+
+    username = sanitize_filename(username)
+    logger.info(f"Detected username: {username}")
+    return username
+
+
+def sanitize_filename(filename: str) -> str:
+    """
+    Sanitize a string for safe use in filenames and paths.
+
+    Args:
+        filename: The string to sanitize
+
+    Returns:
+        str: Sanitized string safe for use in filenames
+    """
+    filename = filename.replace(" ", "_")
+    filename = re.sub(r"[^\w\-.]", "", filename)
+    return filename
+
+
+def ensure_directory(path: Path) -> Path:
+    """
+    Ensure a directory exists, creating it if necessary.
+
+    Args:
+        path: Path to the directory
+
+    Returns:
+        Path: The path object (for chaining)
+    """
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+    logger.debug(f"Ensured directory exists: {path}")
+    return path
+
+
+def validate_atom_symbol(symbol: str) -> bool:
+    """
+    Validate if a string is a valid atomic symbol.
+
+    Args:
+        symbol: Atomic symbol to validate (e.g., 'H', 'C', 'O')
+
+    Returns:
+        bool: True if valid, False otherwise
+    """
+    return symbol.strip() in config.VALID_ATOMS
+
+
+def validate_coordinates(coords: List[float]) -> bool:
+    """
+    Validate that coordinates are a list of 3 numbers.
+
+    Args:
+        coords: List of coordinate values
+
+    Returns:
+        bool: True if valid, False otherwise
+    """
+    if not isinstance(coords, (list, tuple)):
+        return False
+    if len(coords) != 3:
+        return False
+    try:
+        [float(x) for x in coords]
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+def validate_charge(charge: int) -> bool:
+    """
+    Validate molecular charge.
+
+    Args:
+        charge: Charge value
+
+    Returns:
+        bool: True if valid (reasonable range), False otherwise
+    """
+    if not isinstance(charge, int):
+        return False
+    return -10 <= charge <= 10
+
+
+def validate_multiplicity(multiplicity: int) -> bool:
+    """
+    Validate spin multiplicity.
+
+    Args:
+        multiplicity: Multiplicity value (2S+1)
+
+    Returns:
+        bool: True if valid, False otherwise
+    """
+    try:
+        multiplicity = int(multiplicity)
+        return 1 <= multiplicity <= 10
+    except (ValueError, TypeError):
+        return False
+
+
+def student_friendly_error(error: Exception, context: str = "") -> str:
+    """
+    Convert technical errors into student-friendly messages.
+
+    Args:
+        error: The exception that occurred
+        context: Additional context about what was being attempted
+
+    Returns:
+        str: User-friendly error message
+    """
+    error_str = str(error).lower()
+
+    if "command not found" in error_str or "no such file" in error_str:
+        return (
+            f"System Error: Required software not found. "
+            f"Please contact your instructor.\n"
+            f"Technical details: {context}"
+        )
+
+    if "permission denied" in error_str:
+        return (
+            f"Permission Error: You don't have access to perform this operation. "
+            f"Please contact your instructor.\n"
+            f"Technical details: {context}"
+        )
+
+    if "connection" in error_str or "timeout" in error_str:
+        return (
+            f"Connection Error: Cannot reach the requested service. "
+            f"Please check your network connection or try again later.\n"
+            f"Technical details: {context}"
+        )
+
+    return (
+        f"Error: Something went wrong while {context}. "
+        f"Please try again or contact your instructor if the problem persists.\n"
+        f"Technical details: {str(error)}"
+    )
+
+
+def format_file_size(size_bytes: int) -> str:
+    """
+    Format file size in human-readable format.
+
+    Args:
+        size_bytes: File size in bytes
+
+    Returns:
+        str: Formatted size (e.g., "1.5 MB")
+    """
+    size = float(size_bytes)
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size < 1024.0:
+            return f"{size:.1f} {unit}"
+        size /= 1024.0
+    return f"{size:.1f} TB"
+
+
+def get_timestamp() -> str:
+    """
+    Get current timestamp in ISO format.
+
+    Returns:
+        str: ISO format timestamp
+    """
+    return datetime.now().isoformat()
+
+
+def truncate_string(s: str, max_length: int = 100) -> str:
+    """
+    Truncate a string to maximum length with ellipsis.
+
+    Args:
+        s: String to truncate
+        max_length: Maximum length
+
+    Returns:
+        str: Truncated string
+    """
+    if len(s) <= max_length:
+        return s
+    return s[: max_length - 3] + "..."
+
+
+def get_session_resources() -> Tuple[int, Optional[int]]:
+    """
+    Detect available CPU cores and memory in the current process environment.
+
+    Returns:
+        Tuple of (available_cores, available_memory_gb).
+        available_memory_gb is None when psutil is not installed.
+    """
+    try:
+        # sched_getaffinity respects cgroup/container CPU limits (Linux only)
+        available_cores = len(os.sched_getaffinity(0))  # type: ignore[attr-defined]
+    except (AttributeError, OSError, NotImplementedError):
+        # Windows / macOS fallback, or restricted container without sched_getaffinity
+        available_cores = os.cpu_count() or 1
+    try:
+        import psutil
+
+        mem_gb: Optional[int] = psutil.virtual_memory().available // (1024**3)
+    except ImportError:
+        mem_gb = None
+    return available_cores, mem_gb
+
+
+def session_can_handle(
+    estimated_cores: int,
+    estimated_memory_gb: int,
+    pyscf_available: bool = True,
+) -> bool:
+    """
+    Return True if the current session can likely run a calculation locally.
+
+    Args:
+        estimated_cores: Number of cores the job needs.
+        estimated_memory_gb: Memory the job needs in GB.
+        pyscf_available: Whether PySCF is importable in this environment.
+
+    Returns:
+        True if local execution looks feasible, False otherwise.
+    """
+    if not pyscf_available:
+        return False
+    cores, mem_gb = get_session_resources()
+    if estimated_cores > cores:
+        return False
+    if mem_gb is not None and estimated_memory_gb > mem_gb:
+        return False
+    return True