Pulse sequence drawing

From NMR Wiki

The image below was generated by NMR Wiki from plain text using special markup. Click "edit" tab to see source.

Some other examples of drawings like this one are here.

Pulse sequence markup should be surrounded by <pulse> </pulse> tags.

The pulse sequence markup is intended to be easily readable and being able to accomodate detailed input of NMR pulse sequences for display as images and in the future - production of real pulse sequence code.

Current version of <pulse> extension is experimental - please report bugs/problems here.

Installation

On this site this tool is already installed for you, however you can also install it on your own website.

Get the pulse sequence drawing tool for your wiki

Introduction

Markup example and overview

Here is the markup that produced the image in the beginning of this document (JHMBC experiment, Sorensen et al)

First six lines (anchors, disp, time, rf H, rf 13C, and pfg z) are describing the actual pulse sequence, remaining lines are elaborating the elements used within the pulse sequence.

First three lines are required. The following lines rf H, rf 13C and pfg z contain events on rf channels H, 13C and pfg channel z respectively.

anchors line lists all anchors (imaginary representations of timed instants in the pulse sequence) and anchor groups (sequences of anchors separated by delays determined by hardware and attached pulse and aquisition events - that is events not separated by explicit delays)

disp line determines drawing positions of anchors in tens of pixels. (in the future version disp line will not be used)

time line specifies delays and which anchors come before and after each delay, note that delays and anchors/anchor groups are strictly alternating in time line.

<pulse>
anchors:       @a          @a1,b      @b1,c     @c1,d,d1         @e     @f     @g     @h    @j0,j,j1    @i--k        @l
disp:         3@a           5@b       3@c          3@d          9@e    9@f    4@g    4@h      3@j      3@i         10@l
time:    rlx   @a  t1         @b  t2     @c t3      @d  T1a      @e T1b @f T12 @g T12 @h d     @j     d @i--k   aq   @l
rf H:        90@a                                                           180@g                       acq@k---------l
rf 13C:                     90@b       90@c       90@d        180@e   90@f=p1               180@j     90@i=p1
pfg  z:                  g1@a1      g2@b1     g3@c1 g4@d1                                 g5@j0  g6@j1
 
delay T1b: show_at=13C label=\frac{\Delta-\kappa t_1}{2}
delay T1a: show_at=13C label=\frac{\Delta+\kappa t_1}{2}
delay t2: show_at=13C label=\tau_2
delay t1: show_at=13C label=\tau_1
delay t3: show_at=13C label=\tau_3
delay T12: show_at=13C label=\frac{t_1}{2}
delay rlx: hide=true
delay d: label=\delta
 
rfchan 13C: label=^{13}C
rfchan H: label=^1H
pfgchan z: label=Grad.\ z
 
pulse p1: phase=phi1
acq: phase=phi2 type=fid
 
phase phi1: label=\phi_1 table=0,2
phase phi2: label=\phi_2 table=1,3
 
gradient g1: strength=70 label=g_1
gradient g2: strength=-40 label=g_2
gradient g3: strength=-20 label=g_3
gradient g4: strength=-10 label=g_4
gradient g5: strength=50,-30 label=g_5
gradient g6: strength=-30,50 label=g_6
</pulse>

Manual

Concepts

Allowed symbols in variables

The following symbols are allowed in the variable names (anchor names, pulse names, delay names, channel names, phase names etc.)

• lower case and upper case latin alphabetical characters a-z and A-Z (variable names are case sensitive)
• digits 0-9
• underscore _

Line format

Input in pulse sequence markup is line-based. Each line has a heading which starts at the beginning of the line and is ended by the colon (:). Anything after colon till the end of line is the content. If one line is not enough to fit all content, more lines with the same heading can be added and the content of lines will be joined in the order provided.

Example

rf 13CO:  180@d     cpd@k----l

Above is a line denoting events on rf channel named 13CO

Main pulse sequence input

Those are anchor, disp, time, rf channel and pfg channel lines.

They should appear in the beginning of pulse sequence and contain the entire pulse sequence layout.

Extended pulse sequence input

In case you'd like to elaborate some details of main input, you can add these extra lines. Their content will become clear from further reading.

Anchors and events

Pulses (RF and gradient) and acquisition periods (events) are attached to anchors. Anchors serve as imaginary representation of timed instants within the pulse sequence. Anchors are denoted by symbol @.

For example

@a

Means "anchor a" and

90@a

means "90^o pulse at anchor a"

Anchor name is case sensitive, can consist of any number of alphabetical characters, numbers and an underscore

Anchor groups

Anchor group is a sequence of anchors that appear in the pulse sequence separated only by hardware-limited delays or wide pulse and acquisition events attached to those anchors.

Below is an example use of anchor group

anchors:   @b0--b--b1
rf H:        90@b
pfg z:   g1@b0  g2@b1

Means that 90^o pulse at channel H (at anchor b) is preceded by z gradient g1 (at anchor b0) and followed by gradient g2 (at anchor b1).

Resulting simplification of pulse sequence entry is main purpose of using the anchor groups: gradient recovery, gating, frequency switching delays wont be shown in the main part.

