quantui 0.5.1__py3-none-any.whl

quantui/c_stderr.py

@@ -0,0 +1,124 @@
+"""POSIX file-descriptor stderr capture.
+
+PySCF and its C-extension dependencies (libcint, BLAS/LAPACK, dftd3) write
+diagnostic messages directly to file-descriptor 2 (the OS-level stderr),
+bypassing Python's ``sys.stderr`` and PySCF's own ``mol.stdout`` routing.
+In a Voilà notebook those bytes surface as red error text above the cell
+output even when the calculation succeeded — visually alarming, and
+indistinguishable at a glance from a real failure.
+
+This module provides ``capture_c_stderr(relay_stream=...)``, a context
+manager that redirects fd 2 to a private temp file for the duration of
+the block, then drains the captured bytes into the supplied relay stream
+on exit. The end result: C-level diagnostics still reach the user (no
+information loss), but through the normal live-log channel rather than
+the red-text channel.
+
+The implementation is POSIX-only (uses ``os.dup`` / ``os.dup2`` on fd 2).
+On Windows the context is a no-op and yields immediately — safe to use
+unconditionally since PySCF is Linux/macOS/WSL only and the rest of the
+app's runtime gates on platform separately.
+
+Thread-safety note: fd 2 is a process-global resource. QuantUI runs at
+most one calculation at a time (the Run button is disabled during a run
+and the work happens on a single background thread), so the standard
+guidance is "use this only when no other code in the process is writing
+to fd 2 concurrently". Nested contexts work correctly — each push/pop
+saves and restores the previous fd 2 binding.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import tempfile
+from typing import IO, Optional
+
+
+@contextlib.contextmanager
+def capture_c_stderr(relay_stream: Optional[IO[str]] = None):
+    """Capture fd-level stderr to a temp file, relay on exit.
+
+    Parameters
+    ----------
+    relay_stream:
+        Optional writable text stream that receives the captured bytes
+        (decoded UTF-8, replace on bad bytes) when the context exits. When
+        ``None``, captured output is silently dropped — useful when the
+        caller only wants the noise gone, not surfaced anywhere.
+
+    Notes
+    -----
+    Output is buffered to a temp file during the block and flushed to
+    ``relay_stream`` exactly once at exit. For long-running calculations
+    that emit periodic warnings (e.g. an iterative SCF that prints one
+    warning per cycle), the user sees the warnings as a single batch at
+    the end rather than streamed in real time. This is a conscious trade-
+    off: real-time streaming would require a pipe + drainer thread, which
+    isn't worth the complexity for the typical "occasional libcint /
+    BLAS warning" use case.
+
+    The temp file is unlinked automatically by ``TemporaryFile``; no
+    cleanup is required from the caller.
+
+    On non-POSIX platforms the context manager yields immediately and
+    relay_stream is never written to.
+    """
+    if os.name != "posix":
+        yield
+        return
+
+    # Flush any Python-level stderr first so it doesn't get mixed in
+    # with what we're about to capture.
+    try:
+        sys.stderr.flush()
+    except Exception:
+        pass
+
+    # Binary temp file: C-level writes are bytes, not text.
+    tmp = tempfile.TemporaryFile(mode="w+b")
+    saved_fd: Optional[int] = None
+    try:
+        saved_fd = os.dup(2)
+        os.dup2(tmp.fileno(), 2)
+        try:
+            yield
+        finally:
+            # Flush stderr (Python-level) before we tear the fd back so
+            # any pending writes land in the temp file rather than getting
+            # routed to the restored fd.
+            try:
+                sys.stderr.flush()
+            except Exception:
+                pass
+            # Restore fd 2 before reading the temp file — otherwise any
+            # write to stderr during the read (e.g. by relay_stream itself)
+            # would loop back into the still-redirected fd.
+            os.dup2(saved_fd, 2)
+    finally:
+        if saved_fd is not None:
+            try:
+                os.close(saved_fd)
+            except OSError:
+                pass
+
+        # Drain captured bytes (best-effort) and relay.
+        captured = b""
+        try:
+            tmp.flush()
+            tmp.seek(0)
+            captured = tmp.read()
+        except Exception:
+            pass
+        finally:
+            try:
+                tmp.close()
+            except Exception:
+                pass
+
+        if captured and relay_stream is not None:
+            try:
+                relay_stream.write(captured.decode("utf-8", errors="replace"))
+            except Exception:
+                pass

quantui/cactus.py

@@ -0,0 +1,88 @@
+"""NCI CACTUS Chemical Identifier Resolver.
+
+A chained fallback after PubChem. CACTUS resolves a wide range of identifiers
+(common name, IUPAC name, CAS number, InChI, SMILES, formula) to a 3D SDF with
+no API key. It often answers queries PubChem misses — CAS numbers in
+particular.
+
+Best-effort by design: every failure mode (miss, network error, malformed
+response) raises one of the shared PubChem exception types so the provider
+chain in :mod:`quantui.structure_providers` can treat all resolvers uniformly.
+"""
+
+import logging
+from typing import Any, Dict, Tuple
+from urllib.parse import quote
+
+import requests
+
+from . import config
+from .pubchem import MoleculeNotFoundError, PubChemAPIError, sdf_to_xyz
+
+logger = logging.getLogger(__name__)
+
+# CACTUS resolver base. The ``/file?format=sdf&get3d=true`` form returns a 3D
+# SDF; the bare ``/sdf`` form returns whatever (often 2D) CACTUS has.
+CACTUS_BASE_URL = "https://cactus.nci.nih.gov/chemical/structure"
+
+
+def _looks_like_sdf(text: str) -> bool:
+    """CACTUS returns an HTML error page (HTTP 200) for unknown identifiers.
+
+    A real SDF molfile always carries the ``V2000``/``V3000`` counts-line tag
+    and the ``M  END`` terminator, so key off those rather than the status code.
+    """
+    return "M  END" in text and ("V2000" in text or "V3000" in text)
+
+
+def resolve_to_sdf(identifier: str, conformer_3d: bool = True) -> str:
+    """Resolve an identifier to SDF text via CACTUS.
+
+    Tries the 3D endpoint first, then falls back to the plain ``/sdf`` form
+    (whose coordinates RDKit will embed downstream if they are 2D).
+
+    Raises:
+        MoleculeNotFoundError: CACTUS has no structure for the identifier.
+        PubChemAPIError: network/transport failure reaching CACTUS.
+    """
+    enc = quote(identifier, safe="")
+    urls = []
+    if conformer_3d:
+        urls.append(f"{CACTUS_BASE_URL}/{enc}/file?format=sdf&get3d=true")
+    urls.append(f"{CACTUS_BASE_URL}/{enc}/sdf")
+
+    # (connect, read) timeouts: fail fast on an unreachable host, and cap the
+    # read so a slow CACTUS can't hang the search (it's only a fallback).
+    timeout = (config.CACTUS_CONNECT_TIMEOUT_S, config.CACTUS_TIMEOUT_S)
+    last_status = None
+    try:
+        for url in urls:
+            logger.debug(f"CACTUS resolving: {url}")
+            response = requests.get(url, timeout=timeout)
+            last_status = response.status_code
+            if response.status_code == 200 and _looks_like_sdf(response.text):
+                return str(response.text)
+    except requests.RequestException as e:
+        logger.error(f"CACTUS request failed: {e}")
+        raise PubChemAPIError(f"Failed to connect to CACTUS: {e}") from e
+
+    raise MoleculeNotFoundError(
+        f"CACTUS could not resolve '{identifier}' (last status: {last_status})"
+    )
+
+
+def fetch_from_cactus(
+    identifier: str, conformer_3d: bool = True
+) -> Tuple[str, Dict[str, Any]]:
+    """Resolve an identifier to ``(xyz_string, metadata)`` via CACTUS.
+
+    Metadata carries ``source="cactus"`` and a ``conformer_origin`` describing
+    whether RDKit had to embed the coordinates.
+    """
+    sdf_content = resolve_to_sdf(identifier, conformer_3d=conformer_3d)
+    xyz, metadata = sdf_to_xyz(sdf_content)
+    metadata["source"] = "cactus"
+    metadata["conformer_origin"] = (
+        "rdkit-embedded" if metadata.get("coords_embedded") else "cactus"
+    )
+    return xyz, metadata