chem-db-mof

Files (8)

• SKILL.md
• README.md · examples/arcmof_db7_ddmof_559/
• arcmof_geometric_properties_ddmof_559.csv · examples/arcmof_db7_ddmof_559/
• ddmof_559.cif · examples/arcmof_db7_ddmof_559/
• input_configs.yaml · examples/arcmof_db7_ddmof_559/
• majumdar_metadata.csv · examples/arcmof_db7_ddmof_559/
• validation.json · examples/arcmof_db7_ddmof_559/
• query_mof_db.py · scripts/

SKILL.md (first lines)

# chem-db-mof

## Goal

Provide a unified interface for retrieving Metal-Organic Framework (MOF) crystal structures from multiple curated databases. Currently supported:

| Database | Alias | Size | Access | Structures |
|---|---|---|---|---|
| Quantum MOF (QMOF) | `qmof` | ~20,000 DFT-relaxed | MPContribs API | DFT-optimized CIFs + bandgaps |
| ARC-MOF DB7 (Majumdar et al.) | `arcmof-majumdar` | 23,891 hypothetical (`ddmof_1`–`ddmof_23891`) | Materials Cloud archive | CIFs with EQeq partial charges + `mof_data.csv` metadata |

## Prerequisites

- **Environment**: `cpu` (commands run through `venv/run cpu ...`)
- **Packages**: `mpcontribs-client`, `requests`, `pandas`, `pymatgen`
- **Credentials**: `MP_API_KEY` environment variable (required for `qmof` only)

## Instructions

### Step 1: Choose a database and set filters

Decide which database to query and which element/identifier filters to apply.

**For QMOF** — best for DFT-validated, experimentally-derived MOFs:
- Use `--formula` for element filtering (e.g., `Zn` or `Cu,N,O`)
- Use `--identifier` for a specific CSD refcode (e.g., `KAXQIL`)

**For ARC-MOF DB7 (Majumdar et al.)** — best for diverse hypothetical MOFs with underrepresented inorganic SBUs:
- Use `--elements` for element filtering (e.g., `Zn`, or `Zn,F` for fluorinated Zn MOFs); by default every listed element must be present, while `--element-match any` keeps structures containing at least one of them
- Use `--identifier` for a specific structure name (e.g., `ddmof_559`); a full name matches exactly, anything else matches as a substring
- **First run**: downloads the Majumdar archive `mof_data.tar.gz` (~149 MB) from Materials Cloud to `~/.cache/arcmof/` — one-time only; subsequent runs are fast

### Step 2: Run the query

```bash
# QMOF — 10 Zn-containing MOFs
MP_API_KEY=<your_key> ${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/query_mof_db.py \
    --database qmof \
    --formula Zn \
    --max-results 10 \
    --output-dir ./research/<date>_<task>/structures/qmof
```

```bash
# ARC-MOF DB7 (Majumdar) — 20 Zn-containing hypothetical MOFs
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/query_mof_db.py \
    --database arcmof-majumdar \
    --elements Zn \
    --max-results 20 \
    --output-dir ./research/<date>_<task>/structures/arcmof_db7
```

```bash
# ARC-MOF DB7 — retrieve a specific structure by identifier
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/query_mof_db.py \
    --database arcmof-majumdar \
    --identifier ddmof_559 \
    --output-dir ./research/<date>_<task>/structures/arcmof_db7
```

### Available Arguments

| Argument | Applies to | Description |
|---|---|---|
| `--database` | both | `qmof` or `arcmof-majumdar` |
| `--formula` | qmof | Element/formula filter string (e.g., `Zn,O,C`) |
| `--elements` | arcmof-majumdar | Comma-separated elements; by default a structure must contain ALL of them |
| `--element-match` | arcmof-majumdar | `all` (default) or `any` (keep structures containing at least one listed element, e.g. a mixed-metal screening set) |
| `--identifier` | both | Specific structure name or ID substring |
| `--max-results` | both | Max CIFs to download (default: 10) |
| `--output-dir` | both | Directory for output CIF files |
| `--cache-dir` | arcmof-majumdar | Override default cache `~/.cache/arcmof/` |

### Step 3: Inspect outputs

The script saves:
- Individual `.cif` files named by structure identifier
- `majumdar_metadata.csv` (ARC-MOF only) — Majumdar `mof_data.csv` rows (building blocks, topology, volume, density, CO2 uptake) for the downloaded subset

Verify the download:
```bash
ls -lh <output-dir>/*.cif | head -20
```

## Download Behavior: ARC-MOF DB7

The first call with `--database arcmof-majumdar` performs:

1. **Archive download** (~149 MB, one-time): the Majumdar et al. `mof_data.tar.gz` from Materials Cloud (DOI 10.24435/materialscloud:yn-de), cached at `~/.cache/arcmof/majumdar_mof_data.tar.gz`
2. **Metadata**: `mof_data.csv` inside the archive lists all 23,891 structures with their building blocks and properties
3. **CIF extraction**: the nested `mof_structures.tar` is read sequentially and only the CIFs that pass the identifier/metal filters are written to disk; an exact `--identifier` stops at the first hit

Subsequent runs with the same `--output-dir` skip already-downloaded CIFs.

## Examples

**Literature-validated example: ARC-MOF DB7 `ddmof_559`** (the top post-combustion CO₂ MOF in Figure 7 of Majumdar et al. 2021). See [examples/arcmof_db7_ddmof_559/README.md](examples/arcmof_db7_ddmof_559/README.md). It retrieves the structure by exact identifier and checks its composition, Ni₄(μ₃-OH)₂ node stoichiometry, volume and density against the paper and the ARC-MOF metadata.

**Example 1: Query Zn MOFs from QMOF for CO₂ screening pre-processing**
```bash
MP_API_KEY=<your_mp_api_key> \
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/query_mof_db.py \
    --database qmof \
    --formula Zn \
    --max-results 10 \
    --output-dir ./research/2026-03-27_test/qmof_zn
```

**Example 2: Query Zn, Ni, or Mg hypothetical MOFs from ARC-MOF DB7**
```bash
# Zn-based
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/query_mof_db.py \
    --database arcmof-majumdar \
    --elements Zn \
    --max-results 50 \
    --output-dir ./research/2026-03-27_arcmof_zn

# Ni-based
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/query_mof_db.py \

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills