2.5. Error Checking

New in version 7.0.0.

Until version 7.0.0, error reporting and handling was inconsistent throughout SUNDIALS. Starting with version 7.0.0 all of SUNDIALS (the core, implementations of core modules, and packages) reports error mesages through the SUNLogger API. Furthermore, functions in the SUNDIALS core API (i.e., SUN or N_V functions only) either return a SUNErrCode, or (if they don’t return a SUNErrCode) they internally record an error code (if an error occurs) within the SUNContext for the execution stream. This “last error” is accessible via the SUNContext_GetLastError() or SUNContext_PeekLastError() functions.

typedef int SUNErrCode

Thus, in user code, SUNDIALS core API functions can be checked for errors in one of two ways:

SUNContext sunctx;
SUNErrCode sunerr;
N_Vector v;
int length;
sunrealtype dotprod;

// Every code that uses SUNDIALS must create a SUNContext.
sunctx = SUNContext_Create(...);

// Create a SUNDIALS serial vector.
// Some functions do not return an error code.
// We have to check for errors in these functions using SUNContext_GetLastError.
length = 2;
v = N_VNew_Serial(length, sunctx);
sunerr = SUNContext_GetLastError(sunctx);
if (sunerr) {  /* an error occured, do something */ }

// If the function returns a SUNErrCode, we can check it directly
sunerr = N_VLinearCombination(...);
if (sunerr) {  /* an error occured, do something */ }

// Another function that does not return a SUNErrCode.
dotprod = N_VDotProd(...);
SUNContext_GetLastError(sunctx);
if (sunerr) {
 /* an error occured, do something */
} else {
  print("dotprod = %.2f\n", dotprod);
}

The function SUNGetErrMsg() can be used to get a message describing the error code.

const char *SUNGetErrMsg(SUNErrCode code)

Returns a message describing the error code.

Parameters:

  • code – the error code

Returns:

a message describing the error code.

Note

It is recommended in most cases that users check for an error after calling SUNDIALS functions. However, users concerned with getting the most performance might choose to exclude or limit these checks.

Warning

If a function returns a SUNErrCode then the return value is the only place the error is available i.e., these functions do not store their error code as the “last error” so it is invalid to use SUNContext_GetLastError() to check these functions for errors.

2.5.1. Error Handler Functions

When an error occurs in SUNDIALS, it calls error handler functions that have been pushed onto the error handler stack in last-in first-out order. Specific error handlers can be enabled by pushing them onto the error handler stack with the function SUNContext_PushErrHandler(). They may disabled by calling SUNContext_PopErrHandler() or SUNContext_ClearErrHandlers(). A SUNDIALS error handler function has the type

typedef int (*SUNErrHandlerFn)(int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)

SUNDIALS provides a few different error handlers that can be used, or a custom one defined by the user can be provided (useful for linking SUNDIALS errors to your application’s error handling). The default error handler is SUNLogErrHandlerFn() which logs an error to a specified file or stderr if no file is specified.

The error handlers provided in SUNDIALS are:

void SUNLogErrHandlerFn(int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)

Logs the error that occurred using the SUNLogger from sunctx. This is the default error handler.

Parameters:

  • line – the line number at which the error occured

  • func – the function in which the error occured

  • file – the file in which the error occured

  • msg – the message to log, if this is NULL then the default error message for the error code will be used

  • err_code – the error code for the error that occured

  • err_user_data – the user pointer provided to SUNContext_PushErrHandler()

  • sunctx – pointer to a valid SUNContext object

Returns:

void

void SUNAbortErrHandlerFn(int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)

Logs the error and aborts the program if an error occured.

Parameters:

  • line – the line number at which the error occured

  • func – the function in which the error occured

  • file – the file in which the error occured

  • msg – this parameter is ignored

  • err_code – the error code for the error that occured

  • err_user_data – the user pointer provided to SUNContext_PushErrHandler()

  • sunctx – pointer to a valid SUNContext object

Returns:

void

void SUNMPIAbortErrHandlerFn(int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)

Logs the error and calls MPI_Abort if an error occured.

Parameters:

  • line – the line number at which the error occured

  • func – the function in which the error occured

  • file – the file in which the error occured

  • msg – this parameter is ignored

  • err_code – the error code for the error that occured

  • err_user_data – the user pointer provided to SUNContext_PushErrHandler()

  • sunctx – pointer to a valid SUNContext object

Returns:

void