ScienceSoft, LLC

CHAPTER 5: Using The VNMR ShimIt Client Software

The ShimIt version for VNMR consists of menus, macros, and help files. The user interface consists of three ShimIt menus1 and a modified "additional main menu" (main2) containing a button to show the main ShimIt menu.

The VNMR menu system consists of two rows of buttons. The top row is accessible at all times and is referred to as the permanent menu. The second row can be customized and is used to display the three ShimIt menus. After the start of VNMR or after clicking on the [Main Menu] button in the permanent menu the following menus are displayed:

Click on the [More] button to start the modified "additional main menu" containing the button to start the ShimIt main menu:

5.1 ShimIt Main Menu

The ShimIt main menu can be reached from the modified "additional main menu" (discussed above) by clicking on the [ShimIt] button:

All functions of ShimIt are available from this menu. To aid in the editing of ShimIt parameters the Shims and Setup submenus are provided and are accessible from this menu, see SECTION 5.2: "Shims Submenu" and SECTION 5.3: "Setup Submenu" for details. To display a short description of the function of a ShimIt menu click on the [Help] button in the permanent menu while the menu of interest is displayed.

[Help] Button

The [Help] button in the permanent menu explains the function of the menu buttons. This main ShimIt menu [Help] button displays the following short description of the use of ShimIt:

