mumps

MUMPS Installation

MESTI 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, but METIS can sometimes reduce memory usage. Which one is better depends on the problem.

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, click on the "Raw" button, and right click to save the file. If the browser adds a .txt file extension, rename to remove the txt extension.

In the example of Makefile.inc for macOS, we link to Apple's vecLib within its Accelerate framework for the BLAS library by default. For Intel Macs, OpenBLAS is faster, and you can comment out LIBBLAS = -framework Accelerate with a # in the beginning of the line, and uncomment the #LIBBLAS = -L/usr/local/opt/openblas/lib line by deleting its #.

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 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 would like to use METIS, but your cluster cannot find METIS libraries by itself when you run MATLAB interface for MUMPS. You can append the METIS libraries to your LD_LIBRARYP_PATH

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$LMETISDIR

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