see CHANGELOG

BLOCHUS/BLOCHUS.m

@@ -33,8 +33,8 @@
 %------------- BEGIN CODE --------------
 
 %% GUI 'header' info and default GUI settings
-myui.version = '0.1.3';
-myui.date = '22.05.2020';
+myui.version = '0.1.4';
+myui.date = '25.09.2020';
 myui.author = 'Thomas Hiller';
 myui.email = 'thomas.hiller[at]leibniz-liag.de';
 

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.1.4] - 2020-09-25
+
+### Added
+- *pyBLOCHUS* - core functionality of *BLOCHUS* as python module without a graphical user interface.
+
+### Changed
+- Minor GUI improvements and consistency clean ups.
+
+### Fixed
+- bug inside the pulse modulation function
+
 ## [0.1.3] - 2020-05-22
 
 ### Added
@@ -32,6 +43,7 @@
 
 Initial Version
 
+[0.1.4]: https://github.com/ThoHiller/nmr-blochus/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/ThoHiller/nmr-blochus/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/ThoHiller/nmr-blochus/compare/v.0.1.1...v0.1.2
 [0.1.1]: https://github.com/ThoHiller/nmr-blochus/compare/v.0.1.0...v.0.1.1

README.md

@@ -1,4 +1,4 @@
-## BLOCHUS
+## BLOCHUS / pyBLOCHUS
 
 <img src="blochus_logo_small.png" alt="BLOCHUS icon" width="96">
 
@@ -24,6 +24,9 @@
 
 **BLOCHUS** is a set of MATLAB<sup>TM</sup> tools, that allow some basic simulations of (S)NMR spin dynamics based on the Bloch equations. The Bloch equations are solved in the laboratory frame of reference with MATLABs built-in `ode45` solver. Because it was developed within the scope of a near surface SNMR project, its main features are the simulation of (1) pre-polarization switch-off ramps and (2) excitation pulses. The main front-end to the underlying simulation tools is a graphical user interface (GUI) that allows playing around with the different features and helps to understand the basic concepts of (S)NMR spin dynamics.
 
+#### pyBLOCHUS
+**pyBLOCHUS** is a set of python modules that implement the core functionality of **BLOCHUS** without any graphical user interface. More information can be found [here](pyBLOCHUS).
+
 #### Basic features:
 1. Choose between different protons (e.g. *Hydrogen*, *Helium*, *Fluorine*, etc.)
 2. Choose between different pre-polarization switch-off ramp shapes (e.g. *exponential*, *linear*, *half cosine*,  etc.) with arbitrary ramp time 
@@ -76,16 +79,15 @@ A basic documentation to **BLOCHUS** can be found in the `blochus\doc` folder. J
 
 In no particular order and without guarantee that it will ever happen :-) :
 
-1. Adapt the core functionality in a Python module (this is on top of my agenda)
-2. A real Manual
-3. ...
+1. A real Manual
+2. ...
 
 - - -
 <a name="references"></a>
 ### Cite as
 If you use BLOCHUS for your research, please cite it as:
 
