Reference

• 1: OVJ Commands
• 2: Pulse Programming
• 2.1: Pulse Elements
• 2.2: Phase Cycling
• 2.3: Pulse Sequence Parameters
• 2.4: ACODE
• 2.5: Hardware Control
• 3: OVJ Manuals

1 - OVJ Commands

General Command Structure

• OVJ commands are entered at the command line. Some commands require arguments or parameters, which can enclosed in parentheses.
• To change a parameter value, the parameter is entered followed by an equal sign (=), followed by the value of the parameter (real, integer, or string).
• String values are always enclosed in parentheses and surrounded by single quotes.
• Multiple command and parameter settings can be entered consecutively, separated by spaces.

Command Examples:

1
2
3

aph
wft
wft aph dc vsadj

Example of Setting a Parameter Value:

1
2

lb = 0.2
sampe = 'MySample'

Commonly Used OVJ Parameters

The following sections provide a list of commonly OVJ commands and parameters. For a complete list of commands see the VnmrJ Command and Parameter Reference.

Commands

Spectrometer Control and Data Acquisition Parameters

Data Processing and Display Commands

Plotting Commands

Parameters

Acquisition parameters

Processing and display parameters

2 - Pulse Programming

General Concept

Pulse sequences are written in C, a high-level programming language that allows considerable sophistication in the way pulse sequences are created and executed.

A new pulse sequence is written as a C function called pulsesequence. The file containing this function is compiled and linked with an object library that contains the definitions for all pulse-sequence statements, the PSG. A compiled C sequence is executed on the Linux workstation at the start of acquisition, so-called run-time. At run-time, the sequence reads values from a parameter table and constructs a second real-time program of acodes, whose purpose will be to run the SpinCore controller board.

The PSG library contains C code to run the pulsesequence function and to run spectra corresponding to arrays of parameter values. The user need not program these loops explicitly. At the start of the acquisition, all of the variables and statements of the compiled C program, including the C loops and conditionals, are resolved and fixed into acodes, without the possibility of further input or calculation. A complex program with many choices, using the C if-else-endifstatement, may resolve into a very few acodes, because the acodes in the non-selected branches are never created. A pulse program with multidimensional looping and/or parameter arrays will produce a separate set of acodes for every increment.

The real-time acode program is automatically looped over the number of scans for each multidimensional increment or array element. Special real-time integer tables, t1 to t10, are used to increment phases and other values that might change scan-to-scan. These tables and variables are initialized and manipulated by special pulse-sequence statements, the real-time math statements.

Writing pulse sequences

Pulse sequence text files are stored in a directory named psglib in either the system directory (/vnmr/psglib) or in a user directory (/home/vnmr1/vnmrsys/psglib for the user vnmr1). A pulse sequence file has the extension .c to indicate that it contains C language source code. Pulse sequences may also be saved in the psglib directory of an applications directory, which may have any name and path. An applications directory is made accessible through the Edit Applications tool of the Files pull down menu. A pulse sequence text file can be modified using the Linux tool vi, the standard Linux editor gedit, or by an available text editor or development package.

The template for all pulse sequences is:

1
2
3
4
5
6
7

#include "standard.h"

void pulsesequence()
{
  // Pulse elements

}

Since it is a C function, any C construction may be used. The available pulse elements are described below. For examples, see the pulse sequences in /vnmr/psglib

Compiling pulse sequences

After writing a pulse sequence, the source code is compiled by one of the following methods:

• By entering seqgen(filename<.c>) on the OpenVnmrJ command line.
• By entering seqgen on the OpenVnmrJ command line, with seqfil=‘filename’
• By entering seqgen filename<.c> from a Linux shell

For example, enter seqgen('s2pul') to compile the s2pul.c sequence in OpenVnmrJ. A full path is not necessary from the command line. Alternatively, you can enter

1

seqgen s2pul

in a Linux shell. The seqgen command will first search the user, then the available applications directories, and then the system for a file with a .c extension.

During compilation, the system performs the following steps:

1. Extensions are added to the pulse sequence to allow a graphical display of the sequence, using the dps command.
2. The source code is checked for syntax, variable consistency, and the correct usage of functions.
3. The source code is converted into compiled object code.
4. If the conversion is successful, the object code is combined with the necessary system PSG object libraries (libparam.so and libpsglib.so), to be linked at run-time. If the compilation of the pulse sequence with the dps extensions fails, the pulse sequence is recompiled without the dps extensions.

