/**
***************************************************
* \page ug_tutorial_epi_seq %First steps tutorial: sequence

\n

In this tutorial the user is guided through the setup and
simulation of an EPI experiment. This step by step introduction shall
enable the user to setup own experiments thereafter.

To proceed the user must have successfully installed JEMRIS.

\section ug_tutorial_epi_seq_seq Setup the EPI sequence

\li Start up MATLAB
\li Add the directory with the JEMRIS matlab code to the MATLAB path with
    <b> \c >> \c addpath \c /usr/local/share/jemris/matlab</b>
\li Start up the <b>Sequence GUI</b> with the following command<br>
    <b> \c >> \c JEMRIS_seq</b>
The Sequence GUI window pops up:
\htmlonly <style>div.image img[src="seq-gui-top.png"]{width:800px;}</style> \endhtmlonly
@image html pics/seq-gui-top.png
\htmlonly <style>div.image img[src="jemris_sequence.png"]{width:800px;margin-top:-15px}</style> \endhtmlonly
@image html pics/jemris_sequence.png
\image latex pics/seq-gui-top.png width=12cm
\image latex pics/jemris_sequence.png width=12cm

\li From the File drop down menu choose "New sequence".
\li As <b>Filename</b> choose \c <b>MyEPI.xml</b> and save.

You will now see the minimum requirements for a sequence: the <b>top
 node ConcatSequence</b> (outer most loop) of the sequence, \c <b>C1</b>, short
  ConcatSequence, and <b>Parameters node</b>, \c <b>P</b>. Let us start
 with the parameters. The <b>parameters</b> hold information valid for
 the whole sequence. These include in order from top left to bottom
 right: <b>name</b>, <b>FOV in x, y, and z direction</b>,<b>maximum
 gradient amplitude</b>, <b>maximum slewrate</b>, <b>TD</b>,
 <b>TE</b>, <b>TI</b>, and <b>TR</b>. Note that these values do not do anything
 as long as they are not used by the sequence. The parameter node
 is merely a collection of values to be used by other modules.

\li Click on the parameter node \c <b>P</b>
\li Set <b>\c FOVx</b> and <b>\c FOVy</b> to <b>\c 200</b> each.
\li Set <b>\c GradMaxAmpl</b> to <b>\c 5</b>.
\li Set <b>\c GradSlewRate</b> to <b>\c 20</b>.
\li Set <b>\c Nx</b> and <b>\c Ny</b> to <b>\c 64</b> each.
\li Set <b>\c TE</b> to <b>\c 50</b>.
\li Set <b>\c TR</b> to <b>\c 100</b>.
\li Click on \c "write XML"

Note that the last step has to be done always in order to apply unsaved changes.
<b> Do this always in order to see the effect of a change. </b>

Let us now model the sequence.

\li Click on the concat sequence \c <b>C1</b>

Since we do not want to loop over the EPI readout, you do not need to
change any of the parameters of \c <b>C1</b>.

We want to start with inserting the excitation pulse. Pulses, which
are played out simultaneously are contained in <b>atomic
sequences</b>.

\li Click in the selection bar on the symbol for atomic
sequences \c <b>A</b>.
\li Click on \c <b>C1</b> and the atom will be appended.

An atomic sequence is appended to \c <b>C1</b> by the name
of \c <b>A1</b>.

Since we do not care for slice selection for this tutorial, we now
insert a hard RF pulse.

\li Click in the module bar on the symbol for the hard RF pulses.

When you hover over the fields a short description is shown for every
module.

\li Click on \c <b>A1</b> to append the pulse to the excitation atomic
sequence.
\li Set \c <b>Duration</b> to 1 for 1ms.
\li Set \c <b>FlipAngle</b> to 90 for 90 degrees.

Your sequence should, so far, look like this:
\htmlonly <style>div.image img[src="seq-gui-top.png"]{width:800px;}</style> \endhtmlonly
@image html pics/seq-gui-top.png
\htmlonly <style>div.image img[src="jemris_sequence_1.png"]{width:800px;margin-top:-15px}</style> \endhtmlonly
@image html pics/jemris_sequence_1.png
\image latex pics/seq-gui-top.png width=12cm
\image latex pics/jemris_sequence_1.png width=12cm

Note the \c "jemris tree dump" at the bottom of the window. It shows the jemris output of
the sequence. Any error messages due to incorrect or insufficient module attributes will
show up here.

The excitation is now sufficiently defined. We now need to insert
into the sequence the <b>dephasers</b> in read as well as PE
directions. For this purpose the next atom needs to be added after
the \c <b>A1</b> atom.

\li Select from the symbol bar the symbol for atomic sequences.
\li Click on \c <b>C1</b> to insert the atom after \c <b>A1</b>.
\li Choose from the symbol bar the symbol for trapezoidal gradients.
\li Click on \c <b>A2</b> to insert it therein.
\li Change its axis to \c <b>GX</b>
\li Repeat the last three steps for the phase encoding
dephaser, with axis \c <b>GY</b> in the last step

The dephasing areas will be chosen as half the size of k-space. These values
can be obtained from the <b>parameters</b> node, which defines the image
resolution. For that, the gradients have to observe the according parameters
(cf. section \ref ug_JEMRIS_seq_ginac):
\li Click on the first dephaser \c <b>P2</b>
 \li Set \c <b>Observe</b> to  <b>\c A=P.KMAXx</b>
 \li Set \c <b>Area</b> to  <b>\c -A</b>

Do the same for dephaser \c <b>P2</b> (using the parameter <b>\c P.KMAXy</b>).
\n
We will later define the EPI readout along the x-axis. Then, we will see that the
above definition of the dephaser <b>P1</b> was not fully exact and we have to change it.

Next we need to introduce a dead time to match the center of the
EPI readout with \c <b>TE</b> from the parameters.

\li Choose the symbol for a delay atomic sequence from the module bar.
\li Click on \c <b>C1</b> to add it to the sequence.
You will find details on delays here: \ref ug_JEMRIS_seq_intro_seqmod.
Start preparing the delay \c <b>D1</b> by observing the attribute \c TE of the
parameter node:

\li Click on the delay \c <b>D1</b>
\li Set \c <b>Observe</b> to  <b>\c TE=P.TE</b>
\li Set the \c <b>Delay</b> to <b>\c TE</b>
\li Set the \c <b>StartSeq</b> to <b>\c A1</b>
The \c <b>StopSeq</b> will be defined later, once we have created the EPI readout.


You should be looking at a sequence representation looking as follows:
\htmlonly <style>div.image img[src="seq-gui-top.png"]{width:800px;}</style> \endhtmlonly
@image html pics/seq-gui-top.png
\htmlonly <style>div.image img[src="jemris_sequence_2.png"]{width:800px;margin-top:-15px}</style> \endhtmlonly
@image html pics/jemris_sequence_2.png
\image latex pics/seq-gui-top.png width=12cm
\image latex pics/jemris_sequence_2.png width=12cm

Let us now compose the EPI readout. For this, we would like
to implement a loop structure for one readout line and one phase
encoding blip to run through all phase encoding steps.

\li Click on the symbol of a concat sequence in the module bar.
\li Add it to the sequence by clicking on <b>\c C1</b>.
\li Click on the new concat sequence \c <b>C2</b> (the EPI loop)
\li Set <b>\c Observe</b> to <b>\c N=P.Ny</b>
\li Set <b>\c Repetitions</b> to <b>\c N</b>
\li Add two atomic sequences to <b>\c C2</b>, one for the readout and one for the blips.
\li Add to each atomic sequence, <b>\c A3</b> and <b>\c A4</b>, one trapezoidal gradient (<b>\c P4</b> and <b>\c P5</b>) and change their
<b>\c Axis</b> to <b>\c GX</b> and <b>\c GY</b>, respectively.

We have to define the FlatTopArea and the number of sampling points on
the flat top of the readout gradient <b>\c P4</b>:

\li Click on the gradient \c <b>P4</b>
\li Set <b>\c Observe</b> to <b>\c A=P.KMAXx, C=C2.Counter,N=P.Nx</b>
\li Set <b>\c ADCs</b> to <b>\c N</b>
\li Set <b>\c FlatTopArea</b> to<b>\c 2*A*(-1)^C</b>
\li Set <b>\c FlatTopTime</b> to <b>\c 1</b>

Thus, the flat top has a fixed duration of 1ms. Area and polarity will be set
according to the defined formula. By observing the loop counter, the polarity
will toggle between even and odd lines in k-space. (Note: loop counters always
start at zero in jemris!)

 Next, define the <b>\c Area</b> of the PE blip <b>\c P5</b>. This is a
simple assignment, observing the parameter attribute for k-space increment:

\li Click on the gradient \c <b>P5</b>
\li Set <b>\c Observe</b> to <b>\c A=P.DKy</b>.
\li Set <b>\c Area</b> to <b>\c A</b>.

The following image reflects the content of the sequence GUI up to this point:
\htmlonly <style>div.image img[src="seq-gui-top.png"]{width:800px;}</style> \endhtmlonly
@image html pics/seq-gui-top.png
\htmlonly <style>div.image img[src="jemris_sequence_3.png"]{width:800px;margin-top:-15px}</style> \endhtmlonly
@image html pics/jemris_sequence_3.png
\image latex pics/jemris_sequence_3.png width=12cm

We are nearly done, this is already close to a working EPI sequence. However, if you look at
the k-space encoding (select \c "sequence Diagram" and \c "k-space trajectory"), you will notice
that the readout encoding is not exactly symmetrical to k-space center. For that the dephaser
area needs to be exactly half the size of the readout gradient. Let's correct that:
\li Click on the first dephaser \c <b>P2</b>
 \li Change \c <b>Observe</b> to  <b>\c A=P4.Area</b>
 \li Change \c <b>Area</b> to  <b>\c -abs(A)/2</b>

Here, \c "-abs()" was used to ensure negative polarity of the dephaser, as the readout gradient area,
<b>\c P4.Area</b>, starts with a positive readout.\n
(Note that every change of the readout polarity will notify the dephaser to update its area.
This is a consequence of the built-in observe-notify mechanism of JEMRIS modules. It has no
effect in this example but is useful in others, e.g. to automatically set the area of a phase encode rewinder.)

Let us now define the missing parameters of the delay <b>\c D1</b>, to ensure that the delay time TE is counted from center to center (\c C2C) between RF pulse and EPI readout:
\li Click on the delay atom \c <b>D1</b>
\li Set the <b>\c DelayType</b> to <b>\c C2C</b>.
\li Set <b>\c StopSeq</b> to <b>\c C2</b>.

Finally, we add a delay to the end of the sequence to define the TR of the sequence:

\li Choose from the module bar the symbol for an DelayAtomicSequence.
\li Click on <b>\c C1</b> to append it to the sequence.
\li Set <b>\c DelayTape</b> to <b>\c B2E</b>.
\li Set <b>\c Observe</b> to <b>\c TR=P.TR</b>.
\li Set <b>\c Delay</b> to <b>\c TR</b>.
\li Set <b>\c StartSeq</b> to <b>\c A1</b>.

We are done with the EPI sequence.

Let us, finally, have a look at the EPI sequence, the associated sequence diagram, and the k-space trajectory reflecting the data acquisition scheme in the following three images.

The following image reflects the sequence GUI up to this point:
\htmlonly <style>div.image img[src="seq-gui-top.png"]{width:800px;}</style> \endhtmlonly
@image html pics/seq-gui-top.png
\htmlonly <style>div.image img[src="jemris_sequence_4.png"]{width:800px;margin-top:-15px}</style> \endhtmlonly
@image html pics/jemris_sequence_4.png
\image latex pics/seq-gui-top.png width=12cm
\image latex pics/jemris_sequence_4.png width=12cm

Click now on the check box \c <b>"Sequence Diagram"</b> at the top to see the sequence diagram:

\htmlonly <style>div.image img[src="seq-gui-top.png"]{width:800px;}</style> \endhtmlonly
@image html pics/seq-gui-top.png
\htmlonly <style>div.image img[src="jemris_sequence_5.png"]{width:800px;margin-top:-15px}</style> \endhtmlonly
@image html pics/jemris_sequence_5.png
\image latex pics/seq-gui-top.png width=12cm
\image latex pics/jemris_sequence_5.png width=12cm

Click now on the check box \c <b>"k-space trajecory"</b> and then \c <b>"add ADCs"</b> to verify the k-space trajectory and sampling of the EPI sequence:

\htmlonly <style>div.image img[src="seq-gui-top.png"]{width:800px;}</style> \endhtmlonly
@image html pics/seq-gui-top.png
\htmlonly <style>div.image img[src="jemris_sequence_6.png"]{width:800px;margin-top:-15px}</style> \endhtmlonly
@image html pics/jemris_sequence_6.png
\image latex pics/seq-gui-top.png width=12cm
\image latex pics/jemris_sequence_6.png width=12cm

Let us go on to simulate the sequence: <a href="ug_tutorial_epi_sim.html">%First steps tutorial - simulation</a>

***************************************************
*/
