Skip to content

Commit

Permalink
see CHANGELOG.md
Browse files Browse the repository at this point in the history
  • Loading branch information
ThoHiller committed May 17, 2020
1 parent e74ecb4 commit 1026318
Show file tree
Hide file tree
Showing 18 changed files with 603 additions and 519 deletions.
4 changes: 2 additions & 2 deletions BLOCHUS/BLOCHUS.m
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@
%------------- BEGIN CODE --------------

%% GUI 'header' info and default GUI settings
myui.version = '0.1.1';
myui.date = '16.05.2020';
myui.version = '0.1.2';
myui.date = '17.05.2020';
myui.author = 'Thomas Hiller';
myui.email = 'thomas.hiller[at]leibniz-liag.de';

Expand Down
30 changes: 23 additions & 7 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,29 @@
#### Changelog
# Changelog

##### Version v.0.1.1
## [0.1.2] - 2020-05-17

1. bug fix: in `onPushRun.m` the adiabatic quality p was incorrectly calculated when the total simulation time exceeded the actual switch-off ramp time
2. bug fix: both axes for the pulse frequency and current modulation are now show correctly when exporting the *Current View* figure from the menu
3. new feature: an animation of the latest result can be played for all parameter combinations (e.g. *Pulse + Relaxation* or *Pre-polarization switch-off + Pulse + Relaxation*, etc.)
4. typo fixing within comments and `README.md`
### Changed
- Updated `README.md` and `CHANGELOG.md`.

### Fixed

##### Version v.0.1.0
- When switching the *Pulse* panel on/off, the quality factor settings did not behave as expected.

## [0.1.1] - 2020-05-16

### Added
- An animation of the latest result can be played for all parameter combinations (e.g. *Pulse + Relaxation* or *Pre-polarization switch-off + Pulse + Relaxation*, etc.).

### Fixed

- The adiabatic quality p was incorrectly calculated in `onPushRun.m` when the total simulation time exceeded the actual switch-off ramp time.
- When exporting the *Current View* figure from the menu, both axes for the pulse setup (frequency and current modulation) are now correctly shown.
- Fixed typos in comments and `README.md`.

## [0.1.0] - 2020-05-15

Initial Version

