SPEX is a software package for SParse EXact algebra

Aug 20, 2024

Files and folders in this distribution:

README.md           this file

AMD                 Approximate minimum degree ordering for
                    preordering matrices prior to factorization.
                    Please see www.suitesparse.com for more information

COLAMD              Column approximate minimum degree ordering
                    for preordering matrices prior to factorization.
                    Please see www.suitesparse.com for more information

include             Header files for SPEX that are generated by
                    the general makefile

SPEX                Folder containing the SPEX package

SuiteSparse_config  Configuration for all SuiteSparse functions.
                    Please see www.suitesparse.com for information

Dependencies of SPEX:

AMD                 approximate minimum degree ordering

COLAMD              column approximate minimum degree ordering

SuiteSparse_config  configuration for all of SuiteSparse

GNU GMP             GNU Multiple Precision Arithmetic Library
                    for big integer operations

GNU MPFR            GNU Multiple Precision Floating-Point Reliable
                    Library for arbitrary precision floating point
                    operations

Default 'local' instalation locations:

include
lib
bin

To compile SPEX and its dependencies, a very simple top-level Makefile is provided. All it does is use cmake to build each of the packages.

Makefile    to compile all of SPEX and its dependencies

            make            compiles SuiteSparse libraries.
                            Subsequent "make install" will install
                            in just /usr/local/lib.
                            Normally requires "sudu make install"

            make local      compiles SuiteSparse.
                            Subsequent "make install will install only
                            in ./lib, ./include only.  No sudo required.
                            Does not install in /usr/local/lib.

            make global     compiles SuiteSparse libraries.
                            Subsequent "make install" will install in
                            just /usr/local/lib (or whatever your
                            CMAKE_INSTALL_PREFIX is).
                            Normally requires "sudu make install"
                            Does not install in ./lib and ./include.

            make install    installs in the current directory
                            (./lib, ./include), and/or in
                            /usr/local/lib and /usr/local/include,
                            depending on whether "make", "make local",
                            "make global", or "make both",
                            etc has been done.

            make demos      run a few short demos

            make uninstall  undoes 'make install'

            make distclean  removes all files not in distribution, including
                            ./bin, ./lib, and ./include.

            make purge      same as 'make distclean'

            make clean      removes all files not in distribution, but
                            keeps compiled libraries and demoes, ./lib
                            and ./include.

You can also use cmake or ccmake directly. For example, try:

cd AMD/build
ccmake ..
make

---

How to cite the SPEX meta-package and its component packages:

• for AMD:

  P. Amestoy, T. A. Davis, and I. S. Duff, Algorithm 837: An approximate minimum degree ordering algorithm, ACM Trans. on Mathematical Software, 30(3), 2004, pp. 381--388. https://dl.acm.org/doi/abs/10.1145/1024074.1024081

  P. Amestoy, T. A. Davis, and I. S. Duff, An approximate minimum degree ordering algorithm, SIAM J. Matrix Analysis and Applications, 17(4), 1996, pp. 886--905. https://doi.org/10.1137/S0895479894278952

• for COLAMD:

  T. A. Davis, J. R. Gilbert, S. Larimore, E. Ng, Algorithm 836: COLAMD, an approximate column minimum degree ordering algorithm, ACM Trans. on Mathematical Software, 30(3), 2004, pp. 377--380. https://doi.org/10.1145/1024074.1024080

  T. A. Davis, J. R. Gilbert, S. Larimore, E. Ng, A column approximate minimum degree ordering algorithm, ACM Trans. on Mathematical Software, 30(3), 2004, pp. 353--376. https://doi.org/10.1145/1024074.1024079

• for SPEX:

  Christopher Lourenco, Jinhao Chen, Erick Moreno-Centeno, and T. A. Davis. 2022. Algorithm 1021: SPEX Left LU, Exactly Solving Sparse Linear Systems via a Sparse Left-Looking Integer-Preserving LU Factorization. ACM Trans. Math. Softw. June 2022. https://doi.org/10.1145/3519024

---

Compilation options

You can set specific options for CMake with the command (for example):

    cmake -DBUILD_STATIC_LIBS=OFF -DCMAKE_BUILD_TYPE=Debug ..

That command will compile SPEX, AMD, COLAMD, and SuiteSparse_config. Debug mode will be used (the build type). The static libraries will not be built (since -DBUILD_STATIC_LIBS=OFF is set).

• SUITESPARSE_ENABLE_PROJECTS:

  Semicolon separated list of projects to be built or all. Default: all in which case the following projects are built:

  suitesparse_config;amd;colamd;spex

