error handling in sunmatrix

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. 

doc/shared/sunmatrix/SUNMatrix_Description.rst

@@ -127,7 +127,7 @@ set and all operations are copied when cloning a matrix.
      If successful, this function returns a ``SUNMatrix`` object. If an error
      occurs when allocating the object, then this routine will return ``NULL``.
 
-.. c:function:: int SUNMatCopyOps(SUNMatrix A, SUNMatrix B)
+.. c:function:: SUNErrCode SUNMatCopyOps(SUNMatrix A, SUNMatrix B)
 
   This function copies the function pointers in the ``ops`` structure of ``A``
   into the ``ops`` structure of ``B``.

doc/shared/sunmatrix/SUNMatrix_MagmaDense.rst

@@ -273,7 +273,7 @@ implementation specific functions:
 
 
 
-.. c:function:: int SUNMatrix_MagmaDense_CopyToDevice(SUNMatrix A, sunrealtype* h_data)
+.. c:function:: SUNErrCode SUNMatrix_MagmaDense_CopyToDevice(SUNMatrix A, sunrealtype* h_data)
 
    This function copies the matrix data to the GPU device from the provided host
    array.
@@ -283,13 +283,13 @@ implementation specific functions:
       * *h_data* -- a host array pointer to copy data from.
 
    **Return value:**
-      * ``SUNMAT_SUCCESS`` -- if the copy is successful.
-      * ``SUNMAT_ILL_INPUT`` -- if either the ``SUNMatrix`` is not a
+      * ``SUN_SUCCESS`` -- if the copy is successful.
+      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if the ``SUNMatrix`` is not a
         ``SUNMATRIX_MAGMADENSE`` matrix.
-      * ``SUNMAT_MEM_FAIL`` -- if the copy fails.
+      * ``SUN_ERR_MEM_FAIL`` -- if the copy fails.
 
 
-.. c:function:: int SUNMatrix_MagmaDense_CopyFromDevice(SUNMatrix A, sunrealtype* h_data)
+.. c:function:: SUNErrCode SUNMatrix_MagmaDense_CopyFromDevice(SUNMatrix A, sunrealtype* h_data)
 
    This function copies the matrix data from the GPU device to the provided host
    array.
@@ -299,10 +299,10 @@ implementation specific functions:
       * *h_data* -- a host array pointer to copy data to.
 
    **Return value:**
-      * ``SUNMAT_SUCCESS`` -- if the copy is successful.
-      * ``SUNMAT_ILL_INPUT`` -- if either the ``SUNMatrix`` is not a
+      * ``SUN_SUCCESS`` -- if the copy is successful.
+      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if the ``SUNMatrix`` is not a
         ``SUNMATRIX_MAGMADENSE`` matrix.
-      * ``SUNMAT_MEM_FAIL`` -- if the copy fails.
+      * ``SUN_ERR_MEM_FAIL`` -- if the copy fails.
 
 
 SUNMATRIX_MAGMADENSE Usage Notes

doc/shared/sunmatrix/SUNMatrix_OneMklDense.rst

@@ -303,7 +303,7 @@ Copy Data
 ^^^^^^^^^
 
 
-.. c:function:: int SUNMatrix_OneMklDense_CopyToDevice(SUNMatrix A, sunrealtype* h_data)
+.. c:function:: SUNErrCode SUNMatrix_OneMklDense_CopyToDevice(SUNMatrix A, sunrealtype* h_data)
 
    This function copies the matrix data to the GPU device from the provided host
    array.
@@ -313,13 +313,13 @@ Copy Data
       * *h_data* -- a host array pointer to copy data from.
 
    **Return value:**
-      * ``SUNMAT_SUCCESS`` -- if the copy is successful.
-      * ``SUNMAT_ILL_INPUT`` -- if either the ``SUNMatrix`` is not a
+      * ``SUN_SUCCESS`` -- if the copy is successful.
+      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if the ``SUNMatrix`` is not a
         ``SUNMATRIX_ONEMKLDENSE`` matrix.
-      * ``SUNMAT_MEM_FAIL`` -- if the copy fails.
+      * ``SUN_ERR_MEM_FAIL`` -- if the copy fails.
 
 
-.. c:function:: int SUNMatrix_OneMklDense_CopyFromDevice(SUNMatrix A, sunrealtype* h_data)
+.. c:function:: SUNErrCode SUNMatrix_OneMklDense_CopyFromDevice(SUNMatrix A, sunrealtype* h_data)
 
    This function copies the matrix data from the GPU device to the provided host
    array.
@@ -329,10 +329,10 @@ Copy Data
       * *h_data* -- a host array pointer to copy data to.
 
    **Return value:**
