JEMRIS  2.8.1
open-source MRI simulations
Sequence development tool: JEMRIS_seq

JEMRIS sequence development does not require any programming. The sequence is determined through an XML tree structure. A dedicated GUI allows to construct the tree structure for arbitrary complex MRI sequences.


The Sequence tree concept

The MRI sequence is specified utilizing a tree structure. As a simple example, the EPI sequence below is eqivalently described by left-right ordered tree structure. This is very suitable and efficient for computer-aided design and access of the pulse sequence: The MRI simulator JEMRIS utilizes such a tree structure to represent the MRI sequence. The MatLab tool JEMRIS_seq is used to design the sequences.


Introduction to the sequence GUI JEMRIS_seq

Change to the directory in which the sequence xml-files are located and type JEMRIS_seq to start the sequence GUI. The following picture shows a screenshot of the GUI with the EPI sequence loaded into it:


The Sequence GUI allows to interactively build the sequence tree. The tools for this are given in the top panel. The "File" dialog allows to load and save sequences (XML format). The "write XML" button overwrites the current sequence file according to the changes made.

Further, this button executes a run through the sequence and draws the sequence diagram. Possible error output during sequence execution is thrown to the "jemris tree dump" at the bottom. Instead, the "read XML" button discards all changes made to the sequence tree and rereads the current sequence from its XML file. To view the sequence diagram, i.e. the ADC, RF, and gradient events, use the "Sequence Diagram" check box. There are several features to visualize the sequence diagram:

By clicking on a module, its individual attributes are displayed in the upper half of the GUI and may be edited. The attribute values can not only be actual numbers, analytical expressions are also accepted (see section Analytical expressions ). Often attribute values from other modules are needed for an analytical expression, e.g. the area under a previous gradient pulse or the duration of a previous pulse. This is handled using the "observe" attribute (see also section Analytical expressions ).

Sequence Building Modules

This section briefly summarizes all sequence building modules and its attributes. The interaction of these modules is explained in the next section Analytical expressions.

The Parameters Module

The parameter module (orange circle) is always present in a sequence. It is not a part of the sequence tree but exists only once. The module contains global attributes such as field of view $ FOV_{x/y/z} $, the size of the image matrix, the gradient slew rate etc.

Sequence Modules

So far, there exist five modules which are of type sequence:

Pulse Shape Modules

There exist several pulses which may be inserted into an AtomicSequence. All pulses have several attributes in common:

The most simple pulse-shape module is the

All other pulses subdived into two main pulse classes, RF Pulses and Gradient Pulses, respectively. The following RF pulse Modules are defined in JEMRIS:

Note that in terms of numerical efficiency the built-in RF pulses (HardRFPulse,GaussianRFPulse,SincRFPulse) perform best, the evaluation of an AnalyticRFPulse is slower, and an ExternalRFPulse is slowest, if it is specified through many data points.

Next, there exist several Gradient Pulse Modules in JEMRIS. All gradients can induce eddy currents, for which three additional attributes are in common for these pulses:

Eddy currents are implemented in a very flexible way: the eddy currents will adapt automatically, if the gradient module changes its shape during the sequence runtime (e.g. a phase-encoding gradient). Further, eddy currents typically last longer than the gradient event itself, i.e. beyond the AtomicSequence in which it was originated. In this case the transients are taken over to the next AtomicSequence - which could be again the same module, if it runs in a loop (e.g. in EPI). Caution: the latter will fail, if additionally the gradient dynamically changes its shape within the loop, as then the transients are no longer corrrect. In such a case, a dfferent way to implement the sequence has to be chosen. For instance in EPI one could use two readout gradient events with static polarities (positive and negative) within the echotrain loop.

Further, each gradient can have a specific spatial dependence, i.e. it can be a nonlinear gradient. See Exceptional Attributes for explanation. The following gradient pulse modules exist in JEMRIS:

Analytical expressions

The "Observe" Attribute