[Show #Pts] Button

The ShimIt software adjusts the magnet homogeneity based on the shape of an isolated NMR signal. So before optimizing shim values the user needs to display an isolated signal with a small amount of baseline on the screen for the ShimIt optimization:

Manual lineshape shimming tends to focus on making the upper part of the line Lorentzian in shape. A main focus might be to minimize the width at half-height of the line. ShimIt focuses on optimizing the base of the signal which eventually leads to a minimization of the width of the signal as well. Selecting a reasonably good range around the signal for the ShimIt optimization is demonstrated in CHAPTER 6: "Automated Shimming Example".

A major concern for the use of ShimIt is the number of points in the displayed spectral area which ShimIt has to analyze for each acquired FID. This [Show #Pts] button causes the current number of complex spectral points in the displayed spectral area to be shown in the VNMR status line:

So the spectral area shown contains 42 complex-valued spectral points. The time ShimIt spends on analyzing each FID is normally small compared to the overhead of the Varian software for acquiring a spectrum.2 However, an excessive number of points in the selected spectral area can lead to a noticeable slow-down of ShimIt. So this number should be kept as small as possible. On slow workstations the number should be around 50 and faster workstations can normally handle 100 points without causing significant delays. To decrease the number of points in the spectral area decrease the acquisition time, re-acquire the spectrum, and use the [Show #Pts] button to check the current number of complex points again.

[dg()] Button

Several parameters are provided to customize ShimIt's behavior. All ShimIt parameters can be displayed in a data group (dg) using this [dg()] button. The button action is equivalent to issuing dg('dg_shimit') from the command line:

All displayed parameter values can be changed from the command line. The SELECTED SHIMS group is described in SECTION 5.2: "Shims Submenu". The Shims menu started by the [Shims] button allows one to change the selection of shims to be optimized. The SHIMIT PARAMETERS are described in SECTION 5.3: "Setup Submenu". These parameters can be interactively changed from the Setup menu started by the [Setup] button. Finally, the MAGNET PARAMETERS group values should be set during the software installation and should not require further customization. See SECTION 4.2: "Magnet Specific Customization" for details.

[Shims] Button

The [Shims] button starts the Shims submenu of ShimIt. This submenu provides a convenient way to specify the shims to be optimized during the shimming process. See the discussion of this submenu in SECTION 5.2: "Shims Submenu" for details.

[Setup] Button

The [Setup] button starts the Setup submenu of ShimIt. This submenu provides a convenient way to interactively specify the ShimIt parameters controlling the iterative shimming process. See the discussion of this submenu in SECTION 5.3: "Setup Submenu" for details.

[Start] | [Stop] Button

This button can be used to start the shimming process once an isolated NMR signal is displayed and the ShimIt parameters are set as desired. On start of ShimIt the button label toggles from [Start] to [Stop]. The [Stop] button can then be used to terminate the running ShimIt program. The [Stop] button only terminates the ShimIt run but does not terminate an acquisition in progress. To terminate an acquisition click on the [Abort Acq] button in the permanent menu. The [Stop] button changes back to [Start] whenever ShimIt terminates due to a user request, the set maximum number of iterations is reached, the convergence criterion is satisfied, or the response from spectrometer or ShimIt exceeds the set time-out period.

VNMR provides several means of automatic processing which slow down or even interfere with ShimIt. To make ShimIt easy to use, the automatically called MAGICAL macro shimit_start switches all automatic VNMR features off before beginning an auto-shimming run. Should this behavior be undesirable, comment out the corresponding lines in this macro:

 "No automatic VNMR processing"
 load = 'n'       "Don't load shim values from experiment yet"
 wshim = 'n'      "No automatic shimming besides ShimIt"
 alock = 'n'      "Leave lock in its current state"
 spin = 'n'       "Leave spin rate at currently used value"
 gain = 'y'       "No automatic adjustment of receiver gain"
 hdwshim = 'n'    "No hardware z1 shimming"
 in = 'n'         "No interlock: don't adjust lock level or spin rate	"
 wexp = ''        "No action yet when experiment completes"
 werr = ''        "No action for acquisition error"
 wbs = ''         "No action after bs transients"
 wnt = ''         "No action after nt transients"

 "Delay acquisition until new shim values stabilize"
 IF (pad + d1 < 1) THEN
    d1 = 1 - pad

[] | [Show Best] Button

ShimIt improves the magnet homogeneity iteratively. As a result several FIDs might be acquired with a homogeneity worse than previous FIDs. On start of ShimIt the [Show Best] button is only displayed if a Best spectrum from a previous ShimIt run is still available. After the requested steady-state FIDs are completed, ShimIt saves the starting spectrum and the [Show Best] button is displayed. Whenever ShimIt is stopped manually or stops due to a time-out this [Show Best] button should be used to retrieve the best acquired FID and its shim values. If ShimIt terminates normally (either by converging or by reaching the maximum number of iterations) the best spectrum is retrieved automatically at the end of the shimming run.

[Return] Button

The [Return] button in the main ShimIt menu causes the menu system to return to the "additional main menu" (menu file main2).

5.2 Shims Submenu

The [Shims] button in the ShimIt main menu starts the Shims submenu shown above. The purpose of this submenu is to aid in the selection of shim variables to be adjusted by ShimIt. On start of this submenu the ShimIt parameters are displayed in the VNMR alpha window using the dg command. The current selection of shim values is displayed both in the alpha window as well as in the status line as shown in the figure above. As the selection of shims is changed using these menu functions both the dg display in the alpha window as well as the status line are updated accordingly.

The current selection of shims is stored in the shims variable as a list of shim names separated by blanks. To specify a list of shim values, the shim names can be separated by a blank, comma, semicolon, colon, or any non-empty combination thereof. In principle the list can contain all shims recognized by VNMR except for the z0 shim3 and the coarse shims.4 The macro parse_shims also verifies that the specified shims are contained in the selected shim set.5 The default value of shims are all z shims in the selected shim set.

Using these menu functions provides several advantages over setting the shims variable directly from the command line: From the VNMR shimset variable the available shims are already known and can be specified in groups, e.g. "all z shims" and "all non-spinning shims". The menu also allows one to conveniently add and remove shims from the current selection. Finally, all user input is parsed directly and so input errors are discovered immediately. When setting the shims variable from the command line possible errors are only detected at the start of ShimIt.

[z1-z3] Button

This button selects the z1, z2, and z3 shims to be optimized during the automated shimming. The low-order z shims are related to quite visible lineshape distortions and tend to be adjusted after every sample change. Notice that the moment optimization used by ShimIt is very sensitive to high-order z shims allowing ShimIt to be quite effective in their optimization. So the [All z] button should be used if high-order shims might be able to correct some of the observed distortions of the spinning lineshape.

[All z] Button

This button selects all z (axial) shims in the current shim set to be optimized during the automated shimming. For the optimization of the z shims the sample should in general be spinning and the displayed spectral area should not contain the spinning sidebands. Should a clear separation of center resonance and spinning sidebands not be possible use the [All] button instead. To decrease the height of spinning sidebands stop the sample spinning and use the [Non-Spinning] button instead.

[Non-Spinning] Button

This button selects all non-spinning shims (also called non-axial shims) in the current shim set to be optimized during the automated shimming. For a spinning sample the non-spinning shims influence the height of the spinning sidebands. For the optimization of non-spinning shims the sample spinning has to be stopped so that the moment of the center line is influenced by the off-axis homogeneity. Some magnets show a strong interaction between spinning and non-spinning shims. Hence the spinning shims might need to be readjusted after the optimization of the non-spinning shims.

[All] Button

This button selects all shims in the current shim set to be optimized during the automated shimming. Selecting the optimization of all shims is only necessary when the magnet homogeneity is too bad for the sample spinning to baseline separate the spinning sidebands from the center resonance. Otherwise optimizing the non-spinning shims first followed by the optimization of the spinning shims will in general yield a better spinning lineshape.

[Add] Button

This button starts an interactive input request for the specification of shim names to be added to the current shim selection. Duplicate shim names are deleted from the resulting list.

[Remove] Button

This button starts an interactive input request for the specification of shim names to be deleted from the current shim selection.

[Specify] Button

This button starts an interactive input request for the specification of a new list of shim names to be optimized during the automated shimming.

[Return] Button

This [Return] button causes the menu system to return to the main ShimIt menu.

5.3 Setup Submenu

The [Setup] button in the main ShimIt menu starts the Setup submenu shown above.6 There are three groups of parameters which influence the way ShimIt performs the auto-shimming of a magnet. The magnet specific parameters7 are set during the installation of ShimIt as described in SECTION 4.2: "Magnet Specific Customization". The shims to be adjusted can be chosen from the Shims submenu described in SECTION 5.2: "Shims Submenu". The final group of parameters determines how the auto-shimming is performed and these parameters can be set from this submenu. Note that all ShimIt parameters can also be set from the VNMR command line.

[SS Cycles] Button

ShimIt acquires FIDs in rapid succession during shimming. If the relaxation time of the resonance selected for shimming is longer than the repetition time of ShimIt, the sample progressively saturates during the shimming run. A time-consuming method to avoid this problem is to increase the pre-acquisition delay (d1) and thereby to slow down the data acquisition.

A faster approach is to decrease the amount of sample saturation and to auto-shim on the partly saturated sample. The amount of sample saturation during the shimming run can be decreased by lowering the 90 degree pulse width provided the signal-to-noise (S/N) ratio of the spectrum is sufficient. The [SS Cycles] button allows one to set the sscycles variable interactively. ShimIt performs the specified number of sscycles steady-state cycles of acquiring and analyzing an FID to reach the steady-state sample saturation before starting the auto-shimming process.

ShimIt will normally recover from a partial sample saturation occurring during the auto-shimming. However, specifying a few steady-state cycles to be performed before the analysis of a partially saturating signal can improve the speed of the shimming process. Frequently, sscyles=3 is sufficient to approximate the final level of sample saturation. The default value of sscycles is zero.

[Shim Step] Button

ShimIt does not perform a sensitivity analysis of the individual shims specified for optimization. Using this button the shimstep variable can be set interactively. This variable specifies the initial shim change for ShimIt to be used for the auto-shimming process. During the shimming the step size of each shim is automatically adjusted as needed. The default value of shimstep is 256.

The value for shimstep should be chosen so that each shim adjusted by the specified value causes a visible change in the shape of the displayed line. After ShimIt is started the program shows the starting spectrum and a spectrum for each selected shim with the requested initial shim change applied. If the effect of the shim change is either too small or too large the shimming process can be stopped with the [Stop] button in the main ShimIt menu, the best shim settings found so far can be recalled with the [Show Best] button in the main ShimIt menu, the shimstep variable can be adjusted using this [Shim Step] button, and the auto-shimming process can be restarted.

[# FIDs] Button

Using this button the max_fid variable can be set interactively. For an unattended shimming run this variable is useful to limit the time spend by ShimIt for auto-shimming. ShimIt works in logical iteration steps and each step can result in the acquisition of several FIDs. So when the specified maximum number of FIDs are acquired, ShimIt finishes the current logical iteration step and then terminates. Hence, the acquired number of FIDs can slightly exceed the number of FIDs specified by the max_fid variable. The default value of max_iter is 100 and the recommended value for fast shimming is eight times the number of selected shims to be optimized.

[Convergence] Button

ShimIt optimizes the moment of the displayed line. This [Convergence] button allows one to interactively specify the converge variable. This variable causes termination of the auto-shimming process when the smallest determined moment is estimated to lie within converge percent of its optimal value.

Notice that the stability of an NMR instrument and the finite S/N ratio of the spectrum limit the accuracy of determined moments. The default value of converge is 1%. A value for the order parameter of less than one decreases the fluctuation of the determined moment and the converge value should be decreased accordingly. Setting this variable to much less than the default value can significantly delay the convergence of ShimIt without further improvements in the magnet homogeneity.

[Order] Button

Lock-level shimming concentrates on maximizing the height of the lock signal. As a result the lock-level is quite effective for "touching up" the low-order z shims. Unfortunately, in all other cases lock-level optimization tends to run astray and to result in less than optimal lock-level maxima. ShimIt on the other hand optimizes the absolute-value (normally first) central moment of an observed line. This reliably minimizes the width of the base of a signal and minimizes remaining baseline distortions. Given an imperfect shim set, the maximum height and the best narrow base of a signal can frequently not be obtained simultaneously.

Many spectroscopists favor an improved signal height at the expense of a deterioration of the baseline and width of the signal base. The [Order] button allows one to interactively set the order parameter. This parameter determines the order of the (absolute-value) lineshape moment which ShimIt optimizes. Large order values favor flatter baselines and narrower signal bases while smaller order values lead to higher signals with generally smaller width-at-half-height values.

The default value of order is one, corresponding to the minimization of the first absolute-value central moment. The order parameter should be kept between 1 and 0.1. There seems to be no advantage of choosing an order parameter value above one. The second central moment of an absorption-mode Lorentzian line (order=2) is already infinite (for an infinite spectral width) causing instabilities of the shimming algorithm. Setting the order parameter to a negative value causes ShimIt to destroy rather than improve the magnet homogeneity.

It should be noted that only for order values of one (and higher) has it been proven that moment minimization always leads to the best magnet homogeneity. So order=1 should always be used until a good homogeneity has been found. If so desired the value of the order parameter can then be decreased (but kept above zero) to cause ShimIt to more strongly weight the height of the displayed resonance for the optimization.

[Timeout] Button

The VNMR client software of ShimIt was written solely based on the user documentation of the Varian spectrometer system. Besides an avoidable runtime overhead this also resulted in an asynchronous communication of ShimIt with both the spectrometer and the VNMR software.

Using the [Timeout] button the timeout variable can be set interactively. If the spectrometer has not successfully acquired a spectrum requested by ShimIt within timeout seconds or ShimIt has not analyzed an FID within this time frame the auto-shimming is aborted. The default value of timeout is 300 seconds.

[Return] Button

The [Return] button causes the menu system to return to the main ShimIt menu.

5.4 Displayed Shimming Results

During a shimming run ShimIt displays all variable settings, acquired spectra, and obtained analysis results. For further speed improvement, future versions of ShimIt will likely provide an option to reduce the amount of displayed information. While the ShimIt homogeneity optimization is in progress the VNMR display typically shows the following components:

The status line of the Menu window shows messages like "Experiment started". The graphic window is used to display the area of the current spectrum used for auto-shimming. Both phasing and current position of the analyzed spectral region are updated for every acquired FID. ShimIt does however not adjust the width of the displayed spectral area or the number of points in the analysis range. These changes can be automatically performed from macros which use ShimIt as their basic shimming engine, see CHAPTER 6: "Automated Shimming Example".

The values listed at the left side of the spectrum are ShimIt's analysis results of this spectrum. The Report line lists remarks from ShimIt about the currently displayed spectrum, such as the "Best Shims So Far" message displayed above. The FID # line shows the number of the current FID acquired for this shimming run. The displayed number is counted from minus the number of requested steady-state cycles (sscycles variable), over zero for the starting spectrum, to the number of acquired FIDs for the shim optimization.

The determined area of the displayed spectral region is listed in the Integral line. A decrease of the listed integral during a ShimIt run is normally due to progressive sample saturation. If the selected spectral area initially did not contain the complete signal intensity the integral might slightly increase as the magnet homogeneity improves. ShimIt always normalizes the absolute-value integral of the analyzed spectral area before determining the line moment and hence is fairly insensitive to modest integral changes.

Every acquired FID is phase corrected by adjusting the Varian zero-order phase parameter rp.8 The rp Phase line shows the currently used phase parameter. The shape of an NMR line is determined by the T2 relaxation time of the observed nucleus and the inhomogeneity of the current magnetic field. The Mn Width line shows ShimIt's estimate of what the width of the displayed line would be without magnetic field inhomogeneities.

The following three lines in the graphic window show the lineshape moment at start of ShimIt (Start Mo line), the best moment found so far (Best Mo line), and the moment of the currently displayed spectral area (This Mo line). Notice that ShimIt uses an iterative shimming approach and the moment of the currently displayed spectrum might in fact be worse than the best moment or even the starting moment. The Error Mo line provides an estimate of the percent uncertainty in the best moment determined so far. The error value is given after ShimIt has probed the sensitivity of the shims to be optimized and the value is then updated after each acquired FID. The listed error will decrease during shimming and hence is used in conjunction with the converge parameter as a termination criterion. The nonlinear nature of the optimization algorithm, and instabilities in both the instrumental response and the spectral analysis can cause the listed error value to fluctuate somewhat.

The bottom window ("alpha window") in the above figure lists the current ShimIt parameters and the values of the shims to be optimized for the displayed spectrum. For an explanation of the displayed parameters, see SECTION 4.2: "Magnet Specific Customization", SECTION 5.1: "ShimIt Main Menu", and SECTION 5.3: "Setup Submenu".

Created Files

ShimIt generates several files during a shimming run and stores them in directory $HOME/vnmrsys/ShimIt. When ShimIt is started all files from a previous shimming run are deleted. The first file generated is called start and contains all ShimIt and VNMR parameters relevant to the shimming run. In the file ShimIt.log written next are stored during a shimming run the spectrometer commands issued and the shimming results obtained. Finally, each FID acquired which constitutes an improvement in magnet homogeneity over all previous FIDs is stored in a directory called Best??.fid in $HOME/vnmrsys/ShimIt. Directory Best01.fid contains the starting FID and the Best??.fid directory with the highest number contains the best FID acquired so far.

1The ShimIt menu files are called shimit, shims, and params. Unfortunately, the menu name setup was already in use in VNMR 4.3.

2Currently VNMR and ShimIt read the acquired FIDs and FFT the data separately. This inefficiency causes most of the ShimIt response time for analyzing an FID.

3The z0 shim is used to compensate for magnetic field drifts, a process called "locking". This shim should not change the signal lineshape and hence is irrelevant for shimming.

4If a fine shim is specified in the list the corresponding coarse shim is automatically adjusted if the corresponding z?toz?c variable is set to a value greater than zero.

5As magnets using new shim sets become available this check mechanism will have to be extended or disabled.

6The menu file for the Setup submenu is called params since the name setup is used by VNMR 4.3 for other purposes.

7Strictly speaking, splitting a magnet shim into a coarse and fine "dial" is a function of both the software and the DACs used to generate the shimming currents and is not really a function of the magnet.

8ShimIt does not modify the user-set frequency dependent first-order phase parameter lp.

ScienceSoft, LLC