Back to a list of topics

Spooler

This is a brief tutorials of how to use Spooler in Topspin for semi-automatic control of Bruker instruments.

Spooler settings
Opening Spooler
Creating a simple queue
Adding experiments to queue
Changing existing queue
Suspending Spooler to operate spectrometer directly
Spooler logs and reports
Advanced uses of Spooler

Spooler settings

Before you start with the Spooler you need to check your preferences in Manage:Preferences

to see if the "Enable automatic command spooling" is unchecked.

Keeping it unchecked is my personal preference. All following instructions will work exactly as explained only if it is unchecked.

Back to Contents

Opening Spooler

Spooler is a standard part of Topsin. It is started by clicking in the bottom toolbar Spooler section:

or by typing spooler in the Topspin command line, which opens a Spooler window:

Before we start using it, I recommend to suspend it so it creates the queue of commands but does not send them into the spectrometer console:

It is safe to hit Close or X button in the top right to close the window. Spooler retains the queue in its memory. You will be able to open spooler window again by clicking in a toolbar

Back to Contents

Creating a simple queue

We suspended Spooler in the previous step to prevent it from submitting queued commands to NMR console. Now you can send any Topspin command to the Spooler queue if you precede it with qu on a command line. For example, I want to make a queue to lock, tune, and shim my current sample.

First, I will display my experiment I want to acquire.

Second, I will issue on the Topspin command line the following commands

qu lock cdcl3
qu atma
qu ro on
qu topshim

Now if I open Spooler window, I see the queue (below).
IMPORTANT: The commands must be executed when the corresponding NMR experiment is displayed in the Topspin window because commands like atma and topshim need to look into your current experiment parameters for the observe nucleus and other channels. The Data object line shows the experiment each command was issued from:

Now I can uncheck Spooler:Suspend and the Spooler submits my commands one by one in the order in the queue.

IMPORTANT NOTE: While the atma command is executing, you should NOT touch the Topspin window. The tuning procedure opens its own window with the tuning curve. If you happen to display any other dataset during atma operation, the atma may feeze Topspin and the NMR spectrometer!

VERY IMPORTANT NOTE: The Spooler does not check correct spelling of commands. If you made a typo while submitting the command, it will only reveal itself when the time comes for the command to be executed: Topspin will trigger an error and the Spooler will suspend itself. As a result, the remaining queue stalls! Therefore, after you prepared the queue, you must carefully examine it. If you found a typo you should correct the queue as described here Changing existing queue

To avoid typing mistakes, I recommend not to re-type previous commands but, instead, obtain them from Topspin history using one of the two ways:

Hitting Arrow Up on a keyboard brings previous commands one-by-one

Typing cmdhist opens command history window. You may select any command or group of commands and click Execute. This will enter them automatically on Topspin command line. For the group of commands, it will enter them in order as they appear in the selection.

Back to Contents

Adding experiments to queue

Running ONE experiment

Before you add any experiment to the queue you must adjust parameters of the experiment including all pulses and powers.

Please, note that you have to perform locking, tuning, and shimming prior to this!

To prepare experiment for queueing:

display the desired experiment in the Topspin window

adjust all experimental parameters to the desired values

issue getprosol

issue pulsecal if this is a proton experiment with more than one 90-degree pulse

issue rga

issue zg to observe whether

experiment produces signal

you observe any receiver overflows

After these actions, your experiment is ready to be queued.

To queue acquisition of the experiment you will type:

qu zg

Running MULTIPLE experiments

Before you may queue multiple experiments, you have to adjust all of their parameters as described above.

To queue multiple experiments, you

display first experiment for the queue in Topspin window

issue qu zg

display second experiment

issue qu zg

etc.

The resulting queue shows up in the Spooler window. To start the queue, remove a checkmark from Spooler:Suspend. The first experiment will switch from Waiting to Running. To see the content of all columns, you should

maximize Spooler window,

right-click in the blue header line, and

select "Auto-resize columns:

Now you can see estimated duration, start and end times of each experiment.

Adjusting parameters AFTER experiment was queued

If your experiment is still in Waiting status, you may adjust any of its parameters. If your changes affects total acquisition time, the Spooler will automatically update its estimates for Duration and End time. NOTE: If experiment is already Running, your changes will not be used!

Back to Contents

Changing existing queue

If you need to edit or change the queue, there are several approaches:

Situation 1. I don't need this command!

Select the line, right-click, and choose Delete,

or just hit Delete on a keyboard

Situation 2. I made a typo and all following commands will be affected!

Click the line with the typo, keep Shift and click the last line to select all successive commands.

Hit Delete on a keyboard to remove entire block of commands.

Queue a new sequence of commands

Situation 3. I forgot an important experiment and want to run it in the beginning of the queue!

