Skip to content

Commit

Permalink
error handling in stuff that isnt in the other PRs (#392)
Browse files Browse the repository at this point in the history 
Co-authored-by: David Gardner <[email protected]>
Co-authored-by: Daniel R. Reynolds <[email protected]>
  • Loading branch information
@balos1 @gardner48 @drreynolds
3 people authored Dec 13, 2023
1 parent 2dffb50 commit 2545e03
Show file tree
Hide file tree
Showing 31 changed files with 688 additions and 710 deletions.
80 changes: 24 additions & 56 deletions doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,14 +59,14 @@ function pointers to the various controller operations, and is defined as
struct _generic_SUNAdaptController_Ops {
SUNAdaptController_Type (*getid)(SUNAdaptController C);
int (*destroy)(SUNAdaptController C);
int (*estimatestep)(SUNAdaptController C, sunrealtype h, int p, sunrealtype dsm, sunrealtype* hnew);
int (*reset)(SUNAdaptController C);
int (*setdefaults)(SUNAdaptController C);
int (*write)(SUNAdaptController C, FILE* fptr);
int (*seterrorbias)(SUNAdaptController C, sunrealtype bias);
int (*updateh)(SUNAdaptController C, sunrealtype h, sunrealtype dsm);
int (*space)(SUNAdaptController C, long int *lenrw, long int *leniw);
SUNErrCode (*destroy)(SUNAdaptController C);
SUNErrCode (*estimatestep)(SUNAdaptController C, sunrealtype h, int p, sunrealtype dsm, sunrealtype* hnew);
SUNErrCode (*reset)(SUNAdaptController C);
SUNErrCode (*setdefaults)(SUNAdaptController C);
SUNErrCode (*write)(SUNAdaptController C, FILE* fptr);
SUNErrCode (*seterrorbias)(SUNAdaptController C, sunrealtype bias);
SUNErrCode (*updateh)(SUNAdaptController C, sunrealtype h, sunrealtype dsm);
SUNErrCode (*space)(SUNAdaptController C, long int *lenrw, long int *leniw);
};
Expand Down Expand Up @@ -137,7 +137,7 @@ note these requirements below. Additionally, we note the behavior of the base SU
SUNAdaptController_Type id = SUNAdaptController_GetType(C);
.. c:function:: int SUNAdaptController_Destroy(SUNAdaptController C)
.. c:function:: SUNErrCode SUNAdaptController_Destroy(SUNAdaptController C)
Deallocates the controller *C*. If this method is not provided by the
implementation, the base class method will free both the *content* and
Expand All @@ -147,16 +147,15 @@ note these requirements below. Additionally, we note the behavior of the base SU
routine).
:param C: the :c:type:`SUNAdaptController` object.
:return: error code indicating success failure
(see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
.. code-block:: c
retval = SUNAdaptController_Destroy(C);
.. c:function:: int SUNAdaptController_EstimateStep(SUNAdaptController C, sunrealtype h, int p, sunrealtype dsm, sunrealtype* hnew)
.. c:function:: SUNErrCode SUNAdaptController_EstimateStep(SUNAdaptController C, sunrealtype h, int p, sunrealtype dsm, sunrealtype* hnew)
Estimates a single-rate step size. This routine is required for controllers
of type ``SUN_ADAPTCONTROLLER_H``. If this is not provided by the
Expand All @@ -167,60 +166,56 @@ note these requirements below. Additionally, we note the behavior of the base SU
:param p: the current order of accuracy for the time integration method.
:param dsm: the local temporal estimate from the previous step attempt.
:param hnew: (output) the estimated step size.
:return: error code indicating success failure
(see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
.. code-block:: c
retval = SUNAdaptController_EstimateStep(C, hcur, p, dsm, &hnew);
.. c:function:: int SUNAdaptController_Reset(SUNAdaptController C)
.. c:function:: SUNErrCode SUNAdaptController_Reset(SUNAdaptController C)
Resets the controller to its initial state, e.g., if it stores a small number
of previous *dsm* or *h* values.
:param C: the :c:type:`SUNAdaptController` object.
:return: error code indicating success failure
(see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
.. code-block:: c
retval = SUNAdaptController_Reset(C);
.. c:function:: int SUNAdaptController_SetDefaults(SUNAdaptController C)
.. c:function:: SUNErrCode SUNAdaptController_SetDefaults(SUNAdaptController C)
Sets the controller parameters to their default values.
:param C: the :c:type:`SUNAdaptController` object.
:return: error code indicating success failure
(see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
.. code-block:: c
retval = SUNAdaptController_SetDefaults(C);
.. c:function:: int SUNAdaptController_Write(SUNAdaptController C, FILE* fptr)
.. c:function:: SUNErrCode SUNAdaptController_Write(SUNAdaptController C, FILE* fptr)
Writes all controller parameters to the indicated file pointer.
:param C: the :c:type:`SUNAdaptController` object.
:param fptr: the output stream to write the parameters to.
:return: error code indicating success failure
(see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
.. code-block:: c
retval = SUNAdaptController_Write(C, stdout);
.. c:function:: int SUNAdaptController_SetErrorBias(SUNAdaptController C, sunrealtype bias)
.. c:function:: SUNErrCode SUNAdaptController_SetErrorBias(SUNAdaptController C, sunrealtype bias)
Sets an error bias factor for scaling the local error factors. This is
typically used to slightly exaggerate the temporal error during the
Expand All @@ -229,16 +224,15 @@ note these requirements below. Additionally, we note the behavior of the base SU
:param C: the :c:type:`SUNAdaptController` object.
:param bias: the error bias factor -- an input :math:`\leq 0` indicates to use
the default value for the controller.
:return: error code indicating success failure
(see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
.. code-block:: c
retval = SUNAdaptController_SetErrorBias(C, 1.2);
.. c:function:: int SUNAdaptController_UpdateH(SUNAdaptController C, sunrealtype h, sunrealtype dsm)
.. c:function:: SUNErrCode SUNAdaptController_UpdateH(SUNAdaptController C, sunrealtype h, sunrealtype dsm)
Notifies a controller of type SUN_ADAPTCONTROLLER_H that a successful time step
was taken with stepsize *h* and local error factor *dsm*, indicating that these
Expand All @@ -249,16 +243,15 @@ note these requirements below. Additionally, we note the behavior of the base SU
:param C: the :c:type:`SUNAdaptController` object.
:param h: the successful step size.
:param dsm: the successful temporal error estimate.
:return: error code indicating success failure
(see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
.. code-block:: c
retval = SUNAdaptController_UpdateH(C, h, dsm);
.. c:function:: int SUNAdaptController_Space(SUNAdaptController C, long int *lenrw, long int *leniw)
.. c:function:: SUNErrCode SUNAdaptController_Space(SUNAdaptController C, long int *lenrw, long int *leniw)
Informative routine that returns the memory requirements of the
:c:type:`SUNAdaptController` object.
Expand All @@ -269,8 +262,7 @@ note these requirements below. Additionally, we note the behavior of the base SU
:param leniw: (output) number of ``sunindextype`` words stored in the
controller. This may also include pointers, `int` and
`long int` words.
:return: error code indicating success failure
(see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
Expand All @@ -280,30 +272,6 @@ note these requirements below. Additionally, we note the behavior of the base SU
.. _SUNAdaptController.Description.errorCodes:

SUNAdaptController Error Codes
------------------------------

SUNAdaptController functions return one of the following set of error codes:

* ``SUNADAPTCONTROLLER_SUCCESS`` (0) -- successful call.

* ``SUNADAPTCONTROLLER_ILL_INPUT`` (-1001) -- an illegal input has been provided to the function.

* ``SUNADAPTCONTROLLER_MEM_FAIL`` (-1002) -- a memory access or allocation failed.

* ``SUNADAPTCONTROLLER_USER_FCN_FAIL`` (-1003) -- a user-supplied function returned a nonzero [error] value.

* ``SUNADAPTCONTROLLER_OPERATION_FAIL`` (-1004) -- catch-all for errors not in the above list.

.. note::
The SUNDIALS time integrators do not rely on these specific return values and only
on whether the returned values are 0 (successful) or non-zero (failure). Thus,
user-defined implementations are not required to use these specific error codes,
so long as the zero/non-zero convention is followed.


C/C++ API Usage
---------------

Expand Down
4 changes: 2 additions & 2 deletions doc/shared/sunadaptcontroller/SUNAdaptController_ImExGus.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ routines:
SUNAdaptController C = SUNAdaptController_ImExGus(sunctx);
.. c:function:: int SUNAdaptController_SetParams_ImExGus(SUNAdaptController C, sunrealtype k1e, sunrealtype k2e, sunrealtype k1i, sunrealtype k2i)
.. c:function:: SUNErrCode SUNAdaptController_SetParams_ImExGus(SUNAdaptController C, sunrealtype k1e, sunrealtype k2e, sunrealtype k1i, sunrealtype k2i)
This user-callable function provides control over the relevant parameters
above. This should be called *before* the time integrator is called to evolve
Expand All @@ -119,7 +119,7 @@ routines:
:param k2e: parameter used within the controller time step estimate.
:param k1i: parameter used within the controller time step estimate.
:param k2i: parameter used within the controller time step estimate.
:return: error code indication success or failure (see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
Expand Down
24 changes: 12 additions & 12 deletions doc/shared/sunadaptcontroller/SUNAdaptController_Soderlind.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ also provides the following additional user-callable routines:
SUNAdaptController C = SUNAdaptController_Soderlind(sunctx);
.. c:function:: int SUNAdaptController_SetParams_Soderlind(SUNAdaptController C, sunrealtype k1, sunrealtype k2, sunrealtype k3, sunrealtype k4, sunrealtype k5)
.. c:function:: SUNErrCode SUNAdaptController_SetParams_Soderlind(SUNAdaptController C, sunrealtype k1, sunrealtype k2, sunrealtype k3, sunrealtype k4, sunrealtype k5)
This user-callable function provides control over the relevant parameters
above. This should be called *before* the time integrator is called to evolve
Expand All @@ -111,7 +111,7 @@ also provides the following additional user-callable routines:
:param k3: parameter used within the controller time step estimate.
:param k4: parameter used within the controller time step estimate.
:param k5: parameter used within the controller time step estimate.
:return: error code indication success or failure (see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
Expand All @@ -137,7 +137,7 @@ also provides the following additional user-callable routines:
SUNAdaptController C = SUNAdaptController_PID(sunctx);
.. c:function:: int SUNAdaptController_SetParams_PID(SUNAdaptController C, sunrealtype k1, sunrealtype k2, sunrealtype k3)
.. c:function:: SUNErrCode SUNAdaptController_SetParams_PID(SUNAdaptController C, sunrealtype k1, sunrealtype k2, sunrealtype k3)
This user-callable function provides control over the relevant parameters
above for a PID controller, setting :math:`k_4 = k_5 = 0`. This should be
Expand All @@ -147,7 +147,7 @@ also provides the following additional user-callable routines:
:param k1: parameter used within the controller time step estimate.
:param k2: parameter used within the controller time step estimate.
:param k3: parameter used within the controller time step estimate.
:return: error code indication success or failure (see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
Expand All @@ -172,7 +172,7 @@ also provides the following additional user-callable routines:
SUNAdaptController C = SUNAdaptController_PI(sunctx);
.. c:function:: int SUNAdaptController_SetParams_PI(SUNAdaptController C, sunrealtype k1, sunrealtype k2)
.. c:function:: SUNErrCode SUNAdaptController_SetParams_PI(SUNAdaptController C, sunrealtype k1, sunrealtype k2)
This user-callable function provides control over the relevant parameters
above for a PI controller, setting :math:`k_3 = k_4 = k_5 = 0`. This should
Expand All @@ -181,7 +181,7 @@ also provides the following additional user-callable routines:
:param C: the SUNAdaptController_Soderlind object.
:param k1: parameter used within the controller time step estimate.
:param k2: parameter used within the controller time step estimate.
:return: error code indication success or failure (see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
Expand All @@ -206,15 +206,15 @@ also provides the following additional user-callable routines:
SUNAdaptController C = SUNAdaptController_I(sunctx);
.. c:function:: int SUNAdaptController_SetParams_I(SUNAdaptController C, sunrealtype k1)
.. c:function:: SUNErrCode SUNAdaptController_SetParams_I(SUNAdaptController C, sunrealtype k1)
This user-callable function provides control over the relevant parameters
above for an I controller, setting :math:`k_2 = k_3 = k_4 = k_5 = 0`. This
should be called *before* the time integrator is called to evolve the problem.
:param C: the SUNAdaptController_Soderlind object.
:param k1: parameter used within the controller time step estimate.
:return: error code indication success or failure (see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.
Usage:
Expand All @@ -240,7 +240,7 @@ also provides the following additional user-callable routines:
SUNAdaptController C = SUNAdaptController_ExpGus(sunctx);
.. c:function:: int SUNAdaptController_SetParams_ExpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat)
.. c:function:: SUNErrCode SUNAdaptController_SetParams_ExpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat)
This user-callable function provides control over the relevant parameters
above for the explicit Gustafsson controller, setting :math:`k_3 = k_4 = k_5 = 0`.
Expand All @@ -260,7 +260,7 @@ also provides the following additional user-callable routines:
:param C: the SUNAdaptController_Soderlind object.
:param k1_hat: parameter used within the explicit Gustafsson controller time step estimate.
:param k2_hat: parameter used within the explicit Gustafsson controller time step estimate.
:return: error code indication success or failure (see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.

Usage:

Expand All @@ -286,7 +286,7 @@ also provides the following additional user-callable routines:
SUNAdaptController C = SUNAdaptController_ImpGus(sunctx);
.. c:function:: int SUNAdaptController_SetParams_ImpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat)
.. c:function:: SUNErrCode SUNAdaptController_SetParams_ImpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat)
This user-callable function provides control over the relevant parameters
above for the implicit Gustafsson controller, setting :math:`k_3 = k_4 = k_5 = 0`.
Expand All @@ -306,7 +306,7 @@ also provides the following additional user-callable routines:
:param C: the SUNAdaptController_Soderlind object.
:param k1_hat: parameter used within the implicit Gustafsson controller time step estimate.
:param k2_hat: parameter used within the implicit Gustafsson controller time step estimate.
:return: error code indication success or failure (see :numref:`SUNAdaptController.Description.errorCodes`).
:return: :c:type:`SUNErrCode` indicating success or failure.

Usage:

Expand Down
18 changes: 9 additions & 9 deletions doc/shared/sunmemory/SUNMemory_CUDA.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,10 +68,10 @@ The implementation provides the following operations defined by the
**Returns:**
* An ``int`` flag indicating success (zero) or failure (non-zero).
* A new :c:type:`SUNMemory` object.
.. c:function:: int SUNMemoryHelper_Dealloc_Cuda(SUNMemoryHelper helper, \
.. c:function:: SUNErrCode SUNMemoryHelper_Dealloc_Cuda(SUNMemoryHelper helper, \
SUNMemory mem, void* queue)
Deallocates the ``mem->ptr`` field if it is owned by ``mem``, and then
Expand All @@ -85,10 +85,10 @@ The implementation provides the following operations defined by the
**Returns:**
* An ``int`` flag indicating success (zero) or failure (non-zero).
* A :c:type:`SUNErrCode` indicating success or failure.
.. c:function:: int SUNMemoryHelper_Copy_Cuda(SUNMemoryHelper helper, \
.. c:function:: SUNErrCode SUNMemoryHelper_Copy_Cuda(SUNMemoryHelper helper, \
SUNMemory dst, SUNMemory src, \
size_t mem_size, void* queue)
Expand All @@ -108,10 +108,10 @@ The implementation provides the following operations defined by the
**Returns:**
* An ``int`` flag indicating success (zero) or failure (non-zero).
* A :c:type:`SUNErrCode` indicating success or failure.
.. c:function:: int SUNMemoryHelper_CopyAsync_Cuda(SUNMemoryHelper helper, \
.. c:function:: SUNErrCode SUNMemoryHelper_CopyAsync_Cuda(SUNMemoryHelper helper, \
SUNMemory dst, \
SUNMemory src, \
size_t mem_size, void* queue)
Expand All @@ -133,10 +133,10 @@ The implementation provides the following operations defined by the
**Returns:**
* An ``int`` flag indicating success (zero) or failure (non-zero).
* A :c:type:`SUNErrCode` indicating success or failure.
.. c:function:: int SUNMemoryHelper_GetAllocStats_Cuda(SUNMemoryHelper helper, SUNMemoryType mem_type, unsigned long* num_allocations, \
.. c:function:: SUNErrCode SUNMemoryHelper_GetAllocStats_Cuda(SUNMemoryHelper helper, SUNMemoryType mem_type, unsigned long* num_allocations, \
unsigned long* num_deallocations, size_t* bytes_allocated, \
size_t* bytes_high_watermark)
Expand All @@ -153,4 +153,4 @@ The implementation provides the following operations defined by the
**Returns:**
* An ``int`` flag indicating success (zero) or failure (non-zero).
* A :c:type:`SUNErrCode` indicating success or failure.
Loading

0 comments on commit 2545e03

Please sign in to comment.