SuiteSparse Documentation

cpu_features is a cross-platform C library (implemented in C99) used to retrieve CPU features, such as available instruction sets, at runtime. It is designed to be:

• Simple and Extensible: Easy to use and easy to add new architectures or features.
• Highly Portable: Uses C99 to ensure compatibility with old compilers and many architectures.
• Sandbox-compatible: Employs strategies to work in environments where cpuid might be unavailable or restricted.
• Low-level safe: It is thread-safe, performs no memory allocation, and raises no exceptions, making it suitable for use within fundamental libc functions like malloc or memcpy.
• Unit tested.

xxHash is an extremely fast hash algorithm designed to process data at RAM speed limits. It is highly portable and produces identical hashes across all platforms (little/big endian). The library provides several variants depending on your requirements for bit-width and performance:

• XXH32: Generates 32-bit hashes using 32-bit arithmetic.
• XXH64: Generates 64-bit hashes using 64-bit arithmetic.
• XXH3: Generates 64-bit or 128-bit hashes (the 128-bit variant is called XXH128) using vectorized arithmetic. This is the most modern and high-performance variant.

The SPEX_Utilities folder provides a collection of shared utility functions used across all SPEX software packages. It serves as a centralized library for common operations to ensure consistency and code reuse throughout the SPEX ecosystem.

The utilities are categorized into three primary functional groups:

1. GMP/MPFR Wrappers: Functions that wrap the GNU Multiple Precision Arithmetic Library (GMP) and the Multiple Precision Floating-Point Reliable (MPFR) library, providing SPEX-specific interfaces for high-precision arithmetic.
2. Matrix Functions: Shared routines for performing matrix operations required by various SPEX packages.
3. Memory Handling Functions: Utilities for managing memory allocation and deallocation within the SPEX environment.

All functions within this directory are subject to test coverage via the SPEX/Tcov framework.

FACTORIZE is an object-oriented MATLAB method designed for solving linear systems and least squares problems. It can be used with both full-rank and rank-deficient matrices.

Key Dependencies:

• To use the COD (Complete Orthogonal Decomposition) function for sparse matrices, you must have the SPQR mexFunction from the SuiteSparse library installed.
• If SPQR is not available, the FACTORIZE method will still function for full-rank matrices and other use cases, but the COD functionality for sparse matrices will be unavailable. This is because COD is specifically utilized for rank-deficient matrices.

The CHOLMOD demo directory contains several demonstration files categorized by data type (precision and integer size):

• cholmod_di_demo.c: double precision / int32
• cholmod_dl_demo.c: double precision / int64
• cholmod_si_demo.c: single precision / int32
• cholmod_sl_demo.c: single precision / int64
• cholmod_simple.c: A very short, simple double precision demo.
• cholmod_s_simple.c: The single precision version of the simple demo.

SPEX_Backslash is a software package designed to exactly solve sparse systems of linear equations. It achieves exact solutions by utilizing Integer-Preserving factorizations.

Users can provide an input matrix and a right-hand side vector file. The package supports outputting the final solution to a user-specified file in two formats:

1. Double precision
2. Full precision rational numbers

If you need to integrate SPEX_Backslash into a larger software application rather than running it as a standalone tool, you should consult the provided examples for implementation guidance.

SuiteSparseCollection is a MATLAB toolbox designed for managing the SuiteSparse Matrix Collection. While typical MATLAB users of the collection do not need this toolbox, it is essential for maintainers or researchers who need to:

• Create the collection index (ss_index.mat).
• Generate web pages and images for the collection.
• Convert matrices between MATLAB .mat formats and Matrix Market (MM) or Rutherford/Boeing (RB) formats.
• Compute matrix statistics.

Note that the ssread function allows users to read MM/ and RB/ versions of the collection directly into MATLAB without explicit extraction, though it is slower than the ssget package.

The LAGraph/experimental/benchmark/matching-tests/ directory contains tools for generating graphs and verifying matchings.

C++ Programs

• gen_bipartite: Generates a random undirected bipartite graph based on user parameters. It can produce exact (maximum) or approximate (naive) matchings and optional performance data.
• gen_general: Generates a random undirected general (non-bipartite) graph based on user parameters. It can produce exact (maximum) or approximate (naive) matchings and optional performance data.
• verify_matching: A utility used to verify the correctness of a matching produced by GraphBLAS. (Note: This is primarily used internally by bench.py).

Python Programs

• bench.py: An automation tool designed to run a predefined list of tests.

CSparse is a concise sparse matrix package focused on direct methods. It is designed to be asymptotically optimal or fast in practice, while remaining concise and robust.

Key Constraints and Scope

• Direct Methods Only: The package focuses on direct solvers; it does not include iterative methods or eigenvalue solvers.
• Real Matrices Only: Complex matrices are not supported, except for methods that only operate on the nonzero pattern of a matrix. For complex matrix support, use the CXSparse package.
• Dependencies: Some MATLAB tests require the AMD (Approximate Minimum Degree) package.
• Performance Note: While the factorization methods are concise and easy to understand, they may not be as competitive in performance as UMFPACK or CHOLMOD.

rmm_wrap is a C-callable wrapper for the NVIDIA Rapids Memory Manager (RMM). It provides a bridge for C applications to utilize RMM's memory management capabilities.

It works by defining a single global object, RMM_Wrap_Handle, which contains an RMM memory resource and a C++ std::unordered_map. This architecture allows the library to expose 7 specific functions to C applications.

Warning: The rmm_wrap functions are NOT thread safe.

CHOLMOD is a sparse Cholesky modification package designed for factorizing sparse symmetric positive definite matrices (of the form $A$ or $AA^T$). It provides routines for:

• Factorizing sparse symmetric positive definite matrices.
• Updating and downdating sparse Cholesky factorizations.
• Solving linear systems.
• Updating and downdating solutions to triangular systems ($Lx=b$).
• Various other sparse matrix functions for both symmetric and unsymmetric matrices.

CHOLMOD supports both real and complex matrices, including single precision sparse matrices via the CHOLMOD:Utility Module. It is written in ANSI/ISO C and is compatible with Microsoft Windows, Unix, and Linux.