GS Bloch Equations Simulator 1. GS Introduction to Medical Physics IV Bloch Equation Simulator Introduction

Transcription

1 GS Bloch Equations Simulator 1 Purpose GS Introduction to Medical Physics IV Bloch Equation Simulator Introduction The purpose of this laboratory is to investigate some of the implications of the Bloch Equations and to look at basic pulse sequences used in nuclear magnetic resonance and in magnetic resonance imaging. Materials and Methods The tool that facilitates this investigation is a software simulation of the Bloch equations called SpinWright. It is written in the Java programming language and should work on any computer that has a recent Java Runtime Environment installed. For some of the exercises, the simulated data will be saved as text files or as binary files and may be analyzed further in a spreadsheet program such as Excel or by image processing programs such as Matlab or Image/J. SpinWright Tips This lab handout is what currently passes for user documentation of the program. Here is a brief introduction that will be supplemented by the presentation during the formal lab session. The basic steps in simulating an NMR experiment are: to define the subject, which is the collection of spins (the word spin is used in this context as a shorthand term for an isochromatic spin group), to define the pulse sequence, to set the parameters of the experiment, to run the simulation of the experiment, and finally to analyze the simulation output. Some of the input information is (or can be) stored in plain ASCII text. In particular, that is true of pulse sequences. The following table contains a nonsense pulse sequence that shows all of the pulse sequence elements types currently supported by SpinWright. The standard filename extension for ASCII-formatted pulse sequences is PPG. Type Parent Name Parameters (Type-Dependent Meanings) Loop - MainLoop HardPulse MainLoop Hard TruncSincRFPulse MainLoop SoftRF Loop MainLoop InnerLoop RampGradientTable InnerLoop GxRamp InnerLoop XYSprialGradient InnerLoop Spiral RampGradient MainLoop GzRamp StatusPulse MainLoop ADC_ON DelayElement MainLoop Wait Equilibrate MainLoop Eql Spoil MainLoop Spl 79000

