=================== UTL HelperFunctions =================== .. meta:: :description: UTL helper functions of dmritool .. include:: meta_keywords.txt .. include:: links.inc UTL Module ========== This module contains some helper functions, logging macros, debug macros, and an N-dimensional array class implemented using `expression template `__ with support for MKL_, OpenBlas_, Lapack_ and OpenMP_. Although OOP is good, sometimes functional style of programming is more attractive, and classes are too heavy for some specific tasks, e.g. reading text lines from a file, converting a container object to another container object. Thus we prefer using some small functions for those tasks. Build ===== UTL module has only header files and can be used separately based on the different dependencies. See :ref:`file dependency `. To build codes using ``utl::NDArray``, you need to have MKL_ or OpenBlas_ + Lapack_, and your compile needs to support `C++11`_. - MKL_ is free for students, educators, academic researchers and open source contributors. See `the free download link `__. OpenBlas_ and Lapack_ are always free and easy to use. - If you choose OpenBlas_ + Lapack_, you can use them from system repositories. In this case, you need to set environment variables correctly. See `FAQ of OpenBlas `__. :: git clone https://github.com/xianyi/OpenBLAS.git cd OpenBlas git checkout v0.2.13 make BINARY=64 USE_THREAD=0 USE_OPENMP=1 cc=gcc FC=gfortran make install utl::NDArray ============ - ``utl::NDArray`` is an N-dimensional array based on `expression template `__. - ``utl::NDArray`` and ``utl::NDArray`` are more efficient than ``vnl_vector`` and ``vnl_matrix`` because * ``utl::NDArray`` is implemented based on openblas_, lapack_ or mkl_. * ``utl::NDArray`` uses `expression template `__ to avoid temporary copies. * ``utl::NDArray`` uses `rvalue references and move constructors, move assignment from C++11 `__. - You can run ``utlVNLBlasGTest`` and ``utlVNLLapackGTest`` to compare efficiency of ``utl::NDArray`` and ``vnl_vector``, ``vnl_matrix``. File structure and dependency ============================= .. _dependency: +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Files | Dependency | Description | +================================+=============================================+===========================================================================================================================================================================+ | utlSmartAssert.h | std | macros for smart assert, modified based on the `SMART_ASSERT library `__ by `John Torjo `__. | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlCoreMacro.h | std | macros for print and debug | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlCore.h | std | useful functions for general purpose | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlCore11.h | std, c++11 specific | useful functions for general purpose | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlCoreMKL.h | std, (mkl optional) | useful functions for mkl. If mkl is not found, a manual implementation is used. | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlCommandLineParser.h | std | small but powerful command line parser, borrowed from `CImg `__ | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlMath.h | std | math related functions | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlRotationMatrixFromVectors.h | std | functions to find rotation 3x3 matrix from two 3D vectors | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlSTDHeaders.h | std | macros to avoid include confliction issues for different versions of std | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlTypeinfo.h | std, c++11 specific | type alias for c++11 | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlGTest.h | google gtest | useful macros for gtest_ | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utl\_cblas.h | cblas | header file from ``cblas.h``. Add some macro conditions to avoid multiple definition issues from other versions of cblas. | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlBlas.h | cblas, (mkl optional) | templated version of interface for cblas | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlLapack.h | lapack | templated version of interface for ``lapacke`` | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlMKL.h | mkl | templated version of interface for mkl_ | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlExpression.h | std | Implementation of `Expression Template `__ to avoid temporary copies in expression. | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlFunctors.h | std | Some functor classes, and functions for ``utl::NDArray``. | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlNDArray.h | std, blas, lapack, (mkl optional) | ``utl::NDArray`` class (N-dimensional array) based on expression template, blas and mkl. | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlVector.h | std, blas, lapack, (mkl optional) | ``utl::NDArray`` class (vector). | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlMatrix.h | std, blas, lapack, (mkl optional) | ``utl::NDArray`` class (matrix). | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utl4thOrderTensor.h | std, blas, lapack, (mkl optional) | ``utl::NDArray`` class (4th order tensor). | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlNDArrayFunctions.h | std, blas, lapack, (mkl optional) | ``utl::NDArray`` related functions. | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlDMRI.h | std, ``utl::NDArray`` | Useful functions for dMRI | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlDMRIStoredTables.h | std, ``utl::NDArray`` | Precomputed tables for dmritool | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlOpenMP.h | openmp | openmp_ related functions | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlVNL.h | vnl | vnl related functions | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlVNLBlas.h | vnl, blas | useful functions for vnl vector and matrix using blas implementation | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlVNLLapack.h | vnl, blas, lapack | useful functions for vnl vector and matrix using blas and lapack implementation | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlVNLIO.h | std, vnl, blas, lapack, (mkl optional) | conversion between ``utl::NDArray`` and ``vnl_vector``, ``vnl_matrix`` | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlITKMacro.h | itk | macros for itk_ | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlITK.h | itk | functions for itk | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utlVTKMacro.h | vtk | macros for vtk_ | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | utl.h | std, itk, blas, lapack, gsl, (mkl optional) | useful functions for dmritool_ | +--------------------------------+---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+