As mentioned above, instead of being numbers module attributes values can also be analytical expressions. For that variables are needed which contain the attribute values of other modules. Consider a gradient pulse with name "P1" which is dependent on the area of another gradient pulse "P2". To have access to this value, the pulse "P1" needs the special attribute Observe="A=P2.Area". Now the area of pulse "P2" can be accessed in every attribute definition of "P1" with the variable "A". For instance, "P1" sets its area to minus half the area of "P2" through Area="-0.5*A". Multiple attributes can be observed separated by commas, e.g.: Observe="A=P4.Area, NX=P.Nx, NY=P.Ny, C=C2.Repetitions" . Then, the observed attributes are accessed with the user-defined variables "A", "NX", "NY", "C", etc. The variable names can be freely chosen. It is recommended to use only uppercase letters to prevent undesired string replacements in formulas. Further the letters "I", and "P" should not be used as variables as this might conflict with other pre-defined epxressions (see below). (It is valid to use this letters within a variable name, e.g. Observe="C.Counter=INDEX" or Observe="P.FOVx=PFOVX")

Observer syntax in older versions of JEMRIS
As explained above, the current JEMRIS version requires an observer definition of the form: Observe="KEY1=Module1.Attribute1, KEY2=Module2.Attribute2, ...". Then the user-defined keywords "KEY1", "KEY2" can be used in analytic formulas. Older JEMRIS versions (<2.8.1) used a different syntax: Observe="Module1,Attribute1/Module2,Attribute2/...", then the according variables were automatically named "a1", "a2", etc. This syntax has the disadvantage that the user has to keep track which variable (a1,a2,...) belongs to which observed attribute. Therefore, the new syntax with user-defined keywords was introduced. The old syntax is still supported. (And used in some examples in the documentation.)

Hidden Attributes

Each module can have so-called hidden attributes which cannot be edited. Instead, these attributes are calculated from supplied values at runtime. The ConcatSequence, for example, not only has the attribute "Repetitions", it also has a hidden attribute "Counter" which gives the current loop-number. A hidden attribute can be observed by other modules. A list of all hidden attributes can be displayed using the pull-down menu in each module. Some frequently used hidden attributes are listed here:

Hint: "Counter" is the most often observed attribute since it introduces the dynamic to the sequence. Attributes which observe a loop counter change their value in run time. (If these attributes are further observed by other attributes, the latter of course will also dynamically change their values accordingly.)

Expression syntax and predefined functions

The symbolic expression syntax is similar to scalar computation syntax in Matlab. For instance, if a gradient observes three attributes, e.g. Observe="KMX=P.KMAXx, KMY=P.KMAXy, C=C.Repetitions", then a valid formula for its area would be Area="sqrt(KMX^2+KMY^2)*(-1)^C"

Several predefined mathematical expressions may be used:

Pi area of a unit circle
abs(x) absolute value
step(x) step function
I imaginary unit
csgn(x) complex sign
conjugate(x) complex conjugation
real_part(x) real part
imag_part(x) imaginary part
sqrt(x) square root
sin(x) sine
cos(x) cosine
tan(x) tangent
asin(x) inverse sine
acos(x) inverse cosine
atan(x) inverse tangent
atan2(y,x) inverse tangent with two arguments
sinh(x) hyperbolic sine
cosh(x) hyperbolic cosine
tanh(x) hyperbolic tangent
asinh(x) inverse hyperbolic sine
acosh(x) inverse hyperbolic cosine
atanh(x) inverse hyperbolic tangent
exp(x) exponential function
log(x) natural logarithm
floor(x) round to integer
mod(x,y) Modulo
equal(x,y) returns 1, if x equals y, otherwise returns zero
gt(x,y) returns 1, if x is greater than y, otherwise returns zero
lt(x,y) returns 1, if x is less than y, otherwise returns zero
ite(x,y,a,b) returns a, if x equals y, otherwise returns b

There are further, less comonly used, mathematical functions. Please check the GiNaC documentation .

Exceptional Attributes

Every Module has its attributes which will have its internal special meaning. However, for the observer mechanism all these "standard attributes" may be arbitrarily linked to each other. For instance, the flip angle of an RF pulse may set its value through observation of the area of a gradient. However, there are some exceptional attributes for which this general behaviour does not work, i.e. these attributes can not be observed by other modules! These exceptions are listed below:

-- last change 17.06.2016 | Tony Stoecker | Imprint --