From: Guido Kanschat <dr.guido.kanschat@gmail.com>
Date: Tue, 23 Mar 2010 03:33:58 +0000 (+0000)
Subject: documentation
X-Git-Tag: v8.0.0~6277
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=625a5f7dc7f91531b8501de28248e009e81e089b;p=dealii.git

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 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.
  *
+ * <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 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.
  *
+ * <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 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<unsigned int> &local_dof_indices,