The executable code is stored in the user seqlib directory (e.g. /home/vnmr1/vnmrsys/seqlib). If the user does not have a seqlib directory, it is automatically created. A copy of the source code is also saved in vnmrsys/seqlib of the user directory. If desired, you can copy the compiled sequence to /vnmr/seqlib or to the seqlib directory in an applications directory.

Standard compiled sequences are supplied in /vnmr/seqlib and the source code for each of these sequences is found in /vnmr/psglib. To recompile one of these sequences or to modify it, first copy the sequence into the user psglib, make the required modifications, and then recompile the sequence using seqgen. Sequences can only be compiled from a user directory. If you attempt to compile a system sequence, a local copy will be created. The seqgenupdate command performs a seqgen as the first step, and will then attempt to move the resulting seqlib entries back to the application directory from which they were taken.

The source files that are used to create the PSG object library are contained in the system directory /vnmr/psg. In principle, a user can customize and recompile the PSG source files, but most users do not do so. It is easier to add the user source code in a separate file using the standard C #include statement. User #include files should be stored in the ~/vnmrsys/psg directory of a user or an applications directory.

2.1 - Pulse Elements

Pulse sequences are constructed from pulse elements, which specify controls for the NMR hardware. The “C-style” signature for these elements is defined below.

Delay

1
2
3

void delay(double time)
   # Delay for "time" seconds. If 0.0 is passed, the delay is ignored.
   # The minimum delay time is about 67 ns.

Examples:

1
2
3

delay(0.1);
delay(d1);
delay(d2/2.0);

Pulse

1
2
3
4
5

void pulse(double time, int phase)
   # Turn on the RF for duration of "time" seconds with the RF phase set to the
   # value of the "phase" argument. A delay of "rof1" is done prior to turning
   # on the RF pulse to allow the amplifier to switch on. A delay of "rof2" is
   # done following the pulse to allow for probe ring-down.

1
2
3
4

pulse(p1,zero);
pulse(pw,oph);
pulse(pw,PH90);
pulse(pw,t1);

Rgpulse

1
2
3
4
5
6

void rgpulse(double time, int phase, double rg1, double rg2)
   # Turn on the RF for duration of "time" seconds with the RF phase set to the
   # value of the "phase" argument. A delay of rg1 is done prior to turning
   # on the RF pulse to allow the amplifier to switch on. A delay of rg2 is
   # done following the pulse to allow for probe ring-down.
   # rgpulse(p1,zero,rof1,rof2) is equivalent to pulse(p1,zero).

1
2
3
4

rgpulse(pw,oph,rof1,rof2);
rgpulse(p1,zero,rof1,0.0);
rgpulse(pw,PH90,1e-6,0.0);
rgpulse(pw,t1,1e-6,rof2);

Offset

1
2

void offset(double frequency)  // Not yet implemented
  # Offset the RF frequency to the supplied value.

Acquire

1
2
3
4
5
6

void acquire(double datapnts, double dwell)
   # Start acquiring data points. The number of data points is defined
   # by the np parameter. The dwell period to acquire one complex pair is 1/sw.
   # A delay of alfa is done prior to the acquire to account for filter
   # delays. If a pulse sequence does not include an acquire pulse element,
   # one will be automatically added at the end of the sequence.

1

acquire(np, 1.0/sw);

Power

1
2
3
4
5
6
7

void power(double amp)
  # Control the power of the amplifier during an RF pulse. The supplied
  # amp can be in the range of 0.0 (no power) to 100.0 (full power).
  # The power adjustment uses the pulse shaping capability of the SpinCore
  # board. The power controls the amplitude of a rectangular shaped pulse.
  # Only four power levels can be used, one of which is the full power
  # pulse.

Settable

1
2
3
4
5
6

void settable(int table, int cnt, int phases[])
  # The "table" argument is one of the phase table names t1-t10.
  # The "cnt" argument is the number of phase elements to be assigned
  # to the phase table. It is the number of elements in the array specified
  # by the third argument.  The phases[] arguemnt is a pre-defined array
  # of phase elements. For an example, see the "Phase cycling" section.

Status

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

void status(int state)
  # Controls the on/off state of the microwave source. The microwave source
  # is selected by the systemglobal bnc, which can be set with the config
  # program to BNC0 or BNC1. The parameter xm controls the on/off state.
  # It can have multiple states: status(A) sets the status described by
  # the first letter of the xm parameter, status(B) uses the second letter,
  # etc. If a pulse sequence has more status statements than there are
  # letters in the xm parameter, control reverts back to the last letter
  # of the parameter value. For example, xm='nyn' will turn the microwave
  # source off during status A, on during status B, and off during
  # status C. Any status higher than C (D-Z) will select the final character
  # of the xm string (n) and turn the microwave source off.

  # The states do to need to increase monotonically during a pulse
  # sequence. One can write a pulse sequence that starts with status(A),
  # goes later to status(B), returns to status(A) and then goes to status(C).

