Bruker Topspin

Always start with Offline mode unless you specifically need live instrument control.

Quick Start: Process a Spectrum (Offline)

# Note: Directory is 'bruker-topspin' on disk but imports use underscores
from devices.bruker_topspin.adapter import TopSpinAdapter
from devices.bruker_topspin.processor import TopSpinProcessor
from devices.bruker_topspin.visualizer import plot_spectrum

# 1. Connect in offline mode (default)
adapter = TopSpinAdapter(mode="offline")
adapter.connect()

# 2. List available datasets
datasets = adapter.list_datasets()
# Each entry: {"path": str, "sample": str, "expno": int, "title": str}

# 3. Process a dataset (FID -> spectrum with peaks)
spectrum = adapter.process(data_path="/opt/topspin5.0.0/examdata/exam_CMCse_1/1")
# Returns NMRSpectrum with: data, ppm_scale, peaks, nucleus, solvent, frequency_mhz

# 4. Inspect peaks
for peak in spectrum.peaks[:10]:
    print(f"  {peak.ppm:.3f} ppm  (intensity: {peak.intensity:.1f})")

# 5. Plot
plot_spectrum(spectrum, output_path="spectrum.png", annotate_peaks=True)

Key Data Types

NMRSpectrum

The central data object returned by all processing paths:

• data (np.ndarray) -- processed spectrum intensities
• ppm_scale (np.ndarray) -- chemical shift axis
• peaks (list[NMRPeak]) -- detected peaks, sorted high-to-low ppm
• nucleus (str) -- e.g. "1H"
• solvent (str) -- e.g. "CDCl3"
• frequency_mhz (float) -- spectrometer frequency
• title, sample_name (str) -- metadata from dataset

NMRPeak

• ppm (float) -- chemical shift position
• intensity (float) -- peak height
• width_hz (float) -- line width
• multiplicity (str) -- splitting pattern
• integral (float) -- relative area

Core Workflows

1. Process Raw FID (Offline)

The processor runs the standard NMR pipeline: digital filter removal, zero-fill, apodization, FFT, phase correction, baseline correction, peak picking.

processor = TopSpinProcessor(line_broadening=0.3)
dic, fid = processor.read_bruker("/path/to/dataset/1")
spectrum = processor.process_1d(dic, fid, dataset_path="/path/to/dataset/1")

Processing steps (automatic):

1. Remove Bruker digital filter artifact
2. Zero-fill to next power of 2 (min 65536 points)
3. Exponential line broadening (default 0.3 Hz)
4. Fourier transform
5. Reverse spectrum (Bruker convention: high-ppm on left)
6. Automatic phase correction (ACME algorithm)
7. Polynomial baseline correction
8. Peak picking (threshold = 2% of max intensity)

2. Process via TopSpin API (Live)

Note: _acquire_api() is not yet implemented (raises NotImplementedError). Use API mode for processing only (adapter.process()), not acquisition.

adapter = TopSpinAdapter(mode="api")
if adapter.connect():  # connects to gRPC port 3081
    spectrum = adapter.process(data_path="/path/to/dataset/1")
    # TopSpin runs: efp (FT+phase) -> apbk (baseline) -> ppf (peak pick)
    # Then reads processed pdata back via nmrglue

3. Process via GUI Automation

adapter = TopSpinAdapter(mode="gui")
if adapter.connect():  # detects TopSpin window
    spectrum = adapter.process(data_path="/path/to/dataset/1")
    # Types commands into TopSpin command line: efp, apbk, ppf

4. AI-Powered Spectrum Interpretation

from devices.bruker_topspin.brain import TopSpinBrain

brain = TopSpinBrain()  # needs ANTHROPIC_API_KEY or uses cached demos
interpretation = brain.interpret_spectrum(spectrum, molecular_formula="C9H8O4")
# Returns markdown: Peak Analysis, Proposed Structure, Confidence, Next Steps

# Streaming variant
for chunk in brain.interpret_spectrum(spectrum, stream=True):
    print(chunk, end="")

# Suggest follow-up experiments
suggestion = brain.suggest_next_experiment(spectrum, hypothesis="aspirin")

5. Spectral Library Matching

from devices.bruker_topspin.library import SpectralLibrary

lib = SpectralLibrary.from_examdata()  # loads all TopSpin example data
matches = lib.match(unknown_spectrum, top_k=3)
for m in matches:
    print(f"  {m.entry.name}: score={m.score:.2f} ({m.matched_peaks} peaks matched)")

6. Driver Interface (for labclaw)

from devices.bruker_topspin.driver import TopSpinDriver

driver = TopSpinDriver(config={"mode": "offline"})
await driver.connect()
await driver.write({"action": "process", "path": "/path/to/dataset/1"})
result = await driver.read()  # returns dict with peaks, metadata

TopSpin Command Reference

This skill includes 525 command reference files in docs/commands/. Do NOT try to load them all. Instead, search by topic:

# Find commands related to a topic
grep -ril "phase correction" devices/bruker-topspin/docs/commands/
grep -ril "baseline" devices/bruker-topspin/docs/commands/
grep -ril "peak pick" devices/bruker-topspin/docs/commands/
grep -ril "2D" devices/bruker-topspin/docs/commands/

Files are named by command (e.g., efp.md, apk.md, ppf.md). Read a specific file when you need details about a command.

Essential Commands

Standard Processing Pipeline

Note: Processor currently handles 1D 1H only. 2D data can be acquired but must be processed in TopSpin.

For a typical 1D 1H spectrum, the command sequence is:

re <dataset_path>    # open dataset
efp                  # FT + phase
apbk -n              # neural-net auto phase + baseline
ppf                  # peak picking

Bruker Directory Format

Each experiment is a directory tree:

<sample_name>/
  <expno>/              # experiment number (1, 2, 3...)
    fid                 # raw Free Induction Decay
    acqus               # acquisition parameters
    acqu2s              # 2D acquisition parameters (if 2D)
    pdata/
      1/                # processing number
        1r, 1i          # processed real/imaginary data
        procs           # processing parameters
        title           # experiment title
        peaklist.xml    # peak list (after ppf)

Default examdata location: /opt/topspin5.0.0/examdata/

Read SOUL.md for chemical shift interpretation, solvent peaks, and NMR personality.

User Data

Instance-specific operational data in user/:

Reference Documentation