Notes on other libraries' (sparse) TRSM APIs

[rileyjmurray]

The TRSM API was harder to design. It might change in the future.
Here are some notes that might be relevant to that future planning.

Big design considerations.

1. operations with submatrices. New SparseBLAS, Intel MKL, AOCL, and cuSPARSE support
   operating on submatrices. The conventions are clearlest in Intel docs:
   https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2025-0/interface-consideration.html#GUID-0C896CB1-25B6-4B53-A425-C5954B4C22F9

   ^ My feeling is that Intel's conventions are very cool, but I should punt on this.
   The New SparseBLAS approach isn't that complicated and we could offer something
   like it in the future.

2. Need to figure out if/how API incorporates "diag" and "uplo."

How other libraries handle UPLO and DIAG.

oneAPI : uplo and diag explicit arguments.

• https://oneapi-spec.uxlfoundation.org/specifications/oneapi/v1.3-rev-1/elements/onemkl/source/domains/spblas/trsv
  --> Does have a "diag" parameter. Definition at
  https://oneapi-spec.uxlfoundation.org/specifications/oneapi/v1.3-rev-1/elements/onemkl/source/architecture/architecture#onemkl-enum-diag
  implies entries exist in the sparsity structure but are not accessed if diag==unit.
  --> Seems the only supported storage format is CSR?
  https://oneapi-spec.uxlfoundation.org/specifications/oneapi/v1.3-rev-1/elements/onemkl/source/domains/spblas/format-descriptions

New SparseBLAS : uplo and diag explicit arguments.

• TRSV implementation : https://github.com/SparseBLAS/spblas-reference/blob/c512782a5dcba208441eae665efd43883a9230ad/include/spblas/algorithms/triangular_solve_impl.hpp#L1-L65
  has "DiagonalStorage", which can take one of the values here
  https://github.com/SparseBLAS/spblas-reference/blob/c512782a5dcba208441eae665efd43883a9230ad/include/spblas/detail/triangular_types.hpp#L15-L23
• Looking at the implementation it's clear that the input matrix doesn't even need to be
  structurally triangular. No specific assumption about the diagonal being stored is made
  when diag != explicit. Any diagonal that is stored is ignored if diag != explicit.

Intel MKL : uplo and diag in "desc" argument.

• https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2024-2/mkl-sparse-trsm.html
  --> No "diag" parameter. Only a "desc" parameter.
• https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2025-0/interface-consideration.html#GUID-0C896CB1-25B6-4B53-A425-C5954B4C22F9
  --> See "Operations with Partial Matrices."
• For a matrix in the skyline format with the main diagonal declared to be a unit,
  diagonal elements must be stored in the sparse representation even if they are zero.
  In all other formats, diagonal elements can be stored (if needed) in the sparse
  representation if they are not zero.

AOCL : uplo and diag in "desc"

• Parallelizes over columns
  https://github.com/amd/aocl-sparse/blob/master/library/src/level3/aoclsparse_trsm.hpp
• calls
  https://github.com/amd/aocl-sparse/blob/e9645d728d5698642f686e6f6e25df63cc4c17f6/library/src/level2/aoclsparse_trsv.hpp#L734-L1102
  which does have a matrix descriptor that stores information about being upper or lower, etc...

cuSPARSE : uplo and diag in "desc"

• "The routine supports arbitrary sparsity for the input matrix,
  but only the upper or lower triangular part is taken into account
  in the computation."
  sparse matrix handles include a diag descriptor
• https://docs.nvidia.com/cuda/cusparse/index.html#cusparsecreate
• https://docs.nvidia.com/cuda/cusparse/index.html#cusparsediagtype-t
• https://docs.nvidia.com/cuda/cusparse/index.html#cusparsespmatsetattribute
• referenced in TRSV
  https://docs.nvidia.com/cuda/cusparse/index.html#cusparsespsv

ARM Performance Libraries :

• Does not accept "diag" input to SPSV function.
  https://developer.arm.com/documentation/101004/2410/Sparse-Linear-Algebra/Sparse-Linear-Algebra-Functions/armpl-spsv-exec-d?lang=en

Kokkos

• Doesn't support "diag" parameter for sparse triangular solves.
  https://kokkos.org/kokkos-kernels/docs/API/sparse/sptrsv_solve.html
• See also
  https://kokkos.org/kokkos-kernels/docs/API/sparse/handle_get_create_destroy.html#sptrsv
  for what can be stored in an operation-specific sparse matrix handle,
  along with
  https://kokkos.org/kokkos-kernels/docs/API/sparse/CrsMatrix_constructors.html

SuiteSparse's CXSparse : uplo handled by function name.

• Doesn't support "diag" parameter for triangular solves with dense right-hand-sides
  https://github.com/DrTimothyAldenDavis/SuiteSparse/tree/dev/CXSparse/Source