lcmd-db 0.4.0

Python client for the LCMD molecular database — typed access to molecules, reactions, fragments, and assembly templates

LCMD-DB

Python client for the LCMD molecular database.

Installation

uv add lcmd-db
# or
pip install lcmd-db

Quick start

from lcmd_db import load_dataset, load_molecules

# Load a subset (molecules included by default)
data = load_dataset("qm9")
data.molecules  # polars DataFrame

# Include multiple entity types
data = load_dataset("qm9", include=["molecules", "reactions", "fragments"])

# Include XYZ structure files
data = load_dataset("qm9", include_structures=True)

# Select specific properties
data = load_dataset("qm9", molecule_properties=["smiles", "energy"])

# Filter molecules server-side with SMARTS
data = load_dataset("formed", include=["molecules"], smarts="[OX2H]")

# Search molecules directly across the database
molecules = load_molecules(smarts="[OX2H]", smiles="CO")

# Choose output format
data = load_dataset("qm9", data_format="csv")

# Force re-download (bypass cache)
data = load_dataset("qm9", force_download=True)

Dataset API

load_dataset returns a SubsetData object containing polars DataFrames for each entity type. Convert it to a typed Dataset for lazy loading, filtering, and indexing:

data = load_dataset("qm9")

# Get a typed, iterable Dataset
molecules = data.as_dataset("molecules")

# Index and iterate
mol = molecules[0]          # Molecule(id=..., properties={...})
batch = molecules[10:20]    # Dataset slice

# Filter with polars expressions
import polars as pl
heavy = molecules.filter(pl.col("molecular_weight") > 100)

# Select specific columns
subset = molecules.select("smiles", "energy")

# Train/test split
train, test = molecules.train_test_split(test_size=0.2, seed=42)

# Export
df = molecules.to_polars()
pdf = molecules.to_pandas()
atoms = molecules.to_ase()   # requires ase

CLI

# Download a dataset
lcmd-db download qm9
lcmd-db download qm9 --include molecules --include structures
lcmd-db download formed --include molecules --smarts "[OX2H]"
lcmd-db download qm9 -f csv --force

# Browse available schemas
lcmd-db schema list
lcmd-db schema show qm9

# Manage cache
lcmd-db cache clear
lcmd-db cache clear qm9

# Sync type stubs for autocomplete
lcmd-db stubs sync

Configuration

Settings are controlled via environment variables (prefix LCMD_DB_) or programmatically:

Variable	Description	Default
LCMD_DB_BASE_URL	API base URL	https://lcmd-app.epfl.ch
LCMD_DB_CACHE_DIR	Cache directory	OS-dependent
LCMD_DB_TIMEOUT	Download timeout (seconds)	300
LCMD_DB_AUTO_SYNC_STUBS	Auto-sync type stubs on import	true

from lcmd_db import settings

settings.base_url = "https://custom-instance.example.com"