-Thomas Hiller. (2020, May 22). ThoHiller/nmr-blochus: v0.1.3 (Version v0.1.3). Zenodo. [https://doi.org/10.5281/zenodo.3829464]
+Thomas Hiller. (2020, September 25). ThoHiller/nmr-blochus: v0.1.4 (Version v0.1.4). Zenodo. [https://doi.org/10.5281/zenodo.3829464]
 
 Note: Even though the version number might change due to updates, this DOI is permanent (represents all versions) and always links to the latest version.
 
@@ -95,4 +97,4 @@ Note: Even though the version number might change due to updates, this DOI is pe
 1. Hiller, T., Dlugosch, R. and Müller-Petke, M., "Utilizing pre-polarization to enhance SNMR signals - effect of imperfect switch-off", Geophysical Journal International **222**(2), p.815-826, 2020, [DOI](https://doi.org/10.1093/gji/ggaa216)
 
 - - -
-<p style="text-align: center;"> MATLAB is a registered trademark of The Mathworks, Inc. </p>
+<p style="text-align: center;"> MATLAB is a registered trademark of The Mathworks, Inc. </p>

doc/blochus/BLOCHUS/BLOCHUS.html

@@ -105,8 +105,8 @@ <h2><a name="_source"></a>SOURCE CODE <a href="#_top"><img alt="^" border="0" sr
 0033 <span class="comment">%------------- BEGIN CODE --------------</span>
 0034 
 0035 <span class="comment">%% GUI 'header' info and default GUI settings</span>
-0036 myui.version = <span class="string">'0.1.3'</span>;
-0037 myui.date = <span class="string">'22.05.2020'</span>;
+0036 myui.version = <span class="string">'0.1.4'</span>;
+0037 myui.date = <span class="string">'25.09.2020'</span>;
 0038 myui.author = <span class="string">'Thomas Hiller'</span>;
 0039 myui.email = <span class="string">'thomas.hiller[at]leibniz-liag.de'</span>;
 0040 

doc/blochus/callbacks/menus/menu.html

@@ -18,7 +18,7 @@ <h1>Index for blochus\callbacks\menus</h1>
 
 <h2>Matlab files in this directory:</h2>
 <ul style="list-style-image:url(../../../matlabicon.gif)">
-<li><a href="onMenuExport.html" target="function" title=" handles the extra menu entries">onMenuExport </a></li><li><a href="onMenuHelp.html" target="function" title=" shows the Help Information">onMenuHelp </a></li><li><a href="onMenuImport.html" target="function" title=" handles the extra menu entries">onMenuImport </a></li><li><a href="onMenuRestartQuit.html" target="function" title=" restarts or closes the GUI">onMenuRestartQuit </a></li><li><a href="onMenuView.html" target="function" title=" handles the extra menu entries">onMenuView </a></li><li><a href="onMenuViewFigure.html" target="function" title=" shows predefined figure layouts">onMenuViewFigure </a></li><li><a href="onMenuViewShow.html" target="function" title=" handles the extra menu entries">onMenuViewShow </a></li></ul>
+<li><a href="onMenuExport.html" target="function" title=" handles the extra menu entries">onMenuExport </a></li><li><a href="onMenuHelp.html" target="function" title=" shows the Help Information">onMenuHelp </a></li><li><a href="onMenuImport.html" target="function" title=" handles the extra menu entries">onMenuImport </a></li><li><a href="onMenuRestartQuit.html" target="function" title=" restarts or closes the GUI">onMenuRestartQuit </a></li><li><a href="onMenuView.html" target="function" title=" handles the extra menu entries">onMenuView </a></li><li><a href="onMenuViewFigure.html" target="function" title=" shows predefined figure layouts">onMenuViewFigure </a></li></ul>
 
 
 

doc/blochus/functions/blochsim/getPulsePhase.html

@@ -194,7 +194,7 @@ <h2><a name="_source"></a>SOURCE CODE <a href="#_top"><img alt="^" border="0" sr
 0107             <span class="keyword">case</span> 0 <span class="comment">% during pulse</span>
 0108                 theta = 2*pi*(f0.*t + (delta_t*delta_f./fmod.A).*exp(fmod.A.*(-t/delta_t)));
 0109             <span class="keyword">case</span> 1 <span class="comment">% after pulse</span>
-0110                 theta = 2*pi*(fmod.end*t + (delta_t*delta_f./fmod.A)*exp(fmod.A*(-t/delta_t)));
+0110                 theta = 2*pi*(fmod.v1*t + (delta_t*delta_f./fmod.A)*exp(fmod.A*(-t/delta_t)));
 0111         <span class="keyword">end</span>
 0112         
 0113     <span class="keyword">otherwise</span>

doc/blochus/functions/blochsim/getPulseTimeSeries.html

@@ -231,38 +231,33 @@ <h2><a name="_source"></a>SOURCE CODE <a href="#_top"><img alt="^" border="0" sr
 0141                 Bout = 2.*I.*Amp.*[cos(theta + phi + phi_ax + phi_ref) <span class="keyword">...</span>
 0142                     0.*t];
 0143         <span class="keyword">end</span>
-0144         <span class="comment">% test:</span>
-0145         <span class="keyword">if</span> phi ~= 0
-0146             disp(num2str(phi));
-0147         <span class="keyword">end</span>
-0148         <span class="comment">% end test</span>
+0144 <span class="keyword">end</span>
+0145 <span class="comment">% if B-field values are NaN, set them to zero</span>
+0146 <span class="comment">% this can happen due to the interpolation at the end of the MIDI-pulses</span>
+0147 Bout(isnan(Bout)) = 0;
+0148 
 0149 <span class="keyword">end</span>
-0150 <span class="comment">% if B-field values are NaN, set them to zero</span>
-0151 <span class="comment">% this can happen due to the interpolation at the end of the MIDI-pulses</span>
-0152 Bout(isnan(Bout)) = 0;
-0153 
-0154 <span class="keyword">end</span>
-0155 
-0156 <span class="comment">%------------- END OF CODE --------------</span>
-0157 
-0158 <span class="comment">%% License:</span>
-0159 <span class="comment">% GNU GPLv3</span>
-0160 <span class="comment">%</span>
-0161 <span class="comment">% BLOCHUS</span>
-0162 <span class="comment">% Copyright (C) 2019 Thomas Hiller</span>
+0150 
+0151 <span class="comment">%------------- END OF CODE --------------</span>
+0152 
+0153 <span class="comment">%% License:</span>
+0154 <span class="comment">% GNU GPLv3</span>
+0155 <span class="comment">%</span>
+0156 <span class="comment">% BLOCHUS</span>
+0157 <span class="comment">% Copyright (C) 2019 Thomas Hiller</span>
+0158 <span class="comment">%</span>
+0159 <span class="comment">% This program is free software: you can redistribute it and/or modify</span>
+0160 <span class="comment">% it under the terms of the GNU General Public License as published by</span>
+0161 <span class="comment">% the Free Software Foundation, either version 3 of the License, or</span>
+0162 <span class="comment">% (at your option) any later version.</span>
 0163 <span class="comment">%</span>
-0164 <span class="comment">% This program is free software: you can redistribute it and/or modify</span>
-0165 <span class="comment">% it under the terms of the GNU General Public License as published by</span>
-0166 <span class="comment">% the Free Software Foundation, either version 3 of the License, or</span>
-0167 <span class="comment">% (at your option) any later version.</span>
+0164 <span class="comment">% This program is distributed in the hope that it will be useful,</span>
+0165 <span class="comment">% but WITHOUT ANY WARRANTY; without even the implied warranty of</span>
+0166 <span class="comment">% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the</span>
+0167 <span class="comment">% GNU General Public License for more details.</span>
 0168 <span class="comment">%</span>
-0169 <span class="comment">% This program is distributed in the hope that it will be useful,</span>
-0170 <span class="comment">% but WITHOUT ANY WARRANTY; without even the implied warranty of</span>
-0171 <span class="comment">% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the</span>
-0172 <span class="comment">% GNU General Public License for more details.</span>
-0173 <span class="comment">%</span>
-0174 <span class="comment">% You should have received a copy of the GNU General Public License</span>
-0175 <span class="comment">% along with this program.  If not, see &lt;https://www.gnu.org/licenses/&gt;.</span></pre></div>
+0169 <span class="comment">% You should have received a copy of the GNU General Public License</span>
+0170 <span class="comment">% along with this program.  If not, see &lt;https://www.gnu.org/licenses/&gt;.</span></pre></div>
 <hr><address>Generated by <strong><a href="http://www.artefact.tk/software/matlab/m2html/" target="_parent">m2html</a></strong> &copy; 2005</address>
 </body>
 </html>

doc/blochus/functions/interface/plotResults.html

@@ -230,7 +230,7 @@ <h2><a name="_source"></a>SOURCE CODE <a href="#_top"><img alt="^" border="0" sr
 0157 <span class="comment">% axis settings</span>
 0158 grid(ax,<span class="string">'on'</span>);
 0159 set(get(ax,<span class="string">'XLabel'</span>),<span class="string">'String'</span>,<span class="string">'t [ms]'</span>);
-0160 set(get(ax,<span class="string">'YLabel'</span>),<span class="string">'String'</span>,<span class="string">'magnetization M'</span>);
+0160 set(get(ax,<span class="string">'YLabel'</span>),<span class="string">'String'</span>,<span class="string">'magnetization M / M0'</span>);
 0161 <span class="comment">% legend</span>
 0162 lh = legend(ax,<span class="string">'x'</span>,<span class="string">'y'</span>,<span class="string">'z'</span>,<span class="string">'|xy|'</span>,<span class="string">'|M|'</span>,<span class="string">'Location'</span>,<span class="string">'SouthWest'</span>);
 0163 

doc/blochus/functions/interface/switchToolTips.html

@@ -62,7 +62,7 @@ <h2><a name="_cross"></a>CROSS-REFERENCE INFORMATION <a href="#_top"><img alt="^
 </ul>
 This function is called by:
 <ul style="list-style-image:url(../../../matlabicon.gif)">
-<li><a href="../../../blochus/callbacks/menus/onMenuView.html" class="code" title="function onMenuView(src,~)">onMenuView</a>	 handles the extra menu entries</li><li><a href="../../../blochus/callbacks/menus/onMenuViewShow.html" class="code" title="function onMenuViewShow(src,~)">onMenuViewShow</a>	 handles the extra menu entries</li></ul>
+<li><a href="../../../blochus/callbacks/menus/onMenuView.html" class="code" title="function onMenuView(src,~)">onMenuView</a>	 handles the extra menu entries</li></ul>
 <!-- crossreference -->
 
 

doc/blochus/functions/interface/updateStatusInformation.html

@@ -61,7 +61,7 @@ <h2><a name="_cross"></a>CROSS-REFERENCE INFORMATION <a href="#_top"><img alt="^
 </ul>
 This function is called by:
 <ul style="list-style-image:url(../../../matlabicon.gif)">
-<li><a href="../../../blochus/BLOCHUS/BLOCHUS.html" class="code" title="function BLOCHUS">BLOCHUS</a>	 is a graphical user interface (GUI) to simulate NMR spin dynamics</li><li><a href="../../../blochus/callbacks/checkbox/onCheckPrePolPulse.html" class="code" title="function onCheckPrePolPulse(src,~)">onCheckPrePolPulse</a>	 activates / deactivates all control elements needed for</li><li><a href="../../../blochus/callbacks/menus/onMenuView.html" class="code" title="function onMenuView(src,~)">onMenuView</a>	 handles the extra menu entries</li><li><a href="../../../blochus/callbacks/menus/onMenuViewShow.html" class="code" title="function onMenuViewShow(src,~)">onMenuViewShow</a>	 handles the extra menu entries</li><li><a href="../../../blochus/callbacks/popup/onPopupPulseType.html" class="code" title="function onPopupPulseType(src,~)">onPopupPulseType</a>	 selects the pulse type</li><li><a href="../../../blochus/callbacks/push/onPushRun.html" class="code" title="function onPushRun(src,~)">onPushRun</a>	 starts the calculation</li></ul>
+<li><a href="../../../blochus/BLOCHUS/BLOCHUS.html" class="code" title="function BLOCHUS">BLOCHUS</a>	 is a graphical user interface (GUI) to simulate NMR spin dynamics</li><li><a href="../../../blochus/callbacks/checkbox/onCheckPrePolPulse.html" class="code" title="function onCheckPrePolPulse(src,~)">onCheckPrePolPulse</a>	 activates / deactivates all control elements needed for</li><li><a href="../../../blochus/callbacks/menus/onMenuView.html" class="code" title="function onMenuView(src,~)">onMenuView</a>	 handles the extra menu entries</li><li><a href="../../../blochus/callbacks/popup/onPopupPulseType.html" class="code" title="function onPopupPulseType(src,~)">onPopupPulseType</a>	 selects the pulse type</li><li><a href="../../../blochus/callbacks/push/onPushRun.html" class="code" title="function onPushRun(src,~)">onPushRun</a>	 starts the calculation</li></ul>
 <!-- crossreference -->
 
 

functions/blochsim/getPulsePhase.m

@@ -107,7 +107,7 @@
             case 0 % during pulse
                 theta = 2*pi*(f0.*t + (delta_t*delta_f./fmod.A).*exp(fmod.A.*(-t/delta_t)));
             case 1 % after pulse
-                theta = 2*pi*(fmod.end*t + (delta_t*delta_f./fmod.A)*exp(fmod.A*(-t/delta_t)));
+                theta = 2*pi*(fmod.v1*t + (delta_t*delta_f./fmod.A)*exp(fmod.A*(-t/delta_t)));
         end
 
     otherwise

functions/blochsim/getPulseTimeSeries.m

@@ -141,11 +141,6 @@
                 Bout = 2.*I.*Amp.*[cos(theta + phi + phi_ax + phi_ref) ...
                     0.*t];
         end
-        % test:
-        if phi ~= 0
-            disp(num2str(phi));
-        end
-        % end test
 end
 % if B-field values are NaN, set them to zero
 % this can happen due to the interpolation at the end of the MIDI-pulses

functions/interface/plotResults.m

@@ -157,7 +157,7 @@ function plotMag(data,gui,frame)
 % axis settings
 grid(ax,'on');
 set(get(ax,'XLabel'),'String','t [ms]');
-set(get(ax,'YLabel'),'String','magnetization M');
+set(get(ax,'YLabel'),'String','magnetization M / M0');
 % legend
 lh = legend(ax,'x','y','z','|xy|','|M|','Location','SouthWest');
 

pyBLOCHUS/README.md

@@ -0,0 +1,46 @@
+## pyBLOCHUS
+
+Python implementation of the **BLOCHUS** core functionality without any graphical user interface.
+
+### Table of Contents
+1. [About](#about)
+2. [Requirements](#requirements)
+3. [Installation](#installation)
+4. [Usage](#usage)
+
+- - -
+<a name="about"></a>
+### About
+
+**pyBLOCHUS** is a set of python modules, that allow some basic simulations of (S)NMR spin dynamics based on the Bloch equations. The Bloch equations are solved in the laboratory frame of reference with the Scipy solve-ip solver. Because it was developed within the scope of a near surface SNMR project, its main features are the simulation of (1) pre-polarization switch-off ramps and (2) excitation pulses. For graphics output the [matplotlib](https://matplotlib.org/) library is used.
+
+- - -
+<a name="requirements"></a>
+### Requirements
+
+In order to work properly you need to meet the following requirements:
+
+1. A working [Python](https://www.python.org/) installation (I recommend [Anaconda](https://www.anaconda.com/products/individual) - as this is what I use under Windows)
+2. The [NumPy](https://numpy.org/), [SciPy](https://www.scipy.org/) and [matplotlib](https://matplotlib.org/) libraries are <span style="color:red">required</span>
+2. The [Numba](https://numba.pydata.org/) JIT compiler is optional but speeds up the computations considerably.
+
+#### Operating System
+
+I tested it successfully under Windows 7 (64bit) and 10 (64bit) with [Anaconda](https://www.anaconda.com/products/individual) having installed [Python](https://www.python.org/) 3.7.7. and the [Spyder](https://www.spyder-ide.org/) IDE 4.1.3. .
+
+**NOTE:** So far I did not test anything on Linux or a Mac. If you get it to work on either of the two systems (which it basically should I guess) please let me know.
+
+- - -
+<a name="installation"></a>
+### Installation
+
+1. Makes sure that all required packages are installed and work properly
+2. Download or `clone` the **BLOCHUS** repository and put the folder somewhere on your hard drive.
+3. As I recommend uying an IDE like [Spyder](https://www.spyder-ide.org/), make sure that the **pyBLOCHUS** folder is on your PYTHONPATH (e.g. in [Spyder](https://www.spyder-ide.org/):  Tools -> PYTHONPATH manager -> Add path)
+4. Sometimes a [Spyder](https://www.spyder-ide.org/) restart is necessary tu update/sync the PYTHONPATH
+
+- - -
+<a name="usage"></a>
+### Usage
+
+Have a look in the [example](pyBLOCHUS/examples) scripts  for the usage of the different modules.