TopSpin Python API Wrapper

Python wrapper for TopSpin NMR software API, enabling programmatic control of pulse sequences and experiments.

Features

• Open pulse sequence files in TopSpin
• Execute TopSpin commands from Python
• Access current dataset information
• Open and manage experiments
• Simple, intuitive Python API

Important: TopSpin API Requirements

TopSpin Python API requires a running TopSpin API Server. There are two ways to use it:

Method 1: Run from Within TopSpin (Recommended)

Run Python scripts directly from TopSpin's command line:

# In TopSpin command line:
xpy3 F:\topspin_python\example_pulse_sequence.py

Advantages:

• No need to start API server separately
• Direct access to TopSpin's internal state
• Works immediately

Method 2: Run from External Terminal

Start TopSpin API server first:

1. In TopSpin command line, type: api_server
2. Keep TopSpin running
3. In terminal, run Python script

Prerequisites

• TopSpin NMR software installed at D:\topspin (or specify custom path)
• Python 3.8+
• uv package manager (for external terminal usage)
• Windows or Linux system

Installation

Quick Setup (Recommended - Use TopSpin's Python)

No installation needed! TopSpin comes with Python 3.12 and the API pre-installed.

Just run scripts from TopSpin:

# In TopSpin command line:
xpy3 F:\topspin_python\example_pulse_sequence.py

Manual Installation (For External Terminal Usage)

# Install uv if not already installed
pip install uv

# Create virtual environment
uv venv

# Activate environment (Windows)
.venv\Scripts\activate

# Activate environment (Linux/Mac)
source .venv/bin/activate

# Install Python dependencies
uv pip install numpy xarray matplotlib adjustText

# Install TopSpin API (from TopSpin installation)
uv pip install D:/topspin/python/examples/bruker_nmr_api-2.1.0-py3-none-any.whl

Usage

Basic Example

from topspin_api import TopSpinAPI

# Initialize TopSpin API
api = TopSpinAPI(topspin_path="D:/topspin")

# Print TopSpin version
print(f"TopSpin version: {api.get_version()}")

Open a Pulse Sequence File

from topspin_api import TopSpinAPI

api = TopSpinAPI(topspin_path="D:/topspin")

# Open a pulse sequence file directly
api.open_pulse_sequence("D:/topspin/examdata/Cyclosporine/1/pulseprogram")

Open Pulse Sequence for an Experiment

from topspin_api import TopSpinAPI

api = TopSpinAPI(topspin_path="D:/topspin")

# Open pulse sequence for a specific experiment
api.open_pulse_sequence_in_experiment("D:/topspin/examdata/Cyclosporine/1")

Execute TopSpin Commands

from topspin_api import TopSpinAPI

api = TopSpinAPI(topspin_path="D:/topspin")

# Execute a TopSpin command
api.execute_topspin_command("wrp 2 y")
api.execute_topspin_command("efp")

Open an Experiment

from topspin_api import TopSpinAPI

api = TopSpinAPI(topspin_path="D:/topspin")

# Open an experiment
api.open_experiment("D:/topspin/examdata/Cyclosporine/1")

Command Line Usage

Run the example script with a pulse sequence file path:

python example_pulse_sequence.py D:/topspin/examdata/Cyclosporine/1/pulseprogram

Or run without arguments to see all examples:

python example_pulse_sequence.py

API Reference

TopSpinAPI Class

__init__(topspin_path=None)

Initialize the TopSpin API wrapper.

Parameters:

• topspin_path (str|Path, optional): Path to TopSpin installation directory. Defaults to "D:/topspin".

Raises:

• FileNotFoundError: If TopSpin installation not found.
• ImportError: If TopSpin API package not installed.

open_pulse_sequence(pulse_sequence_path)

Open a pulse sequence file in TopSpin using the edpul command.

Parameters:

• pulse_sequence_path (str|Path): Path to the pulse sequence file.

Returns:

• bool: True if successful, False otherwise.

open_pulse_sequence_in_experiment(experiment_path, pulse_sequence_name="pulseprogram")

Open a pulse sequence for a specific experiment.

Parameters:

• experiment_path (str|Path): Path to the experiment directory.
• pulse_sequence_name (str, optional): Name of the pulse sequence file. Defaults to "pulseprogram".

Returns:

• bool: True if successful, False otherwise.

execute_topspin_command(command)

Execute a TopSpin command.

Parameters:

• command (str): TopSpin command string to execute.

Returns:

• bool: True if successful, False otherwise.

get_current_dataset_info()

Get information about the current dataset.

Returns:

• dict|None: Dictionary with dataset information, or None if no dataset is open.

open_experiment(experiment_path)

Open an experiment in TopSpin.

Parameters:

• experiment_path (str|Path): Path to the experiment directory.

Returns:

• bool: True if successful, False otherwise.

Running from Within TopSpin

For best integration, you can run Python scripts directly from TopSpin:

1. Open TopSpin
2. From TopSpin command line, use:

   xpy3 example_pulse_sequence.py
   

This provides full access to TopSpin's internal state and datasets.

Troubleshooting

Import Error: "bruker.api.topspin" not found

This means the TopSpin API package is not installed. Run:

uv pip install D:/topspin/python/examples/bruker_nmr_api-*.whl

TopSpin Installation Not Found

Ensure TopSpin is installed at D:/topspin, or specify the correct path:

api = TopSpinAPI(topspin_path="/path/to/your/topspin")

Pulse Sequence File Not Found

Verify the pulse sequence file exists and the path is correct:

from pathlib import Path
print(Path("D:/topspin/examdata/Cyclosporine/1/pulseprogram").exists())

Requirements

numpy>=1.20.0
xarray>=0.20.0
matplotlib>=3.5.0
adjustText>=0.8
bruker_nmr_api>=2.1.0

License

This wrapper uses the TopSpin API, which is subject to TopSpin's license terms. Please ensure you have a valid TopSpin license.

Author

TopSpin Python API Wrapper

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Resources

• TopSpin Documentation: Available within TopSpin software
• TopSpin Python API Documentation: D:/topspin/python/docs/
• TopSpin Examples: D:/topspin/python/examples/