From 6c6adece1df122d76284ddaef58047274a2a45f0 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Thu, 4 May 2023 10:08:31 -0600 Subject: [PATCH] Document that the callbacks can throw exceptions. --- include/deal.II/sundials/kinsol.h | 76 +++++++++++++++++++++---------- 1 file changed, 52 insertions(+), 24 deletions(-) diff --git a/include/deal.II/sundials/kinsol.h b/include/deal.II/sundials/kinsol.h index df4177b520..024ba92e22 100644 --- a/include/deal.II/sundials/kinsol.h +++ b/include/deal.II/sundials/kinsol.h @@ -415,6 +415,13 @@ namespace SUNDIALS * block vectors are used), and MPI communicator (if the vector is * distributed across multiple processors using MPI), along with any * other properties necessary. + * + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. In particular, KINSOL can deal + * with "recoverable" errors in some circumstances, so callbacks + * can throw exceptions of type RecoverableUserCallbackError. */ std::function reinit_vector; @@ -424,12 +431,12 @@ namespace SUNDIALS * SolutionStrategy::newton, SolutionStrategy::linesearch, or * SolutionStrategy::picard strategies were selected. * - * This function should return: - * - 0: Success - * - >0: Recoverable error (KINSOL will try to change its internal - * parameters and attempt a new solution step) - * - <0: Unrecoverable error the computation will be aborted and an - * assertion will be thrown. + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. In particular, KINSOL can deal + * with "recoverable" errors in some circumstances, so callbacks + * can throw exceptions of type RecoverableUserCallbackError. */ std::function residual; @@ -439,12 +446,12 @@ namespace SUNDIALS * iteration. This function is only used if the * SolutionStrategy::fixed_point strategy is selected. * - * This function should return: - * - 0: Success - * - >0: Recoverable error (KINSOL will try to change its internal - * parameters and attempt a new solution step) - * - <0: Unrecoverable error; the computation will be aborted and an - * assertion will be thrown. + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. In particular, KINSOL can deal + * with "recoverable" errors in some circumstances, so callbacks + * can throw exceptions of type RecoverableUserCallbackError. */ std::function iteration_function; @@ -487,12 +494,12 @@ namespace SUNDIALS * @param current_u Current value of $u$ * @param current_f Current value of $F(u)$ or $G(u)$ * - * This function should return: - * - 0: Success - * - >0: Recoverable error (KINSOL will try to change its internal - * parameters and attempt a new solution step) - * - <0: Unrecoverable error the computation will be aborted and an - * assertion will be thrown. + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. In particular, KINSOL can deal + * with "recoverable" errors in some circumstances, so callbacks + * can throw exceptions of type RecoverableUserCallbackError. */ std::function @@ -555,6 +562,13 @@ namespace SUNDIALS * to a *previous* iterate), then you will also have to set the * AdditionalData::maximum_newton_step variable to one, indicating * that the Jacobian should be re-computed in every iteration. + * + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. In particular, KINSOL can deal + * with "recoverable" errors in some circumstances, so callbacks + * can throw exceptions of type RecoverableUserCallbackError. */ DEAL_II_DEPRECATED std::function0: Recoverable error (KINSOL will try to change its internal - * parameters and attempt a new solution step) - * - <0: Unrecoverable error the computation will be aborted and an - * assertion will be thrown. + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. In particular, KINSOL can deal + * with "recoverable" errors in some circumstances, so callbacks + * can throw exceptions of type RecoverableUserCallbackError. */ std::function< void(const VectorType &rhs, VectorType &dst, const double tolerance)> @@ -643,6 +657,13 @@ namespace SUNDIALS * If no function is provided to a KINSOL object, then this is interpreted * as implicitly saying that all of these scaling factors should be * considered as one. + * + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. In particular, KINSOL can deal + * with "recoverable" errors in some circumstances, so callbacks + * can throw exceptions of type RecoverableUserCallbackError. */ std::function get_solution_scaling; @@ -659,6 +680,13 @@ namespace SUNDIALS * than the components of $U$, when computing norms. As above, if no * function is provided, then this is equivalent to using a scaling vector * whose components are all equal to one. + * + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. In particular, KINSOL can deal + * with "recoverable" errors in some circumstances, so callbacks + * can throw exceptions of type RecoverableUserCallbackError. */ std::function get_function_scaling; -- 2.39.5