1
2
3

status(A);
delay(d1);
status(B);

Getstr

1
2
3
4
5
6
7
8

void getstr(const char *variable, char buf[])
void getstrnwarn(const char *variable, char buf[])
  # Get the value of a string parameter. The first argument is the name
  # of the string parameter and the second argument is a character array
  # of length MAXSTR. If the parameter does not exist, a null
  # string is returned. The getstr() element will give a warning if the
  # parameter does not exist. The getstrnwarn() will not give a
  # warning if the parameter does not exist.

1
2

char myFlag[MAXSTR];
getstr("flag", myFlag);

Getval

1
2
3
4
5
6
7

double getval(const char *variable)
double getvalnwarn(const char *variable)
  # Get the value of a real valued parameter. The argument is the name
  # of the parameter.  If the parameter does not exist, a 0.0
  # is returned. The getval() element will give a warning if the
  # parameter does not exist. The getvalnwarn() will not give a
  # warning if the parameter does not exist.

1

double myVal = getval("val");

2.2 - Phase Cycling

There are several phase variables that control the phase of RF pulses and the phase of the receiver. These are:

• zero, one, two, three
• t1, t2, t3, t4, t5, t6, t7, t8, t9, and t10
• oph

The constants PH0, PH90, PH160, PH270 are used to select the 0, 90, 180,and 270 degree phase. The constants ZERO, ONE, TWO, and THREE similarly represent the 0, 90, 180, and 270 degree phase. These are present for compatibility with Varian/Agilent pulse sequences.

There are also phase tables t1-t10 and oph. These tables may contain any number of phase elements. The particular element used is determined by the current transient (CT) being acquired. The tranisients increment from 0 to (nt-1) where nt is the total number of transients.

The zero, one, two, and three phase variables are initialized to ZERO, ONE, TWO, and THREE, respectively. The oph phase table controls the phase of the receiver. It is initialized to the four values {ZERO,ONE,TWO,THREE}, which represents the “cyclops” phase cycle. The t1-t10 tables are only used if they are defined by the pulse sequence.

The cp parameter (cycle phase) is typically set to ‘y’. If it is set to ’n’, the cycling of the receiver phase (oph) is turned off. That is, only the first element of the oph table is used. This is usually only used during FID shimming and wobble.

The second argument to the pulse element is the phase. For example:

1

pulse(pw, zero);

That second argument can to zero, one, two, or three. Equivalently, it can be PH0, PH90, PH180, or PH270. It can also be oph, in which case the phase of the pulse tracks the receiver phase. Phase tables t1-t10 can also be used. For example:

1

static int ph1 = {PH0, PH180, PH90, PH270};

1
2
3
4
5
6
7
8
9

void pulsesequence()
{
   ...

   settable(t1,4,ph1);

   pulse(pw,t1);

}

By setting oph to a table, one can alter the receiver phase.

1

settable(oph,4,ph1);

2.3 - Pulse Sequence Parameters

The following parameters are used by all pulse sequences. The global parameters do not exist and the defaults are the normal values.

Experiment parameters used by all pulse sequences include:

1
2
3
4

if (ix % 2)
        status(A);
else
        status(B);|

Other parameter associated with a pulse sequence are used within the pulse sequence itself. For example, the s2pul.c pulse sequence uses

If custom parameters are defined for a pulse sequence, their values may be obtained with the getval() and getstr() pulse elements.

Processing parameters:

2.4 - ACODE

ACODE generation

When the OpenVnmrJ “go” command is executed, the parameter seqfil is used toselect the pulse sequence to execute. For example, if seqfil=‘s2pul’, then a binary file named s2pul is looked for in ~/vnmrsys/seqlib and /vnnmr/seqlib. If it is found, it is started and the parameters from the “joined” experiment, along with the global parameters are sent to the s2pul binary. The s2pul program then generates a set of acodes, based on the parameters and the details of the pulsesequence function. The acodes are keyword - value pairs. For example, running s2pul with just a single transient (nt=1) may generate a set of acodes such as

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

