Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
110 lines (77 loc) · 2.41 KB

SETUP_GUIDE.md

File metadata and controls

110 lines (77 loc) · 2.41 KB

TopSpin Python API - Setup Guide

Important: How TopSpin API Works

TopSpin Python API requires a running TopSpin API Server to be active. There are two ways to use the API:

Method 1: Run Scripts from Within TopSpin (Recommended)

  1. Open TopSpin
  2. In TopSpin command line, use: 
    xpy3 your_script.py

Advantages:

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

Method 2: Run Scripts from External Terminal

To run Python scripts from outside TopSpin, you need to start the TopSpin API Server first.

Start TopSpin API Server:

  1. Open TopSpin

  2. In TopSpin command line, type:

    api_server

    This will start the API server on port 3081.

  3. Keep TopSpin running with the API server active

  4. In a separate terminal, run your Python script:

    cd topspin_python
D:\topspin\python\python.exe your_script.py

Note: The API server must remain running while your Python script executes.

Test Your Setup

Method 1 (From TopSpin):

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

Method 2 (From External Terminal):

# Step 1: In TopSpin, start API server
api_server

# Step 2: In terminal, run test
cd F:\topspin_python
D:\topspin\python\python.exe test_setup.py

Troubleshooting

Error: "Connection refused on port 3081"

Cause: TopSpin API server is not running.

Solution:

  • Either run script from TopSpin using xpy3, OR
  • Start API server in TopSpin using api_server command

Cannot run Python scripts from TopSpin

Cause: Python script not in TopSpin's search path.

Solution: Use full path when running:

xpy3 F:\topspin_python\your_script.py

Quick Example

from topspin_api import TopSpinAPI

# Initialize (will connect if TopSpin API server is running)
api = TopSpinAPI(topspin_path="D:/topspin")

# Open pulse sequence editor
api.execute_topspin_command("edpul")

# Or open experiment
api.open_experiment("D:/topspin/examdata/Cyclosporine/1")

Running Example Scripts

From TopSpin (Recommended):

xpy3 F:\topspin_python\example_pulse_sequence.py

From External Terminal:

# First start API server in TopSpin: api_server

# Then run script:
cd F:\topspin_python
D:\topspin\python\python.exe example_pulse_sequence.py D:/topspin/examdata/Cyclosporine/1