-      * ``SUNMAT_SUCCESS`` -- if the copy is successful.
-      * ``SUNMAT_ILL_INPUT`` -- if either the ``SUNMatrix`` is not a
+      * ``SUN_SUCCESS`` -- if the copy is successful.
+      * ``SUN_ERR_ARG_INCOMPATIBLE`` -- if the ``SUNMatrix`` is not a
         ``SUNMATRIX_ONEMKLDENSE`` matrix.
-      * ``SUNMAT_MEM_FAIL`` -- if the copy fails.
+      * ``SUN_ERR_MEM_FAIL`` -- if the copy fails.
 
 
 SUNMATRIX_ONEMKLDENSE Usage Notes

doc/shared/sunmatrix/SUNMatrix_Operations.rst

@@ -62,7 +62,7 @@ below.
       SUNMatDestroy(A);
 
 
-.. c:function:: int SUNMatSpace(SUNMatrix A, long int *lrw, long int *liw)
+.. c:function:: SUNErrCode SUNMatSpace(SUNMatrix A, long int *lrw, long int *liw)
 
    Returns the storage requirements for the matrix *A*.  *lrw*
    contains the number of sunrealtype words and *liw* contains the number
@@ -80,7 +80,7 @@ below.
       retval = SUNMatSpace(A, &lrw, &liw);
 
 
-.. c:function:: int SUNMatZero(SUNMatrix A)
+.. c:function:: SUNErrCode SUNMatZero(SUNMatrix A)
 
    Zeros all entries of the ``SUNMatrix`` *A*.  The return value is an
    integer flag denoting success/failure of the operation:
@@ -95,7 +95,7 @@ below.
       retval = SUNMatZero(A);
 
 
-.. c:function:: int SUNMatCopy(SUNMatrix A, SUNMatrix B)
+.. c:function:: SUNErrCode SUNMatCopy(SUNMatrix A, SUNMatrix B)
 
    Performs the operation *B \gets A* for all entries of the matrices *A*
    and *B*.  The return value is an integer flag denoting success/failure of
@@ -111,7 +111,7 @@ below.
       retval = SUNMatCopy(A,B);
 
 
-.. c:function:: int SUNMatScaleAdd(sunrealtype c, SUNMatrix A, SUNMatrix B)
+.. c:function:: SUNErrCode SUNMatScaleAdd(sunrealtype c, SUNMatrix A, SUNMatrix B)
 
    Performs the operation *A \gets cA + B*.  The return value is an integer
    flag denoting success/failure of the operation:
@@ -126,7 +126,7 @@ below.
       retval = SUNMatScaleAdd(c, A, B);
 
 
-.. c:function:: int SUNMatScaleAddI(sunrealtype c, SUNMatrix A)
+.. c:function:: SUNErrCode SUNMatScaleAddI(sunrealtype c, SUNMatrix A)
 
    Performs the operation *A \gets cA + I*.  The return value is an integer
    flag denoting success/failure of the operation:
@@ -141,7 +141,7 @@ below.
       retval = SUNMatScaleAddI(c, A);
 
 
-.. c:function:: int SUNMatMatvecSetup(SUNMatrix A)
+.. c:function:: SUNErrCode SUNMatMatvecSetup(SUNMatrix A)
 
    Performs any setup necessary to perform a matrix-vector product.
    The return value is an integer flag denoting success/failure of the
@@ -155,7 +155,7 @@ below.
 
       retval = SUNMatMatvecSetup(A);
 
-.. c:function:: int SUNMatMatvec(SUNMatrix A, N_Vector x, N_Vector y)
+.. c:function:: SUNErrCode SUNMatMatvec(SUNMatrix A, N_Vector x, N_Vector y)
 
    Performs the matrix-vector product *y \gets Ax*.  It should
    only be called with vectors *x* and *y* that are compatible with
@@ -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.
-
-* ``SUNMAT_SUCCESS`` (0) -- successful call
-
-* ``SUNMAT_ILL_INPUT`` (-1) -- an illegal input has been provided to the function
-
-* ``SUNMAT_MEM_FAIL`` (-2) -- failed memory access or allocation
-
-* ``SUNMAT_OPERATION_FAIL`` (-3) -- a SUNMatrix operation returned nonzero
-
-* ``SUNMAT_MATVEC_SETUP_REQUIRED`` (-4) -- the :c:func:`SUNMatMatvecSetup` routine needs to be
-  called prior to calling :c:func:`SUNMatMatvec`

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)
 

doc/shared/sunmatrix/SUNMatrix_cuSparse.rst