DEBUG 0
BOARD_NUMBER 0
BLANK_BIT 2
BYPASS_FIR 1
ADC_FREQUENCY 75
FILE /home/vnmr1/vnmrsys/exp2/acqfil
ARRAYDIM 1
MPS ext
PULSEPROG_START 1
SPECTROMETER_FREQUENCY 14.0005
NUMBER_POINTS 32768
NUMBER_OF_SCANS 1
SPECTRAL_WIDTH 8012.82
POWERS 1 1000 -1 -1 -1
PULSE_ELEMENTS START
PHASE_RESET 1
DELAY 1
PULSE 4.9e-06 0 1e-05
DELAY 3.4875e-05
ACQUIRE 0
PULSEPROG_DONE 1

The values following each keyword are determined from the parameters that were sent to the pulse sequence program (s2pul). The acodes are reproduced below with the operative parameters noted.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

DEBUG 0                               "debug flag set by whether go or go('debug') is called"
BOARD_NUMBER 0                        "global B12_BoardNum parameter"
BLANK_BIT 2                           "global B12_BlankBit parameter"
BYPASS_FIR 1                          "global B12_BypassFIR parameter"
ADC_FREQUENCY 75                      "global B12_ADC parameter"
FILE /home/vnmr1/vnmrsys/exp2/acqfil  "exppath parameter"
ARRAYDIM 1                            "arraydim parameter"
MPS ext                               "mps parameter"
PULSEPROG_START 1                     "keyword indicating start of experiment."
                                      "Index indicates which array element is being collected"
                                      "It would range from 1 to ARRAYDIM."

SPECTROMETER_FREQUENCY 14.0005        "sfrq parameter"
NUMBER_POINTS 32768                   "np parameter"
NUMBER_OF_SCANS 1                     "nt parameter"
SPECTRAL_WIDTH 8012.82                "sw parameter"
POWERS 1 1000 -1 -1 -1                "values of the shaped pulse amplitudes"
PULSE_ELEMENTS START                  "Keyword indicating start of pulsesequence"
PHASE_RESET 1                         "Keyword to reset phases. Called once for each element in array."

DELAY 1                               "d1 parameter"
PULSE 4.9e-06 0 1e-05                 "pw parameter, first element of oph phase table, rof1 parameter"
DELAY 3.4875e-05                      "sum of parameters rof2 and alfa"
ACQUIRE 0                             "Keyword to trigger data acquisition. 0 argument is the"
                                      "current transient (ct). It ranges from 0 to NUMBER_OF_SCANS-1"
                                      "It is there to simplify acode parsing"

PULSEPROG_DONE 1                      "Keyword to indicate acodes for FID 1 is done."
                                      "It also is an instruction to get the data from the"
                                      "SpinCore system and save it to FILE"

Phase cycling is handled by incrementing the index used when accessing the phase tables. Note that the actual phase tables are not included in the acodes. Only the values of the indexed phase tables are in theacodes. To avoid multiple copies of the acodes where the only differences are the phase values, the PSG first scans the pulse sequence to determine the longest phase cycle used, and then uses the SpinCore looping mechanism to loop over the pulse elements the proper number of times.

To illustrate, the following are the acodes for s2pul with nt=10. The longest phase cycle used by s2pul is 4 for the receiver (oph) phase cycle. The acodes loop twice over four transients and then the remaining two transients follow. Acodes with no comments are the same as for the seqfil=‘s2pul’ and nt=1 case.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

DEBUG 0
BOARD_NUMBER 0
BLANK_BIT 2
BYPASS_FIR 1
ADC_FREQUENCY 75
FILE /home/vnmr1/vnmrsys/exp2/acqfil
ARRAYDIM 1
MPS ext
PULSEPROG_START 1
SPECTROMETER_FREQUENCY 14.0005
NUMBER_POINTS 32768
NUMBER_OF_SCANS 10                    "nt parameter"
SPECTRAL_WIDTH 8012.82
POWERS 1 1000 -1 -1 -1
PULSE_ELEMENTS START
PHASE_RESET 1
NSC_LOOP 2                            "keyword to loop over the following acodes 2 times"
                                      "the end of the looping section is denoted"
                                      "by the NSC_ENDLOOP keyword"
DELAY 1
PULSE 4.9e-06 0 1e-05                 "pulse with phase 0"
DELAY 3.4875e-05
ACQUIRE 0                             "end of transient 0"
DELAY 1
PULSE 4.9e-06 1 1e-05                 "pulse with phase 1"
DELAY 3.4875e-05
ACQUIRE 1                             "end of transient 1"
DELAY 1
PULSE 4.9e-06 2 1e-05                 "pulse with phase 2"
DELAY 3.4875e-05
ACQUIRE 2                             "end of transient 2"
DELAY 1
PULSE 4.9e-06 3 1e-05                 "pulse with phase 3"
DELAY 3.4875e-05
NSC_ENDLOOP 10                        "Because of the way SpinCore programming works,"
                                      "the NSC_ENDLOOP is specified prior to the final"
                                      "acode in the loop." 
