diff --git a/doc/arkode/guide/source/Introduction.rst b/doc/arkode/guide/source/Introduction.rst index 7f8dcba92c..3d967fdaee 100644 --- a/doc/arkode/guide/source/Introduction.rst +++ b/doc/arkode/guide/source/Introduction.rst @@ -224,10 +224,6 @@ 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** -Users now need to link to ``sundials_core`` in addition to the libraries already linked to. -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. - Changes in v5.6.2 ----------------- diff --git a/doc/arkode/guide/source/Usage/General.rst b/doc/arkode/guide/source/Usage/General.rst index 7bf60f01ed..5dc87b8ede 100644 --- a/doc/arkode/guide/source/Usage/General.rst +++ b/doc/arkode/guide/source/Usage/General.rst @@ -35,11 +35,11 @@ modules, vectors and algebraic solvers, are found in .. code-block:: - /libsundials_nvec*. - /libsundials_sunmat*. - /libsundials_sunlinsol*. - /libsundials_sunnonlinsol*. - /libsundials_sunmem. + /libsundials_nvec*.lib + /libsundials_sunmat*.lib + /libsundials_sunlinsol*.lib + /libsundials_sunnonlinsol*.lib + /libsundials_sunmem*.lib The file extension ``.lib`` is typically ``.so`` for shared libraries and ``.a`` for static libraries. @@ -63,24 +63,34 @@ prototypes, and include the shared ``arkode/arkode.h`` and included, but there are optional ones that can be included as necessary. Information on optional headers is given in the relevant documentation section. +The calling program must also include an :c:type:`N_Vector` implementation header file, +of the form ``nvector/nvector_*.h``. See :numref:`NVectors` for the appropriate name. + If the user includes a non-trivial implicit component to their ODE system in ARKStep, or if the slow time scale for MRIStep should be treated implicitly, then each implicit stage will require a nonlinear solver for the resulting system of algebraic equations -- the default for this is a modified or inexact Newton iteration, depending on the user's choice of linear solver. If choosing to set which nonlinear solver module, or when interacting with a -:numref:`SUNNonlinSol` module directly, the calling program must also include a -:numref:`SUNNonlinSol` header file, of the form ``sunnonlinsol/sunnonlinsol_***.h`` +:c:type:`SUNNonlinearSolver` module directly, the calling program must also include a +:c:type:`SUNNonlinearSolver` header file, of the form ``sunnonlinsol/sunnonlinsol_***.h`` where ``***`` is the name of the nonlinear solver module (see :numref:`SUNNonlinSol` for more information). + If using a nonlinear solver that requires the solution of a linear system of the form :math:`\mathcal{A}x=b` (e.g., the default Newton iteration), then a linear solver module header file will also be required. Similarly, if the ODE system in ARKStep involves a non-identity mass matrix :math:`M \ne I`, then each time -step will require a linear solver for systems of the form :math:`Mx=b`. -In this case it will be necessary to include the header file for a SUNDIALS linear -solver, which is of the form ``sunlinsol/sunlinsol_***.h``. +step will require a linear solver for systems of the form :math:`Mx=b`. In this +case it will be necessary to include the header file for a +:c:type:`SUNLinearSolver` solver, which is of the form +``sunlinsol/sunlinsol_***.h`` (see :numref:`SUNLinSol` for more information). + +If the linear solver is matrix-based, the linear solver header will also include a +header file of the from ``sunmatrix/sunmatrix_*.h`` where ``*`` is the name of the +matrix implementation compatible with the linear solver (see :numref:`SUNMatrix` for +more information). Other headers may be needed, according to the choice of preconditioner, etc. For example, if preconditioning for an iterative linear solver were performed diff --git a/doc/cvode/guide/source/Usage/index.rst b/doc/cvode/guide/source/Usage/index.rst index 31a0901ac2..4fbf898baf 100644 --- a/doc/cvode/guide/source/Usage/index.rst +++ b/doc/cvode/guide/source/Usage/index.rst @@ -70,11 +70,11 @@ modules, vectors and algebraic solvers, are found in .. code-block:: - /libsundials_nvec*. - /libsundials_sunmat*. - /libsundials_sunlinsol*. - /libsundials_sunnonlinsol*. - /libsundials_sunmem. + /libsundials_nvec*.lib + /libsundials_sunmat*.lib + /libsundials_sunlinsol*.lib + /libsundials_sunnonlinsol*.lib + /libsundials_sunmem*.lib The file extension ``.lib`` is typically ``.so`` for shared libraries and ``.a`` for static libraries. @@ -88,23 +88,32 @@ the header file for CVODE in addition to the SUNDIALS core header file: #include // Provides core SUNDIALS types #include // CVODE provides linear multistep methods -The calling program must also include an ``N_Vector`` implementation header file, of the form +The calling program must also include an :c:type:`N_Vector` implementation header file, of the form ``nvector/nvector_*.h``. See :numref:`NVectors` for the appropriate name. -If using a non-default nonlinear solver module, or when interacting with a ``SUNNonlinearSolver`` -module directly, the calling program must also include a ``SUNNonlinearSolver`` implementation -header file, of the form ``sunnonlinsol/sunnonlinsol_*.h`` where is the name of the nonlinear solver -module (see :numref:`SUNNonlinSol` for more information). This file in turn includes the header file -which defines the abstract data type. +If using a non-default nonlinear solver module, or when interacting with a +:c:type:`SUNNonlinearSolver` module directly, the calling program must +also include a :c:type:`SUNNonlinearSolver` implementation header file, +of the form ``sunnonlinsol/sunnonlinsol_*.h`` where ``*`` is the name of +the nonlinear solver module (see :numref:`SUNNonlinSol` for more +information). If using a nonlinear solver that requires the solution of a linear system of the form :eq:`CVODE_Newton` (e.g., the default Newton iteration), then a linear solver module header file -will be required. +will be required. In this case it will be necessary to include the header file for a +:c:type:`SUNLinearSolver` solver, which is of the form ``sunlinsol/sunlinsol_***.h`` +(see :numref:`SUNLinSol` for more information). + +If the linear solver is matrix-based, the linear solver header will also include a +header file of the from ``sunmatrix/sunmatrix_*.h`` where ``*`` is the name of the +matrix implementation compatible with the linear solver (see :numref:`SUNMatrix` for +more information). Other headers may be needed, according to the choice of preconditioner, etc. For example, in the example (see :cite:p:`cvode_ex`), preconditioning is done with a block-diagonal matrix. For this, -even though the ``SUNLINSOL_SPGMR`` linear solver is used, the header is included for access to the -underlying generic dense matrix arithmetic routines. +even though the ``SUNLINSOL_SPGMR`` linear solver is used, the header +``sundials dense.h`` is included for access to the underlying generic dense matrix +arithmetic routines. .. _CVODE.Usage.CC.skeleton_sim: diff --git a/doc/cvodes/guide/source/Usage/SIM.rst b/doc/cvodes/guide/source/Usage/SIM.rst index 6d0222fa20..9f9f24ea85 100644 --- a/doc/cvodes/guide/source/Usage/SIM.rst +++ b/doc/cvodes/guide/source/Usage/SIM.rst @@ -69,11 +69,11 @@ modules, vectors and algebraic solvers, are found in .. code-block:: - /libsundials_nvec*. - /libsundials_sunmat*. - /libsundials_sunlinsol*. - /libsundials_sunnonlinsol*. - /libsundials_sunmem. + /libsundials_nvec*.lib + /libsundials_sunmat*.lib + /libsundials_sunlinsol*.lib + /libsundials_sunnonlinsol*.lib + /libsundials_sunmem*.lib The file extension ``.lib`` is typically ``.so`` for shared libraries and ``.a`` for static libraries. @@ -87,24 +87,32 @@ the header file for CVODES in addition to the SUNDIALS core header file: #include // Provides core SUNDIALS types #include // CVODES provides linear multistep methods with sensitivity analysis -The calling program must also include an ``N_Vector`` implementation header file, of the form +The calling program must also include an :c:type`N_Vector` implementation header file, of the form ``nvector/nvector_*.h``. See :numref:`NVectors` for the appropriate name. -If using a non-default nonlinear solver module, or when interacting with a ``SUNNonlinearSolver`` -module directly, the calling program must also include a ``SUNNonlinearSolver`` implementation -header file, of the form ``sunnonlinsol/sunnonlinsol_*.h`` where is the name of the nonlinear solver -module (see :numref:`SUNNonlinSol` for more information). This file in turn includes the header file -which defines the abstract data type. +If using a non-default nonlinear solver module, or when interacting with a +:c:type:`SUNNonlinearSolver` module directly, the calling program must +also include a :c:type:`SUNNonlinearSolver` implementation header file, +of the form ``sunnonlinsol/sunnonlinsol_*.h`` where ``*`` is the name of +the nonlinear solver module (see :numref:`SUNNonlinSol` for more +information). If using a nonlinear solver that requires the solution of a linear system of the form :eq:`CVODES_Newton` (e.g., the default Newton iteration), then a linear solver module header file -will be required. +will be required. In this case it will be necessary to include the header file for a +:c:type:`SUNLinearSolver` solver, which is of the form ``sunlinsol/sunlinsol_***.h`` +(see :numref:`SUNLinSol` for more information). + +If the linear solver is matrix-based, the linear solver header will also include a +header file of the from ``sunmatrix/sunmatrix_*.h`` where ``*`` is the name of the +matrix implementation compatible with the linear solver (see :numref:`SUNMatrix` for +more information). Other headers may be needed, according to the choice of preconditioner, etc. For example, in the example (see :cite:p:`cvodes_ex`), preconditioning is done with a block-diagonal matrix. For this, -even though the ``SUNLINSOL_SPGMR`` linear solver is used, the header is included for access to the -underlying generic dense matrix arithmetic routines. - +even though the ``SUNLINSOL_SPGMR`` linear solver is used, the header +``sundials dense.h`` is included for access to the underlying generic dense matrix +arithmetic routines. .. warning:: diff --git a/doc/ida/guide/source/Usage/index.rst b/doc/ida/guide/source/Usage/index.rst index 3d04fea608..7e5698acd0 100644 --- a/doc/ida/guide/source/Usage/index.rst +++ b/doc/ida/guide/source/Usage/index.rst @@ -63,11 +63,11 @@ modules, vectors and algebraic solvers, are found in .. code-block:: - /libsundials_nvec*. - /libsundials_sunmat*. - /libsundials_sunlinsol*. - /libsundials_sunnonlinsol*. - /libsundials_sunmem. + /libsundials_nvec*.lib + /libsundials_sunmat*.lib + /libsundials_sunlinsol*.lib + /libsundials_sunnonlinsol*.lib + /libsundials_sunmem*.lib The file extension ``.lib`` is typically ``.so`` for shared libraries and ``.a`` for static libraries. @@ -81,27 +81,25 @@ the header file for IDA in addition to the SUNDIALS core header file: #include // Provides core SUNDIALS types #include // IDA provides methods for DAEs -The calling program must also include an ``N_Vector`` implementation header file, of the form +The calling program must also include an :c:type:`N_Vector` implementation header file, of the form ``nvector/nvector_*.h``. See :numref:`NVectors` for the appropriate name. -The calling program must also include an ``N_Vector`` implementation -header file, of the form ``nvector/nvector_*.h`` (see Chapter :numref:`NVectors` -for more information). If using a non-default nonlinear solver object, or when interacting with a -``SUNNonlinearSolver`` object directly, the calling program must also include a -``SUNNonlinearSolver`` implementation header file, of the form +:c:type:`SUNNonlinearSolver` object directly, the calling program must also include a +:c:type:`SUNNonlinearSolver` implementation header file, of the form ``sunnonlinsol/sunnonlinsol_*.h`` where ``*`` is the name of the nonlinear solver (see Chapter :numref:`SUNNonlinSol` for more information). If using a nonlinear solver that requires the solution of a linear system of the form :eq:`IDA_DAE_nls` (e.g., the default Newton iteration), the calling program -must also include a ``SUNLinearSolver`` implementation header file, of the from +must also include a :c:type:`SUNLinearSolver` implementation header file, of the from ``sunlinsol/sunlinsol_*.h`` where ``*`` is the name of the linear solver (see Chapter :numref:`SUNLinSol` for more information). If the linear solver is matrix-based, the linear solver header will also include a header file of the from ``sunmatrix/sunmatrix_*.h`` where ``*`` is the name of -the matrix implementation compatible with the linear solver. +the matrix implementation compatible with the linear solver (see Chapter +:numref:`SUNMatrix` for more information). Other headers may be needed, according to the choice of preconditioner, etc. For example, in the example ``idaFoodWeb_kry_p`` (see :cite:p:`ida_ex`), diff --git a/doc/idas/guide/source/Usage/SIM.rst b/doc/idas/guide/source/Usage/SIM.rst index 7ce42bad1c..44d06147ac 100644 --- a/doc/idas/guide/source/Usage/SIM.rst +++ b/doc/idas/guide/source/Usage/SIM.rst @@ -55,18 +55,18 @@ where ``instdir`` is the directory where SUNDIALS was installed. Regardless of where the user's application program resides, its associated compilation and load commands must make reference to the appropriate locations for the library and header files required by -IDAS. IDAS symbols are found in ``libdir/libsundials_ida.lib``. +IDAS. IDAS symbols are found in ``libdir/libsundials_idas.lib``. Thus, in addition to linking to ``libdir/libsundials_core.lib``, IDAS users need to link to the IDAS library. Symbols for additional SUNDIALS modules, vectors and algebraic solvers, are found in .. code-block:: - /libsundials_nvec*. - /libsundials_sunmat*. - /libsundials_sunlinsol*. - /libsundials_sunnonlinsol*. - /libsundials_sunmem. + /libsundials_nvec*.lib + /libsundials_sunmat*.lib + /libsundials_sunlinsol*.lib + /libsundials_sunnonlinsol*.lib + /libsundials_sunmem*.lib The file extension ``.lib`` is typically ``.so`` for shared libraries and ``.a`` for static libraries. @@ -80,27 +80,25 @@ the header file for IDAS in addition to the SUNDIALS core header file: #include // Provides core SUNDIALS types #include // IDAS provides methods for DAEs with sensitivity analysis -The calling program must also include an ``N_Vector`` implementation header file, of the form +The calling program must also include an :c:type:`N_Vector` implementation header file, of the form ``nvector/nvector_*.h``. See :numref:`NVectors` for the appropriate name. -The calling program must also include an ``N_Vector`` implementation -header file, of the form ``nvector/nvector_*.h`` (see Chapter :numref:`NVectors` -for more information). If using a non-default nonlinear solver object, or when interacting with a -``SUNNonlinearSolver`` object directly, the calling program must also include a -``SUNNonlinearSolver`` implementation header file, of the form +:c:type:`SUNNonlinearSolver` object directly, the calling program must also include a +:c:type:`SUNNonlinearSolver` implementation header file, of the form ``sunnonlinsol/sunnonlinsol_*.h`` where ``*`` is the name of the nonlinear solver (see Chapter :numref:`SUNNonlinSol` for more information). If using a nonlinear solver that requires the solution of a linear system of the form :eq:`IDAS_DAE_nls` (e.g., the default Newton iteration), the calling program -must also include a ``SUNLinearSolver`` implementation header file, of the from +must also include a :c:type:`SUNLinearSolver` implementation header file, of the from ``sunlinsol/sunlinsol_*.h`` where ``*`` is the name of the linear solver (see Chapter :numref:`SUNLinSol` for more information). If the linear solver is matrix-based, the linear solver header will also include a header file of the from ``sunmatrix/sunmatrix_*.h`` where ``*`` is the name of -the matrix implementation compatible with the linear solver. +the matrix implementation compatible with the linear solver. (see Chapter +:numref:`SUNMatrix` for more information). Other headers may be needed, according to the choice of preconditioner, etc. For example, in the example ``idasFoodWeb_kry_p`` (see :cite:p:`ida_ex`), diff --git a/doc/kinsol/guide/source/Usage/index.rst b/doc/kinsol/guide/source/Usage/index.rst index c54b4d056b..d32ccf69d8 100644 --- a/doc/kinsol/guide/source/Usage/index.rst +++ b/doc/kinsol/guide/source/Usage/index.rst @@ -57,18 +57,18 @@ where ``instdir`` is the directory where SUNDIALS was installed. Regardless of where the user's application program resides, its associated compilation and load commands must make reference to the appropriate locations for the library and header files required by -KINSOL. KINSOL symbols are found in ``libdir/libsundials_ida.lib``. +KINSOL. KINSOL symbols are found in ``libdir/libsundials_kinsol.lib``. Thus, in addition to linking to ``libdir/libsundials_core.lib``, KINSOL users need to link to the KINSOL library. Symbols for additional SUNDIALS modules, vectors and algebraic solvers, are found in .. code-block:: - /libsundials_nvec*. - /libsundials_sunmat*. - /libsundials_sunlinsol*. - /libsundials_sunnonlinsol*. - /libsundials_sunmem. + /libsundials_nvec*.lib + /libsundials_sunmat*.lib + /libsundials_sunlinsol*.lib + /libsundials_sunnonlinsol*.lib + /libsundials_sunmem*.lib The file extension ``.lib`` is typically ``.so`` for shared libraries and ``.a`` for static libraries. @@ -82,20 +82,19 @@ the header file for KINSOL in addition to the SUNDIALS core header file: #include // Provides core SUNDIALS types #include // KINSOL provides methods for solving nonlinear systems -The calling program must also include an ``N_Vector`` implementation header file, of the form +The calling program must also include an :c:type:`N_Vector` implementation header file, of the form ``nvector/nvector_*.h``. See :numref:`NVectors` for the appropriate name. -The calling program must also include an ``N_Vector`` implementation -header file, of the form ``nvector/nvector_*.h`` (see Chapter :numref:`NVectors` -for more information). If using a Newton or Picard nonlinear solver that requires the solution of a -linear system, then a linear solver module header file will be required. If the -linear solver is matrix-based, the linear solver header will also include a -header file of the from ``sunmatrix/sunmatrix_*.h`` where ``*`` is the name of -the matrix implementation compatible with the linear solver. The matrix header -file provides access to the relevant matrix functions/macros and in turn -includes the header file ``sundials_matrix.h`` which defines the abstract matrix -data type. +linear system, the calling program must also include a ``SUNLinearSolver`` +implementation header file, of the from ``sunlinsol/sunlinsol_*.h`` where ``*`` +is the name of the linear solver (see Chapter :numref:`SUNLinSol` for more +information). + +If the linear solver is matrix-based, the linear solver header will also include +a header file of the from ``sunmatrix/sunmatrix_*.h`` where ``*`` is the name of +the matrix implementation compatible with the linear solver. (see Chapter +:numref:`SUNMatrix` for more information). Other headers may be needed, according to the choice of preconditioner, etc. For example, in the example ``kinFoodWeb_kry_p`` (see :cite:p:`kinsol_ex`), diff --git a/doc/shared/sundials/Errors.rst b/doc/shared/sundials/Errors.rst index 572a76d39e..b993146365 100644 --- a/doc/shared/sundials/Errors.rst +++ b/doc/shared/sundials/Errors.rst @@ -24,7 +24,7 @@ functions. The error code type :c:type:`SUNErrCode` is just a typedef to an ``in Errors are always negative, while success is defined with the ``SUN_SUCCESS`` code and has the value ``0``. To see all of the possible error codes, refer to the ``sundials/sundials_errors.h`` header file -(`here _`). +(`here `_). Functions in the SUNDIALS core API (i.e., ``SUN`` or ``N_V`` functions only) either return a :c:type:`SUNErrCode`, or (if they don't return a :c:type:`SUNErrCode`) they internally record an @@ -67,6 +67,17 @@ Thus, in user code, SUNDIALS core functions can be checked for errors in one of } +The function :c:func:`SUNGetErrMsg` can be used to get a message describing the error code. + +.. c:function:: const char* SUNGetErrMsg(SUNErrCode code) + + Returns a message describing the error code. + + :param code: the error code + + :return: a message describing the error code. + + .. note:: It is recommended in most cases that users check for an error after calling SUNDIALS functions. @@ -75,9 +86,9 @@ Thus, in user code, SUNDIALS core functions can be checked for errors in one of .. warning:: - If a function returns a :c:type:`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 - :c:func:`SUNContext_GetLastError` to check these functions for errors. + If a function returns a :c:type:`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 + :c:func:`SUNContext_GetLastError` to check these functions for errors. .. _SUNDIALS.Errors.Handlers: @@ -103,7 +114,7 @@ The error handlers provided in SUNDIALS are: const char* msg, SUNErrCode err_code, \ void* err_user_data, SUNContext sunctx) - Logs the error that occurred using the :c:type:`SUNLogger` for ``sunctx``. + Logs the error that occurred using the :c:type:`SUNLogger` from ``sunctx``. This is the default error handler. :param line: the line number at which the error occured @@ -125,7 +136,7 @@ The error handlers provided in SUNDIALS are: :param line: the line number at which the error occured :param func: the function in which the error occured :param file: the file in which the error occured - :param msg: the message to log, if this is ``NULL`` then the default error message for the error code will be used + :param msg: this parameter is ignored :param err_code: the error code for the error that occured :param err_user_data: the user pointer provided to :c:func:`SUNContext_PushErrHandler` :param sunctx: pointer to a valid :c:type:`SUNContext` object @@ -160,7 +171,7 @@ The error handlers provided in SUNDIALS are: :param line: the line number at which the error occured :param func: the function in which the error occured :param file: the file in which the error occured - :param msg: the message to log, if this is ``NULL`` then the default error message for the error code will be used + :param msg: this parameter is ignored :param err_code: the error code for the error that occured :param err_user_data: the user pointer provided to :c:func:`SUNContext_PushErrHandler` :param sunctx: pointer to a valid :c:type:`SUNContext` object diff --git a/doc/shared/sundials/Fortran.rst b/doc/shared/sundials/Fortran.rst index 3c838bc964..b76965cd2f 100644 --- a/doc/shared/sundials/Fortran.rst +++ b/doc/shared/sundials/Fortran.rst @@ -178,6 +178,8 @@ equivalencies with the parameter direction in mind. +-------------------------+-------------------------------+-------------------------------------------+ | **C Type** | **Parameter Direction** | **Fortran 2003 type** | +=========================+===============================+===========================================+ + |``SUNComm`` | in, inout, out, return | ``integer(c_int)`` | + +-------------------------+-------------------------------+-------------------------------------------+ |``SUNErrCode`` | in, inout, out, return | ``integer(c_int)`` | +-------------------------+-------------------------------+-------------------------------------------+ |``double`` | in, inout, out, return | ``real(c_double)`` | diff --git a/doc/shared/sundials/SUNContext.rst b/doc/shared/sundials/SUNContext.rst index bed5064799..c7dc31148c 100644 --- a/doc/shared/sundials/SUNContext.rst +++ b/doc/shared/sundials/SUNContext.rst @@ -117,7 +117,7 @@ The :c:type:`SUNContext` API further consists of the following functions: :return: :c:type:`SUNErrCode` indicating success or failure -.. c:function:: SUNErrCode SUNContext_ClearErrHandler(SUNContext sunctx) +.. c:function:: SUNErrCode SUNContext_ClearErrHandlers(SUNContext sunctx) Clears the entire error handler stack. After doing this it is important to push an error handler onto the stack with :c:type:`SUNContext_PushErrHandler` otherwise errors will be ignored. @@ -159,7 +159,7 @@ The :c:type:`SUNContext` API further consists of the following functions: :param sunctx: a valid :c:type:`SUNContext` object. :param logger: a :c:type:`SUNLogger` object to associate with this - context; this is ignored if profiling is not enabled. + context; this is ignored if logging is not enabled. :return: :c:type:`SUNErrCode` indicating success or failure @@ -171,7 +171,7 @@ The :c:type:`SUNContext` API further consists of the following functions: Gets the :c:type:`SUNLogger` object associated with the :c:type:`SUNContext` object. :param sunctx: a valid :c:type:`SUNContext` object. - :param logger: [in,out] a pointer to the :c:type:`SUNLogger` object associated with this context; will be ``NULL`` if profiling is not enabled. + :param logger: [in,out] a pointer to the :c:type:`SUNLogger` object associated with this context; will be ``NULL`` if logging is not enabled. :return: :c:type:`SUNErrCode` indicating success or failure diff --git a/doc/superbuild/source/developers/style_guide/SourceCode.rst b/doc/superbuild/source/developers/style_guide/SourceCode.rst index 6add8174d5..8025bac982 100644 --- a/doc/superbuild/source/developers/style_guide/SourceCode.rst +++ b/doc/superbuild/source/developers/style_guide/SourceCode.rst @@ -263,7 +263,7 @@ Coding Conventions and Rules realtype* zd=NULL; realtype* xd=NULL; - SUNFunctionBegin(X[0]->sunctx); // Incorrect + SUNFunctionBegin(X[0]->sunctx); // Incorrect, SUNFunctionBegin should occur as early as possible /* invalid number of vectors */ SUNAssert(nvec >= 1, SUN_ERR_ARG_OUTOFRANGE); @@ -283,7 +283,7 @@ Coding Conventions and Rules cv_mem = (CVodeMem) cvode_mem; - SUNFunctionBegin(cv_mem->sunctx); // Correct + SUNFunctionBegin(cv_mem->sunctx); // Correct - this is as early as possible to call SUNFunctionBegin SUNFunctionBegin(ele->sunctx); // Incorrect - cvode_mem is first in the function parameter list // ... diff --git a/include/sundials/priv/sundials_errors_impl.h b/include/sundials/priv/sundials_errors_impl.h index 42d6bb9e34..898d33624c 100644 --- a/include/sundials/priv/sundials_errors_impl.h +++ b/include/sundials/priv/sundials_errors_impl.h @@ -1,6 +1,6 @@ /* ----------------------------------------------------------------- * SUNDIALS Copyright Start - * Copyright (c) 2002-2022, Lawrence Livermore National Security + * Copyright (c) 2002-2023, Lawrence Livermore National Security * and Southern Methodist University. * All rights reserved. * @@ -21,6 +21,7 @@ #define _SUNDIALS_ERRORS_IMPL_H #include +#include "sundials/sundials_export.h" /* ---------------------------------------------------------------------------- * SUNErrHandler_ definition. @@ -43,6 +44,7 @@ struct SUNErrHandler_ :return: A SUNErrCode indicating success or failure */ +SUNDIALS_EXPORT SUNErrCode SUNErrHandler_Create(SUNErrHandlerFn eh_fn, void* eh_data, SUNErrHandler* eh_out); @@ -54,30 +56,8 @@ SUNErrCode SUNErrHandler_Create(SUNErrHandlerFn eh_fn, void* eh_data, :return: void */ -void SUNErrHandler_Destroy(SUNErrHandler eh); - -/* - This function calls the error handlers registered with the SUNContext. - - :param line: the line number of the error - :param func: the function in which the error occurred - :param file: the file in which the error occurred - :param code: the SUNErrCode for the error - :param sunctx: a valid SUNContext object - - :return: void -*/ -static inline void SUNHandleErr(int line, const char* func, const char* file, - SUNErrCode code, SUNContext sunctx) -{ - sunctx->last_err = code; - SUNErrHandler eh = sunctx->err_handler; - while (eh != NULL) - { - eh->call(line, func, file, NULL, code, eh->data, sunctx); - eh = eh->previous; - } -} +SUNDIALS_EXPORT +void SUNErrHandler_Destroy(SUNErrHandler* eh); /* This function calls the error handlers registered with the SUNContext @@ -92,6 +72,7 @@ static inline void SUNHandleErr(int line, const char* func, const char* file, :return: void */ +SUNDIALS_EXPORT static inline void SUNHandleErrWithMsg(int line, const char* func, const char* file, const char* msg, SUNErrCode code, SUNContext sunctx) @@ -119,6 +100,7 @@ static inline void SUNHandleErrWithMsg(int line, const char* func, :return: void */ +SUNDIALS_EXPORT static inline void SUNHandleErrWithFmtMsg(int line, const char* func, const char* file, const char* msgfmt, SUNErrCode code, SUNContext sunctx, ...) diff --git a/include/sundials/priv/sundials_mpi_errors_impl.h b/include/sundials/priv/sundials_mpi_errors_impl.h index dc5197f77a..c063bdeffb 100644 --- a/include/sundials/priv/sundials_mpi_errors_impl.h +++ b/include/sundials/priv/sundials_mpi_errors_impl.h @@ -1,6 +1,6 @@ /* ----------------------------------------------------------------- * SUNDIALS Copyright Start - * Copyright (c) 2002-2022, Lawrence Livermore National Security + * Copyright (c) 2002-2023, Lawrence Livermore National Security * and Southern Methodist University. * All rights reserved. * diff --git a/include/sundials/sundials_errors.h b/include/sundials/sundials_errors.h index 506e8d2ab1..62fd4942d1 100644 --- a/include/sundials/sundials_errors.h +++ b/include/sundials/sundials_errors.h @@ -107,7 +107,7 @@ void SUNAssertErrHandlerFn(int line, const char* func, const char* file, /* Turn error code into error message */ SUNDIALS_EXPORT -const char* SUNGetErrMsg(SUNErrCode code, SUNContext sunctx); +const char* SUNGetErrMsg(SUNErrCode code); #ifdef __cplusplus /* wrapper to enable C++ usage */ } /* extern "C" */ diff --git a/include/sundials/sundials_mpi_errors.h b/include/sundials/sundials_mpi_errors.h index 5a37910d97..8942d1c722 100644 --- a/include/sundials/sundials_mpi_errors.h +++ b/include/sundials/sundials_mpi_errors.h @@ -1,6 +1,6 @@ /* ----------------------------------------------------------------- * SUNDIALS Copyright Start - * Copyright (c) 2002-2022, Lawrence Livermore National Security + * Copyright (c) 2002-2023, Lawrence Livermore National Security * and Southern Methodist University. * All rights reserved. * diff --git a/include/sundials/sundials_nonlinearsolver.h b/include/sundials/sundials_nonlinearsolver.h index 198e770637..b30854f45d 100644 --- a/include/sundials/sundials_nonlinearsolver.h +++ b/include/sundials/sundials_nonlinearsolver.h @@ -99,8 +99,8 @@ struct _generic_SUNNonlinearSolver_Ops { SUNNonlinearSolver_Type (*gettype)(SUNNonlinearSolver); SUNErrCode (*initialize)(SUNNonlinearSolver); - SUNErrCode (*setup)(SUNNonlinearSolver, N_Vector, void*); - SUNErrCode (*solve)(SUNNonlinearSolver, N_Vector, N_Vector, N_Vector, sunrealtype, sunbooleantype, void*); + int (*setup)(SUNNonlinearSolver, N_Vector, void*); + int (*solve)(SUNNonlinearSolver, N_Vector, N_Vector, N_Vector, sunrealtype, sunbooleantype, void*); SUNErrCode (*free)(SUNNonlinearSolver); SUNErrCode (*setsysfn)(SUNNonlinearSolver, SUNNonlinSolSysFn); SUNErrCode (*setlsetupfn)(SUNNonlinearSolver, SUNNonlinSolLSetupFn); diff --git a/src/sundials/CMakeLists.txt b/src/sundials/CMakeLists.txt index 243cc0d16c..527ffb0fc6 100644 --- a/src/sundials/CMakeLists.txt +++ b/src/sundials/CMakeLists.txt @@ -153,6 +153,12 @@ install(FILES ${SUNDIALS_SOURCE_DIR}/include/sundials/priv/sundials_errors_impl.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/sundials/priv") +if(ENABLE_MPI) + install(FILES + ${SUNDIALS_SOURCE_DIR}/include/sundials/priv/sundials_mpi_errors_impl.h + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/sundials/priv") +endif() + # SUNDIALS_EXPORT macro include(GenerateExportHeader) generate_export_header( diff --git a/src/sundials/fmod/fsundials_errors_mod.c b/src/sundials/fmod/fsundials_errors_mod.c index 6d23d4c883..765f1de0ec 100644 --- a/src/sundials/fmod/fsundials_errors_mod.c +++ b/src/sundials/fmod/fsundials_errors_mod.c @@ -293,15 +293,13 @@ SWIGEXPORT void _wrap_FSUNAssertErrHandlerFn(int const *farg1, SwigArrayWrapper } -SWIGEXPORT SwigArrayWrapper _wrap_FSUNGetErrMsg(int const *farg1, void *farg2) { +SWIGEXPORT SwigArrayWrapper _wrap_FSUNGetErrMsg(int const *farg1) { SwigArrayWrapper fresult ; SUNErrCode arg1 ; - SUNContext arg2 = (SUNContext) 0 ; char *result = 0 ; arg1 = (SUNErrCode)(*farg1); - arg2 = (SUNContext)(farg2); - result = (char *)SUNGetErrMsg(arg1,arg2); + result = (char *)SUNGetErrMsg(arg1); fresult.size = strlen((const char*)(result)); fresult.data = (char *)(result); return fresult; diff --git a/src/sundials/fmod/fsundials_errors_mod.f90 b/src/sundials/fmod/fsundials_errors_mod.f90 index e07905b9ae..b4d36c2819 100644 --- a/src/sundials/fmod/fsundials_errors_mod.f90 +++ b/src/sundials/fmod/fsundials_errors_mod.f90 @@ -112,13 +112,12 @@ subroutine SWIG_free(cptr) & use, intrinsic :: ISO_C_BINDING type(C_PTR), value :: cptr end subroutine -function swigc_FSUNGetErrMsg(farg1, farg2) & +function swigc_FSUNGetErrMsg(farg1) & bind(C, name="_wrap_FSUNGetErrMsg") & result(fresult) use, intrinsic :: ISO_C_BINDING import :: swigarraywrapper integer(C_INT), intent(in) :: farg1 -type(C_PTR), value :: farg2 type(SwigArrayWrapper) :: fresult end function @@ -249,19 +248,16 @@ subroutine SWIG_chararray_to_string(wrap, string) end do end subroutine -function FSUNGetErrMsg(code, sunctx) & +function FSUNGetErrMsg(code) & result(swig_result) use, intrinsic :: ISO_C_BINDING character(kind=C_CHAR, len=:), allocatable :: swig_result integer(C_INT), intent(in) :: code -type(C_PTR) :: sunctx type(SwigArrayWrapper) :: fresult integer(C_INT) :: farg1 -type(C_PTR) :: farg2 farg1 = code -farg2 = sunctx -fresult = swigc_FSUNGetErrMsg(farg1, farg2) +fresult = swigc_FSUNGetErrMsg(farg1) call SWIG_chararray_to_string(fresult, swig_result) if (.false.) call SWIG_free(fresult%data) end function diff --git a/src/sundials/sundials_adiak_metadata.h b/src/sundials/sundials_adiak_metadata.h index bf3efdc545..f506a64f2a 100644 --- a/src/sundials/sundials_adiak_metadata.h +++ b/src/sundials/sundials_adiak_metadata.h @@ -1,4 +1,3 @@ - /* ----------------------------------------------------------------- * Programmer(s): Yu Pan and Cody Balos @ LLNL * ----------------------------------------------------------------- diff --git a/src/sundials/sundials_context.c b/src/sundials/sundials_context.c index c8896db4ff..0e5a864ab0 100644 --- a/src/sundials/sundials_context.c +++ b/src/sundials/sundials_context.c @@ -123,7 +123,7 @@ SUNErrCode SUNContext_PeekLastError(SUNContext sunctx) SUNErrCode SUNContext_PushErrHandler(SUNContext sunctx, SUNErrHandlerFn err_fn, void* err_user_data) { - if (!sunctx) { return SUN_ERR_SUNCTX_CORRUPT; } + if (!sunctx || !err_fn) { return SUN_ERR_SUNCTX_CORRUPT; } SUNFunctionBegin(sunctx); SUNErrHandler new_err_handler = NULL; @@ -147,7 +147,7 @@ SUNErrCode SUNContext_PopErrHandler(SUNContext sunctx) } else { sunctx->err_handler = NULL; } - SUNErrHandler_Destroy(eh); + SUNErrHandler_Destroy(&eh); } return SUN_SUCCESS; } @@ -235,9 +235,8 @@ SUNErrCode SUNContext_SetLogger(SUNContext sunctx, SUNLogger logger) SUNErrCode SUNContext_Free(SUNContext* sunctx) { -#if defined(SUNDIALS_BUILD_WITH_PROFILING) && !defined(SUNDIALS_CALIPER_ENABLED) - FILE* fp = NULL; - char* sunprofiler_print_env = NULL; +#ifdef SUNDIALS_ADIAK_ENABLED + adiak_fini(); #endif if (!sunctx || !(*sunctx)) { @@ -246,7 +245,8 @@ SUNErrCode SUNContext_Free(SUNContext* sunctx) #if defined(SUNDIALS_BUILD_WITH_PROFILING) && !defined(SUNDIALS_CALIPER_ENABLED) /* Find out where we are printing to */ - sunprofiler_print_env = getenv("SUNPROFILER_PRINT"); + FILE* fp = NULL; + char* sunprofiler_print_env = getenv("SUNPROFILER_PRINT"); fp = NULL; if (sunprofiler_print_env) { if (!strcmp(sunprofiler_print_env, "0")) fp = NULL; @@ -266,16 +266,12 @@ SUNErrCode SUNContext_Free(SUNContext* sunctx) } #endif -#ifdef SUNDIALS_ADIAK_ENABLED - adiak_fini(); -#endif - if ((*sunctx)->logger && (*sunctx)->own_logger) { SUNLogger_Destroy(&(*sunctx)->logger); } - SUNErrHandler_Destroy((*sunctx)->err_handler); + SUNErrHandler_Destroy(&(*sunctx)->err_handler); free(*sunctx); *sunctx = NULL; diff --git a/src/sundials/sundials_errors.c b/src/sundials/sundials_errors.c index f300bb7ecf..e9cb30257c 100644 --- a/src/sundials/sundials_errors.c +++ b/src/sundials/sundials_errors.c @@ -1,6 +1,6 @@ /* ----------------------------------------------------------------- * SUNDIALS Copyright Start - * Copyright (c) 2002-2022, Lawrence Livermore National Security + * Copyright (c) 2002-2023, Lawrence Livermore National Security * and Southern Methodist University. * All rights reserved. * @@ -41,12 +41,14 @@ SUNErrCode SUNErrHandler_Create(SUNErrHandlerFn eh_fn, void* eh_data, return SUN_SUCCESS; } -void SUNErrHandler_Destroy(SUNErrHandler eh) +void SUNErrHandler_Destroy(SUNErrHandler* eh) { - free(eh); + if (!eh || !(*eh)) { return; } + free(*eh); + *eh = NULL; } -const char* SUNGetErrMsg(SUNErrCode code, SUNContext sunctx) +const char* SUNGetErrMsg(SUNErrCode code) { #define SUN_EXPAND_TO_CASES(name, description) \ case name: return description; break; @@ -65,7 +67,7 @@ void SUNLogErrHandlerFn(int line, const char* func, const char* file, SUNContext sunctx) { char* file_and_line = combineFileAndLine(line, file); - if (msg == NULL) { msg = SUNGetErrMsg(err_code, sunctx); } + if (msg == NULL) { msg = SUNGetErrMsg(err_code); } SUNLogger_QueueMsg(sunctx->logger, SUN_LOGLEVEL_ERROR, file_and_line, func, msg); free(file_and_line); diff --git a/src/sundials/sundials_hashmap.h b/src/sundials/sundials_hashmap.h index 2bbbfa7089..a5bdfeee98 100644 --- a/src/sundials/sundials_hashmap.h +++ b/src/sundials/sundials_hashmap.h @@ -79,7 +79,7 @@ static SUNErrCode SUNHashMap_New(int max_size, SUNHashMap* map) if (max_size <= 0) { - return (-1); + return SUN_ERR_ARG_OUTOFRANGE; } *map = NULL; diff --git a/src/sundials/sundials_logger.c b/src/sundials/sundials_logger.c index b3cacf7dee..9ee3c80eff 100644 --- a/src/sundials/sundials_logger.c +++ b/src/sundials/sundials_logger.c @@ -237,7 +237,9 @@ SUNErrCode SUNLogger_CreateFromEnv(SUNComm comm, SUNLogger* logger_out) SUNErrCode SUNLogger_SetErrorFilename(SUNLogger logger, const char* error_filename) { - if (!sunLoggerIsOutputRank(logger, NULL)) { return SUN_SUCCESS; } + if (!logger) { return SUN_ERR_ARG_CORRUPT; } + + if (!sunLoggerIsOutputRank(logger, NULL)) { return SUN_SUCCESS; } if (error_filename && strcmp(error_filename, "")) { diff --git a/src/sundials/sundials_mpi_errors.c b/src/sundials/sundials_mpi_errors.c index 638599eec7..3a4c38e1a6 100644 --- a/src/sundials/sundials_mpi_errors.c +++ b/src/sundials/sundials_mpi_errors.c @@ -1,6 +1,6 @@ /* ----------------------------------------------------------------- * SUNDIALS Copyright Start - * Copyright (c) 2002-2022, Lawrence Livermore National Security + * Copyright (c) 2002-2023, Lawrence Livermore National Security * and Southern Methodist University. * All rights reserved. * diff --git a/src/sundials/sundials_nonlinearsolver.c b/src/sundials/sundials_nonlinearsolver.c index 26b7d80b06..c40d8b27b0 100644 --- a/src/sundials/sundials_nonlinearsolver.c +++ b/src/sundials/sundials_nonlinearsolver.c @@ -21,6 +21,7 @@ #include #include #include +#include "sundials/sundials_errors.h" #include "sundials_logger_impl.h" #if defined(SUNDIALS_BUILD_WITH_PROFILING) @@ -108,7 +109,7 @@ SUNErrCode SUNNonlinSolInitialize(SUNNonlinearSolver NLS) if (NLS->ops->initialize) ier = NLS->ops->initialize(NLS); else - ier = SUN_NLS_SUCCESS; + ier = SUN_SUCCESS; SUNDIALS_MARK_FUNCTION_END(getSUNProfiler(NLS)); return(ier); } diff --git a/src/sundials/sundials_nvector_impl.h b/src/sundials/sundials_nvector_impl.h index dde58e4755..aefa1c8cc1 100644 --- a/src/sundials/sundials_nvector_impl.h +++ b/src/sundials/sundials_nvector_impl.h @@ -1,6 +1,6 @@ /* ----------------------------------------------------------------- * SUNDIALS Copyright Start - * Copyright (c) 2002-2022, Lawrence Livermore National Security + * Copyright (c) 2002-2023, Lawrence Livermore National Security * and Southern Methodist University. * All rights reserved. * diff --git a/src/sundials/sundials_profiler.c b/src/sundials/sundials_profiler.c index 792c525a93..5a68f9211f 100644 --- a/src/sundials/sundials_profiler.c +++ b/src/sundials/sundials_profiler.c @@ -222,6 +222,8 @@ SUNErrCode SUNProfiler_Create(SUNComm comm, const char* title, SUNProfiler* p) SUNErrCode SUNProfiler_Free(SUNProfiler* p) { + if (!p || !(*p)) { return SUN_SUCCESS; } + SUNDIALS_MARK_END(*p, SUNDIALS_ROOT_TIMER); if (*p) diff --git a/src/sundials/sundials_version.c b/src/sundials/sundials_version.c index d2dba489e4..dc6dd74064 100644 --- a/src/sundials/sundials_version.c +++ b/src/sundials/sundials_version.c @@ -27,7 +27,7 @@ /* fill string with SUNDIALS version information */ SUNErrCode SUNDIALSGetVersion(char *version, int len) { - if (version == NULL) return SUN_ERR_CORRUPT; + if (version == NULL) return SUN_ERR_ARG_CORRUPT; if (strlen(SUNDIALS_VERSION) >= (size_t)len) return SUN_ERR_ARG_OUTOFRANGE; strncpy(version, SUNDIALS_VERSION, (size_t)len); @@ -38,12 +38,12 @@ SUNErrCode SUNDIALSGetVersion(char *version, int len) /* fill integers with SUNDIALS major, minor, and patch release numbers and fill a string with the release label */ SUNErrCode SUNDIALSGetVersionNumber(int *major, int *minor, int *patch, - char *label, int len) + char *label, int len) { if (major == NULL || minor == NULL || patch == NULL || - label == NULL) return SUN_ERR_CORRUPT; + label == NULL) return SUN_ERR_ARG_CORRUPT; if (strlen(SUNDIALS_VERSION_LABEL) >= (size_t)len) return SUN_ERR_ARG_OUTOFRANGE; *major = SUNDIALS_VERSION_MAJOR; diff --git a/swig/sundials/fsundials_errors_mod.i b/swig/sundials/fsundials_errors_mod.i index 293eb2d115..4ad52ce1f3 100644 --- a/swig/sundials/fsundials_errors_mod.i +++ b/swig/sundials/fsundials_errors_mod.i @@ -2,7 +2,7 @@ // Programmer: Cody J. Balos @ LLNL // --------------------------------------------------------------- // SUNDIALS Copyright Start -// Copyright (c) 2002-2022, Lawrence Livermore National Security +// Copyright (c) 2002-2023, Lawrence Livermore National Security // and Southern Methodist University. // All rights reserved. // diff --git a/test/unit_tests/sundials/test_sundials_errors.cpp b/test/unit_tests/sundials/test_sundials_errors.cpp index bb68dcb7f7..aed7964cda 100644 --- a/test/unit_tests/sundials/test_sundials_errors.cpp +++ b/test/unit_tests/sundials/test_sundials_errors.cpp @@ -1,6 +1,6 @@ /* ----------------------------------------------------------------- * SUNDIALS Copyright Start - * Copyright (c) 2002-2022, Lawrence Livermore National Security + * Copyright (c) 2002-2023, Lawrence Livermore National Security * and Southern Methodist University. * All rights reserved. * @@ -93,7 +93,7 @@ TEST_F(SUNContextErrFunctionTests, SUNContextPushErrHandlerWorks) SUNContext_PushErrHandler(sunctx, firstHandler, static_cast(&order)); SUNContext_PushErrHandler(sunctx, secondHandler, static_cast(&order)); SUNContext_PushErrHandler(sunctx, thirdHandler, static_cast(&order)); - SUNHandleErr(__LINE__, __func__, __FILE__, -1, sunctx); + SUNHandleErrWithMsg(__LINE__, __func__, __FILE__, NULL, -1, sunctx); EXPECT_EQ(order.size(), 3); EXPECT_EQ(order.at(0), 2); EXPECT_EQ(order.at(1), 1); @@ -108,7 +108,7 @@ TEST_F(SUNContextErrFunctionTests, SUNContextPopErrHandlerWorks) SUNContext_PushErrHandler(sunctx, secondHandler, static_cast(&order)); SUNContext_PushErrHandler(sunctx, thirdHandler, static_cast(&order)); SUNContext_PopErrHandler(sunctx); - SUNHandleErr(__LINE__, __func__, __FILE__, -1, sunctx); + SUNHandleErrWithMsg(__LINE__, __func__, __FILE__, NULL, -1, sunctx); EXPECT_EQ(order.size(), 2); EXPECT_EQ(order.at(0), 1); EXPECT_EQ(order.at(1), 0);