Installation

POISE comprises a frontend script, which is accessible from within TopSpin itself, as well as a backend script, which has to be run using Python 3 (i.e. not TopSpin’s native Python interpreter).

The requirements are:

  • TopSpin. We have tested TopSpin versions 3.6 and 4.0 thoroughly. Older versions of TopSpin are not guaranteed to work: they should, however, work as long as the Python version inside TopSpin is 2.7.

    To check the TopSpin Python version, you can create a new Python script in TopSPin (edpy), enter the following, and execute it:

    import sys; MSG(sys.version)

    If the resulting version number starts with 2.7, you should be good to go.

  • Python 3. This refers to a separate, system installation of Python 3; in particular, POISE requires a minimum version of Python 3.6. (We have tested up to Python 3.9.)

    For Windows, your best bet is to download an installer from the Python website. For macOS and Linux, we suggest using a package manager to do so (such as Homebrew for macOS or apt/yum & their equivalents on Linux), although the installers are also fine.

Once that’s done, you can install POISE using pip (replace python with python3 if necessary):

python -m pip install nmrpoise

pip tries to take care of installing the scripts to your TopSpin directory. To do so, it checks for TopSpin installations in standard directories (/opt on Unix and C:\Bruker on Windows). If pip exits without errors, this should have succeeded; you can test it by typing poise -h into TopSpin’s command-line, which should spawn a popup. If that is the case, congratulations — you can move on to the next chapter, Setting up a Routine.

Updating POISE

Simply use:

python -m pip install --upgrade nmrpoise --no-cache-dir

(again replacing python with python3 if necessary). All other steps (including troubleshooting, if necessary) are the same.

Troubleshooting

If you are reinstalling POISE (either using the --upgrade flag, or after uninstalling it), make sure to add the --no-cache-dir flag to pip install. In other words, run python -m pip install nmrpoise --no-cache-dir. (The reason for this is because if pip uses a pre-built wheel to install POISE, the TopSpin files will not be installed. When POISE is installed for the first time, pip will create a wheel, and subsequent installations will use the wheel and fail to install the TopSpin files, unless the -no-cache-dir flag is passed. There is a possible workaround for this to prevent wheels from ever being built, but even though this allows installation to complete successfully, it shows the user some scary red text in the process, which I’d rather not.)

Apart from this, the installation can occasionally fail if TopSpin is installed to a non-standard location. To solve this issue, you can specify the TopSpin installation directory as an environment variable TSDIR before installing POISE. The way to do this depends on what operating system (and shell) you use.

On Windows PowerShell, run the following command:

$env:TSDIR = "C:\Bruker\TopSpinX.Y.Z\exp\stan\nmr"

replacing the part in quotes with your actual TopSpin installation directory (it must point to the exp/stan/nmr folder).

On old-school Windows cmd, use:

set TSDIR="C:\Bruker\TopSpinX.Y.Z\exp\stan\nmr"

On Unix systems, use:

export TSDIR="/opt/topspinX.Y.Z/exp/stan/nmr"

(Unless you’re using csh or the like, in which case you use setenv, although you probably didn’t need to be told that!)

After running the appropriate command for your operating system, pip install nmrpoise should be able to detect the TSDIR environment variable and install the scripts accordingly.

From source

If you obtained the source code (e.g. from git clone or a GitHub release) and want to install from there, simply cd into the top-level nmrpoise directory and run:

pip install .

or equivalently:

python setup.py install

The installation to the TopSpin directory is subject to the same considerations as above.

Without an internet connection

If your spectrometer does not have an Internet connection, then the installation becomes a bit more protracted. On a computer that does have an Internet connection:

  1. Make a new folder.

  2. Download the CPython installer for the spectrometer operating system. Place it in that folder.

  3. cd to the folder and run these commands:

    pip download Py-BOBYQA nmrpoise --no-deps --no-binary=:all:
pip download numpy pandas scipy --only-binary=:all: --python-version <3.X> --platform <PLATFORM>

    where <3.X> is the version of Python to be installed on the spectrometer, and <PLATFORM> is one of win32, win_amd64, macosx_10_9_x86_64, or manylinux1_x86_64 depending on the spectrometer operating system. (n.b. These options are not well-documented; I have figured them out by trawling Stack Overflow. Any additions are welcome.)

  4. Copy the whole folder over to your spectrometer. It should contain a bunch of .whl files and two .tar.gz files.

Now, on the spectrometer:

  1. Install CPython with the installer.

  2. cd to the folder and run

    pip install ./nmrpoise-<VERSION>.tar.gz --no-index --find-links .

    (replace <VERSION> with whichever version you downloaded).

It should then install properly, unless your TopSpin installation location is non-standard: in that case, set the $TSDIR environment variable (described above) before retrying Step 2.