2 GS Bloch Equations Simulator 2 The meanings of the fields are given below. The one immutably constrained aspect of these is that the first line of a pulse sequence must be a Loop that is named MainLoop and that has as its second field (which is the name of its parent loop) the particular entry -. It typically starts at time 0 and has a duration equal to the entire duration of the pulse program. It can repeat several times, but is shown here with only one pass. The columns are separated by white space (spaces and tabs). An important implication of this is that one cannot have spaces or tabs in the name of a pulse sequence element. The first column is always the element type. Loop, HardPulse, TruncSincRFPulse, RampGradient, RampGradientTable, XYSpiralGradient, DelayElement, StatusPulse, Equilibrate and Spoil are the supported types at present. The second column is the name of the parent loop. Since the MainLoop is the body of the pulse sequence, it has no parent and thus uses the special character - for its parent. The next column is the name of the element. With the exception of the main loop, which must be named MainLoop (and yes, case matters), the names can be whatever suits you, provided that the name contains no whitespace (e.g., spaces or tabs). You should exercise caution in putting punctuation marks into element names, but underscores don t seem to bother the program. The subsequent columns vary in meaning depending on the particular element type. Loop Parent_Loop(str) Element_Name(str) Start_Time(int µs) Duration_Time(int µs) Passes(int) HardPulse Parent_Loop(str) Element_Name(str) Amplitude(float µt) Phase(float deg) Offset (float freq) Start_Time(int µs) Duration_Time(int µs) TruncSincRFPulse Parent_Loop(str) Element_Name(str) Amplitude(float µt) Phase(float deg) Offset (float freq) Zero_Crossings_(Halfside)(int) Start_Time(int µs) Duration_Time(int µs) RampGradient Parent_Loop(str) Element_Name(str) GxAmplitude(float mt/m) GyAmplitude(float mt/m) GzAmplitude(float mt/m) Start_Time(int µs) Duration_Time(int µs) RampUp_Time(int µs) RampDown_Time(int µs) RampGradientTable Parent_Loop(str) Element_Name(str) ControllingLoop_Name(str) GxStartAmplitude(float mt/m) GxStopAmplitude(float mt/m) GyStartAmplitude(float mt/m) GyStopAmplitude(float mt/m) GzStartAmplitude(float mt/m) GzStopAmplitude(float mt/m) Start_Time(int µs) Duration_Time(int µs) RampUp_Time(int µs) RampDown_Time(int µs) XYSpiralGradient Parent_Loop(str) Element_Name(str) GxAmplitude(float mt/m) GyAmplitude(float mt/m) GzAmplitude(float mt/m) Field_of_View(float cm) Maximum_Gradient_Slewrate(float mt/m/ms) Number_of_Wisps(int) Start_Time(int µs) Duration_Time(int µs) [NB: GyAmplitude and GzAmplitude are ignored use GxAmplitude to set the maximum gradient amplitude. Also note that this currently does not read the

3 GS Bloch Equations Simulator 3 scanner information, although that would be an obvious and desirable thing to do.] StatusPulse Parent_Loop(str) Element_Name(str) StatusBit(int) Start_Time(int µs) Duration_Time(int µs) DelayElement Parent_Loop(str) Element_Name(str) Start_Time(int µs) Duration_Time(int µs) Equilibrate Parent_Loop(str) Element_Name(str) Start_Time(int µs) Spoil Parent_Loop(str) Element_Name(str) Start_Time(int µs) The starting time is with respect to the containing loop, not to the beginning of the entire pulse sequence. For RampGradients, the duration includes both the ramp-up and the ramp-down times, as well as the full-on time. A major MR manufacturer does not include the ramp down time in the gradient duration in their pulse programmer, but I felt that it would be more consistent if the duration always comprised the entire element (and it also made the coding a little easier for me). The downside of this is that one has to think a little harder to figure out exactly the value of duration to use (e.g., in a compensated gradient waveform). For the RampGradientTable, it is possible for the gradient to appear within several nested loops, but not to be incremented by the innermost loop (e.g., the slab-direction of a 3DFT sequence) but rather by one farther out. The ramp gradient table amplitude values have separate start and stop values. The stop value is not actually reached, but rather the last value is one gradient increment shy of the stated stop value. If you must achieve a particular stop value, plan accordingly and set the nominal stop value one increment higher than your target stopping value. The XYSpiralGradient implements the algorithm giving in GH Glover, Simple Analytic Spiral K-Space Algorithm, Magnetic Resonance in Medicine 42: , It is an Archimedean spiral with a Λ value of five. Note that the maximum gradient slewrate is specified in mt/m per millisecond. This is so the number will be manageable. The StatusPulse is used to mark parts of the output data stream for further processing (or it conceivably could be used as a trigger pulse for some piece of hardware, so if you re using this program to create a figure for a paper, it might be handy just for graphical purposes). The HardPulse is pretty straightforward. The TruncSincRFPulse implements a box-car truncated sinc function with a configurable number of zero-crossings. The number of zero-crossings is specified by the number to one side of the center, so the main lobe only would have a zero-crossing value of unity while a pulse with the first side lobes would have a zero-crossing value of two. The number of zero-crossings in combination with the duration controls the bandwidth of the pulse, while the number of zero-crossings affects the sharpness of the pulse edges in temporal frequency (and hence the edge qualities of the slice if the pulse is used for slice selection). Two features that were introduced in 2012 are "magic" in the sense that they are not realistic, but rather ideal. Equilibrate sets the z-axis magnetization equal to the spin density and sets the x-y plane magnetization to zero. Spoil sets the x-y plane magnetization to zero but leaves the z-axis magnetization alone. These are useful for teaching purposes, but unfortunately they are not possible in the real world. In the main SpinWright menu bar, there is a Pulse Sequence choice. The New option under Pulse Sequence presents a GUI-based pulse sequence entry tool. This is nice because it takes care of the bookkeeping of start and duration times with only a

