From 6b55878193b9e9a4fe13c60710908579762debc8 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 3 May 2021 17:51:49 -0600 Subject: [PATCH] Leave references to step-77. --- examples/step-15/doc/intro.dox | 8 +++++++- examples/step-15/doc/results.dox | 7 +++++-- examples/step-15/step-15.cc | 6 ++++-- include/deal.II/base/timer.h | 8 +++++++- include/deal.II/dofs/dof_tools.h | 2 ++ include/deal.II/sundials/kinsol.h | 5 +++-- 6 files changed, 28 insertions(+), 8 deletions(-) diff --git a/examples/step-15/doc/intro.dox b/examples/step-15/doc/intro.dox index 7794162e0c..784f222610 100644 --- a/examples/step-15/doc/intro.dox +++ b/examples/step-15/doc/intro.dox @@ -241,7 +241,8 @@ full step lengths we forego the rapid, quadratic convergence that makes Newton's method so appealing. Obviously, this is a point one eventually has to address if the program was made into one that is meant to solve more realistic problems. We will comment on this issue -some more in the results section. +some more in the results section, and use an +even better approach in step-77.

Summary of the algorithm and testcase

@@ -270,6 +271,11 @@ follows: $\alpha^n=0.1$. To make things easier to extend later on, this happens in a function of its own, namely in MinimalSurfaceProblem::determine_step_length. + (The strategy of always choosing $\alpha^n=0.1$ is of course not + optimal -- we should choose a step length that works for a given + search direction -- but it requires a bit of work to do that. In the + end, we leave these sorts of things to external packages: step-77 + does that.)
  • diff --git a/examples/step-15/doc/results.dox b/examples/step-15/doc/results.dox index f939657c18..c643e2ed1e 100644 --- a/examples/step-15/doc/results.dox +++ b/examples/step-15/doc/results.dox @@ -174,12 +174,15 @@ A separate point, very much worthwhile making, however, is that in practice the implementation of efficient nonlinear solvers is about as complicated as the implementation of efficient finite element methods. One should not attempt to reinvent the wheel by implementing all of the necessary steps -oneself. Rather, just like building finite element solvers on libraries +oneself. Substantial pieces of the puzzle are already available in +the LineMinimization::line_search() function and could be used to this end. +But, instead, just like building finite element solvers on libraries such as deal.II, one should be building nonlinear solvers on libraries such as [SUNDIALS](https://computing.llnl.gov/projects/sundials). In fact, deal.II has interfaces to SUNDIALS and in particular to its nonlinear solver sub-package KINSOL through the SUNDIALS::KINSOL class. It would not be -very difficult to base the current problem on that interface. +very difficult to base the current problem on that interface -- +indeed, that is what step-77 does. diff --git a/examples/step-15/step-15.cc b/examples/step-15/step-15.cc index 6959010bc2..29cd9328da 100644 --- a/examples/step-15/step-15.cc +++ b/examples/step-15/step-15.cc @@ -91,7 +91,9 @@ namespace Step15 // determine_step_length() computes the step length $\alpha^n$ // in each Newton iteration. As discussed in the introduction, we here use a // fixed step length and leave implementing a better strategy as an - // exercise. + // exercise. (step-77 does this differently: It simply uses an + // external package for the whole solution process, and a good + // line search strategy is part of what that package provides.) template class MinimalSurfaceProblem @@ -581,7 +583,7 @@ namespace Step15 // choice: ideally, what one wants is that the step size goes to one as we // get closer to the solution, so that we get to enjoy the rapid quadratic // convergence of Newton's method. We will discuss better strategies below - // in the results section. + // in the results section, and step-77 also covers this aspect. template double MinimalSurfaceProblem::determine_step_length() const { diff --git a/include/deal.II/base/timer.h b/include/deal.II/base/timer.h index a59712b220..8f28e4dc5f 100644 --- a/include/deal.II/base/timer.h +++ b/include/deal.II/base/timer.h @@ -361,7 +361,13 @@ private: * entered several times. By changing the options in OutputFrequency and * OutputType, the user can choose whether output should be generated every * time a section is joined or just in the end of the program. Moreover, it is - * possible to show CPU times, wall times or both. + * possible to show CPU times, wall times, or both. + * + * The class is used in a substantial number of tutorial programs that collect + * timing data. step-77 is an example of a relatively simple sequential program + * that uses it. step-40 and several others mentioned below use it for parallel + * computations. + * * *

    Usage

    * diff --git a/include/deal.II/dofs/dof_tools.h b/include/deal.II/dofs/dof_tools.h index 2fd8331919..0f7b9b1452 100644 --- a/include/deal.II/dofs/dof_tools.h +++ b/include/deal.II/dofs/dof_tools.h @@ -1473,6 +1473,8 @@ namespace DoFTools * located that shall be extracted. If it is an empty list (the default), then * all boundary indicators are accepted. * + * This function is used in step-11 and step-15, for example. + * * @note If the DoFHandler object is defined on a * parallel Triangulation object, then the computed index set * will contain only those degrees of freedom on the boundary that belong to diff --git a/include/deal.II/sundials/kinsol.h b/include/deal.II/sundials/kinsol.h index da18ba8a0d..83b73e10e3 100644 --- a/include/deal.II/sundials/kinsol.h +++ b/include/deal.II/sundials/kinsol.h @@ -51,7 +51,7 @@ DEAL_II_NAMESPACE_OPEN namespace SUNDIALS { /** - * Interface to SUNDIALS non linear solver (KINSOL). + * Interface to SUNDIALS' nonlinear solver (KINSOL). * * KINSOL is a solver for nonlinear algebraic systems in residual form $F(u) * = 0$ or fixed point form $G(u) = u$, where $u$ is a vector which we will @@ -61,7 +61,8 @@ namespace SUNDIALS * $F,G:{\mathbb C}^N \to{\mathbb C}^N$. It includes a Newton-Krylov solver * as well as Picard and fixed point solvers, both of which can be * accelerated with Anderson acceleration. KINSOL is based on the previous - * Fortran package NKSOL of Brown and Saad. + * Fortran package NKSOL of Brown and Saad. An example of using KINSOL + * can be found in the step-77 tutorial program. * * KINSOL's Newton solver employs the inexact Newton method. As this solver * is intended mainly for large systems, the user is required to provide -- 2.39.5