From f6ebc0b5665031dae63370a9be557d34cc1f4c81 Mon Sep 17 00:00:00 2001 From: Stefano Zampini Date: Wed, 19 Jul 2023 02:08:00 +0200 Subject: [PATCH] PETScWrappers::NonlinearSolver: Improve documentation --- include/deal.II/lac/petsc_snes.h | 40 +++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/include/deal.II/lac/petsc_snes.h b/include/deal.II/lac/petsc_snes.h index 82513b2691..7412b0ee02 100644 --- a/include/deal.II/lac/petsc_snes.h +++ b/include/deal.II/lac/petsc_snes.h @@ -201,17 +201,29 @@ namespace PETScWrappers * For details, consult the [PETSc * manual](https://petsc.org/release/manual/snes/#sec-nlmatrixfree). * - * In alternative, users can also provide the implementation of the - * Jacobian. This can be accomplished in two ways: + * Users can also provide the implementations of the Jacobian. This can be + * accomplished in two ways: * - PETSc style using NonlinearSolver::jacobian * - deal.II style using NonlinearSolver::setup_jacobian and - * NonlinearSolver::solve_with_jacobian. + * NonlinearSolver::solve_with_jacobian. + * The preconditioning matrix can be specified using + * NonlinearSolver::set_matrix. In case both approaches are implemented, the + * deal.II style will be used. * - * In case both approaches are implemented, the deal.II style - * will be used. + * NonlinearSolver::set_matrices must be used in case the user wants to + * provide the iteration matrix of the tangent system in the deal.II style + * approach, thus replacing the matrix-free linearization. * - * The second approach is more in style with the deal.II philosophy - * and it also allows command line customization, like for example, + * The correctness of the constructed Jacobians passed using + * NonlinearSolver::set_matrix can be checked using + * @code + * ./myApp -snes_test_jacobian + * @endcode + * See NonlinearSolver::set_matrix and NonlinearSolver::set_matrices for + * additional details. + * + * The deal.II style approach still allows command line customization, like + * for example, * @code * ./myApp -snes_type newtontr -ksp_type cg * @endcode @@ -219,15 +231,14 @@ namespace PETScWrappers * a trust region solver and iterate on the matrix-free tangent system with * CG, still using NonlinearSolver::solve_with_jacobian as a preconditioner. * - * The first approach has instead the advantage that only the matrix assembly - * procedure has to be provided, thus allowing quicker implementations and - * faster turnaround for experimenting with linear solver preconditioning - * configurations via command line customizations, like for example, + * The PETSc style approach has instead the advantage that only the matrix + * assembly procedure has to be implemented, thus allowing quicker + * implementations and faster turnaround for experimenting with linear solver + * preconditioning configurations via command line customizations, like for + * example, * @code * ./myApp -ksp_type cg -pc_type gamg * @endcode - * See NonlinearSolver::set_matrix and NonlinearSolver::set_matrices for - * additional details. * * In case the nonlinear equations are derived from energy minimization * arguments, it may be beneficial to perform linesearch or test trust-region @@ -323,7 +334,8 @@ namespace PETScWrappers /** * Set both the linear system matrix and the preconditioning matrix - * that PETSc will use. + * that PETSc will use (can be the same matrix). In this case, the + * Jacobian-Free-Newton-Krylov approach will not be used. */ void set_matrices(AMatrixType &A, PMatrixType &P); -- 2.39.5