The above introduced Matlab GUIs follow the same procedure: construct a valid XML file from the user input, then call the external JEMRIS executables to compute the data, and finally read and visualise the result. Of course it is possible to directly run the executables without running Matlab. For this, the XML configuration files might be directly manipulated to set up the numerical experiments.
This section presents example XML files and explains how to use the JEMRIS from the command line:
MRI sequences may be scripted directly in XML where the sequence and pulse modules are represented by XML elements. Their parameterization is done via attributes utilizing the observer mechanism. See section Sequence Building Modules for a list of available modules and their attributes. Section Analytical expressions describes the observer mechanism and symbolic attribute dependences.
This is an example of a 2D EPI sequence for 2D simulation (i.e. without slice selection).
Prototype of a trapezoidal gradient pulse (e.g. for cartesian k-space imaging)
Definition TrapGradPulse.h:36
The Coil Array XML file
As for the sequence, also coil array files can be directly scripted in XML. Elements represent the available coils (see section 'Coil array layout tool: JEMRIS_txrx' for a complete list and their parameterization). This is an example for an 8 channel phased array:
The simulation XML file contains elements for the XML file locations of the sequence, the coil arrays (transmit and receive), and the location of the sample HDF5-file (the object).
Examples of such samples as well as how to create user defined samples are described in section Object Properties.
Additionally, a few other parameters may be added via attributes of the "parameter" element which are documented in section 'Additional parameters' of the simulation GUI chapter.
The special case 'modlist' is used by the Sequence development tool: JEMRIS_seq to generate the list of modules. Therefore, framework extensions will automatically appear in the GUI.
Generating the Pulse Sequence Diagram Data
Running jemris with the EPI sequence XML file results in
Additionally, a HDF5-file "seq.h5" is written which is read by the Matlab GUI to plot the sequence diagram.
The output shows that this sequence has in total 4096 ADC points. The sequence diagram is non-equidistantly sampled: it consists of 4488 TPOIs ("time points of interest") which are the ADCs plus some additional important time points (for instance the ramps of trapezoidal gradients). In the above example the HDF5-file "seq.h5" contains 4888 sampling points. The data is stored in a dataspace "seqdiag" with names "T", "RXP", "TXM", "TXP", "GX", "GY", and "GZ", each of size (column vectors) where is the number of sampling points.
Reading the sequence diagram HDF5-file in Matlab:
T = h5read('seq.h5','/seqdiag/T'); % temporal sampling points
RXP = h5read('seq.h5','/seqdiag/RXP'); % RF Receiver phase; unit: radiants; if negative, the TPOI was not an ADC
Running jemris with a coil array XML file results in
me@my_box:~$ jemris 8chheadcyl.xml
JEMRIS 2.2 r1509M
dumping sensitivity maps to sensmaps.h5 ...
done!
The coil sensitivity HDF5-file contains dataspaces "/maps/magnitude/00" and "/maps/phase/00" which hold 2D or 3D coil maps according to the grid size which is specified in the coil array XML file. If the coil-array has multiple channels (coils), the maps of the second coil are stored in datspaces "/maps/magnitude/01", "/maps/phase/01", etc.
Example to read the complex sensitivity HDF5-file in Matlab, assuming 4 coils with 2D-sensitivities:
for i = 1:4
a = h5read ('sensmaps.h5', sprintf('/maps/magnitude/%02d',i-1));
p = h5read ('sensmaps.h5', sprintf('/maps/phase/%02d',i-1));
The Sample is the object to simulate. It contains the spins.
Definition Sample.h:301
The simulation result is stored to the HDF5-file "signals.h5".
The signal file contains the HDF5 datspace "/signal/times" of size , the time points of each ADC event of the sequence, and the datspace "/signal/channel/00" where the acoording signals of size are stored, i.e. the x,y, and z component of the net magnetization at every time point. If a receive coil with multiple channels was used, the signals of channels 2,3, etc. are stores in datspaces "/signal/channel/01", "/signal/channel/02", etc.
Example to read the signal HDF5-file in Matlab, assuming 8 receiver channels:
If an imaging sequence was simulated, image reconstruction can be started directly after the simulation using the switch -r
me@my_box:~$ jemris -r simu.xml
Assuming that the recon server is installed, this will run the python image reconstruction pipeline and store the images to the file signals_ismrmrd_recon.h5. See section Starting the Image Reconstruction for more information about the image reconstruction pipeline.
Invoking the parallel version of JEMRIS
Running the parallel version requires a working MPI environment (see Installation).
The following command runs the parallel version with 5 parallel processes:
The resulting signal file is the same as for sequential jemris simulations.
Additionally, the percent progress is written to the hidden file ".jemris_progress.out".
Note that spins are first distributed in small packets, then the packet size increases (and decreases at the end, to ). The program performs load balancing and first estimates the number of spins which are simulated in 5 seconds per process. Then, every 5 seconds checkpoints are stored to temporary hidden binary files the ".spins_state.dat" and ".tmp_sig01.bin" which are removed after successful completion. If however the simulation is unexpectedly stopped, a restart will continue at the last checkpoint. This is useful for huge simulations lasting several hours (or even days) where sudden crash e.g. due to power breakdown may occur.
Exporting a Sequence to an MRI Scanner with Pulseq
Running jemris with the -x option exports the sequence in Pulseq format (http://pulseq.github.io) for execution on a real MRI scanner,
This creates a file suitable to run on a scanner. The -x option indicates export, -d allows for custom definitions (such as scan ID), and the .seq file is named according to the -f option (default: external.seq). In addition, an ISMRMD file is generated (epi.h5 in the example above, default: external.h5 ), which contains sequence meta information (trajectory etc.) which can be used for image reonstruction. This file can be merged with the ISMRD raw data file resulting from scanner execution and then fed into the Python reconstruction pipeline, wich is also used for image reconstruction of JEMRIS simulations. The workflow is described in detail on the project's github page.
Caution: read the Pulseq manual carefully before running sequences created with JEMRIS on the scanner! Creating valid Pulseq files requires some experience. Here is a brief and incomplete list of things which may be taken into account when creating Pulseq files with JEMRIS:
For trapezoidal gradients (TrapGradPulse): ramp sampling is not used if FlatTopTime and FlatTopArea are set. Otherwise, ramp sampling is always enabled (as displayed in the Sequence development tool: JEMRIS_seq )
All other gradient forms are exported as arbitrary gradients.
The EmptyPulse can be used as a delay. Here, ADCs are exported to the Pulseq file.
For all ADC events, the dwell time is defined as Duration / number of ADCs
Additionally, some hardware-specific restrictions may have to be considered (see the Pulseq Manual for more details).
In Pulseq's "strict timing mode", the RF pulse requires a simultaneous GradPulse or EmptyPulse in the same AtomicSequence. Otherwise the Strict Duration Check may fail due to missing dead times before and/or after the RF pulse.
The number of ADCs should be chosen such that the dwell time is compatible with the hardware RF raster time.
Sequence blocks should not end with an ADC, for example a delay can be set parallel to the ADC.
For large numbers of ADCs it might be necessary to segment ADCs events, which match gradient raster time
