chem-spectrum-matcher

Files (4)

• SKILL.md
• README.md · examples/nmr-ethanol/
• match_spectrum.py · scripts/
• register_spectrum.py · scripts/

SKILL.md (first lines)

# Spectrum Matcher

## Goal
To retrieve or generate reference spectra for a set of candidate molecules and rank them by similarity to an experimental query spectrum. The skill abstracts a common three-component pattern:

1. **Prediction** — generate reference spectra from structure (SMILES) via empirical predictors or QM.
2. **Reference DB** — cache computed spectra locally; fall back to public databases for known compounds.
3. **Similarity metric** — score each candidate against the query and rank.

This pattern applies to any spectral modality: 1H NMR, 13C NMR, IR, mass spectrometry, UV-Vis, Raman. The concrete implementation here covers **1H NMR** and **IR**, with the NMR path fully implemented and IR sketched for extension.

## When to Use This Skill

- Confirm a proposed structure against an experimental spectrum.
- Screen a shortlist of candidates and rank by spectral similarity.
- Avoid re-running expensive predictions by retrieving cached spectra from the local catalog.
- Fetch experimental reference spectra from public databases (NMRShiftDB2, NIST WebBook) before committing to a prediction run.

## When NOT to Use This Skill

- **Unknown structure elucidation from scratch** — this skill requires a candidate list. For open-ended structure identification, use `general-query-literature-database` first.
- **Mixture deconvolution** — use `chem-nmr-analysis` (Wasserstein deconvolution) for quantifying component ratios.
- **13C, 19F, 31P NMR prediction** — `chem-nmr-predict` (SPINUS) covers 1H only. Extension needed.
- **Mass spectrometry** — not yet implemented. Scaffold is in place; add a predictor and similarity metric.

---

## Architecture

```
SMILES  ──► [Predictor]  ──► predicted spectrum (.xy / .jdx)
                                        │
                                        ▼
                              [Local Catalog]  ◄──  register_spectrum.py
                                        │
        [Public DB fallback]  ──────────┤  (NMRShiftDB2, NIST WebBook)
                                        │
                                        ▼
            Experimental query  ──► [match_spectrum.py]  ──► ranked candidates
```

### Modality–Predictor–Metric table

| Modality | Predictor skill | Public DB | Similarity metric |
|---|---|---|---|
| 1H NMR | `chem-nmr-predict` (SPINUS + nmrsim) | NMRShiftDB2 | L2 / Wasserstein |
| IR | `chem-db-spectra` (NIST) or ORCA DFT | NIST WebBook | Cosine |
| 13C NMR | *(not yet implemented)* | NMRShiftDB2 | L2 |
| Mass spec | *(not yet implemented)* | NIST WebBook | Dot product |

---

## Workflow

### Step 1 — Prepare Candidate Reference Spectra

#### Option A: Retrieve from catalog or public DB (fast, no prediction)

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/match_spectrum.py \
  --query experimental_spectrum.xy \
  --smiles "CCO" \
  --names "ethanol" \
  --modality nmr_1h \
  --catalog_dir research/spectrum_catalog/ \
  --output_dir <research_dir>/spectrum_match/ \
  --fallback_public_db
```

#### Option B: Predict first, then match

Run the appropriate predictor for the modality, then register outputs into the catalog, then match.

**1H NMR:**
```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/../chem-nmr-predict/scripts/predict_nmr.py \
  --smiles "CCO" \
  --names "ethanol" \
  --field_mhz 400 \
  --output_dir <research_dir>/nmr_predictions/

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/register_spectrum.py \
  --source_dir <research_dir>/nmr_predictions/ \
  --modality nmr_1h \
  --catalog_dir research/spectrum_catalog/
```

**IR (from NIST WebBook):**
```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/../chem-db-spectra/scripts/query_spectra.py \
  C10H18O <research_dir>/ir_references/ --type IR

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/register_spectrum.py \
  --source_dir <research_dir>/ir_references/ \
  --modality ir \
  --catalog_dir research/spectrum_catalog/
```

**IR (QM-backed, high accuracy):**
```bash
# Run ORCA frequency calculation → extract IR spectrum → register
# ORCA setup (ORCA_BINARY_PATH, x86_64 only): see the chem-dft-orca-singlepoint skill.
# After ORCA run, convert output with ${CLAUDE_SKILL_DIR}/../../src/utils/dft/orca_utils.py
# then call register_spectrum.py --modality ir
```

### Step 2 — Match and Rank

`match_spectrum.py` retrieves reference spectra (catalog → public DB fallback) and computes similarity scores between the query and each candidate.

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/match_spectrum.py \
  --query experimental_spectrum.xy \
  --smiles "CCO" \
  --names "ethanol" \
  --modality nmr_1h \
  --metric l2 \
  --catalog_dir research/spectrum_catalog/ \
  --output_dir <research_dir>/spectrum_match/ \

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills