documentation

git-svn-id: https://svn.dealii.org/trunk@20883 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/deal.II/include/numerics/newton.h b/deal.II/deal.II/include/numerics/newton.h
index 3074f2efe0683bb865994d73b47e8b6f3857a052..5192221d94505856cd9016f6af18d60130f2b686 100644 (file)
--- 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.
  *
+ * <h3>Contents of the NamedData objects</h3>
+ *
+ * The only value used by the Newton method is the first vector in the
+ * parameter <tt>out</tt> of operator()(). It serves as the start
+ * vector of Newton's method and in the end contains the solution. All
+ * other vectors of <tt>out</tt> are ignored by Newton's method and
+ * its inner Operator objects. All vectors of <tt>in</tt> are forwarded to
+ * the inner Operator objects, with additional information added as follows.
+ *
+ * When calling (*#residual)(), the NamedData <tt>in</tt> given to the
+ * Newton iteration is prepended by a vector <tt>"Newton iterate"</tt>,
+ * 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 <tt>"Newton
+ * residual"</tt> is inserted before <tt>"Newton iterate"<tt>.
+ *
  * @author Guido Kanschat, 2006, 2010
  */
   template <class VECTOR>
@@ -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<VECTOR>& residual, Operator<VECTOR>& 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 <tt>out(0)</tt>, which
+                                       * also contains the result
+                                       * after convergence. Values in
+                                       * <tt>in</tt> are not used by
+                                       * Newton, but will be handed
+                                       * down to the objects
+                                       * #residual and #inverse_derivative.
                                        */
       virtual void operator() (NamedData<VECTOR*>& out, const NamedData<VECTOR*>& in);
       

diff --git a/deal.II/deal.II/include/numerics/operator.h b/deal.II/deal.II/include/numerics/operator.h
index 0559613c3e82ab315a25d96953172314bcfc8d0e..fd6d6ae98034c25411f8d3d9b8021c5a874c0721 100644 (file)
--- 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.
  *
+ * <h3>Usage for nested iterations</h3>
+ *
+ * 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 <tt>out</tt> contains the start vector when
+ * operator()() is called, and the solution when the function
+ * returns. The object <tt>in</tt> is providing additional information
+ * and forwarded to the inner Operator objects of the nested
+ * iteration.
+ *
  * @author Guido Kanschat, 2010
  */
   template <class VECTOR>

diff --git a/deal.II/lac/include/lac/constraint_matrix.h b/deal.II/lac/include/lac/constraint_matrix.h
index b31c279d63b18dd934a8e688d3789a35aacf49df..63d75bff6a7721522b67af3627a54c6b4c45a301 100644 (file)
--- 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<unsigned int> &local_dof_indices,