Skip to content

Commit

Permalink
Merge branch 'feature/error-handling-staging' into feature/error-hand…
Browse files Browse the repository at this point in the history 
…ling-kinsol
  • Loading branch information
@balos1
balos1 committed Dec 12, 2023
2 parents bf440b5 + 9b66b14 commit b5680be
Show file tree
Hide file tree
Showing 47 changed files with 1,248 additions and 2,080 deletions.
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,14 @@ This will be picked up automatically in projects that use the SUNDIALS CMake tar
The library `sundials_generic` has been superceded by `sundials_core` and is no longer available.
This fixes some duplicate symbol errors on Windows when linking to multiple SUNDIALS libraries.

**Breaking change**
The `*SetErrHandlerFn` and `*SetErrFile` functions in CVODE(S), IDA(S), ARKODE and KINSOL have been
removed. Users of these functions can use the functions `SUNContext_PushErrHandler`, and
`SUNLogger_SetErrorFilename` instead. For further details see the [Error
Checking](https://sundials.readthedocs.io/en/latest/sundials/Errors_link.html) and
[Logging](https://sundials.readthedocs.io/en/latest/sundials/Logging_link.html) sections in the
documentation.


## Changes to SUNDIALS in release 6.6.2

Expand Down
17 changes: 17 additions & 0 deletions doc/arkode/guide/source/Introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,23 @@ Users now need to link to ``sundials_core`` in addition to the libraries already
This will be picked up automatically in projects that use the SUNDIALS CMake target. The library ``sundials_generic`` has been superceded by ``sundials_core`` and is no longer available.
This fixes some duplicate symbol errors on Windows when linking to multiple SUNDIALS libraries.

**Breaking change**
The following functions have been removed

.. code-block::
ARKStepSetErrHandlerFn
ARKStepSetErrFile
ERKStepSetErrHandlerFn
ERKStepSetErrFile
MRIStepSetErrHandlerFn
MRIStepSetErrFile
SPRKStepSetErrHandlerFn
SPRKStepSetErrFile
Users of these functions can use the functions :c:func:`SUNContext_PushErrHandler`,
and :c:func:`SUNLogger_SetErrorFilename` instead. For further details see
Sections :numref:`SUNDIALS.Errors` and :numref:`SUNDIALS.Logging`.

Changes in v5.6.2
-----------------
Expand Down
53 changes: 0 additions & 53 deletions doc/arkode/guide/source/Usage/ARKStep_c_interface/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -864,8 +864,6 @@ Return ARKStep parameters to their defaults :c:func:`ARKStepSetDefaults`
Set dense output interpolation type :c:func:`ARKStepSetInterpolantType` ``ARK_INTERP_HERMITE``
Set dense output polynomial degree :c:func:`ARKStepSetInterpolantDegree` 5
Supply a pointer to a diagnostics output file :c:func:`ARKStepSetDiagnostics` ``NULL``
Supply a pointer to an error output file :c:func:`ARKStepSetErrFile` ``stderr``
Supply a custom error handler function :c:func:`ARKStepSetErrHandlerFn` internal fn
Disable time step adaptivity (fixed-step mode) :c:func:`ARKStepSetFixedStep` disabled
Supply an initial step size to attempt :c:func:`ARKStepSetInitStep` estimated
Maximum no. of warnings for :math:`t_n+h = t_n` :c:func:`ARKStepSetMaxHnilWarns` 10
Expand Down Expand Up @@ -1020,57 +1018,6 @@ Set max number of constraint failures :c:func:`ARKStepSetMaxNumConst
Use :c:func:`SUNLogger_SetInfoFilename` instead.
.. c:function:: int ARKStepSetErrFile(void* arkode_mem, FILE* errfp)
Specifies a pointer to the file where all ARKStep warning and error
messages will be written if the default internal error handling
function is used.
**Arguments:**
* *arkode_mem* -- pointer to the ARKStep memory block.
* *errfp* -- pointer to the output file.
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the ARKStep memory is ``NULL``
* *ARK_ILL_INPUT* if an argument has an illegal value
**Notes:**
The default value for *errfp* is ``stderr``.
Passing a ``NULL`` value disables all future error message output
(except for the case wherein the ARKStep memory pointer is
``NULL``). This use of the function is strongly discouraged.
If used, this routine should be called before any other
optional input functions, in order to take effect for subsequent
error messages.
.. c:function:: int ARKStepSetErrHandlerFn(void* arkode_mem, ARKErrHandlerFn ehfun, void* eh_data)
Specifies the optional user-defined function to be used
in handling error messages.
**Arguments:**
* *arkode_mem* -- pointer to the ARKStep memory block.
* *ehfun* -- name of user-supplied error handler function.
* *eh_data* -- pointer to user data passed to *ehfun* every time
it is called.
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the ARKStep memory is ``NULL``
* *ARK_ILL_INPUT* if an argument has an illegal value
**Notes:**
Error messages indicating that the ARKStep solver memory is
``NULL`` will always be directed to ``stderr``.
.. c:function:: int ARKStepSetFixedStep(void* arkode_mem, sunrealtype hfixed)
Disables time step adaptivity within ARKStep, and specifies the
Expand Down
55 changes: 0 additions & 55 deletions doc/arkode/guide/source/Usage/ERKStep_c_interface/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -477,10 +477,6 @@ Optional inputs for ERKStep
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply a pointer to a diagnostics output file | :c:func:`ERKStepSetDiagnostics()` | ``NULL`` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply a pointer to an error output file | :c:func:`ERKStepSetErrFile()` | ``stderr`` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply a custom error handler function | :c:func:`ERKStepSetErrHandlerFn()` | internal fn |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Disable time step adaptivity (fixed-step mode) | :c:func:`ERKStepSetFixedStep()` | disabled |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply an initial step size to attempt | :c:func:`ERKStepSetInitStep()` | estimated |
Expand Down Expand Up @@ -645,57 +641,6 @@ Optional inputs for ERKStep
Use :c:func:`SUNLogger_SetInfoFilename` instead.
.. c:function:: int ERKStepSetErrFile(void* arkode_mem, FILE* errfp)
Specifies a pointer to the file where all ERKStep warning and error
messages will be written if the default internal error handling
function is used.
**Arguments:**
* *arkode_mem* -- pointer to the ERKStep memory block.
* *errfp* -- pointer to the output file.
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the ERKStep memory is ``NULL``
* *ARK_ILL_INPUT* if an argument has an illegal value
**Notes:**
The default value for *errfp* is ``stderr``.
Passing a ``NULL`` value disables all future error message output
(except for the case wherein the ERKStep memory pointer is
``NULL``). This use of the function is strongly discouraged.
If used, this routine should be called before any other
optional input functions, in order to take effect for subsequent
error messages.
.. c:function:: int ERKStepSetErrHandlerFn(void* arkode_mem, ARKErrHandlerFn ehfun, void* eh_data)
Specifies the optional user-defined function to be used
in handling error messages.
**Arguments:**
* *arkode_mem* -- pointer to the ERKStep memory block.
* *ehfun* -- name of user-supplied error handler function.
* *eh_data* -- pointer to user data passed to *ehfun* every time
it is called.
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the ERKStep memory is ``NULL``
* *ARK_ILL_INPUT* if an argument has an illegal value
**Notes:**
Error messages indicating that the ERKStep solver memory is
``NULL`` will always be directed to ``stderr``.
.. c:function:: int ERKStepSetFixedStep(void* arkode_mem, sunrealtype hfixed)
Disabled time step adaptivity within ERKStep, and specifies the
Expand Down
63 changes: 0 additions & 63 deletions doc/arkode/guide/source/Usage/MRIStep_c_interface/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -680,10 +680,6 @@ Optional inputs for MRIStep
+---------------------------------------------------------------+-------------------------------------------+------------------------+
| Supply a pointer to a diagnostics output file | :c:func:`MRIStepSetDiagnostics()` | ``NULL`` |
+---------------------------------------------------------------+-------------------------------------------+------------------------+
| Supply a pointer to an error output file | :c:func:`MRIStepSetErrFile()` | ``stderr`` |
+---------------------------------------------------------------+-------------------------------------------+------------------------+
| Supply a custom error handler function | :c:func:`MRIStepSetErrHandlerFn()` | internal fn |
+---------------------------------------------------------------+-------------------------------------------+------------------------+
| Run with fixed-step sizes | :c:func:`MRIStepSetFixedStep()` | required |
+---------------------------------------------------------------+-------------------------------------------+------------------------+
| Maximum no. of warnings for :math:`t_n+h = t_n` | :c:func:`MRIStepSetMaxHnilWarns()` | 10 |
Expand Down Expand Up @@ -857,65 +853,6 @@ Optional inputs for MRIStep
Use :c:func:`SUNLogger_SetInfoFilename` instead.
.. c:function:: int MRIStepSetErrFile(void* arkode_mem, FILE* errfp)
Specifies a pointer to the file where all MRIStep warning and error
messages will be written if the default internal error handling
function is used.
**Arguments:**
* *arkode_mem* -- pointer to the MRIStep memory block.
* *errfp* -- pointer to the output file.
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the MRIStep memory is ``NULL``
* *ARK_ILL_INPUT* if an argument has an illegal value
**Notes:** The default value for *errfp* is ``stderr``.
Passing a ``NULL`` value disables all future error message output
(except for the case wherein the MRIStep memory pointer is
``NULL``). This use of the function is strongly discouraged.
If used, this routine should be called before any other
optional input functions, in order to take effect for subsequent
error messages.
.. c:function:: int MRIStepSetErrHandlerFn(void* arkode_mem, ARKErrHandlerFn ehfun, void* eh_data)
Specifies the optional user-defined function to be used
in handling error messages.
**Arguments:**
* *arkode_mem* -- pointer to the MRIStep memory block.
* *ehfun* -- name of user-supplied error handler function.
* *eh_data* -- pointer to user data passed to *ehfun* every time
it is called.
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the MRIStep memory is ``NULL``
* *ARK_ILL_INPUT* if an argument has an illegal value
**Notes:** Error messages indicating that the MRIStep solver memory is
``NULL`` will always be directed to ``stderr``.
.. c:function:: int MRIStepSetFixedStep(void* arkode_mem, sunrealtype hs)
Expand Down
49 changes: 0 additions & 49 deletions doc/arkode/guide/source/Usage/SPRKStep_c_interface/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -271,10 +271,6 @@ Optional inputs for SPRKStep
+-----------------------------------------------------+------------------------------------------+------------------------+
| Supply a pointer to a diagnostics output file | :c:func:`SPRKStepSetDiagnostics()` | ``NULL`` |
+-----------------------------------------------------+------------------------------------------+------------------------+
| Supply a pointer to an error output file | :c:func:`SPRKStepSetErrFile()` | ``stderr`` |
+-----------------------------------------------------+------------------------------------------+------------------------+
| Supply a custom error handler function | :c:func:`SPRKStepSetErrHandlerFn()` | internal fn |
+-----------------------------------------------------+------------------------------------------+------------------------+
| Set fixed step size (required user input) | :c:func:`SPRKStepSetFixedStep()` | user defined |
+-----------------------------------------------------+------------------------------------------+------------------------+
| Maximum no. of internal steps before *tout* | :c:func:`SPRKStepSetMaxNumSteps()` | 500 |
Expand Down Expand Up @@ -379,51 +375,6 @@ Optional inputs for SPRKStep
obtained by the integrator are returned at the ends of the time interval.
.. c:function:: int SPRKStepSetErrFile(void* arkode_mem, FILE* errfp)
Specifies a pointer to the file where all SPRKStep warning and error
messages will be written if the default internal error handling
function is used.
The default value for *errfp* is ``stderr``.
Passing a ``NULL`` value disables all future error message output
(except for the case wherein the SPRKStep memory pointer is
``NULL``). This use of the function is strongly discouraged.
:param arkode_mem: pointer to the SPRKStep memory block.
:param errfp: pointer to the output file.
:retval ARK_SUCCESS: if successful
:retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
:retval ARK_ILL_INPUT: if an argument has an illegal value
.. note::
If used, this routine should be called before any other
optional input functions, in order to take effect for subsequent
error messages.
.. c:function:: int SPRKStepSetErrHandlerFn(void* arkode_mem, ARKErrHandlerFn ehfun, void* eh_data)
Specifies the optional user-defined function to be used
in handling error messages.
:param arkode_mem: pointer to the SPRKStep memory block.
:param ehfun: name of user-supplied error handler function.
:param eh_data: pointer to user data passed to *ehfun* every time it is called.
:retval ARK_SUCCESS: if successful
:retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
:retval ARK_ILL_INPUT: if an argument has an illegal value
.. note::
Error messages indicating that the SPRKStep solver memory is
``NULL`` will always be directed to ``stderr``.
.. c:function:: int SPRKStepSetFixedStep(void* arkode_mem, sunrealtype hfixed)
Sets the time step size used within SPRKStep.
Expand Down
40 changes: 0 additions & 40 deletions doc/arkode/guide/source/Usage/User_supplied.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,46 +125,6 @@ ODE system to MRIStep:




.. _ARKODE.Usage.ErrorHandler:

Error message handler function
--------------------------------------

As an alternative to the default behavior of directing error and
warning messages to the file pointed to by `errfp` (see
:c:func:`ARKStepSetErrFile`, :c:func:`ERKStepSetErrFile`, and
:c:func:`MRIStepSetErrFile`), the user may provide a function of type
:c:type:`ARKErrHandlerFn` to process any such messages.



.. c:type:: void (*ARKErrHandlerFn)(int error_code, const char* module, const char* function, char* msg, void* user_data)
This function processes error and warning messages from
ARKODE and its sub-modules.

**Arguments:**
* *error_code* -- the error code.
* *module* -- the name of the ARKODE module reporting the error.
* *function* -- the name of the function in which the error occurred.
* *msg* -- the error message.
* *user_data* -- a pointer to user data, the same as the
*eh_data* parameter that was passed to :c:func:`ARKStepSetErrHandlerFn`,
:c:func:`ERKStepSetErrHandlerFn`, or :c:func:`MRIStepSetErrHandlerFn`.

**Return value:**
An *ARKErrHandlerFn* function has no return value.

**Notes:**
*error_code* is negative for errors and positive
(*ARK_WARNING*) for warnings. If a function that returns a
pointer to memory encounters an error, it sets *error_code* to
0.




.. _ARKODE.Usage.ErrorWeight:

Error weight function
Expand Down
3 changes: 0 additions & 3 deletions include/arkode/arkode.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -153,9 +153,6 @@ typedef int (*ARKEwtFn)(N_Vector y, N_Vector ewt, void* user_data);

typedef int (*ARKRwtFn)(N_Vector y, N_Vector rwt, void* user_data);

typedef void (*ARKErrHandlerFn)(int error_code, const char* module,
const char* function, char* msg, void* user_data);

typedef int (*ARKAdaptFn)(N_Vector y, sunrealtype t, sunrealtype h1,
sunrealtype h2, sunrealtype h3, sunrealtype e1,
sunrealtype e2, sunrealtype e3, int q, int p,
Expand Down
3 changes: 0 additions & 3 deletions include/arkode/arkode_arkstep.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -174,9 +174,6 @@ SUNDIALS_EXPORT int ARKStepSetMaxNumConstrFails(void* arkode_mem, int maxfails);
SUNDIALS_EXPORT int ARKStepSetRootDirection(void* arkode_mem, int* rootdir);
SUNDIALS_EXPORT int ARKStepSetNoInactiveRootWarn(void* arkode_mem);

SUNDIALS_EXPORT int ARKStepSetErrHandlerFn(void* arkode_mem,
ARKErrHandlerFn ehfun, void* eh_data);
SUNDIALS_EXPORT int ARKStepSetErrFile(void* arkode_mem, FILE* errfp);
SUNDIALS_EXPORT int ARKStepSetUserData(void* arkode_mem, void* user_data);

SUNDIALS_EXPORT int ARKStepSetPostprocessStepFn(void* arkode_mem,
Expand Down
3 changes: 0 additions & 3 deletions include/arkode/arkode_erkstep.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,9 +118,6 @@ SUNDIALS_EXPORT int ERKStepSetMaxNumConstrFails(void* arkode_mem, int maxfails);
SUNDIALS_EXPORT int ERKStepSetRootDirection(void* arkode_mem, int* rootdir);
SUNDIALS_EXPORT int ERKStepSetNoInactiveRootWarn(void* arkode_mem);

SUNDIALS_EXPORT int ERKStepSetErrHandlerFn(void* arkode_mem,
ARKErrHandlerFn ehfun, void* eh_data);
SUNDIALS_EXPORT int ERKStepSetErrFile(void* arkode_mem, FILE* errfp);
SUNDIALS_EXPORT int ERKStepSetUserData(void* arkode_mem, void* user_data);

SUNDIALS_EXPORT int ERKStepSetPostprocessStepFn(void* arkode_mem,
Expand Down
Loading

0 comments on commit b5680be

Please sign in to comment.