Click Run Calculation — results appear in the "
@@ -305,6 +307,36 @@
"in the QuantUI repo."
),
},
+ "finding_structures": {
+ "title": "Finding a molecule (library, search, SMILES)",
+ "body": (
+ "The Molecule Input panel offers three ways to get a "
+ "starting structure — all of which work fully offline except the "
+ "Online Search.
"
+ ""
+ "- Library — browse the bundled offline library: filter by "
+ "category (amino acids, solvents, drugs, …) or type in the "
+ "search box to match by name or formula. It includes a small "
+ "curated set plus thousands of small molecules (QM9), so you can "
+ "work with no internet connection.
"
+ "- XYZ Input — paste raw
element x y z "
+ "coordinates, one atom per line. "
+ "- Online Search — type a name (aspirin), "
+ "SMILES (
CC(=O)O), CID (2244), or "
+ "InChI. SMILES/InChI are built locally by RDKit (no network); "
+ "names and CIDs are resolved by trying PubChem, then "
+ "NCI CACTUS (which also understands CAS numbers), and finally "
+ "the bundled library if you are offline. When a name matches several "
+ "compounds (e.g. xylene), a pick-list appears so you "
+ "choose the right one instead of guessing. "
+ "
"
+ "Provenance: the status line states where a structure came "
+ "from — the library, a local SMILES build, PubChem, or CACTUS — so "
+ "you know whether coordinates are experimental, DFT-optimized, or "
+ "force-field-embedded. Either way, treat them as a starting "
+ "point and run a geometry optimization for accurate results.
"
+ ),
+ },
}
# All valid topic keys (for testing / discovery)
diff --git a/quantui/molecule_library.py b/quantui/molecule_library.py
new file mode 100644
index 0000000..b318b77
--- /dev/null
+++ b/quantui/molecule_library.py
@@ -0,0 +1,433 @@
+"""Bundled molecule library — indexed package-data store + lazy loader.
+
+The library lives in ``quantui/data/`` as two committed artifacts:
+
+- ``manifests/presets.json`` — the human-readable, reviewable source of record.
+- ``library/library.sqlite`` — an indexed, lazily-queried store generated from
+ the manifest(s). Coordinates are packed as ``int16`` @ 0.001 Å (7–8 bytes per
+ atom) so the store stays compact enough to hold the ~10 MB hybrid library
+ without bloating import time.
+
+Design goals:
+
+- **Lazy + indexed** — search/get touch only the rows they need, so the store
+ scales to tens of thousands of bulk entries without loading them all.
+- **Back-compat** — :func:`get_preset_dict` returns the exact legacy
+ ``MOLECULE_LIBRARY`` shape, so ``config.MOLECULE_LIBRARY`` and every existing
+ consumer keep working unchanged.
+- **Robust** — if the SQLite artifact is missing or unreadable, every entry
+ point transparently falls back to the JSON manifest, so ``import quantui``
+ never fails on a fresh/odd checkout.
+
+Adding curated or bulk content only adds manifests + rebuilds the store;
+nothing in this module's public API changes.
+"""
+
+import json
+import logging
+import sqlite3
+import struct
+from functools import lru_cache
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# ── Coordinate codec ─────────────────────────────────────────────────────────
+# Per-atom record: 2 bytes element symbol (ascii, 2nd byte 0 if 1-char) +
+# 3× int16 little-endian coordinate in milli-ångström. 8 bytes/atom.
+_COORD_SCALE = 1000 # 0.001 Å resolution; ±32.767 Å range (int16)
+_ATOM_RECORD = " bytes:
+ """Pack ``(atoms, coords)`` into the compact per-atom binary record."""
+ buf = bytearray()
+ for sym, (x, y, z) in zip(atoms, coords):
+ s = sym.encode("ascii")
+ if not 1 <= len(s) <= 2:
+ raise ValueError(f"Unsupported element symbol: {sym!r}")
+ c0 = s[0]
+ c1 = s[1] if len(s) > 1 else 0
+ buf += struct.pack(
+ _ATOM_RECORD,
+ c0,
+ c1,
+ round(float(x) * _COORD_SCALE),
+ round(float(y) * _COORD_SCALE),
+ round(float(z) * _COORD_SCALE),
+ )
+ return bytes(buf)
+
+
+def decode_coords(blob: bytes) -> Tuple[List[str], List[List[float]]]:
+ """Unpack a coordinate blob back into ``(atoms, coords)``."""
+ atoms: List[str] = []
+ coords: List[List[float]] = []
+ for offset in range(0, len(blob), _ATOM_RECORD_SIZE):
+ c0, c1, xi, yi, zi = struct.unpack(
+ _ATOM_RECORD, blob[offset : offset + _ATOM_RECORD_SIZE]
+ )
+ sym = chr(c0) + (chr(c1) if c1 else "")
+ atoms.append(sym)
+ coords.append([xi / _COORD_SCALE, yi / _COORD_SCALE, zi / _COORD_SCALE])
+ return atoms, coords
+
+
+# ── Paths ────────────────────────────────────────────────────────────────────
+def _data_dir() -> Path:
+ return Path(str(files("quantui"))) / "data"
+
+
+def db_path() -> Path:
+ return _data_dir() / "library" / "library.sqlite"
+
+
+def manifest_paths() -> List[Path]:
+ """All manifest JSON files that seed the store.
+
+ ``presets.json`` is ordered first so the original teaching molecules lead
+ the (interim) flat dropdown; remaining manifests follow alphabetically.
+ """
+ manifest_dir = _data_dir() / "manifests"
+ if not manifest_dir.is_dir():
+ return []
+ return sorted(
+ manifest_dir.glob("*.json"),
+ key=lambda p: (p.name != "presets.json", p.name),
+ )
+
+
+# ── Manifest loading (always-available fallback source) ──────────────────────
+@lru_cache(maxsize=1)
+def _manifest_entries() -> Tuple[Dict[str, Any], ...]:
+ """Load every manifest entry. Cached. The JSON is the source of record."""
+ entries: List[Dict[str, Any]] = []
+ for path in manifest_paths():
+ try:
+ entries.extend(json.loads(path.read_text(encoding="utf-8")))
+ except Exception as exc: # pragma: no cover - corrupt manifest
+ logger.error(f"Failed to read library manifest {path}: {exc}")
+ return tuple(entries)
+
+
+def _normalize_entry(raw: Dict[str, Any]) -> Dict[str, Any]:
+ """Fill derived fields (id/formula/n_atoms/...) for a manifest entry."""
+ atoms = raw["atoms"]
+ formula = raw.get("formula") or raw.get("id") or raw["name"]
+ return {
+ "id": raw.get("id", formula),
+ "name": raw.get("name", formula),
+ "formula": formula,
+ "category": raw.get("category", "preset"),
+ "n_atoms": len(atoms),
+ "n_heavy": sum(1 for a in atoms if a != "H"),
+ "charge": int(raw.get("charge", 0)),
+ "multiplicity": int(raw.get("multiplicity", 1)),
+ "source": raw.get("source", "preset"),
+ "smiles": raw.get("smiles"),
+ "inchikey": raw.get("inchikey"),
+ "synonyms": raw.get("synonyms", ""),
+ "description": raw.get("description", ""),
+ "atoms": atoms,
+ "coordinates": raw["coordinates"],
+ }
+
+
+# ── Store build (run by scripts/build_library.py or on-demand) ───────────────
+_SCHEMA = """
+CREATE TABLE molecule (
+ id TEXT PRIMARY KEY,
+ name TEXT,
+ formula TEXT NOT NULL,
+ category TEXT NOT NULL,
+ n_heavy INTEGER NOT NULL,
+ n_atoms INTEGER NOT NULL,
+ charge INTEGER NOT NULL DEFAULT 0,
+ multiplicity INTEGER NOT NULL DEFAULT 1,
+ source TEXT NOT NULL,
+ smiles TEXT,
+ inchikey TEXT,
+ synonyms TEXT,
+ description TEXT,
+ coords BLOB NOT NULL
+);
+CREATE INDEX idx_name ON molecule(name);
+CREATE INDEX idx_formula ON molecule(formula);
+CREATE INDEX idx_category ON molecule(category);
+CREATE INDEX idx_inchikey ON molecule(inchikey);
+"""
+
+
+def build_store(entries: List[Dict[str, Any]], target: Path) -> Path:
+ """(Re)build the SQLite store from a list of (raw) manifest entries.
+
+ Deterministic: entries are inserted in the order given, so a rebuild from
+ the same manifest yields a stable file. Overwrites ``target``.
+ """
+ target.parent.mkdir(parents=True, exist_ok=True)
+ if target.exists():
+ target.unlink()
+ con = sqlite3.connect(target)
+ try:
+ con.executescript(_SCHEMA)
+ rows = []
+ for raw in entries:
+ e = _normalize_entry(raw)
+ rows.append(
+ (
+ e["id"],
+ e["name"],
+ e["formula"],
+ e["category"],
+ e["n_heavy"],
+ e["n_atoms"],
+ e["charge"],
+ e["multiplicity"],
+ e["source"],
+ e["smiles"],
+ e["inchikey"],
+ e["synonyms"],
+ e["description"],
+ encode_coords(e["atoms"], e["coordinates"]),
+ )
+ )
+ con.executemany(
+ "INSERT INTO molecule (id, name, formula, category, n_heavy, n_atoms, "
+ "charge, multiplicity, source, smiles, inchikey, synonyms, description, "
+ "coords) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+ rows,
+ )
+ con.commit()
+ finally:
+ con.close()
+ logger.info(f"Built molecule library store: {target} ({len(entries)} entries)")
+ return target
+
+
+def build_from_manifests(target: Optional[Path] = None) -> Path:
+ """Build the store from all committed manifests. Returns the store path."""
+ target = target or db_path()
+ return build_store([dict(e) for e in _manifest_entries()], target)
+
+
+def _ensure_store() -> Optional[Path]:
+ """Best-effort: ensure the SQLite store exists. Returns its path or None.
+
+ Never raises — if the package dir is read-only (installed wheel) and the
+ store is somehow absent, callers fall back to the JSON manifest.
+ """
+ path = db_path()
+ if path.exists():
+ return path
+ try:
+ if _manifest_entries():
+ return build_from_manifests(path)
+ except Exception as exc: # pragma: no cover - read-only install w/o store
+ logger.warning(f"Could not build library store on demand: {exc}")
+ return None
+
+
+# ── Query API ────────────────────────────────────────────────────────────────
+def _connect_ro() -> Optional[sqlite3.Connection]:
+ """Open a fresh read-only connection (thread-safe per-call), or None."""
+ path = _ensure_store()
+ if path is None or not path.exists():
+ return None
+ con = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+ con.row_factory = sqlite3.Row
+ return con
+
+
+def _row_to_entry(row: sqlite3.Row) -> Dict[str, Any]:
+ atoms, coords = decode_coords(row["coords"])
+ return {
+ "id": row["id"],
+ "name": row["name"],
+ "formula": row["formula"],
+ "category": row["category"],
+ "n_heavy": row["n_heavy"],
+ "n_atoms": row["n_atoms"],
+ "charge": row["charge"],
+ "multiplicity": row["multiplicity"],
+ "source": row["source"],
+ "smiles": row["smiles"],
+ "inchikey": row["inchikey"],
+ "synonyms": row["synonyms"],
+ "description": row["description"],
+ "atoms": atoms,
+ "coordinates": coords,
+ }
+
+
+@lru_cache(maxsize=1)
+def get_preset_dict() -> Dict[str, Dict[str, Any]]:
+ """Return the curated/preset entries in the legacy ``MOLECULE_LIBRARY`` shape.
+
+ Keyed by entry id (the formula key, e.g. ``"H2O"``); each value carries the
+ legacy ``atoms`` / ``coordinates`` / ``charge`` / ``multiplicity`` /
+ ``description`` fields. Bulk categories are excluded (they are reached via
+ :func:`search`, never the browse dropdown). Preserves manifest order.
+
+ Prefers the SQLite store; falls back to the JSON manifest if the store is
+ unavailable, so this never hard-fails.
+ """
+ out: Dict[str, Dict[str, Any]] = {}
+ con = _connect_ro()
+ if con is not None:
+ try:
+ placeholders = ",".join("?" * len(_BULK_CATEGORIES))
+ rows = con.execute(
+ f"SELECT * FROM molecule WHERE category NOT IN ({placeholders}) "
+ "ORDER BY rowid",
+ tuple(_BULK_CATEGORIES),
+ ).fetchall()
+ for row in rows:
+ e = _row_to_entry(row)
+ out[e["id"]] = _legacy_view(e)
+ return out
+ except Exception as exc: # pragma: no cover - corrupt store
+ logger.warning(f"Library store unreadable, using manifest: {exc}")
+ finally:
+ con.close()
+ # JSON fallback.
+ for raw in _manifest_entries():
+ e = _normalize_entry(raw)
+ if e["category"] in _BULK_CATEGORIES:
+ continue
+ out[e["id"]] = _legacy_view(e)
+ return out
+
+
+def _legacy_view(entry: Dict[str, Any]) -> Dict[str, Any]:
+ """Project a full entry down to the legacy MOLECULE_LIBRARY value shape."""
+ return {
+ "atoms": entry["atoms"],
+ "coordinates": entry["coordinates"],
+ "charge": entry["charge"],
+ "multiplicity": entry["multiplicity"],
+ "description": entry["description"],
+ }
+
+
+def get(entry_id: str) -> Optional[Dict[str, Any]]:
+ """Fetch one full entry (incl. decoded coordinates) by id, or None."""
+ con = _connect_ro()
+ if con is not None:
+ try:
+ row = con.execute(
+ "SELECT * FROM molecule WHERE id = ?", (entry_id,)
+ ).fetchone()
+ return _row_to_entry(row) if row else None
+ finally:
+ con.close()
+ for raw in _manifest_entries():
+ e = _normalize_entry(raw)
+ if e["id"] == entry_id:
+ return e
+ return None
+
+
+def search(
+ query: str = "", *, category: Optional[str] = None, limit: int = 50
+) -> List[Dict[str, Any]]:
+ """Search the library by name / formula / synonyms (substring, case-insensitive).
+
+ Returns lightweight rows (no coordinates) for listing; call :func:`get` to
+ materialize the chosen entry. Empty ``query`` lists entries (optionally
+ filtered by ``category``).
+ """
+ q = f"%{query.strip().lower()}%"
+ con = _connect_ro()
+ if con is not None:
+ try:
+ sql = (
+ "SELECT id, name, formula, category, n_heavy, n_atoms, charge, "
+ "multiplicity, source FROM molecule WHERE "
+ "(lower(name) LIKE ? OR lower(formula) LIKE ? OR lower(synonyms) LIKE ?)"
+ )
+ params: List[Any] = [q, q, q]
+ if category:
+ sql += " AND category = ?"
+ params.append(category)
+ sql += " ORDER BY n_atoms, id LIMIT ?"
+ params.append(limit)
+ return [dict(r) for r in con.execute(sql, params).fetchall()]
+ finally:
+ con.close()
+ # JSON fallback (linear scan).
+ needle = query.strip().lower()
+ results = []
+ for raw in _manifest_entries():
+ e = _normalize_entry(raw)
+ hay = f"{e['name']} {e['formula']} {e['synonyms']}".lower()
+ if needle in hay and (category is None or e["category"] == category):
+ results.append(
+ {
+ k: e[k]
+ for k in (
+ "id",
+ "name",
+ "formula",
+ "category",
+ "n_heavy",
+ "n_atoms",
+ "charge",
+ "multiplicity",
+ "source",
+ )
+ }
+ )
+ results.sort(key=lambda r: (r["n_atoms"], r["id"]))
+ return results[:limit]
+
+
+def categories() -> List[str]:
+ """Distinct category labels present in the library."""
+ con = _connect_ro()
+ if con is not None:
+ try:
+ return [
+ r[0]
+ for r in con.execute(
+ "SELECT DISTINCT category FROM molecule ORDER BY category"
+ ).fetchall()
+ ]
+ finally:
+ con.close()
+ return sorted({_normalize_entry(e)["category"] for e in _manifest_entries()})
+
+
+def count() -> int:
+ """Total number of entries in the library."""
+ con = _connect_ro()
+ if con is not None:
+ try:
+ return int(con.execute("SELECT COUNT(*) FROM molecule").fetchone()[0])
+ finally:
+ con.close()
+ return len(_manifest_entries())
+
+
+def iter_entries():
+ """Yield every entry (full, with decoded coordinates) in store order.
+
+ Single connection — efficient for whole-library governance/round-trip
+ checks. Falls back to the JSON manifest if the store is absent.
+ """
+ con = _connect_ro()
+ if con is None:
+ for raw in _manifest_entries():
+ yield _normalize_entry(raw)
+ return
+ try:
+ for row in con.execute("SELECT * FROM molecule ORDER BY rowid"):
+ yield _row_to_entry(row)
+ finally:
+ con.close()
diff --git a/quantui/orbital_visualization.py b/quantui/orbital_visualization.py
index 7ef9701..546a03b 100644
--- a/quantui/orbital_visualization.py
+++ b/quantui/orbital_visualization.py
@@ -696,6 +696,12 @@ def generate_cube_from_arrays(
# Cube-file isosurface viewer (plotly — works anywhere)
# ============================================================================
+# Max grid points handed to one go.Isosurface trace. The cube grid is a fixed
+# resolution regardless of molecule size, so the volume is strided down to this
+# cap at render time to keep the figure payload bounded; the saved .cube keeps
+# full resolution.
+_MAX_ISOSURFACE_POINTS = 48_000
+
def parse_cube_file(cube_path: Path) -> dict:
"""
@@ -845,33 +851,25 @@ def plot_cube_isosurface(
origin = cube["origin"]
axes = cube["axes"]
- # Build coordinate grids (Bohr)
- x = origin[0] + np.arange(nx) * axes[0, 0]
- y = origin[1] + np.arange(ny) * axes[1, 1]
- z = origin[2] + np.arange(nz) * axes[2, 2]
+ # Downsample so the browser payload + plotly.js isosurfacing stay bounded.
+ # Stride each axis so the total point count stays under _MAX_ISOSURFACE_POINTS.
+ total = nx * ny * nz
+ stride = 1
+ if total > _MAX_ISOSURFACE_POINTS:
+ stride = int(np.ceil((total / _MAX_ISOSURFACE_POINTS) ** (1.0 / 3.0)))
+ data = data[::stride, ::stride, ::stride]
+
+ # Build coordinate grids (Bohr), strided to match the downsampled volume.
+ x = origin[0] + np.arange(nx)[::stride] * axes[0, 0]
+ y = origin[1] + np.arange(ny)[::stride] * axes[1, 1]
+ z = origin[2] + np.arange(nz)[::stride] * axes[2, 2]
X, Y, Z = np.meshgrid(x, y, z, indexing="ij")
fig = go.Figure()
- # Positive lobe (blue)
- fig.add_trace(
- go.Isosurface(
- x=X.flatten(),
- y=Y.flatten(),
- z=Z.flatten(),
- value=data.flatten(),
- isomin=isovalue,
- isomax=isovalue,
- surface_count=1,
- opacity=opacity,
- colorscale=[[0, "rgb(49,130,189)"], [1, "rgb(49,130,189)"]],
- showscale=False,
- name=f"+{isovalue}",
- caps=dict(x_show=False, y_show=False, z_show=False),
- )
- )
-
- # Negative lobe (red)
+ # Both lobes in a single trace (half the payload of two): surfaces at
+ # -isovalue (red) and +isovalue (blue), via a step colorscale split at the
+ # midpoint of [-isovalue, +isovalue].
fig.add_trace(
go.Isosurface(
x=X.flatten(),
@@ -879,12 +877,19 @@ def plot_cube_isosurface(
z=Z.flatten(),
value=data.flatten(),
isomin=-isovalue,
- isomax=-isovalue,
- surface_count=1,
+ isomax=isovalue,
+ surface_count=2,
opacity=opacity,
- colorscale=[[0, "rgb(222,45,38)"], [1, "rgb(222,45,38)"]],
+ colorscale=[
+ [0.0, "rgb(222,45,38)"],
+ [0.5, "rgb(222,45,38)"],
+ [0.5, "rgb(49,130,189)"],
+ [1.0, "rgb(49,130,189)"],
+ ],
+ cmin=-isovalue,
+ cmax=isovalue,
showscale=False,
- name=f"-{isovalue}",
+ name=f"±{isovalue}",
caps=dict(x_show=False, y_show=False, z_show=False),
)
)
diff --git a/quantui/pubchem.py b/quantui/pubchem.py
index 38fd640..b7e5e33 100644
--- a/quantui/pubchem.py
+++ b/quantui/pubchem.py
@@ -6,11 +6,17 @@
"""
import logging
+import re
+import threading
+import time
from functools import lru_cache
from typing import Any, Dict, Optional, Tuple
+from urllib.parse import quote
import requests
+from . import config
+
try:
from rdkit import Chem
from rdkit.Chem import AllChem, Descriptors
@@ -24,7 +30,63 @@
# PubChem API endpoints
PUBCHEM_BASE_URL = "https://pubchem.ncbi.nlm.nih.gov/rest/pug"
-PUBCHEM_TIMEOUT = 10 # seconds
+# Back-compat alias; canonical value lives in config (constraint #5).
+PUBCHEM_TIMEOUT = config.PUBCHEM_TIMEOUT_S
+
+# ── HTTP client: client-side throttle + bounded 503 back-off ─────────────────
+# A single process-wide limiter keeps us under PUG-REST's ~5 req/s ceiling even
+# when several search threads fire at once.
+_request_lock = threading.Lock()
+_last_request_time = 0.0
+
+
+def _throttle() -> None:
+ """Block just long enough to honor the client-side minimum request gap."""
+ global _last_request_time
+ with _request_lock:
+ wait = config.PUBCHEM_MIN_REQUEST_INTERVAL_S - (
+ time.monotonic() - _last_request_time
+ )
+ if wait > 0:
+ time.sleep(wait)
+ _last_request_time = time.monotonic()
+
+
+def _http_get(
+ url: str,
+ *,
+ params: Optional[Dict[str, Any]] = None,
+ timeout: Optional[float] = None,
+) -> requests.Response:
+ """GET with client-side throttle + exponential back-off on 503 throttling.
+
+ Retries only on HTTP 503 (PUG-REST's throttle signal). All other status
+ codes are returned to the caller unchanged; network exceptions
+ (``Timeout`` / ``ConnectionError`` / ...) propagate so callers can map them
+ to :class:`PubChemAPIError` exactly as before.
+ """
+ timeout = timeout if timeout is not None else config.PUBCHEM_TIMEOUT_S
+ response = None
+ for attempt in range(config.PUBCHEM_MAX_RETRIES):
+ _throttle()
+ response = requests.get(url, params=params, timeout=timeout)
+ if response.status_code != 503:
+ return response
+ # Throttled — back off (capped) and retry, unless this was the last try.
+ if attempt < config.PUBCHEM_MAX_RETRIES - 1:
+ backoff = min(
+ config.PUBCHEM_BACKOFF_BASE_S * (2**attempt),
+ config.PUBCHEM_BACKOFF_MAX_S,
+ )
+ logger.warning(
+ "PubChem throttled (503); retrying in %.1fs (attempt %d/%d)",
+ backoff,
+ attempt + 1,
+ config.PUBCHEM_MAX_RETRIES,
+ )
+ time.sleep(backoff)
+ # Exhausted retries — hand the last 503 back; caller raises via raise_for_status.
+ return response # type: ignore[return-value]
class PubChemError(Exception):
@@ -59,11 +121,11 @@ def search_molecule_by_name(name: str) -> int:
PubChemAPIError: If API request fails
MoleculeNotFoundError: If molecule not found
"""
- url = f"{PUBCHEM_BASE_URL}/compound/name/{name}/cids/JSON"
+ url = f"{PUBCHEM_BASE_URL}/compound/name/{quote(name, safe='')}/cids/JSON"
try:
logger.debug(f"Searching PubChem for: {name}")
- response = requests.get(url, timeout=PUBCHEM_TIMEOUT)
+ response = _http_get(url)
if response.status_code == 404:
raise MoleculeNotFoundError(f"Molecule '{name}' not found in PubChem")
@@ -84,6 +146,92 @@ def search_molecule_by_name(name: str) -> int:
raise PubChemAPIError(f"Failed to connect to PubChem: {e}")
+def search_cid_by_inchikey(inchikey: str) -> int:
+ """Resolve a standard InChIKey to a PubChem CID.
+
+ InChIKeys are hashes and cannot be inverted to a structure locally, so this
+ is the one identifier type that always requires the network.
+ """
+ url = f"{PUBCHEM_BASE_URL}/compound/inchikey/{quote(inchikey, safe='')}/cids/JSON"
+ try:
+ response = _http_get(url)
+ if response.status_code == 404:
+ raise MoleculeNotFoundError(f"InChIKey '{inchikey}' not found in PubChem")
+ response.raise_for_status()
+ cids = response.json().get("IdentifierList", {}).get("CID", [])
+ if not cids:
+ raise MoleculeNotFoundError(f"No CID found for InChIKey '{inchikey}'")
+ return int(cids[0])
+ except requests.RequestException as e:
+ logger.error(f"PubChem InChIKey request failed: {e}")
+ raise PubChemAPIError(f"Failed to connect to PubChem: {e}")
+
+
+def search_cids_by_name(name: str) -> list:
+ """Return ALL PubChem CIDs matching a name (best-match order); [] if none.
+
+ Unlike :func:`search_molecule_by_name` (which returns just the first hit),
+ this exposes every match so the UI can disambiguate.
+ """
+ url = f"{PUBCHEM_BASE_URL}/compound/name/{quote(name, safe='')}/cids/JSON"
+ try:
+ response = _http_get(url)
+ if response.status_code == 404:
+ return []
+ response.raise_for_status()
+ return [
+ int(c) for c in response.json().get("IdentifierList", {}).get("CID", [])
+ ]
+ except requests.RequestException as e:
+ logger.error(f"PubChem CID-list request failed: {e}")
+ raise PubChemAPIError(f"Failed to connect to PubChem: {e}")
+
+
+def search_pubchem_candidates(query: str, max_results: int = 10) -> list:
+ """Lightweight candidate descriptors for an ambiguous name query.
+
+ Returns a list of ``{cid, title, formula, mw}`` dicts (best-match order,
+ capped at ``max_results``), or ``[]`` if nothing matches. Uses one batch
+ property request rather than fetching each full structure.
+ """
+ cids = search_cids_by_name(query)[:max_results]
+ if not cids:
+ return []
+ cid_str = ",".join(str(c) for c in cids)
+ url = (
+ f"{PUBCHEM_BASE_URL}/compound/cid/{cid_str}"
+ f"/property/MolecularFormula,MolecularWeight,Title/JSON"
+ )
+ try:
+ response = _http_get(url)
+ response.raise_for_status()
+ props = response.json().get("PropertyTable", {}).get("Properties", [])
+ except requests.RequestException as e:
+ logger.error(f"PubChem property request failed: {e}")
+ raise PubChemAPIError(f"Failed to connect to PubChem: {e}")
+
+ # Preserve the CID search order (the property endpoint may reorder).
+ by_cid = {int(p.get("CID")): p for p in props if p.get("CID") is not None}
+ out = []
+ for cid in cids:
+ p = by_cid.get(cid)
+ if p is None:
+ continue
+ try:
+ mw = float(p.get("MolecularWeight", 0) or 0)
+ except (TypeError, ValueError):
+ mw = 0.0
+ out.append(
+ {
+ "cid": cid,
+ "title": p.get("Title") or f"CID {cid}",
+ "formula": p.get("MolecularFormula", "?"),
+ "mw": mw,
+ }
+ )
+ return out
+
+
@lru_cache(maxsize=50)
def get_molecule_sdf(cid: int, conformer_3d: bool = True) -> str:
"""
@@ -109,7 +257,7 @@ def get_molecule_sdf(cid: int, conformer_3d: bool = True) -> str:
try:
logger.debug(f"Fetching {record_type.upper()} SDF for CID {cid}")
- response = requests.get(url, params=params, timeout=PUBCHEM_TIMEOUT)
+ response = _http_get(url, params=params)
if response.status_code == 404:
if conformer_3d:
@@ -129,6 +277,51 @@ def get_molecule_sdf(cid: int, conformer_3d: bool = True) -> str:
raise PubChemAPIError(f"Failed to retrieve molecule: {e}")
+def _separate_fragments(mol: Any, min_gap: float = 3.0) -> None:
+ """Push disconnected fragments (e.g. a salt's counterion) apart, in place.
+
+ RDKit's ``EmbedMolecule`` places multiple fragments in one coordinate frame
+ and frequently overlaps them — a counterion can land ~1.4 Å from the cation,
+ which distance-based bond perception then reads as a (hyper)valent bond and
+ the renderer rejects ("Valence of atom N is …, larger than allowed"). This
+ is why salts like methylene blue (cation + Cl⁻) failed.
+
+ After embedding, translate every non-largest fragment radially outward from
+ the main fragment so the closest inter-fragment gap is at least ``min_gap``
+ Å. Operates on the existing conformer; atom order is preserved. No-op for
+ single-fragment molecules.
+ """
+ if not RDKIT_AVAILABLE or mol.GetNumConformers() == 0:
+ return
+ frags = Chem.GetMolFrags(mol) # tuple of atom-index tuples, order preserved
+ if len(frags) <= 1:
+ return
+
+ import numpy as np
+ from rdkit.Geometry import Point3D
+
+ conf = mol.GetConformer()
+ pos = {i: np.array(conf.GetAtomPosition(i)) for i in range(mol.GetNumAtoms())}
+ main = max(frags, key=len)
+ main_c = np.mean([pos[i] for i in main], axis=0)
+ main_r = max((float(np.linalg.norm(pos[i] - main_c)) for i in main), default=0.0)
+ for frag in frags:
+ if frag is main:
+ continue
+ fc = np.mean([pos[i] for i in frag], axis=0)
+ fr = max((float(np.linalg.norm(pos[i] - fc)) for i in frag), default=0.0)
+ direction = fc - main_c
+ norm = float(np.linalg.norm(direction))
+ direction = direction / norm if norm > 1e-6 else np.array([1.0, 0.0, 0.0])
+ shift = (main_c + direction * (main_r + fr + min_gap)) - fc
+ for i in frag:
+ new = pos[i] + shift
+ conf.SetAtomPosition(
+ i, Point3D(float(new[0]), float(new[1]), float(new[2]))
+ )
+ pos[i] = new
+
+
def sdf_to_xyz(sdf_content: str) -> Tuple[str, Dict[str, Any]]:
"""
Convert SDF content to XYZ format string.
@@ -148,19 +341,37 @@ def sdf_to_xyz(sdf_content: str) -> Tuple[str, Dict[str, Any]]:
raise ImportError("RDKit is required for SDF to XYZ conversion")
try:
- # Parse SDF with RDKit
- mol = Chem.MolFromMolBlock(sdf_content)
+ # Parse SDF with RDKit, keeping any explicit hydrogens (3D PubChem SDFs
+ # already carry them with real coordinates).
+ mol = Chem.MolFromMolBlock(sdf_content, removeHs=False)
if mol is None:
raise ValueError("Failed to parse SDF content")
- # Add hydrogens if not present
- mol = Chem.AddHs(mol)
-
- # Generate 3D coordinates if needed
- if mol.GetNumConformers() == 0:
- AllChem.EmbedMolecule(mol, randomSeed=42)
- AllChem.UFFOptimizeMolecule(mol)
+ # Add any missing hydrogens *with* coordinates. Without addCoords the
+ # new H default to the origin, which — combined with a 2D SDF — yields a
+ # degenerate geometry (atoms piled at 0,0,0) that bond perception then
+ # reads as absurd valences.
+ mol = Chem.AddHs(mol, addCoords=True)
+
+ # Re-embed in 3D whenever there is no conformer, or the conformer is 2D
+ # (PubChem's 3D→2D fallback). A flat conformer must not be returned as a
+ # "3D" structure.
+ conf = mol.GetConformer() if mol.GetNumConformers() else None
+ coords_embedded = conf is None or not conf.Is3D()
+ if coords_embedded:
+ if AllChem.EmbedMolecule(mol, randomSeed=42) != 0:
+ AllChem.EmbedMolecule(mol, randomSeed=42, useRandomCoords=True)
+ try:
+ AllChem.MMFFOptimizeMolecule(mol)
+ except Exception:
+ try:
+ AllChem.UFFOptimizeMolecule(mol)
+ except Exception:
+ pass
+ # Salts/counterions embed jammed together — separate them so bond
+ # perception doesn't see a bonded counterion.
+ _separate_fragments(mol)
# Extract coordinates and build XYZ string
conf = mol.GetConformer()
@@ -184,6 +395,7 @@ def sdf_to_xyz(sdf_content: str) -> Tuple[str, Dict[str, Any]]:
"charge": Chem.GetFormalCharge(mol),
"num_atoms": mol.GetNumAtoms(),
"num_heavy_atoms": mol.GetNumHeavyAtoms(),
+ "coords_embedded": coords_embedded,
}
logger.debug(f"Converted SDF to XYZ: {metadata['formula']}")
@@ -386,6 +598,8 @@ def smiles_to_xyz(smiles: str, optimize_3d: bool = True) -> Tuple[str, Dict[str,
except Exception:
logger.warning("UFF optimization failed, using unoptimized coordinates")
+ _separate_fragments(mol) # keep salt counterions apart
+
# Extract coordinates
if mol.GetNumConformers() == 0:
raise ValueError("Failed to generate 3D coordinates")
@@ -424,6 +638,62 @@ def smiles_to_xyz(smiles: str, optimize_3d: bool = True) -> Tuple[str, Dict[str,
raise ValueError(f"Failed to convert SMILES to XYZ: {e}")
+def inchi_to_xyz(inchi: str, optimize_3d: bool = True) -> Tuple[str, Dict[str, Any]]:
+ """Convert an InChI string to XYZ coordinates via RDKit (no network).
+
+ Mirrors :func:`smiles_to_xyz`: parse → add H → embed (ETKDG, seed 42) →
+ UFF-optimize. Returns ``(xyz_string, metadata)``; metadata carries the
+ canonical SMILES so the caller can label provenance consistently.
+ """
+ if not RDKIT_AVAILABLE:
+ raise ImportError("RDKit is required for InChI conversion")
+
+ try:
+ mol = Chem.MolFromInchi(inchi)
+ if mol is None:
+ raise ValueError(f"Invalid InChI string: {inchi}")
+
+ mol = Chem.AddHs(mol)
+ if optimize_3d:
+ result = AllChem.EmbedMolecule(mol, randomSeed=42)
+ if result != 0:
+ AllChem.EmbedMolecule(mol, randomSeed=42, useRandomCoords=True)
+ try:
+ AllChem.UFFOptimizeMolecule(mol)
+ except Exception:
+ logger.warning("UFF optimization failed, using unoptimized coordinates")
+
+ _separate_fragments(mol) # keep salt counterions apart
+
+ if mol.GetNumConformers() == 0:
+ raise ValueError("Failed to generate 3D coordinates")
+
+ conf = mol.GetConformer()
+ formula = Chem.rdMolDescriptors.CalcMolFormula(mol)
+ xyz_lines = [str(mol.GetNumAtoms()), f"Generated from InChI ({formula})"]
+ for atom in mol.GetAtoms():
+ pos = conf.GetAtomPosition(atom.GetIdx())
+ xyz_lines.append(
+ f"{atom.GetSymbol():3s} {pos.x:12.6f} {pos.y:12.6f} {pos.z:12.6f}"
+ )
+
+ metadata = {
+ "formula": formula,
+ "molecular_weight": Descriptors.MolWt(mol),
+ "charge": Chem.GetFormalCharge(mol),
+ "num_atoms": mol.GetNumAtoms(),
+ "num_heavy_atoms": mol.GetNumHeavyAtoms(),
+ "inchi": inchi,
+ "canonical_smiles": Chem.MolToSmiles(mol),
+ }
+ logger.info(f"Converted InChI to XYZ: {formula}")
+ return "\n".join(xyz_lines), metadata
+
+ except Exception as e:
+ logger.error(f"InChI to XYZ conversion failed: {e}")
+ raise ValueError(f"Failed to convert InChI to XYZ: {e}")
+
+
def student_friendly_smiles_to_xyz(smiles: str) -> Tuple[Optional[str], str]:
"""
Convert SMILES to XYZ with student-friendly error messages.
@@ -688,3 +958,164 @@ def validate_smiles(smiles: str) -> Tuple[bool, str]:
except Exception as e:
return False, f"Validation error: {str(e)}"
+
+
+# ============================================================================
+# Smart input routing
+# ============================================================================
+
+# Standard InChIKey: 14 block chars - 10 block chars - 1 flag char.
+_INCHIKEY_RE = re.compile(r"^[A-Z]{14}-[A-Z]{10}-[A-Z]$")
+# A bare molecular formula, e.g. "H2O", "C6H6", "CO2", "Fe".
+_FORMULA_RE = re.compile(r"^(?:[A-Z][a-z]?\d*)+$")
+# Characters that only appear in SMILES, never in a common/IUPAC molecule name.
+_SMILES_STRUCTURAL = set("=#()[]/\\@.%+")
+
+
+def _looks_like_smiles(query: str) -> bool:
+ """High-precision SMILES check: only ``True`` when RDKit parses it *and* it
+ carries SMILES-only signals (structural punctuation or ring digits).
+
+ Deliberately conservative — bare-letter tokens like ``CCO`` (which are valid
+ SMILES *and* plausible names/formulas) are left for the provider chain
+ to disambiguate, so we never misroute a plain name to a local parse.
+ """
+ if not RDKIT_AVAILABLE or " " in query:
+ return False
+ has_structural = any(c in _SMILES_STRUCTURAL for c in query)
+ has_digit = any(c.isdigit() for c in query)
+ if not (has_structural or has_digit):
+ return False
+ return Chem.MolFromSmiles(query) is not None
+
+
+def classify_query(query: str) -> str:
+ """Classify a user structure query so it can be routed to the right resolver.
+
+ Returns one of ``"cid"``, ``"inchikey"``, ``"inchi"``, ``"smiles"``,
+ ``"formula"``, or ``"name"``. ``smiles`` / ``inchi`` resolve locally via
+ RDKit (no network); the rest go to PubChem. ``formula`` is currently routed
+ like ``name`` (PubChem's async fastformula search is not used here).
+ """
+ q = query.strip()
+ if not q:
+ raise ValueError("Empty query")
+ if q.startswith("InChI="):
+ return "inchi"
+ if _INCHIKEY_RE.match(q):
+ return "inchikey"
+ if re.fullmatch(r"(?:CID:?\s*)?\d+", q, flags=re.IGNORECASE):
+ return "cid"
+ if _looks_like_smiles(q):
+ return "smiles"
+ if _FORMULA_RE.match(q):
+ return "formula"
+ return "name"
+
+
+def _coerce_cid(query: str) -> int:
+ """Extract the integer CID from ``123`` / ``CID123`` / ``cid: 123`` forms."""
+ return int(re.sub(r"[^\d]", "", query))
+
+
+def fetch_structure(
+ query: str, conformer_3d: bool = True
+) -> Tuple[str, Dict[str, Any]]:
+ """Resolve any supported query type to ``(xyz_string, metadata)``.
+
+ Routes by :func:`classify_query`: SMILES/InChI resolve locally via RDKit
+ (no network); CID/InChIKey/name/formula go to PubChem. ``metadata`` always
+ carries a ``source`` key (``"rdkit-smiles"`` / ``"rdkit-inchi"`` /
+ ``"pubchem"``) and a ``conformer_origin`` key describing where the 3D
+ coordinates came from, so the UI can be honest about provenance.
+
+ Raises :class:`PubChemError` / :class:`ValueError` on failure (the
+ student-friendly wrapper :func:`student_friendly_resolve` maps these to
+ messages).
+ """
+ qtype = classify_query(query)
+ q = query.strip()
+ logger.info(f"Resolving structure query '{q}' classified as '{qtype}'")
+
+ if qtype == "smiles":
+ xyz, metadata = smiles_to_xyz(q, optimize_3d=conformer_3d)
+ metadata["source"] = "rdkit-smiles"
+ metadata["conformer_origin"] = "rdkit-embedded"
+ return xyz, metadata
+
+ if qtype == "inchi":
+ xyz, metadata = inchi_to_xyz(q, optimize_3d=conformer_3d)
+ metadata["source"] = "rdkit-inchi"
+ metadata["conformer_origin"] = "rdkit-embedded"
+ return xyz, metadata
+
+ # Network branch: resolve to a CID, then fetch + convert the SDF.
+ if qtype == "cid":
+ cid = _coerce_cid(q)
+ elif qtype == "inchikey":
+ cid = search_cid_by_inchikey(q)
+ else: # "name" or "formula"
+ cid = search_molecule_by_name(q)
+
+ sdf_content = get_molecule_sdf(cid, conformer_3d=conformer_3d)
+ xyz, metadata = sdf_to_xyz(sdf_content)
+ metadata["source"] = "pubchem"
+ metadata["pubchem_cid"] = cid
+ metadata["query_type"] = qtype
+ metadata["conformer_origin"] = (
+ "rdkit-embedded" if metadata.get("coords_embedded") else "pubchem"
+ )
+ return xyz, metadata
+
+
+def student_friendly_resolve(query: str) -> Tuple[Optional[str], str]:
+ """Smart, type-aware structure fetch with student-friendly messages.
+
+ Drop-in replacement for :func:`student_friendly_fetch` that also handles
+ SMILES / InChI / CID / InChIKey input (the plain-name path is unchanged).
+ Returns ``(xyz_string_or_None, message)``.
+ """
+ try:
+ xyz_string, metadata = fetch_structure(query, conformer_3d=True)
+ except (MoleculeNotFoundError, ValueError) as exc:
+ return None, (
+ f"❌ Could not resolve '{query}'.\n"
+ f" {exc}\n"
+ f" Try a different name, a SMILES (e.g. CCO), or check spelling.\n"
+ f" Search manually at: https://pubchem.ncbi.nlm.nih.gov/"
+ )
+ except PubChemAPIError:
+ return None, (
+ "❌ Connection to PubChem failed.\n"
+ " • Check your internet connection\n"
+ " • Try again in a moment\n"
+ " • Use a preset molecule if the problem persists"
+ )
+ except ImportError:
+ return None, (
+ "❌ RDKit is required for SMILES / InChI input.\n"
+ " Install with: conda install -c conda-forge rdkit"
+ )
+ except Exception as exc: # pragma: no cover - unexpected
+ logger.error(
+ f"Unexpected error in student_friendly_resolve: {exc}", exc_info=True
+ )
+ return None, f"❌ Error resolving '{query}': {exc}"
+
+ source = {
+ "rdkit-smiles": "generated locally from SMILES",
+ "rdkit-inchi": "generated locally from InChI",
+ "pubchem": "PubChem",
+ }.get(metadata.get("source", ""), metadata.get("source", "?"))
+ origin = metadata.get("conformer_origin", "")
+ origin_note = (
+ " (2D structure embedded by RDKit)" if origin == "rdkit-embedded" else ""
+ )
+ message = (
+ f"✓ Resolved '{query}' via {source}.\n"
+ f" Formula: {metadata.get('formula', '?')}\n"
+ f" Atoms: {metadata.get('num_atoms', '?')} "
+ f"({metadata.get('num_heavy_atoms', '?')} heavy)\n"
+ f" Molecular weight: {metadata.get('molecular_weight', 0):.2f} g/mol{origin_note}"
+ )
+ return xyz_string, message
diff --git a/quantui/results_storage.py b/quantui/results_storage.py
index 55cbcbb..d25c03a 100644
--- a/quantui/results_storage.py
+++ b/quantui/results_storage.py
@@ -130,6 +130,11 @@ def save_result(
"homo_lumo_gap_ev": getattr(result, "homo_lumo_gap_ev", None),
"converged": getattr(result, "converged", None),
"n_iterations": getattr(result, "n_iterations", -1),
+ # Post-HF correlation breakdown — None for HF/DFT. Persisted so the
+ # saved-result card can show the HF reference + correlation rows.
+ "mp2_correlation_hartree": getattr(result, "mp2_correlation_hartree", None),
+ "ccsd_correlation_hartree": getattr(result, "ccsd_correlation_hartree", None),
+ "ccsd_t_correction_hartree": getattr(result, "ccsd_t_correction_hartree", None),
"spectra": spectra if spectra is not None else {},
}
if extras:
diff --git a/quantui/structure_providers.py b/quantui/structure_providers.py
new file mode 100644
index 0000000..6c7aad8
--- /dev/null
+++ b/quantui/structure_providers.py
@@ -0,0 +1,253 @@
+"""Unified structure-resolver chain with offline fallback.
+
+Resolution order (first hit wins):
+
+1. **Local RDKit** for SMILES / InChI input — offline, no network.
+2. **Bundled library** exact hit (formula key) — offline, instant.
+3. **PubChem** (hardened client).
+4. **NCI CACTUS** resolver.
+5. **Bundled-library fuzzy fallback** (name/description substring) — the
+ last-resort offline answer so the search box is never a dead end, even with
+ no network.
+
+Every resolver returns a normalized :class:`ResolvedStructure` so callers
+(and the disambiguation UI) treat all sources uniformly. The
+``source`` field records which resolver answered, so the UI can be honest about
+provenance.
+
+The bundled-library steps currently search ``config.MOLECULE_LIBRARY`` (the 20
+presets). The library lives in an indexed package-data store, reached only
+through :func:`_library_exact` / :func:`_library_fuzzy`, so the chain is
+unaffected by how it is stored.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+from . import cactus, config
+from .pubchem import (
+ MoleculeNotFoundError,
+ PubChemAPIError,
+ classify_query,
+ fetch_structure,
+ search_pubchem_candidates,
+)
+
+logger = logging.getLogger(__name__)
+
+# Elements that count as "heavy" exclusions when tallying heavy atoms.
+_HYDROGEN = "H"
+
+
+@dataclass
+class ResolvedStructure:
+ """A structure resolved by the provider chain, normalized across sources."""
+
+ xyz: str
+ source: str # "rdkit-smiles" | "rdkit-inchi" | "library" | "pubchem" | "cactus" | "library-offline-fallback"
+ formula: str = "?"
+ num_atoms: int = 0
+ num_heavy_atoms: int = 0
+ charge: int = 0
+ multiplicity: int = 1
+ molecular_weight: Optional[float] = None
+ conformer_origin: str = ""
+ identifiers: Dict[str, Any] = field(default_factory=dict)
+
+ @property
+ def is_offline(self) -> bool:
+ return self.source in (
+ "library",
+ "library-offline-fallback",
+ ) or self.source.startswith("rdkit-")
+
+
+def _from_metadata(xyz: str, meta: Dict[str, Any], *, source: str) -> ResolvedStructure:
+ """Build a ResolvedStructure from a ``(xyz, metadata)`` resolver result."""
+ identifiers = {
+ k: meta[k]
+ for k in ("pubchem_cid", "smiles", "canonical_smiles", "inchi", "query_type")
+ if k in meta
+ }
+ return ResolvedStructure(
+ xyz=xyz,
+ source=source,
+ formula=meta.get("formula", "?"),
+ num_atoms=int(meta.get("num_atoms", 0) or 0),
+ num_heavy_atoms=int(meta.get("num_heavy_atoms", 0) or 0),
+ charge=int(meta.get("charge", 0) or 0),
+ molecular_weight=meta.get("molecular_weight"),
+ conformer_origin=meta.get("conformer_origin", meta.get("source", "")),
+ identifiers=identifiers,
+ )
+
+
+def _entry_to_xyz(name: str, entry: Dict[str, Any]) -> str:
+ """Format a ``MOLECULE_LIBRARY`` entry as an XYZ string."""
+ atoms = entry["atoms"]
+ coords = entry["coordinates"]
+ desc = entry.get("description", "")
+ lines = [str(len(atoms)), f"{name}: {desc}".strip()]
+ for sym, (x, y, z) in zip(atoms, coords):
+ lines.append(f"{sym:3s} {float(x):12.6f} {float(y):12.6f} {float(z):12.6f}")
+ return "\n".join(lines)
+
+
+def _entry_to_resolved(
+ name: str, entry: Dict[str, Any], *, source: str
+) -> ResolvedStructure:
+ atoms = entry["atoms"]
+ return ResolvedStructure(
+ xyz=_entry_to_xyz(name, entry),
+ source=source,
+ formula=name,
+ num_atoms=len(atoms),
+ num_heavy_atoms=sum(1 for a in atoms if a != _HYDROGEN),
+ charge=int(entry.get("charge", 0)),
+ multiplicity=int(entry.get("multiplicity", 1)),
+ conformer_origin="library",
+ identifiers={"library_key": name},
+ )
+
+
+def _library_exact(query: str) -> Optional[ResolvedStructure]:
+ """Exact (case-insensitive) match on a bundled-library formula key."""
+ q = query.strip().lower()
+ for key, entry in config.MOLECULE_LIBRARY.items():
+ if q == key.lower():
+ logger.info(f"Resolved '{query}' from bundled library (exact key '{key}')")
+ return _entry_to_resolved(key, entry, source="library")
+ return None
+
+
+def _library_fuzzy(query: str) -> Optional[ResolvedStructure]:
+ """Loose offline fallback: substring match over keys + descriptions.
+
+ Used only when the network resolvers are unreachable or all miss, so a
+ looser match is acceptable (and clearly labelled as a fallback to the user).
+ """
+ q = query.strip().lower()
+ if not q:
+ return None
+ for key, entry in config.MOLECULE_LIBRARY.items():
+ haystack = f"{key} {entry.get('description', '')}".lower()
+ if q == key.lower() or q in haystack:
+ logger.info(f"Offline fallback matched '{query}' to library entry '{key}'")
+ return _entry_to_resolved(key, entry, source="library-offline-fallback")
+ return None
+
+
+def resolve_structure(
+ query: str,
+ *,
+ conformer_3d: bool = True,
+ allow_network: bool = True,
+) -> ResolvedStructure:
+ """Resolve ``query`` through the provider chain. Raises on total failure.
+
+ Raises:
+ MoleculeNotFoundError: nothing in the chain could resolve the query.
+ ValueError: empty query, or RDKit failed to parse a SMILES/InChI.
+ """
+ qtype = classify_query(query)
+ logger.info(f"Resolving '{query}' (type={qtype}, network={allow_network})")
+
+ # 1. Local RDKit for SMILES / InChI — no network, no library needed.
+ if qtype in ("smiles", "inchi"):
+ xyz, meta = fetch_structure(query, conformer_3d=conformer_3d)
+ return _from_metadata(xyz, meta, source=meta["source"])
+
+ # 2. Exact bundled-library hit (offline, instant) — e.g. "H2O", "C6H6".
+ hit = _library_exact(query)
+ if hit is not None:
+ return hit
+
+ # 3/4. Network resolvers: PubChem, then CACTUS. A genuine miss
+ # (MoleculeNotFoundError) or a transport error (PubChemAPIError) both fall
+ # through to the next resolver, then to the offline fallback.
+ errors: List[Tuple[str, Exception]] = []
+ if allow_network:
+ try:
+ xyz, meta = fetch_structure(query, conformer_3d=conformer_3d)
+ return _from_metadata(xyz, meta, source="pubchem")
+ except (MoleculeNotFoundError, PubChemAPIError) as exc:
+ logger.info(f"PubChem did not resolve '{query}': {exc}")
+ errors.append(("pubchem", exc))
+
+ try:
+ xyz, meta = cactus.fetch_from_cactus(query, conformer_3d=conformer_3d)
+ return _from_metadata(xyz, meta, source="cactus")
+ except (MoleculeNotFoundError, PubChemAPIError) as exc:
+ logger.info(f"CACTUS did not resolve '{query}': {exc}")
+ errors.append(("cactus", exc))
+
+ # 5. Offline fuzzy fallback against the bundled library.
+ hit = _library_fuzzy(query)
+ if hit is not None:
+ return hit
+
+ tried = ", ".join(name for name, _ in errors) or "offline only"
+ raise MoleculeNotFoundError(
+ f"Could not resolve '{query}' (tried: {tried}, bundled library)"
+ )
+
+
+def search_candidates(query: str) -> List[Dict[str, Any]]:
+ """Return disambiguation candidates for a multi-match name/formula query.
+
+ Only name/formula queries can be ambiguous (SMILES/InChI/CID resolve to a
+ single structure, and the local library is exact). Returns ``[]`` for those
+ types, and ``[]`` on any network failure so the caller falls back to the
+ full single-result chain (PubChem → CACTUS → offline library).
+ """
+ if classify_query(query) not in ("name", "formula"):
+ return []
+ try:
+ return search_pubchem_candidates(query)
+ except (MoleculeNotFoundError, PubChemAPIError):
+ return []
+
+
+def student_friendly_resolve(query: str) -> Tuple[Optional[str], str]:
+ """Chain-backed, student-friendly resolve. Drop-in for the UI handler.
+
+ Returns ``(xyz_string_or_None, message)``.
+ """
+ try:
+ result = resolve_structure(query, conformer_3d=True)
+ except (MoleculeNotFoundError, ValueError) as exc:
+ return None, (
+ f"❌ Could not resolve '{query}'.\n"
+ f" {exc}\n"
+ f" Try a different name, a SMILES (e.g. CC(=O)O), a CAS number, "
+ f"or check spelling.\n"
+ f" Search manually at: https://pubchem.ncbi.nlm.nih.gov/"
+ )
+ except Exception as exc: # pragma: no cover - unexpected
+ logger.error(f"Unexpected error resolving '{query}': {exc}", exc_info=True)
+ return None, f"❌ Error resolving '{query}': {exc}"
+
+ source_label = {
+ "rdkit-smiles": "generated locally from SMILES",
+ "rdkit-inchi": "generated locally from InChI",
+ "library": "the bundled library (offline)",
+ "library-offline-fallback": "the bundled library (offline fallback — "
+ "network resolvers were unavailable)",
+ "pubchem": "PubChem",
+ "cactus": "NCI CACTUS",
+ }.get(result.source, result.source)
+
+ embedded = (
+ " (2D structure embedded by RDKit)"
+ if result.conformer_origin == "rdkit-embedded"
+ else ""
+ )
+ mw = f"{result.molecular_weight:.2f} g/mol" if result.molecular_weight else "—"
+ message = (
+ f"✓ Resolved '{query}' via {source_label}.\n"
+ f" Formula: {result.formula}\n"
+ f" Atoms: {result.num_atoms} ({result.num_heavy_atoms} heavy)\n"
+ f" Molecular weight: {mw}{embedded}"
+ )
+ return result.xyz, message
diff --git a/scripts/build_bulk_library.py b/scripts/build_bulk_library.py
new file mode 100644
index 0000000..b6ab125
--- /dev/null
+++ b/scripts/build_bulk_library.py
@@ -0,0 +1,211 @@
+"""Generate the bulk QM9 library manifest (M-STRUCT STRUCT.8).
+
+Downloads the QM9 dataset (Ramakrishnan et al., Sci. Data 2014; GDB-9 subset;
+**CC0**), parses the 133,885 B3LYP/6-31G(2df,p)-optimized structures, filters +
+dedups against the curated set, stratified-samples for chemical diversity, and
+writes quantui/data/manifests/bulk_qm9.json (category="bulk-qm9",
+source="qm9-dft"). Then rebuild the store:
+
+ python scripts/build_bulk_library.py [--target N]
+ python scripts/build_library.py
+
+Bulk entries are identified by formula + QM9 index and surface via search only
+(excluded from the browsable preset dict). Deterministic: stratified sampling
+draws in a fixed (formula-sorted, index-ordered) order — no RNG.
+
+The QM9 tarball (~92 MB) is cached under the system temp dir, so re-runs don't
+re-download. Maintainer build step; the generated manifest + store are what ship.
+"""
+
+import argparse
+import hashlib
+import json
+import tarfile
+import urllib.request
+from collections import Counter, defaultdict
+from pathlib import Path
+from tempfile import gettempdir
+
+from rdkit import Chem, RDLogger
+
+from quantui import config
+
+RDLogger.DisableLog("rdApp.*")
+
+# figshare ndownloader file ids for dataset 978904.
+QM9_TARBALL_URL = (
+ "https://ndownloader.figshare.com/files/3195389" # dsgdb9nsd.xyz.tar.bz2
+)
+QM9_UNCHAR_URL = "https://ndownloader.figshare.com/files/3195404" # uncharacterized.txt
+_CACHE = Path(gettempdir()) / "quantui_qm9_cache"
+
+OUT = Path("quantui/data/manifests/bulk_qm9.json")
+PROVENANCE = Path("quantui/data/library/QM9-PROVENANCE.md")
+CURATED = Path("quantui/data/manifests/curated.json")
+
+DEFAULT_TARGET = 2500 # ~0.6 MB store (demo cap; raise to fill toward 10 MB)
+PER_FORMULA_CAP = 4 # keep at most N isomers per formula (diversity + bounded memory)
+CEILING = config.LIBRARY_HEAVY_ATOM_CEILING_BULK
+
+
+def _download(url: str, dest: Path) -> Path:
+ if dest.exists():
+ return dest
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ print(f"Downloading {url} -> {dest} ...")
+ req = urllib.request.Request(url, headers={"User-Agent": "quantui-build"})
+ with urllib.request.urlopen(req, timeout=120) as r, open(dest, "wb") as f:
+ f.write(r.read())
+ print(f" {dest.stat().st_size / 1024 / 1024:.1f} MB")
+ return dest
+
+
+def _hill_formula(atoms: list) -> str:
+ c = Counter(atoms)
+ parts = []
+ for sym in ("C", "H"):
+ if c.get(sym):
+ parts.append(sym + (str(c[sym]) if c[sym] > 1 else ""))
+ del c[sym]
+ for sym in sorted(c):
+ parts.append(sym + (str(c[sym]) if c[sym] > 1 else ""))
+ return "".join(parts)
+
+
+def _parse_qm9_xyz(text: str):
+ """Parse one QM9 .xyz → (index, atoms, coords, smiles, inchi).
+
+ Layout: natoms / props / n atom lines / frequencies / SMILES line /
+ InChI line. The SMILES and InChI lines each carry two values (GDB17 and
+ B3LYP-relaxed); we take the relaxed (last) of each.
+ """
+ lines = text.splitlines()
+ n = int(lines[0])
+ index = int(lines[1].split()[1]) # 'gdb '
+ atoms, coords = [], []
+ for ln in lines[2 : 2 + n]:
+ parts = ln.split()
+ atoms.append(parts[0])
+ # QM9 uses Fortran exponent notation like "1.23*^-6".
+ xyz = [float(p.replace("*^", "e")) for p in parts[1:4]]
+ coords.append([round(v, 6) for v in xyz])
+ smiles_line = lines[2 + n + 1].split() # after the frequencies line
+ smiles = smiles_line[-1] if smiles_line else None
+ inchi_line = lines[2 + n + 2].split()
+ inchi = inchi_line[-1] if inchi_line else ""
+ return index, atoms, coords, smiles, inchi
+
+
+def main() -> None:
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--target", type=int, default=DEFAULT_TARGET)
+ args = ap.parse_args()
+
+ tarball = _download(QM9_TARBALL_URL, _CACHE / "dsgdb9nsd.xyz.tar.bz2")
+ sha = hashlib.sha256(tarball.read_bytes()).hexdigest()
+ print(f"QM9 tarball sha256: {sha}")
+
+ unchar_path = _download(QM9_UNCHAR_URL, _CACHE / "uncharacterized.txt")
+ uncharacterized = set()
+ for ln in unchar_path.read_text(encoding="utf-8", errors="replace").splitlines():
+ toks = ln.split()
+ if toks and toks[0].isdigit():
+ uncharacterized.add(int(toks[0]))
+ print(f"Excluding {len(uncharacterized)} uncharacterized molecules")
+
+ curated_keys = {
+ e["inchikey"]
+ for e in json.loads(CURATED.read_text(encoding="utf-8"))
+ if e.get("inchikey")
+ }
+
+ # Pass: bucket candidates by Hill formula (bounded per formula).
+ buckets: dict = defaultdict(list)
+ n_seen = n_kept = 0
+ with tarfile.open(tarball, mode="r:bz2") as tar:
+ for member in tar:
+ if not member.name.endswith(".xyz"):
+ continue
+ n_seen += 1
+ fobj = tar.extractfile(member)
+ if fobj is None:
+ continue
+ try:
+ index, atoms, coords, smiles, inchi = _parse_qm9_xyz(
+ fobj.read().decode("utf-8", "replace")
+ )
+ except Exception:
+ continue
+ if index in uncharacterized:
+ continue
+ if sum(1 for a in atoms if a != "H") > CEILING:
+ continue
+ formula = _hill_formula(atoms)
+ if len(buckets[formula]) < PER_FORMULA_CAP:
+ buckets[formula].append((index, atoms, coords, smiles, inchi))
+ n_kept += 1
+ print(f"Scanned {n_seen} molecules; {len(buckets)} formulas, {n_kept} bucketed")
+
+ # Stratified round-robin draw: one isomer per formula per round, formula-sorted.
+ order = []
+ for r in range(PER_FORMULA_CAP):
+ for formula in sorted(buckets):
+ if r < len(buckets[formula]):
+ order.append((formula, buckets[formula][r]))
+
+ out, seen_keys, skipped_dup = [], set(), 0
+ for formula, (index, atoms, coords, smiles, inchi) in order:
+ if len(out) >= args.target:
+ break
+ try:
+ key = Chem.InchiToInchiKey(inchi) if inchi.startswith("InChI=") else None
+ except Exception:
+ key = None
+ if key and (key in curated_keys or key in seen_keys):
+ skipped_dup += 1
+ continue
+ if key:
+ seen_keys.add(key)
+ out.append(
+ {
+ "id": f"qm9-{index}",
+ "name": f"{formula} (QM9 #{index})",
+ "formula": formula,
+ "category": "bulk-qm9",
+ "source": "qm9-dft",
+ "charge": 0,
+ "multiplicity": 1,
+ "smiles": smiles,
+ "inchikey": key,
+ "synonyms": "",
+ "description": f"{formula} — QM9 #{index} (B3LYP/6-31G(2df,p))",
+ "atoms": atoms,
+ "coordinates": coords,
+ }
+ )
+
+ OUT.write_text(json.dumps(out, separators=(",", ":")) + "\n", encoding="utf-8")
+ print(f"Wrote {len(out)} bulk entries to {OUT} (deduped {skipped_dup} vs curated)")
+
+ PROVENANCE.parent.mkdir(parents=True, exist_ok=True)
+ PROVENANCE.write_text(
+ "# QM9 bulk-library provenance\n\n"
+ f"- Entries shipped: {len(out)} (cap {args.target}; "
+ f"`category=bulk-qm9`, `source=qm9-dft`)\n"
+ f"- Source: QM9 / GDB-9 (figshare dataset 978904)\n"
+ f"- Tarball sha256: `{sha}`\n"
+ "- Geometries: B3LYP/6-31G(2df,p) optimized\n"
+ "- License: CC0 (public domain)\n"
+ "- Citation: Ramakrishnan, Dral, Rupp & von Lilienfeld, "
+ "*Sci. Data* **1**, 140022 (2014).\n"
+ "- Selection: stratified by Hill formula (≤"
+ f"{CEILING} heavy atoms, uncharacterized excluded, "
+ "InChIKey-deduped vs the curated set), deterministic round-robin.\n"
+ "- Regenerate: `python scripts/build_bulk_library.py --target N`\n",
+ encoding="utf-8",
+ )
+ print(f"Wrote provenance to {PROVENANCE}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/build_curated_library.py b/scripts/build_curated_library.py
new file mode 100644
index 0000000..bbee3f9
--- /dev/null
+++ b/scripts/build_curated_library.py
@@ -0,0 +1,124 @@
+"""Generate the curated library manifest (M-STRUCT STRUCT.7).
+
+Reads the human-editable SMILES seed (scripts/curated_seed.json), generates 3D
+coordinates with RDKit (ETKDGv3, seed=42 → MMFF94, UFF fallback), and writes
+the full manifest quantui/data/manifests/curated.json (same schema as
+presets.json, with coordinates). Then rebuild the SQLite store:
+
+ python scripts/build_curated_library.py
+ python scripts/build_library.py
+
+Deterministic (fixed RDKit seed). Molecules that fail to parse/embed or exceed
+the curated heavy-atom ceiling are skipped + reported (no silent drops).
+"""
+
+import json
+import re
+from pathlib import Path
+
+from rdkit import Chem, RDLogger
+from rdkit.Chem import AllChem
+
+from quantui import config
+
+RDLogger.DisableLog("rdApp.*") # quiet InChI/sanitize chatter
+
+SEED = Path("scripts/curated_seed.json")
+OUT = Path("quantui/data/manifests/curated.json")
+CEILING = config.LIBRARY_HEAVY_ATOM_CEILING_CURATED
+
+
+def _slug(name: str) -> str:
+ return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def _embed(mol):
+ params = AllChem.ETKDGv3()
+ params.randomSeed = 42
+ if AllChem.EmbedMolecule(mol, params) != 0:
+ params.useRandomCoords = True
+ if AllChem.EmbedMolecule(mol, params) != 0:
+ raise ValueError("3D embedding failed")
+ try:
+ AllChem.MMFFOptimizeMolecule(mol)
+ except Exception:
+ try:
+ AllChem.UFFOptimizeMolecule(mol)
+ except Exception:
+ pass # ship unoptimized rather than fail
+
+
+def _generate(entry: dict) -> dict:
+ mol = Chem.MolFromSmiles(entry["smiles"])
+ if mol is None:
+ raise ValueError("unparseable SMILES")
+ mol = Chem.AddHs(mol)
+ _embed(mol)
+
+ atoms = [a.GetSymbol() for a in mol.GetAtoms()]
+ n_heavy = sum(1 for a in atoms if a != "H")
+ if n_heavy > CEILING:
+ raise ValueError(f"{n_heavy} heavy atoms exceeds ceiling {CEILING}")
+
+ conf = mol.GetConformer()
+ coords = [
+ [
+ round(conf.GetAtomPosition(i).x, 6),
+ round(conf.GetAtomPosition(i).y, 6),
+ round(conf.GetAtomPosition(i).z, 6),
+ ]
+ for i in range(mol.GetNumAtoms())
+ ]
+ formula = Chem.rdMolDescriptors.CalcMolFormula(mol)
+ try:
+ inchikey = Chem.InchiToInchiKey(Chem.MolToInchi(mol)) or None
+ except Exception:
+ inchikey = None
+
+ return {
+ "id": _slug(entry["name"]),
+ "name": entry["name"],
+ "formula": formula,
+ "category": entry["category"],
+ "source": "curated-ff",
+ "charge": int(entry.get("charge", Chem.GetFormalCharge(mol))),
+ "multiplicity": int(entry.get("multiplicity", 1)),
+ "smiles": Chem.MolToSmiles(Chem.RemoveHs(mol)),
+ "inchikey": inchikey,
+ "synonyms": entry.get("synonyms", ""),
+ "description": f"{entry['name']} ({formula})",
+ "atoms": atoms,
+ "coordinates": coords,
+ }
+
+
+def main() -> None:
+ seed = json.loads(SEED.read_text(encoding="utf-8"))
+ out, failures, seen = [], [], set()
+ for entry in seed:
+ try:
+ rec = _generate(entry)
+ except Exception as exc:
+ failures.append((entry["name"], str(exc)))
+ continue
+ if rec["id"] in seen:
+ failures.append((entry["name"], f"duplicate id '{rec['id']}'"))
+ continue
+ seen.add(rec["id"])
+ out.append(rec)
+
+ OUT.parent.mkdir(parents=True, exist_ok=True)
+ OUT.write_text(json.dumps(out, indent=1) + "\n", encoding="utf-8")
+ print(f"Wrote {len(out)}/{len(seed)} curated entries to {OUT}")
+ by_cat: dict = {}
+ for r in out:
+ by_cat[r["category"]] = by_cat.get(r["category"], 0) + 1
+ print("By category:", dict(sorted(by_cat.items())))
+ if failures:
+ print(f"\nSkipped {len(failures)}:")
+ for name, why in failures:
+ print(f" - {name}: {why}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/build_library.py b/scripts/build_library.py
new file mode 100644
index 0000000..0c8ae23
--- /dev/null
+++ b/scripts/build_library.py
@@ -0,0 +1,32 @@
+"""Rebuild the bundled molecule-library SQLite store from the committed manifests.
+
+Usage:
+ python scripts/build_library.py
+
+Reads every ``quantui/data/manifests/*.json`` and writes
+``quantui/data/library/library.sqlite`` (deterministic, overwrites). Prints the
+final entry count + on-disk size and asserts the 10 MB budget (STRUCT.10).
+
+When STRUCT.7 (curated set) and STRUCT.8 (bulk QM9 subset) land, they add more
+manifests; this tool is unchanged.
+"""
+
+from quantui import molecule_library as ml
+
+_BUDGET_BYTES = 10 * 1024 * 1024 # 10 MB (DEC-015)
+
+
+def main() -> None:
+ path = ml.build_from_manifests()
+ size = path.stat().st_size
+ n = ml.count()
+ print(f"Built {path} — {n} entries, {size / 1024:.1f} KiB")
+ print(f"Categories: {', '.join(ml.categories())}")
+ if size > _BUDGET_BYTES:
+ raise SystemExit(
+ f"Library store {size / 1024 / 1024:.2f} MB exceeds the 10 MB budget"
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/curated_seed.json b/scripts/curated_seed.json
new file mode 100644
index 0000000..30a57dc
--- /dev/null
+++ b/scripts/curated_seed.json
@@ -0,0 +1,166 @@
+[
+ { "name": "Glycine", "smiles": "NCC(=O)O", "category": "amino-acid", "synonyms": "Gly;G;aminoacetic acid" },
+ { "name": "Alanine", "smiles": "CC(N)C(=O)O", "category": "amino-acid", "synonyms": "Ala;A" },
+ { "name": "Valine", "smiles": "CC(C)C(N)C(=O)O", "category": "amino-acid", "synonyms": "Val;V" },
+ { "name": "Leucine", "smiles": "CC(C)CC(N)C(=O)O", "category": "amino-acid", "synonyms": "Leu;L" },
+ { "name": "Isoleucine", "smiles": "CCC(C)C(N)C(=O)O", "category": "amino-acid", "synonyms": "Ile;I" },
+ { "name": "Proline", "smiles": "OC(=O)C1CCCN1", "category": "amino-acid", "synonyms": "Pro;P" },
+ { "name": "Phenylalanine", "smiles": "NC(Cc1ccccc1)C(=O)O", "category": "amino-acid", "synonyms": "Phe;F" },
+ { "name": "Tryptophan", "smiles": "NC(Cc1c[nH]c2ccccc12)C(=O)O", "category": "amino-acid", "synonyms": "Trp;W" },
+ { "name": "Methionine", "smiles": "CSCCC(N)C(=O)O", "category": "amino-acid", "synonyms": "Met;M" },
+ { "name": "Serine", "smiles": "NC(CO)C(=O)O", "category": "amino-acid", "synonyms": "Ser;S" },
+ { "name": "Threonine", "smiles": "CC(O)C(N)C(=O)O", "category": "amino-acid", "synonyms": "Thr;T" },
+ { "name": "Cysteine", "smiles": "NC(CS)C(=O)O", "category": "amino-acid", "synonyms": "Cys;C" },
+ { "name": "Tyrosine", "smiles": "NC(Cc1ccc(O)cc1)C(=O)O", "category": "amino-acid", "synonyms": "Tyr;Y" },
+ { "name": "Asparagine", "smiles": "NC(CC(N)=O)C(=O)O", "category": "amino-acid", "synonyms": "Asn;N" },
+ { "name": "Glutamine", "smiles": "NC(CCC(N)=O)C(=O)O", "category": "amino-acid", "synonyms": "Gln;Q" },
+ { "name": "Aspartic acid", "smiles": "NC(CC(=O)O)C(=O)O", "category": "amino-acid", "synonyms": "Asp;D" },
+ { "name": "Glutamic acid", "smiles": "NC(CCC(=O)O)C(=O)O", "category": "amino-acid", "synonyms": "Glu;E" },
+ { "name": "Lysine", "smiles": "NCCCCC(N)C(=O)O", "category": "amino-acid", "synonyms": "Lys;K" },
+ { "name": "Arginine", "smiles": "NC(CCCNC(=N)N)C(=O)O", "category": "amino-acid", "synonyms": "Arg;R" },
+ { "name": "Histidine", "smiles": "NC(Cc1cnc[nH]1)C(=O)O", "category": "amino-acid", "synonyms": "His;H" },
+
+ { "name": "Adenine", "smiles": "Nc1ncnc2nc[nH]c12", "category": "nucleobase", "synonyms": "6-aminopurine" },
+ { "name": "Guanine", "smiles": "Nc1nc2[nH]cnc2c(=O)[nH]1", "category": "nucleobase", "synonyms": "" },
+ { "name": "Cytosine", "smiles": "Nc1cc[nH]c(=O)n1", "category": "nucleobase", "synonyms": "" },
+ { "name": "Thymine", "smiles": "Cc1c[nH]c(=O)[nH]c1=O", "category": "nucleobase", "synonyms": "5-methyluracil" },
+ { "name": "Uracil", "smiles": "O=c1cc[nH]c(=O)[nH]1", "category": "nucleobase", "synonyms": "" },
+
+ { "name": "Glucose", "smiles": "OCC1OC(O)C(O)C(O)C1O", "category": "biomolecule", "synonyms": "dextrose" },
+ { "name": "Urea", "smiles": "NC(N)=O", "category": "biomolecule", "synonyms": "carbamide" },
+ { "name": "Citric acid", "smiles": "OC(=O)CC(O)(CC(=O)O)C(=O)O", "category": "biomolecule", "synonyms": "" },
+ { "name": "Lactic acid", "smiles": "CC(O)C(=O)O", "category": "biomolecule", "synonyms": "2-hydroxypropanoic acid" },
+ { "name": "Pyruvic acid", "smiles": "CC(=O)C(=O)O", "category": "biomolecule", "synonyms": "2-oxopropanoic acid" },
+ { "name": "Oxalic acid", "smiles": "OC(=O)C(=O)O", "category": "biomolecule", "synonyms": "ethanedioic acid" },
+ { "name": "Glycerol", "smiles": "OCC(O)CO", "category": "biomolecule", "synonyms": "glycerin;propane-1,2,3-triol" },
+ { "name": "Ascorbic acid", "smiles": "OCC(O)C1OC(=O)C(O)=C1O", "category": "biomolecule", "synonyms": "vitamin C" },
+
+ { "name": "Methanol", "smiles": "CO", "category": "solvent", "synonyms": "methyl alcohol" },
+ { "name": "Ethanol", "smiles": "CCO", "category": "solvent", "synonyms": "ethyl alcohol" },
+ { "name": "1-Propanol", "smiles": "CCCO", "category": "solvent", "synonyms": "n-propanol" },
+ { "name": "Isopropanol", "smiles": "CC(C)O", "category": "solvent", "synonyms": "2-propanol;IPA" },
+ { "name": "1-Butanol", "smiles": "CCCCO", "category": "solvent", "synonyms": "n-butanol" },
+ { "name": "tert-Butanol", "smiles": "CC(C)(C)O", "category": "solvent", "synonyms": "2-methyl-2-propanol" },
+ { "name": "Acetone", "smiles": "CC(C)=O", "category": "solvent", "synonyms": "propanone;dimethyl ketone" },
+ { "name": "Methyl ethyl ketone", "smiles": "CCC(C)=O", "category": "solvent", "synonyms": "MEK;butanone" },
+ { "name": "Dichloromethane", "smiles": "ClCCl", "category": "solvent", "synonyms": "DCM;methylene chloride" },
+ { "name": "Chloroform", "smiles": "ClC(Cl)Cl", "category": "solvent", "synonyms": "trichloromethane" },
+ { "name": "Carbon tetrachloride", "smiles": "ClC(Cl)(Cl)Cl", "category": "solvent", "synonyms": "tetrachloromethane" },
+ { "name": "Tetrahydrofuran", "smiles": "C1CCOC1", "category": "solvent", "synonyms": "THF" },
+ { "name": "1,4-Dioxane", "smiles": "C1COCCO1", "category": "solvent", "synonyms": "dioxane" },
+ { "name": "Diethyl ether", "smiles": "CCOCC", "category": "solvent", "synonyms": "ether;ethoxyethane" },
+ { "name": "Dimethylformamide", "smiles": "CN(C)C=O", "category": "solvent", "synonyms": "DMF" },
+ { "name": "Dimethyl sulfoxide", "smiles": "CS(C)=O", "category": "solvent", "synonyms": "DMSO" },
+ { "name": "Acetonitrile", "smiles": "CC#N", "category": "solvent", "synonyms": "MeCN;methyl cyanide" },
+ { "name": "Ethyl acetate", "smiles": "CCOC(C)=O", "category": "solvent", "synonyms": "EtOAc" },
+ { "name": "n-Hexane", "smiles": "CCCCCC", "category": "solvent", "synonyms": "hexane" },
+ { "name": "n-Pentane", "smiles": "CCCCC", "category": "solvent", "synonyms": "pentane" },
+ { "name": "n-Heptane", "smiles": "CCCCCCC", "category": "solvent", "synonyms": "heptane" },
+ { "name": "Cyclohexane", "smiles": "C1CCCCC1", "category": "solvent", "synonyms": "" },
+ { "name": "Toluene", "smiles": "Cc1ccccc1", "category": "solvent", "synonyms": "methylbenzene" },
+ { "name": "Pyridine", "smiles": "c1ccncc1", "category": "solvent", "synonyms": "" },
+ { "name": "Acetic acid", "smiles": "CC(=O)O", "category": "solvent", "synonyms": "ethanoic acid" },
+ { "name": "Formic acid", "smiles": "OC=O", "category": "solvent", "synonyms": "methanoic acid" },
+ { "name": "Nitromethane", "smiles": "C[N+](=O)[O-]", "category": "solvent", "synonyms": "" },
+ { "name": "Ethylene glycol", "smiles": "OCCO", "category": "solvent", "synonyms": "ethane-1,2-diol" },
+
+ { "name": "Propanal", "smiles": "CCC=O", "category": "functional-group", "synonyms": "propionaldehyde" },
+ { "name": "Butanal", "smiles": "CCCC=O", "category": "functional-group", "synonyms": "butyraldehyde" },
+ { "name": "Propanoic acid", "smiles": "CCC(=O)O", "category": "functional-group", "synonyms": "propionic acid" },
+ { "name": "Butanoic acid", "smiles": "CCCC(=O)O", "category": "functional-group", "synonyms": "butyric acid" },
+ { "name": "Methyl acetate", "smiles": "COC(C)=O", "category": "functional-group", "synonyms": "" },
+ { "name": "Ethylamine", "smiles": "CCN", "category": "functional-group", "synonyms": "" },
+ { "name": "Dimethylamine", "smiles": "CNC", "category": "functional-group", "synonyms": "" },
+ { "name": "Trimethylamine", "smiles": "CN(C)C", "category": "functional-group", "synonyms": "" },
+ { "name": "Propanenitrile", "smiles": "CCC#N", "category": "functional-group", "synonyms": "propionitrile" },
+ { "name": "Nitroethane", "smiles": "CC[N+](=O)[O-]", "category": "functional-group", "synonyms": "" },
+ { "name": "Dimethyl sulfide", "smiles": "CSC", "category": "functional-group", "synonyms": "DMS" },
+ { "name": "Ethanethiol", "smiles": "CCS", "category": "functional-group", "synonyms": "ethyl mercaptan" },
+ { "name": "Dimethyl ether", "smiles": "COC", "category": "functional-group", "synonyms": "methoxymethane" },
+ { "name": "Acetamide", "smiles": "CC(N)=O", "category": "functional-group", "synonyms": "ethanamide" },
+ { "name": "Formamide", "smiles": "NC=O", "category": "functional-group", "synonyms": "methanamide" },
+ { "name": "Acetic anhydride", "smiles": "CC(=O)OC(C)=O", "category": "functional-group", "synonyms": "" },
+ { "name": "Anisole", "smiles": "COc1ccccc1", "category": "functional-group", "synonyms": "methoxybenzene" },
+ { "name": "Phenol", "smiles": "Oc1ccccc1", "category": "functional-group", "synonyms": "carbolic acid" },
+ { "name": "Aniline", "smiles": "Nc1ccccc1", "category": "functional-group", "synonyms": "aminobenzene" },
+ { "name": "Benzaldehyde", "smiles": "O=Cc1ccccc1", "category": "functional-group", "synonyms": "" },
+ { "name": "Acetophenone", "smiles": "CC(=O)c1ccccc1", "category": "functional-group", "synonyms": "" },
+ { "name": "Benzoic acid", "smiles": "OC(=O)c1ccccc1", "category": "functional-group", "synonyms": "" },
+ { "name": "Oxirane", "smiles": "C1CO1", "category": "functional-group", "synonyms": "ethylene oxide;epoxyethane" },
+ { "name": "Furan", "smiles": "c1ccoc1", "category": "functional-group", "synonyms": "" },
+ { "name": "Thiophene", "smiles": "c1ccsc1", "category": "functional-group", "synonyms": "" },
+ { "name": "Pyrrole", "smiles": "c1cc[nH]c1", "category": "functional-group", "synonyms": "" },
+ { "name": "Imidazole", "smiles": "c1c[nH]cn1", "category": "functional-group", "synonyms": "" },
+
+ { "name": "Propane", "smiles": "CCC", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Butane", "smiles": "CCCC", "category": "hydrocarbon", "synonyms": "n-butane" },
+ { "name": "Isobutane", "smiles": "CC(C)C", "category": "hydrocarbon", "synonyms": "2-methylpropane" },
+ { "name": "Cyclopropane", "smiles": "C1CC1", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Cyclobutane", "smiles": "C1CCC1", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Cyclopentane", "smiles": "C1CCCC1", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Propene", "smiles": "CC=C", "category": "hydrocarbon", "synonyms": "propylene" },
+ { "name": "1-Butene", "smiles": "CCC=C", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Isobutylene", "smiles": "CC(=C)C", "category": "hydrocarbon", "synonyms": "2-methylpropene" },
+ { "name": "1,3-Butadiene", "smiles": "C=CC=C", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Isoprene", "smiles": "CC(=C)C=C", "category": "hydrocarbon", "synonyms": "2-methyl-1,3-butadiene" },
+ { "name": "Propyne", "smiles": "CC#C", "category": "hydrocarbon", "synonyms": "methylacetylene" },
+ { "name": "1-Butyne", "smiles": "CCC#C", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Cyclohexene", "smiles": "C1CCC=CC1", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Naphthalene", "smiles": "c1ccc2ccccc2c1", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Anthracene", "smiles": "c1ccc2cc3ccccc3cc2c1", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Biphenyl", "smiles": "c1ccc(-c2ccccc2)cc1", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Ethylbenzene", "smiles": "CCc1ccccc1", "category": "hydrocarbon", "synonyms": "" },
+ { "name": "Cumene", "smiles": "CC(C)c1ccccc1", "category": "hydrocarbon", "synonyms": "isopropylbenzene" },
+ { "name": "Styrene", "smiles": "C=Cc1ccccc1", "category": "hydrocarbon", "synonyms": "vinylbenzene" },
+
+ { "name": "Aspirin", "smiles": "CC(=O)Oc1ccccc1C(=O)O", "category": "drug", "synonyms": "acetylsalicylic acid;ASA" },
+ { "name": "Paracetamol", "smiles": "CC(=O)Nc1ccc(O)cc1", "category": "drug", "synonyms": "acetaminophen;APAP" },
+ { "name": "Ibuprofen", "smiles": "CC(C)Cc1ccc(cc1)C(C)C(=O)O", "category": "drug", "synonyms": "" },
+ { "name": "Naproxen", "smiles": "COc1ccc2cc(ccc2c1)C(C)C(=O)O", "category": "drug", "synonyms": "" },
+ { "name": "Caffeine", "smiles": "Cn1cnc2c1c(=O)n(C)c(=O)n2C", "category": "drug", "synonyms": "" },
+ { "name": "Theobromine", "smiles": "Cn1cnc2c1c(=O)[nH]c(=O)n2C", "category": "drug", "synonyms": "" },
+ { "name": "Nicotine", "smiles": "CN1CCCC1c1cccnc1", "category": "drug", "synonyms": "" },
+ { "name": "Salicylic acid", "smiles": "OC(=O)c1ccccc1O", "category": "drug", "synonyms": "2-hydroxybenzoic acid" },
+ { "name": "Dopamine", "smiles": "NCCc1ccc(O)c(O)c1", "category": "drug", "synonyms": "" },
+ { "name": "Serotonin", "smiles": "NCCc1c[nH]c2ccc(O)cc12", "category": "drug", "synonyms": "5-HT" },
+ { "name": "Histamine", "smiles": "NCCc1c[nH]cn1", "category": "drug", "synonyms": "" },
+ { "name": "Melatonin", "smiles": "COc1ccc2[nH]cc(CCNC(C)=O)c2c1", "category": "drug", "synonyms": "" },
+ { "name": "Adrenaline", "smiles": "CNCC(O)c1ccc(O)c(O)c1", "category": "drug", "synonyms": "epinephrine" },
+ { "name": "Acetylcholine", "smiles": "CC(=O)OCC[N+](C)(C)C", "category": "drug", "synonyms": "ACh", "charge": 1 },
+ { "name": "GABA", "smiles": "NCCCC(=O)O", "category": "drug", "synonyms": "gamma-aminobutyric acid" },
+ { "name": "Vanillin", "smiles": "COc1cc(C=O)ccc1O", "category": "drug", "synonyms": "" },
+ { "name": "Menthol", "smiles": "CC(C)C1CCC(C)CC1O", "category": "drug", "synonyms": "" },
+ { "name": "Camphor", "smiles": "CC1(C)C2CCC1(C)C(=O)C2", "category": "drug", "synonyms": "" },
+ { "name": "Nicotinamide", "smiles": "NC(=O)c1cccnc1", "category": "drug", "synonyms": "niacinamide;vitamin B3" },
+ { "name": "Benzocaine", "smiles": "CCOC(=O)c1ccc(N)cc1", "category": "drug", "synonyms": "" },
+ { "name": "Lidocaine", "smiles": "CCN(CC)CC(=O)Nc1c(C)cccc1C", "category": "drug", "synonyms": "" },
+ { "name": "Aspartame", "smiles": "COC(=O)C(Cc1ccccc1)NC(=O)C(N)CC(=O)O", "category": "drug", "synonyms": "" },
+
+ { "name": "Hydrogen sulfide", "smiles": "S", "category": "inorganic", "synonyms": "" },
+ { "name": "Sulfur dioxide", "smiles": "O=S=O", "category": "inorganic", "synonyms": "" },
+ { "name": "Sulfur trioxide", "smiles": "O=S(=O)=O", "category": "inorganic", "synonyms": "" },
+ { "name": "Nitrous oxide", "smiles": "[N-]=[N+]=O", "category": "inorganic", "synonyms": "dinitrogen monoxide;laughing gas" },
+ { "name": "Hydrogen cyanide", "smiles": "C#N", "category": "inorganic", "synonyms": "" },
+ { "name": "Nitric acid", "smiles": "O[N+](=O)[O-]", "category": "inorganic", "synonyms": "" },
+ { "name": "Sulfuric acid", "smiles": "OS(=O)(=O)O", "category": "inorganic", "synonyms": "" },
+ { "name": "Phosphoric acid", "smiles": "OP(=O)(O)O", "category": "inorganic", "synonyms": "" },
+ { "name": "Phosphine", "smiles": "P", "category": "inorganic", "synonyms": "" },
+ { "name": "Silane", "smiles": "[SiH4]", "category": "inorganic", "synonyms": "" },
+ { "name": "Boron trifluoride", "smiles": "FB(F)F", "category": "inorganic", "synonyms": "" },
+ { "name": "Carbon disulfide", "smiles": "S=C=S", "category": "inorganic", "synonyms": "" },
+ { "name": "Dinitrogen tetroxide", "smiles": "O=[N+]([O-])[N+](=O)[O-]", "category": "inorganic", "synonyms": "" },
+ { "name": "Nitric oxide", "smiles": "[N]=O", "category": "inorganic", "synonyms": "nitrogen monoxide", "multiplicity": 2 },
+ { "name": "Nitrogen dioxide", "smiles": "[O]N=O", "category": "inorganic", "synonyms": "", "multiplicity": 2 },
+
+ { "name": "Hydronium", "smiles": "[OH3+]", "category": "ion", "synonyms": "oxonium", "charge": 1 },
+ { "name": "Hydroxide", "smiles": "[OH-]", "category": "ion", "synonyms": "", "charge": -1 },
+ { "name": "Ammonium", "smiles": "[NH4+]", "category": "ion", "synonyms": "", "charge": 1 },
+ { "name": "Carbonate", "smiles": "[O-]C(=O)[O-]", "category": "ion", "synonyms": "", "charge": -2 },
+ { "name": "Bicarbonate", "smiles": "OC(=O)[O-]", "category": "ion", "synonyms": "hydrogen carbonate", "charge": -1 },
+ { "name": "Nitrate", "smiles": "[O-][N+](=O)[O-]", "category": "ion", "synonyms": "", "charge": -1 },
+ { "name": "Nitrite", "smiles": "[O-]N=O", "category": "ion", "synonyms": "", "charge": -1 },
+ { "name": "Sulfate", "smiles": "[O-]S(=O)(=O)[O-]", "category": "ion", "synonyms": "", "charge": -2 },
+ { "name": "Phosphate", "smiles": "[O-]P(=O)([O-])[O-]", "category": "ion", "synonyms": "", "charge": -3 },
+ { "name": "Acetate", "smiles": "CC(=O)[O-]", "category": "ion", "synonyms": "", "charge": -1 },
+ { "name": "Cyanide", "smiles": "[C-]#N", "category": "ion", "synonyms": "", "charge": -1 }
+]
diff --git a/tests/conftest.py b/tests/conftest.py
index c259c38..3a5385a 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -4,9 +4,32 @@
Shared test fixtures for QuantUI test suite.
"""
+import os
+import tempfile
+
import pytest
+@pytest.fixture(autouse=True, scope="session")
+def _isolate_results_dir():
+ """Redirect the default results directory to a temp dir for the whole suite.
+
+ ``results_storage._default_results_dir()`` falls back to a **cwd-relative**
+ ``Path("results")`` when ``results_dir`` isn't passed (e.g. the calibration
+ runner in ``benchmarks.py`` saves each step that way). Pointing
+ ``QUANTUI_RESULTS_DIR`` at a temp dir keeps every default save isolated, so
+ the suite never writes ``results/`` into the working directory.
+ """
+ prev = os.environ.get("QUANTUI_RESULTS_DIR")
+ with tempfile.TemporaryDirectory(prefix="quantui_test_results_") as tmp:
+ os.environ["QUANTUI_RESULTS_DIR"] = tmp
+ yield
+ if prev is None:
+ os.environ.pop("QUANTUI_RESULTS_DIR", None)
+ else:
+ os.environ["QUANTUI_RESULTS_DIR"] = prev
+
+
@pytest.fixture(autouse=True, scope="session")
def _suppress_plotly_browser():
"""Prevent plotly from opening browser tabs during tests.
diff --git a/tests/test_app.py b/tests/test_app.py
index 1b89a03..2a770df 100644
--- a/tests/test_app.py
+++ b/tests/test_app.py
@@ -1251,8 +1251,8 @@ def test_unfiltered_when_no_molecule_loaded(self, tmp_path, monkeypatch):
assert app._molecule is None
app._refresh_freq_seed_options()
labels = [lbl for lbl, _ in app._freq_seed_dd.options]
- assert any(lbl.startswith("H2O") for lbl in labels)
- assert any(lbl.startswith("CH4") for lbl in labels)
+ assert any("H2O" in lbl for lbl in labels)
+ assert any("CH4" in lbl for lbl in labels)
def test_filtered_to_current_molecule_formula(self, tmp_path, monkeypatch):
monkeypatch.setenv("QUANTUI_RESULTS_DIR", str(tmp_path))
@@ -1263,8 +1263,8 @@ def test_filtered_to_current_molecule_formula(self, tmp_path, monkeypatch):
app._refresh_freq_seed_options()
labels = [lbl for lbl, _ in app._freq_seed_dd.options]
assert labels[0] == "(use current molecule)"
- assert any(lbl.startswith("H2O") for lbl in labels)
- assert not any(lbl.startswith("CH4") for lbl in labels)
+ assert any("H2O" in lbl for lbl in labels)
+ assert not any("CH4" in lbl for lbl in labels)
def test_set_molecule_triggers_filter(self, tmp_path, monkeypatch):
# Loading a new molecule should auto-refresh the dropdown so stale
@@ -1275,8 +1275,8 @@ def test_set_molecule_triggers_filter(self, tmp_path, monkeypatch):
app = QuantUIApp()
app._set_molecule(self._water(), label="test")
labels = [lbl for lbl, _ in app._freq_seed_dd.options]
- assert any(lbl.startswith("H2O") for lbl in labels)
- assert not any(lbl.startswith("CH4") for lbl in labels)
+ assert any("H2O" in lbl for lbl in labels)
+ assert not any("CH4" in lbl for lbl in labels)
class TestPopIsosurfaceBug8:
@@ -1435,8 +1435,8 @@ def test_seed_options_filtered_by_formula(self, tmp_path, monkeypatch):
app._molecule = self._water()
app._refresh_tddft_seed_options()
labels = [lbl for lbl, _ in app._tddft_seed_dd.options]
- assert any(lbl.startswith("H2O") for lbl in labels)
- assert not any(lbl.startswith("CH4") for lbl in labels)
+ assert any("H2O" in lbl for lbl in labels)
+ assert not any("CH4" in lbl for lbl in labels)
def test_set_molecule_triggers_tddft_seed_filter(self, tmp_path, monkeypatch):
monkeypatch.setenv("QUANTUI_RESULTS_DIR", str(tmp_path))
@@ -1445,8 +1445,8 @@ def test_set_molecule_triggers_tddft_seed_filter(self, tmp_path, monkeypatch):
app = QuantUIApp()
app._set_molecule(self._water(), label="test")
labels = [lbl for lbl, _ in app._tddft_seed_dd.options]
- assert any(lbl.startswith("H2O") for lbl in labels)
- assert not any(lbl.startswith("CH4") for lbl in labels)
+ assert any("H2O" in lbl for lbl in labels)
+ assert not any("CH4" in lbl for lbl in labels)
def test_picking_seed_disables_preopt_and_shows_note(self, tmp_path, monkeypatch):
monkeypatch.setenv("QUANTUI_RESULTS_DIR", str(tmp_path))
@@ -1831,7 +1831,7 @@ def test_same_formula_different_geometry_excluded(self, tmp_path, monkeypatch):
labels = [lbl for lbl, _ in app._freq_seed_dd.options]
assert len(labels) == 2, labels
assert labels[0] == "(use current molecule)"
- assert labels[1].startswith("H2O")
+ assert "H2O" in labels[1]
def test_same_formula_within_tolerance_included(self, tmp_path, monkeypatch):
monkeypatch.setenv("QUANTUI_RESULTS_DIR", str(tmp_path))
@@ -1847,7 +1847,7 @@ def test_same_formula_within_tolerance_included(self, tmp_path, monkeypatch):
app._refresh_freq_seed_options()
labels = [lbl for lbl, _ in app._freq_seed_dd.options]
assert len(labels) == 3, labels
- assert sum(1 for lbl in labels if lbl.startswith("H2O")) == 2
+ assert sum(1 for lbl in labels if "H2O" in lbl) == 2
def test_atom_order_mismatch_excluded(self, tmp_path, monkeypatch):
# Strict atom-order policy: ["H","O","H"] is not the same as
@@ -1864,7 +1864,7 @@ def test_atom_order_mismatch_excluded(self, tmp_path, monkeypatch):
app._refresh_freq_seed_options()
labels = [lbl for lbl, _ in app._freq_seed_dd.options]
assert len(labels) == 2
- assert labels[1].startswith("H2O")
+ assert "H2O" in labels[1]
def test_malformed_trajectory_falls_back_to_formula_match(
self, tmp_path, monkeypatch
@@ -1892,7 +1892,7 @@ def test_malformed_trajectory_falls_back_to_formula_match(
app._molecule = self._water_molecule()
app._refresh_freq_seed_options()
labels = [lbl for lbl, _ in app._freq_seed_dd.options]
- assert any(lbl.startswith("H2O") for lbl in labels)
+ assert any("H2O" in lbl for lbl in labels)
def test_starting_geometry_cache_hit_avoids_reread(self, tmp_path):
# _load_starting_geometry must cache per-result so back-to-back
diff --git a/tests/test_app_formatters.py b/tests/test_app_formatters.py
index 3a47871..2ed2596 100644
--- a/tests/test_app_formatters.py
+++ b/tests/test_app_formatters.py
@@ -161,3 +161,63 @@ def test_format_past_result_contains_calc_type_badge():
html = format_past_result(data)
assert "Single Point" in html
assert "H2O" in html
+
+
+def test_format_past_result_renders_ccsd_breakdown():
+ # The saved-result card (Results tab) must show the HF reference + CCSD
+ # correlation + (T) triples rows when those fields were persisted.
+ data = {
+ "calc_type": "single_point",
+ "converged": True,
+ "homo_lumo_gap_ev": 27.0,
+ "energy_hartree": -75.0139,
+ "energy_ev": -2041.23,
+ "n_iterations": 5,
+ "timestamp": "2026-06-10_15-48-02-285574",
+ "formula": "H2O",
+ "method": "CCSD(T)",
+ "basis": "STO-3G",
+ "ccsd_correlation_hartree": -0.0497,
+ "ccsd_t_correction_hartree": -0.0008,
+ }
+ html = format_past_result(data)
+ assert "HF reference" in html
+ assert "CCSD correlation" in html
+ assert "(T) triples correction" in html
+
+
+def test_format_past_result_renders_mp2_breakdown():
+ data = {
+ "calc_type": "single_point",
+ "converged": True,
+ "homo_lumo_gap_ev": 20.0,
+ "energy_hartree": -75.01,
+ "energy_ev": -2041.0,
+ "n_iterations": 8,
+ "timestamp": "2026-06-10_15-48-02-285574",
+ "formula": "H2O",
+ "method": "MP2",
+ "basis": "STO-3G",
+ "mp2_correlation_hartree": -0.035,
+ }
+ html = format_past_result(data)
+ assert "HF reference" in html
+ assert "MP2 correlation" in html
+
+
+def test_format_past_result_hf_dft_has_no_breakdown():
+ data = {
+ "calc_type": "single_point",
+ "converged": True,
+ "homo_lumo_gap_ev": 10.0,
+ "energy_hartree": -75.0,
+ "energy_ev": -2040.0,
+ "n_iterations": 10,
+ "timestamp": "2026-05-02_12-00-00-000001",
+ "formula": "H2O",
+ "method": "RHF",
+ "basis": "STO-3G",
+ }
+ html = format_past_result(data)
+ assert "correlation" not in html
+ assert "HF reference" not in html
diff --git a/tests/test_bulk_library.py b/tests/test_bulk_library.py
new file mode 100644
index 0000000..6283ae9
--- /dev/null
+++ b/tests/test_bulk_library.py
@@ -0,0 +1,86 @@
+"""Tests for the bulk QM9 library subset (M-STRUCT STRUCT.8).
+
+Platform-independent: reads the committed store + manifest (the QM9 download +
+RDKit are build-time only). No PySCF.
+"""
+
+import json
+
+import pytest
+
+from quantui import config
+from quantui import molecule_library as ml
+
+_BULK = ml._data_dir() / "manifests" / "bulk_qm9.json"
+
+pytestmark = pytest.mark.skipif(
+ not _BULK.exists(),
+ reason="bulk_qm9.json not built (run scripts/build_bulk_library.py)",
+)
+
+
+def _bulk_entries():
+ return json.loads(_BULK.read_text(encoding="utf-8"))
+
+
+# ============================================================================
+# Manifest integrity
+# ============================================================================
+
+
+class TestBulkManifest:
+ def test_manifest_nonempty(self):
+ assert len(_bulk_entries()) >= 100
+
+ def test_every_entry_well_formed(self):
+ ceiling = config.LIBRARY_HEAVY_ATOM_CEILING_BULK
+ for e in _bulk_entries():
+ assert e["category"] == "bulk-qm9"
+ assert e["source"] == "qm9-dft"
+ assert e["charge"] == 0 and e["multiplicity"] == 1
+ assert len(e["coordinates"]) == len(e["atoms"])
+ assert sum(1 for a in e["atoms"] if a != "H") <= ceiling
+ assert e["id"].startswith("qm9-")
+
+ def test_ids_unique(self):
+ ids = [e["id"] for e in _bulk_entries()]
+ assert len(ids) == len(set(ids))
+
+ def test_provenance_file_exists(self):
+ prov = ml._data_dir() / "library" / "QM9-PROVENANCE.md"
+ assert prov.exists()
+ assert "CC0" in prov.read_text(encoding="utf-8")
+
+
+# ============================================================================
+# Store integration + key contracts
+# ============================================================================
+
+
+class TestBulkInStore:
+ def test_total_count_includes_bulk(self):
+ assert ml.count() >= 176 + len(_bulk_entries())
+
+ def test_bulk_excluded_from_preset_dict(self):
+ # The browse dropdown must NOT balloon with thousands of bulk entries.
+ d = config.MOLECULE_LIBRARY
+ assert all(not k.startswith("qm9-") for k in d)
+ assert len(d) == 176 # presets + curated only
+
+ def test_bulk_category_present(self):
+ assert "bulk-qm9" in ml.categories()
+
+ def test_bulk_reachable_via_search(self):
+ rows = ml.search("", category="bulk-qm9", limit=10)
+ assert len(rows) == 10
+ assert all(r["category"] == "bulk-qm9" for r in rows)
+
+ def test_bulk_entry_materializes_with_coords(self):
+ sample_id = _bulk_entries()[0]["id"]
+ entry = ml.get(sample_id)
+ assert entry is not None
+ assert len(entry["coordinates"]) == len(entry["atoms"])
+ assert entry["coordinates"] # non-empty
+
+ def test_store_within_budget(self):
+ assert ml.db_path().stat().st_size <= config.LIBRARY_SIZE_BUDGET_BYTES
diff --git a/tests/test_curated_library.py b/tests/test_curated_library.py
new file mode 100644
index 0000000..4679c2c
--- /dev/null
+++ b/tests/test_curated_library.py
@@ -0,0 +1,138 @@
+"""Tests for the curated named library (M-STRUCT STRUCT.7).
+
+Platform-independent: reads the committed store + manifest (RDKit is only
+needed at build time, not here). No PySCF.
+"""
+
+import json
+
+from quantui import config
+from quantui import molecule_library as ml
+
+_CURATED = ml._data_dir() / "manifests" / "curated.json"
+
+
+def _curated_entries():
+ return json.loads(_CURATED.read_text(encoding="utf-8"))
+
+
+# ============================================================================
+# Manifest integrity
+# ============================================================================
+
+
+class TestCuratedManifest:
+ def test_manifest_exists_and_nonempty(self):
+ entries = _curated_entries()
+ assert len(entries) >= 150
+
+ def test_every_entry_well_formed(self):
+ for e in _curated_entries():
+ assert e["atoms"], e["name"]
+ assert len(e["coordinates"]) == len(e["atoms"]), e["name"]
+ assert e["source"] == "curated-ff"
+ assert e["category"]
+ assert e["id"]
+
+ def test_ids_unique(self):
+ ids = [e["id"] for e in _curated_entries()]
+ assert len(ids) == len(set(ids))
+
+ def test_respects_heavy_atom_ceiling(self):
+ ceiling = config.LIBRARY_HEAVY_ATOM_CEILING_CURATED
+ for e in _curated_entries():
+ n_heavy = sum(1 for a in e["atoms"] if a != "H")
+ assert n_heavy <= ceiling, f"{e['name']} has {n_heavy} heavy atoms"
+
+
+# ============================================================================
+# Store contents after curated merge
+# ============================================================================
+
+
+class TestStoreWithCurated:
+ def test_total_count_includes_presets_and_curated(self):
+ # Store also holds bulk entries (STRUCT.8); assert the curated tier is
+ # fully present rather than an exact total.
+ assert ml.count() >= 20 + len(_curated_entries())
+ curated_rows = sum(
+ len(ml.search("", category=c, limit=1000))
+ for c in (
+ "amino-acid",
+ "nucleobase",
+ "biomolecule",
+ "solvent",
+ "functional-group",
+ "hydrocarbon",
+ "drug",
+ "inorganic",
+ "ion",
+ )
+ )
+ assert curated_rows == len(_curated_entries())
+
+ def test_expected_categories_present(self):
+ cats = set(ml.categories())
+ assert {
+ "amino-acid",
+ "nucleobase",
+ "biomolecule",
+ "solvent",
+ "functional-group",
+ "hydrocarbon",
+ "drug",
+ "inorganic",
+ "ion",
+ } <= cats
+
+ def test_all_20_amino_acids(self):
+ rows = ml.search("", category="amino-acid", limit=100)
+ assert len(rows) == 20
+
+ def test_aspirin_present_and_correct(self):
+ asp = ml.get("aspirin")
+ assert asp is not None
+ assert asp["formula"] == "C9H8O4"
+ assert asp["category"] == "drug"
+ assert asp["charge"] == 0
+
+ def test_ion_charges(self):
+ assert ml.get("nitrate")["charge"] == -1
+ assert ml.get("sulfate")["charge"] == -2
+ assert ml.get("phosphate")["charge"] == -3
+ assert ml.get("ammonium")["charge"] == 1
+
+ def test_radical_multiplicities(self):
+ assert ml.get("nitric-oxide")["multiplicity"] == 2
+ assert ml.get("nitrogen-dioxide")["multiplicity"] == 2
+
+ def test_search_by_synonym(self):
+ assert any(h["id"] == "glucose" for h in ml.search("dextrose"))
+ assert any(h["id"] == "paracetamol" for h in ml.search("acetaminophen"))
+
+
+# ============================================================================
+# Back-compat dict + size budget
+# ============================================================================
+
+
+class TestPresetDictAndBudget:
+ def test_preset_dict_includes_curated(self):
+ d = config.MOLECULE_LIBRARY
+ assert "aspirin" in d
+ assert "glycine" in d
+ # Presets still lead the (interim) flat dropdown.
+ assert list(d)[:3] == ["H2", "O2", "N2"]
+
+ def test_curated_entry_has_legacy_shape(self):
+ gly = config.MOLECULE_LIBRARY["glycine"]
+ assert set(gly) == {
+ "atoms",
+ "coordinates",
+ "charge",
+ "multiplicity",
+ "description",
+ }
+
+ def test_store_within_budget(self):
+ assert ml.db_path().stat().st_size <= config.LIBRARY_SIZE_BUDGET_BYTES
diff --git a/tests/test_library_governance.py b/tests/test_library_governance.py
new file mode 100644
index 0000000..92d5720
--- /dev/null
+++ b/tests/test_library_governance.py
@@ -0,0 +1,102 @@
+"""Whole-library governance + round-trip checks (M-STRUCT STRUCT.10).
+
+Validates *every* shipped entry (across all tiers) — well-formed, coordinate
+round-trip stable, ids globally unique — plus the ≤10 MB budget and the
+preset-dict/bulk contract. Platform-independent; no PySCF, no network.
+"""
+
+import math
+
+import pytest
+
+from quantui import config
+from quantui import molecule_library as ml
+
+# Reasonable element-symbol whitelist for the bundled tiers (CHONF + curated
+# heteroatoms + common ions). Guards against codec corruption.
+_KNOWN = {
+ "H",
+ "He",
+ "Li",
+ "Be",
+ "B",
+ "C",
+ "N",
+ "O",
+ "F",
+ "Ne",
+ "Na",
+ "Mg",
+ "Al",
+ "Si",
+ "P",
+ "S",
+ "Cl",
+ "Ar",
+ "K",
+ "Ca",
+ "Br",
+ "I",
+}
+
+
+class TestEveryEntryWellFormed:
+ def test_all_entries_consistent(self):
+ seen_ids = set()
+ for e in ml.iter_entries():
+ eid = e["id"]
+ assert eid not in seen_ids, f"duplicate id {eid}"
+ seen_ids.add(eid)
+ atoms, coords = e["atoms"], e["coordinates"]
+ assert atoms, eid
+ assert len(atoms) == len(coords) == e["n_atoms"], eid
+ assert e["n_heavy"] == sum(1 for a in atoms if a != "H"), eid
+ assert isinstance(e["charge"], int) and isinstance(e["multiplicity"], int)
+ assert e["formula"], eid
+ assert e["category"] and e["source"], eid
+ for sym in atoms:
+ assert sym in _KNOWN, f"{eid}: unexpected symbol {sym!r}"
+ for xyz in coords:
+ assert len(xyz) == 3, eid
+
+ def test_coordinate_round_trip_is_stable(self):
+ # Re-encoding the stored (already-decoded) coords must be idempotent at
+ # the codec's 0.001 Å resolution.
+ for e in ml.iter_entries():
+ atoms, coords = e["atoms"], e["coordinates"]
+ blob = ml.encode_coords(atoms, coords)
+ out_atoms, out_coords = ml.decode_coords(blob)
+ assert out_atoms == atoms, e["id"]
+ for a, b in zip(coords, out_coords):
+ for ca, cb in zip(a, b):
+ assert math.isclose(ca, cb, abs_tol=1e-6), e["id"]
+
+
+class TestBudgetAndContracts:
+ def test_store_within_10mb_budget(self):
+ size = ml.db_path().stat().st_size
+ assert size <= config.LIBRARY_SIZE_BUDGET_BYTES, f"{size} bytes > budget"
+
+ def test_iter_count_matches_count(self):
+ assert sum(1 for _ in ml.iter_entries()) == ml.count()
+
+ def test_preset_dict_is_non_bulk_only(self):
+ d = ml.get_preset_dict()
+ non_bulk = sum(
+ 1 for e in ml.iter_entries() if e["category"] not in ml._BULK_CATEGORIES
+ )
+ assert len(d) == non_bulk
+ assert all(not k.startswith("qm9-") for k in d)
+
+ def test_reproducible_build_tooling_present(self):
+ # No-silent-cap governance: the deterministic builders ship in-repo and
+ # report skips/dedup counts to stdout (not hidden truncation).
+ scripts = ml._data_dir().parent.parent / "scripts"
+ if not scripts.is_dir():
+ pytest.skip("scripts/ not present (non-dev install)")
+ for name in (
+ "build_library.py",
+ "build_curated_library.py",
+ "build_bulk_library.py",
+ ):
+ assert (scripts / name).exists(), name
diff --git a/tests/test_molecule_library.py b/tests/test_molecule_library.py
new file mode 100644
index 0000000..c44ac58
--- /dev/null
+++ b/tests/test_molecule_library.py
@@ -0,0 +1,160 @@
+"""Tests for the bundled molecule-library store + loader (M-STRUCT STRUCT.6).
+
+Platform-independent (stdlib sqlite3 + struct + json); no RDKit, no PySCF.
+"""
+
+import math
+
+import pytest
+
+from quantui import config
+from quantui import molecule_library as ml
+
+_BUDGET_BYTES = 10 * 1024 * 1024 # DEC-015
+
+
+# ============================================================================
+# Coordinate codec
+# ============================================================================
+
+
+class TestCoordCodec:
+ def test_round_trip_exact_for_3_decimal_coords(self):
+ atoms = ["O", "H", "H", "Cl"]
+ coords = [
+ [0.0, 0.0, 0.0],
+ [0.0, 0.757, 0.587],
+ [0.0, -0.757, 0.587],
+ [1.27, 0.0, -2.48],
+ ]
+ blob = ml.encode_coords(atoms, coords)
+ out_atoms, out_coords = ml.decode_coords(blob)
+ assert out_atoms == atoms
+ for a, b in zip(coords, out_coords):
+ for ca, cb in zip(a, b):
+ assert math.isclose(ca, cb, abs_tol=1e-9)
+
+ def test_record_size_is_8_bytes_per_atom(self):
+ blob = ml.encode_coords(["C", "H"], [[0, 0, 0], [1, 1, 1]])
+ assert len(blob) == 2 * 8
+
+ def test_two_char_symbol_round_trips(self):
+ atoms, coords = ml.decode_coords(
+ ml.encode_coords(["Cl", "Na"], [[0, 0, 0], [2, 0, 0]])
+ )
+ assert atoms == ["Cl", "Na"]
+
+ def test_rejects_long_symbol(self):
+ with pytest.raises(ValueError):
+ ml.encode_coords(["Uuo"], [[0, 0, 0]])
+
+
+# ============================================================================
+# Store build + query API
+# ============================================================================
+
+
+class TestStoreBuildAndQuery:
+ def test_build_from_manifest_round_trips(self, tmp_path):
+ target = tmp_path / "lib.sqlite"
+ ml.build_from_manifests(target)
+ assert target.exists()
+
+ def test_store_contains_the_original_presets(self):
+ # The store grows as STRUCT.7/.8 add content; assert the original 20
+ # presets are all still present rather than an exact total.
+ preset_ids = {
+ "H2",
+ "O2",
+ "N2",
+ "CO",
+ "HF",
+ "HCl",
+ "H2O",
+ "CO2",
+ "O3",
+ "H2O2",
+ "CH4",
+ "NH3",
+ "C2H6",
+ "C2H4",
+ "C2H2",
+ "CH3OH",
+ "CH2O",
+ "CH3CHO",
+ "CH3COOH",
+ "C6H6",
+ }
+ assert ml.count() >= 20
+ assert all(ml.get(pid) is not None for pid in preset_ids)
+
+ def test_categories_present(self):
+ cats = ml.categories()
+ assert {"diatomic", "triatomic", "small-organic", "aromatic"} <= set(cats)
+
+ def test_get_returns_full_entry_with_coords(self):
+ entry = ml.get("H2O")
+ assert entry is not None
+ assert entry["atoms"] == ["O", "H", "H"]
+ assert entry["n_heavy"] == 1
+ assert entry["coordinates"][1] == [0.0, 0.757, 0.587]
+
+ def test_get_unknown_returns_none(self):
+ assert ml.get("NOTAREALID") is None
+
+ def test_search_by_formula(self):
+ hits = ml.search("C6H6")
+ assert any(h["id"] == "C6H6" for h in hits)
+
+ def test_search_by_category_filter(self):
+ hits = ml.search("", category="aromatic")
+ assert [h["id"] for h in hits] == ["C6H6"]
+
+ def test_search_returns_lightweight_rows(self):
+ hits = ml.search("H2O")
+ assert hits and "coordinates" not in hits[0]
+
+
+# ============================================================================
+# Legacy back-compat shim
+# ============================================================================
+
+
+class TestPresetDictBackCompat:
+ def test_get_preset_dict_shape(self):
+ d = ml.get_preset_dict()
+ assert len(d) >= 20
+ h2o = d["H2O"]
+ assert set(h2o) == {
+ "atoms",
+ "coordinates",
+ "charge",
+ "multiplicity",
+ "description",
+ }
+
+ def test_config_shim_resolves(self):
+ lib = config.MOLECULE_LIBRARY
+ assert len(lib) >= 20
+ assert lib["O2"]["multiplicity"] == 3 # triplet preserved
+ assert lib["H2O"]["coordinates"][2] == [0.0, -0.757, 0.587]
+
+ def test_config_shim_unknown_attr_raises(self):
+ with pytest.raises(AttributeError):
+ _ = config.THIS_DOES_NOT_EXIST
+
+ def test_preset_dict_excludes_bulk_categories(self):
+ # No bulk entries yet, but the contract must hold for STRUCT.8.
+ for entry_id in ml.get_preset_dict():
+ full = ml.get(entry_id)
+ assert full["category"] not in ml._BULK_CATEGORIES
+
+
+# ============================================================================
+# Size governance (STRUCT.10 precursor)
+# ============================================================================
+
+
+class TestSizeBudget:
+ def test_committed_store_within_10mb(self):
+ assert ml.db_path().stat().st_size <= _BUDGET_BYTES
diff --git a/tests/test_orbital_visualization.py b/tests/test_orbital_visualization.py
index bad6d3a..697fd16 100644
--- a/tests/test_orbital_visualization.py
+++ b/tests/test_orbital_visualization.py
@@ -291,9 +291,37 @@ def test_returns_figure(self, minimal_cube_file):
fig = plot_cube_isosurface(minimal_cube_file)
assert isinstance(fig, go.Figure)
- def test_has_two_traces(self, minimal_cube_file):
+ def test_has_single_isosurface_trace(self, minimal_cube_file):
+ # Both lobes are drawn by one go.Isosurface trace (surface_count=2) to
+ # halve the figure payload (BUG-ISO-OOM).
fig = plot_cube_isosurface(minimal_cube_file)
- assert len(fig.data) == 2
+ iso = [t for t in fig.data if t.type == "isosurface"]
+ assert len(iso) == 1
+ assert iso[0].surface.count == 2 # both lobes via one trace
+
+ def test_large_grid_is_downsampled(self):
+ # The cube is written at a fixed resolution regardless of molecule size;
+ # a full 60^3 = 216k-point grid flattened into the figure could exhaust
+ # browser memory. The render path must stride it under the cap.
+ from unittest.mock import patch
+
+ from quantui import orbital_visualization as ov
+
+ n = 60
+ fake_cube = {
+ "nx": n,
+ "ny": n,
+ "nz": n,
+ "data": np.zeros((n, n, n)),
+ "origin": np.zeros(3),
+ "axes": np.eye(3) * 0.3,
+ "atoms": [],
+ }
+ with patch.object(ov, "parse_cube_file", return_value=fake_cube):
+ fig = ov.plot_cube_isosurface("dummy.cube", isovalue=0.02)
+ iso = [t for t in fig.data if t.type == "isosurface"][0]
+ assert len(iso.x) <= ov._MAX_ISOSURFACE_POINTS
+ assert len(iso.x) < n * n * n # actually downsampled
def test_custom_title(self, minimal_cube_file):
fig = plot_cube_isosurface(minimal_cube_file, title="HOMO Isosurface")
@@ -304,8 +332,11 @@ def test_scene_has_axis_labels(self, minimal_cube_file):
assert "Bohr" in fig.layout.scene.xaxis.title.text
def test_show_molecule_adds_overlay_traces(self, minimal_cube_file):
+ # The isosurface is one trace now; show_molecule adds ≥1 scatter3d
+ # overlay (atoms, plus bonds when there are ≥2 atoms).
fig = plot_cube_isosurface(minimal_cube_file, show_molecule=True)
- assert len(fig.data) >= 3
+ scatter = [t for t in fig.data if t.type == "scatter3d"]
+ assert len(scatter) >= 1
def test_show_grid_false_hides_scene_grid(self, minimal_cube_file):
fig = plot_cube_isosurface(minimal_cube_file, show_grid=False)
diff --git a/tests/test_struct_disambiguation.py b/tests/test_struct_disambiguation.py
new file mode 100644
index 0000000..00b1222
--- /dev/null
+++ b/tests/test_struct_disambiguation.py
@@ -0,0 +1,135 @@
+"""Tests for online-search disambiguation (M-STRUCT STRUCT.5).
+
+Platform-independent: network mocked, no PySCF. Exercises the candidate
+backend + the app pick-list handlers (no event loop / no real threads).
+"""
+
+from unittest.mock import Mock, patch
+
+from quantui import structure_providers
+from quantui.app import QuantUIApp
+from quantui.pubchem import search_pubchem_candidates
+
+_XYLENE_CIDS = [7237, 7929, 7809] # o-, m-, p-xylene
+_XYLENE_PROPS = {
+ "PropertyTable": {
+ "Properties": [
+ {
+ "CID": 7237,
+ "MolecularFormula": "C8H10",
+ "MolecularWeight": "106.16",
+ "Title": "o-Xylene",
+ },
+ {
+ "CID": 7929,
+ "MolecularFormula": "C8H10",
+ "MolecularWeight": "106.16",
+ "Title": "m-Xylene",
+ },
+ {
+ "CID": 7809,
+ "MolecularFormula": "C8H10",
+ "MolecularWeight": "106.16",
+ "Title": "p-Xylene",
+ },
+ ]
+ }
+}
+
+
+# ============================================================================
+# Backend: search_pubchem_candidates / search_candidates
+# ============================================================================
+
+
+class TestCandidateBackend:
+ @patch("quantui.pubchem._http_get")
+ @patch("quantui.pubchem.search_cids_by_name")
+ def test_candidates_built_from_batch_props(self, mock_cids, mock_http):
+ mock_cids.return_value = _XYLENE_CIDS
+ mock_http.return_value = Mock(
+ status_code=200,
+ json=Mock(return_value=_XYLENE_PROPS),
+ raise_for_status=Mock(),
+ )
+ cands = search_pubchem_candidates("xylene")
+ assert [c["cid"] for c in cands] == _XYLENE_CIDS # search order preserved
+ assert cands[0]["title"] == "o-Xylene"
+ assert cands[0]["formula"] == "C8H10"
+ assert abs(cands[0]["mw"] - 106.16) < 0.01
+
+ @patch("quantui.pubchem.search_cids_by_name")
+ def test_candidates_empty_when_no_cids(self, mock_cids):
+ mock_cids.return_value = []
+ assert search_pubchem_candidates("zzznotreal") == []
+
+ def test_search_candidates_skips_non_name_types(self):
+ # SMILES / CID resolve to a single structure → no disambiguation.
+ assert structure_providers.search_candidates("CC(=O)O") == []
+ assert structure_providers.search_candidates("962") == []
+
+ @patch("quantui.structure_providers.search_pubchem_candidates")
+ def test_search_candidates_swallows_network_error(self, mock_cands):
+ from quantui.pubchem import PubChemAPIError
+
+ mock_cands.side_effect = PubChemAPIError("offline")
+ # Falls back to [] so the caller uses the full single-result chain.
+ assert structure_providers.search_candidates("xylene") == []
+
+ @patch("quantui.structure_providers.search_pubchem_candidates")
+ def test_search_candidates_returns_list_for_name(self, mock_cands):
+ mock_cands.return_value = [
+ {"cid": 1, "title": "x", "formula": "CH4", "mw": 16.0}
+ ]
+ out = structure_providers.search_candidates("methane")
+ assert len(out) == 1
+
+
+# ============================================================================
+# App pick-list handlers
+# ============================================================================
+
+
+class TestPickListHandlers:
+ def test_candidates_dropdown_hidden_initially(self):
+ app = QuantUIApp()
+ assert app.pubchem_candidates_dd.layout.display == "none"
+
+ def test_show_candidates_populates_and_reveals(self):
+ app = QuantUIApp()
+ cands = [
+ {"cid": 7237, "title": "o-Xylene", "formula": "C8H10", "mw": 106.16},
+ {"cid": 7929, "title": "m-Xylene", "formula": "C8H10", "mw": 106.16},
+ ]
+ app._show_pubchem_candidates("xylene", cands)
+ values = [v for _, v in app.pubchem_candidates_dd.options]
+ assert values == ["", "7237", "7929"] # placeholder + 2 cids
+ assert app.pubchem_candidates_dd.layout.display == ""
+ assert "2 matches" in app.pubchem_msg.value
+ # Showing the list must not auto-load a molecule.
+ assert app._molecule is None
+
+ def test_hide_candidates_resets(self):
+ app = QuantUIApp()
+ app._show_pubchem_candidates(
+ "xylene",
+ [
+ {"cid": 1, "title": "a", "formula": "C8H10", "mw": 1.0},
+ {"cid": 2, "title": "b", "formula": "C8H10", "mw": 1.0},
+ ],
+ )
+ app._hide_pubchem_candidates()
+ assert app.pubchem_candidates_dd.layout.display == "none"
+ assert app.pubchem_candidates_dd.value == ""
+
+ def test_candidate_select_placeholder_is_noop(self):
+ app = QuantUIApp()
+ app._on_pubchem_candidate_selected({"new": ""})
+ assert app._molecule is None
+
+ def test_candidate_select_ignored_during_refresh(self):
+ app = QuantUIApp()
+ app._pubchem_cand_refreshing = True
+ # Should return before touching the event loop / spawning a thread.
+ app._on_pubchem_candidate_selected({"new": "7237"})
+ assert app._molecule is None
diff --git a/tests/test_struct_providers.py b/tests/test_struct_providers.py
new file mode 100644
index 0000000..dc3b44c
--- /dev/null
+++ b/tests/test_struct_providers.py
@@ -0,0 +1,178 @@
+"""Tests for M-STRUCT STRUCT.3 (NCI CACTUS) + STRUCT.4 (provider chain).
+
+Platform-independent: network mocked, RDKit-only paths gated, no PySCF.
+"""
+
+from unittest.mock import Mock, patch
+
+import pytest
+import requests
+
+from quantui import cactus
+from quantui.pubchem import RDKIT_AVAILABLE, MoleculeNotFoundError, PubChemAPIError
+from quantui.structure_providers import (
+ ResolvedStructure,
+ resolve_structure,
+ student_friendly_resolve,
+)
+
+rdkit_only = pytest.mark.skipif(not RDKIT_AVAILABLE, reason="rdkit not installed")
+
+_WATER_META = {
+ "formula": "H2O",
+ "num_atoms": 3,
+ "num_heavy_atoms": 1,
+ "charge": 0,
+ "molecular_weight": 18.02,
+ "conformer_origin": "pubchem",
+ "source": "pubchem",
+}
+_WATER_XYZ = "3\nwater\nO 0 0 0\nH 1 0 0\nH 0 1 0"
+
+
+# ============================================================================
+# STRUCT.3 — CACTUS resolver
+# ============================================================================
+
+
+class TestCactus:
+ def test_looks_like_sdf(self, sample_sdf_water):
+ assert cactus._looks_like_sdf(sample_sdf_water) is True
+ assert cactus._looks_like_sdf("Page not found") is False
+
+ @patch("quantui.cactus.requests.get")
+ def test_resolve_to_sdf_success(self, mock_get, sample_sdf_water):
+ mock_get.return_value = Mock(status_code=200, text=sample_sdf_water)
+ sdf = cactus.resolve_to_sdf("aspirin")
+ assert "M END" in sdf
+ assert "compound" not in mock_get.call_args[0][0] # uses CACTUS, not pubchem
+
+ @patch("quantui.cactus.requests.get")
+ def test_resolve_to_sdf_tries_3d_then_2d(self, mock_get, sample_sdf_water):
+ # 3D endpoint returns an HTML error page; 2D endpoint returns real SDF.
+ mock_get.side_effect = [
+ Mock(status_code=200, text="error"),
+ Mock(status_code=200, text=sample_sdf_water),
+ ]
+ sdf = cactus.resolve_to_sdf("weirdmol", conformer_3d=True)
+ assert "M END" in sdf
+ assert mock_get.call_count == 2
+
+ @patch("quantui.cactus.requests.get")
+ def test_resolve_to_sdf_miss_raises_not_found(self, mock_get):
+ mock_get.return_value = Mock(status_code=404, text="not found")
+ with pytest.raises(MoleculeNotFoundError):
+ cactus.resolve_to_sdf("zzznotreal")
+
+ @patch("quantui.cactus.requests.get")
+ def test_resolve_to_sdf_network_error_raises_api_error(self, mock_get):
+ mock_get.side_effect = requests.ConnectionError("down")
+ with pytest.raises(PubChemAPIError):
+ cactus.resolve_to_sdf("aspirin")
+
+ @rdkit_only
+ @patch("quantui.cactus.requests.get")
+ def test_fetch_from_cactus_returns_xyz(self, mock_get, sample_sdf_water):
+ mock_get.return_value = Mock(status_code=200, text=sample_sdf_water)
+ xyz, meta = cactus.fetch_from_cactus("water")
+ assert meta["source"] == "cactus"
+ assert meta["num_atoms"] == 3
+
+
+# ============================================================================
+# STRUCT.4 — provider chain ordering
+# ============================================================================
+
+
+class TestProviderChain:
+ @rdkit_only
+ @patch("quantui.pubchem.requests.get")
+ def test_smiles_resolves_locally_no_network(self, mock_get):
+ mock_get.side_effect = AssertionError("network must not be touched")
+ result = resolve_structure("CC(=O)O")
+ assert isinstance(result, ResolvedStructure)
+ assert result.source == "rdkit-smiles"
+ assert result.is_offline is True
+ mock_get.assert_not_called()
+
+ @patch("quantui.structure_providers.fetch_structure")
+ def test_exact_library_hit_short_circuits_network(self, mock_fetch):
+ mock_fetch.side_effect = AssertionError("library hit must not hit network")
+ result = resolve_structure("H2O") # exact MOLECULE_LIBRARY key
+ assert result.source == "library"
+ assert result.formula == "H2O"
+ assert result.num_atoms == 3
+ mock_fetch.assert_not_called()
+
+ @patch("quantui.structure_providers.fetch_structure")
+ def test_name_resolves_via_pubchem(self, mock_fetch):
+ mock_fetch.return_value = (_WATER_XYZ, dict(_WATER_META))
+ result = resolve_structure("dihydrogen monoxide")
+ assert result.source == "pubchem"
+ mock_fetch.assert_called_once()
+
+ @patch("quantui.structure_providers.cactus.fetch_from_cactus")
+ @patch("quantui.structure_providers.fetch_structure")
+ def test_pubchem_miss_falls_through_to_cactus(self, mock_fetch, mock_cactus):
+ mock_fetch.side_effect = MoleculeNotFoundError("pubchem miss")
+ mock_cactus.return_value = (_WATER_XYZ, {**_WATER_META, "source": "cactus"})
+ result = resolve_structure("64-19-7") # a CAS number
+ assert result.source == "cactus"
+ mock_fetch.assert_called_once()
+ mock_cactus.assert_called_once()
+
+ @patch("quantui.structure_providers.cactus.fetch_from_cactus")
+ @patch("quantui.structure_providers.fetch_structure")
+ def test_network_down_uses_offline_fuzzy_fallback(self, mock_fetch, mock_cactus):
+ mock_fetch.side_effect = PubChemAPIError("network down")
+ mock_cactus.side_effect = PubChemAPIError("network down")
+ # "water" isn't an exact key but appears in the H2O entry description.
+ result = resolve_structure("water")
+ assert result.source == "library-offline-fallback"
+ assert result.formula == "H2O"
+
+ @patch("quantui.structure_providers.cactus.fetch_from_cactus")
+ @patch("quantui.structure_providers.fetch_structure")
+ def test_total_miss_raises(self, mock_fetch, mock_cactus):
+ mock_fetch.side_effect = MoleculeNotFoundError("miss")
+ mock_cactus.side_effect = MoleculeNotFoundError("miss")
+ with pytest.raises(MoleculeNotFoundError):
+ resolve_structure("zzqxnotarealmolecule")
+
+ @patch("quantui.structure_providers.fetch_structure")
+ def test_allow_network_false_skips_resolvers(self, mock_fetch):
+ mock_fetch.side_effect = AssertionError("network disabled")
+ result = resolve_structure("water", allow_network=False)
+ assert result.source == "library-offline-fallback"
+ mock_fetch.assert_not_called()
+
+
+# ============================================================================
+# STRUCT.4 — friendly wrapper messaging
+# ============================================================================
+
+
+class TestFriendlyResolve:
+ def test_library_message_mentions_offline(self):
+ xyz, msg = student_friendly_resolve("H2O")
+ assert xyz is not None
+ assert "bundled library (offline)" in msg
+ assert "H2O" in msg
+
+ @patch("quantui.structure_providers.cactus.fetch_from_cactus")
+ @patch("quantui.structure_providers.fetch_structure")
+ def test_offline_fallback_message(self, mock_fetch, mock_cactus):
+ mock_fetch.side_effect = PubChemAPIError("down")
+ mock_cactus.side_effect = PubChemAPIError("down")
+ xyz, msg = student_friendly_resolve("water")
+ assert xyz is not None
+ assert "offline fallback" in msg
+
+ @patch("quantui.structure_providers.cactus.fetch_from_cactus")
+ @patch("quantui.structure_providers.fetch_structure")
+ def test_not_found_message(self, mock_fetch, mock_cactus):
+ mock_fetch.side_effect = MoleculeNotFoundError("miss")
+ mock_cactus.side_effect = MoleculeNotFoundError("miss")
+ xyz, msg = student_friendly_resolve("zzqxnotreal")
+ assert xyz is None
+ assert "Could not resolve" in msg
diff --git a/tests/test_struct_resolver.py b/tests/test_struct_resolver.py
new file mode 100644
index 0000000..99811b7
--- /dev/null
+++ b/tests/test_struct_resolver.py
@@ -0,0 +1,295 @@
+"""Tests for M-STRUCT STRUCT.1 (input-type routing) + STRUCT.2 (hardened client).
+
+All tests are platform-independent: network is mocked, RDKit-only paths are
+gated. No PySCF dependency.
+"""
+
+from unittest.mock import Mock, patch
+
+import pytest
+import requests
+
+from quantui import config
+from quantui.pubchem import (
+ RDKIT_AVAILABLE,
+ MoleculeNotFoundError,
+ PubChemAPIError,
+ classify_query,
+ fetch_structure,
+ get_molecule_sdf,
+ search_cid_by_inchikey,
+ search_molecule_by_name,
+ student_friendly_resolve,
+)
+
+rdkit_only = pytest.mark.skipif(not RDKIT_AVAILABLE, reason="rdkit not installed")
+
+
+# ============================================================================
+# STRUCT.1 — classify_query routing
+# ============================================================================
+
+
+class TestClassifyQuery:
+ @pytest.mark.parametrize(
+ "query,expected",
+ [
+ ("962", "cid"),
+ ("CID962", "cid"),
+ ("cid: 2244", "cid"),
+ ("InChI=1S/H2O/h1H2", "inchi"),
+ ("XLYOFNOQVPJJNP-UHFFFAOYSA-N", "inchikey"), # water InChIKey
+ ("CC(=O)O", "smiles"), # acetic acid — structural chars
+ ("c1ccccc1", "smiles"), # benzene — aromatic + ring digit
+ ("[OH3+]", "smiles"), # hydronium — brackets + charge
+ ("H2O", "formula"), # digit but not valid SMILES
+ ("C6H6", "formula"),
+ ("Fe", "formula"),
+ ("water", "name"),
+ ("carbon dioxide", "name"), # space → never SMILES
+ ("acetylsalicylic acid", "name"),
+ ],
+ )
+ def test_classification(self, query, expected):
+ # SMILES classification needs RDKit to validate; skip those when absent.
+ if expected == "smiles" and not RDKIT_AVAILABLE:
+ pytest.skip("rdkit not installed")
+ assert classify_query(query) == expected
+
+ def test_empty_query_raises(self):
+ with pytest.raises(ValueError):
+ classify_query(" ")
+
+ @rdkit_only
+ def test_bare_letter_smiles_routes_to_name_not_smiles(self):
+ # "CCO" is valid SMILES *and* a plausible token; we deliberately leave
+ # it to the (future) provider chain rather than misroute a name.
+ assert classify_query("CCO") in ("formula", "name")
+
+
+# ============================================================================
+# STRUCT.2 — URL encoding
+# ============================================================================
+
+
+class TestUrlEncoding:
+ @patch("quantui.pubchem.requests.get")
+ def test_name_with_space_is_encoded(self, mock_get):
+ mock_get.return_value = Mock(
+ status_code=200, json=Mock(return_value={"IdentifierList": {"CID": [280]}})
+ )
+ search_molecule_by_name("carbon dioxide")
+ url = mock_get.call_args[0][0]
+ assert "carbon%20dioxide" in url
+ assert " " not in url
+
+ @patch("quantui.pubchem.requests.get")
+ def test_inchikey_endpoint_encoded(self, mock_get):
+ mock_get.return_value = Mock(
+ status_code=200, json=Mock(return_value={"IdentifierList": {"CID": [962]}})
+ )
+ cid = search_cid_by_inchikey("XLYOFNOQVPJJNP-UHFFFAOYSA-N")
+ assert cid == 962
+ assert "compound/inchikey/" in mock_get.call_args[0][0]
+
+
+# ============================================================================
+# STRUCT.2 — throttle / 503 back-off
+# ============================================================================
+
+
+class TestThrottleBackoff:
+ @patch("quantui.pubchem.time.sleep") # don't actually sleep
+ @patch("quantui.pubchem.requests.get")
+ def test_503_then_success_retries(self, mock_get, mock_sleep):
+ resp_503 = Mock(status_code=503)
+ resp_ok = Mock(
+ status_code=200, json=Mock(return_value={"IdentifierList": {"CID": [962]}})
+ )
+ mock_get.side_effect = [resp_503, resp_ok]
+
+ cid = search_molecule_by_name("water")
+ assert cid == 962
+ assert mock_get.call_count == 2 # one retry after the 503
+ assert mock_sleep.called # backed off between attempts
+
+ @patch("quantui.pubchem.time.sleep")
+ @patch("quantui.pubchem.requests.get")
+ def test_persistent_503_exhausts_retries_then_errors(self, mock_get, mock_sleep):
+ resp_503 = Mock(status_code=503)
+ resp_503.raise_for_status.side_effect = requests.HTTPError("503")
+ mock_get.return_value = resp_503
+
+ with pytest.raises(PubChemAPIError):
+ search_molecule_by_name("water")
+ # Tried the full retry budget, then gave up.
+ assert mock_get.call_count == config.PUBCHEM_MAX_RETRIES
+ # Backed off at least once between attempts (sleep is also used by the
+ # rate-limiter, so assert "happened" rather than an exact count).
+ assert mock_sleep.called
+
+ @patch("quantui.pubchem.requests.get")
+ def test_non_503_not_retried(self, mock_get):
+ # A 500 must surface immediately, not trigger the 503 retry loop.
+ resp = Mock(status_code=500)
+ resp.raise_for_status.side_effect = requests.HTTPError("500")
+ mock_get.return_value = resp
+ with pytest.raises(PubChemAPIError):
+ search_molecule_by_name("water")
+ assert mock_get.call_count == 1
+
+
+# ============================================================================
+# STRUCT.1 — fetch_structure routing (local vs network)
+# ============================================================================
+
+
+class TestFetchStructureRouting:
+ @rdkit_only
+ @patch("quantui.pubchem.requests.get")
+ def test_smiles_resolves_locally_without_network(self, mock_get):
+ mock_get.side_effect = AssertionError("network must not be touched for SMILES")
+ xyz, meta = fetch_structure("CC(=O)O") # acetic acid
+ assert meta["source"] == "rdkit-smiles"
+ assert meta["conformer_origin"] == "rdkit-embedded"
+ assert meta["formula"] == "C2H4O2"
+ assert xyz.strip().splitlines()[0].strip() == str(meta["num_atoms"])
+ mock_get.assert_not_called()
+
+ @rdkit_only
+ @patch("quantui.pubchem.requests.get")
+ def test_inchi_resolves_locally_without_network(self, mock_get):
+ mock_get.side_effect = AssertionError("network must not be touched for InChI")
+ xyz, meta = fetch_structure("InChI=1S/H2O/h1H2") # water
+ assert meta["source"] == "rdkit-inchi"
+ assert meta["num_heavy_atoms"] == 1
+ mock_get.assert_not_called()
+
+ @rdkit_only
+ @patch("quantui.pubchem.search_cid_by_inchikey")
+ @patch("quantui.pubchem.get_molecule_sdf")
+ def test_inchikey_routes_through_network(
+ self, mock_sdf, mock_inchikey, sample_sdf_water
+ ):
+ mock_inchikey.return_value = 962
+ mock_sdf.return_value = sample_sdf_water
+ xyz, meta = fetch_structure("XLYOFNOQVPJJNP-UHFFFAOYSA-N")
+ mock_inchikey.assert_called_once()
+ assert meta["source"] == "pubchem"
+ assert meta["pubchem_cid"] == 962
+ assert meta["conformer_origin"] in ("pubchem", "rdkit-embedded")
+
+ @rdkit_only
+ @patch("quantui.pubchem.get_molecule_sdf")
+ @patch("quantui.pubchem.search_molecule_by_name")
+ def test_name_routes_through_pubchem(self, mock_search, mock_sdf, sample_sdf_water):
+ mock_search.return_value = 962
+ mock_sdf.return_value = sample_sdf_water
+ _, meta = fetch_structure("water")
+ mock_search.assert_called_once_with("water")
+ assert meta["source"] == "pubchem"
+ assert meta["query_type"] == "name"
+
+
+# ============================================================================
+# STRUCT.1/.2 — student-friendly wrapper
+# ============================================================================
+
+
+class TestStudentFriendlyResolve:
+ @rdkit_only
+ def test_smiles_success_message(self):
+ # Use an unambiguous SMILES (structural chars) so it resolves locally
+ # with no network. Bare-letter tokens like "CCO" classify as
+ # formula/name by design and are left to the provider chain.
+ xyz, msg = student_friendly_resolve("CC(=O)O")
+ assert xyz is not None
+ assert "generated locally from SMILES" in msg
+ assert "C2H4O2" in msg
+
+ @patch("quantui.pubchem.fetch_structure")
+ def test_not_found_message(self, mock_fetch):
+ mock_fetch.side_effect = MoleculeNotFoundError("nope")
+ xyz, msg = student_friendly_resolve("zzxqq")
+ assert xyz is None
+ assert "Could not resolve" in msg
+
+ @patch("quantui.pubchem.fetch_structure")
+ def test_api_error_message(self, mock_fetch):
+ mock_fetch.side_effect = PubChemAPIError("down")
+ xyz, msg = student_friendly_resolve("water")
+ assert xyz is None
+ assert "Connection to PubChem failed" in msg
+
+
+# ============================================================================
+# STRUCT.2 — sdf_to_xyz provenance flag (regression guard)
+# ============================================================================
+
+
+class TestCoordsEmbeddedFlag:
+ @rdkit_only
+ def test_sdf_with_3d_coords_not_flagged_embedded(self, sample_sdf_water):
+ from quantui.pubchem import sdf_to_xyz
+
+ get_molecule_sdf.cache_clear()
+ _, meta = sdf_to_xyz(sample_sdf_water)
+ assert "coords_embedded" in meta
+ # The fixture SDF already carries 3D coords, so RDKit should not embed.
+ assert meta["coords_embedded"] is False
+
+ @rdkit_only
+ def test_2d_sdf_is_reembedded_to_3d_no_atoms_piled(self):
+ """STRUCT.12 regression: a 2D SDF (H added without coords in the old
+ code piled them at the origin → 'valence 13') must come back as a real
+ 3D structure with every atom at a distinct position."""
+ import math
+
+ from rdkit import Chem
+ from rdkit.Chem import AllChem
+
+ from quantui.pubchem import sdf_to_xyz
+
+ m = Chem.MolFromSmiles("CCO") # ethanol, no explicit H
+ AllChem.Compute2DCoords(m) # 2D conformer, flagged 2D
+ sdf_2d = Chem.MolToMolBlock(m)
+
+ xyz, meta = sdf_to_xyz(sdf_2d)
+ assert meta["coords_embedded"] is True # we re-embedded the 2D input
+
+ coords = [
+ [float(c) for c in line.split()[1:4]]
+ for line in xyz.strip().splitlines()[2:]
+ ]
+ assert len(coords) == meta["num_atoms"] == 9 # C2H6O
+ # No two atoms coincide (the old bug piled all H at 0,0,0).
+ for i in range(len(coords)):
+ for j in range(i + 1, len(coords)):
+ d = math.dist(coords[i], coords[j])
+ assert d > 0.5, f"atoms {i},{j} only {d:.3f} Å apart"
+ # Genuinely 3D, not flat.
+ assert max(abs(c[2]) for c in coords) > 1e-3
+
+
+class TestSaltFragmentSeparation:
+ """STRUCT.14 regression: a salt's counterion must not embed jammed into the
+ cation (RDKit otherwise places it ~1.4 Å away → bond perception reads it as
+ a bonded, hypervalent atom and the renderer rejects it, e.g. methylene
+ blue)."""
+
+ @rdkit_only
+ def test_counterion_is_separated(self):
+ import math
+
+ from quantui.pubchem import smiles_to_xyz
+
+ # Ammonium chloride: [NH4+] cation + Cl- counterion (two fragments).
+ xyz, meta = smiles_to_xyz("[NH4+].[Cl-]")
+ atoms = [
+ (line.split()[0], [float(c) for c in line.split()[1:4]])
+ for line in xyz.strip().splitlines()[2:]
+ ]
+ cl = next(p for sym, p in atoms if sym == "Cl")
+ nearest = min(math.dist(cl, p) for sym, p in atoms if sym != "Cl")
+ # A real bond is ~1.3-2.0 Å; the separated counterion must be well beyond.
+ assert nearest > 2.5, f"Cl- only {nearest:.2f} Å from the cation"
diff --git a/tests/test_struct_ui.py b/tests/test_struct_ui.py
new file mode 100644
index 0000000..b537f64
--- /dev/null
+++ b/tests/test_struct_ui.py
@@ -0,0 +1,115 @@
+"""Tests for the library browse/search UI (M-STRUCT STRUCT.9).
+
+Instantiates QuantUIApp() headlessly (no .display()) and drives the library
+widgets + handlers directly. Platform-independent; no PySCF.
+"""
+
+import ipywidgets as widgets
+
+from quantui import molecule_library as ml
+from quantui.app import QuantUIApp
+from quantui.app_builders import library_result_options
+
+# ============================================================================
+# library_result_options helper
+# ============================================================================
+
+
+class TestLibraryResultOptions:
+ def test_leads_with_placeholder(self):
+ opts, _ = library_result_options()
+ assert opts[0][1] == "" # placeholder value is empty
+
+ def test_category_filter(self):
+ opts, _ = library_result_options(category="amino-acid")
+ ids = [v for _, v in opts if v]
+ assert len(ids) == 20
+
+ def test_search_by_formula(self):
+ opts, _ = library_result_options(query="C6H6")
+ ids = [v for _, v in opts if v]
+ assert "C6H6" in ids
+
+ def test_note_reports_count(self):
+ _, note = library_result_options(category="aromatic")
+ assert "1 match" in note
+
+ def test_note_reports_truncation(self):
+ _, note = library_result_options() # all categories → > 200
+ assert "first 200" in note
+
+
+# ============================================================================
+# Widgets exist + are wired
+# ============================================================================
+
+
+class TestLibraryWidgets:
+ def test_library_widgets_exist(self):
+ app = QuantUIApp()
+ assert isinstance(app.lib_category_dd, widgets.Dropdown)
+ assert isinstance(app.lib_search_txt, widgets.Text)
+ assert isinstance(app.lib_results_dd, widgets.Dropdown)
+ assert isinstance(app.lib_count_lbl, widgets.HTML)
+
+ def test_category_dropdown_lists_categories(self):
+ app = QuantUIApp()
+ values = [v for _, v in app.lib_category_dd.options]
+ assert "" in values # "All categories"
+ for cat in ml.categories():
+ assert cat in values
+
+ def test_search_text_is_not_continuous(self):
+ app = QuantUIApp()
+ assert app.lib_search_txt.continuous_update is False
+
+
+# ============================================================================
+# Handlers
+# ============================================================================
+
+
+class TestLibraryHandlers:
+ def test_select_loads_molecule(self):
+ app = QuantUIApp()
+ assert app._molecule is None
+ app._on_lib_select({"new": "aspirin"})
+ assert app._molecule is not None
+ assert app._molecule.get_formula() == "C9H8O4"
+
+ def test_select_placeholder_is_noop(self):
+ app = QuantUIApp()
+ app._on_lib_select({"new": ""})
+ assert app._molecule is None
+
+ def test_select_ignored_during_refresh(self):
+ app = QuantUIApp()
+ app._lib_refreshing = True
+ app._on_lib_select({"new": "aspirin"})
+ assert app._molecule is None
+
+ def test_filter_change_repopulates_results(self):
+ app = QuantUIApp()
+ app.lib_category_dd.value = "amino-acid"
+ app._on_lib_filter_changed({"new": "amino-acid"})
+ ids = [v for _, v in app.lib_results_dd.options if v]
+ assert len(ids) == 20
+ assert app.lib_results_dd.value == "" # reset to placeholder, no load
+ assert app._molecule is None
+
+ def test_search_then_select_bulk_entry(self):
+ app = QuantUIApp()
+ # Pick any bulk id from the store and confirm it loads via the handler.
+ bulk = ml.search("", category="bulk-qm9", limit=1)
+ if not bulk:
+ return # bulk not built in this checkout
+ bulk_id = bulk[0]["id"]
+ app._on_lib_select({"new": bulk_id})
+ assert app._molecule is not None
+ assert len(app._molecule.atoms) >= 1
+
+ def test_refresh_updates_count_label(self):
+ app = QuantUIApp()
+ app.lib_category_dd.value = "aromatic"
+ app._refresh_lib_results()
+ assert "1 match" in app.lib_count_lbl.value