Chapter 1
Introduction

1.1 What is MRiLab

The MRiLab is a numerical MRI simulation package. It has been developed and optimized to simulate MR signal formation, k-space acquisition and MR image reconstruction. MRiLab provides several dedicated toolboxes to analyze RF pulse, design MR sequence, configure multiple transmitting and receiving coils, investigate magnetic field related properties and evaluate real-time imaging technique. The main MRiLab simulation platform combined with those toolboxes can be applied to customize various virtual MR experiments which can serve as a prior stage for prototyping and testing new MR technique and application.

The MRiLab features highly interactive graphical user interface (GUI) for the convenience of fast experiment design and technique prototyping. High simulation accuracy is achieved by simulating discrete spin evolution at small time interval using the Bloch-equation and appropriate tissue model. In order to manipulate large multidimensional spin array, MRiLab employs parallel computing by incorporating latest graphical processing unit (GPU) technique and multi-threading CPU technique. With efficient parallelization, MRiLab can accomplish multidimensional multiple spin species MR simulation at high simulation accuracy and time efficiency, and with low computing hardware cost.

1.2 Obtaining MRiLab

The current MRiLab version (v1.3) is made available online. MRiLab is released as a free software. This means that you are free to use and modify this software as your needs, as long as you acknowledge the original author in any future work. If you find MRiLab useful for the publication of any scientific results, including a line in your acknowledgments section for MRiLab is requested.

MRiLab downloading address:

We also request you to cite this scientific paper:

Fang Liu, Julia V. Velikina, Walter F. Block, Richard Kijowski and Alexey A. Samsonov: Fast Realistic MRI Simulations Based on Generalized Multi-Pool Exchange Tissue Model, IEEE Trans. Med. Imag., doi: 10.1109/TMI.2016.2620961, 2016.

1.3 Installing and Running MRiLab

To use MRiLab, you need to install Matlab software first. The current MRiLab version was successfully tested under mutiple Matlab versions:

• Matlab R2011a 64-bit Windows
• Matlab R2013a 64-bit Windows
• Matlab R2015a 64-bit Windows
• Matlab R2012b 64-bit Unix
• Matlab R2015a 64-bit Unix

To install MRiLab, you need to download MRiLab source code, then extract the MRiLab root folder, put the folder to any location in you computer. To run MRiLab, start Matlab, then simply run the ‘MRiLab.m’ script under the MRiLab root folder.

The GUIs in MRiLab is developed under Matlab GUI development environment (GUIDE). Majority of the simulation configuration code is programmed using pure Matlab language and Extensible Markup Language (XML). The computing intensive functions are programmed and optimized using MATLAB Executable (MEX) C code. These MEX binaries include GPU computing kernels that interact with GPU devices via NVIDIA Compute Unified Device Architecture (CUDA), and CPU kernels with multi-threading via Open Multi-Processing (OpenMP) for multi-core CPU. Other MEX binaries include several 3D image rendering functions using Visualization Toolkit (VTK). These MEX library binaries have been built under 64-bit Windows and Linux OS system and shipped with MRiLab source code. However, if they are incompatible with your OS system for any reason or if you wish to modify these MEX files for your own good, you need to recompile them from source code.

Before recompiling these MEX files, some dependent packages are required.

1. CMake (required)
   CMake is used for cross platform building of these MEX files.
   

   CMake : http://www.cmake.org/cmake/resources/software.html
   

2. IPP or Framewave (required)
   MRiLab uses Intel Integrated Performance Primitives (IPP) or AMD Framewave libraries for large scale matrix manipulation. Please note that Intel IPP isn’t a free open source software, however if you are planning to use MRiLab IPP version (i), you can download Intel C Studio XE which includes IPP distribution and follow Intel’s non-commercial license for non-commercial usage. As an alternative, MRiLab provides Framewave version (f) which uses equivalent Framewave libraries. The Framewave is released as a free open source software.
   

   Intel IPP : http://software.intel.com/en-us/intel-ipp
   AMD Framewave : http://framewave.sourceforge.net
   

3. CUDA (optional)
   NVIDIA GPU driver is required for running GPU devices and also for MRiLab to interact with GPU devices. The current MRiLab version only supports GPU cards which support NVIDIA CUDA technique. The GPU card must support CUDA computing capability 2.0 and above. The shipped MEX files in the MRiLab distribution use CUDA libraries from CUDA 7.0.
   

   NVIDIA : http://www.nvidia.com/page/home.html
   CUDA : http://www.nvidia.com/object/cuda_home_new.html
   

   Although GPU acceleration dramatically improves computational efficiency, the GPU computing mode is also optional. Alternatively, MRiLab provides multi-threading CPU computing mode via OpenMP which requires no additional packages on modern operating system. The CPU kernel provides the same simulation accuary but with reduced computational efficiency compared to GPU mode.

4. VTK (optional)
   The VTK library provides nice functions to render 3D k-space trajectory as well as complex image object in 3D space. The current MRiLab version uses MEX built against VTK 5.10. However, VTK rendering is optional as native Matlab rendering is also provided.
   

   VTK : http://www.vtk.org
   

5. ISMRMRD (optional)
   MRiLab supports data conversion from Matlab variables to ISMRMRD, the default data storage format for Gadgetron MRI reconstruction framework. To enable Gadgetron function and allow data conversion to ISMRMRD, the user needs to install ISMRMRD.
   

   ISMRMRD : http://ismrmrd.sourceforge.net/#obtaining-and-installing

After completing abovementioned dependent packages, you also need to add a few environment variables in your system :

• MATLAB_ROOT : Matlab root folder path
• IPP_ROOT : IPP root folder path if IPP is used
• FRAMEWAVE_ROOT : Framewave root folder path if Framewave is used

Note that the C source code for these MEX files is in /MRiLab/Lib/src folder. To compile and install MEX files

1. Linux Installation
   The command lines for compiling the MEX files are
   mkdir build  
   cd build  
   cmake MRiLab/Lib/src  
   make  
   sudo make install

   You also can use cmake-gui for configuration and other building tools (e.g. Eclipse) for building the binaries.

2. Windows Installation
   It is recommended to use cmake-gui for generating Visual Studio projects, then build the projects in Visual Studio.
   • Step 1 : Locate source folder and build folder in cmake-gui (Figure 1.1)

     ---

     
     

     Figure 1.1: The cmake-gui for locating source folder and build folder

     ---

   • Step 2 : Configure and generate Visual Studio projects in cmake-gui (Figure 1.2)

     ---

     
     

     Figure 1.2: The cmake-gui for configuring and building Visual Studio projects

     ---

   • Step 3 : Build the INSTALL project, compiled MEX binaries will be copied to MRiLab/Lib/bin folder by default (Figure 1.3)

     ---

     
     

     Figure 1.3: Build INSTALL project using Visual Studio

     ---

If installation problems do occur in your case, feel free to leave comments on the online supporting forum. For your information, I provide here my development environment (Table 1.1) for the current MRiLab version.