mumps

MUMPS Installation

MESTI.m uses the sequential version of MUMPS for the augmented partial factorization (APF) method, and optionally for the factorize-and-solve method. Here are steps to install MUMPS.

Download MUMPS

Go to the MUMPS website and fill out the download request form. The MUMPS maintainers will email you the download link.

Prerequisites

To compile the sequential version of MUMPS and its MATLAB interface, you need compilation tools like make, ar, and ranlib, C and Fortran compilers, BLAS library, LAPACK library, and a compatible mex compiler. Instructions specific to the operating system are provided below:

1. Linux
2. macOS
3. Windows

If memory usage is important for you, you can optionally install the METIS (version 5.1.0) program for graph partitioning (not to be confused with MESTI). Download it (you can just download archive/metis-5.1.0.tar.gz), decompress it, and set it to double precision (use #define REALTYPEWIDTH 64 in include/metis.h). Compile it with make config; make. If you have write access to /usr/local, you can install METIS to there with sudo make install; otherwise you can move the METIS folder to where you want and specify its path when compiling MUMPS. Later, if you set opts.use_METIS = true in mesti() or mesti2s(), MUMPS will use METIS instead of the default AMD method for matrix ordering. From our experience, in 2D, AMD is usually faster when using the APF method (because its analysis stage is faster), but METIS can sometimes reduce memory usage. Which one is better depends on the problem. In 3D, the factorization time generally dominates over the analysis time, and the METIS ordering is much better (both in memmory usage and in factorization time) than AMD.

Compile MUMPS

Suppose you downloaded the 5.6.0 version of MUMPS to your ~/Downloads/ folder. Then, go to the folder where you want to compile MUMPS, and enter

tar zxvf ~/Downloads/MUMPS_5.6.0.tar.gz
cd MUMPS_5.6.0

in terminal.

Read the file INSTALL, copy the closest Makefile.inc file in the Make.inc folder, and modify it to fit your environment and machine. Most importantly, in Makefile.inc you need to specify:

• CC: the C compiler to use
• FC: the Fortran compiler to use
• FL: the Fortran linker to use
• LAPACK: how the Fortran compiler can link to the LAPACK library
• LIBBLAS: how the Fortran compiler can link to the BLAS library

If you installed METIS, you also need to specify

• LMETISDIR: path to the folder where the METIS library is
• IMETIS: path to the folder where the METIS headers are

and add -Dmetis to ORDERINGSF.

Examples of Makefile.inc are provided below:

1. Linux
2. macOS
3. Windows

To download, click the link above, and click on the "Download raw file" button to the right of the "Raw" button.

These Makefile.inc examples for Linux and Windows enable multithreading by linking to a multithreaded BLAS library and compiling MUMPS with OpenMP activated.

The Makefile.inc example for macOS does not use multithreading, because there we link to Apple's vecLib within its Accelerate framework for the BLAS library. On Macs with an Apple Silicon processor, the Accelerate framework utilizes the Apple Matrix coprocessor (AMX), so it is not multithreaded but achieves speed comparable to or faster than multithreaded OpenBLAS (e.g., see this benchmark). Multithreading is, therefore, not necessary.

If you have a Mac with an Intel processor, OpenBLAS would be faster than Accelerate. In that case, you can comment out the line LIBBLAS = -framework Accelerate in Makefile.inc by adding a # in the beginning of the line, and uncomment the #LIBBLAS = -L/usr/local/opt/openblas/lib line by deleting its #. In this case, multithreading can provide further speed-up, but we did not work out a multithreaded Makefile.inc example since Apple has moved away from Intel processors.

After done with Makefile.inc, enter

make d z

in terminal, which will compile the sequential version of MUMPS with double precision for real and complex variables (i.e., dmumps and zmumps).

If there is no error, check if the following files have been generated in the lib folder: libdmumps.a (or libdmumps.so) and libzmumps.a (or libzmumps.so).

Warning messages from the Fortran compiler are normal and can be ignored.

If there is error, read the message and try to figure out where it comes from and/or look it up and address it. Before recompiling with make d z, be sure to type make clean first to remove files generate by the previous compile attempt.

Compile the MATLAB interface for MUMPS

cd into the MATLAB folder inside the MUMPS folder and modify make.inc. Most importantly, you need to specify

• MEX: the mex compiler to use
• MUMPS_DIR: path to the folder where MUMPS is compiled
• LIBFORT: how mex can link to the Fortran library
• LIBBLAS: how mex can link to the BLAS and LAPACK libraries

If you installed METIS, you also need to specify

• LMETISDIR: path to the folder where the METIS library is

and uncomment the #LMETIS = -L$(LMETISDIR) -lmetis line.

Examples of make.inc are provided below:

1. Linux
2. macOS
3. Windows

IMPORTANT: When simulating large systems (such as the metalens example), one may encounter segmentation fault due to a bug in the MATLAB interface that comes with MUMPS. Please replace the original mumpsmex.c in this MATLAB folder with a modified one here, mumpsmex.c, which modifies four lines to disable reading the scaling array from MATLAB and returning the scaling array to MATLAB; these lines are where the segmentation fault happens. Since MESTI does not use user-specified scaling arrays, these modifications do not affect functionality.

Then, enter

make

in terminal, which will compile the MATLAB interface for MUMPS. Check that files dmumpsmex.mexa64 and zmumpsmex.mexa64 (or *.mexmaca64 on a Mac) have been generated in the MATLAB folder.

Test MUMPS

Now, open MATLAB, cd to the MATLAB interface folder of MUMPS, and run the following test scripts:

• simple_example.m
• multiplerhs_example.m
• sparserhs_example.m
• schur_example.m
• zsimple_example.m.

If any of them does not run successfully, look back at the compilation of MUMPS or the MATLAB interface to see if there were serious warning messages.

If they all pass, congratulations! You are done.

Add this folder of MATLAB interface for MUMPS to the search path of MATLAB using the addpath command in MATLAB, so mesti() can find the function file zmumps.m there. You can also have this path to be added every time MATLAB starts by editing startup.m with the edit(fullfile(userpath,'startup.m')) command.

If you want to use METIS but your cluster cannot find the METIS library when you run the MATLAB interface for MUMPS, you can append the METIS library to your LD_LIBRARYP_PATH by

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$LMETISDIR

LMETISDIR is the path to the folder where the METIS library is.