Embed Size (px)
Citation preview
Varian NMR Systems
User Programming
User Programming Course Outline
INTRODUCTION
Resource materialsVNMRJ structureUser Interface
BASIC SYSTEM ADMINISTRATION
The Windowing EnvironmentEditors
PULSE SEQUENCE PROGRAMMING
hardware interactionbeginning Cbasic pulse sequencesadvanced sequences
MAGICAL II
macros
BASIC CONCEPTS of VNMRJ
Varian NMR Systems
User Programming
Putting it all Together
Pulse Sequence Programming
• Pulse sequence itself
• setup macro
• parameter set customizations
• Adding to GUI
• processing macros
• Controlling Pbox
Varian NMR Systems
User Programming
Introduction
Resource Materials
On the Spectrometer
man(subject)help(subject)VNMR on-lineVNMR news/E-mailEXISTING CODE & FILES !!!!
Hard copy - referenceCommand & Parameter ReferenceUser Programming
Resource Materials
Hard copy - "how to"
System Operation
Guide to NMR Experiments
System Administration
VNMRJ Pulse Sequences
User Guide: Liquids NMR
User Guide: Solids NMR
User Guide: Imaging
Varian NMR Systems
User Programming
Introduction
VNMR Structure
Equivalent Paths
/export/home/user/vnmrsys = ~/vnmrsys = userdir = $vnmruser
Each unique NMR user area
/export/home/vnmr = /vnmr = systemdir = $vnmrsystem
System VNMR Software area
In VNMR
In Shell
Varian NMR Systems
User Programming
VNMR directories/files
Conpar
System configuration:
contains critical system parameters
number and type of channels
shim set type
lock frequency
.....
Varian NMR Systems
User Programming
VNMRJ directories/files
Conpar
UNITY+, INOVA and VNMRS systems autoconfigure,
Gemini 2000, Unity, VXR-S systems cannot autoconfigure
Varian NMR Systems
User Programming
VNMR directories/files
devicenames - printer names - used by VNMR
/vnmr/bin/adddevices is used to add new devices
Varian NMR Systems
User Programming
VNMRJ directories/files
psglibsource code for pulse sequences
seqlib
compiled pulse sequences
Use the User equivalent directories for modifications
shapelibshaped pulse files
shimsshim files
Varian NMR Systems
User Programming
VNMRJ directories/files
maclibMAGICAL macros used by the system
templatestext files controlling VNMRJ parameter pages and interface
parlibParameters for individual experiments
cosy.par, noesy.par
this directory is actually linked to one of the directories par200 - par750
stdpar
Nucleus parameter filese.g. H1.par, C13.par
Varian NMR Systems
User Programming
Basic System Administration
The Windowing Environment
Editor
Varian NMR Systems
User Programming
The X Windows Environment
What is X Windows?
X is a standardized windowing
environment . X has the advantage
that it separates the functions of
computation and display.
Nomenclature
The computer that you are using as
a display is the X Client (X
terminal).
The computer that is running the software is the X Server.
The X Server and X Client may either be the same or different.
Varian NMR Systems
User Programming
The X Windows Environment
Where the X Server is not the same computer as the X Client, the
two are normally connected via ethernet.
It is not simple to connect via serial ports!
Varian NMR Systems
User Programming
Editors
Although strictly not necessary, an editor
makes life much easier when using the
system.
You will use an editor for
writing macros
writing menus
writing pulse sequences
other VNMRJ text manipulations
Unix/Linux text manipulations
There are a number of editors available.
The two that are used most are
textedit - a mouse driven editor
vi - a character based editor
Varian NMR Systems
User Programming
Editors
The choice of an editor is somewhat governed by the use
to which it is put:
vi is generally used by software engineers. It is
keyboard-controlled only, but is efficient.
Text based editor is generally used by people used to PC based packages. Example – dtpad (/usr/dt/bin/dtpad)
Varian NMR Systems
User Programming
Editors
The default editor in VNMRJ is vi!
You can change this default by setting the environmental variable
vnmreditor in your .login file.
For example, setenv vnmreditor dtpad
VNMR will use dtpad the next time you login
See the CPR (for example - macroedit)
Varian NMR Systems
User Programming
A few Vi Editor CommandsInsert mode
i - insert before cursor
a - insert after cursor
o - insert on newline
ESC to exit insert mode
Command mode
dw - delete word
dd - delete line
cw - change word
u - undo
/ - search forward
n - next occurrence
Y- yank line
P - put yanked line above cursor
p - put yanked line below cursor
:w - write file
:q - quit
:q! - force quit no write
:wq - write and quit
:r - read
ZZ - write and quit
CTRL-d - scroll forward
CTRL-u - scroll back
CTRL-f - next screen
CTRL-b - previous screen
use arrow keys to navigate within screen
Varian NMR Systems
User Programming
textedit
dtpad is much more of a wysiwyg editor. It uses the
mouse and the left keypad to operate.
Text based editor is OS specific.
Linux system can use the editor from the toolbar
Varian NMR Systems
User Programming
Pulse Sequence Programming
Syllabus
Pulse sequence execution
Hardware issues
Programming & compilation of sequences
Pulse sequence statements
Phase and other calculations
Access to parameters
Advanced programming
Varian NMR Systems
User Programming
Pulse Sequence Execution
When “go” runs:
go is a macro which looks first for a
macro usergo and executes it if it
exists.
Next, go looks for a macro go_{seqfil}
and executes it if it exists.
go next executes the Acq program
which looks up parameters in the
current experiment, then runs a program stored in seqlib ({seqfil} ) which outputs a series of instructions (A-codes).
The A-codes are downloaded to the acquisition computer.
The A-codes describe 1 transient and the number of times it must be repeated to acquire 1 fid.
There is a set of A-codes for
each fid in an array
each increment in a nD experiment
Varian NMR Systems
User Programming
Pulse Sequence Execution
"run" time execution
Some calculations are executed only once
when program runs.
This value is used for rest of pulse sequence
and does not change, for example -
tau = 1.0/(2.0*J);
This is a run time statement.
Run-time statements are evaluated and
executed in the host.
“real time” execution
Some calculations must occur during
execution.
For example, the steady state counter ct is
updated for each transient
add(one,ct,v4);
This is a real time statement
Real-time statements are evaluated and executed in the acquisition system.
Varian NMR Systems
User Programming
gating
Pulse execution requires hardware to be turned on or off.
transmitter gateamplifier blanking gateLO gatereceiver gate
Varian NMR Systems
User Programming
Event timing
A finite amount of time is required to gate the
hardware. Communication may occur via the AP bus
(frequency setting), RS232 ports (VT Unit) or high
speed lines (pulses). This is system specific:
INOVA or previous: uses AP bus
VNMRS: no AP bus
Varian NMR Systems
User Programming
AP Bus timing
AP bus instructions incur a delay of 0.5 s on INOVA, 1.15µs on U+,
1.2 s on Mercury, 2.15 µs on Unity, VXR-S and Gemini 2000.
Each instruction is one or more FIFO events
Multiple events may be required by a statement
Delays associated with statements in UP chapter 2
Exact delays are accessible in /vnmr/psg/apdelay.h
Varian NMR Systems
User Programming
Unity Inova RF
Varian NMR Systems
User Programming
PTS: Resolution- 0.1 Hz
Phase: 0-360 in 0.25 degree steps
Amplitude: 60 dB in 0-4095 linear steps
RF Attn: 79 dB: -16-63 in 1 dB steps
Filters: 8 pole quasi elliptical
ADC: 16 bit-500kHz
Unity Inova RF
Varian NMR Systems
User Programming
PTS: Resolution- 0.1 Hz
Phase: 0-360 in 0.25 degree steps
Amplitude: 60 dB in 0-4095 linear steps
RF Attn: 79 dB: -16-63 in 1 dB steps
Filters: 8 pole quasi elliptical
ADC: 16 bit-500kHz
INOVA RF
Varian NMR Systems
User ProgrammingVNMRS RF
PowerPC
EB
CD
MA
RS2
32E
ther
net
SDRAM(Error Correcting)
64 MbFlash32 Mb
IntC
RF Math
FIFO & Timer
GPIO
GPIO
IntC
SyncIN
Con
fig
FPGA RF Aux
Register Decode
EB
CInstruction
FIFO
Attn, Synth, Users
RF Transmitter
Sync
VarianDDR –
20 MHz IF sampled directly at
80 MHz rate
RF Attenuator
Varian NMR Systems
User Programming
Pulse Sequence Programming
1. Pulse Sequences are written onto a framework of
the C programming language.
2. Extensive knowledge of the C programming
language is NOT necessary to write pulse
sequences.
3. Pulse sequence source code is created with vi or
your favorite editor and stored in psglib. Each
defined user may have his or her own psglib.
4. Unlike macros, pulse sequences must be
compiled before they can be used. Compiled pulse
sequences are found in seqlib. Only the system
manager may put compiled sequences into the
system seqlib.
Varian NMR Systems
User Programming
User Friendly Sequences
1. Each pulse sequence should have its own setup macro that accesses any needed parameters.
2. Pulse sequence specific parameters should be stored in the library parlib.
3. Each pulse sequence should have its help file that explains what parameters are and what values are reasonable for the parameters.
Varian NMR Systems
User Programming
C Framework
The syntax for a pulse program
is as follows:
#include <standard.h>
pulsesequence()
{
pulse sequence statements ....
}
a. Each sequence must begin with the
#include <standard.h> declaration.
b. The body of the pulse sequence follows
the first { . Each statement must be
terminated by a semicolon.
c. Any new variables must be declared.
d. The pulse sequence ends with }.
Varian NMR Systems
User Programming
Basic C for Pulse Sequence Programming
Most statements take the form
statement(argument);
Most arguments are real numbers and can be represented as:
Variables - example d1constants - example 5.2expressions - example 2.0*pw
Varian NMR Systems
User Programming
Basic C for Pulse Sequence Programming
You can declare any
number of new variables
for use as parameters.
Variables must be of a
specific type:
Types
char character 8 bits
short short int 16 bits
int integer 32 bits
float floating point 32 bits
double double precision fp 64 bits
Shape character (only
with Pbox_psg.h )
Varian NMR Systems
User Programming
Basic C for Pulse Sequence Programming
Most real numerical variables will be of type double
Integers will be of type int
strings (like dmm) will be of type char with dimension MAXSTR
An example is
double j1hx,tau1; or
Double j1hx=getval(“j1hx”);
char fad[MAXSTR];
Varian NMR Systems
User Programming
Pulse Sequence Compilation
The pulse sequence is a program that is compiled by issuing a command
seqgen filename or seqgen filename.c
This adds dps extensions
It checks for syntax errors
It combines the pulse sequence function with necessary psg object libraries
to produce executable code which is stored under the name filename in
~/vnmrsys/seqlib
Varian NMR Systems
User Programming
Pulse Sequence Statements
Pulse sequences may contain:
PULSES
DELAYS
RECEIVER control statements
PHASE calculations
POWER control statements
XMTR, DECPLR gate control
AP tables
miscellaneous statements
Varian NMR Systems
User Programming
Control Statements
Math statements
Boolean Logicif (dm[0]==‘n’) statement; /* C language */
Loopsfor (i=0,i<count,i++) statement; /* C language*/loop(v1,v2); /* unity real time loop*/ endloop(v2);loop(2,v1,v2); /* G2000 rt loop*/ endloop(2);starthardloop(v10); /*not G2000 -hardware loop*/ endhardloop();
C statementstpwr=tpwr+6.0; i3++;
Varian NMR Systems
User Programming
DELAY Statements
delay(time); - Time must be a REAL number.
hsdelay(time); - Homospoil delay using z1 shim coil.
Actual homospoil time is controlled by the parameter hst. (The use of this
statement has largely been superceded by the use of pulsed field gradient
pulses.)
Examples
delay(d1);
hsdelay(d1); /* will give homospoil of hst in the d1 delay if hs=‘y’ */
Varian NMR Systems
User Programming
DELAY Statements
vdelay(timebase,count);
timebase can be NSEC,USEC,MSEC or SECcount must be a real time variabledelay length for NSEC timebase is 100 + (count)*resolution nsec.Resolution = 12.5 ns for INOVA. If count = 4, the delay wouldbe (100 + (4*12.5)) or 150 ns.
Example
vdelay(NSEC,v5); /*normal syntax*/
Varian NMR Systems
User Programming
DELAY Statements
initdelay & incdelay enable real-time
incremental delays
initdelay(time_increment,index);
Initializes the time increment and
delay index.Index is one of the indices DELAY1,DELAY2,...,DELAY5.
incdelay(count,index);
count must be a real time variable
Example
initdelay(mintau,DELAY3);
incdelay(v4,DELAY3); /*will delay v4*mintau */
Varian NMR Systems
User Programming
PULSE Events
The state of the receiver determines the
state of:
Preamplifier blanking
Transmitter blanking
RF
Receiver Gate
Transmitter Gate
rof1pw
rof2
Varian NMR Systems
User Programming
PULSE (Observe Channel) Statements
rgpulse(pulsewidth,phase,RG1,RG2); -
Receiver Gated PULSE. RG1 and RG2 are
often set as rof1 and rof2. The receiver is
gated off by RG1 microseconds before the
pulse and gated back on RG2 seconds after the
end. Pulse width must be a REAL number or
expression.
Example
rgpulse(pw,oph,rof1,rof2);
simpulse(obswidth,decwidth,obsphase,decphase,
RG1,RG2); Performs simultaneous pulse on
channels 1 and 2 (the “decoupler” and observe
channel transmitter).
Example
simpulse(pw,pp,oph,t3,rof1,rof2);
Varian NMR Systems
User Programming
PULSE (Observe Channel) Statements
obspulse(pulsewidth); - Simple observe
PULSE. Receiver gates are rof1 and rof2.
Phase is automatically “oph”
Example obspulse(pw);
pulse(pulsewidth, phase); - Simple observe
PULSE. Receiver gates are rof1 and rof2.
Phase is specified by variable or constant.
Example pulse(pw, zero);
pulse(pw, oph);
Varian NMR Systems
User Programming
Non-Observe Channel Pulses
decrgpulse(width,phase,RG1,RG2);
pulsed at current power level of decoupler (channel 2).
if tn and dn have different amp bands, decoupler amp is CW
else decoupler amp is in pulse mode and blanked
dec2rgpulse - 3 rf channels
dec3rgpulse - 4 rf channels
Example
decrgpulse(pp,t4,rof1,0.0);
Varian NMR Systems
User Programming
POWER Control Statements
obspower(tpwr); Sets power of observe channel to value of tpwr.
Argument is a variable of type real.
Functionally the same as rlpower(tpwr, OBSch);
decpower(pwxlvl); Sets power of 1st decoupler to value of pwxlvl
dec2power(39); dec3power(value); …. Etc.
Varian NMR Systems
User Programming
Frequency Control Statements
Similar to power control statements…
The actual time for this statement varies with system type. Where timing is critical, make sure that you use the predefined variables from /vnmr/psg/apdelay.h
obsoffset(tof); decoffset(dof); , etc.
Varian NMR Systems
User Programming
GATING Control Statements
STATUS CONCEPT
Convenient way to pass parameter control into pulse sequences
status(state); controls decoupler and hs gating
state = A,B,...Z
dm, dmm,dm2,dmm2 etc. are under status control
dm = “Decoupler mode”
dmm = “decoupler modulation mode”
EXAMPLES:
dm=‘nny’ dm=‘ynn’ dm=‘y’
Varian NMR Systems
User Programming
REAL TIME Variables
v1 to v14 - Real time variables that are used in the calculation of loops, phases etc.
ct Completed transient counter. Starting point for most calculations
oph Observe receiver phase (0123). This can be changed by the user.
zero, one, two,three are 0, 90, 180, and 270 respectively.
bsctr Block size counter
Varian NMR Systems
User Programming
INTEGER Math
assign(vi,vj); set vj equal to vi
add(vi,vj,vk); set vk equal to vi+vj
sub(vi,vj,vk); set vk equal to vi-vj
dbl(vi,vj); set vj equal to 2*vi
hlv(vi,vj); set vj equal to integer part of 0.5*vi
mod4(vi,vj); set vj equal to vi mod 4
mod2(vi,vj); set vj equal to vi mod 2
incr(vi); increment vi by 1
decr(vi); decrement vi by 1
Varian NMR Systems
User Programming
Integer Math
modn(vi,vj,vk) set vk equal to vi mod vj
divn(vi,vj,vk) set vk equal to vi div vj
mult(vi,vj,vk) set vk equal to vi*vj
initval(value,vi) initialize vi to a specific value
Varian NMR Systems
User Programming
Integer Math
Example Calculations
mod2(ct,v1); v1 = 0101010...
dbl(v1,v2); v2 = 020202...
hlv(ct,v1); v1=0011223344...
hlv(v1,v2); v2=00001111....
dbl(v1,v1); v1=00220022...
add(v1,v2,v3); v3=00221133...
mod4(v3,oph); oph=00221133...
Varian NMR Systems
User Programming
Real Time Loops
loop(count,index)
endloop(index)
ifzero(vi)
elsenz(vi)
endif(vi)
The acquisition computer generates timer
words as determined by execution of these
commands.
EXAMPLE
mod2(ct,v1);
ifzero(v1);
delay(d2/2);
elsenz(v1);
delay(d2);
endif(v1);
Varian NMR Systems
User Programming
Phase-related Statements
phase may be changed before a pulse to
avoid settling delays
txphase(phase);
decphase(phase);
dec2phase(phase);
dec3phase(phase);
phase must be real time variable.
Example
decphase(three);
rgpulse(pw,oph,rof1,0.0);
decpulse(pp,three);
This example changes the decoupler phase to 270° before the observe channel pulse so that it is stable for the decoupler pulse which comes immediately after.
Varian NMR Systems
User Programming
Phase Cycling with Integer Math
Calculation of Exorcycle Phase
Cycle = 0000111122223333
hlv(ct,v1); /*v1=0011223344556677*/
hlv(v1,v2); /*v2=0000 1111 2222 3333*/
cycle = 0123 1230 2301 3012
mod4(ct,v3); /*v3=0123 0123 0123 0123*/
add(v1,v3,v3); /*v3=0123 1230 2301 3012*/
cycle = 0202 1313 0202 1313
mod2(ct,v4); /*v4=0101 0101 0101 0101*/
dbl(v4,v4); /*v4=0202 0202 0202 0202*/
mod4(v1,v5); /*v5=0011 2233 0011 2233*/
hlv(v5,v5); /*v5=0000 1111 0000 1111*/
add(v5,v4,v4); /*v4=0202 1313 0202 1313*/
Varian NMR Systems
User Programming
REAL-TIME AP Tables
table name is assigned one of the
variables t1 - t60
table name is separated from
statements
by = sign
elements are separated by white space
a. Tables can be used to store phase cycles,
arrays etc.
b. Tables are associated with the variables
t1-t60
c. The values stored must be integers in the
range -32767 to 32768
Example:
t1 = 1 2 3 0 2 3 0 1 3 0 1 2 0 1 2 3
use in pulse sequence
rgpulse(p1,t1,rof1,rof2);
Varian NMR Systems
User Programming
Phase Tables within Sequence
static int phasecycle[8]={0,2,1,3,1,3,2,0};
{
.
.
.
settable(t3,8,phasecycle);
Phase tables within pulse sequence are best when phase cycling is known.
This usage is also “self-documenting”, not relying on external table.
Phase tables from ~/vnmrsys/tablib are good for determining phase cycle.
Varian NMR Systems
User Programming
Example Pulsesequence
#include <standard.h>static int phasecycle[4] = {0, 2,1,3};pulsesequence(){status(A);hsdelay(d1);status(B);rgpulse(p1,zero,rof1,rof2);hsdelay(d2);status(C);settable(t1,4,phasecycle);rgpulse(pw,t1,rof1,rof2);setreceiver(t1);}
Varian NMR Systems
User Programming
Phase Table Summary
load table statements from text file…
loadtable(“ph1”);
or
declare an integer array in a table within the pulsesequence…static int ph1[8]={0,0,1,1,2,2,3,3};
pulsesequence(){ alwayssettable(tablename,numelements,intarray);settable(t1,8,ph1);
setreceiver(tablename) -cycle the receiver using the named table
setreceiver(t60);
Varian NMR Systems
User Programming
Access to parameters/variables
variables known to VNMRJ do not have to be declared
to be used in a pulse sequence
EXAMPLESalfa
d1,d2,d3,d4
dpwr
tpwr
pw, p1, pw90,.. Many more.
variables unknown to VNMRJ have to be declared
before use in a pulse sequence
Varian NMR Systems
User Programming
Access to Parameters
declared variables must be retrieved by the pulse sequence.
getval("parametername") - retrieves the value of the non-string parameter
parametername and makes it available in the pulse sequence. Syntax is
internalname=getval("parametername").
This is very important for parameters created for the experiment. For example
in the DEPT pulse sequence the parameter j1xh must be created and retrieved
for use by the pulse sequence.
example: j1xh = getval("j1xh");
Varian NMR Systems
User Programming
Example Pulse Sequence
#include <standard.h>
{
double jhh; /*declare the variable jhh*/
jhh = getval("jhh"); /*retrieve the variable*/
d3=1/(2.0*jhh); /*calculate a fixed delay using known variable d3 and jhh*/
mod4(ct,v1); /*v1 = 0123*/
mod2(ct,v2); /*v2 = 0101*/
dbl(v1,v2); /*v2 = 0202*/
delay(d1); /*d1 is a known variable*/
pulse(pw,v1); /*pw is known, v1 real time variable*/
delay(1/2.0*jhh); /*directly calculate delay*/
pulse(2.0*pw,zero); /*calculate a 180*/
delay(d3); /*use previously calculated delay*/
}
Varian NMR Systems
User Programming
Exercise
Write the following pulse sequence:
delay - 90 - delay -180 - acquire
with phases:180 degree pulse = X90 = 3201 3201 3201 3201Receiver = 1230 1230 1230 1230
Varian NMR Systems
User Programming
Exercise
Write the phase sensitive homonuclear 2D pulse sequence pecosy.
d1 - 90(ph1) - t1 - 35(ph2) - acquire [even transients]
d1 - 90(ph1) - t1 - delaypw90time - acquire [odd transients]
Ph1 = 0 0 0 0 2 2 2 2 1 1 1 1 3 3 3 3
Ph2 = 0 2 2 0 0 2 2 0 1 3 3 1 1 3 3 1
Rec = 0 2 0 2 2 0 2 0 1 3 1 3 3 1 3 1
Varian NMR Systems
User Programming
PECOSY - declare variables
/* primitive ecosy.c - L. Mueller J.Magn. Reson. 72,191-196 (1987).
Version 1.0 phases are as implemented by Nemeth and Cheatham MRC 91 */
#include <standard.h>
static int ph1[16] = {0,0,0,0,2,2,2,2,1,1,1,1,3,3,3,3},
ph2[16] = {0,2,2,0,0,2,2,0,1,3,3,1,1,3,3,1},
recph[16] = {0,2,0,2,2,0,2,0,1,3,1,3,3,1,3,1};
pulsesequence()
{
double sstrim;
int iphase;
sstrim = getval("sstrim");
phase = getval("phase")
iphase = (int) (phase + 0.5);
4 errors.. Let’s compile and see what happens!
Varian NMR Systems
User Programming
PECOSY Calculations & sspulse
mod2(ct,v10); /* 0101... counter for phase compensation */
settable(t1,16,ph1);
settable(t2,16,ph2);
settable(t3,16,ph3);
getelem(t1, ct, v1);
if (iphase == 2) /* hypercomplex F1 quadrature */
incr(v1);
if (sstrim != 0.0)
{
rgpulse(sstrim,zero,2.0e-6,2.0e-6);
rgpulse(sstrim,one,1.0e-6,2.0e-5);
}
Varian NMR Systems
User Programming
PECOSY - finish pulsesequence
status(A);
hsdelay(d1);
rgpulse(p1, v1, rof1,2.0e-6);
status(B);
delay(d2);
ifzero(v10);
rgpulse(pw, t2, 0.0, rof1); /* use pw=35 degrees for measuring couplings */
elsenz(v10);
delay(pw + rof1); /* compensate phase between diagonal and crosspeaks */
endif(v10);
setreceiver(t3);
status(C);
rcvron(); delay(rof1);
}
Varian NMR Systems
User Programming
Channel Independence
INOVA, UNITY+, VNMRS
Provided that only obspower, decpower etc. are used, generalized rf channel remapping is available through the parameter rfchannel
Example
rfchannel=‘213’ makes ch 2 observe, ch 1 decouple and ch 3 the 2nd decoupler
(Typically the case for Indirect detection experiments in modern spectrometers with 1H-only 2nd channel.)
Varian NMR Systems
User Programming
HARDWARE Looping
Hardware loop capability depends on type of acquisition hardware used on the system.
i. Output boards - limited hardlooping - 63 events
ii. Acquisition controller boards - 1024 events
iii. Unity plus/INOVA Pulse Sequence Generation boards - 2048 events
iv. VNMRS – no distinction between hardware and software looping
hardloop statements are executed as software loops
Varian NMR Systems
User Programming
HARDWARE Looping (U+ and INOVA)
Events
An event is a single activation of the timing circuitTime bases: 25ns (U, U+), 1µs, 1ms, 1sec, 12.5 ns (INOVA)maximum of two time bases per delaycounter goes from 2 to 4095 for each time base
Example a 35µs pulse is 1 event: 350 counts on 0.1µs time base
example a 542.4µs is 2 events: 542 counts on 1µs time base, 4 counts in .1µs time base
Varian NMR Systems
User Programming
HARDWARE Looping
starthardloop(numberofrepetitions)
endhardloop()
i. only pulses, delays, acquires allowed
ii. No nesting
iii. number of repetitions must be a real time variable
iv. for output boards it is usually necessary to insert a short delay (0.2e-6sec) between one endhardloop and a second starthardloop
v. the maximum number of points that can be acquired within a hard loop is
63 for output board
1024 for Aqc control board
2048 for Pulse Seq. Controller
Exampleinitval(loops,v3);starthardloop(v3);
endhardloop();
Varian NMR Systems
User Programming
HARDWARE Looping-Explicit Acquisition
Basic explicit acquisition sequence using hardlooping that permits other
statements during acquisition:
delay(alfa+1.0/(beta*fb)); /*beta delay for receiver*/
initval(np/2,v9);
starthardloop(v9);
acquire(2.0,1.0/sw);
endhardloop();
Varian NMR Systems
User Programming
Pulse Field Gradients
rgradient(gradient,amplitude)
gradient is coil direction (usually 'z‘)
amplitude is between 32K and -32K
This is used when psg statements are
used during gradient, or when gradient is
along x or y directions.
Example
rgradient(‘z’,4000);
delay(gt1);
rgradient(‘z’,2000);
delay(gt2);
rgradient(‘z’,0.0);
zgradpulse(amplitude,width)
gives a pulse-like element for z-axis pfg gradient pulses.
amplitude is within ±32K
width is in seconds
Example
zgradpulse(gzlvl1,gt1);
Varian NMR Systems
User Programming
Pulse Sequences: A Closer look
psg - contains source code for statementsheader (xx.h) files contain constants and definitionsexample: apdelay.h - times for ap delays
/vnmr/psg
Varian NMR Systems
User Programming
New Functions
New functions can be created in psg as xxx.c and referenced as an include file.
These functions may be coded directly into the sequence or placed on top of pulse sequence as an include statement.
#include <standard.h>#include <myroutine.c>
Varian NMR Systems
User Programming
Small Angle Phase Shifts
stepsize(base,device);
sets the step size of the s.a.phase shift
stepsize(60.0,TODEV); /*60 degree step size for obs xmtr*/
This does function, but now replaced!
obsstepsize(30.0);
decstepsize(45.0);
dec2stepsize(60.0); etc..
Varian NMR Systems
User Programming
Small Angle Phase Shifts
EXAMPLE
obsstepsize(60.0);
initval(6.0,v1);
modn(ct,v1,v2); /*v2 = 012345012345*/
xmtrphase(v2); /*phase = 0,60,120,180,240,300*/
carry over = 0,0,90,180,180,270
mod4(ct,v3);
pulse(pw,v3); /*specified phase = 0,90,180,270*/
actual = 0,90,270,450,180,360actual = specified + carry over
Varian NMR Systems
User Programming
Small Angle Phase Shifts
xmtrphase(multiplier);
dcplrphase(multipler);
dcplr2phase(multiplier);
multiplier must be a real time variable
multiplier * base = phase
If the product of (base*multiplier) is greater than 90, the sub-90 part of the phase is set by xmtrphase..
Varian NMR Systems
User Programming
Pulse Shaping
Files are in shapelib
Files are simple text files with an extension
.RF – rf pulses
.DEC – decoupling or spin locks
.GRD - gradients
Varian NMR Systems
User Programming
Multifrequency excitation
Varian NMR Systems
User Programming
How to generate a shaped pulse?
Shaped pulse is a series of rectangular pulses with different amplitude and/or phase
Varian NMR Systems
User Programming
How to generate a shaped pulse?
Provide amplitude and phase information in a
“Table”. Drive amplitude and phase modulators
Standard on ALL channels
AmplitudeControl
PhaseControl
PhaseModulator
IF
LO
RF
4096 linear steps over 60 dB
0.25o steps (INOVA)0.043o steps (VNMRS)
RF transmitter/modulator
Varian NMR Systems
User Programming
How to generate a shaped pulse?[INOVA]
Provide amplitude and phase information as a “Table” to a Waveform Generator
Optional for ALL channels
AmplitudeControl
PhaseControl
PhaseModulator
IF
LO
RF
RF transmitter/modulator
Con
trol
& lo
o pin
g
Duration
Amplitude
Phase
Waveform Generator
Transmitter Control
Varian NMR Systems
User Programming
How to generate a shaped pulse?[VNMRS]
Amplitude and phase information are stored in the RF Controller
Optional for ALL channels
AmplitudeControl
PhaseControl
PhaseModulator
IF
LO
RF
RF transmitter/modulator
Duration
Amplitude
Phase
RF Controller Memory
Varian NMR Systems
User Programming
RF shape files
Phase amplitude duration gate
….. ….. ….. …..….. ….. ….. …..
Varian NMR Systems
User Programming
RF shape files[example]
Varian NMR Systems
User Programming
DEC shape files
tipangle phase amplitude gate
….. ….. ….. …..….. ….. ….. …..
Varian NMR Systems
User Programming
DEC shape files[example]
Varian NMR Systems
User Programming
Pulse Shaping
RF PATTERNS .. .RF
Column 2 - amplitude
Column 1 - phase
Column 3 - relative duration
Column 4 - xmtr gate
DECOUPLER PATTERNS.. .DEC
Column 1 - Tip angle per element
Column 2 - RF phase
Column 3 - Amplitude
Column 4 - Transmitter gate
Gradient Patterns.. .GRDcolumn 1 - signed magnitudecolumn 2 - relative durationcolumn 3 - gating
Varian NMR Systems
User Programming
Software Tools
Pbox [Pandora’s Box]
Pulsetool
MAGICAL macrosconvolute
setpowerattval
Varian NMR Systems
User Programming
PBox
Powerful tool to create pulse and decoupling patternsMenu drivenEasy to use Integrated into VNMR environment
Varian NMR Systems
User Programming
PBox
[/vnmr/wavelib]
wavelib
excitation
inversion
decoupling
Varian NMR Systems
User Programming
Shaped Decoupling[Execution] – programming issues
Using “status”
Programmed decoupling during status(C):
dm = ‘nny’dmm = ‘ccp’dpwr = decoupling powerdmf = appropriate numberdseq = ‘xxxxx’dres = appropriate value
dmf is “modulation frequency”dres – is the tip angle resolution in the decoupling shape
Get from Pbox generated xxxxx.DEC file
Varian NMR Systems
User Programming
Pulse Shaping
obsprgoff
decprgoff
dec2prgoff
turn off programmable control of device
normally will also need xmtroff() as well
Varian NMR Systems
User Programming
Pulse Shaping
obsprgon(name,pw90,tipangle_resol);start programmable control of xmtr
decprgondec2prgonThese statements will return an integer value of the number of 50 ns ticks in 1 cycle of the pattern. Explicit gating of the relevant transmitter is required.Example
int tix;
tix=obsprgon(“mlev16”,pw90,tres);
xmtron();
Varian NMR Systems
User Programming
Shaped Decoupling[Execution] – programming issues
Using in the sequence
…..decpower(xx);decprgon(decseq.name, 1/decseq.dmf, decseq.dres);decon();delay(z);decoff();decprgoff();decpower(yy);…..
Varian NMR Systems
User Programming
Shaped Decoupling[Execution] – programming issues
Using in the sequence [homonuclear decoupling]
…..obspower(xx);obsprgon(decseq.name, 1/decseq.dmf, decseq.dres);xmtron();delay(z);xmtroff();obsprgoff();obspower(yy);…..
Varian NMR Systems
User Programming
Pulse Shaping
shaped_pulse(shape,width,phase,RG1,RG2);
decshaped_pulse(shape,width,phase,RG1,RG2);
simshaped_pulse(obsshape,decshape,obswidth,decwidth,obsphase,decphase,RG1,RG2);
sim3shapedpulse(obsshape,decshape,dec2shape,obswidth,decwidth,dec2width,obsphase,decphase,dec2phase,RG1,RG2);
setting one of the pulsewidths to 0.0 will yield a 2-pulse on any channel combination.
Using “” in the shape name field will result in a normal rectangular pulse for that channel. This is useful when that channel does not have a waveform generator (INOVA), or when a normal rectangular pulse is desired.
Varian NMR Systems
User Programming
Pulse Shaping
spinlock control
spinlock(name,pw90,tipangle_resol,phase,ncycles);decspinlockdec2spinlockdec3spinlockExample
spinlock(“mlev16”,pw90,tres,one,4);
Varian NMR Systems
User Programming
Pulse Shaping
Statements for AP Bus
These provide wfg capability for INOVA & Unity plus systems without a
waveform generator being used.
apshaped_pulse(pattern,width,phase,power,phasetable,rg1,rg2);
apshaped_decpulse
apshaped_dec2pulse
Example
apshaped_pulse(“sinc”,pw,oph,t14,t9,rof1,rof2);
Shaped_pulse, decshaped_pulse, etc..now do this automatically!!
Varian NMR Systems
User Programming
Excitation Sculpting[Double Pulse Field Gradient Spin Echo – DPFGSE]
Shaka, et. al., JACS, 117, 4199 (1995)
DPFGSE
gradient
Varian NMR Systems
User Programming
Excitation Sculpting[DPFGSE “operator”]
Shaka, et. al., JACS, 117, 4199 (1995)
G1 G1 G2 G2
Varian NMR Systems
User Programming
Excitation SculptingFeatures
The “sculptured” bandwidth is the inversion profiles of the two pulses
The phase of the “selected” resonance at the end of 2 is same as that at the beginning of 1
All the transverse magnetizations outside the bandwidth are dephased by G1 and G2
G1 G1 G2 G2
Varian NMR Systems
User Programming
Excitation SculptingExample: selexcit
d(GGTTGGTGTGGTTGG)
H1’ region
Base H region
Varian NMR Systems
User Programming
Excitation SculptingApplication: NOESY1D
DPFGSE mix
gradient
Varian NMR Systems
User Programming
Excitation SculptingNOESY1D
Varian NMR Systems
User Programming
IPA
Interactive Parameter Adjustment
Only available on U+ and INOVAIPA allows adjustment of various pulse sequence attributes in acqiIPA is pulse sequence statement oriented rather than parameter oriented.Statements available are
idelay - delayidecpulse, idecrgpulse - decoupler pulseiobspulse, ipulse, irgpulse - observe channel pulseioffset - frequency offsetipwrf, ipwrm - fine power adjustment
These statements may replace the normal equivalents without any overt change in go, however, when run in acqi (after gf) the same parameter is adjustable when IPA is selected.Note. The parameter value is not returned to VNMRJ.
Varian NMR Systems
User Programming
SpinCAD
SpinCAD is a graphical pulse sequence programming tool.
Drag and drop familiar NMR elements to make new pulse sequences.
SpinCAD allows direct setting of the spectrometer hardware.
SpinCAD enables control of up to EIGHT channels.
SpinCAD has not been implemented in VNMRS
Varian NMR Systems
User Programming
Starting SpinCADType spincad on the command line.
Varian NMR Systems
User Programming
Programming in SpinCAD
Drag a delay and drop in the canvas.
Drag a pulse and drop next to the delay.
The front of the pulse is docked to the end of the delay.
Keep adding elements until the sequence is completed.
Varian NMR Systems
User Programming
Spin-echo in SpinCAD
Drag & drop delay at the start.
Next get a pulse. The front of the pulse is docked to the end of the delay.
Drag & drop another delay next to the first pulse.
Drag & drop another pulse in the middle of the second delay.
Drag & drop acquire all points.
Varian NMR Systems
User Programming
SpinCAD vs C #include <standard.h>
static int phi1[4]={0,1,2,3},
phi2[4]={1,2,3,0};
Pulsesequence()
{
status(A);
settable(t1,4,phi1);
settable(t2,4,phi2);
delay(d1);
rgpulse(pw,t1,rof1,rof2);
delay(d2/2.0-pw);
rgpulse(2.0*pw,t2,rof1,rof2);
delay(d2/2.0-pw);
setreceiver(t1);status(B);
}
Varian NMR Systems
User Programming
SpinCAD-Pull Down Menus
Varian NMR Systems
User Programming
Triple Resonance Experiments
Flexibility like in ‘c’ programming.
There are several if statements.
Receiver phase is selected by the if statement flag setting.
Uses 4 of the possible 8 channels.
Channel name can be anything.
Varian NMR Systems
User Programming
More Than Triple Resonance
Varian NMR Systems
User Programming
Auto-Creation of Parameters
Varian NMR Systems
User Programming
Desktop Publishing
Graphics of the pulse sequence can be created.
Shows sequence of the events in the pulse scheme.
Varian NMR Systems
User Programming
Magical II™(MAGnetics Instrument Control and Analysis Language, version II.)
Syllabus
Macros
Menus
Parameters
Varian NMR Systems
User Programming
Magical II macros
Basic Macro Programming
Language Features
MAGICAL II supports
tokens variables expressions conditional statements looping
Very advanced features
read/write files
pattern searching
pass variables
shell command access
Varian NMR Systems
User Programming
tokens
identifiers -
name of command or variable
reserved words -
recognized in both upper and lower
case forms
abortoff
aborton
and
break
do
else
endif
abort endwhile sqrt
if
mod
not
or
repeat
return
size
trunc
typeof
then
until
while
Varian NMR Systems
User Programming
tokens
constants - floating and string
operators -
scientific sqrt(), trunc(), typeof(),size()
unary -
multiplicative. *, /, %, mod
additive +, -
relational <, >, <=, >=
equality =, <>
logical not, and, or
assignment. =
Varian NMR Systems
User Programming
Variables
Global or External
available within a SPECIFIC experiment usually experimental parameters, nt, at, etc.
include : r1,r2,r3,r4,r5,r6,r7 and n1,n2,n3
Local
variables created within a macro and "belong" to
that macro exist only as long as the macro executes
begin with $ Examples $height, $freq, etc.
no variable declaration necessary
EXCEPTION - when the first use of a string
variable is the return argument from a
procedure.
$age=' ' input('Input your age: '):$age string
input('Input your age: '):$age real
Varian NMR Systems
User Programming
macro arguments
Macro and program output:
A macro may return arguments to the
calling program using the return
statement. The calling program
nominates the result parameters by
specifying them after a :
Example -
peak:$height,$freq
The output of the peak program is captured in the local variables $height and $freq.
Both arguments are not needed, i.e. peak:$height is also correct.
Varian NMR Systems
User Programming
Macro arguments
Macro input
arguments passed to a macro are referenced by $n where n is the argument number
the number of arguments passed to the macro is referenced by the variable $#
Varian NMR Systems
User Programming
Expressions
mathematical
d3=2*pw+rof2
$average=($1+$2)/$#
boolean
internally, false is defined to be 0.0, any other
number is true.
Varian NMR Systems
User Programming
Name Replacement
An identifier surrounded by curly braces, {}, results in the
identifier being replaced by its value.
EXAMPLE
pw=20.0 "pw is equal to 20.0"$a='pw' "$a is equal to the string 'pw'"$a={pw} "$a is equal to 20.0"
ANOTHER EXAMPLE
$cmd='wft'{$cmd} "do a wft”
Varian NMR Systems
User Programming
Conditional Statements
if booleanexpressionistrue then
dosomething endif
if booleanexpressionistrue then
dosomething
else
dosomethingelse
endif
For each if there must be an endif !!
nested if statements are allowed
Varian NMR Systems
User Programming
Macro arguments
EXAMPLE: hetcon which sets contour plot size for inverse heteronuclear correlation experiments. The macro accepts an argument for length of f2 and adjusts the height of the f1 dimension to be 2/3 of this value.
"hetcon(length) - length is length along f2
and height is f1”
trace='f2'
wc=$1
wc2=$1*0.67
dconi
hetcon(200) would produce a contour map
200x134 mm
Varian NMR Systems
User Programming
Macro arguments
Improved hetcon macro…
“hetcon(length, width) - if only 1 argument, height is 2/3 of length”
“Defaults to 180mm length”
if ($#=0) then $len=180 $hgt=0.67*$len endifif ($#=1) then $len=$1 $hgt=0.67*$len endifif ($#=2) then $len=$1 $hgt=$2 endif
trace=‘f2’ wc=$len wc2=$hgt sc=6 sc2=0 dconi
Varian NMR Systems
User Programming
Macro example
Design a macro to setup plots of 1D spectra around on the top or side of a 2D plot.
Make macro either plot to paper or file OR simply setup the
desired regions.
Varian NMR Systems
User ProgrammingMacro example
"getrefb - a macro to setup plot top and side projections"
if ($# < 1) then
input('Enter exp# where the spectrum to go on TOP resides. '):$top
input('Enter exp # where the spectrum to go on the SIDE resides. 0 for no side.. '):$side
$1=$top
$2=$side
endif
if ($#=1) then
$2=0
endif
if ($#=3) then
if ($3='p') then $comd='page'
else $comd='page($3)' endif
endif
$sc=sc $sc2=sc2 $wc2=wc2 $wc=wc
if (trace='f2') then
$sp=sp $wp=wp $sp1=sp1 $wp1=wp1
endif
if (trace='f1') then
$sp1=sp $wp1=wp $sp=sp1 $wp=wp1
endif
jexp($1) sc=$sc sc2=$sc2 wc=$wc wc2=$wc2
sp=$sp wp=$wp vp=0 ds
if ($#=3) then pl('top') endif
if ($2 <> 0) then
jexp($2) sc=$sc sc2=$sc2 wc=$wc wc2=$wc2
sp=$sp1 wp=$wp1 vp=0 ds
if ($#=3) then pl('side') endif
endif
if ($#=3) then
exec($comd)
endif
Varian NMR Systems
User Programming
loops
“while loop”
while booleanexpressionistrue
do
something
endwhile
“repeat loop”
repeat
something
until booleanexpr.is.true
Remember: If the boolean expression
initially evaluates to false then the
while will not be executed even once.
The repeat statement always performs
an action once.
Always remember to avoid endless
loops!
Varian NMR Systems
User Programming
Example “maxpk”
"maxpk(first,last) - find the tallest peak in a series of spectra"$first=$1repeat
select($1) peak:$htif $1=$first
then $maxht=$htelse
if $ht>$maxht then $maxht=$ht endif
endif$1=$1+1
until $1>$2
Varian NMR Systems
User Programming
Macro Exercise
Design a macro to process and display either 1D or 2D data...
"myprocess - a macro to process and display 1d or 2d data"
rt($1)
exists('ni','parameter'):$e
if ($e=0) then
wft f full vp=15 ds dc dscale
endif
if ($e=1) then
wft2da f full dconi
endif
Varian NMR Systems
User Programming
Unix Interaction
shell command allows execution of a
Unix command.
shell produces a "pop up" window
for Unix. Unix commands can be
typed in this - they are executed in
foreground. VNMR operation is
suspended until you exit (or ctrl/D)
from the window.
shell(command) executes the Unix command. The text window is stdout and stdin is null.
example -shell('df') "run Unix df command and display in text window"
shell(command):file does the same as above, except that the output is redirected to <file>.
shell(command+'&') runs in background
Varian NMR Systems
User Programming
Macro Exercise
Create a macro to process and display an entire directory of fids one after the other.
Varian NMR Systems
User Programming
Macro ftall Example p.1
"ftall - a macro to process and display an entire directory of fids "
exists('/vnmr/tmp/templace','file'):$e
if ($e=1) then
shell('rm -r /vnmr/tmp/templace'):$dum
endif
shell('mkdir /vnmr/tmp/templace; cp -r *.fid /vnmr/tmp/templace')
shell('cd /vnmr/tmp/templace ; ls > list'):$dum
cd('/vnmr/tmp/templace')
$file='list'
nrecords($file):$count
$numfids=$count-1 // list is also included in the file list
write('line3','Number of fids = %s',$numfids)
Varian NMR Systems
User Programming
Macro ftall example p.2
lookup('file',$file)
$i=1
repeat
lookup('read',1):$name
if ($name <> 'list') then
myprocess($name)
endif
$i=$i+1
write('line3','increment = %s',$i)
until ($i>$count)
cd
shell('rm -r /vnmr/tmp/templace')
Varian NMR Systems
User Programming
Macro to read a file for parameter values"testread is a macro that reads a file and reads lines and updates a parameter"
$file = '' $file = $1
write('line3','file name is = %s ',$file)
nrecords($file):$count
write('line3', '# of lines = %s',$count)
$i = 1
lookup('file',$file)
repeat
lookup('read',1):$val
write('line3', '%s value is =%s',$i,$val)
d2[$i] = $val
$i=$i+1
until $i > $count
da
Varian NMR Systems
User Programming
Argument types
To determine the type of an
argument that is passed to a macro
the typeof() operator is provided.
typeof() -
returns false (zero) if the variable is real
or does not exist.returns true (one) if the variable is a string.
EXAMPLE
if typeof('$1') then doonenastything
HINT: C-like logic statements
if athing then doanastything
is equivalent to the statement
if athing is not equal to 0 then doanastything
Remember that 0 is false, any number other than 0 is true.
Varian NMR Systems
User Programming
Macro termination
return command
terminates execution of a macro
return(value1,value2,…) allows the macro to return a value to a calling macro.
Example:
“abs(value)- returns absolute value of a number”
if $1 > 0 then return ($1) endif
if $1 < 0 then return (-$1) endif
Another macro that uses abs will have a syntax:
abs($num):$absnum
abort command
terminates execution of a macro and of all higher (calling) macros.
takes no arguments.
Varian NMR Systems
User Programming
Execution Priorities
1. Command
2. users maclib directory
3. directory pointed to by maclibpath variable
4. directory pointed to by sysmaclibpath variable
(e.g. sysmaclibpath=/vnmr/maclib/maclib.autotest)
5. system maclib directory
Varian NMR Systems
User Programming
VNMRJ Basic Concepts
Varian NMR Systems
User Programming
VNMRJ 1.1D - Experimental Interface
Varian NMR Systems
User Programming
/vnmr/templates/vnmrj/interface
Varian NMR Systems
User Programming
ToolPanel.xml
Varian NMR Systems
User Programming
/vnmr/templates/layout/default/TopPanel.xml
Varian NMR Systems
User Programming
/vnmr/templates/layout/default
Varian NMR Systems
User Programming
acq_action.xml
proc_action.xml
/vnmr/templates/layout/default
Varian NMR Systems
User Programming
/vnmr/walkup/templates/vnmrj/interface
ToolPanel.xml for apptype=‘walkup’
Varian NMR Systems
User Programming
protocolListWalkup.xml
/vnmr/adm/users/protocolListWalkup.xml
Varian NMR Systems
User Programming
vnmrj adm - Administrator tool
Varian NMR Systems
User Programming
New Concepts
Protocol - strictly - an xml object.
Vnmrsys/templates/vnmrj/protocols.
Really - A collection of files
{parameters, sequence, xml object, macros}
Varian NMR Systems
User Programming
Example Protocol : Carbon.xml
<template type="basic" name="Carbon" author="varian" investigator=""
time_created="20040408T120000" apptype="std1d"
application="liquids" scans="Carbon" seqfil="s2pul">
<protocol title="Carbon" type="protocol">
<action type="LIB" status="Ready" lock="off" title="Carbon" exp="Carbon"
time="10 min" macro="cqexp('Carbon','std1d')" data="" />
</protocol>
</template>
You COULD just put your old-style Vnmr classic into the macro field.
Varian NMR Systems
User Programming
Example Protocol as a macro only!!
<template type="basic" name="Carbon" author="varian" investigator=""
time_created="20040408T120000" apptype="std1d"
application="liquids" scans="Carbon" seqfil="s2pul">
<protocol title="Carbon" type="protocol">
<action type=”CMD" status="Ready" lock="off" title="Carbon" exp="Carbon"
time="10 min" macro=”mydarnmacro” data="" />
</protocol>
</template>
Varian NMR Systems
User Programming
So.. What is different?
By sorting experiments into groups of similar types,
APPTYPE
Setup and processing macros for specific experiments virtually disappear!
