﻿Installation instruction for LSCM implementation 

1. Preparation

It is easiest to work in a Linux environment. However, MacOS may also work fine (not tested). In Windows 10, a way to go is to install the latest version of WSL and in this virtual machine a Linux distibution of your choice, preferably Ubuntu LTS 18.04 or OpenSuSE 15.4. The latter is my development environment.

The make files depend on gmake. Other implementations may work well, but no guarantee. I was using the GNU C++ and gfortran compilers version 7.5. Additonally, the Intel oneAPI compiler suite 2021.4
was tested. Other compilers may work well, too. The code uses the C++11 standard!

The code makes use of the following libraries:

* The Eigen library: http://eigen.tuxfamily.org/index.php?title=Main_Page. Tested versions are 3.3.9 and 3.4.0. Even if the compilation is optimized, Eigen includes a number of standard checks. You can play around with compiler options to further spped up th executable.
* Suite Sparse, http://faculty.cse.tamu.edu/davis/suitesparse.html. Here, only the routine SPQR is used so far (may change in the future). Tested versions are 5.6.0 and 5.10.1.

* An optimized BLAS/LAPACK library:

+ The Intel MKL library: https://software.intel.com/en-us/mkl. This library is part of Intel oneAPI base now. It is freely usable, note the EULA! Here, only the BLAS and LAPACK routines are needed. Additionally, its FFTW3 interface is used. Tested with different versions, finally version 2024.1.

+ The AMD AOCL library: https://www.amd.com/en/developer/aocl.html. Here, BLAS (blis), LAPACK (flame), and FFTW3 are used. Tested with version 4.1.0.

+ If the optimized libraries cannot be used, any BLAS/LAPACK implementation may be used. However, it should provide best performance. Sometimes I use OpenBLAS (https://www.openblas.net/) as a replacement. Note that the header lapacke.h must be available. Additionally, FFTW3.3.10 is used. Tested with OpenBLAS 0.3.21 and 0.3.27.

* For using the plotting interface, gnuplot must be installed.

Install Intel MKL or AMD AOCL depending on your hardware (or, OpenBLAS and FFTW3), Suite Sparse, Eigen in that order.

2. Install LSCM

The distribution contains an interface to Algorithm 782 of ACM Trans. on Math. Software.
However, the ACM License is incompatible with the GPL. So if you want to use it, install the
fortran source files of the distribution (folder v15.acm, double precision version) in the
subfolder RRQR of the distribution and change the main Makefile varable acordingly.

Change to the root directory of the source tree (this directory). Edit the Makefile there to change the values of the indicated macros according to your installation. The makefile will select MKL/AOCL if it is available on your machine. This will build the library together with a number of demo examples.

In order to test the correct installation, you can run the demos and have a look at the output.

"make doc" will generate the documentation, both in html and latex format. This step will need doxygen. For browsing everything it is easiest to use the html version.

Finally, "make clean" will throw away all generated files (of course not your edited files).
