topspin_api.py

"""
TopSpin Python API Wrapper

This module provides a Python interface to control TopSpin NMR software,
specifically for opening and manipulating pulse sequence files.

Author: TopSpin Python API Wrapper
License: See TopSpin license
"""

import os
import sys
from pathlib import Path
from typing import Optional, Union

# Add TopSpin Python directory to path for importing the API
TOPSPIN_DEFAULT_PATH = "D:/topspin"


class TopSpinAPI:
    """
    Wrapper class for TopSpin NMR software Python API.

    This class provides methods to interact with TopSpin, including
    opening pulse sequence files and executing TopSpin commands.
    """

    def __init__(self, topspin_path: Optional[Union[str, Path]] = None):
        """
        Initialize the TopSpin API wrapper.

        Args:
            topspin_path: Path to TopSpin installation directory.
                         Defaults to D:/topspin.
        """
        self._topspin_path = Path(topspin_path) if topspin_path else Path(TOPSPIN_DEFAULT_PATH)

        if not self._topspin_path.exists():
            raise FileNotFoundError(
                f"TopSpin installation not found at: {self._topspin_path}\n"
                f"Please provide the correct TopSpin installation path."
            )

        # Add TopSpin Python to sys.path for importing the API
        python_path = self._topspin_path / "python"
        if python_path.exists():
            if str(python_path) not in sys.path:
                sys.path.insert(0, str(python_path))

        # Import TopSpin API
        try:
            from bruker.api.topspin import Topspin
            self._topspin = Topspin()
        except ImportError as e:
            raise ImportError(
                f"Failed to import TopSpin API. Error: {e}\n"
                f"Please ensure bruker_nmr_api is installed. "
                f"Install with: uv pip install {self._topspin_path}/python/examples/bruker_nmr_api-*.whl"
            )

        self._data_provider = self._topspin.getDataProvider()

    def get_version(self) -> str:
        """Get TopSpin version."""
        return self._topspin.getVersion()

    def get_installation_directory(self) -> str:
        """Get TopSpin installation directory."""
        return self._topspin.getInstallationDirectory()

    def open_pulse_sequence(self, pulse_sequence_path: Union[str, Path]) -> bool:
        """
        Open a pulse sequence file in TopSpin.

        This method opens a pulse sequence file in TopSpin using the 'edpul' command.
        The pulse sequence file can be specified as an absolute or relative path.

        Args:
            pulse_sequence_path: Path to the pulse sequence file (.pulse extension).

        Returns:
            True if successful, False otherwise.

        Raises:
            FileNotFoundError: If the pulse sequence file does not exist.

        Example:
            >>> api = TopSpinAPI()
            >>> api.open_pulse_sequence("D:/topspin/exp/stu/expnam/pulseprogram")
        """
        pulse_path = Path(pulse_sequence_path)

        if not pulse_path.exists():
            raise FileNotFoundError(f"Pulse sequence file not found: {pulse_path}")

        # Try to open the pulse sequence using TopSpin's edpul command
        try:
            # Get current dataset (if any)
            current_dataset = self._data_provider.getCurrentDataset()

            if current_dataset is None:
                # If no dataset is open, we can't open a pulse sequence in context
                # Try to open the pulse sequence file directly using TopSpin's file opening
                print(f"No dataset open. Pulse sequence file: {pulse_path}")
                print("To edit a pulse sequence, open a dataset first or use the full path.")
                return False

            # Open pulse sequence using the edpul command
            # This opens the pulse sequence editor for the current experiment
            result = current_dataset.launch(f"edpul {pulse_path}")

            print(f"Pulse sequence opened: {pulse_path}")
            return True

        except Exception as e:
            print(f"Error opening pulse sequence: {e}")
            return False

    def open_pulse_sequence_in_experiment(
        self,
        experiment_path: Union[str, Path],
        pulse_sequence_name: str = "pulseprogram"
    ) -> bool:
        """
        Open a pulse sequence for a specific experiment.

        This method opens a pulse sequence file associated with an experiment.
        The pulse sequence is typically named 'pulseprogram' in the experiment directory.

        Args:
            experiment_path: Path to the experiment directory.
            pulse_sequence_name: Name of the pulse sequence file (default: "pulseprogram").

        Returns:
            True if successful, False otherwise.

        Raises:
            FileNotFoundError: If the experiment or pulse sequence file does not exist.

        Example:
            >>> api = TopSpinAPI()
            >>> api.open_pulse_sequence_in_experiment("D:/topspin/exp/stu/expnam")
        """
        exp_path = Path(experiment_path)

        if not exp_path.exists():
            raise FileNotFoundError(f"Experiment directory not found: {exp_path}")

        # Construct path to pulse sequence file
        pulse_path = exp_path / pulse_sequence_name

        if not pulse_path.exists():
            raise FileNotFoundError(f"Pulse sequence file not found: {pulse_path}")

        # Load the experiment data
        try:
            experiment = self._data_provider.getNMRData(str(exp_path))

            # Open pulse sequence using edpul command
            experiment.launch(f"edpul {pulse_path}")

            print(f"Pulse sequence opened for experiment: {exp_path}")
            print(f"Pulse sequence file: {pulse_path}")
            return True

        except Exception as e:
            print(f"Error opening pulse sequence for experiment: {e}")
            return False

    def execute_topspin_command(self, command: str) -> bool:
        """
        Execute a TopSpin command.

        Args:
            command: TopSpin command string to execute.

        Returns:
            True if successful, False otherwise.

        Example:
            >>> api = TopSpinAPI()
            >>> api.execute_topspin_command("wrp 2 y")
        """
        try:
            current_dataset = self._data_provider.getCurrentDataset()

            if current_dataset is None:
                print("No dataset open. Cannot execute command.")
                return False

            result = current_dataset.launch(command)
            print(f"Command executed: {command}")
            return True

        except Exception as e:
            print(f"Error executing command: {e}")
            return False

    def get_current_dataset_info(self) -> Optional[dict]:
        """
        Get information about the current dataset.

        Returns:
            Dictionary with dataset information or None if no dataset is open.
        """
        try:
            current_dataset = self._data_provider.getCurrentDataset()

            if current_dataset is None:
                return None

            identifier = current_dataset.getIdentifier()
            return {
                "identifier": identifier,
                "path": str(identifier),
            }

        except Exception as e:
            print(f"Error getting current dataset info: {e}")
            return None

    def open_experiment(self, experiment_path: Union[str, Path]) -> bool:
        """
        Open an experiment in TopSpin.

        Args:
            experiment_path: Path to the experiment directory.

        Returns:
            True if successful, False otherwise.

        Example:
            >>> api = TopSpinAPI()
            >>> api.open_experiment("D:/topspin/examdata/Cyclosporine/1")
        """
        try:
            experiment = self._data_provider.getNMRData(str(experiment_path))

            # Show the dataset in TopSpin display
            self._topspin.getDisplay().show(experiment)

            print(f"Experiment opened: {experiment_path}")
            return True

        except Exception as e:
            print(f"Error opening experiment: {e}")
            return False


def main():
    """Example usage of TopSpinAPI."""

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

    try:
        print(f"TopSpin version: {api.get_version()}")
        print(f"TopSpin installation: {api.get_installation_directory()}")
    except Exception as e:
        print(f"Note: Could not connect to running TopSpin instance.")
        print(f"Error: {e}")
        print("\nIMPORTANT: TopSpin must be RUNNING to use the Python API.")
        print("Please start TopSpin first, then run this script.")
        return

    # Get current dataset info
    dataset_info = api.get_current_dataset_info()
    if dataset_info:
        print(f"Current dataset: {dataset_info}")
    else:
        print("No dataset currently open.")

    # Example: Open a pulse sequence
    # Uncomment and modify to use:
    # api.open_pulse_sequence("D:/topspin/exp/stu/expnam/pulseprogram")

    # Example: Open pulse sequence for an experiment
    # Uncomment and modify to use:
    # api.open_pulse_sequence_in_experiment("D:/topspin/examdata/Cyclosporine/1")


if __name__ == "__main__":
    main()