4 GS Bloch Equations Simulator 4 slight loss of generality. We ll focus on it in class, because with it you can produce all three stored representations of a pulse sequence: PPV, PPG and PPC files. Note that Java uses the UNIX newline (LF) rather than the DOS convention (CR-LF), so in Windows, use WordPad rather than NotePad to edit and print these text files. One can either read in a PPV file using Pulse Sequence Actions Load PPV, which will populate the GUI with the pulse sequence elements, or create a blank one using Pulse Sequence Actions New. The pulse sequence elements may be added, deleted and modified in the GUI. Then click Pulse Sequence Sequence Ready, which converts the graphical version into an internally stored PPG. It is not a bad idea to use Pulse Sequence Actions Save PPV (Visual) As as a matter of course. Then, go to Pulse Sequence Sequence and use the process below to compile the internally stored PPG and proceed. To summarize up to this point, the GUI representation is stored in a file with a PPV extension. That representation gets converted into a similar representation with a PPG extension. Both of these are oriented around pulse sequences. Please note that the format of the gradients in PPV files changed slightly (in order to correct a bug) and so PPV files that were created in versions before (January 2018) will not work, although they can readily be edited by hand if need be, to make them work in later versions. Once one has a PPG-formatted pulse sequence, it is compiled into a time-based representation in which each of the rf and gradient waveforms is represented as amplitudes at regular time points. You can think of this as a list mode representation of the waveforms. In order to compile the PPG-formatted pulse sequence, one must specify the starting time, duration, and clock tick of the experiment. These are defined on the Experiment page. The Experiment Action Pulse Sequence Parameters menu item sets up the experiment to accommodate the entire duration of the pulse sequence. If you want to change the starting time, duration, or sampling period of the experiment later, you can enter the new numbers on the Experiment page and then (re)compile the pulse sequence with Pulse Sequence Sequence Compile or Experiment Actions Compile PPG (ASCII). Once the pulse sequence has been compiled, a graph of the waveforms can be viewed with Pulse Sequence Sequence Display. The collection of the isochromatic spin groups that are to be simulated is selected through the Subject menu option. Subject Actions Load Binary Subject loads a file with a SUBJECT file extension while Subject Actions Load ASCII Subject loads a file with a SUBJASC file extension and Subject Actions New clears the existing subject, if any. The ASCII file format describes one isochromatic spin group per line. The parameters are separated by white space (i.e., either spaces or tabs) and must be in the following order: Gyromagnetic_Ratio (MHz/T), Spin_Density (in arbitrary units, but use reasonably large numbers), T 1 (msec), T 2 (msec), Chemical_Shift (ppm), m x, m y, m z, position x (cm), position y (cm), position z (cm), velocity x (cm/s), velocity y (cm/s), velocity z (cm/s), acceleration x (cm/s 2 ), acceleration y (cm/s 2 ), acceleration z (cm/s 2 ), jerk x (cm/s 3 ), jerk y (cm/s 3 ), and jerk z (cm/s 3 ). The currently loaded subject is displayed in the GUI subject editor. The top part is an isochromatic spin group editor whereas the bottom part is a list of all of the ISGs in the subject. One may select a particular ISG to edit by clicking it in the list or by typing its order number in the Current ISG text box. There are controls to the right of the list for adding the ISG in the GUI to the list, replacing the selected ISG in the list by that in

5 GS Bloch Equations Simulator 5 the GUI, deleting the selected ISG or deleting all of them (the same as Subject Actions New). Note that if an experiment has been run, the values shown are those of the isochromats at the end of the experiment. This is currently the only way to see the effect of the experiment on a particular, individual isochromat. If one wants to rerun an experiment with the spins in their initial states, the subject must be reloaded, using Subject Actions Reload, or else the simulation will start where the last one left off. Note that Reload works only if the subject has been loaded from a file, so if you create a new subject that you might want to use more than once, save it to a file and then load it from the file before running experiments. One also needs to specify some characteristics of the Scanner. The field strength is used in a number of internal calculations, and it is possible to specific some imperfections in the static magnetic field, although we will not use the B 0 imperfections feature in this lab. The gradient information is currently ignored by the simulation, although it is envisioned for the future that the maximum gradient amplitudes and slew rates could be applied as constraints on pulse sequences such as the XYSpiralGradient element. When all of this has been set, the Experiment Actions Run option performs the simulation and automatically presents a graph of the three spatial components of the net magnetization vector as a function of time. This plot can be aligned with the plot from Sequence Display to visualize the effect of the pulse sequence elements on the net magnetization. These plots are still extremely limited. It is possible to save the net magnetization vector in an ASCII file. Experiment Actions Save Data Save All Data As will save the entire experiment s time series of the net magnetization vector whereas Experiment Actions Save Data Save All Status Lines As saves only the net magnetization vector's values at time points that are marked by a status line and Experiment Actions Save Data Save Status Line Flagged Data As 0, 1,, 8 or Save Status Line Number As will save only the temporal spans of data when the specified status line is on. In a Windows environment, these files can be dropped into or opened by Excel and analyzed and plotted in Excel. SpinWright has some rudimentary data analysis capability. If a status bit is set, one can perform a one-dimensional Fourier transform of the data flagged with a particular bit from the Analysis page. Checking the Real/Imaginary and the Magnitude/Phase boxes presents those views of the flagged data and their respective Fourier transforms. If the data length is a power of two, a radix-2 FFT is used to perform the transformation. For other data lengths, a DFT is used. If a two-dimensional dataset is set up properly, a two-dimensional Fourier transform can be performed. The results of the 2DFT are saved as 32-bit real-valued binary data, whereas most other outputs are ASCIIencoded. The saved data are four images deep: real, imaginary, magnitude and phase. The lab exercises will always assume that you have gotten SpinWright running and that it is in a normal state. If SpinWright seems to be unresponsive, you might need to increase the memory allocated to it as described in the installation document or in the Starting SpinWright section at the end of this document. Thanks to the work of Chris Walker, the memory requirement has been reduced dramatically and the computationally intensive parts have been multi-threaded so that the execution time is much shorter on multiple core computers.

