Repository files navigation

modeling and iNversion of nUCLear magnetic rEsonance data with angUlar poreS

1. About
2. Requirements
3. Installation
4. Usage
5. Documentation
6. ToDo
7. Cite as & References
8. Changelog

NUCLEUS is a set of MATLAB^TM tools, that allow forward and inverse modeling of nuclear magnetic resonance (NMR) relaxometry data (T₁ and T₂ relaxation). The main front-ends to these tools are two graphical user interfaces,NUCLEUSmod andNUCLEUSinv for forward and inverse modeling, respectively. For simple NMR relaxometry data inversion, theNUCLEUSinv GUI may be a littlefeature-rich. But one of the ideas, when starting to develop this code, was to help students understand the basic concepts of NMR relaxometry data inversion.

1. Generate pore size distributions (PSD) that can have a cylindrical, rectangular or polygonal cross section
2. Calculate a capillary pressure saturation curve (CPSC) for the PSD by applying a range of non-zero air pressures (the capillaries are assumed to be water filled and completely water-wet); different saturations for drainage and imbibition conditions are considered
3. Based on the different saturation levels along the CPSC, calculate the corresponding geometry-dependent forward NMR signals
4. 2D forward modeling of T1-T2 data

NUCLEUSmod	NUCLEUSmod - 2D (T1-T2)

1. Can importNUCLEUSmod data (directly from the open GUI or from a saved session file) and a wide range of different laboratory NMR data files (please contact me if you need a specific import routine for your data)
2. Expert mode for more features (Standard mode has basic settings which should be sufficient for most users)
3. Simple pre-processing of NMR signals (cutting, gating, normalizing, phasing)
4. Different inversion options to process NMR data (e.g. mono-exponential fit, bi-exponential fit, multi-exponential fit) and estimate the uncertainty of the resulting relaxation time distributions (RTDs)
5. Different regularization options for multi-exponential fitting (e.g. manual, L-curve, SVD tools)
6. Joint inversion of NMR and CPS data to directly infer a PSD (non-linear inversion of surface relaxivity and PSD)
7. 2D inversion of T1-T2 data

NUCLEUSinv	NUCLEUSinv - 2D (T1-T2)
NUCLEUSinv - RTD Uncertainty View	NUCLEUSinv - Phase View

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

1. TheMathworks MATLAB^TM software development environment (tested with R2016b and newer)
   • The Optimization toolbox (optional)
   • The Statistics toolbox (optional)
2. The GUI Layout Toolbox (get it fromFEX) (required)
3. The regularization toolbox from P. Hansen (get it fromFEX or find out more about ithere) (required)
4. findjobj (get it fromFEX) (required)
5. fminsearchbnd (get it fromFEX) (required)
6. dynamicDateTicks (get it fromFEX) (optional)
7. kde kernel density estimator (get it fromFEX) (optional; not needed for R2023b and newer)
8. imagescnan (get it fromFEX) (optional; only needed for the 2D inversion)

If you do not have the Optimization or Statistics toolboxes then not all features are available (especially parts of the joint inversion). However, the general functionality of obtaining relaxation time distributions (RTDs) form NMR relaxometry data is of course working.

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

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.

1. It is recommended to install the GUI Layout Toolbox directly into MATLAB^TM via the mltbx-file (but it should also work via the old-school way of adding the toolbox folders to the MATLAB^TM path)
2. To useNUCLEUS you just need to place thenucleus folder from the git repository on your hard drive and use the start scriptsstartNUCLEUSinv andstartNUCLEUSmod, respectively (within these scripts all necessaryNUCLEUS folders are added to the MATLAB^TM path)

NOTE: It is recommended to have onlyone version ofNUCLEUS on your current MATLAB^TM path.

1. By executing the start scripts (see above)
2. Simply typeNUCLEUSinv orNUCLEUSmod on the MATLAB^TM prompt (make sure thenucleus folder is on the MATLAB^TM path)
3. Check the demo scripts for the usage of the core functions without the GUI (inside thescripts folder)

A basic documentation toNUCLEUS can be found in thenucleus\doc folder. Just open theindex.html in the web browser of your choice. The documentation was created withm2html by Guillaume Flandin.

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

1. A Manual (this is on top of my agenda)
2. Adapt the core functionality in a Python module
3. NUCLEUSinv:
   • An import wizard to get rid of the import menu
   • Easy way to set optimization settings
   • For noise estimation: select manually a range of the NMR raw signal
4. ...

If you use NUCLEUS for your research, please cite it as:

Thomas Hiller. (2024, Nov 27). ThoHiller/nmr-nucleus: v0.3.0 (Version v0.3.0). Zenodo. [https://doi.org/10.5281/zenodo.4022195]

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.

1. Lorenzoni,R., Cunningham, P., Fritsch, T., Schmidt, W., Kruschwitz, S. and Bruno, G. "Microstructure analysis of cement-biochar composites",Materials and Structures,57, 2024, 175,DOI
2. Kruschwitz, S., Munsch, S., Telong, M., Schmidt, W., Bintz, T., Fladt, M. and Stelzner, L., "The NMR core analyzing tomograph: a multi-functional tool for non-destructive testing of building materials",Magnetic Resonance Letters.3(3), 2023, 207-219,DOI
3. Costabel, S., Hiller, T. and Houben, G. "Nuclear magnetic resonance at the laboratory and field scale as a tool for detecting redox fronts in aquifers",GEOPHYSICS,88(2), 2023, KS13-KS25,DOI
4. Costabel, S., Hiller, T., Dlugosch, R., Kruschwitz, S. and Müller-Petke, M. "Evaluation of single-sided nuclear magnetic resonance technology for usage in geosciences",Measurement Science and Technology,34(1), 2023, 015112,DOI
5. Munsch, S., Bintz, T., Heyn, R., Hirsch, H., Grunewald, J. and Kruschwitz, S., "Detailed investigation of capillary active insulation materials by 1H nuclear magnetic resonance (NMR) and thermogravimetric drying", International Symposium on Non-Destructive Testing in Civil Engineering (NDT-CE 2022), 16-18 August 2022, Zurich, Switzerland,e-Journal of Nondestructive Testing,27(9),DOI
6. Hiller, T., Costabel, S., Radic, T., Dlugosch, R. and Müller-Petke, M. "Feasibility study on prepolarized surface nuclear magnetic resonance for soil moisture measurements",Vadose Zone Journal,20(5), 2021, e20138,DOI
7. Costabel, S. and Hiller, T., "Soil hydraulic interpretation of nuclear magnetic resonance measurements based on circular and triangular capillary models",Vadose Zone Journal,20(2), 2021, e20104,DOI
8. Hiller, T. and Klitzsch, N., "Joint inversion of nuclear magnetic resonance data from partially saturated rocks using a triangular pore model",GEOPHYSICS,83(4), JM15-JM28, 2018,DOI

MATLAB is a registered trademark of The Mathworks, Inc.