Imaging module

From Spinach Documentation Wiki
Revision as of 16:58, 3 January 2018 by Kuprov (talk | contribs) (Other relevant functions)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Introduction

Spinach contains a very general implementation of the Fokker-Planck formalism that is able to treat 3D diffusion and hydrodynamics simultaneously with Liouville-space spin dynamics, relaxation and chemical kinetics. This is a result of our in-house research, and it is dictated by the direction in which the field is moving: many emerging magnetic resonance methods (ultrafast NMR, singlet state imaging, spatially encoded NMR, metabolite-selective MRI, catalyst MRI, hyperpolarised imaging, etc.) fall in between the established simulation frameworks: on the one hand, they require accurate simulation of three-dimensional diffusion, hydrodynamics and chemical processes; on the other, it is essential that the spin evolution in every molecule is treated quantum mechanically in a way that accurately describes spin relaxation processes. At the same time, sophisticated spatially and temporally modulated radiofrequency pulses must be accounted for. Within the Fokker-Planck formalism, things like three-dimensional diffusion, hydrodynamics and off-resonance radiofrequency appear in a very simple way – each of these is just another constant matrix to add to the background evolution Hamiltonian.

Setting up the imaging context

The Fokker-Planck imaging simulation context that generates the Hamiltonian, the relaxation superoperator, the kinetics superoperator, the Fokker-Planck spatial dynamics generator (including diffusion and flow), gradient operators, and passes all of that to the pulse sequence, which should be supplied as a handle. Syntax:

           answer=imaging(spin_system,pulse_sequence,parameters)

where pulse sequence is a function handle to one of the pulse sequences located in the experiments directory, and parameters is a structure with the following subfields:

  parameters.spins   - a cell array giving the spins that 
                       the pulse sequence involves, e.g. 
                       {'1H','13C'}

  parameters.offset  - a cell array giving transmitter off-
                       sets in Hz on each of the spins listed
                       in parameters.spins array

  parameters.u       - X components of the velocity vectors
                       for each point in the sample, m/s

  parameters.v       - Y components of the velocity vectors
                       for each point in the sample, m/s

  parameters.w       - Z components of the velocity vectors
                       for each point in the sample, m/s 

  parameters.diff    - diffusion coefficient or 3x3 tensor, m^2/s
                       for situations when this parameter is the 
                       same in every voxel

  parameters.dxx     - Cartesian components of the diffusion
  parameters.dxy       tensor for each voxel of the sample
       ...
  parameters.dzz
 
  parameters.dims    - dimensions of the 3D box, meters

  parameters.npts    - number of points in each dimension
                       of the 3D box

  parameters.deriv   - {'fourier'} uses Fourier diffe-
                       rentiation matrices; {'period',n}
                       requests n-point central finite-
                       difference matrices with periodic
                       boundary conditions

Three types of phantoms must be specified. The relaxation theory phantom contains relaxation superoperators and their coefficients in each voxel, specified in the following way:

                parameters.rlx_ph={Ph1,Ph2,...,PhN}
                parameters.rlx_op={R1,R2,...,RN}

where PhN have the same dimension as the sample voxel grid and RN are relaxation superoperators. The initial condition phantom reflects the fact that different voxels might start off in a different spin state. It must be specified in the following way:

                parameters.rho0_ph={Ph1,Ph2,...,PhN}
                parameters.rho0_op={rho1,rho2,...,rhoN}

where PhN have the same dimension as the sample voxel grid and rhoN are spin states obtained from state() function. The detection state phantom reflects the fact that different voxels might be detected at different angles and with different sensitivity. It must be specified in the follo wing way:

                parameters.coil_ph={Ph1,Ph2,...,PhN}
                parameters.coil_op={rho1,rho2,...,rhoN}

where PhN have the same dimension as the sample voxel grid and rhoN are spin states obtained from state() function.

The pulse sequence must use the following syntax:

    answer=pulse_sequence(spin_system,parameters,H,R,K,G,F);

where H is the Hamiltonian commutation superoperator, R is the relaxation superoperator, K is the kinetics superoperator, G is a cell array of three gradient operators normalized to 1 Tesla/m, and F is the diffusion and flow superoperator.

The context function sets the following fields inside the parameters structure that is passed to the pulse sequence:

    parameters.rho0 - the initial condition in the Fokker-Planck space

    parameters.coil - the detection state in the Fokker-Planck space.

Note: the direct product order is Z(x)Y(x)X(x)Spin, this corresponds to a column-wise vectorization of a 3D array with dimensions ordered as [X Y Z].

Pre-programmed pulse sequences

basic_1d_hard.m - basic 1D imaging with a hard pulse and a gradient

cpmg_dec.m - CPMG echo train

dwi.m - 2D (spatial) diffusion weighted imaging sequence

epi.m - 2D (spatial) echo planar imaging sequence

fse.m - 2D (spatial) fast spin echo sequence

grad_echo.m - simple gradient echo pulse sequence

phase_enc.m - 2D (spatial) phase encoded imaging.

press_1d.m - 1D (spatial) PRESS sequence

press_2d.m - 2D (spatial) PRESS sequence

press_voxel_1d.m - voxel selection diagnostics for 1D (spatial) PRESS pulse sequence

press_voxel_2d.m - voxel selection diagnostics for 2D (spatial) PRESS pulse sequence

slice_phase_enc.m - 3D (spatial) imaging with slice selection followed by phase-encoded acquisition

slice_select_1d.m - slice selection diagnostics

spin_echo.m - simple spin echo pulse sequence

spiral.m - 2D (spatial) imaging with spiral readout

udd_dec.m - Uhrig Dynamic Decoupling (UDD) echo train

uhrig_times.m - timing sequence for UDD echo train

Other relevant functions

g2fplanck.m - returns magnetic field gradient operators.

hydrodynamics.m - first derivative operators with respect to spatial coordinates.

mri_plot_2d.m - MRI image plotting with a black-and-white colour map.

ngridpts.m - estimates the minimum number of spatial grid points necessary to have a valid treatment of gradient driven experiments with explicit digitization of spatial dimensions.

phantoms.m - MRI phantoms library.

v2fplanck.m - converts diffusion and velocity fields into Fokker-Planck operators.


Version 2.1, authors: Ilya Kuprov, Ahmed Allami, Maria Grazia Concilio