@@ -199,16 +199,16 @@ functions:
    the matrix.
 
 
-.. c:function:: int SUNMatrix_cuSparse_CopyToDevice(SUNMatrix A, sunrealtype* h_data, int* h_idxptrs, int* h_idxvals)
+.. c:function:: SUNErrCode SUNMatrix_cuSparse_CopyToDevice(SUNMatrix A, sunrealtype* h_data, int* h_idxptrs, int* h_idxvals)
 
    This functions copies the matrix information to the GPU device from the provided
    host arrays. A user may provide ``NULL`` for any of ``h_data``, ``h_idxptrs``, or
    ``h_idxvals`` to avoid copying that information.
 
-   The function returns ``SUNMAT_SUCCESS`` if the copy operation(s) were successful,
+   The function returns ``SUN_SUCCESS`` if the copy operation(s) were successful,
    or a nonzero error code otherwise.
 
-.. c:function:: int SUNMatrix_cuSparse_CopyFromDevice(SUNMatrix A, sunrealtype* h_data, int* h_idxptrs, int* h_idxvals)
+.. c:function:: SUNErrCode SUNMatrix_cuSparse_CopyFromDevice(SUNMatrix A, sunrealtype* h_data, int* h_idxptrs, int* h_idxvals)
 
    This functions copies the matrix information from the GPU device to the provided
    host arrays. A user may provide ``NULL`` for any of ``h_data``, ``h_idxptrs``, or
@@ -223,11 +223,11 @@ functions:
    * The ``h_idxvals`` array must be at least
      ``(SUNMatrix_cuSparse_BlockNNZ(A))*sizeof(int)`` bytes.
 
-   The function returns ``SUNMAT_SUCCESS`` if the copy operation(s) were successful,
+   The function returns ``SUN_SUCCESS`` if the copy operation(s) were successful,
    or a nonzero error code otherwise.
 
 
-.. c:function:: int SUNMatrix_cuSparse_SetFixedPattern(SUNMatrix A, sunbooleantype yesno)
+.. c:function:: SUNErrCode SUNMatrix_cuSparse_SetFixedPattern(SUNMatrix A, sunbooleantype yesno)
 
    This function changes the behavior of the the ``SUNMatZero`` operation on the object
    ``A``.  By default the matrix sparsity pattern is not considered to be fixed, thus,
@@ -238,7 +238,7 @@ functions:
    Providing a value of ``0`` or ``SUNFALSE`` for the ``yesno`` argument is equivalent
    to the default behavior.
 
-.. c:function:: int SUNMatrix_cuSparse_SetKernelExecPolicy(SUNMatrix A, SUNCudaExecPolicy* exec_policy)
+.. c:function:: SUNErrCode SUNMatrix_cuSparse_SetKernelExecPolicy(SUNMatrix A, SUNCudaExecPolicy* exec_policy)
 
    This function sets the execution policies which control the kernel parameters
    utilized when launching the CUDA kernels. By default the matrix is setup to use

examples/arkode/CXX_parhyp/ark_heat2D_hypre_ls.cpp

@@ -2429,7 +2429,7 @@ int Hypre5ptMatrix_Copy(SUNMatrix A, SUNMatrix B)
   if (flag != 0) { return (flag); }
 
   // Return success
-  return (SUNMAT_SUCCESS);
+  return (SUN_SUCCESS);
 }
 
 int Hypre5ptMatrix_ScaleAddI(sunrealtype c, SUNMatrix A)
@@ -2462,7 +2462,7 @@ int Hypre5ptMatrix_ScaleAddI(sunrealtype c, SUNMatrix A)
   if (flag != 0) { return (flag); }
 
   // Return success
-  return (SUNMAT_SUCCESS);
+  return (SUN_SUCCESS);
 }
 
 // -----------------------------------------------------------------------------

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

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

examples/cvode/CXX_parhyp/cv_heat2D_hypre_ls.cpp

@@ -2338,7 +2338,7 @@ int Hypre5ptMatrix_Copy(SUNMatrix A, SUNMatrix B)
   if (flag != 0) { return (flag); }
 
   // Return success
-  return (SUNMAT_SUCCESS);
+  return (SUN_SUCCESS);
 }
 
 int Hypre5ptMatrix_ScaleAddI(sunrealtype c, SUNMatrix A)
@@ -2371,7 +2371,7 @@ int Hypre5ptMatrix_ScaleAddI(sunrealtype c, SUNMatrix A)
   if (flag != 0) { return (flag); }
 
   // Return success
-  return (SUNMAT_SUCCESS);
+  return (SUN_SUCCESS);
 }
 
 // -----------------------------------------------------------------------------