LLNL · balos1 · Dec 15, 2023 · Dec 11, 2023 · Dec 11, 2023 · Dec 11, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -85,7 +85,7 @@ sundials_band.h
 
 **Breaking change**
 The following functions have had their signature updated to ensure they can leverage
-the new SUNDIALS error handling capabilties. 
+the new SUNDIALS error handling capabilties.
 
 ```c
 // From sundials_futils.h
@@ -130,7 +130,16 @@ accordingly.
 
 **Breaking change**
 Functions, types and header files that were previously deprecated have been
-removed.
+removed. In addittion the following names/symbols were replaced by ``SUN_ERR_*``
+codes:
+
+```
+SUNMAT_SUCCESS --> SUN_SUCCESS
+SUNMAT_ILL_INPUT --> SUN_ERR_ARG_*
+SUNMAT_MEM_FAIL --> SUN_ERR_MEM_FAIL
+SUNMAT_OPERATION_FAIL --> SUN_ERR_OP_FAIL
+SUNMAT_MATVEC_SETUP_REQUIRED --> SUN_ERR_OP_FAIL
+```
 
 **Breaking change**
 Users now need to link to `sundials_core` in addition to the libraries already linked to. 

diff --git a/doc/shared/sunmatrix/SUNMatrix_MagmaDense.rst b/doc/shared/sunmatrix/SUNMatrix_MagmaDense.rst
@@ -284,7 +284,7 @@ implementation specific functions:
 
    **Return value:**
       * ``SUN_SUCCESS`` -- if the copy is successful.
-      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if either the ``SUNMatrix`` is not a
+      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if the ``SUNMatrix`` is not a
         ``SUNMATRIX_MAGMADENSE`` matrix.
       * ``SUN_ERR_MEM_FAIL`` -- if the copy fails.
 
@@ -300,7 +300,7 @@ implementation specific functions:
 
    **Return value:**
       * ``SUN_SUCCESS`` -- if the copy is successful.
-      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if either the ``SUNMatrix`` is not a
+      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if the ``SUNMatrix`` is not a
         ``SUNMATRIX_MAGMADENSE`` matrix.
       * ``SUN_ERR_MEM_FAIL`` -- if the copy fails.
 

diff --git a/doc/shared/sunmatrix/SUNMatrix_OneMklDense.rst b/doc/shared/sunmatrix/SUNMatrix_OneMklDense.rst
@@ -314,7 +314,7 @@ Copy Data
 
    **Return value:**
       * ``SUN_SUCCESS`` -- if the copy is successful.
-      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if either the ``SUNMatrix`` is not a
+      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if the ``SUNMatrix`` is not a
         ``SUNMATRIX_ONEMKLDENSE`` matrix.
       * ``SUN_ERR_MEM_FAIL`` -- if the copy fails.
 
@@ -330,7 +330,7 @@ Copy Data
 
    **Return value:**
       * ``SUN_SUCCESS`` -- if the copy is successful.
-      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if either the ``SUNMatrix`` is not a
+      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if the ``SUNMatrix`` is not a
         ``SUNMATRIX_ONEMKLDENSE`` matrix.
       * ``SUN_ERR_MEM_FAIL`` -- if the copy fails.
 

diff --git a/doc/shared/sunmatrix/SUNMatrix_Operations.rst b/doc/shared/sunmatrix/SUNMatrix_Operations.rst
@@ -170,27 +170,3 @@ below.
    .. code-block:: c
 
       retval = SUNMatMatvec(A, x, y);
-
-
-.. _SUNMatrix.Ops.errorCodes:
-
-SUNMatrix return codes
-----------------------
-
-The functions provided to SUNMatrix modules within the SUNDIALS-provided
-SUNMatrix implementations utilize a common set of return codes, listed below.
-These adhere to a common pattern: 0 indicates success, a negative value
-indicates a failure. Aside from this pattern, the actual values of each error
-code are primarily to provide additional information to the user in case of a
-SUNMatrix failure.
-
-* ``SUN_SUCCESS`` (0) -- successful call
-
-* ``SUN_ERR_ARG_INCOMPATIBLE`` (-1) -- an illegal input has been provided to the function
-
-* ``SUN_ERR_MEM_FAIL`` (-2) -- failed memory access or allocation
-
-* ``SUN_ERR_OP_FAIL`` (-3) -- a SUNMatrix operation returned nonzero
-
-* ``SUN_ERR_OP_FAIL`` (-4) -- the :c:func:`SUNMatMatvecSetup` routine needs to be
-  called prior to calling :c:func:`SUNMatMatvec`
diff --git a/doc/shared/sunmatrix/SUNMatrix_Sparse.rst b/doc/shared/sunmatrix/SUNMatrix_Sparse.rst
@@ -375,15 +375,18 @@ following additional user-callable routines:
 
 
 
-.. c:function:: int SUNSparseMatrix_Realloc(SUNMatrix A)
+.. c:function:: SUNErrCode SUNSparseMatrix_Realloc(SUNMatrix A)
 
    This function reallocates internal storage arrays in a sparse matrix
    so that the resulting sparse matrix has no wasted space (i.e. the
    space allocated for nonzero entries equals the actual number of
-   nonzeros, ``indexptrs[NP]``). Returns 0 on success and
-   1 on failure (e.g. if the input matrix is not sparse).
+   nonzeros, ``indexptrs[NP]``). Returns a :c:type:`SUNErrCode`.
 
+.. c:function:: SUNErrCode SUNSparseMatrix_Reallocate(SUNMatrix A)
 
+   Function to reallocate internal sparse matrix storage arrays so that the
+   resulting sparse matrix has storage for a specified number of nonzeros.
+   Returns a :c:type:`SUNErrCode`.
 
 .. c:function:: void SUNSparseMatrix_Print(SUNMatrix A, FILE* outfile)
 

diff --git a/examples/arkode/F2003_custom/test_fsunlinsol_fortran_mod.f90 b/examples/arkode/F2003_custom/test_fsunlinsol_fortran_mod.f90
@@ -143,7 +143,7 @@ program main
 
   ! compute B = A*X
   retval = FSUNMatMatvec(sA, sX, sB)
-  if (retval /= SUNMAT_SUCCESS) then
+  if (retval /= SUN_SUCCESS) then
      print *, 'ERROR: FSUNMatMatvec fail'
      stop 1
   end if

diff --git a/examples/arkode/F2003_custom/test_fsunmatrix_fortran_mod.f90 b/examples/arkode/F2003_custom/test_fsunmatrix_fortran_mod.f90
@@ -231,7 +231,7 @@ program main
   ! test SUNMatZero
   retval = FSUNMatZero(sB)
   if ( (check_matrix_entry(sB, 0.d0, 1.d-14, Nvar, N) /= 0) &
-       .or. (retval /= SUNMAT_SUCCESS) ) then
+       .or. (retval /= SUN_SUCCESS) ) then
      fails = fails + 1
      print *, '>>> FAILED test -- FSUNMatZero'
   else
@@ -241,7 +241,7 @@ program main
   ! test SUNMatCopy
   retval = FSUNMatCopy(sA, sB)
   if ( (check_matrix(sA, sB, 1.d-14, Nvar, N) /= 0) &
-       .or. (retval /= SUNMAT_SUCCESS) ) then
+       .or. (retval /= SUN_SUCCESS) ) then
      fails = fails + 1
      print *, '>>> FAILED test -- FSUNMatCopy'
   else
@@ -252,7 +252,7 @@ program main
   retval = FSUNMatCopy(sA, sB)
   retval = FSUNMatScaleAdd(-1.d0, sB, sB)
   if ( (check_matrix_entry(sB, 0.d0, 1.d-14, Nvar, N) /= 0) &
-       .or. (retval /= SUNMAT_SUCCESS) ) then
+       .or. (retval /= SUN_SUCCESS) ) then
      fails = fails + 1
      print *, '>>> FAILED test -- FSUNMatScaleAdd case 1'
   else
@@ -262,9 +262,9 @@ program main
   retval = FSUNMatCopy(sA, sD)
   retval = FSUNMatCopy(sI, sC)
   retval = FSUNMatScaleAdd(1.d0, sD, sI)
-  if (retval == SUNMAT_SUCCESS)  retval = FSUNMatScaleAdd(1.d0, sC, sA)
+  if (retval == SUN_SUCCESS)  retval = FSUNMatScaleAdd(1.d0, sC, sA)
   if ( (check_matrix(sD, sC, 1.d-14, Nvar, N) /= 0) &
-       .or. (retval /= SUNMAT_SUCCESS) ) then
+       .or. (retval /= SUN_SUCCESS) ) then
      fails = fails + 1
      print *, '>>> FAILED test -- FSUNMatScaleAdd case 2'
   else
@@ -275,7 +275,7 @@ program main
   retval = FSUNMatCopy(sI, sB)
   retval = FSUNMatScaleAddI(-1.d0, sB)
   if ( (check_matrix_entry(sB, 0.d0, 1.d-14, Nvar, N) /= 0) &
-       .or. (retval /= SUNMAT_SUCCESS) ) then
+       .or. (retval /= SUN_SUCCESS) ) then
      fails = fails + 1
      print *, '>>> FAILED test -- FSUNMatScaleAddI'
   else
@@ -288,7 +288,7 @@ program main
   retval = FSUNMatMatvec(sB, sX, sZ)
   call FN_VLinearSum(3.d0, sY, 1.d0, sX, sW)
   if ( (check_vector(sW, sZ, 1.d-15*Nvar*Nvar, Nvar, N) /= 0) &
-       .or. (retval /= SUNMAT_SUCCESS) ) then
+       .or. (retval /= SUN_SUCCESS) ) then
      fails = fails + 1
      print *, '>>> FAILED test -- FSUNMatMatvec'
   else

diff --git a/include/sunmatrix/sunmatrix_cusparse.h b/include/sunmatrix/sunmatrix_cusparse.h
@@ -99,8 +99,8 @@ SUNDIALS_EXPORT int* SUNMatrix_cuSparse_IndexPointers(SUNMatrix A);
 SUNDIALS_EXPORT int* SUNMatrix_cuSparse_IndexValues(SUNMatrix A);
 SUNDIALS_EXPORT sunrealtype* SUNMatrix_cuSparse_Data(SUNMatrix A);
 
-SUNDIALS_EXPORT SUNErrCode
-SUNMatrix_cuSparse_SetFixedPattern(SUNMatrix A, sunbooleantype yesno);
+SUNDIALS_EXPORT
+SUNErrCode SUNMatrix_cuSparse_SetFixedPattern(SUNMatrix A, sunbooleantype yesno);
 SUNDIALS_EXPORT SUNErrCode SUNMatrix_cuSparse_SetKernelExecPolicy(
   SUNMatrix A, SUNCudaExecPolicy* exec_policy);
 SUNDIALS_EXPORT int SUNMatrix_cuSparse_NumBlocks(SUNMatrix A);

diff --git a/include/sunmatrix/sunmatrix_magmadense.h b/include/sunmatrix/sunmatrix_magmadense.h
@@ -76,8 +76,8 @@ SUNDIALS_EXPORT sunindextype SUNMatrix_MagmaDense_NumBlocks(SUNMatrix A);
 SUNDIALS_EXPORT sunrealtype** SUNMatrix_MagmaDense_BlockData(SUNMatrix A);
 SUNDIALS_EXPORT SUNErrCode SUNMatrix_MagmaDense_CopyToDevice(SUNMatrix A,
                                                              sunrealtype* h_data);
-SUNDIALS_EXPORT SUNErrCode
-SUNMatrix_MagmaDense_CopyFromDevice(SUNMatrix A, sunrealtype* h_data);
+SUNDIALS_EXPORT
+SUNErrCode SUNMatrix_MagmaDense_CopyFromDevice(SUNMatrix A, sunrealtype* h_data);
 
 SUNDIALS_STATIC_INLINE
 sunrealtype* SUNMatrix_MagmaDense_Block(SUNMatrix Amat, sunindextype k)

diff --git a/src/sunmatrix/band/sunmatrix_band.c b/src/sunmatrix/band/sunmatrix_band.c
@@ -26,6 +26,8 @@
 #include <sundials/sundials_math.h>
 #include <sunmatrix/sunmatrix_band.h>
 
+#include "sundials/sundials_errors.h"
+
 #define ZERO SUN_RCONST(0.0)
 #define ONE  SUN_RCONST(1.0)
 
@@ -123,6 +125,8 @@ void SUNBandMatrix_Print(SUNMatrix A, FILE* outfile)
   SUNFunctionBegin(A->sunctx);
   sunindextype i, j, start, finish;
 
+  SUNAssertVoid(SUNMatGetID(A) == SUNMATRIX_BAND, SUN_ERR_ARG_WRONGTYPE);
+
   /* perform operation */
   fprintf(outfile, "\n");
   for (i = 0; i < SM_ROWS_B(A); i++)
@@ -361,7 +365,8 @@ SUNErrCode SUNMatScaleAdd_Band(sunrealtype c, SUNMatrix A, SUNMatrix B)
   /* Call separate routine in B has larger bandwidth(s) than A */
   if ((SM_UBAND_B(B) > SM_UBAND_B(A)) || (SM_LBAND_B(B) > SM_LBAND_B(A)))
   {
-    return SMScaleAddNew_Band(c, A, B);
+    SUNCheckCall(SMScaleAddNew_Band(c, A, B));
+    return SUN_SUCCESS;
   }
 
   /* Otherwise, perform operation in-place */
@@ -391,6 +396,9 @@ SUNErrCode SUNMatMatvec_Band(SUNMatrix A, N_Vector x, N_Vector y)
   yd = N_VGetArrayPointer(y);
   SUNCheckLastErr();
 
+  SUNAssert(xd, SUN_ERR_MEM_FAIL);
+  SUNAssert(yd, SUN_ERR_MEM_FAIL);
+
   /* Perform operation */
   for (i = 0; i < SM_ROWS_B(A); i++) { yd[i] = ZERO; }
   for (j = 0; j < SM_COLUMNS_B(A); j++)
@@ -407,6 +415,8 @@ SUNErrCode SUNMatSpace_Band(SUNMatrix A, long int* lenrw, long int* leniw)
 {
   SUNFunctionBegin(A->sunctx);
   SUNAssert(SUNMatGetID(A) == SUNMATRIX_BAND, SUN_ERR_ARG_WRONGTYPE);
+  SUNAssert(lenrw, SUN_ERR_ARG_CORRUPT);
+  SUNAssert(leniw, SUN_ERR_ARG_CORRUPT);
   *lenrw = SM_COLUMNS_B(A) * (SM_SUBAND_B(A) + SM_LBAND_B(A) + 1);
   *leniw = 7 + SM_COLUMNS_B(A);
   return SUN_SUCCESS;

diff --git a/src/sunmatrix/cusparse/sunmatrix_cusparse.cu b/src/sunmatrix/cusparse/sunmatrix_cusparse.cu
@@ -618,7 +618,7 @@ SUNErrCode SUNMatrix_cuSparse_SetKernelExecPolicy(SUNMatrix A,
 {
   if (SUNMatGetID(A) != SUNMATRIX_CUSPARSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
 
   /* Reset to the default policy if the new one is NULL */
@@ -643,7 +643,7 @@ SUNErrCode SUNMatrix_cuSparse_CopyToDevice(SUNMatrix dA, sunrealtype* h_data,
 
   if (SUNMatGetID(dA) != SUNMATRIX_CUSPARSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
 
   stream = SMCU_EXECPOLICY(dA)->stream();
@@ -709,7 +709,7 @@ SUNErrCode SUNMatrix_cuSparse_CopyFromDevice(SUNMatrix dA, sunrealtype* h_data,
 
   if (SUNMatGetID(dA) != SUNMATRIX_CUSPARSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
 
   stream = SMCU_EXECPOLICY(dA)->stream();

diff --git a/src/sunmatrix/dense/sunmatrix_dense.c b/src/sunmatrix/dense/sunmatrix_dense.c
@@ -23,6 +23,8 @@
 #include <sundials/priv/sundials_errors_impl.h>
 #include <sunmatrix/sunmatrix_dense.h>
 
+#include "sundials/sundials_errors.h"
+
 #define ZERO SUN_RCONST(0.0)
 #define ONE  SUN_RCONST(1.0)
 
@@ -300,10 +302,11 @@ SUNErrCode SUNMatScaleAdd_Dense(sunrealtype c, SUNMatrix A, SUNMatrix B)
 
 SUNErrCode SUNMatMatvec_Dense(SUNMatrix A, N_Vector x, N_Vector y)
 {
+  SUNFunctionBegin(A->sunctx);
   sunindextype i, j;
   sunrealtype *col_j, *xd, *yd;
-  SUNFunctionBegin(A->sunctx);
 
+  SUNAssert(SUNMatGetID(A) == SUNMATRIX_DENSE, SUN_ERR_ARG_WRONGTYPE);
   SUNCheck(compatibleMatrixAndVectors(A, x, y), SUN_ERR_ARG_DIMSMISMATCH);
 
   /* access vector data (return if NULL data pointers) */
@@ -312,6 +315,10 @@ SUNErrCode SUNMatMatvec_Dense(SUNMatrix A, N_Vector x, N_Vector y)
   yd = N_VGetArrayPointer(y);
   SUNCheckLastErr();
 
+  SUNAssert(xd, SUN_ERR_MEM_FAIL);
+  SUNAssert(yd, SUN_ERR_MEM_FAIL);
+  SUNAssert(xd != yd, SUN_ERR_MEM_FAIL);
+
   /* Perform operation y = Ax */
   for (i = 0; i < SM_ROWS_D(A); i++) { yd[i] = ZERO; }
   for (j = 0; j < SM_COLUMNS_D(A); j++)
@@ -326,6 +333,8 @@ SUNErrCode SUNMatSpace_Dense(SUNMatrix A, long int* lenrw, long int* leniw)
 {
   SUNFunctionBegin(A->sunctx);
   SUNAssert(SUNMatGetID(A) == SUNMATRIX_DENSE, SUN_ERR_ARG_WRONGTYPE);
+  SUNAssert(lenrw, SUN_ERR_ARG_CORRUPT);
+  SUNAssert(leniw, SUN_ERR_ARG_CORRUPT);
   *lenrw = SM_LDATA_D(A);
   *leniw = 3 + SM_COLUMNS_D(A);
   return SUN_SUCCESS;

diff --git a/src/sunmatrix/magmadense/sunmatrix_magmadense.cpp b/src/sunmatrix/magmadense/sunmatrix_magmadense.cpp
@@ -192,7 +192,7 @@ sunindextype SUNMatrix_MagmaDense_Rows(SUNMatrix Amat)
   SUNMatrixContent_MagmaDense A = SMLD_CONTENT(Amat);
 
   if (SUNMatGetID(Amat) == SUNMATRIX_MAGMADENSE) { return (A->M * A->nblocks); }
-  else { return (SUN_ERR_ARG_INCOMPATIBLE); }
+  else { return (SUN_ERR_ARG_WRONGTYPE); }
 }
 
 sunindextype SUNMatrix_MagmaDense_Columns(SUNMatrix Amat)
@@ -293,7 +293,7 @@ SUNErrCode SUNMatrix_MagmaDense_CopyToDevice(SUNMatrix Amat, sunrealtype* h_data
 {
   if (SUNMatGetID(Amat) != SUNMATRIX_MAGMADENSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
   SUNMatrixContent_MagmaDense A = SMLD_CONTENT(Amat);
 
@@ -316,7 +316,7 @@ SUNErrCode SUNMatrix_MagmaDense_CopyFromDevice(SUNMatrix Amat, sunrealtype* h_da
 {
   if (SUNMatGetID(Amat) != SUNMATRIX_MAGMADENSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
   SUNMatrixContent_MagmaDense A = SMLD_CONTENT(Amat);
 
@@ -418,7 +418,7 @@ SUNErrCode SUNMatZero_MagmaDense(SUNMatrix Amat)
 
   if (SUNMatGetID(Amat) != SUNMATRIX_MAGMADENSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
 
   SUNMatrixContent_MagmaDense A = SMLD_CONTENT(Amat);
@@ -444,7 +444,7 @@ SUNErrCode SUNMatCopy_MagmaDense(SUNMatrix Amat, SUNMatrix Bmat)
 
   if (SUNMatGetID(Amat) != SUNMATRIX_MAGMADENSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
 
   SUNMatrixContent_MagmaDense A = SMLD_CONTENT(Amat);
@@ -469,11 +469,11 @@ SUNErrCode SUNMatCopy_MagmaDense(SUNMatrix Amat, SUNMatrix Bmat)
 
 SUNErrCode SUNMatScaleAddI_MagmaDense(sunrealtype c, SUNMatrix Amat)
 {
-  if (Amat == NULL) { return (SUN_ERR_ARG_INCOMPATIBLE); }
+  if (Amat == NULL) { return (SUN_ERR_ARG_CORRUPT; }
 
   if (SUNMatGetID(Amat) != SUNMATRIX_MAGMADENSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
 
   SUNMatrixContent_MagmaDense A = SMLD_CONTENT(Amat);
@@ -619,7 +619,7 @@ SUNErrCode SUNMatSpace_MagmaDense(SUNMatrix Amat, long int* lenrw, long int* len
 
   if (SUNMatGetID(Amat) != SUNMATRIX_MAGMADENSE)
   {
-    return (SUN_ERR_ARG_INCOMPATIBLE);
+    return (SUN_ERR_ARG_WRONGTYPE);
   }
 
   SUNMatrixContent_MagmaDense A = SMLD_CONTENT(Amat);