In the example above anchor group consists of anchors b0, b and b2. The group could be equivalently entered as

@b0,b,b2

Sequences of dashes can be used instead of commas simply to align appearance of anchor symbols between the lines.

Delays

Explicit delays are entered on the time: line, they are not entered on rf channel input lines. This unclutters input, makes pulse sequence more readable and easier to parse.

Drawing offsets

Event drawing offsets (how far from the leftmost edge they are drawn) are specified through positions of associated anchors in the disp: line.

Each individual anchor (i.e. not one belonging to an anchor group) must have drawing specified. In addition, for each anchor group at least one anchor must have a specified drawing offset.

Elaborating details of pulse sequence

There is a limitation that symbol = (equal sign) cannot appear in the parameter values. This limits types of latex labels entered from additional input below the main part (i.e those labels can't contain equal sign). This problem is on the buglist.

Care has been taken to minimize input of the main pulse sequence part to fit a few lines on a single page. Or perhaps a dozen lines for the most complex pulse sequences.

All details (pulse phase tables, etc) will need to be supplied on separate lines after the main part.

For example, if we want to put a x, − x label underneath a 90^o pulse, we will write in the main part (on one of rf channel lines):

90@f=p1

Now pulse has name p1

Also in addition, below the main part we'll add the following line:

pulse p1: label=x,-x

Analogously, other types of events can be customized.

More detailed input instructions

Anchors line

The first line in the markup must be "anchors" line, e.g.

anchors: @a @b0,b1,b2 @z

This line must display all anchors used in the pulse sequence in their exact order of appearance.

In the example above @b0,b1,b2 is an anchor group

Drawing offset line

In the example below event attached to anchor a will be drawn 30 pixels from the left edge, event attached to anchor b 50 pixels to the right of anchor a

disp:         3@a           5@b 

Requirements:

• anchors in disp line must appear in the same order as in the anchors line
• exactly one anchor from each anchor group must be present in disp line

Time line

Example (in the context of "anchors" line)

anchors:  @a1,a2,a3,a4     @z
...
time: d1     @a2,a3    d2  @z

Purpose of the time line is to specify when in the pulse sequence key events are supposed to take place.

There are some requirements on the content of time line:

1. time line must start with delay and end with anchor or part of anchor group
2. delays and anchors must strictly alternate
3. no delays should be inserted between anchors belonging to the same anchor group
4. at least one anchor from each anchor group must appear in time line
5. order of anchors in time line must be the same as in anchors line

Defining RF pulses and other anchored events

RF channel events

Three types of events can be specified in RF channel line: (1) short pulses, (2) long pulses and (3) acquisition periods.

"Short pulses" - those that can be conviniently associated with one anchor. These are not necessarily hard pulses.

"Long pulses" - beginning and end attached to separate anchors

Named RF channel events

"Named anchored events" - a modification that applies to RF pulses and acquisition periods.
This section explains how to name those events. A separate section will explain how to further customize them.

PFG events

Only single-anchored gradient pulses are suported at this time. Wide gradient pulses will be supported in the future

Note: gradient pulses are named by default, unlike RF channel events.

Customizing named events and other elements

Customization of pulse sequence elements should be done after the main pulse sequence input. No particular order of customization lines is required.

Currently pulse sequence elements don't have many customization options, but they can expand as application becomes more functional.

Customizing delays

Example

delay d2: show_at=13C label=\frac{\Delta + \kappa t_1}{2}

setting	value	meaning
show_at	name of rf channel	rf channel on which delay should be drawn in the figure
hide	true/false	if hide=true, delay label will not be shown in the drawing
label	latex code	formula to be shown as delay label, in this case
label_yoffset	integer	additional vertical drawing offset for delay symbol in pixels; default value is 0

Customizing single-anchored pulses

Customizing wide pulses (double-anchored)

Example:

rf H:  cpd@a-b=sl 90@d  acq@e-f
rf N:                    wp@e-f=dec

cpd sl: label=MLEV-71
wp dec: label=WALTZ-16

cpd (composite pulse decoupling) and wp (wide pulse) keywords are synonyms, perhaps should be replaced with just wp in the future.

Customizing gradients

Customizing phases

This is intended for input of phase tables. Manual will appear when application starts producing real pulse sequence code.

Troubleshooting (a.k.a debugging)

There is no error reporting (yet) which can make entering entering pulse sequences correctly quite difficult. One way you can build a complex pulse sequence entry - start doing so element by element, saving small changes each time.

Remembering these things might help:

• all anchors should appear on the "anchors" line
• time line should start with delay and end with an anchor
• anchors (or anchor groups) and delays should strictly alternate on the "time" line
• at least one anchor in an anchor group must be timed (preceded end succeded by delay; only last anchor group/anchor should not be succeeded by delay)
• at least one anchor in an anchor group should have specified display offset
• don't forget using @ symbol with anchors in the main input part
• in parts other then main input (anchors,disp,time,rf,pfg lines) @ symbol should not be used for anchors
• all input is case sensitive
• use compare versions in history tab to figure out what broke the working input
• whole lines can be commented out by '#' symbol in the beginning