First, queue the experiment. It will show up as a last line in the queue. In the next steps we will move it up.

In the example below, it is an acquisition of EXPNO 3. We see that EXPNO 1 is already in the console and has a status Running. EXPNO 2 is Waiting and the first to start after EXPNO 1 finishes. Our plan is to move EXPNO 3 to the head of the queue.
Right-click the EXPNO 3 line and select Properties
A Properties box pops up. Notice a slider for the job Priority:

All jobs have a Priority=0 in the queue by default. Changing priority will move the job up:

The experiment from EXPNO 3 is now ahead of the entire queue because its priority is highest. It will start as soon as running EXPNO 1 finishes.
You may repeatedly change Priority on multiple jobs to rearrange them. However, it might be more reliable to just delete the queue and populate it again in a corect order.

Back to Contents

Suspending Spooler to operate spectrometer directly

If you realize you need to do something with the spectrometer in the middle of the queue, you can suspend the Spooler

The experiment that is Running has already been sent by a Spooler to the spectrometer. You will have to either wait for it to finish or stop it. Once you did, the spectrometer is free for you to use, while the Spooler still keeps the queue. When you are done, you have to

re-insert the same sample (if you took it out)

lock, tune all channels and shim (if you changed samples)

unsuspend the Spooler

The queue resumes from the job that was Waiting in the top of the list.

Back to Contents

Spooler logs and reports

As Spooler is populated with commands and submits the queue to the NMR spectrometer, it creates two logs, which you find in its Tools menu:

Spooler report stores all commands that Spooler submitted to the NMR console. It records "Success" status, time stamp, the command name and the EXPNO from which the command was issued. Below is an example of a report from my previous spooler run:

Spooler log collects all actions you perform on the Spooler including suspending/unsuspending, adding and deleting jobs, changing priorities, etc.

Back to Contents

Advanced uses of Spooler

Sample changer operation

The Spooler may be used to control sample changers. You need to make sure that you precede sample changing commands with unlocking and stopping rotation:

qu ro off
qu lock off
qu sx [sample position]

Long multi-block experiments

The Spooler comes very handy to perform tuning and shimming in the middle of long acquisitions before more experiments are started. For example, if I need a very long carbon 1D, I will break it into 6- or 8-hour parts because a typical magnet may be not as stable beyond such a time interval. Separating long experiment into identical parts safeguards the dataset from NMR system failures and allows to re-tune, re-shim and acquire a "quick survey" proton 1D between the parts. The proton "survey" helps monitoring the state of the magnet and the sample through the series.

To perform such complex multi-block acquisition, I would:

display first "quick survey" proton
qu ro on
qu zg
display first long carbon
qu zg
qu atma
qu topshim
display second "quick survey"
qu zg
display second long carbon
qu zg
... repeat re-tuning, re-shimming and proton "survey" for parts 3, 4 and so on
Finish with collecting the last proton survey:
qu atma
qu topshim
display the last "survey"
qu zg
qu ro off
The final command is to stop spinning when we are not acquiring -- it conserves the expensive N2 gas.

After experiments are finished,

I would overlay all proton surveys to determine if sample and spectrometer parameters were stable.

If they were, I would make an overlay of all carbons and verify that there are no spectral shifts. If there were shifts - I will shift individual spectra to match peak positions.

Finally, I would add together all carbon experiments to effectively create a desired super-long experiment as if it was acquired on a super-stable spectrometer.

If I see in a proton overlay that spectrometer performance deteriorated at some point I can exclude corresponding long carbons from addition.

Same goes for my sample degradation: I can directly monitor the sample stability by proton signals and may decide to only add carbons that corresponded to the intact sample.

Note on complex commands with interactive dialogs

The Spooler will stall if any of queued commands pop up a dialog box. One of such commands is pulsecal if issued without parameters. To prevent popup dialogs in pulsecal use the following synthax: pulsecal quiet sn [nucleus name]

Working in Topspin while the queue runs

Generally, it is safe to display datasets, create new datasets, and change parameters while the queue runs.

However, while the atma command is executing, you should NOT touch the Topspin window. The tuning procedure opens its own window with a tuning curve. If you happen to display any other dataset during atma operation, the atma may feeze Topspin and the NMR spectrometer!

Same goes for pulsecal quiet sn because it will deposit the newly calibrated pulse into the currently open dataset. If you change dataset, the parameter will be updated in a wrong place.

To avoid any such interference, you may open the second Topspin window by issuing newtop on the Topspin command line. The second window allows access to all the same datasets and will not create interference with the currently running commands. However, NEVER rename, renumber, or delete experiments that are in the current queue!

Remember to quit the second Topspin along with the first one before you log out.

Back to Contents