From 4c4fd86fd8e4f9074f3e8f690fe4f786ca196eaf Mon Sep 17 00:00:00 2001 From: kanschat Date: Tue, 23 Mar 2010 03:33:58 +0000 Subject: [PATCH] documentation git-svn-id: https://svn.dealii.org/trunk@20883 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/deal.II/include/numerics/newton.h | 33 ++++++++++++++++++--- deal.II/deal.II/include/numerics/operator.h | 14 +++++++++ deal.II/lac/include/lac/constraint_matrix.h | 2 +- 3 files changed, 44 insertions(+), 5 deletions(-) diff --git a/deal.II/deal.II/include/numerics/newton.h b/deal.II/deal.II/include/numerics/newton.h index 3074f2efe0..5192221d94 100644 --- a/deal.II/deal.II/include/numerics/newton.h +++ b/deal.II/deal.II/include/numerics/newton.h @@ -41,6 +41,23 @@ namespace Algorithms * #inverse_derivative. It is up to this object to implement * reassembling accordingly. * + *

Contents of the NamedData objects

+ * + * The only value used by the Newton method is the first vector in the + * parameter out of operator()(). It serves as the start + * vector of Newton's method and in the end contains the solution. All + * other vectors of out are ignored by Newton's method and + * its inner Operator objects. All vectors of in are forwarded to + * the inner Operator objects, with additional information added as follows. + * + * When calling (*#residual)(), the NamedData in given to the + * Newton iteration is prepended by a vector "Newton iterate", + * the current value of the Newton iterate, which can be used to + * evaluate the residual at this point. + * + * For the call to (*#inverse_derivative), the vector "Newton + * residual" is inserted before "Newton iterate". + * * @author Guido Kanschat, 2006, 2010 */ template @@ -49,14 +66,14 @@ namespace Algorithms public: /** * Constructor, receiving the - * application computing the + * applications computing the * residual and solving the - * linear problem. + * linear problem, respectively. */ Newton (Operator& residual, Operator& inverse_derivative); /** - * Declare the parameter + * Declare the parameters * applicable to Newton's method. */ void declare_parameters (ParameterHandler& param); @@ -67,7 +84,15 @@ namespace Algorithms void initialize (ParameterHandler& param); /** - * The actual Newton iteration. + * The actual Newton + * iteration. The initial value + * is in out(0), which + * also contains the result + * after convergence. Values in + * in are not used by + * Newton, but will be handed + * down to the objects + * #residual and #inverse_derivative. */ virtual void operator() (NamedData& out, const NamedData& in); diff --git a/deal.II/deal.II/include/numerics/operator.h b/deal.II/deal.II/include/numerics/operator.h index 0559613c3e..fd6d6ae980 100644 --- a/deal.II/deal.II/include/numerics/operator.h +++ b/deal.II/deal.II/include/numerics/operator.h @@ -33,6 +33,20 @@ namespace Algorithms * method, which would then trigger reassembling of a matrix or * similar things. * + *

Usage for nested iterations

+ * + * This is probably the most prominent use for Operator, where an + * outer iterative method calls an inner solver and so on. Typically, + * the innermost method in such a nested system will have to compute a + * residual using values from all outer iterations. Since the depth + * and order of such a nesting is hardly predictable when designing a + * general tool, we use NamedData to access these vectors. Typically, + * the first vector in out contains the start vector when + * operator()() is called, and the solution when the function + * returns. The object in is providing additional information + * and forwarded to the inner Operator objects of the nested + * iteration. + * * @author Guido Kanschat, 2010 */ template diff --git a/deal.II/lac/include/lac/constraint_matrix.h b/deal.II/lac/include/lac/constraint_matrix.h index b31c279d63..63d75bff6a 100644 --- a/deal.II/lac/include/lac/constraint_matrix.h +++ b/deal.II/lac/include/lac/constraint_matrix.h @@ -1843,7 +1843,7 @@ class ConstraintMatrix : public Subscriptor * function. * * Creates a list of affected - * rows for sistribution. + * rows for distribution. */ void make_sorted_row_list (const std::vector &local_dof_indices, -- 2.39.5