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

@@ -57,13 +57,13 @@ defined as
      SUNMatrix_ID (*getid)(SUNMatrix);
      SUNMatrix    (*clone)(SUNMatrix);
      void         (*destroy)(SUNMatrix);
-     int          (*zero)(SUNMatrix);
-     int          (*copy)(SUNMatrix, SUNMatrix);
-     int          (*scaleadd)(sunrealtype, SUNMatrix, SUNMatrix);
-     int          (*scaleaddi)(sunrealtype, SUNMatrix);
-     int          (*matvecsetup)(SUNMatrix);
-     int          (*matvec)(SUNMatrix, N_Vector, N_Vector);
-     int          (*space)(SUNMatrix, long int*, long int*);
+     SUNErrCode   (*zero)(SUNMatrix);
+     SUNErrCode   (*copy)(SUNMatrix, SUNMatrix);
+     SUNErrCode   (*scaleadd)(sunrealtype, SUNMatrix, SUNMatrix);
+     SUNErrCode   (*scaleaddi)(sunrealtype, SUNMatrix);
+     SUNErrCode   (*matvecsetup)(SUNMatrix);
+     SUNErrCode   (*matvec)(SUNMatrix, N_Vector, N_Vector);
+     SUNErrCode   (*space)(SUNMatrix, long int*, long int*);
    };
 
 
@@ -79,9 +79,9 @@ operation:
 
 .. code-block:: c
 
-   int SUNMatZero(SUNMatrix A)
+   SUNErrCode SUNMatZero(SUNMatrix A)
    {
-     return((int) A->ops->zero(A));
+     return(A->ops->zero(A));
    }
 
 :numref:`SUNMatrix.Ops` contains a complete list of all
@@ -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``.
@@ -137,9 +137,7 @@ set and all operations are copied when cloning a matrix.
       * *B* -- the matrix to copy operations to.
 
    **Return value:**
-      If successful, this function returns ``0``. If either of the inputs
-      are ``NULL`` or the ``ops`` structure of either input is ``NULL``,
-      then is function returns a non-zero value.
+      * A :c:type:`SUNErrCode`
 
 .. c:function:: void SUNMatFreeEmpty(SUNMatrix A)
 
@@ -164,15 +162,15 @@ identifier.
    :align: center
 
    ======================  =================================================
-   Matrix ID               Matrix type                                      
+   Matrix ID               Matrix type
    ======================  =================================================
-   SUNMATRIX_BAND          Band :math:`M \times M` matrix                     
-   SUNMATRIX_CUSPARSE      CUDA sparse CSR matrix                             
-   SUNMATRIX_CUSTOM        User-provided custom matrix                      
-   SUNMATRIX_DENSE         Dense :math:`M \times N` matrix      
+   SUNMATRIX_BAND          Band :math:`M \times M` matrix
+   SUNMATRIX_CUSPARSE      CUDA sparse CSR matrix
+   SUNMATRIX_CUSTOM        User-provided custom matrix
+   SUNMATRIX_DENSE         Dense :math:`M \times N` matrix
    SUNMATRIX_GINKGO        SUNMatrix wraper for Ginkgo matrices
-   SUNMATRIX_MAGMADENSE    Dense :math:`M \times N` matrix        
-   SUNMATRIX_ONEMKLDENSE   oneMKL dense :math:`M \times N` matrix             
-   SUNMATRIX_SLUNRLOC      SUNMatrix wrapper for SuperLU_DIST SuperMatrix     
-   SUNMATRIX_SPARSE        Sparse (CSR or CSC) :math:`M\times N` matrix       
+   SUNMATRIX_MAGMADENSE    Dense :math:`M \times N` matrix
+   SUNMATRIX_ONEMKLDENSE   oneMKL dense :math:`M \times N` matrix
+   SUNMATRIX_SLUNRLOC      SUNMatrix wrapper for SuperLU_DIST SuperMatrix
+   SUNMATRIX_SPARSE        Sparse (CSR or CSC) :math:`M\times N` matrix
    ======================  =================================================

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,10 +80,10 @@ 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:
+   Zeros all entries of the ``SUNMatrix`` *A*.  The return value
+   denotes the success/failure of the operation:
 
    .. math::
       A_{i,j} = 0, \quad i=1,\ldots,m, \; j=1,\ldots,n.
@@ -95,10 +95,10 @@ 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
+   and *B*.  The return value denotes the success/failure of
    the operation:
 
    .. math::
@@ -111,10 +111,10 @@ 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:
+   Performs the operation *A \gets cA + B*.  The return value
+   denotes the success/failure of the operation:
 
    .. math::
       A_{i,j} = cA_{i,j} + B_{i,j}, \quad i=1,\ldots,m, \; j=1,\ldots,n.
@@ -126,10 +126,10 @@ 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:
+   Performs the operation *A \gets cA + I*.  The return value
+   denotes the success/failure of the operation:
 
    .. math::
       A_{i,j} = cA_{i,j} + \delta_{i,j}, \quad i,j=1,\ldots,n.
@@ -141,10 +141,10 @@ 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
+   The return value denotes the success/failure of the
    operation. It is useful for SUNMatrix implementations which need to
    prepare the matrix itself, or communication structures before performing
    the matrix-vector product.
@@ -155,12 +155,12 @@ 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
    the matrix *A* -- both in storage type and dimensions.  The return
-   value is an integer flag denoting success/failure of the operation:
+   value denotes the success/failure of the operation:
 
    .. math::
       y_i = \sum_{j=1}^n A_{i,j} x_j, \quad i=1,\ldots,m.
@@ -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