JEMRIS 2.9.1
open-source MRI simulations
No Matches
MRI Simulation tool: JEMRIS_sim

JEMRIS simulations can be started from the Simulation GUI JEMRIS_sim, which provides several predefined objects for simulation and some functionality to view the simulation results.

Introduction to the simulation GUI JEMRIS_sim

Object Properties

Starting the Simulation

Starting the Image Reconstruction

Introduction to the simulation GUI JEMRIS_sim

To start the simulator GUI, open "JEMRIS_sim" as before in the path where the sequence *.xml files are stored. In the following screenshot, the epi-sequence has been loaded into the GUI and was simulated for a brain phantom:

Before the simulation, the sequence file has to be selected via "File->open Sequence". Additionally, coil array loops for transmit and receive may be loaded via the File menu (see Coil array layout tool: JEMRIS_txrx). If no coils are specified, a uniform B1 sensitivity is assumed.

Object Properties

Next, the sample to which the sequence is applied has to be specified. There are five predefined samples: a sphere, two interleaved spheres, a 1D column phatom, the Shepp-Logan phantom (requires the Matlab Image Processing Toolbox) and a brain model. Since 3D simulations are very time consuming, the samples are defined as 2D slices (except the 1D column), while for the brain model the desired slice can be selected using "slice" parameter. Here also 3D portions of the brain may be simulated by specifying the first and the last slice. For all samples, "{dx,dy}" specifies the distance between two neighboring spins. For larger distances, less spins need to be calculated and thus the simulation will be faster. However, artifacts are likely if too few spins are used in the simulation. The following physical properties of the object, the sample parameters, can be specified (one value per parameter in case of a sphere, two values per parameter in case of two spheres or the 1D column phantom, and one factor per parameter in case of the brain phantom or the Shepp-Logan phantom):

  • T1: longitudinal relaxation time. Units: [ms].
  • T2: transverse relaxation time. Units: [ms].
  • T2*: effective transverse relaxation time (including a reversible decay). Units: [ms]. If T2* is zero, or equals T2, or is not specified, then no such reversible components are simulated. If specified, a high spin density per voxel may be needed to correctly simulate T2*-induced intravoxel de- and rephasing.
  • M0: equilibrium magnetization. Units: arbitrary.
  • CS : chemical shift. Units: [rad/sec].
  • Radius: The radius (radii) of the sphere(s). This parameter changes to the slice index for the brain phantom, the matrix size for the Shepp-Logan phantom, or length and number of blocks for a 1D column phantom (odd/even blocks have the parameters of the first/second value for each ).

In case of the brain phantom, the parameters T1,T2,T2*,M0, and CS are tissue parameters at 1.5 Tesla. The user may change them individually by specifying a constant factor. Setting T2*=0 will also omit any reversible signal decay. Further, for the brain phantom a realistic susceptibility-induced field variation may be included.

Finally, it is also possible to specify a user-defined object as a Matlab mat-file. An example file "userSample.mat" is located in Jemris' matlab installation directory (default /usr/local/share/jemris/matlab).

Starting the Simulation

After specifying the sample and the sequence, the "start simu" button calls JEMRIS. Its output is displayed in the "simulation message dump". After the simulation has finished, the results will be displayed in the lower right of the GUI. Besides the signal, the k-space and the image space can be displayed. K-space is only shown, if the sequence contained imaging ADCs (i.e. ADCFlag=2, see Pulse Shape Modules). Images are only shown, if image reconstruction was performed (see next section).

Additional parameters

On the right hand side there are three additional parameters controlling the simulation:

  • "increment to store M(t) (time evolution)": The signal is the sum over all simulated spins. However, the information of each individual spin is present in the simulation and can be returned by JEMRIS. If this parameter is set to i, the magnetization of each individual spin is stored for every i-th readout event. Caution: if increment=1, then the complete magnetization is stored at every sampling point which may result in huge output files.
  • "concomitant fields": account for concomitant fields introduced by the gradient field
  • "random noise": adds Gaussian random noise to the signal during the simulation. Note: The noise level is given in percent of the maximum equilibrium Magnetization in the sample. Furthermore, it scales with the bandwidth (inverse dwell time) of the sequence.

Addtionally, there are settings for simulation of motion, flow, and diffusion, which are not yet well documented. More explanation on these topics may be found on in the JEMRIS discussion group on Google.


To speed up the simuation JEMRIS can make use of multiple CPUs, either of a computer cluster or of a multi-core processor on a single workstation. The desired mode can be selected from the "Settings" dialog. To utilize multiple CPU cores on a single workstation the GUI must be able to log into the system without supplying a password, thus an ssh-key has to be installed in the system.

Starting the Image Reconstruction

If an imaging sequence was implemented using ADCFlag=2 for k-space encoding (cf. Pulse Shape Modules), the simuation will generate the ISMRMRD raw data file "signals_ismrmrd.h5". Then, the "start reco" button calls an automated image reconstruction pipeline as a docker service (if it was installed, see Installation of the Automated Image Reconstruction Pipeline). This will start the required Docker server, send the ISMRMRD data to it, perform image reconstruction with the BART toolbox, save the images to the file gui-reco.h5, and finally terminate the server. Ouput is again displayed in the "simulation message dump". Usually image reconstruction is much faster than the simulation.

The python reconstruction pipeline for JEMRIS is designed to run fully automatically. Details of are given on the project's github page. Here is a short list of features:

  • By default a fast non-uniform Fourier Transform (bart nufft) is used for reconstruction, which supports arbitrary k-space trajectories.
  • If a receive array is used in the simulations, then Parallel Imaging reconstruction (bart pics) is applied. By default it will use the true coil sensitivities for reconstruction.
  • If ADC data was acquired with the sequence (ADCFlag=4), those will be used to estimate the coil sensitivities instead of using the true coil sensitivities.
  • Currently, the reonstruction does not use phase correction scans of the sequence (ADCFlag=8), but noise scans (ADCFlag=16) are considered.

-- last change 03.10.2023 | Tony Stoecker | Imprint | Data Protection --