6 GS Bloch Equations Simulator 6 Here are a few summary suggestions for minimizing the agony of using this software: 1) Names in pulse programs cannot contain whitespace (e.g., spaces and tabs). The GUI interface tries to replace whitespace with underscores, but if you are creating a PPG file by hand, remember not to use spaces or tabs in names because those separate distinct items in a row of text. 2) The various text entry boxes do no error checking. If you enter junk where the program expects a number, it will not comport itself in an optimal fashion. 3) When you look at a pulse program file (PPG, PPV or PPC), a subject file (SUBJASC) or an ASCII data file on a Windows system, use Wordpad rather than Notepad. This is because Java uses UNIX-style newline markers (LF) rather than the Windows-style (CR-LF) when reading and writing text. 4) After having run an experiment, Subject will display the magnetization values of each spin at the conclusion of the experiment in the list. As mentioned above, enter a new subject with Subject New and then the add buttons, save it before you run an experiment or you just had a single-shot subject. This is a feature rather than a bug because it is, at present, the only way to look at the magnetization of individual isochromats following an experiment. When the Subject tab is orange, it means that the spin system is no longer in its original state. 5) Some of the saved files (.MRSCNR and.subject) are saved in a fashion that makes them dependent on this particular version of SpinWright (they are stored as serialized objects for reasons that made sense fifteen years ago but not now). Please don t invest a huge amount of time in creating large binary subject files (.subject), for example, if you expect them to work with future versions; they won t. Instead, save ASCII versions. If push comes to shove, you can edit a SUBJASC file by hand to accommodate version changes. 6) Right now, the data are sampled at multiples of the clock tick (with a default of a sample on each clock tick). The clock tick is really for the benefit of the numerical integration and the specification of gradient and rf waveforms, so the program allows one to specify the sampling multiple on the experiment page. If you want to get a power of two length to the data, you need to pay attention to the clock tick and the duration of the Status Line on period (e.g., with a duration of microseconds and a 100 microsecond clock tick, you ll get 5120 points, which could be slow to transform, even for an FFT, so consider using a sampling multiple of 10 ticks as well to make the dataset more tractable). You also have to be sure that every time interval is an integer multiple of the click tick or the program will decline to run the simulation. (Chris added a warning about this, whereas the program used simply to crash unceremoniously. Thanks, Chris.) 7) The simulator can save the one-dimensional Fourier transform of the data in a text format for subsequent use in another program. It saves the twodimensional transforms as 32-bit real-valued binary data in four planes: real, imaginary, magnitude and phase (from -π to π). 8) You can use a screen capture program to grab graphical outputs for insertion into reports.

7 GS Bloch Equations Simulator 7 9) If the program just seems to hang, it might have run out of allocated memory. See the next section for how to set the heap size for Java. If you are suspicious that this is the problem run the program from the command line or with java.exe instead of javaw.exe (again, see below) so that you can see any error messages. An OutOfMemoryException typically means that your simulation is too big for the allocated heap and that you should enlarge it as described below. I have yet to figure out how to handle this situation automatically and to provide a useful diagnostic message. Thanks to Chris' work, the program now uses memory much more efficiently and this is less likely to be a problem than it had been in the past. Starting SpinWright Exactly how you start SpinWright depends upon the operating system. In general, if you go to the installation directory and double-click the file SpinWright.jar (which is an "executable JAR file"), it should start. For some of the exercises, you might need to give Java more memory, so you should start it from the command line with a command such as java -Xms512m -Xmx512m -jar SpinWright.jar, which tells Java to use 512 megabytes of RAM (see for links to the command line documentation for many parts of the Java system). Of course, if you have more memory available, you can set the figure to be larger than 512m (i.e., 512 megabytes). If SpinWright inexplicably hangs, you should suspect that you have run out of memory allocated to Java. Try increasing the allocated memory (within the constraint of the physical memory available on your computer) and run SpinWright again. The distribution includes a sample shortcut for Windows, which you can edit to customize to your environment (we'll cover this in the lab session). Make sure that the path to the javaw.exe command is correct for your system. The Oracle installers create a path C:\\ProgramData\Oracle\Java\javapath that is supposed to be independent of the precise version of Java that is installed. Set the Start in: folder of the shortcut to be that folder in which you installed SpinWright. You can substitute the command java.exe for javaw.exe and you will get a window that might show helpful error messages if the program is behaving badly. You can add the -Xms and -Xmx options to the shortcut to allocate more memory if you would like that to happen every time that you use the shortcut. The -Xms option is not required, whereas the -Xmx option is, if you want to increase the size of the memory that is allocated to Java.