User Programming Course Outline

1. INTRODUCTION Resource materials VNMRJ structure User Interface BASIC SYSTEM ADMINISTRATION The Windowing Environment Editors PULSE SEQUENCE PROGRAMMING hardware interaction beginning C basic pulse sequences advanced sequences MAGICAL II macros BASIC CONCEPTS of VNMRJ User Programming Course Outline

2. Pulse Sequence Programming • Pulse sequence itself • setup macro • parameter set customizations • Adding to GUI • processing macros • Controlling Pbox Putting it all Together

3. 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 Introduction • Resource Materials • On the Spectrometer • man(subject) • help(subject) • VNMR on-line • VNMR news/E-mail • EXISTING CODE & FILES !!!! • Hard copy - reference Command & Parameter Reference User Programming

4. 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

5. VNMR directories/files • Conpar • System configuration: • contains critical system parameters • number and type of channels • shim set type • lock frequency • .....

6. VNMRJ directories/files • Conpar • UNITY+, INOVA and VNMRS systems autoconfigure, • Gemini 2000, Unity, VXR-S systems cannot autoconfigure

7. VNMR directories/files • devicenames - printer names - used by VNMR • /vnmr/bin/adddevices is used to add new devices

8. psglib source code for pulse sequences seqlib compiled pulse sequences Use the User equivalent directories for modifications shapelib shaped pulse files shims shim files VNMRJ directories/files

9. maclib MAGICAL macros used by the system templates text files controlling VNMRJ parameter pages and interface parlib Parameters for individual experiments cosy.par, noesy.par this directory is actually linked to one of the directories par200 - par750 stdpar Nucleus parameter files e.g. H1.par, C13.par VNMRJ directories/files

10. Basic System Administration • The Windowing Environment • Editor

11. 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. The X Windows Environment

12. 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!

13. 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 Editors

14. 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)

15. 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)

16. Insert 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 A few Vi Editor Commands use arrow keys to navigate within screen

17. 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

18. 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

19. When “go” runs: go is a macro which looks first for a macro usergoand 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 Pulse Sequence Execution

20. "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. Pulse Sequence Execution

21. gating • Pulse execution requires hardware to be turned on or off. transmitter gate amplifier blanking gate LO gate receiver gate

22. 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

23. AP Bus timing • AP bus instructions incur a delay of 0.5 ms on INOVA, 1.15µs on U+, 1.2 ms 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

24. Unity Inova RF

25. 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

26. INOVA RF 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

27. VNMRS RF Varian DDR – 20 MHz IF sampled directly at 80 MHz rate RF Attenuator SDRAM (Error Correcting) 64 Mb Flash 32 Mb PowerPC FIFO & Timer EBC Register Decode Instruction FIFO RF Transmitter EBC Ethernet DMA RF Math Config GPIO RS232 IntC Attn, Synth, Users FPGA IntC RF Aux SyncIN GPIO Sync

28. 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. Pulse Sequence Programming

29. 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.

30. 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 }. C Framework

31. 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 d1 constants - example 5.2 expressions - example 2.0*pw

32. 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 ) Basic C for Pulse Sequence Programming

33. 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];

34. 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

35. 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

36. Control Statements • Math statements Boolean Logic • if (dm[0]==‘n’) statement; /* C language */ Loops • for (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 statements • tpwr=tpwr+6.0; • i3++;

37. 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’ */

38. DELAY Statements • vdelay(timebase,count); timebase can be NSEC,USEC,MSEC or SEC count must be a real time variable delay length for NSEC timebase is 100 + (count)*resolution nsec. Resolution = 12.5 ns for INOVA. If count = 4, the delay would be (100 + (4*12.5)) or 150 ns. • Example • vdelay(NSEC,v5); /*normal syntax*/

39. initdelay & incdelay enable real-timeincremental 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 */ DELAY Statements

40. The state of the receiver determines the state of: Preamplifier blanking Transmitter blanking PULSE Events

41. 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); PULSE (Observe Channel) Statements

42. 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); PULSE (Observe Channel) Statements

43. 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);

44. 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.

45. 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.

46. 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’

47. 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

48. 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

49. 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

50. 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...