• CMAKE_BUILD_TYPE:

  Default: Release, use Debug for debugging.

• SUITESPARSE_USE_STRICT:

  SuiteSparse has many user-definable settings of the form SUITESPARSE_USE_* or (package)_USE_* for some particular package. In general, these settings are not strict. For example, if SUITESPARSE_USE_OPENMP is ON then OpenMP is preferred, but SuiteSparse can be used without OpenMP so no error is generated if OpenMP is not found. However, if SUITESPARSE_USE_STRICT is ON then all *_USE_* settings are treated strictly and an error occurs if any are set to ON but the corresponding package or setting is not available. The *_USE_SYSTEM_* settings are always treated as strict. Default: OFF.

• CMAKE_INSTALL_PREFIX:

  Defines the install location (default on Linux is /usr/local). For example, this command while in a folder build in the top level SuiteSparse folder will set the install directory to /stuff, used by the subsequent sudo cmake --install .:

    cmake -DCMAKE_INSTALL_PREFIX=/stuff ..
    sudo cmake --install .

• SUITESPARSE_PKGFILEDIR:

  Directory where CMake Config and pkg-config files will be installed. By default, CMake Config files will be installed in the subfolder cmake of the directory where the (static) libraries will be installed (e.g., lib). The .pc files for pkg-config will be installed in the subfolder pkgconfig of the directory where the (static) libraries will be installed.

  This option allows to install them at a location different from the (static) libraries. This allows to install multiple configurations of the SuiteSparse libraries at the same time (e.g., by also setting a different CMAKE_RELEASE_POSTFIX and CMAKE_INSTALL_LIBDIR for each of them). To pick up the respective configuration in downstream projects, set, e.g., CMAKE_PREFIX_PATH (for CMake) or PKG_CONFIG_PATH (for build systems using pkg-config) to the path containing the respective CMake Config files or pkg-config files.

• SUITESPARSE_INCLUDEDIR_POSTFIX:

  Postfix for installation target of header from SuiteSparse. Default: suitesparse, so the default include directory is: CMAKE_INSTALL_PREFIX/include/suitesparse

• BUILD_SHARED_LIBS:

  If ON, shared libraries are built. Default: ON.

• BUILD_STATIC_LIBS:

  If ON, static libraries are built. Default: ON, except for GraphBLAS, which takes a long time to compile so the default for GraphBLAS is OFF unless BUILD_SHARED_LIBS is OFF.

• SUITESPARSE_USE_OPENMP:

  If ON, OpenMP is used by default if it is available. Default: ON. SPEX relies on OpenMP for its thread safety.

• SUITESPARSE_CONFIG_USE_OPENMP:

  If ON, SuiteSparse_config uses OpenMP if it is available. Default: SUITESPARSE_USE_OPENMP. It is not essential and only used to let SuiteSparse_time call omp_get_wtime.

• SPEX_USE_OPENMP:

  If ON, OpenMP is used in SPEX if it is available. Default: SUITESPARSE_USE_OPENMP.

• SUITESPARSE_DEMOS:

  If ON, build the demo programs for each package. Default: OFF.

• SUITESPARSE_USE_SYSTEM_AMD:

  If ON, use AMD libraries installed on the build system. If OFF, automatically build AMD as dependency if needed. Default: OFF.

• SUITESPARSE_USE_SYSTEM_COLAMD:

  If ON, use COLAMD libraries installed on the build system. If OFF, automatically build COLAMD as dependency if needed. Default: OFF.

• SUITESPARSE_USE_SYSTEM_SUITESPARSE_CONFIG:

  If ON, use SuiteSparse_config libraries installed on the build system. If OFF, automatically build SuiteSparse_config as dependency if needed. Default: OFF.

---

Acknowledgements

We would like to thank François Bissey, Sebastien Villemot, Erik Welch, Jim Kitchen, Markus Mützel, and Fabian Wein for their valuable feedback on the SuiteSparse build system and how it works with various Linux / Python distros and other package managers. If you are a maintainer of a SuiteSparse packaging for a Linux distro, conda-forge, R, spack, brew, vcpkg, etc, please feel free to contact us if there's anything we can do to make your life easier.

See also the various Acknowledgements within each package.

Primary Author of SPEX: Chris Lourenco

SPEX Coauthors (alphabetical order):

Jinhao Chen
Timothy A Davis
Lorena Mejia Domenzain
Erick Moreno-Centeno