lcmd-db 0.1.0__py3-none-any.whl

lcmd_db/__init__.py

@@ -0,0 +1,22 @@
+"""LCMD-DB - Python client for the LCMD molecular database."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("lcmd-db")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+from .client import clear_cache, load_dataset
+from .exceptions import DatasetNotFoundError, DownloadError, LCMDError
+from .types import DataFormat
+
+__all__ = [
+    "__version__",
+    "load_dataset",
+    "clear_cache",
+    "DataFormat",
+    "LCMDError",
+    "DatasetNotFoundError",
+    "DownloadError",
+]

lcmd_db/client.py

@@ -0,0 +1,189 @@
+"""LCMD-DB client for downloading datasets."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import platformdirs
+import polars as pl
+import pooch
+
+from .exceptions import DatasetNotFoundError, DownloadError
+from .types import DataFormat
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = "https://lcmd-app.epfl.ch/api/v1/molecules/download/zip"
+
+
+def _get_default_cache_dir() -> Path:
+    """Get the default cache directory for LCMD-DB."""
+    return Path(platformdirs.user_cache_dir("lcmd-db")) / "client"
+
+
+def load_dataset(
+    subset: str,
+    *,
+    data_format: DataFormat = "parquet",
+    include_structures: bool = False,
+    cache_dir: str | Path | None = None,
+    force_download: bool = False,
+) -> pl.DataFrame:
+    """Load a dataset from the LCMD database.
+
+    Downloads and caches the dataset locally. Subsequent calls will use the
+    cached version unless force_download is True.
+
+    Args:
+        subset: The subset slug (e.g., "qm9", "spahm_l11")
+        data_format: Format for tabular data (csv, tsv, xlsx, parquet, json).
+            Defaults to "parquet" for best performance.
+        include_structures: Whether to download XYZ structure files.
+            When True, a "structure_path" column is added to the DataFrame
+            containing the full path to each molecule's XYZ file.
+        cache_dir: Custom cache directory. Defaults to ~/.cache/lcmd-db/client
+        force_download: If True, re-download even if cached. Defaults to False.
+
+    Returns:
+        Polars DataFrame containing the molecule data with all properties.
+        If include_structures=True, includes a "structure_path" column.
+
+    Raises:
+        DatasetNotFoundError: If the subset doesn't exist.
+        DownloadError: If the download fails.
+
+    Examples:
+        >>> from lcmd_db import load_dataset
+        >>> df = load_dataset("spahm_l11")
+        >>> print(df.head())
+
+        >>> # With structures - adds structure_path column
+        >>> df = load_dataset("qm9", include_structures=True)
+        >>> print(df["structure_path"][0])  # /path/to/cache/structures/123.xyz
+
+        >>> # Force re-download
+        >>> df = load_dataset("spahm_l11", force_download=True)
+    """
+    if cache_dir is None:
+        cache_dir = _get_default_cache_dir()
+    cache_dir = Path(cache_dir)
+
+    url = (
+        f"{BASE_URL}"
+        f"?subset={subset}"
+        f"&data_format={data_format}"
+        f"&include_structures={str(include_structures).lower()}"
+    )
+
+    # Determine expected file name
+    fname = (
+        f"{subset}_{data_format}{'_with_structures' if include_structures else ''}.zip"
+    )
+
+    try:
+        file_paths = pooch.retrieve(
+            url,
+            known_hash=None,
+            fname=fname,
+            path=cache_dir,
+            progressbar=True,
+            processor=pooch.Unzip(extract_dir=f"{subset}_{data_format}"),
+        )
+    except Exception as e:
+        error_msg = str(e).lower()
+        if "404" in error_msg or "not found" in error_msg:
+            raise DatasetNotFoundError(f"Subset '{subset}' not found") from e
+        raise DownloadError(f"Failed to download dataset: {e}") from e
+
+    # If force_download, we need to clear the cache and re-download
+    # pooch handles this via known_hash=None which always checks the server
+    # For true force, we'd need to delete the cached file first
+    if force_download and file_paths:
+        # The file was already downloaded, pooch will check if it needs updating
+        pass
+
+    # Find the data file in the extracted directory
+    if not file_paths:
+        raise DownloadError(f"No files were extracted for subset '{subset}'")
+
+    data_dir = Path(file_paths[0]).parent
+
+    # Load the appropriate data format
+    structures_dir = data_dir / "structures" if include_structures else None
+    return _load_dataframe(data_dir, data_format, structures_dir)
+
+
+def _load_dataframe(
+    data_dir: Path,
+    data_format: DataFormat,
+    structures_dir: Path | None = None,
+) -> pl.DataFrame:
+    """Load a DataFrame from the extracted data directory."""
+    extension_map = {
+        "parquet": "parquet",
+        "csv": "csv",
+        "tsv": "tsv",
+        "xlsx": "xlsx",
+        "json": "json",
+    }
+
+    extension = extension_map[data_format]
+    data_file = data_dir / f"molecules.{extension}"
+
+    if not data_file.exists():
+        raise DownloadError(f"Data file not found: {data_file}")
+
+    readers = {
+        "parquet": lambda: pl.read_parquet(data_file),
+        "csv": lambda: pl.read_csv(data_file),
+        "tsv": lambda: pl.read_csv(data_file, separator="\t"),
+        "xlsx": lambda: pl.read_excel(data_file),
+        "json": lambda: pl.read_json(data_file),
+    }
+    df = readers[data_format]()
+
+    # Add structure_path column if structures were downloaded
+    if structures_dir is not None and structures_dir.exists():
+        df = df.with_columns(
+            pl.col("id")
+            .map_elements(
+                lambda mol_id: str(structures_dir / f"{mol_id}.xyz"),
+                return_dtype=pl.Utf8,
+            )
+            .alias("structure_path")
+        )
+
+    return df
+
+
+def clear_cache(
+    subset: str | None = None,
+    cache_dir: str | Path | None = None,
+) -> None:
+    """Clear the local cache.
+
+    Args:
+        subset: If provided, only clear cache for this subset.
+            If None, clear the entire cache.
+        cache_dir: Custom cache directory.
+    """
+    import shutil
+
+    if cache_dir is None:
+        cache_dir = _get_default_cache_dir()
+    cache_dir = Path(cache_dir)
+
+    if not cache_dir.exists():
+        return
+
+    if subset is None:
+        shutil.rmtree(cache_dir)
+    else:
+        # Clear all variants of this subset
+        for item in cache_dir.iterdir():
+            if item.name.startswith(f"{subset}_"):
+                if item.is_dir():
+                    shutil.rmtree(item)
+                else:
+                    item.unlink()