ACQUIRE 3                             "end of transient 3"
DELAY 1                               "Program the remaining two transients"
PULSE 4.9e-06 0 1e-05                 "pulse with phase 0"
DELAY 3.4875e-05
ACQUIRE 0
DELAY 1
PULSE 4.9e-06 1 1e-05                 "pulse with phase 1"
DELAY 3.4875e-05
ACQUIRE 1
PULSEPROG_DONE 1

Acquiring arrayed data sets involves multiple acode sets. This is illustrated in the following acode set for seqfil=‘s2pul’ and nt=1,4

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

DEBUG 0
BOARD_NUMBER 0
BLANK_BIT 2
BYPASS_FIR 1
ADC_FREQUENCY 75
FILE /home/vnmr1/vnmrsys/exp2/acqfil
ARRAYDIM 2                            "acquire 2 FIDs"
MPS ext
PULSEPROG_START 1                     "Start acodes for FID 1" 
SPECTROMETER_FREQUENCY 14.0005
NUMBER_POINTS 32768
NUMBER_OF_SCANS 1
SPECTRAL_WIDTH 8012.82
POWERS 1 1000 -1 -1 -1
PULSE_ELEMENTS START
PHASE_RESET 1
DELAY 1
PULSE 4.9e-06 0 1e-05
DELAY 3.4875e-05
ACQUIRE 0
PULSEPROG_DONE 1                      "Finish acodes for FID 1"
PULSEPROG_START 2                     "Start acodes for FID 2" 
SPECTROMETER_FREQUENCY 14.0005
NUMBER_POINTS 32768
NUMBER_OF_SCANS 4
SPECTRAL_WIDTH 8012.82
POWERS 1 1000 -1 -1 -1
PULSE_ELEMENTS START
PHASE_RESET 1                        "No need for NSC looping elements"
                                     "since nt=4 is the same as the maximum"
                                     "phase cycle"
DELAY 1
PULSE 4.9e-06 0 1e-05
DELAY 3.4875e-05
ACQUIRE 0
DELAY 1
PULSE 4.9e-06 1 1e-05
DELAY 3.4875e-05
ACQUIRE 1
DELAY 1
PULSE 4.9e-06 2 1e-05
DELAY 3.4875e-05
ACQUIRE 2
DELAY 1
PULSE 4.9e-06 3 1e-05
DELAY 3.4875e-05
ACQUIRE 3
PULSEPROG_DONE 2                      "Finish acodes for FID 2"

ACODE interpretation

When the go command is executed, it generates the acode file as described above and a second file used by “the procs” to handle experiment queueing and monitoring. When the controlling Expproc determines that it is time to start an experiment, it checks its queue and starts B12proc, passing the name of the acode file to use.

The B12proc program reads the acode file line by line. Each keyword causes some action. Some keywords, such as BOARD_NUMBER, BLANK_BIT, BYPASS_FIR, ADC_FREQUENCY, FILE, NUMBER_POINTS, NUMBER_OF_SCANS, SPECTRAL_WIDTH, and POWER just set parameters. Other keywords cause SpinCore elements to be executed.

The PULSEPROG_START acode causes the SpinCore initialization functions to be called. It also initializes the internal current transient (ct) counter. The PULSE_ELEMENTS acode calls the pb_start_programming(PULSE_PROGRAM) SpinCore function.

The PULSEPROG_DONE acode calls the pb_stop_programming() function and also uses the pb_get_data() function to collect the data from the SpinCore board and save it to a file defined by the FILE keyword.

Other keywords, such as DELAY, PULSE, and ACQUIRE cause appropriate pb_inst_radio_shape() functions to be called .

2.5 - Hardware Control

Triggers of the SpinCore Board

The SpinCore board has four TTL lines, named Flag0 to Flag3. They have been assigned the following functions.

Receiver Attenuator

The “receiver attenuator” is a USB device controlled by the /vnmr/bin/mcl_RUDAT command. The range of values is 0 to 120 (in dB) in 0.25 steps. One can set the attenuator directly from a terminal with the command /vnmr/bin/mcl_RUDAT <value>.

The attenuator is controlled from a pulse sequence with the rattn parameter.

3 - OVJ Manuals

Below is a collection of Open VnmrJ manuals relevant to the Bridge12 SCN spectrometer. Many more manuals are available for Open VnmrJ. You can access those through the help menu in Open VnmrJ.