install - Man Page

Installation

Requirements

The following tools and libraries are required for installing MEPACK:

If the BLAS / LAPACK library does not provide the full interface, i.e. some routines are not implemented or available for the user, MEPACK builds the required but missing routines from reference LAPACK and includes them in MEPACK. This is the if IBM ESSL is used as BLAS library.

Installation

The source code is configured using CMake. An out-of-source build is preferred. Typically, this is done by 

cmake -S . -B build-dir  <OtherCMakeOptions>
make -C build-dir
make -C build-dir install

The following options can be added to CMake to configure MEPACK properly, for MATLAB/GNU Octave specific options, see below:

Option   Description   Default    -DDEBUG=ON/OFF   Enable building the library in debug mode   OFF    -DBUILD_STATIC=ON/OFF   Enable building the static libraries.   OFF    -DCOVERAGE=ON/OFF   Enable the creation of code coverage files   OFF    -DCMAKE_INSTALL_PREFIX=PREFIX   Installation prefix   /usr/local    -DBLA_VENDOR=VENDOR_NAME   Set the BLAS library to use.   Generic    See FindBLAS.cmake for details   -DHOSTOPT=ON/OFF   Enable host-specific optimizations   OFF    -DLTO=ON/OFF   Enable Link Time Optimization   OFF    -DVALGRIND_SUPPRESSIONS=PATH   Set a suppressions file for valgrind   empty    -DINTEGER8=ON/OFF   Build with 64-bit integers and 64 bit BLAS   OFF    -DFORTRAN_BOUND_CHECK=ON/OFF   Check the array bounds at runtime (slow)   OFF    -DFORTRAN_SANITIZE=ON/OFF   Check the memory accesses at runtime (slow)   OFF    -DDOC=ON/OFF   Build the documentation   OFF    -DMATLAB=ON/OFF   Enable MATLAB / Octave interface building   OFF    -DEXAMPLES=ON/OFF   Build the tests and examples   ON    -DMEPACK_LUA_CONFIG=PATH   Path for an alternative configuration file   empty    -DRECSY=PATH   Path to a precompiled library containing   empty    the RECSY library.   empty    -DGL705=PATH   Path to a precompiled library containing   empty    the code from Algorithm 705 as library.   empty    -DCMAKE_INSTALL_MODULEDIR=PATH   Custom destination directory for Fortran   /usr/include/mepack/    modules.  

The test suite is executed by calling 

make -C build-dir test

If valgrind was found during the configuration procedure, all tets can be executed with the help of valgrind by executing: 

cd build-dir
ctest -D NightlyMemoryCheck

The documentation is built in build-dir/doc by calling: 

make -C build-dir doc

MATLAB/Octave Interface

The MATLAB/Octave interface is built if -DMATLAB=ON is set during configuration. The build process can be adjusted using the following CMake options:

Option   Description   Default    -DMEXOCT_MATLAB_DOC=ON/OFF   Extract the help texts for MATLAB   ON    -DMEXOCT_MATLAB=ON/OFF   Search for MATLAB   ON    -DMEXOCT_OCTAVE=ON/OFF   Search for Octave   ON    -DMEXOCT_MATLAB_ROOT=PATH   Path of the MATLAB installation   empty    -DMEXOCT_OCTAVE_CONFIG=PATH   Full path of the octave-config tool   empty    -DMEXOCT_LINK_STATIC=ON/OFF   Static linking of MEPACK to the MEX/OCT files   OFF    -DMEXOCT_SKIP_RPATH=1/0   Skip the RPATH setting in MEX/OCT files   0  

After compiling, the build directory contains a matlab/matlab folder including the mex files to be used with MATLAB and a matlab/octave folder, which contains the octfiles for GNU Octave. Furthermore, a distribution archive 

mepack-<MEPACK_VERSION>-matlab-<MATLAB_RELEASE>-<ARCH>-dist.tar.gz

for MATLAB and 

mepack-<MEPACK_VERSION>-octave-<OCTAVE_VERSION>-<ARCH>-dist.tar.gz

for GNU Octave is created in the root of the build directory. These files can be used to ship the compiled MEX/OCT files to othersystems.

The test suite is also added to the test target of the main makefile. In this way 

make -C build-dir test

will also test the MATLAB/Octave interface. In order to test the MATLAB/Octave interface separately run 

cd build-dir/matlab
make test

By default (MEXOCT_SKIP_RPATH=0) the MEX and OCT files have set its RPATH to the $ORIGIN and thus will search for the libmepack.so file in the current directory. In this case, the libmepack.so is copied to the matlab or octave directory. In this case, the libmepack.so file will also be added to the distribution archives. If MEXOCT_LINK_STATIC is enabled, no RPATH is required since MEPACK is statically linked to the MEX/OCT files, resulting in larger files. The libmepack.so file is not part of the distribution file in this case.

Attention: The MATLAB part of the interface requires -DINTEGER8=ON in most cases, since MATLAB uses 64-bit integers everywhere. In the case of GNU Octave the setting -DINTEGER8=OFF is required in most cases, since Octave uses 64-bit integers internally, but uses BLAS/LAPACK/other Fortran codes with 32-bit integers.

Attention: Enable the static linkage with MEXOCT_LINK_STATIC also requires to build the static library with BUILD_STATIC=ON.

Warning: The MATLAB interface is implemented using C++ template meta programming and thus the compiling the code leads to a huge memory consumption. If MEPACK is build in parallel, e.g. make -j 4, this can crash your computer. For reason the MATLAB interface should be compiled with one job per 8 GB of free memory. If your are not sure if this is fulfilled, consider compiling the code with only one job, i.e. make -j 1.

RECSY and Algorithm 705

The RECSY library and the reference implementation of Algorithm 705 cannot be shipped due to unclear licenses. If you want to compile the examples with support for these codes, you have to provide a shared or static library containing the codes yourself. Perferably, RECSY and Algorithm 705 should be compiled as static library with the -fPIC flag set during compilation. Then they can be enabled in the during the build via 

cmake ....... -DRECSY=/path/to/librecsy.a -DGL705=/path/to/libgl705.a

Info

Tue Mar 7 2023 Version 1.0.3 MEPACK