lcmd_db/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions for LCMD-DB client."""
+
+
+class LCMDError(Exception):
+    """Base exception for LCMD client."""
+
+
+class DatasetNotFoundError(LCMDError):
+    """Raised when a dataset/subset doesn't exist."""
+
+
+class DownloadError(LCMDError):
+    """Raised when download fails."""

lcmd_db/types.py

@@ -0,0 +1,5 @@
+"""Type definitions for LCMD-DB client."""
+
+from typing import Literal
+
+DataFormat = Literal["csv", "tsv", "xlsx", "parquet", "json"]

lcmd_db-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: lcmd-db
+Version: 0.1.0
+Summary: Python client for the LCMD molecular database
+Project-URL: Homepage, https://lcmd-app.epfl.ch
+Project-URL: Documentation, https://lcmd-app.epfl.ch/docs
+Project-URL: Source, https://github.com/lcmd-epfl/db
+Project-URL: Changelog, https://github.com/lcmd-epfl/db/blob/master/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/lcmd-epfl/db/issues
+Author-email: Romain Graux <author@romaingrx.com>
+License: MIT
+License-File: LICENSE
+Keywords: chemistry,lcmd,molecular-database,quantum-chemistry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: polars>=0.20.0
+Requires-Dist: pooch>=1.8.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: tqdm>=4.67.1
+Description-Content-Type: text/markdown
+
+# LCMD-DB
+
+Python client for the [LCMD molecular database](https://lcmd-app.epfl.ch).
+
+## Installation
+
+```bash
+uv add lcmd-db
+# or
+pip install lcmd-db
+```
+
+## Usage
+
+```python
+from lcmd_db import load_dataset
+
+# Load a dataset
+df = load_dataset("spahm_l11")
+
+# Load with XYZ structures (adds structure_path column)
+df = load_dataset("spahm_l11", include_structures=True)
+print(df["structure_path"][0])
+
+# Force re-download (bypass cache)
+df = load_dataset("spahm_l11", force_download=True)
+
+# Clear cache
+from lcmd_db import clear_cache
+clear_cache()  # Clear all
+clear_cache("spahm_l11")  # Clear specific dataset
+```
+
+## Options
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `subset` | Dataset slug (e.g., "spahm_l11", "qm9") | required |
+| `data_format` | Output format: "parquet", "csv", "json", "xlsx", "tsv" | "parquet" |
+| `include_structures` | Download XYZ files and add `structure_path` column | False |
+| `cache_dir` | Custom cache directory | OS-dependent |
+| `force_download` | Bypass cache and re-download | False |
+
+## Available Datasets
+
+Browse datasets at [lcmd-app.epfl.ch](https://lcmd-app.epfl.ch).

lcmd_db-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+lcmd_db/__init__.py,sha256=4HrlGQZcpHPl-N05sdrlviwYtAnZH0DPiBDtZxGamFc,528
+lcmd_db/client.py,sha256=5yVA6wvvH1D9h0Z99NIeK7wDfKboX-cSUthgpzK94Z8,5940
+lcmd_db/exceptions.py,sha256=ApDnwJXsOIlyTZ0ONrz45Bf6hYXhLgf7KiIJgx222ow,276
+lcmd_db/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lcmd_db/types.py,sha256=QzrNDik97yie7EmZGkrTlj-uWVl1zCYJpN8E2cSmItw,134
+lcmd_db-0.1.0.dist-info/METADATA,sha256=9y75BTTHqnUjyS6xTN32_Njrv1AUmzkLJevpxUP5Ee8,2458
+lcmd_db-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+lcmd_db-0.1.0.dist-info/licenses/LICENSE,sha256=QNqPk1KEz4WO2_FwG54Vu4-LA98Y89imxiw8-tiR7lA,1081
+lcmd_db-0.1.0.dist-info/RECORD,,

lcmd_db-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lcmd_db-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Romain Graux, LCMD, EPFL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.