[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
[0.1.0]: https://github.com/ThoHiller/nmr-blochus/releases/tag/v.0.1.0
42 changes: 34 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,25 @@
## BLOCHUS

<img src="blochus_logo_small.png" alt="BLOCHUS icon" width="96">

**BLOCH** **U**niversal **S**imulator

[![release](https://img.shields.io/github/release/ThoHiller/nmr-blochus.svg)](https://github.com/ThoHiller/nmr-blochus/releases/latest)
[![DOI](https://zenodo.org/badge/264257175.svg)](https://zenodo.org/badge/latestdoi/264257175)
- - -

### Table of Contents
1. [About](#about)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Usage](#usage)
5. [Documentation](#documentation)
6. [ToDo](#todo)
7. [Cite as & References](#references)
8. [Changelog](CHANGELOG.md)

- - -
<a name="about"></a>
### About

**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.
Expand All @@ -15,46 +29,50 @@
2. Choose between different pre-polarization switch-off ramp shapes (e.g. *exponential*, *linear*, *half cosine*, etc.) with arbitrary ramp time
3. Choose between different excitation pulses (*pi/2*, *pi*, *adiabatic half passage*, etc.) with arbitrary off-resonance frequency, or in case of the adiabatic pulses, arbitrary frequency and current modulation.

- - -
<img src="blochus_gui_ahp.png" alt="Adiabatic half passage pulse" width="400">
<img src="blochus_gui_linexp.png" alt="Pre-polarization switch-off ramp" width="400">


- - -
<a name="requirements"></a>
### Requirements

In order to work properly you need to meet the following requirements:

1. The [Mathworks](https://www.mathworks.com) MATLAB<sup>TM</sup> software development environment (tested with R2017b and newer)
1. The [Mathworks](https://www.mathworks.com) MATLAB<sup>TM</sup> software development environment (tested with R2017a and newer)
2. The GUI Layout Toolbox (get it from [FEX](https://de.mathworks.com/matlabcentral/fileexchange/47982-gui-layout-toolbox)) (<span style="color:red">required</span>)
3. `findjobj` (get it from [FEX](https://de.mathworks.com/matlabcentral/fileexchange/14317-findjobj-find-java-handles-of-matlab-graphic-objects)) (<span style="color:red">required</span>)

#### Operating System

I tested it successfully under Windows 7 (64bit) and 10 (64bit) with Matlab R2018a.
I tested it successfully under Windows 7 (64bit) and 10 (64bit) with Matlab R2017a and newer. Always with the latest version of the GUI Layout Toolbox (current version is v2.3.4)

**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. It is recommended to install the GUI Layout Toolbox directly into MATLAB<sup>TM</sup> via the mltbx-file (but it should also work via the old-school way of adding the toolbox folders to the MATLAB<sup>TM</sup> path)
2. To use **BLOCHUS** you just need to place the `blochus` folder from the git repository on your hard drive and use the start script `startBLOCHUS` (within this script all necessary **BLOCHUS** folders are added to the MATLAB<sup>TM</sup> path)

- - -

<a name="usage"></a>
### Usage

1. By executing the start scripts (see above)
2. Simply type `BLOCHUS` on the MATLAB<sup>TM</sup> prompt (make sure the `blochus` folder is on the MATLAB<sup>TM</sup> path)
3. Check the example scripts for the usage of the core functions without the GUI (inside the `scripts` folder)

- - -

<a name="documentation"></a>
### Documentation

A basic documentation to **BLOCHUS** can be found in the `blochus\doc` folder. Just open the `index.html` in the web browser of your choice. The documentation was created with [m2html](https://www.artefact.tk/software/matlab/m2html/) by Guillaume Flandin.

- - -

### TODO
<a name="todo"></a>
### ToDo

In no particular order and without guarantee that it will ever happen :-) :

Expand All @@ -63,6 +81,14 @@ In no particular order and without guarantee that it will ever happen :-) :
3. ...

- - -
<a name="references"></a>
### Cite as
If you use BLOCHUS for your research, please cite it as:

Thomas Hiller. (2020, May 17). ThoHiller/nmr-blochus: v0.1.2 (Version v0.1.2). 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.


### References

Expand Down
Binary file added blochus_gui_ahp.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added blochus_gui_linexp.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added blochus_logo_small.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletions callbacks/checkbox/onCheckPrePolPulse.m
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,9 @@ function onCheckPrePolPulse(src,~)
set(gui.edit_handles.PulseIend,'Enable','off');
set(gui.edit_handles.PulseIA,'Enable','off');
set(gui.edit_handles.PulseIB,'Enable','off');
set(gui.check_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQdf,'Enable','off');

% clear Pulse axes
clearSingleAxis(gui.axes_handles.PulseB);
Expand Down Expand Up @@ -156,6 +159,9 @@ function onCheckPrePolPulse(src,~)
set(gui.edit_handles.PulseIend,'Enable','off');
set(gui.edit_handles.PulseIA,'Enable','off');
set(gui.edit_handles.PulseIB,'Enable','off');
set(gui.check_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQdf,'Enable','off');

% clear Pulse axes
clearSingleAxis(gui.axes_handles.PulseB);
Expand Down
6 changes: 5 additions & 1 deletion callbacks/checkbox/onCheckPulseQ.m
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,13 @@ function onCheckPulseQ(src,~)

switch get(src,'Value')
case 0
data.pulse.Istart = 0;
set(gui.edit_handles.PulseIstart,'String',num2str(data.pulse.Istart));
set(gui.edit_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQdf,'Enable','off');
case 1
case 1
data.pulse.Istart = 1;
set(gui.edit_handles.PulseIstart,'String',num2str(data.pulse.Istart));
set(gui.edit_handles.PulseQ,'Enable','on');
set(gui.edit_handles.PulseQdf,'Enable','on');
end
Expand Down
4 changes: 2 additions & 2 deletions callbacks/popup/onPopupPulseDFmode.m
Original file line number Diff line number Diff line change
Expand Up @@ -59,14 +59,14 @@ function onPopupPulseDFmode(src,~)

case 3 % tanh GMR
data.pulse.DFmode = 'tanhGMR';
data.pulse.DFstart = -300;
data.pulse.DFstart = -200;
set(gui.edit_handles.PulseDFstart,'String',num2str(data.pulse.DFstart));
set(gui.edit_handles.PulseDFA,'Enable','off');
set(gui.edit_handles.PulseDFB,'Enable','off');

case 4 % exp
data.pulse.DFmode = 'exp';
data.pulse.DFstart = -300;
data.pulse.DFstart = -200;
data.pulse.DFA = 10;
set(gui.edit_handles.PulseDFstart,'String',num2str(data.pulse.DFstart));
set(gui.edit_handles.PulseDFA,'String',num2str(data.pulse.DFA));
Expand Down
6 changes: 0 additions & 6 deletions callbacks/popup/onPopupPulseImode.m
Original file line number Diff line number Diff line change
Expand Up @@ -50,27 +50,21 @@ function onPopupPulseImode(src,~)

case 2 % tanh MIDI
data.pulse.Imode = 'tanhMIDI';
data.pulse.Istart = 0;
data.pulse.IA = 0.5;
data.pulse.IB = 1;
set(gui.edit_handles.PulseIstart,'String',num2str(data.pulse.Istart));
set(gui.edit_handles.PulseIA,'String',num2str(data.pulse.IA));
set(gui.edit_handles.PulseIA,'Enable','on');
set(gui.edit_handles.PulseIB,'String',num2str(data.pulse.IB));
set(gui.edit_handles.PulseIB,'Enable','on');

case 3 % tanh GMR
data.pulse.Imode = 'tanhGMR';
data.pulse.Istart = 0;
set(gui.edit_handles.PulseIstart,'String',num2str(data.pulse.Istart));
set(gui.edit_handles.PulseIA,'Enable','off');
set(gui.edit_handles.PulseIB,'Enable','off');

case 4 % exp
data.pulse.Imode = 'exp';
data.pulse.Istart = 0;
data.pulse.IA = 10;
set(gui.edit_handles.PulseIstart,'String',num2str(data.pulse.Istart));
set(gui.edit_handles.PulseIA,'String',num2str(data.pulse.IA));
set(gui.edit_handles.PulseIA,'Enable','on');
set(gui.edit_handles.PulseIB,'Enable','off');
Expand Down
19 changes: 18 additions & 1 deletion callbacks/popup/onPopupPulseType.m
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,8 @@ function onPopupPulseType(src,~)
set(gui.edit_handles.PulseIA,'Enable','off');
set(gui.edit_handles.PulseIB,'Enable','off');
set(gui.check_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQdf,'Enable','off');

case 2 % pi
data.pulse.Type = 'pi';
Expand Down Expand Up @@ -96,6 +98,8 @@ function onPopupPulseType(src,~)
set(gui.edit_handles.PulseIA,'Enable','off');
set(gui.edit_handles.PulseIB,'Enable','off');
set(gui.check_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQdf,'Enable','off');

case 3 % free
data.pulse.Type = 'free';
Expand All @@ -120,6 +124,8 @@ function onPopupPulseType(src,~)
set(gui.edit_handles.PulseIA,'Enable','off');
set(gui.edit_handles.PulseIB,'Enable','off');
set(gui.check_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQdf,'Enable','off');

case 4 % AHP
data.pulse.Type = 'AHP';
Expand All @@ -133,7 +139,11 @@ function onPopupPulseType(src,~)
set(gui.edit_handles.PulseDFA,'Enable','off');
set(gui.edit_handles.PulseDFB,'Enable','off');

data.pulse.Istart = 0;
if get(gui.check_handles.PulseQ,'Value') == 0
data.pulse.Istart = 0;
else
data.pulse.Istart = 1;
end
data.pulse.Iend = 1;
set(gui.popup_handles.PulseImode,'Enable','on');
set(gui.edit_handles.PulseIstart,'Enable','on','String',num2str(data.pulse.Istart));
Expand All @@ -142,6 +152,9 @@ function onPopupPulseType(src,~)
set(gui.edit_handles.PulseIB,'Enable','off');
set(gui.check_handles.PulseQ,'Enable','on');

setappdata(fig,'data',data);
onCheckPulseQ(gui.check_handles.PulseQ);
data = getappdata(fig,'data');
setappdata(fig,'data',data);
onPopupPulseDFmode(gui.popup_handles.PulseDFmode);
data = getappdata(fig,'data');
Expand Down Expand Up @@ -173,6 +186,8 @@ function onPopupPulseType(src,~)
set(gui.edit_handles.PulseIA,'Enable','off');
set(gui.edit_handles.PulseIB,'Enable','off');
set(gui.check_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQdf,'Enable','off');

% update the GUI as if the number of periods would have been
% changed manually
Expand Down Expand Up @@ -209,6 +224,8 @@ function onPopupPulseType(src,~)
set(gui.edit_handles.PulseIA,'Enable','on','String',num2str(data.pulse.IA));
set(gui.edit_handles.PulseIB,'Enable','on','String',num2str(data.pulse.IB));
set(gui.check_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQ,'Enable','off');
set(gui.edit_handles.PulseQdf,'Enable','off');

% update the GUI as if the number of periods would have been
% changed manually
Expand Down
4 changes: 2 additions & 2 deletions doc/blochus/BLOCHUS/BLOCHUS.html
Original file line number Diff line number Diff line change
Expand Up @@ -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.1'</span>;
0037 myui.date = <span class="string">'16.05.2020'</span>;
0036 myui.version = <span class="string">'0.1.2'</span>;
0037 myui.date = <span class="string">'17.05.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
Expand Down
Loading

0 comments on commit 1026318

Please sign in to comment.