ScienceSoft, LLC

CHAPTER 4: VNMR ShimIt Installation

The VNMR 4.3 ShimIt software consists of macros, menus, and help files. These files need to be placed in directories recognized by VNMR as described in SECTION 4.1: "Installing Macros, Menus, and Help Files". ShimIt was written to work with all seven shim sets recognized by VNMR 4.3. Unfortunately, for some magnets Varian chose to generate the current for one magnet coil from two parameters, a coarse shim and a fine shim. Based on the setting of the VNMR shimset variable ShimIt knows which coarse shims are available. But the sensitivity ratio between coarse and fine shim varies between spectrometers and Varian failed to make these ratios accessible through software or even to document them. Hence, these sensitivity ratios might need to be determined and specified during the ShimIt software installation, as described in SECTION 4.2: "Magnet Specific Customization".

4.1 Installing Macros, Menus, and Help Files

The ShimIt macros should be placed in a VNMR recognized maclib directory, the menus in a menulib directory, and the help files in a help directory. To install ShimIt temporarily or for only one user the maclib, menulib, and help directories in $HOME/vnmrsys should be used. For the permanent installation for all users the maclib, menulib, and help directories in /vnmr should be used. The last possibility is to place the software anywhere in the filesystem and to set the UNIX PATH variable and various VNMR parameters accordingly.

The ShimIt software is distributed as a compressed tar file named shimit.tar.Z. The file contains the following directories and files:




First load the file shimit.tar.Z from the distribution medium. Consult your system administrator in case of problems. To simplify the following discussion it is assumed that shimit.tar.Z is loaded in the directory /tmp. Now install the software in one of the following three ways:

System-Wide Installation

To install the ShimIt software system-wide obtain root privileges using ("%" symbolizes the user prompt):

 % su

and specify the password. Then change the current directory to /vnmr ("#" symbolizes the root prompt) by typing:

 # cd /vnmr

and uncompress (zcat) and untar (tar xvf) the shimit.tar.Z file in the current directory by entering:

 # zcat /tmp/shimit.tar.Z | tar xvf -

This command installs all files in their intended places.

Single User Installation

To install the ShimIt software only for the current user issue the following commands:

 % cd $HOME/vnmrsys
 % zcat /tmp/shimit.tar.Z | tar xvf -

Installation In Unsupported Directory

To install the ShimIt software in an unsupported directory (here assumed to be /tmp) issue the following UNIX commands:

 % cd /tmp
 % zcat /tmp/shimit.tar.Z | tar xvf -

Notice that in contrast to the previous examples three new directories are created (help, maclib, menulib). The fastest approach to using an unsupported directory for the ShimIt installation is to link all files in the created directories to the corresponding VNMR directories which completes the installation of ShimIt files:

 % ln -s /tmp/help/* $HOME/vnmrsys/help
 % ln -s /tmp/maclib/* $HOME/vnmrsys/maclib
 % ln -s /tmp/menulib/* $HOME/vnmrsys/menulib

If links for these files are not desired the installation becomes more tedious. To increase the efficiency of the ShimIt software the "macros" shimit_SunOS and usleep_SunOS are actually binary programs. The ShimIt software is configured to search for these executables in the directories in the user's PATH variable, in $HOME/bin, $HOME/vnmrsys/maclib, /vnmr/bin, and /vnmr/maclib.

For UNIX to find the binary program in a non-standard directory either extend the PATH variable with:

 % PATH=/tmp:$PATH; export PATH   	(Borne and Korn shell)
 % set path = (/tmp $path)         	(C shell)

or copy, move or link both files to a recognized directory (here: the user's bin directory)

 % ln -s /tmp/maclib/shimit_SunOS $HOME/bin
 % ln -s /tmp/maclib/usleep_SunOS $HOME/bin

or modify the maclib/shimit_start and maclib/shimit_client macros to include the chosen directory in the PATH variable before calling shimit_SunOS and usleep_SunOS.

Finally VNMR has to be told where to search for the new menus, macros, and help files. So inside VNMR issue the following commands (ignore VNMR create warnings about already existing variables):


Known ShimIt Incompatibilities

In order to make the ShimIt submenus accessible from the VNMR menu system, a [ShimIt] button has to be placed in one of the existing menus. The ShimIt software contains a modified VNMR 4.3 main2 menu which allows one to start the ShimIt menu system. For VNMR sites using an already modified main2 menu both main2 files will have to be merged manually.

For reasons of speed all ShimIt computations are done in a binary program called (for Sun SPARC computers) shimit_SunOS and for timing purposes the binary program usleep_SunOS is used. These executables were build on a Sun SPARC running SunOS 4.1. In order to run the executables under Solaris 2.3 (SunOS 5.3) the "Binary Compatibility Package" which is part of the Solaris 2.3 environment has to be installed.

4.2 Magnet Specific Customization

One of the major strengths of ShimIt is that the software can shim magnets even when no reasonable starting values for the shims are know. To do so requires the knowledge of the range in which shim values can be adjusted, which coarse shims are available, and what the sensitivity ratio of present coarse to fine shims is. ShimIt uses the following global VNMR variables to provide information about the magnet used:

 sh_range      Maximum +/- range of shim values
 z1toz1c       Sensitivity ratio z1 fine to coarse shim
 z2toz2c       Sensitivity ratio z2 fine to coarse shim
 z3toz3c       Sensitivity ratio z3 fine to coarse shim
 z4toz4c       Sensitivity ratio z4 fine to coarse shim

VNMR 4.3 recognizes seven shim sets and for each of the recognized shim sets defines the maximum allowable shim range (sh_range) and which coarse shims are available for each. So ShimIt sets these variables automatically when the main ShimIt menu is displayed for the first time.1 For VNMR's shim sets 3, 4, 6, and 7 which have no coarse shims the ShimIt software installation is completed.

Both shim sets 1 and 2 have a z1c and z2c shim and shim set 5 has all four coarse shims (z1c, z2c, z3c, z4c). Varian failed to specify the sensitivity of fine to coarse shim values. So ShimIt sets the z?toz?c variables of unavailable coarse shims to minus one and to a default value of 20 for available coarse shims. The value twenty means that the corresponding coarse shim is assumed to have twenty times the effect of the corresponding fine shim.

Unfortunately, the default value is not sufficiently accurate for most spectrometers. The following table of sensitivity ratios was determined from the "Schematics Package" of the corresponding spectrometers:

 Spectrometer   shimset   z1toz1c   z2toz2c
 Unity-300         1       30.2      46.5
 VXR-500           2       24.95     19.55

Additional spectrometers will be added to the table as the corresponding values become available. Since the sensitivity ratio of coarse and fine shims is determined by the shimming hardware, the spectrometer vendor (Varian) should be able to provide missing values.2 This table is contained in macro shimit_init and to activate the appropriate definitions remove the double quotes from the appropriate lines.

An experimental procedure to estimate these sensitivity ratios is to change a coarse shim by a given number of steps and to determine how many steps of the fine shim are needed to compensate. The corresponding z?toz?c shim should be set to the absolute value of the number of determined fine shim steps divided by the number of coarse shim steps. Once these variable values have been determined they should be entered in macro shimit_init so each user will get the determined sensitivity ratios by default.

1To have ShimIt recognize a so far unknown shim set or to customize an already defined shim set the macro shimit_init and the menu file shims have to be customized accordingly.

2ShimIt can be configured to ignore a coarse shim by setting the corresponding z?toz?c variable to -1 or to only use the coarse shims by setting the variable to 1.

ScienceSoft, LLC